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 messages, see g_critical().
1240 * This level is also used for messages produced by g_return_if_fail()
1241 * and g_return_val_if_fail().
1242 * @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning()
1243 * @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message()
1244 * @G_LOG_LEVEL_INFO: log level for informational messages, see g_info()
1245 * @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug()
1246 * @G_LOG_LEVEL_MASK: a mask including all log levels
1248 * Flags specifying the level of log messages.
1250 * It is possible to change how GLib treats messages of the various
1251 * levels using g_log_set_handler() and g_log_set_fatal_mask().
1258 * The #GMappedFile represents a file mapping created with
1259 * g_mapped_file_new(). It has only private members and should
1260 * not be accessed directly.
1265 * GMarkupCollectType:
1266 * @G_MARKUP_COLLECT_INVALID: used to terminate the list of attributes
1268 * @G_MARKUP_COLLECT_STRING: collect the string pointer directly from
1269 * the attribute_values[] array. Expects a parameter of type (const
1270 * char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the
1271 * attribute isn't present then the pointer will be set to %NULL
1272 * @G_MARKUP_COLLECT_STRDUP: as with %G_MARKUP_COLLECT_STRING, but
1273 * expects a parameter of type (char **) and g_strdup()s the
1274 * returned pointer. The pointer must be freed with g_free()
1275 * @G_MARKUP_COLLECT_BOOLEAN: expects a parameter of type (gboolean *)
1276 * and parses the attribute value as a boolean. Sets %FALSE if the
1277 * attribute isn't present. Valid boolean values consist of
1278 * (case-insensitive) "false", "f", "no", "n", "0" and "true", "t",
1280 * @G_MARKUP_COLLECT_TRISTATE: as with %G_MARKUP_COLLECT_BOOLEAN, but
1281 * in the case of a missing attribute a value is set that compares
1282 * equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is
1284 * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields.
1285 * If present, allows the attribute not to appear. A default value
1286 * is set depending on what value type is used
1288 * A mixed enumerated type and flags field. You must specify one type
1289 * (string, strdup, boolean, tristate). Additionally, you may optionally
1290 * bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL.
1292 * It is likely that this enum will be extended in the future to
1293 * support other types.
1300 * The #GMutex struct is an opaque data structure to represent a mutex
1301 * (mutual exclusion). It can be used to protect data against shared
1304 * Take for example the following function:
1305 * |[<!-- language="C" -->
1307 * give_me_next_number (void)
1309 * static int current_number = 0;
1311 * // now do a very complicated calculation to calculate the new
1312 * // number, this might for example be a random number generator
1313 * current_number = calc_next_number (current_number);
1315 * return current_number;
1318 * It is easy to see that this won't work in a multi-threaded
1319 * application. There current_number must be protected against shared
1320 * access. A #GMutex can be used as a solution to this problem:
1321 * |[<!-- language="C" -->
1323 * give_me_next_number (void)
1325 * static GMutex mutex;
1326 * static int current_number = 0;
1329 * g_mutex_lock (&mutex);
1330 * ret_val = current_number = calc_next_number (current_number);
1331 * g_mutex_unlock (&mutex);
1336 * Notice that the #GMutex is not initialised to any particular value.
1337 * Its placement in static storage ensures that it will be initialised
1338 * to all-zeros, which is appropriate.
1340 * If a #GMutex is placed in other contexts (eg: embedded in a struct)
1341 * then it must be explicitly initialised using g_mutex_init().
1343 * A #GMutex should only be accessed via g_mutex_ functions.
1349 * @data: contains the actual data of the node.
1350 * @next: points to the node's next sibling (a sibling is another
1351 * #GNode with the same parent).
1352 * @prev: points to the node's previous sibling.
1353 * @parent: points to the parent of the #GNode, or is %NULL if the
1354 * #GNode is the root of the tree.
1355 * @children: points to the first child of the #GNode. The other
1356 * children are accessed by using the @next pointer of each
1359 * The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees].
1366 * @data: user data passed to g_node_children_foreach().
1368 * Specifies the type of function passed to g_node_children_foreach().
1369 * The function is called with each child node, together with the user
1370 * data passed to g_node_children_foreach().
1375 * GNodeTraverseFunc:
1377 * @data: user data passed to g_node_traverse().
1379 * Specifies the type of function passed to g_node_traverse(). The
1380 * function is called with each of the nodes visited, together with the
1381 * user data passed to g_node_traverse(). If the function returns
1382 * %TRUE, then the traversal is stopped.
1384 * Returns: %TRUE to stop the traversal.
1390 * @status: the status of the #GOnce
1391 * @retval: the value returned by the call to the function, if @status
1392 * is %G_ONCE_STATUS_READY
1394 * A #GOnce struct controls a one-time initialization function. Any
1395 * one-time initialization function must have its own unique #GOnce
1404 * @G_ONCE_STATUS_NOTCALLED: the function has not been called yet.
1405 * @G_ONCE_STATUS_PROGRESS: the function call is currently in progress.
1406 * @G_ONCE_STATUS_READY: the function has been called.
1408 * The possible statuses of a one-time initialization function
1409 * controlled by a #GOnce struct.
1417 * @p: pointer containing an integer
1419 * Extracts an integer from a pointer. The integer must have
1420 * been stored in the pointer with GINT_TO_POINTER().
1422 * Remember, you may not store pointers in integers. This is not portable
1423 * in any way, shape or form. These macros only allow storing integers in
1424 * pointers, and only preserve 32 bits of the integer; values outside the
1425 * range of a 32-bit integer will be mangled.
1431 * @p: pointer to extract a #gsize from
1433 * Extracts a #gsize from a pointer. The #gsize must have
1434 * been stored in the pointer with GSIZE_TO_POINTER().
1440 * @p: pointer to extract an unsigned integer from
1442 * Extracts an unsigned integer from a pointer. The integer must have
1443 * been stored in the pointer with GUINT_TO_POINTER().
1450 * A GPatternSpec struct is the 'compiled' form of a pattern. This
1451 * structure is opaque and its fields cannot be accessed directly.
1458 * The #GPrivate struct is an opaque data structure to represent a
1459 * thread-local data key. It is approximately equivalent to the
1460 * pthread_setspecific()/pthread_getspecific() APIs on POSIX and to
1461 * TlsSetValue()/TlsGetValue() on Windows.
1463 * If you don't already know why you might want this functionality,
1464 * then you probably don't need it.
1466 * #GPrivate is a very limited resource (as far as 128 per program,
1467 * shared between all libraries). It is also not possible to destroy a
1468 * #GPrivate after it has been used. As such, it is only ever acceptable
1469 * to use #GPrivate in static scope, and even then sparingly so.
1471 * See G_PRIVATE_INIT() for a couple of examples.
1473 * The #GPrivate structure should be considered opaque. It should only
1474 * be accessed via the g_private_ functions.
1480 * @pdata: points to the array of pointers, which may be moved when the
1482 * @len: number of pointers in the array
1484 * Contains the public fields of a pointer array.
1491 * A GQuark is a non-zero integer which uniquely identifies a
1492 * particular string. A GQuark value of zero is associated to %NULL.
1499 * The GRWLock struct is an opaque data structure to represent a
1500 * reader-writer lock. It is similar to a #GMutex in that it allows
1501 * multiple threads to coordinate access to a shared resource.
1503 * The difference to a mutex is that a reader-writer lock discriminates
1504 * between read-only ('reader') and full ('writer') access. While only
1505 * one thread at a time is allowed write access (by holding the 'writer'
1506 * lock via g_rw_lock_writer_lock()), multiple threads can gain
1507 * simultaneous read-only access (by holding the 'reader' lock via
1508 * g_rw_lock_reader_lock()).
1510 * Here is an example for an array with access functions:
1511 * |[<!-- language="C" -->
1516 * my_array_get (guint index)
1518 * gpointer retval = NULL;
1523 * g_rw_lock_reader_lock (&lock);
1524 * if (index < array->len)
1525 * retval = g_ptr_array_index (array, index);
1526 * g_rw_lock_reader_unlock (&lock);
1532 * my_array_set (guint index, gpointer data)
1534 * g_rw_lock_writer_lock (&lock);
1537 * array = g_ptr_array_new ();
1539 * if (index >= array->len)
1540 * g_ptr_array_set_size (array, index+1);
1541 * g_ptr_array_index (array, index) = data;
1543 * g_rw_lock_writer_unlock (&lock);
1546 * This example shows an array which can be accessed by many readers
1547 * (the my_array_get() function) simultaneously, whereas the writers
1548 * (the my_array_set() function) will only be allowed one at a time
1549 * and only if no readers currently access the array. This is because
1550 * of the potentially dangerous resizing of the array. Using these
1551 * functions is fully multi-thread safe now.
1553 * If a #GRWLock is allocated in static storage then it can be used
1554 * without initialisation. Otherwise, you should call
1555 * g_rw_lock_init() on it and g_rw_lock_clear() when done.
1557 * A GRWLock should only be accessed with the g_rw_lock_ functions.
1566 * The GRand struct is an opaque data structure. It should only be
1567 * accessed through the g_rand_* functions.
1574 * The GRecMutex struct is an opaque data structure to represent a
1575 * recursive mutex. It is similar to a #GMutex with the difference
1576 * that it is possible to lock a GRecMutex multiple times in the same
1577 * thread without deadlock. When doing so, care has to be taken to
1578 * unlock the recursive mutex as often as it has been locked.
1580 * If a #GRecMutex is allocated in static storage then it can be used
1581 * without initialisation. Otherwise, you should call
1582 * g_rec_mutex_init() on it and g_rec_mutex_clear() when done.
1584 * A GRecMutex should only be accessed with the
1585 * g_rec_mutex_ functions.
1593 * @val: a #gsize value in big-endian byte order
1595 * Converts a #gsize value from big-endian to the host byte order.
1597 * Returns: @val converted to host byte order
1603 * @val: a #gsize value in little-endian byte order
1605 * Converts a #gsize value from little-endian to host byte order.
1607 * Returns: @val converted to host byte order
1613 * @val: a #gsize value in host byte order
1615 * Converts a #gsize value from host byte order to big-endian.
1617 * Returns: @val converted to big-endian byte order
1623 * @val: a #gsize value in host byte order
1625 * Converts a #gsize value from host byte order to little-endian.
1627 * Returns: @val converted to little-endian
1633 * @s: #gsize to stuff into the pointer
1635 * Stuffs a #gsize into a pointer type.
1641 * @data: holds the element's data, which can be a pointer to any kind
1642 * of data, or any integer value using the
1643 * [Type Conversion Macros][glib-Type-Conversion-Macros]
1644 * @next: contains the link to the next element in the list.
1646 * The #GSList struct is used for each element in the singly-linked
1653 * @val: a #gssize value in big-endian byte order
1655 * Converts a #gssize value from big-endian to host byte order.
1657 * Returns: @val converted to host byte order
1663 * @val: a #gssize value in little-endian byte order
1665 * Converts a #gssize value from little-endian to host byte order.
1667 * Returns: @val converted to host byte order
1673 * @val: a #gssize value in host byte order
1675 * Converts a #gssize value from host byte order to big-endian.
1677 * Returns: @val converted to big-endian
1683 * @val: a #gssize value in host byte order
1685 * Converts a #gssize value from host byte order to little-endian.
1687 * Returns: @val converted to little-endian
1693 * @user_data: unused
1694 * @max_parse_errors: unused
1695 * @parse_errors: g_scanner_error() increments this field
1696 * @input_name: name of input stream, featured by the default message handler
1697 * @qdata: quarked data
1698 * @config: link into the scanner configuration
1699 * @token: token parsed by the last g_scanner_get_next_token()
1700 * @value: value of the last token from g_scanner_get_next_token()
1701 * @line: line number of the last token from g_scanner_get_next_token()
1702 * @position: char number of the last token from g_scanner_get_next_token()
1703 * @next_token: token parsed by the last g_scanner_peek_next_token()
1704 * @next_value: value of the last token from g_scanner_peek_next_token()
1705 * @next_line: line number of the last token from g_scanner_peek_next_token()
1706 * @next_position: char number of the last token from g_scanner_peek_next_token()
1707 * @msg_handler: handler function for _warn and _error
1709 * The data structure representing a lexical scanner.
1711 * You should set @input_name after creating the scanner, since
1712 * it is used by the default message handler when displaying
1713 * warnings and errors. If you are scanning a file, the filename
1714 * would be a good choice.
1716 * The @user_data and @max_parse_errors fields are not used.
1717 * If you need to associate extra data with the scanner you
1718 * can place them here.
1720 * If you want to use your own message handler you can set the
1721 * @msg_handler field. The type of the message handler function
1722 * is declared by #GScannerMsgFunc.
1728 * @cset_skip_characters: specifies which characters should be skipped
1729 * by the scanner (the default is the whitespace characters: space,
1730 * tab, carriage-return and line-feed).
1731 * @cset_identifier_first: specifies the characters which can start
1732 * identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z).
1733 * @cset_identifier_nth: specifies the characters which can be used
1734 * in identifiers, after the first character (the default is
1735 * #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS,
1737 * @cpair_comment_single: specifies the characters at the start and
1738 * end of single-line comments. The default is "#\n" which means
1739 * that single-line comments start with a '#' and continue until
1740 * a '\n' (end of line).
1741 * @case_sensitive: specifies if symbols are case sensitive (the
1742 * default is %FALSE).
1743 * @skip_comment_multi: specifies if multi-line comments are skipped
1744 * and not returned as tokens (the default is %TRUE).
1745 * @skip_comment_single: specifies if single-line comments are skipped
1746 * and not returned as tokens (the default is %TRUE).
1747 * @scan_comment_multi: specifies if multi-line comments are recognized
1748 * (the default is %TRUE).
1749 * @scan_identifier: specifies if identifiers are recognized (the
1750 * default is %TRUE).
1751 * @scan_identifier_1char: specifies if single-character
1752 * identifiers are recognized (the default is %FALSE).
1753 * @scan_identifier_NULL: specifies if %NULL is reported as
1754 * %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
1755 * @scan_symbols: specifies if symbols are recognized (the default
1757 * @scan_binary: specifies if binary numbers are recognized (the
1758 * default is %FALSE).
1759 * @scan_octal: specifies if octal numbers are recognized (the
1760 * default is %TRUE).
1761 * @scan_float: specifies if floating point numbers are recognized
1762 * (the default is %TRUE).
1763 * @scan_hex: specifies if hexadecimal numbers are recognized (the
1764 * default is %TRUE).
1765 * @scan_hex_dollar: specifies if '$' is recognized as a prefix for
1766 * hexadecimal numbers (the default is %FALSE).
1767 * @scan_string_sq: specifies if strings can be enclosed in single
1768 * quotes (the default is %TRUE).
1769 * @scan_string_dq: specifies if strings can be enclosed in double
1770 * quotes (the default is %TRUE).
1771 * @numbers_2_int: specifies if binary, octal and hexadecimal numbers
1772 * are reported as #G_TOKEN_INT (the default is %TRUE).
1773 * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT
1774 * (the default is %FALSE).
1775 * @identifier_2_string: specifies if identifiers are reported as strings
1776 * (the default is %FALSE).
1777 * @char_2_token: specifies if characters are reported by setting
1778 * `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE).
1779 * @symbol_2_token: specifies if symbols are reported by setting
1780 * `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE).
1781 * @scope_0_fallback: specifies if a symbol is searched for in the
1782 * default scope in addition to the current scope (the default is %FALSE).
1783 * @store_int64: use value.v_int64 rather than v_int
1785 * Specifies the #GScanner parser configuration. Most settings can
1786 * be changed during the parsing phase and will affect the lexical
1787 * parsing of the next unpeeked token.
1793 * @scanner: a #GScanner
1794 * @message: the message
1795 * @error: %TRUE if the message signals an error,
1796 * %FALSE if it signals a warning.
1798 * Specifies the type of the message handler function.
1804 * @G_SEEK_CUR: the current position in the file.
1805 * @G_SEEK_SET: the start of the file.
1806 * @G_SEEK_END: the end of the file.
1808 * An enumeration specifying the base position for a
1809 * g_io_channel_seek_position() operation.
1816 * The #GSequence struct is an opaque data type representing a
1817 * [sequence][glib-Sequences] data type.
1824 * The #GSequenceIter struct is an opaque data type representing an
1825 * iterator pointing into a #GSequence.
1830 * GSequenceIterCompareFunc:
1831 * @a: a #GSequenceIter
1832 * @b: a #GSequenceIter
1835 * A #GSequenceIterCompareFunc is a function used to compare iterators.
1836 * It must return zero if the iterators compare equal, a negative value
1837 * if @a comes before @b, and a positive value if @b comes before @a.
1839 * Returns: zero if the iterators are equal, a negative value if @a
1840 * comes before @b, and a positive value if @b comes before @a.
1846 * @G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting.
1847 * @G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty.
1848 * @G_SHELL_ERROR_FAILED: Some other error.
1850 * Error codes returned by shell functions.
1857 * A type corresponding to the appropriate struct type for the stat()
1858 * system call, depending on the platform and/or compiler being used.
1860 * See g_stat() for more information.
1866 * @str: points to the character data. It may move as text is added.
1867 * The @str field is null-terminated and so
1868 * can be used as an ordinary C string.
1869 * @len: contains the length of the string, not including the
1870 * terminating nul byte.
1871 * @allocated_len: the number of bytes that can be stored in the
1872 * string before it needs to be reallocated. May be larger than @len.
1874 * The GString struct contains the public fields of a GString.
1881 * An opaque data structure representing String Chunks.
1882 * It should only be accessed by using the following functions.
1889 * An opaque structure representing a test case.
1895 * @user_data: the data provided when registering the test
1897 * The type used for test case functions that take an extra pointer
1906 * @G_TEST_DIST: a file that was included in the distribution tarball
1907 * @G_TEST_BUILT: a file that was built on the compiling machine
1909 * The type of file to return the filename for, when used with
1910 * g_test_build_filename().
1912 * These two options correspond rather directly to the 'dist' and
1913 * 'built' terminology that automake uses and are explicitly used to
1914 * distinguish between the 'srcdir' and 'builddir' being separate. All
1915 * files in your project should either be dist (in the
1916 * `DIST_EXTRA` or `dist_schema_DATA`
1917 * sense, in which case they will always be in the srcdir) or built (in
1918 * the `BUILT_SOURCES` sense, in which case they will
1919 * always be in the builddir).
1921 * Note: as a general rule of automake, files that are generated only as
1922 * part of the build-from-git process (but then are distributed with the
1923 * tarball) always go in srcdir (even if doing a srcdir != builddir
1924 * build from git) and are considered as distributed files.
1932 * @fixture: the test fixture
1933 * @user_data: the data provided when registering the test
1935 * The type used for functions that operate on test fixtures. This is
1936 * used for the fixture setup and teardown functions as well as for the
1937 * testcases themselves.
1939 * @user_data is a pointer to the data that was given when registering
1942 * @fixture will be a pointer to the area of memory allocated by the
1943 * test framework, of the size requested. If the requested size was
1944 * zero then @fixture will be equal to @user_data.
1953 * The type used for test case functions.
1960 * GTestSubprocessFlags:
1961 * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child
1962 * process will inherit the parent's stdin. Otherwise, the child's
1963 * stdin is redirected to `/dev/null`.
1964 * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child
1965 * process will inherit the parent's stdout. Otherwise, the child's
1966 * stdout will not be visible, but it will be captured to allow
1967 * later tests with g_test_trap_assert_stdout().
1968 * @G_TEST_SUBPROCESS_INHERIT_STDERR: If this flag is given, the child
1969 * process will inherit the parent's stderr. Otherwise, the child's
1970 * stderr will not be visible, but it will be captured to allow
1971 * later tests with g_test_trap_assert_stderr().
1973 * Flags to pass to g_test_trap_subprocess() to control input and output.
1975 * Note that in contrast with g_test_trap_fork(), the default is to
1976 * not show stdout and stderr.
1983 * An opaque structure representing a test suite.
1989 * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
1990 * `/dev/null` so it cannot be observed on the console during test
1991 * runs. The actual output is still captured though to allow later
1992 * tests with g_test_trap_assert_stdout().
1993 * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
1994 * `/dev/null` so it cannot be observed on the console during test
1995 * runs. The actual output is still captured though to allow later
1996 * tests with g_test_trap_assert_stderr().
1997 * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the
1998 * child process is shared with stdin of its parent process.
1999 * It is redirected to `/dev/null` otherwise.
2001 * Test traps are guards around forked tests.
2002 * These flags determine what traps to set.
2004 * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(),
2005 * which is deprecated. g_test_trap_subprocess() uses
2006 * #GTestTrapSubprocessFlags.
2013 * The #GThread struct represents a running thread. This struct
2014 * is returned by g_thread_new() or g_thread_try_new(). You can
2015 * obtain the #GThread struct representing the current thread by
2016 * calling g_thread_self().
2018 * GThread is refcounted, see g_thread_ref() and g_thread_unref().
2019 * The thread represented by it holds a reference while it is running,
2020 * and g_thread_join() consumes the reference that it is given, so
2021 * it is normally not necessary to manage GThread references
2024 * The structure is opaque -- none of its fields may be directly
2031 * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource
2032 * shortage. Try again later.
2034 * Possible errors of thread related functions.
2040 * @data: data passed to the thread
2042 * Specifies the type of the @func functions passed to g_thread_new()
2043 * or g_thread_try_new().
2045 * Returns: the return value of the thread
2051 * @func: the function to execute in the threads of this pool
2052 * @user_data: the user data for the threads of this pool
2053 * @exclusive: are all threads exclusive to this pool
2055 * The #GThreadPool struct represents a thread pool. It has three
2056 * public read-only members, but the underlying struct is bigger,
2057 * so you must not copy this struct.
2064 * Simply a replacement for time_t. It has been deprecated
2065 * since it is not equivalent to time_t on 64-bit platforms
2066 * with a 64-bit time_t. Unrelated to #GTimer.
2068 * Note that #GTime is defined to always be a 32-bit integer,
2069 * unlike time_t which may be 64-bit on some systems. Therefore,
2070 * #GTime will overflow in the year 2038, and you cannot use the
2071 * address of a #GTime variable as argument to the UNIX time()
2074 * Instead, do the following:
2075 * |[<!-- language="C" -->
2080 * gtime = (GTime)ttime;
2088 * @tv_usec: microseconds
2090 * Represents a precise time, with seconds and microseconds.
2091 * Similar to the struct timeval returned by the gettimeofday()
2094 * GLib is attempting to unify around the use of 64bit integers to
2095 * represent microsecond-precision time. As such, this type will be
2096 * removed from a future version of GLib.
2103 * #GTimeZone is an opaque structure whose members cannot be accessed
2113 * Opaque datatype that records a start time.
2119 * @G_TOKEN_EOF: the end of the file
2120 * @G_TOKEN_LEFT_PAREN: a '(' character
2121 * @G_TOKEN_LEFT_CURLY: a '{' character
2122 * @G_TOKEN_LEFT_BRACE: a '[' character
2123 * @G_TOKEN_RIGHT_CURLY: a '}' character
2124 * @G_TOKEN_RIGHT_PAREN: a ')' character
2125 * @G_TOKEN_RIGHT_BRACE: a ']' character
2126 * @G_TOKEN_EQUAL_SIGN: a '=' character
2127 * @G_TOKEN_COMMA: a ',' character
2128 * @G_TOKEN_NONE: not a token
2129 * @G_TOKEN_ERROR: an error occurred
2130 * @G_TOKEN_CHAR: a character
2131 * @G_TOKEN_BINARY: a binary integer
2132 * @G_TOKEN_OCTAL: an octal integer
2133 * @G_TOKEN_INT: an integer
2134 * @G_TOKEN_HEX: a hex integer
2135 * @G_TOKEN_FLOAT: a floating point number
2136 * @G_TOKEN_STRING: a string
2137 * @G_TOKEN_SYMBOL: a symbol
2138 * @G_TOKEN_IDENTIFIER: an identifier
2139 * @G_TOKEN_IDENTIFIER_NULL: a null identifier
2140 * @G_TOKEN_COMMENT_SINGLE: one line comment
2141 * @G_TOKEN_COMMENT_MULTI: multi line comment
2143 * The possible types of token returned from each
2144 * g_scanner_get_next_token() call.
2150 * @v_symbol: token symbol value
2151 * @v_identifier: token identifier value
2152 * @v_binary: token binary integer value
2153 * @v_octal: octal integer value
2154 * @v_int: integer value
2155 * @v_int64: 64-bit integer value
2156 * @v_float: floating point value
2157 * @v_hex: hex integer value
2158 * @v_string: string value
2159 * @v_comment: comment value
2160 * @v_char: character value
2161 * @v_error: error value
2163 * A union holding the value of the token.
2169 * @next: pointer to the previous element of the stack,
2170 * gets stored in the first `sizeof (gpointer)`
2171 * bytes of the element
2173 * Each piece of memory that is pushed onto the stack
2174 * is cast to a GTrashStack*.
2180 * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has
2181 * been introduced in 2.6, for older version use
2182 * %G_TRAVERSE_LEAFS.
2183 * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This
2184 * name has been introduced in 2.6, for older
2185 * version use %G_TRAVERSE_NON_LEAFS.
2186 * @G_TRAVERSE_ALL: all nodes should be visited.
2187 * @G_TRAVERSE_MASK: a mask of all traverse flags.
2188 * @G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES.
2189 * @G_TRAVERSE_NON_LEAFS: identical to %G_TRAVERSE_NON_LEAVES.
2191 * Specifies which nodes are visited during several of the tree
2192 * functions, including g_node_traverse() and g_node_find().
2198 * @key: a key of a #GTree node
2199 * @value: the value corresponding to the key
2200 * @data: user data passed to g_tree_traverse()
2202 * Specifies the type of function passed to g_tree_traverse(). It is
2203 * passed the key and value of each node, together with the @user_data
2204 * parameter passed to g_tree_traverse(). If the function returns
2205 * %TRUE, the traversal is stopped.
2207 * Returns: %TRUE to stop the traversal
2213 * @G_IN_ORDER: vists a node's left child first, then the node itself,
2214 * then its right child. This is the one to use if you
2215 * want the output sorted according to the compare
2217 * @G_PRE_ORDER: visits a node, then its children.
2218 * @G_POST_ORDER: visits the node's children, then the node itself.
2219 * @G_LEVEL_ORDER: is not implemented for
2220 * [balanced binary trees][glib-Balanced-Binary-Trees].
2221 * For [n-ary trees][glib-N-ary-Trees], it
2222 * vists the root node first, then its children, then
2223 * its grandchildren, and so on. Note that this is less
2224 * efficient than the other orders.
2226 * Specifies the type of traveral performed by g_tree_traverse(),
2227 * g_node_traverse() and g_node_find(). The different orders are
2229 * - In order: A, B, C, D, E, F, G, H, I
2230 * ![](Sorted_binary_tree_inorder.svg)
2231 * - Pre order: F, B, A, D, C, E, G, I, H
2232 * ![](Sorted_binary_tree_preorder.svg)
2233 * - Post order: A, C, E, D, B, H, I, G, F
2234 * ![](Sorted_binary_tree_postorder.svg)
2235 * - Level order: F, B, G, A, D, I, C, E, H
2236 * ![](Sorted_binary_tree_breadth-first_traversal.svg)
2243 * The GTree struct is an opaque data structure representing a
2244 * [balanced binary tree][glib-Balanced-Binary-Trees]. It should be
2245 * accessed only by using the following functions.
2251 * @val: a #guint16 value in big-endian byte order
2253 * Converts a #guint16 value from big-endian to host byte order.
2255 * Returns: @val converted to host byte order
2261 * @val: a #guint16 value in little-endian byte order
2263 * Converts a #guint16 value from little-endian to host byte order.
2265 * Returns: @val converted to host byte order
2270 * GUINT16_SWAP_BE_PDP:
2271 * @val: a #guint16 value in big-endian or pdp-endian byte order
2273 * Converts a #guint16 value between big-endian and pdp-endian byte order.
2274 * The conversion is symmetric so it can be used both ways.
2276 * Returns: @val converted to the opposite byte order
2281 * GUINT16_SWAP_LE_BE:
2282 * @val: a #guint16 value in little-endian or big-endian byte order
2284 * Converts a #guint16 value between little-endian and big-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_PDP:
2293 * @val: a #guint16 value in little-endian or pdp-endian byte order
2295 * Converts a #guint16 value between little-endian and pdp-endian byte order.
2296 * The conversion is symmetric so it can be used both ways.
2298 * Returns: @val converted to the opposite byte order
2304 * @val: a #guint16 value in host byte order
2306 * Converts a #guint16 value from host byte order to big-endian.
2308 * Returns: @val converted to big-endian
2314 * @val: a #guint16 value in host byte order
2316 * Converts a #guint16 value from host byte order to little-endian.
2318 * Returns: @val converted to little-endian
2324 * @val: a #guint32 value in big-endian byte order
2326 * Converts a #guint32 value from big-endian to host byte order.
2328 * Returns: @val converted to host byte order
2334 * @val: a #guint32 value in little-endian byte order
2336 * Converts a #guint32 value from little-endian to host byte order.
2338 * Returns: @val converted to host byte order
2343 * GUINT32_SWAP_BE_PDP:
2344 * @val: a #guint32 value in big-endian or pdp-endian byte order
2346 * Converts a #guint32 value between big-endian and pdp-endian byte order.
2347 * The conversion is symmetric so it can be used both ways.
2349 * Returns: @val converted to the opposite byte order
2354 * GUINT32_SWAP_LE_BE:
2355 * @val: a #guint32 value in little-endian or big-endian byte order
2357 * Converts a #guint32 value between little-endian and big-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_PDP:
2366 * @val: a #guint32 value in little-endian or pdp-endian byte order
2368 * Converts a #guint32 value between little-endian and pdp-endian byte order.
2369 * The conversion is symmetric so it can be used both ways.
2371 * Returns: @val converted to the opposite byte order
2377 * @val: a #guint32 value in host byte order
2379 * Converts a #guint32 value from host byte order to big-endian.
2381 * Returns: @val converted to big-endian
2387 * @val: a #guint32 value in host byte order
2389 * Converts a #guint32 value from host byte order to little-endian.
2391 * Returns: @val converted to little-endian
2397 * @val: a #guint64 value in big-endian byte order
2399 * Converts a #guint64 value from big-endian to host byte order.
2401 * Returns: @val converted to host byte order
2407 * @val: a #guint64 value in little-endian byte order
2409 * Converts a #guint64 value from little-endian to host byte order.
2411 * Returns: @val converted to host byte order
2416 * GUINT64_SWAP_LE_BE:
2417 * @val: a #guint64 value in little-endian or big-endian byte order
2419 * Converts a #guint64 value between little-endian and big-endian byte order.
2420 * The conversion is symmetric so it can be used both ways.
2422 * Returns: @val converted to the opposite byte order
2428 * @val: a #guint64 value in host byte order
2430 * Converts a #guint64 value from host byte order to big-endian.
2432 * Returns: @val converted to big-endian
2438 * @val: a #guint64 value in host byte order
2440 * Converts a #guint64 value from host byte order to little-endian.
2442 * Returns: @val converted to little-endian
2448 * @val: a #guint value in big-endian byte order
2450 * Converts a #guint value from big-endian to host byte order.
2452 * Returns: @val converted to host byte order
2458 * @val: a #guint value in little-endian byte order
2460 * Converts a #guint value from little-endian to host byte order.
2462 * Returns: @val converted to host byte order
2468 * @val: a #guint value in host byte order
2470 * Converts a #guint value from host byte order to big-endian.
2472 * Returns: @val converted to big-endian byte order
2478 * @val: a #guint value in host byte order
2480 * Converts a #guint value from host byte order to little-endian.
2482 * Returns: @val converted to little-endian byte order.
2488 * @u: unsigned integer to stuff into the pointer
2490 * Stuffs an unsigned integer into a pointer type.
2496 * @val: a #gulong value in big-endian byte order
2498 * Converts a #gulong value from big-endian to host byte order.
2500 * Returns: @val converted to host byte order
2506 * @val: a #gulong value in little-endian byte order
2508 * Converts a #gulong value from little-endian to host byte order.
2510 * Returns: @val converted to host byte order
2516 * @val: a #gulong value in host byte order
2518 * Converts a #gulong value from host byte order to big-endian.
2520 * Returns: @val converted to big-endian
2526 * @val: a #gulong value in host byte order
2528 * Converts a #gulong value from host byte order to little-endian.
2530 * Returns: @val converted to little-endian
2537 * #GVariant is an opaque data structure and can only be accessed
2538 * using the following functions.
2547 * A utility type for constructing container-type #GVariant instances.
2549 * This is an opaque structure and may only be accessed using the
2550 * following functions.
2552 * #GVariantBuilder is not threadsafe in any way. Do not attempt to
2553 * access it from more than one thread.
2559 * @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean.
2560 * @G_VARIANT_CLASS_BYTE: The #GVariant is a byte.
2561 * @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer.
2562 * @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer.
2563 * @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer.
2564 * @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer.
2565 * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer.
2566 * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer.
2567 * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index.
2568 * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating
2570 * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string.
2571 * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path
2573 * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string.
2574 * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant.
2575 * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value.
2576 * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array.
2577 * @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple.
2578 * @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry.
2580 * The range of possible top-level types of #GVariant instances.
2589 * #GVariantDict is a mutable interface to #GVariant dictionaries.
2591 * It can be used for doing a sequence of dictionary lookups in an
2592 * efficient way on an existing #GVariant dictionary or it can be used
2593 * to construct new dictionaries with a hashtable-like interface. It
2594 * can also be used for taking existing dictionaries and modifying them
2595 * in order to create new ones.
2597 * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT
2600 * It is possible to use #GVariantDict allocated on the stack or on the
2601 * heap. When using a stack-allocated #GVariantDict, you begin with a
2602 * call to g_variant_dict_init() and free the resources with a call to
2603 * g_variant_dict_clear().
2605 * Heap-allocated #GVariantDict follows normal refcounting rules: you
2606 * allocate it with g_variant_dict_new() and use g_variant_dict_ref()
2607 * and g_variant_dict_unref().
2609 * g_variant_dict_end() is used to convert the #GVariantDict back into a
2610 * dictionary-type #GVariant. When used with stack-allocated instances,
2611 * this also implicitly frees all associated memory, but for
2612 * heap-allocated instances, you must still call g_variant_dict_unref()
2615 * You will typically want to use a heap-allocated #GVariantDict when
2616 * you expose it as part of an API. For most other uses, the
2617 * stack-allocated form will be more convenient.
2619 * Consider the following two examples that do the same thing in each
2620 * style: take an existing dictionary and look up the "count" uint32
2621 * key, adding 1 to it if it is found, or returning an error if the
2622 * key is not found. Each returns the new dictionary as a floating
2625 * ## Using a stack-allocated GVariantDict
2629 * add_to_count (GVariant *orig,
2632 * GVariantDict dict;
2635 * g_variant_dict_init (&dict, orig);
2636 * if (!g_variant_dict_lookup (&dict, "count", "u", &count))
2638 * g_set_error (...);
2639 * g_variant_dict_clear (&dict);
2643 * g_variant_dict_insert (&dict, "count", "u", count + 1);
2645 * return g_variant_dict_end (&dict);
2649 * ## Using heap-allocated GVariantDict
2653 * add_to_count (GVariant *orig,
2656 * GVariantDict *dict;
2660 * dict = g_variant_dict_new (orig);
2662 * if (g_variant_dict_lookup (dict, "count", "u", &count))
2664 * g_variant_dict_insert (dict, "count", "u", count + 1);
2665 * result = g_variant_dict_end (dict);
2669 * g_set_error (...);
2673 * g_variant_dict_unref (dict);
2684 * GVariantIter: (skip)
2686 * #GVariantIter is an opaque data structure and can only be accessed
2687 * using the following functions.
2692 * GVariantParseError:
2693 * @G_VARIANT_PARSE_ERROR_FAILED: generic error (unused)
2694 * @G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED: a non-basic #GVariantType was given where a basic type was expected
2695 * @G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE: cannot infer the #GVariantType
2696 * @G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED: an indefinite #GVariantType was given where a definite type was expected
2697 * @G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END: extra data after parsing finished
2698 * @G_VARIANT_PARSE_ERROR_INVALID_CHARACTER: invalid character in number or unicode escape
2699 * @G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING: not a valid #GVariant format string
2700 * @G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH: not a valid object path
2701 * @G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE: not a valid type signature
2702 * @G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING: not a valid #GVariant type string
2703 * @G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE: could not find a common type for array entries
2704 * @G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE: the numerical value is out of range of the given type
2705 * @G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG: the numerical value is out of range for any type
2706 * @G_VARIANT_PARSE_ERROR_TYPE_ERROR: cannot parse as variant of the specified type
2707 * @G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN: an unexpected token was encountered
2708 * @G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD: an unknown keyword was encountered
2709 * @G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT: unterminated string constant
2710 * @G_VARIANT_PARSE_ERROR_VALUE_EXPECTED: no value given
2712 * Error codes returned by parsing text-format GVariants.
2717 * G_ASCII_DTOSTR_BUF_SIZE:
2719 * A good size for a buffer to be passed into g_ascii_dtostr().
2720 * It is guaranteed to be enough for all output of that function
2721 * on systems with 64bit IEEE-compatible doubles.
2723 * The typical usage would be something like:
2724 * |[<!-- language="C" -->
2725 * char buf[G_ASCII_DTOSTR_BUF_SIZE];
2727 * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
2733 * G_ATOMIC_LOCK_FREE:
2735 * This macro is defined if the atomic operations of GLib are
2736 * implemented using real hardware atomic operations. This means that
2737 * the GLib atomic API can be used between processes and safely mixed
2738 * with other (hardware) atomic APIs.
2740 * If this macro is not defined, the atomic operations may be
2741 * emulated using a mutex. In that case, the GLib atomic operations are
2742 * only atomic relative to themselves and within a single process.
2749 * Used (along with #G_END_DECLS) to bracket header files. If the
2750 * compiler in use is a C++ compiler, adds extern "C"
2751 * around the header.
2758 * Specifies one of the possible types of byte order.
2759 * See #G_BYTE_ORDER.
2766 * The host byte order.
2767 * This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for
2768 * #G_PDP_ENDIAN may be added in future.)
2775 * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
2776 * to nothing. By default, the macro expands to const. The macro
2777 * can be used in place of const for functions that return a value
2778 * that should not be modified. The purpose of this macro is to allow
2779 * us to turn on const for returned constant strings by default, while
2780 * allowing programmers who find that annoying to turn it off. This macro
2781 * should only be used for return values and for "out" parameters, it
2782 * doesn't make sense for "in" parameters.
2784 * Deprecated: 2.30: API providers should replace all existing uses with
2785 * const and API consumers should adjust their code accordingly
2792 * The set of uppercase ASCII alphabet characters.
2793 * Used for specifying valid identifier characters
2794 * in #GScannerConfig.
2801 * The set of uppercase ISO 8859-1 alphabet characters
2802 * which are not ASCII characters.
2803 * Used for specifying valid identifier characters
2804 * in #GScannerConfig.
2811 * The set of lowercase ISO 8859-1 alphabet characters
2812 * which are not ASCII characters.
2813 * Used for specifying valid identifier characters
2814 * in #GScannerConfig.
2821 * The set of lowercase ASCII alphabet characters.
2822 * Used for specifying valid identifier characters
2823 * in #GScannerConfig.
2830 * Represents an invalid #GDateDay.
2835 * G_DATE_BAD_JULIAN:
2837 * Represents an invalid Julian day number.
2844 * Represents an invalid year.
2850 * @QN: the name to return a #GQuark for
2851 * @q_n: prefix for the function name
2853 * A convenience macro which defines a function returning the
2854 * #GQuark for the name @QN. The function will be named
2857 * Note that the quark name will be stringified automatically
2858 * in the macro, so you shouldn't use double quotes.
2867 * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
2868 * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
2869 * meant to be portable across different compilers and must be placed
2870 * before the function declaration.
2878 * @f: the name of the function that this function was deprecated for
2880 * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
2881 * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
2882 * is meant to be portable across different compilers and must be placed
2883 * before the function declaration.
2892 * The directory separator character.
2893 * This is '/' on UNIX machines and '\' under Windows.
2898 * G_DIR_SEPARATOR_S:
2900 * The directory separator as a string.
2901 * This is "/" on UNIX machines and "\" under Windows.
2908 * The base of natural logarithms.
2915 * Used (along with #G_BEGIN_DECLS) to bracket header files. If the
2916 * compiler in use is a C++ compiler, adds extern "C"
2917 * around the header.
2924 * Error domain for file operations. Errors in this domain will
2925 * be from the #GFileError enumeration. See #GError for information
2933 * This is the platform dependent conversion specifier for scanning and
2934 * printing values of type #gint16. It is a string literal, but doesn't
2935 * include the percent-sign, such that you can add precision and length
2936 * modifiers between percent-sign and conversion specifier.
2938 * |[<!-- language="C" -->
2941 * sscanf ("42", "%" G_GINT16_FORMAT, &in)
2943 * g_print ("%" G_GINT32_FORMAT, out);
2949 * G_GINT16_MODIFIER:
2951 * The platform dependent length modifier for conversion specifiers
2952 * for scanning and printing values of type #gint16 or #guint16. It
2953 * is a string literal, but doesn't include the percent-sign, such
2954 * that you can add precision and length modifiers between percent-sign
2955 * and conversion specifier and append a conversion specifier.
2957 * The following example prints "0x7b";
2958 * |[<!-- language="C" -->
2959 * gint16 value = 123;
2960 * g_print ("%#" G_GINT16_MODIFIER "x", value);
2970 * This is the platform dependent conversion specifier for scanning
2971 * and printing values of type #gint32. See also #G_GINT16_FORMAT.
2976 * G_GINT32_MODIFIER:
2978 * The platform dependent length modifier for conversion specifiers
2979 * for scanning and printing values of type #gint32 or #guint32. It
2980 * is a string literal. See also #G_GINT16_MODIFIER.
2987 * G_GINT64_CONSTANT:
2988 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
2990 * This macro is used to insert 64-bit integer literals
2991 * into the source code.
2998 * This is the platform dependent conversion specifier for scanning
2999 * and printing values of type #gint64. See also #G_GINT16_FORMAT.
3001 * Some platforms do not support scanning and printing 64-bit integers,
3002 * even though the types are supported. On such platforms %G_GINT64_FORMAT
3003 * is not defined. Note that scanf() may not support 64-bit integers, even
3004 * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
3005 * is not recommended for parsing anyway; consider using g_ascii_strtoull()
3011 * G_GINT64_MODIFIER:
3013 * The platform dependent length modifier for conversion specifiers
3014 * for scanning and printing values of type #gint64 or #guint64.
3015 * It is a string literal.
3017 * Some platforms do not support printing 64-bit integers, even
3018 * though the types are supported. On such platforms %G_GINT64_MODIFIER
3028 * This is the platform dependent conversion specifier for scanning
3029 * and printing values of type #gintptr.
3036 * G_GINTPTR_MODIFIER:
3038 * The platform dependent length modifier for conversion specifiers
3039 * for scanning and printing values of type #gintptr or #guintptr.
3040 * It is a string literal.
3047 * G_GNUC_ALLOC_SIZE:
3048 * @x: the index of the argument specifying the allocation size
3050 * Expands to the GNU C alloc_size function attribute if the compiler
3051 * is a new enough gcc. This attribute tells the compiler that the
3052 * function returns a pointer to memory of a size that is specified
3053 * by the @xth function parameter.
3055 * Place the attribute after the function declaration, just before the
3058 * See the GNU C documentation for more details.
3065 * G_GNUC_ALLOC_SIZE2:
3066 * @x: the index of the argument specifying one factor of the allocation size
3067 * @y: the index of the argument specifying the second factor of the allocation size
3069 * Expands to the GNU C alloc_size function attribute if the compiler is a
3070 * new enough gcc. This attribute tells the compiler that the function returns
3071 * a pointer to memory of a size that is specified by the product of two
3072 * function parameters.
3074 * Place the attribute after the function declaration, just before the
3077 * See the GNU C documentation for more details.
3084 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
3086 * Tells gcc (if it is a new enough version) to temporarily stop emitting
3087 * warnings when functions marked with %G_GNUC_DEPRECATED or
3088 * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have
3089 * one deprecated function calling another one, or when you still have
3090 * regression tests for deprecated functions.
3092 * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
3093 * are not compiling with `-Wdeprecated-declarations` then neither macro
3096 * This macro can be used either inside or outside of a function body,
3097 * but must appear on a line by itself.
3106 * Expands to the GNU C const function attribute if the compiler is gcc.
3107 * Declaring a function as const enables better optimization of calls to
3108 * the function. A const function doesn't examine any values except its
3109 * parameters, and has no effects except its return value.
3111 * Place the attribute after the declaration, just before the semicolon.
3113 * See the GNU C documentation for more details.
3115 * A function that has pointer arguments and examines the data pointed to
3116 * must not be declared const. Likewise, a function that calls a non-const
3117 * function usually must not be const. It doesn't make sense for a const
3118 * function to return void.
3123 * G_GNUC_DEPRECATED:
3125 * Expands to the GNU C deprecated attribute if the compiler is gcc.
3126 * It can be used to mark typedefs, variables and functions as deprecated.
3127 * When called with the `-Wdeprecated-declarations` option,
3128 * gcc will generate warnings when deprecated interfaces are used.
3130 * Place the attribute after the declaration, just before the semicolon.
3132 * See the GNU C documentation for more details.
3139 * G_GNUC_DEPRECATED_FOR:
3140 * @f: the intended replacement for the deprecated symbol,
3141 * such as the name of a function
3143 * Like %G_GNUC_DEPRECATED, but names the intended replacement for the
3144 * deprecated symbol if the version of gcc in use is new enough to support
3145 * custom deprecation messages.
3147 * Place the attribute after the declaration, just before the semicolon.
3149 * See the GNU C documentation for more details.
3151 * Note that if @f is a macro, it will be expanded in the warning message.
3152 * You can enclose it in quotes to prevent this. (The quotes will show up
3153 * in the warning, but it's better than showing the macro expansion.)
3160 * G_GNUC_END_IGNORE_DEPRECATIONS:
3162 * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
3163 * gcc to begin outputting warnings again (assuming those warnings
3164 * had been enabled to begin with).
3166 * This macro can be used either inside or outside of a function body,
3167 * but must appear on a line by itself.
3176 * Expands to __extension__ when gcc is used as the compiler. This simply
3177 * tells gcc not to warn about the following non-standard code when compiling
3178 * with the `-pedantic` option.
3184 * @arg_idx: the index of the argument
3186 * Expands to the GNU C format_arg function attribute if the compiler
3187 * is gcc. This function attribute specifies that a function takes a
3188 * format string for a printf(), scanf(), strftime() or strfmon() style
3189 * function and modifies it, so that the result can be passed to a printf(),
3190 * scanf(), strftime() or strfmon() style function (with the remaining
3191 * arguments to the format function the same as they would have been
3192 * for the unmodified string).
3194 * Place the attribute after the function declaration, just before the
3197 * See the GNU C documentation for more details.
3199 * |[<!-- language="C" -->
3200 * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
3208 * Expands to "" on all modern compilers, and to __FUNCTION__ on gcc
3209 * version 2.x. Don't use it.
3211 * Deprecated: 2.16: Use G_STRFUNC() instead
3218 * This attribute can be used for marking library functions as being used
3219 * internally to the library only, which may allow the compiler to handle
3220 * function calls more efficiently. Note that static functions do not need
3221 * to be marked as internal in this way. See the GNU C documentation for
3224 * When using a compiler that supports the GNU C hidden visibility attribute,
3225 * this macro expands to __attribute__((visibility("hidden"))).
3226 * When using the Sun Studio compiler, it expands to __hidden.
3228 * Note that for portability, the attribute should be placed before the
3229 * function declaration. While GCC allows the macro after the declaration,
3230 * Sun Studio does not.
3232 * |[<!-- language="C" -->
3234 * void _g_log_fallback_handler (const gchar *log_domain,
3235 * GLogLevelFlags log_level,
3236 * const gchar *message,
3237 * gpointer unused_data);
3247 * Expands to the GNU C malloc function attribute if the compiler is gcc.
3248 * Declaring a function as malloc enables better optimization of the function.
3249 * A function can have the malloc attribute if it returns a pointer which is
3250 * guaranteed to not alias with any other pointer when the function returns
3251 * (in practice, this means newly allocated memory).
3253 * Place the attribute after the declaration, just before the semicolon.
3255 * See the GNU C documentation for more details.
3264 * Expands to the GNU C may_alias type attribute if the compiler is gcc.
3265 * Types with this attribute will not be subjected to type-based alias
3266 * analysis, but are assumed to alias with any other type, just like char.
3268 * See the GNU C documentation for details.
3277 * Expands to the GNU C noreturn function attribute if the compiler is gcc.
3278 * It is used for declaring functions which never return. It enables
3279 * optimization of the function, and avoids possible compiler warnings.
3281 * Place the attribute after the declaration, just before the semicolon.
3283 * See the GNU C documentation for more details.
3288 * G_GNUC_NO_INSTRUMENT:
3290 * Expands to the GNU C no_instrument_function function attribute if the
3291 * compiler is gcc. Functions with this attribute will not be instrumented
3292 * for profiling, when the compiler is called with the
3293 * `-finstrument-functions` option.
3295 * Place the attribute after the declaration, just before the semicolon.
3297 * See the GNU C documentation for more details.
3302 * G_GNUC_NULL_TERMINATED:
3304 * Expands to the GNU C sentinel function attribute if the compiler is gcc.
3305 * This function attribute only applies to variadic functions and instructs
3306 * the compiler to check that the argument list is terminated with an
3309 * Place the attribute after the declaration, just before the semicolon.
3311 * See the GNU C documentation for more details.
3318 * G_GNUC_PRETTY_FUNCTION:
3320 * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
3321 * on gcc version 2.x. Don't use it.
3323 * Deprecated: 2.16: Use G_STRFUNC() instead
3329 * @format_idx: the index of the argument corresponding to the
3330 * format string (The arguments are numbered from 1)
3331 * @arg_idx: the index of the first of the format arguments
3333 * Expands to the GNU C format function attribute if the compiler is gcc.
3334 * This is used for declaring functions which take a variable number of
3335 * arguments, with the same syntax as printf(). It allows the compiler
3336 * to type-check the arguments passed to the function.
3338 * Place the attribute after the function declaration, just before the
3341 * See the GNU C documentation for more details.
3343 * |[<!-- language="C" -->
3344 * gint g_snprintf (gchar *string,
3346 * gchar const *format,
3347 * ...) G_GNUC_PRINTF (3, 4);
3355 * Expands to the GNU C pure function attribute if the compiler is gcc.
3356 * Declaring a function as pure enables better optimization of calls to
3357 * the function. A pure function has no effects except its return value
3358 * and the return value depends only on the parameters and/or global
3361 * Place the attribute after the declaration, just before the semicolon.
3363 * See the GNU C documentation for more details.
3369 * @format_idx: the index of the argument corresponding to
3370 * the format string (The arguments are numbered from 1)
3371 * @arg_idx: the index of the first of the format arguments
3373 * Expands to the GNU C format function attribute if the compiler is gcc.
3374 * This is used for declaring functions which take a variable number of
3375 * arguments, with the same syntax as scanf(). It allows the compiler
3376 * to type-check the arguments passed to the function.
3378 * See the GNU C documentation for details.
3385 * Expands to the GNU C unused function attribute if the compiler is gcc.
3386 * It is used for declaring functions and arguments which may never be used.
3387 * It avoids possible compiler warnings.
3389 * For functions, place the attribute after the declaration, just before the
3390 * semicolon. For arguments, place the attribute at the beginning of the
3391 * argument declaration.
3393 * |[<!-- language="C" -->
3394 * void my_unused_function (G_GNUC_UNUSED gint unused_argument,
3395 * gint other_argument) G_GNUC_UNUSED;
3398 * See the GNU C documentation for more details.
3403 * G_GNUC_WARN_UNUSED_RESULT:
3405 * Expands to the GNU C warn_unused_result function attribute if the compiler
3406 * is gcc. This function attribute makes the compiler emit a warning if the
3407 * result of a function call is ignored.
3409 * Place the attribute after the declaration, just before the semicolon.
3411 * See the GNU C documentation for more details.
3418 * G_GOFFSET_CONSTANT:
3419 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
3421 * This macro is used to insert #goffset 64-bit integer literals
3422 * into the source code.
3424 * See also #G_GINT64_CONSTANT.
3433 * This is the platform dependent conversion specifier for scanning
3434 * and printing values of type #goffset. See also #G_GINT64_FORMAT.
3441 * G_GOFFSET_MODIFIER:
3443 * The platform dependent length modifier for conversion specifiers
3444 * for scanning and printing values of type #goffset. It is a string
3445 * literal. See also #G_GINT64_MODIFIER.
3454 * This is the platform dependent conversion specifier for scanning
3455 * and printing values of type #gsize. See also #G_GINT16_FORMAT.
3464 * The platform dependent length modifier for conversion specifiers
3465 * for scanning and printing values of type #gsize or #gssize. It
3466 * is a string literal.
3475 * This is the platform dependent conversion specifier for scanning
3476 * and printing values of type #gssize. See also #G_GINT16_FORMAT.
3485 * This is the platform dependent conversion specifier for scanning
3486 * and printing values of type #guint16. See also #G_GINT16_FORMAT
3493 * This is the platform dependent conversion specifier for scanning
3494 * and printing values of type #guint32. See also #G_GINT16_FORMAT.
3499 * G_GUINT64_CONSTANT:
3500 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7U
3502 * This macro is used to insert 64-bit unsigned integer
3503 * literals into the source code.
3512 * This is the platform dependent conversion specifier for scanning
3513 * and printing values of type #guint64. See also #G_GINT16_FORMAT.
3515 * Some platforms do not support scanning and printing 64-bit integers,
3516 * even though the types are supported. On such platforms %G_GUINT64_FORMAT
3517 * is not defined. Note that scanf() may not support 64-bit integers, even
3518 * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
3519 * is not recommended for parsing anyway; consider using g_ascii_strtoull()
3525 * G_GUINTPTR_FORMAT:
3527 * This is the platform dependent conversion specifier
3528 * for scanning and printing values of type #guintptr.
3538 * Casts a pointer to a `GHook*`.
3546 * Returns %TRUE if the #GHook is active, which is normally the case
3547 * until the #GHook is destroyed.
3549 * Returns: %TRUE if the #GHook is active
3557 * Gets the flags of a hook.
3562 * G_HOOK_FLAG_USER_SHIFT:
3564 * The position of the first bit which is not reserved for internal
3565 * use be the #GHook implementation, i.e.
3566 * `1 << G_HOOK_FLAG_USER_SHIFT` is the first
3567 * bit which can be used for application-defined flags.
3575 * Returns %TRUE if the #GHook function is currently executing.
3577 * Returns: %TRUE if the #GHook function is currently executing
3582 * G_HOOK_IS_UNLINKED:
3585 * Returns %TRUE if the #GHook is not in a #GHookList.
3587 * Returns: %TRUE if the #GHook is not in a #GHookList
3595 * Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList,
3596 * it is active and it has not been destroyed.
3598 * Returns: %TRUE if the #GHook is valid
3603 * G_IEEE754_DOUBLE_BIAS:
3605 * The bias by which exponents in double-precision floats are offset.
3610 * G_IEEE754_FLOAT_BIAS:
3612 * The bias by which exponents in single-precision floats are offset.
3619 * This macro is used to export function prototypes so they can be linked
3620 * with an external version when no inlining is performed. The file which
3621 * implements the functions should define %G_IMPLEMENTS_INLINES
3622 * before including the headers which contain %G_INLINE_FUNC declarations.
3623 * Since inlining is very compiler-dependent using these macros correctly
3624 * is very difficult. Their use is strongly discouraged.
3626 * This macro is often mistaken for a replacement for the inline keyword;
3627 * inline is already declared in a portable manner in the GLib headers
3628 * and can be used normally.
3633 * G_IO_CHANNEL_ERROR:
3635 * Error domain for #GIOChannel operations. Errors in this domain will
3636 * be from the #GIOChannelError enumeration. See #GError for
3637 * information on error domains.
3642 * G_IS_DIR_SEPARATOR:
3645 * Checks whether a character is a directory
3646 * separator. It returns %TRUE for '/' on UNIX
3647 * machines and for '\' or '/' under Windows.
3654 * G_KEY_FILE_DESKTOP_GROUP:
3656 * The name of the main group of a desktop entry file, as defined in the
3657 * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec).
3658 * Consult the specification for more
3659 * details about the meanings of the keys below.
3666 * G_KEY_FILE_DESKTOP_KEY_CATEGORIES:
3668 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
3669 * of strings giving the categories in which the desktop entry
3670 * should be shown in a menu.
3677 * G_KEY_FILE_DESKTOP_KEY_COMMENT:
3679 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
3680 * string giving the tooltip for the desktop entry.
3687 * G_KEY_FILE_DESKTOP_KEY_EXEC:
3689 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3690 * giving the command line to execute. It is only valid for desktop
3691 * entries with the `Application` type.
3698 * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME:
3700 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
3701 * string giving the generic name of the desktop entry.
3708 * G_KEY_FILE_DESKTOP_KEY_HIDDEN:
3710 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
3711 * stating whether the desktop entry has been deleted by the user.
3718 * G_KEY_FILE_DESKTOP_KEY_ICON:
3720 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
3721 * string giving the name of the icon to be displayed for the desktop
3729 * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE:
3731 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
3732 * of strings giving the MIME types supported by this desktop entry.
3739 * G_KEY_FILE_DESKTOP_KEY_NAME:
3741 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
3742 * string giving the specific name of the desktop entry.
3749 * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN:
3751 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
3752 * strings identifying the environments that should not display the
3760 * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY:
3762 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
3763 * stating whether the desktop entry should be shown in menus.
3770 * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN:
3772 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
3773 * strings identifying the environments that should display the
3781 * G_KEY_FILE_DESKTOP_KEY_PATH:
3783 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3784 * containing the working directory to run the program in. It is only
3785 * valid for desktop entries with the `Application` type.
3792 * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY:
3794 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
3795 * stating whether the application supports the
3796 * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec).
3803 * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS:
3805 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string
3806 * identifying the WM class or name hint of a window that the application
3807 * will create, which can be used to emulate Startup Notification with
3808 * older applications.
3815 * G_KEY_FILE_DESKTOP_KEY_TERMINAL:
3817 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
3818 * stating whether the program should be run in a terminal window.
3819 * It is only valid for desktop entries with the
3820 * `Application` type.
3827 * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC:
3829 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3830 * giving the file name of a binary on disk used to determine if the
3831 * program is actually installed. It is only valid for desktop entries
3832 * with the `Application` type.
3839 * G_KEY_FILE_DESKTOP_KEY_TYPE:
3841 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3842 * giving the type of the desktop entry. Usually
3843 * #G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
3844 * #G_KEY_FILE_DESKTOP_TYPE_LINK, or
3845 * #G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.
3852 * G_KEY_FILE_DESKTOP_KEY_URL:
3854 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3855 * giving the URL to access. It is only valid for desktop entries
3856 * with the `Link` type.
3863 * G_KEY_FILE_DESKTOP_KEY_VERSION:
3865 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3866 * giving the version of the Desktop Entry Specification used for
3867 * the desktop entry file.
3874 * G_KEY_FILE_DESKTOP_TYPE_APPLICATION:
3876 * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
3877 * entries representing applications.
3884 * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY:
3886 * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
3887 * entries representing directories.
3894 * G_KEY_FILE_DESKTOP_TYPE_LINK:
3896 * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
3897 * entries representing links to documents.
3906 * Error domain for key file parsing. Errors in this domain will
3907 * be from the #GKeyFileError enumeration.
3909 * See #GError for information on error domains.
3915 * @expr: the expression
3917 * Hints the compiler that the expression is likely to evaluate to
3918 * a true value. The compiler may use this information for optimizations.
3920 * |[<!-- language="C" -->
3921 * if (G_LIKELY (random () != 1))
3922 * g_print ("not one");
3925 * Returns: the value of @expr
3933 * Specifies one of the possible types of byte order.
3934 * See #G_BYTE_ORDER.
3941 * The natural logarithm of 10.
3948 * The natural logarithm of 2.
3954 * @name: the name of the lock
3956 * Works like g_mutex_lock(), but for a lock defined with
3963 * @name: the name of the lock
3965 * The #G_LOCK_ macros provide a convenient interface to #GMutex.
3966 * #G_LOCK_DEFINE defines a lock. It can appear in any place where
3967 * variable definitions may appear in programs, i.e. in the first block
3968 * of a function or outside of functions. The @name parameter will be
3969 * mangled to get the name of the #GMutex. This means that you
3970 * can use names of existing variables as the parameter - e.g. the name
3971 * of the variable you intend to protect with the lock. Look at our
3972 * give_me_next_number() example using the #G_LOCK macros:
3974 * Here is an example for using the #G_LOCK convenience macros:
3975 * |[<!-- language="C" -->
3976 * G_LOCK_DEFINE (current_number);
3979 * give_me_next_number (void)
3981 * static int current_number = 0;
3984 * G_LOCK (current_number);
3985 * ret_val = current_number = calc_next_number (current_number);
3986 * G_UNLOCK (current_number);
3995 * G_LOCK_DEFINE_STATIC:
3996 * @name: the name of the lock
3998 * This works like #G_LOCK_DEFINE, but it creates a static object.
4004 * @name: the name of the lock
4006 * This declares a lock, that is defined with #G_LOCK_DEFINE in another
4014 * Multiplying the base 2 exponent by this number yields the base 10 exponent.
4021 * Defines the log domain.
4023 * For applications, this is typically left as the default %NULL
4024 * (or "") domain. Libraries should define this so that any messages
4025 * which they log can be differentiated from messages from other
4026 * libraries and application code. But be careful not to define
4027 * it in any public header files.
4029 * For example, GTK+ uses this in its Makefile.am:
4031 * INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"
4039 * GLib log levels that are considered fatal by default.
4046 * The maximum value which can be held in a #gdouble.
4053 * The maximum value which can be held in a #gfloat.
4060 * The maximum value which can be held in a #gint.
4067 * The maximum value which can be held in a #gint16.
4076 * The maximum value which can be held in a #gint32.
4085 * The maximum value which can be held in a #gint64.
4092 * The maximum value which can be held in a #gint8.
4101 * The maximum value which can be held in a #glong.
4108 * The maximum value which can be held in a #goffset.
4115 * The maximum value which can be held in a #gshort.
4122 * The maximum value which can be held in a #gsize.
4131 * The maximum value which can be held in a #gssize.
4140 * The maximum value which can be held in a #guint.
4147 * The maximum value which can be held in a #guint16.
4156 * The maximum value which can be held in a #guint32.
4165 * The maximum value which can be held in a #guint64.
4172 * The maximum value which can be held in a #guint8.
4181 * The maximum value which can be held in a #gulong.
4188 * The maximum value which can be held in a #gushort.
4195 * The minimum positive value which can be held in a #gdouble.
4197 * If you are interested in the smallest value which can be held
4198 * in a #gdouble, use -%G_MAXDOUBLE.
4205 * The minimum positive value which can be held in a #gfloat.
4207 * If you are interested in the smallest value which can be held
4208 * in a #gfloat, use -%G_MAXFLOAT.
4215 * The minimum value which can be held in a #gint.
4222 * The minimum value which can be held in a #gint16.
4231 * The minimum value which can be held in a #gint32.
4240 * The minimum value which can be held in a #gint64.
4247 * The minimum value which can be held in a #gint8.
4256 * The minimum value which can be held in a #glong.
4263 * The minimum value which can be held in a #goffset.
4270 * The minimum value which can be held in a #gshort.
4277 * The minimum value which can be held in a #gssize.
4287 * Determines the number of elements in an array. The array must be
4288 * declared so the compiler knows its size at compile-time; this
4289 * macro will not work on an array allocated on the heap, only static
4290 * arrays or arrays on the stack.
4297 * A #GOnce must be initialized with this macro before it can be used.
4299 * |[<!-- language="C" -->
4300 * GOnce my_once = G_ONCE_INIT;
4310 * This macro is defined only on UNIX. So you can bracket
4311 * UNIX-specific code in "\#ifdef G_OS_UNIX".
4318 * This macro is defined only on Windows. So you can bracket
4319 * Windows-specific code in "\#ifdef G_OS_WIN32".
4325 * @identifier1: an identifier
4326 * @identifier2: an identifier
4328 * Yields a new preprocessor pasted identifier
4329 * @identifier1identifier2 from its expanded
4330 * arguments @identifier1 and @identifier2. For example,
4331 * the following code:
4332 * |[<!-- language="C" -->
4333 * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
4334 * const gchar *name = GET (traveller, name);
4335 * const gchar *quest = GET (traveller, quest);
4336 * GdkColor *favourite = GET (traveller, favourite_colour);
4339 * is transformed by the preprocessor into:
4340 * |[<!-- language="C" -->
4341 * const gchar *name = traveller_get_name (traveller);
4342 * const gchar *quest = traveller_get_quest (traveller);
4343 * GdkColor *favourite = traveller_get_favourite_colour (traveller);
4353 * Specifies one of the possible types of byte order
4354 * (currently unused). See #G_BYTE_ORDER.
4361 * The value of pi (ratio of circle's circumference to its diameter).
4381 * @notify: a #GDestroyNotify
4383 * A macro to assist with the static initialisation of a #GPrivate.
4385 * This macro is useful for the case that a #GDestroyNotify function
4386 * should be associated the key. This is needed when the key will be
4387 * used to point at memory that should be deallocated when the thread
4390 * Additionally, the #GDestroyNotify will also be called on the previous
4391 * value stored in the key when g_private_replace() is used.
4393 * If no #GDestroyNotify is needed, then use of this macro is not
4394 * required -- if the #GPrivate is declared in static scope then it will
4395 * be properly initialised by default (ie: to all zeros). See the
4398 * |[<!-- language="C" -->
4399 * static GPrivate name_key = G_PRIVATE_INIT (g_free);
4401 * // return value should not be freed
4403 * get_local_name (void)
4405 * return g_private_get (&name_key);
4409 * set_local_name (const gchar *name)
4411 * g_private_replace (&name_key, g_strdup (name));
4415 * static GPrivate count_key; // no free function
4418 * get_local_count (void)
4420 * return GPOINTER_TO_INT (g_private_get (&count_key));
4424 * set_local_count (gint count)
4426 * g_private_set (&count_key, GINT_TO_POINTER (count));
4435 * G_SEARCHPATH_SEPARATOR:
4437 * The search path separator character.
4438 * This is ':' on UNIX machines and ';' under Windows.
4443 * G_SEARCHPATH_SEPARATOR_S:
4445 * The search path separator as a string.
4446 * This is ":" on UNIX machines and ";" under Windows.
4453 * Error domain for shell functions. Errors in this domain will be from
4454 * the #GShellError enumeration. See #GError for information on error
4462 * The square root of two.
4468 * @expr: a constant expression
4470 * The G_STATIC_ASSERT() macro lets the programmer check
4471 * a condition at compile time, the condition needs to
4472 * be compile time computable. The macro can be used in
4473 * any place where a typedef is valid.
4475 * A typedef is generally allowed in exactly the same places that
4476 * a variable declaration is allowed. For this reason, you should
4477 * not use G_STATIC_ASSERT() in the middle of blocks of code.
4479 * The macro should only be used once per source code line.
4486 * G_STATIC_ASSERT_EXPR:
4487 * @expr: a constant expression
4489 * The G_STATIC_ASSERT_EXPR() macro lets the programmer check
4490 * a condition at compile time. The condition needs to be
4491 * compile time computable.
4493 * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression
4494 * and, as such, can be used in the middle of other expressions.
4495 * Its value should be ignored. This can be accomplished by placing
4496 * it as the first argument of a comma expression.
4498 * |[<!-- language="C" -->
4499 * #define ADD_ONE_TO_INT(x) \
4500 * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
4510 * Used within multi-statement macros so that they can be used in places
4511 * where only one statement is expected by the compiler.
4518 * Used within multi-statement macros so that they can be used in places
4519 * where only one statement is expected by the compiler.
4526 * Expands to a string identifying the current function.
4534 * @macro_or_string: a macro or a string
4536 * Accepts a macro or a string and converts it into a string after
4537 * preprocessor argument expansion. For example, the following code:
4539 * |[<!-- language="C" -->
4541 * const gchar *greeting = G_STRINGIFY (AGE) " today!";
4544 * is transformed by the preprocessor into (code equivalent to):
4546 * |[<!-- language="C" -->
4547 * const gchar *greeting = "27 today!";
4555 * Expands to a string identifying the current code position.
4561 * @member_type: the type of the struct field
4562 * @struct_p: a pointer to a struct
4563 * @struct_offset: the offset of the field from the start of the struct,
4566 * Returns a member of a structure at a given offset, using the given type.
4568 * Returns: the struct member
4573 * G_STRUCT_MEMBER_P:
4574 * @struct_p: a pointer to a struct
4575 * @struct_offset: the offset from the start of the struct, in bytes
4577 * Returns an untyped pointer to a given offset of a struct.
4579 * Returns: an untyped pointer to @struct_p plus @struct_offset bytes
4585 * @struct_type: a structure type, e.g. #GtkWidget
4586 * @member: a field in the structure, e.g. @window
4588 * Returns the offset, in bytes, of a member of a struct.
4590 * Returns: the offset of @member from the start of @struct_type
4597 * The standard delimiters, used in g_strdelimit().
4604 * The error domain of the GLib thread subsystem.
4610 * @name: the name of the lock
4612 * Works like g_mutex_trylock(), but for a lock defined with
4615 * Returns: %TRUE, if the lock could be locked.
4621 * @maj: the major version that introduced the symbol
4622 * @min: the minor version that introduced the symbol
4624 * This macro can be used to mark a function declaration as unavailable.
4625 * It must be placed before the function declaration. Use of a function
4626 * that has been annotated with this macros will produce a compiler warning.
4634 * @expr: the expression
4636 * Hints the compiler that the expression is unlikely to evaluate to
4637 * a true value. The compiler may use this information for optimizations.
4639 * |[<!-- language="C" -->
4640 * if (G_UNLIKELY (random () == 1))
4641 * g_print ("a random one");
4644 * Returns: the value of @expr
4651 * @name: the name of the lock
4653 * Works like g_mutex_unlock(), but for a lock defined with
4661 * Number of microseconds in one second (1 million).
4662 * This macro is provided for code readability.
4667 * G_VARIANT_PARSE_ERROR:
4669 * Error domain for GVariant text format parsing. Specific error codes
4670 * are not currently defined for this domain. See #GError for
4671 * information on error domains.
4677 * @ap1: the va_list variable to place a copy of @ap2 in
4680 * Portable way to copy va_list variables.
4682 * In order to use this function, you must include string.h yourself,
4683 * because this macro may use memmove() and GLib does not include
4689 * G_WIN32_DLLMAIN_FOR_DLL_NAME:
4690 * @static: empty or "static"
4691 * @dll_name: the name of the (pointer to the) char array where
4692 * the DLL name will be stored. If this is used, you must also
4693 * include `windows.h`. If you need a more complex DLL entry
4694 * point function, you cannot use this
4696 * On Windows, this macro defines a DllMain() function that stores
4697 * the actual DLL name that the code being compiled will be included in.
4699 * On non-Windows platforms, expands to nothing.
4704 * G_WIN32_HAVE_WIDECHAR_API:
4706 * On Windows, this macro defines an expression which evaluates to
4707 * %TRUE if the code is running on a version of Windows where the wide
4708 * character versions of the Win32 API functions, and the wide character
4709 * versions of the C library functions work. (They are always present in
4710 * the DLLs, but don't work on Windows 9x and Me.)
4712 * On non-Windows platforms, it is not defined.
4719 * G_WIN32_IS_NT_BASED:
4721 * On Windows, this macro defines an expression which evaluates to
4722 * %TRUE if the code is running on an NT-based Windows operating system.
4724 * On non-Windows platforms, it is not defined.
4732 * @a: a numeric value
4733 * @b: a numeric value
4735 * Calculates the maximum of @a and @b.
4737 * Returns: the maximum of @a and @b.
4744 * Provided for UNIX emulation on Windows; equivalent to UNIX
4745 * macro %MAXPATHLEN, which is the maximum length of a filename
4746 * (including full path).
4752 * @a: a numeric value
4753 * @b: a numeric value
4755 * Calculates the minimum of @a and @b.
4757 * Returns: the minimum of @a and @b.
4763 * @Context: a message context, must be a string literal
4764 * @String: a message id, must be a string literal
4766 * Only marks a string for translation, with context.
4767 * This is useful in situations where the translated strings can't
4768 * be directly used, e.g. in string array initializers. To get the
4769 * translated string, you should call g_dpgettext2() at runtime.
4771 * |[<!-- language="C" -->
4773 * static const char *messages[] = {
4774 * NC_("some context", "some very meaningful message"),
4775 * NC_("some context", "and another one")
4777 * const char *string;
4780 * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message")
4781 * : g_dpgettext2 (NULL, "some context", messages[index]);
4788 * If you are using the NC_() macro, you need to make sure that you pass
4789 * `--keyword=NC_:1c,2` to xgettext when extracting messages.
4790 * Note that this only works with GNU gettext >= 0.15. Intltool has support
4791 * for the NC_() macro since version 0.40.1.
4800 * Defines the standard %NULL pointer.
4806 * @String: the string to be translated
4808 * Only marks a string for translation. This is useful in situations
4809 * where the translated strings can't be directly used, e.g. in string
4810 * array initializers. To get the translated string, call gettext()
4812 * |[<!-- language="C" -->
4814 * static const char *messages[] = {
4815 * N_("some very meaningful message"),
4816 * N_("and another one")
4818 * const char *string;
4821 * = index > 1 ? _("a default message") : gettext (messages[index]);
4834 * @String: the string to be translated, with a '|'-separated prefix
4835 * which must not be translated
4837 * Like _(), but handles context in message ids. This has the advantage
4838 * that the string can be adorned with a prefix to guarantee uniqueness
4839 * and provide context to the translator.
4841 * One use case given in the gettext manual is GUI translation, where one
4842 * could e.g. disambiguate two "Open" menu entries as "File|Open" and
4843 * "Printer|Open". Another use case is the string "Russian" which may
4844 * have to be translated differently depending on whether it's the name
4845 * of a character set or a language. This could be solved by using
4846 * "charset|Russian" and "language|Russian".
4848 * See the C_() macro for a different way to mark up translatable strings
4851 * If you are using the Q_() macro, you need to make sure that you pass
4852 * `--keyword=Q_` to xgettext when extracting messages.
4853 * If you are using GNU gettext >= 0.15, you can also use
4854 * `--keyword=Q_:1g` to let xgettext split the context
4855 * string off into a msgctxt line in the po file.
4857 * Returns: the translated message
4865 * @short_description: arrays of arbitrary elements which grow
4866 * automatically as elements are added
4868 * Arrays are similar to standard C arrays, except that they grow
4869 * automatically as elements are added.
4871 * Array elements can be of any size (though all elements of one array
4872 * are the same size), and the array can be automatically cleared to
4873 * '0's and zero-terminated.
4875 * To create a new array use g_array_new().
4877 * To add elements to an array, use g_array_append_val(),
4878 * g_array_append_vals(), g_array_prepend_val(), and
4879 * g_array_prepend_vals().
4881 * To access an element of an array, use g_array_index().
4883 * To set the size of an array, use g_array_set_size().
4885 * To free an array, use g_array_free().
4887 * Here is an example that stores integers in a #GArray:
4888 * |[<!-- language="C" -->
4891 * // We create a new array to store gint values.
4892 * // We don't want it zero-terminated or cleared to 0's.
4893 * garray = g_array_new (FALSE, FALSE, sizeof (gint));
4894 * for (i = 0; i < 10000; i++)
4895 * g_array_append_val (garray, i);
4896 * for (i = 0; i < 10000; i++)
4897 * if (g_array_index (garray, gint, i) != i)
4898 * g_print ("ERROR: got %d instead of %d\n",
4899 * g_array_index (garray, gint, i), i);
4900 * g_array_free (garray, TRUE);
4906 * SECTION:arrays_byte
4907 * @title: Byte Arrays
4908 * @short_description: arrays of bytes
4910 * #GByteArray is a mutable array of bytes based on #GArray, to provide arrays
4911 * of bytes which grow automatically as elements are added.
4913 * To create a new #GByteArray use g_byte_array_new(). To add elements to a
4914 * #GByteArray, use g_byte_array_append(), and g_byte_array_prepend().
4916 * To set the size of a #GByteArray, use g_byte_array_set_size().
4918 * To free a #GByteArray, use g_byte_array_free().
4920 * An example for using a #GByteArray:
4921 * |[<!-- language="C" -->
4922 * GByteArray *gbarray;
4925 * gbarray = g_byte_array_new ();
4926 * for (i = 0; i < 10000; i++)
4927 * g_byte_array_append (gbarray, (guint8*) "abcd", 4);
4929 * for (i = 0; i < 10000; i++)
4931 * g_assert (gbarray->data[4*i] == 'a');
4932 * g_assert (gbarray->data[4*i+1] == 'b');
4933 * g_assert (gbarray->data[4*i+2] == 'c');
4934 * g_assert (gbarray->data[4*i+3] == 'd');
4937 * g_byte_array_free (gbarray, TRUE);
4940 * See #GBytes if you are interested in an immutable object representing a
4941 * sequence of bytes.
4946 * SECTION:arrays_pointer
4947 * @title: Pointer Arrays
4948 * @short_description: arrays of pointers to any type of data, which
4949 * grow automatically as new elements are added
4951 * Pointer Arrays are similar to Arrays but are used only for storing
4954 * If you remove elements from the array, elements at the end of the
4955 * array are moved into the space previously occupied by the removed
4956 * element. This means that you should not rely on the index of particular
4957 * elements remaining the same. You should also be careful when deleting
4958 * elements while iterating over the array.
4960 * To create a pointer array, use g_ptr_array_new().
4962 * To add elements to a pointer array, use g_ptr_array_add().
4964 * To remove elements from a pointer array, use g_ptr_array_remove(),
4965 * g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
4967 * To access an element of a pointer array, use g_ptr_array_index().
4969 * To set the size of a pointer array, use g_ptr_array_set_size().
4971 * To free a pointer array, use g_ptr_array_free().
4973 * An example using a #GPtrArray:
4974 * |[<!-- language="C" -->
4976 * gchar *string1 = "one", *string2 = "two", *string3 = "three";
4978 * gparray = g_ptr_array_new ();
4979 * g_ptr_array_add (array, (gpointer) string1);
4980 * g_ptr_array_add (array, (gpointer) string2);
4981 * g_ptr_array_add (array, (gpointer) string3);
4983 * if (g_ptr_array_index (array, 0) != (gpointer) string1)
4984 * g_print ("ERROR: got %p instead of %p\n",
4985 * g_ptr_array_index (array, 0), string1);
4987 * g_ptr_array_free (array, TRUE);
4993 * SECTION:async_queues
4994 * @title: Asynchronous Queues
4995 * @short_description: asynchronous communication between threads
4996 * @see_also: #GThreadPool
4998 * Often you need to communicate between different threads. In general
4999 * it's safer not to do this by shared memory, but by explicit message
5000 * passing. These messages only make sense asynchronously for
5001 * multi-threaded applications though, as a synchronous operation could
5002 * as well be done in the same thread.
5004 * Asynchronous queues are an exception from most other GLib data
5005 * structures, as they can be used simultaneously from multiple threads
5006 * without explicit locking and they bring their own builtin reference
5007 * counting. This is because the nature of an asynchronous queue is that
5008 * it will always be used by at least 2 concurrent threads.
5010 * For using an asynchronous queue you first have to create one with
5011 * g_async_queue_new(). #GAsyncQueue structs are reference counted,
5012 * use g_async_queue_ref() and g_async_queue_unref() to manage your
5015 * A thread which wants to send a message to that queue simply calls
5016 * g_async_queue_push() to push the message to the queue.
5018 * A thread which is expecting messages from an asynchronous queue
5019 * simply calls g_async_queue_pop() for that queue. If no message is
5020 * available in the queue at that point, the thread is now put to sleep
5021 * until a message arrives. The message will be removed from the queue
5022 * and returned. The functions g_async_queue_try_pop() and
5023 * g_async_queue_timeout_pop() can be used to only check for the presence
5024 * of messages or to only wait a certain time for messages respectively.
5026 * For almost every function there exist two variants, one that locks
5027 * the queue and one that doesn't. That way you can hold the queue lock
5028 * (acquire it with g_async_queue_lock() and release it with
5029 * g_async_queue_unlock()) over multiple queue accessing instructions.
5030 * This can be necessary to ensure the integrity of the queue, but should
5031 * only be used when really necessary, as it can make your life harder
5032 * if used unwisely. Normally you should only use the locking function
5033 * variants (those without the _unlocked suffix).
5035 * In many cases, it may be more convenient to use #GThreadPool when
5036 * you need to distribute work to a set of worker threads instead of
5037 * using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue
5043 * SECTION:atomic_operations
5044 * @title: Atomic Operations
5045 * @short_description: basic atomic integer and pointer operations
5046 * @see_also: #GMutex
5048 * The following is a collection of compiler macros to provide atomic
5049 * access to integer and pointer-sized values.
5051 * The macros that have 'int' in the name will operate on pointers to
5052 * #gint and #guint. The macros with 'pointer' in the name will operate
5053 * on pointers to any pointer-sized value, including #gsize. There is
5054 * no support for 64bit operations on platforms with 32bit pointers
5055 * because it is not generally possible to perform these operations
5058 * The get, set and exchange operations for integers and pointers
5059 * nominally operate on #gint and #gpointer, respectively. Of the
5060 * arithmetic operations, the 'add' operation operates on (and returns)
5061 * signed integer values (#gint and #gssize) and the 'and', 'or', and
5062 * 'xor' operations operate on (and return) unsigned integer values
5063 * (#guint and #gsize).
5065 * All of the operations act as a full compiler and (where appropriate)
5066 * hardware memory barrier. Acquire and release or producer and
5067 * consumer barrier semantics are not available through this API.
5069 * It is very important that all accesses to a particular integer or
5070 * pointer be performed using only this API and that different sizes of
5071 * operation are not mixed or used on overlapping memory regions. Never
5072 * read or assign directly from or to a value -- always use this API.
5074 * For simple reference counting purposes you should use
5075 * g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that
5076 * fall outside of simple reference counting patterns are prone to
5077 * subtle bugs and occasionally undefined behaviour. It is also worth
5078 * noting that since all of these operations require global
5079 * synchronisation of the entire machine, they can be quite slow. In * the case of performing multiple atomic operations it can often be
5080 * faster to simply acquire a mutex lock around the critical area,
5081 * perform the operations normally and then release the lock.
5087 * @title: Base64 Encoding
5088 * @short_description: encodes and decodes data in Base64 format
5090 * Base64 is an encoding that allows a sequence of arbitrary bytes to be
5091 * encoded as a sequence of printable ASCII characters. For the definition
5093 * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt)
5095 * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
5096 * Base64 is most commonly used as a MIME transfer encoding
5099 * GLib supports incremental encoding using g_base64_encode_step() and
5100 * g_base64_encode_close(). Incremental decoding can be done with
5101 * g_base64_decode_step(). To encode or decode data in one go, use
5102 * g_base64_encode() or g_base64_decode(). To avoid memory allocation when
5103 * decoding, you can use g_base64_decode_inplace().
5105 * Support for Base64 encoding has been added in GLib 2.12.
5110 * SECTION:bookmarkfile
5111 * @title: Bookmark file parser
5112 * @short_description: parses files containing bookmarks
5114 * GBookmarkFile lets you parse, edit or create files containing bookmarks
5115 * to URI, along with some meta-data about the resource pointed by the URI
5116 * like its MIME type, the application that is registering the bookmark and
5117 * the icon that should be used to represent the bookmark. The data is stored
5119 * [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec).
5121 * The syntax of the bookmark files is described in detail inside the
5122 * Desktop Bookmark Specification, here is a quick summary: bookmark
5123 * files use a sub-class of the XML Bookmark Exchange Language
5124 * specification, consisting of valid UTF-8 encoded XML, under the
5125 * <xbel> root element; each bookmark is stored inside a
5126 * <bookmark> element, using its URI: no relative paths can
5127 * be used inside a bookmark file. The bookmark may have a user defined
5128 * title and description, to be used instead of the URI. Under the
5129 * <metadata> element, with its owner attribute set to
5130 * `http://freedesktop.org`, is stored the meta-data about a resource
5131 * pointed by its URI. The meta-data consists of the resource's MIME
5132 * type; the applications that have registered a bookmark; the groups
5133 * to which a bookmark belongs to; a visibility flag, used to set the
5134 * bookmark as "private" to the applications and groups that has it
5135 * registered; the URI and MIME type of an icon, to be used when
5136 * displaying the bookmark inside a GUI.
5138 * Here is an example of a bookmark file:
5139 * [bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel)
5141 * A bookmark file might contain more than one bookmark; each bookmark
5142 * is accessed through its URI.
5144 * The important caveat of bookmark files is that when you add a new
5145 * bookmark you must also add the application that is registering it, using
5146 * g_bookmark_file_add_application() or g_bookmark_file_set_app_info().
5147 * If a bookmark has no applications then it won't be dumped when creating
5148 * the on disk representation, using g_bookmark_file_to_data() or
5149 * g_bookmark_file_to_file().
5151 * The #GBookmarkFile parser was added in GLib 2.12.
5156 * SECTION:byte_order
5157 * @title: Byte Order Macros
5158 * @short_description: a portable way to convert between different byte orders
5160 * These macros provide a portable way to determine the host byte order
5161 * and to convert values between different byte orders.
5163 * The byte order is the order in which bytes are stored to create larger
5164 * data types such as the #gint and #glong values.
5165 * The host byte order is the byte order used on the current machine.
5167 * Some processors store the most significant bytes (i.e. the bytes that
5168 * hold the largest part of the value) first. These are known as big-endian
5169 * processors. Other processors (notably the x86 family) store the most
5170 * significant byte last. These are known as little-endian processors.
5172 * Finally, to complicate matters, some other processors store the bytes in
5173 * a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
5174 * most significant byte is stored first, then the 4th, then the 1st and
5177 * Obviously there is a problem when these different processors communicate
5178 * with each other, for example over networks or by using binary file formats.
5179 * This is where these macros come in. They are typically used to convert
5180 * values into a byte order which has been agreed on for use when
5181 * communicating between different processors. The Internet uses what is
5182 * known as 'network byte order' as the standard byte order (which is in
5183 * fact the big-endian byte order).
5185 * Note that the byte order conversion macros may evaluate their arguments
5186 * multiple times, thus you should not use them with arguments which have
5193 * @title: Data Checksums
5194 * @short_description: computes the checksum for data
5196 * GLib provides a generic API for computing checksums (or "digests")
5197 * for a sequence of arbitrary bytes, using various hashing algorithms
5198 * like MD5, SHA-1 and SHA-256. Checksums are commonly used in various
5199 * environments and specifications.
5201 * GLib supports incremental checksums using the GChecksum data
5202 * structure, by calling g_checksum_update() as long as there's data
5203 * available and then using g_checksum_get_string() or
5204 * g_checksum_get_digest() to compute the checksum and return it either
5205 * as a string in hexadecimal form, or as a raw sequence of bytes. To
5206 * compute the checksum for binary blobs and NUL-terminated strings in
5207 * one go, use the convenience functions g_compute_checksum_for_data()
5208 * and g_compute_checksum_for_string(), respectively.
5210 * Support for checksums has been added in GLib 2.16
5215 * SECTION:conversions
5216 * @title: Character Set Conversion
5217 * @short_description: convert strings between different character sets
5219 * The g_convert() family of function wraps the functionality of iconv().
5220 * In addition to pure character set conversions, GLib has functions to
5221 * deal with the extra complications of encodings for file names.
5223 * ## File Name Encodings
5225 * Historically, UNIX has not had a defined encoding for file names:
5226 * a file name is valid as long as it does not have path separators
5227 * in it ("/"). However, displaying file names may require conversion:
5228 * from the character set in which they were created, to the character
5229 * set in which the application operates. Consider the Spanish file name
5230 * "Presentación.sxi". If the application which created it uses
5231 * ISO-8859-1 for its encoding,
5233 * Character: P r e s e n t a c i ó n . s x i
5234 * Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
5236 * However, if the application use UTF-8, the actual file name on
5237 * disk would look like this:
5239 * Character: P r e s e n t a c i ó n . s x i
5240 * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
5242 * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
5243 * Glib do the same thing. If you get a file name from the file system,
5244 * for example, from readdir() or from g_dir_read_name(), and you wish
5245 * to display the file name to the user, you will need to convert it
5246 * into UTF-8. The opposite case is when the user types the name of a
5247 * file he wishes to save: the toolkit will give you that string in
5248 * UTF-8 encoding, and you will need to convert it to the character
5249 * set used for file names before you can create the file with open()
5252 * By default, Glib assumes that file names on disk are in UTF-8
5253 * encoding. This is a valid assumption for file systems which
5254 * were created relatively recently: most applications use UTF-8
5255 * encoding for their strings, and that is also what they use for
5256 * the file names they create. However, older file systems may
5257 * still contain file names created in "older" encodings, such as
5258 * ISO-8859-1. In this case, for compatibility reasons, you may want
5259 * to instruct Glib to use that particular encoding for file names
5260 * rather than UTF-8. You can do this by specifying the encoding for
5261 * file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING]
5262 * environment variable. For example, if your installation uses
5263 * ISO-8859-1 for file names, you can put this in your `~/.profile`
5265 * export G_FILENAME_ENCODING=ISO-8859-1
5267 * Glib provides the functions g_filename_to_utf8() and
5268 * g_filename_from_utf8() to perform the necessary conversions.
5269 * These functions convert file names from the encoding specified
5270 * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This
5271 * [diagram][file-name-encodings-diagram] illustrates how
5272 * these functions are used to convert between UTF-8 and the
5273 * encoding for file names in the file system.
5275 * ## Conversion between file name encodings # {#file-name-encodings-diagram)
5277 * ![](file-name-encodings.png)
5279 * ## Checklist for Application Writers
5281 * This section is a practical summary of the detailed
5283 * things to do to make sure your applications process file
5284 * name encodings correctly.
5286 * 1. If you get a file name from the file system from a function
5287 * such as readdir() or gtk_file_chooser_get_filename(), you do
5288 * not need to do any conversion to pass that file name to
5289 * functions like open(), rename(), or fopen() -- those are "raw"
5290 * file names which the file system understands.
5292 * 2. If you need to display a file name, convert it to UTF-8 first
5293 * by using g_filename_to_utf8(). If conversion fails, display a
5294 * string like "Unknown file name". Do not convert this string back
5295 * into the encoding used for file names if you wish to pass it to
5296 * the file system; use the original file name instead.
5298 * For example, the document window of a word processor could display
5299 * "Unknown file name" in its title bar but still let the user save
5300 * the file, as it would keep the raw file name internally. This
5301 * can happen if the user has not set the `G_FILENAME_ENCODING`
5302 * environment variable even though he has files whose names are
5303 * not encoded in UTF-8.
5305 * 3. If your user interface lets the user type a file name for saving
5306 * or renaming, convert it to the encoding used for file names in
5307 * the file system by using g_filename_from_utf8(). Pass the converted
5308 * file name to functions like fopen(). If conversion fails, ask the
5309 * user to enter a different file name. This can happen if the user
5310 * types Japanese characters when `G_FILENAME_ENCODING` is set to
5311 * `ISO-8859-1`, for example.
5317 * @title: Keyed Data Lists
5318 * @short_description: lists of data elements which are accessible by a
5319 * string or GQuark identifier
5321 * Keyed data lists provide lists of arbitrary data elements which can
5322 * be accessed either with a string or with a #GQuark corresponding to
5325 * The #GQuark methods are quicker, since the strings have to be
5326 * converted to #GQuarks anyway.
5328 * Data lists are used for associating arbitrary data with #GObjects,
5329 * using g_object_set_data() and related functions.
5331 * To create a datalist, use g_datalist_init().
5333 * To add data elements to a datalist use g_datalist_id_set_data(),
5334 * g_datalist_id_set_data_full(), g_datalist_set_data() and
5335 * g_datalist_set_data_full().
5337 * To get data elements from a datalist use g_datalist_id_get_data()
5338 * and g_datalist_get_data().
5340 * To iterate over all data elements in a datalist use
5341 * g_datalist_foreach() (not thread-safe).
5343 * To remove data elements from a datalist use
5344 * g_datalist_id_remove_data() and g_datalist_remove_data().
5346 * To remove all data elements from a datalist, use g_datalist_clear().
5353 * @short_description: associate groups of data elements with
5354 * particular memory locations
5356 * Datasets associate groups of data elements with particular memory
5357 * locations. These are useful if you need to associate data with a
5358 * structure returned from an external library. Since you cannot modify
5359 * the structure, you use its location in memory as the key into a
5360 * dataset, where you can associate any number of data elements with it.
5362 * There are two forms of most of the dataset functions. The first form
5363 * uses strings to identify the data elements associated with a
5364 * location. The second form uses #GQuark identifiers, which are
5365 * created with a call to g_quark_from_string() or
5366 * g_quark_from_static_string(). The second form is quicker, since it
5367 * does not require looking up the string in the hash table of #GQuark
5370 * There is no function to create a dataset. It is automatically
5371 * created as soon as you add elements to it.
5373 * To add data elements to a dataset use g_dataset_id_set_data(),
5374 * g_dataset_id_set_data_full(), g_dataset_set_data() and
5375 * g_dataset_set_data_full().
5377 * To get data elements from a dataset use g_dataset_id_get_data() and
5378 * g_dataset_get_data().
5380 * To iterate over all data elements in a dataset use
5381 * g_dataset_foreach() (not thread-safe).
5383 * To remove data elements from a dataset use
5384 * g_dataset_id_remove_data() and g_dataset_remove_data().
5386 * To destroy a dataset, use g_dataset_destroy().
5392 * @title: Date and Time Functions
5393 * @short_description: calendrical calculations and miscellaneous time stuff
5395 * The #GDate data structure represents a day between January 1, Year 1,
5396 * and sometime a few thousand years in the future (right now it will go
5397 * to the year 65535 or so, but g_date_set_parse() only parses up to the
5398 * year 8000 or so - just count on "a few thousand"). #GDate is meant to
5399 * represent everyday dates, not astronomical dates or historical dates
5400 * or ISO timestamps or the like. It extrapolates the current Gregorian
5401 * calendar forward and backward in time; there is no attempt to change
5402 * the calendar to match time periods or locations. #GDate does not store
5403 * time information; it represents a day.
5405 * The #GDate implementation has several nice features; it is only a
5406 * 64-bit struct, so storing large numbers of dates is very efficient. It
5407 * can keep both a Julian and day-month-year representation of the date,
5408 * since some calculations are much easier with one representation or the
5409 * other. A Julian representation is simply a count of days since some
5410 * fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
5411 * ("Julian" dates in the #GDate API aren't really Julian dates in the
5412 * technical sense; technically, Julian dates count from the start of the
5413 * Julian period, Jan 1, 4713 BC).
5415 * #GDate is simple to use. First you need a "blank" date; you can get a
5416 * dynamically allocated date from g_date_new(), or you can declare an
5417 * automatic variable or array and initialize it to a sane state by
5418 * calling g_date_clear(). A cleared date is sane; it's safe to call
5419 * g_date_set_dmy() and the other mutator functions to initialize the
5420 * value of a cleared date. However, a cleared date is initially
5421 * invalid, meaning that it doesn't represent a day that exists.
5422 * It is undefined to call any of the date calculation routines on an
5423 * invalid date. If you obtain a date from a user or other
5424 * unpredictable source, you should check its validity with the
5425 * g_date_valid() predicate. g_date_valid() is also used to check for
5426 * errors with g_date_set_parse() and other functions that can
5427 * fail. Dates can be invalidated by calling g_date_clear() again.
5429 * It is very important to use the API to access the #GDate
5430 * struct. Often only the day-month-year or only the Julian
5431 * representation is valid. Sometimes neither is valid. Use the API.
5433 * GLib also features #GDateTime which represents a precise time.
5440 * @short_description: a structure representing Date and Time
5441 * @see_also: #GTimeZone
5443 * #GDateTime is a structure that combines a Gregorian date and time
5444 * into a single structure. It provides many conversion and methods to
5445 * manipulate dates and times. Time precision is provided down to
5446 * microseconds and the time can range (proleptically) from 0001-01-01
5447 * 00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX
5448 * time in the sense that it is oblivious to leap seconds.
5450 * #GDateTime is an immutable object; once it has been created it cannot
5451 * be modified further. All modifiers will create a new #GDateTime.
5452 * Nearly all such functions can fail due to the date or time going out
5453 * of range, in which case %NULL will be returned.
5455 * #GDateTime is reference counted: the reference count is increased by calling
5456 * g_date_time_ref() and decreased by calling g_date_time_unref(). When the
5457 * reference count drops to 0, the resources allocated by the #GDateTime
5458 * structure are released.
5460 * Many parts of the API may produce non-obvious results. As an
5461 * example, adding two months to January 31st will yield March 31st
5462 * whereas adding one month and then one month again will yield either
5463 * March 28th or March 29th. Also note that adding 24 hours is not
5464 * always the same as adding one day (since days containing daylight
5465 * savings time transitions are either 23 or 25 hours in length).
5467 * #GDateTime is available since GLib 2.26.
5472 * SECTION:error_reporting
5473 * @Title: Error Reporting
5474 * @Short_description: a system for reporting errors
5476 * GLib provides a standard method of reporting errors from a called
5477 * function to the calling code. (This is the same problem solved by
5478 * exceptions in other languages.) It's important to understand that
5479 * this method is both a data type (the #GError struct) and a set of
5480 * rules. If you use #GError incorrectly, then your code will not
5481 * properly interoperate with other code that uses #GError, and users
5482 * of your API will probably get confused.
5484 * First and foremost: #GError should only be used to report recoverable
5485 * runtime errors, never to report programming errors. If the programmer
5486 * has screwed up, then you should use g_warning(), g_return_if_fail(),
5487 * g_assert(), g_error(), or some similar facility. (Incidentally,
5488 * remember that the g_error() function should only be used for
5489 * programming errors, it should not be used to print any error
5490 * reportable via #GError.)
5492 * Examples of recoverable runtime errors are "file not found" or
5493 * "failed to parse input." Examples of programming errors are "NULL
5494 * passed to strcmp()" or "attempted to free the same pointer twice."
5495 * These two kinds of errors are fundamentally different: runtime errors
5496 * should be handled or reported to the user, programming errors should
5497 * be eliminated by fixing the bug in the program. This is why most
5498 * functions in GLib and GTK+ do not use the #GError facility.
5500 * Functions that can fail take a return location for a #GError as their
5501 * last argument. For example:
5502 * |[<!-- language="C" -->
5503 * gboolean g_file_get_contents (const gchar *filename,
5508 * If you pass a non-%NULL value for the `error` argument, it should
5509 * point to a location where an error can be placed. For example:
5510 * |[<!-- language="C" -->
5512 * GError *err = NULL;
5514 * g_file_get_contents ("foo.txt", &contents, NULL, &err);
5515 * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
5518 * // Report error to user, and free error
5519 * g_assert (contents == NULL);
5520 * fprintf (stderr, "Unable to read file: %s\n", err->message);
5521 * g_error_free (err);
5525 * // Use file contents
5526 * g_assert (contents != NULL);
5529 * Note that `err != NULL` in this example is a reliable indicator
5530 * of whether g_file_get_contents() failed. Additionally,
5531 * g_file_get_contents() returns a boolean which
5532 * indicates whether it was successful.
5534 * Because g_file_get_contents() returns %FALSE on failure, if you
5535 * are only interested in whether it failed and don't need to display
5536 * an error message, you can pass %NULL for the @error argument:
5537 * |[<!-- language="C" -->
5538 * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
5539 * // no error occurred
5546 * The #GError object contains three fields: @domain indicates the module
5547 * the error-reporting function is located in, @code indicates the specific
5548 * error that occurred, and @message is a user-readable error message with
5549 * as many details as possible. Several functions are provided to deal
5550 * with an error received from a called function: g_error_matches()
5551 * returns %TRUE if the error matches a given domain and code,
5552 * g_propagate_error() copies an error into an error location (so the
5553 * calling function will receive it), and g_clear_error() clears an
5554 * error location by freeing the error and resetting the location to
5555 * %NULL. To display an error to the user, simply display the @message,
5556 * perhaps along with additional context known only to the calling
5557 * function (the file being opened, or whatever - though in the
5558 * g_file_get_contents() case, the @message already contains a filename).
5560 * When implementing a function that can report errors, the basic
5561 * tool is g_set_error(). Typically, if a fatal error occurs you
5562 * want to g_set_error(), then return immediately. g_set_error()
5563 * does nothing if the error location passed to it is %NULL.
5564 * Here's an example:
5565 * |[<!-- language="C" -->
5567 * foo_open_file (GError **error)
5571 * fd = open ("file.txt", O_RDONLY);
5575 * g_set_error (error,
5576 * FOO_ERROR, // error domain
5577 * FOO_ERROR_BLAH, // error code
5578 * "Failed to open file: %s", // error message format string
5579 * g_strerror (errno));
5587 * Things are somewhat more complicated if you yourself call another
5588 * function that can report a #GError. If the sub-function indicates
5589 * fatal errors in some way other than reporting a #GError, such as
5590 * by returning %TRUE on success, you can simply do the following:
5591 * |[<!-- language="C" -->
5593 * my_function_that_can_fail (GError **err)
5595 * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
5597 * if (!sub_function_that_can_fail (err))
5599 * // assert that error was set by the sub-function
5600 * g_assert (err == NULL || *err != NULL);
5604 * // otherwise continue, no error occurred
5605 * g_assert (err == NULL || *err == NULL);
5609 * If the sub-function does not indicate errors other than by
5610 * reporting a #GError, you need to create a temporary #GError
5611 * since the passed-in one may be %NULL. g_propagate_error() is
5612 * intended for use in this case.
5613 * |[<!-- language="C" -->
5615 * my_function_that_can_fail (GError **err)
5617 * GError *tmp_error;
5619 * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
5622 * sub_function_that_can_fail (&tmp_error);
5624 * if (tmp_error != NULL)
5626 * // store tmp_error in err, if err != NULL,
5627 * // otherwise call g_error_free() on tmp_error
5628 * g_propagate_error (err, tmp_error);
5632 * // otherwise continue, no error occurred
5636 * Error pileups are always a bug. For example, this code is incorrect:
5637 * |[<!-- language="C" -->
5639 * my_function_that_can_fail (GError **err)
5641 * GError *tmp_error;
5643 * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
5646 * sub_function_that_can_fail (&tmp_error);
5647 * other_function_that_can_fail (&tmp_error);
5649 * if (tmp_error != NULL)
5651 * g_propagate_error (err, tmp_error);
5656 * @tmp_error should be checked immediately after sub_function_that_can_fail(),
5657 * and either cleared or propagated upward. The rule is: after each error,
5658 * you must either handle the error, or return it to the calling function.
5660 * Note that passing %NULL for the error location is the equivalent
5661 * of handling an error by always doing nothing about it. So the
5662 * following code is fine, assuming errors in sub_function_that_can_fail()
5663 * are not fatal to my_function_that_can_fail():
5664 * |[<!-- language="C" -->
5666 * my_function_that_can_fail (GError **err)
5668 * GError *tmp_error;
5670 * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
5672 * sub_function_that_can_fail (NULL); // ignore errors
5675 * other_function_that_can_fail (&tmp_error);
5677 * if (tmp_error != NULL)
5679 * g_propagate_error (err, tmp_error);
5685 * Note that passing %NULL for the error location ignores errors;
5686 * it's equivalent to
5687 * `try { sub_function_that_can_fail (); } catch (...) {}`
5688 * in C++. It does not mean to leave errors unhandled; it means
5689 * to handle them by doing nothing.
5691 * Error domains and codes are conventionally named as follows:
5693 * - The error domain is called <NAMESPACE>_<MODULE>_ERROR,
5694 * for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
5695 * |[<!-- language="C" -->
5696 * #define G_SPAWN_ERROR g_spawn_error_quark ()
5699 * g_spawn_error_quark (void)
5701 * return g_quark_from_static_string ("g-spawn-error-quark");
5705 * - The quark function for the error domain is called
5706 * <namespace>_<module>_error_quark,
5707 * for example g_spawn_error_quark() or g_thread_error_quark().
5709 * - The error codes are in an enumeration called
5710 * <Namespace><Module>Error;
5711 * for example, #GThreadError or #GSpawnError.
5713 * - Members of the error code enumeration are called
5714 * <NAMESPACE>_<MODULE>_ERROR_<CODE>,
5715 * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
5717 * - If there's a "generic" or "unknown" error code for unrecoverable
5718 * errors it doesn't make sense to distinguish with specific codes,
5719 * it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
5720 * for example %G_SPAWN_ERROR_FAILED.
5722 * Summary of rules for use of #GError:
5724 * - Do not report programming errors via #GError.
5726 * - The last argument of a function that returns an error should
5727 * be a location where a #GError can be placed (i.e. "#GError** error").
5728 * If #GError is used with varargs, the #GError** should be the last
5729 * argument before the "...".
5731 * - The caller may pass %NULL for the #GError** if they are not interested
5732 * in details of the exact error that occurred.
5734 * - If %NULL is passed for the #GError** argument, then errors should
5735 * not be returned to the caller, but your function should still
5736 * abort and return if an error occurs. That is, control flow should
5737 * not be affected by whether the caller wants to get a #GError.
5739 * - If a #GError is reported, then your function by definition had a
5740 * fatal failure and did not complete whatever it was supposed to do.
5741 * If the failure was not fatal, then you handled it and you should not
5742 * report it. If it was fatal, then you must report it and discontinue
5743 * whatever you were doing immediately.
5745 * - If a #GError is reported, out parameters are not guaranteed to
5746 * be set to any defined value.
5748 * - A #GError* must be initialized to %NULL before passing its address
5749 * to a function that can report errors.
5751 * - "Piling up" errors is always a bug. That is, if you assign a
5752 * new #GError to a #GError* that is non-%NULL, thus overwriting
5753 * the previous error, it indicates that you should have aborted
5754 * the operation instead of continuing. If you were able to continue,
5755 * you should have cleared the previous error with g_clear_error().
5756 * g_set_error() will complain if you pile up errors.
5758 * - By convention, if you return a boolean value indicating success
5759 * then %TRUE means success and %FALSE means failure.
5760 * <footnote><para>Avoid creating functions which have a boolean
5761 * return value and a GError parameter, but where the boolean does
5762 * something other than signal whether the GError is set. Among other
5763 * problems, it requires C callers to allocate a temporary error. Instead,
5764 * provide a "gboolean *" out parameter. There are functions in GLib
5765 * itself such as g_key_file_has_key() that are deprecated because of this.
5766 * </para></footnote>
5768 * returned, the error must be set to a non-%NULL value.
5769 * <footnote><para>One exception to this is that in situations that are
5770 * already considered to be undefined behaviour (such as when a
5771 * g_return_val_if_fail() check fails), the error need not be set.
5772 * Instead of checking separately whether the error is set, callers
5773 * should ensure that they do not provoke undefined behaviour, then
5774 * assume that the error will be set on failure.</para></footnote>
5776 * - A %NULL return value is also frequently used to mean that an error
5777 * occurred. You should make clear in your documentation whether %NULL
5778 * is a valid return value in non-error cases; if %NULL is a valid value,
5779 * then users must check whether an error was returned to see if the
5780 * function succeeded.
5782 * - When implementing a function that can report errors, you may want
5783 * to add a check at the top of your function that the error return
5784 * location is either %NULL or contains a %NULL error (e.g.
5785 * `g_return_if_fail (error == NULL || *error == NULL);`).
5791 * @title: File Utilities
5792 * @short_description: various file-related functions
5794 * There is a group of functions which wrap the common POSIX functions
5795 * dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(),
5796 * g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these
5797 * wrappers is to make it possible to handle file names with any Unicode
5798 * characters in them on Windows without having to use ifdefs and the
5799 * wide character API in the application code.
5801 * The pathname argument should be in the GLib file name encoding.
5802 * On POSIX this is the actual on-disk encoding which might correspond
5803 * to the locale settings of the process (or the `G_FILENAME_ENCODING`
5804 * environment variable), or not.
5806 * On Windows the GLib file name encoding is UTF-8. Note that the
5807 * Microsoft C library does not use UTF-8, but has separate APIs for
5808 * current system code page and wide characters (UTF-16). The GLib
5809 * wrappers call the wide character API if present (on modern Windows
5810 * systems), otherwise convert to/from the system code page.
5812 * Another group of functions allows to open and read directories
5813 * in the GLib file name encoding. These are g_dir_open(),
5814 * g_dir_read_name(), g_dir_rewind(), g_dir_close().
5819 * SECTION:ghostutils
5820 * @short_description: Internet hostname utilities
5822 * Functions for manipulating internet hostnames; in particular, for
5823 * converting between Unicode and ASCII-encoded forms of
5824 * Internationalized Domain Names (IDNs).
5827 * [Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt)
5828 * standards allow for the use
5829 * of Unicode domain names in applications, while providing
5830 * backward-compatibility with the old ASCII-only DNS, by defining an
5831 * ASCII-Compatible Encoding of any given Unicode name, which can be
5832 * used with non-IDN-aware applications and protocols. (For example,
5833 * "Παν語.org" maps to "xn--4wa8awb4637h.org".)
5839 * @title: Perl-compatible regular expressions
5840 * @short_description: matches strings against regular expressions
5841 * @see_also: [Regular expression syntax][glib-regex-syntax]
5843 * The g_regex_*() functions implement regular
5844 * expression pattern matching using syntax and semantics similar to
5845 * Perl regular expression.
5847 * Some functions accept a @start_position argument, setting it differs
5848 * from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL
5849 * in the case of a pattern that begins with any kind of lookbehind assertion.
5850 * For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
5851 * in the middle of words. ("\B" matches only if the current position in the
5852 * subject is not a word boundary.) When applied to the string "Mississipi"
5853 * from the fourth byte, namely "issipi", it does not match, because "\B" is
5854 * always false at the start of the subject, which is deemed to be a word
5855 * boundary. However, if the entire string is passed , but with
5856 * @start_position set to 4, it finds the second occurrence of "iss" because
5857 * it is able to look behind the starting point to discover that it is
5858 * preceded by a letter.
5860 * Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
5861 * to these functions must be encoded in UTF-8. The lengths and the positions
5862 * inside the strings are in bytes and not in characters, so, for instance,
5863 * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
5864 * single character. If you set #G_REGEX_RAW the strings can be non-valid
5865 * UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
5866 * bytes and two characters long.
5868 * When matching a pattern, "\n" matches only against a "\n" character in
5869 * the string, and "\r" matches only a "\r" character. To match any newline
5870 * sequence use "\R". This particular group matches either the two-character
5871 * sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
5872 * U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
5873 * CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
5874 * separator, U+2028), or PS (paragraph separator, U+2029).
5876 * The behaviour of the dot, circumflex, and dollar metacharacters are
5877 * affected by newline characters, the default is to recognize any newline
5878 * character (the same characters recognized by "\R"). This can be changed
5879 * with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF
5880 * compile options, and with #G_REGEX_MATCH_NEWLINE_ANY,
5881 * #G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and
5882 * #G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also
5883 * relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an
5884 * unescaped "#" outside a character class is encountered. This indicates
5885 * a comment that lasts until after the next newline.
5887 * When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern
5888 * matching is changed to be compatible with the way that regular expressions
5889 * work in JavaScript. More precisely, a lonely ']' character in the pattern
5890 * is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and
5891 * you must use the '\u' escape sequence with 4 hex digits to specify a unicode
5892 * codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by
5893 * the specified number of hex digits, they match 'x' and 'u' literally; also
5894 * '\U' always matches 'U' instead of being an error in the pattern. Finally,
5895 * pattern matching is modified so that back references to an unset subpattern
5896 * group produces a match with the empty string instead of an error. See
5897 * pcreapi(3) for more information.
5899 * Creating and manipulating the same #GRegex structure from different
5900 * threads is not a problem as #GRegex does not modify its internal
5901 * state between creation and destruction, on the other hand #GMatchInfo
5902 * is not threadsafe.
5904 * The regular expressions low-level functionalities are obtained through
5906 * [PCRE](http://www.pcre.org/)
5907 * library written by Philip Hazel.
5913 * @title: UNIX-specific utilities and integration
5914 * @short_description: pipes, signal handling
5915 * @include: glib-unix.h
5917 * Most of GLib is intended to be portable; in contrast, this set of
5918 * functions is designed for programs which explicitly target UNIX,
5919 * or are using it to build higher level abstractions which would be
5920 * conditionally compiled if the platform matches G_OS_UNIX.
5922 * To use these functions, you must explicitly include the
5923 * "glib-unix.h" header.
5929 * @title: URI Functions
5930 * @short_description: manipulating URIs
5932 * Functions for manipulating Universal Resource Identifiers (URIs) as
5934 * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt).
5935 * It is highly recommended that you have read and
5936 * understand RFC 3986 for understanding this API.
5943 * @short_description: strongly typed value datatype
5944 * @see_also: GVariantType
5946 * #GVariant is a variant datatype; it stores a value along with
5947 * information about the type of that value. The range of possible
5948 * values is determined by the type. The type system used by #GVariant
5951 * #GVariant instances always have a type and a value (which are given
5952 * at construction time). The type and value of a #GVariant instance
5953 * can never change other than by the #GVariant itself being
5954 * destroyed. A #GVariant cannot contain a pointer.
5956 * #GVariant is reference counted using g_variant_ref() and
5957 * g_variant_unref(). #GVariant also has floating reference counts --
5958 * see g_variant_ref_sink().
5960 * #GVariant is completely threadsafe. A #GVariant instance can be
5961 * concurrently accessed in any way from any number of threads without
5964 * #GVariant is heavily optimised for dealing with data in serialised
5965 * form. It works particularly well with data located in memory-mapped
5966 * files. It can perform nearly all deserialisation operations in a
5967 * small constant time, usually touching only a single memory page.
5968 * Serialised #GVariant data can also be sent over the network.
5970 * #GVariant is largely compatible with D-Bus. Almost all types of
5971 * #GVariant instances can be sent over D-Bus. See #GVariantType for
5972 * exceptions. (However, #GVariant's serialisation format is not the same
5973 * as the serialisation format of a D-Bus message body: use #GDBusMessage,
5974 * in the gio library, for those.)
5976 * For space-efficiency, the #GVariant serialisation format does not
5977 * automatically include the variant's type or endianness, which must
5978 * either be implied from context (such as knowledge that a particular
5979 * file format always contains a little-endian %G_VARIANT_TYPE_VARIANT)
5980 * or supplied out-of-band (for instance, a type and/or endianness
5981 * indicator could be placed at the beginning of a file, network message
5982 * or network stream).
5984 * A #GVariant's size is limited mainly by any lower level operating
5985 * system constraints, such as the number of bits in #gsize. For
5986 * example, it is reasonable to have a 2GB file mapped into memory
5987 * with #GMappedFile, and call g_variant_new_from_data() on it.
5989 * For convenience to C programmers, #GVariant features powerful
5990 * varargs-based value construction and destruction. This feature is
5991 * designed to be embedded in other libraries.
5993 * There is a Python-inspired text language for describing #GVariant
5994 * values. #GVariant includes a printer for this language and a parser
5995 * with type inferencing.
5999 * #GVariant tries to be quite efficient with respect to memory use.
6000 * This section gives a rough idea of how much memory is used by the
6001 * current implementation. The information here is subject to change
6004 * The memory allocated by #GVariant can be grouped into 4 broad
6005 * purposes: memory for serialised data, memory for the type
6006 * information cache, buffer management memory and memory for the
6007 * #GVariant structure itself.
6009 * ## Serialised Data Memory
6011 * This is the memory that is used for storing GVariant data in
6012 * serialised form. This is what would be sent over the network or
6013 * what would end up on disk.
6015 * The amount of memory required to store a boolean is 1 byte. 16,
6016 * 32 and 64 bit integers and double precision floating point numbers
6017 * use their "natural" size. Strings (including object path and
6018 * signature strings) are stored with a nul terminator, and as such
6019 * use the length of the string plus 1 byte.
6021 * Maybe types use no space at all to represent the null value and
6022 * use the same amount of space (sometimes plus one byte) as the
6023 * equivalent non-maybe-typed value to represent the non-null case.
6025 * Arrays use the amount of space required to store each of their
6026 * members, concatenated. Additionally, if the items stored in an
6027 * array are not of a fixed-size (ie: strings, other arrays, etc)
6028 * then an additional framing offset is stored for each item. The
6029 * size of this offset is either 1, 2 or 4 bytes depending on the
6030 * overall size of the container. Additionally, extra padding bytes
6031 * are added as required for alignment of child values.
6033 * Tuples (including dictionary entries) use the amount of space
6034 * required to store each of their members, concatenated, plus one
6035 * framing offset (as per arrays) for each non-fixed-sized item in
6036 * the tuple, except for the last one. Additionally, extra padding
6037 * bytes are added as required for alignment of child values.
6039 * Variants use the same amount of space as the item inside of the
6040 * variant, plus 1 byte, plus the length of the type string for the
6041 * item inside the variant.
6043 * As an example, consider a dictionary mapping strings to variants.
6044 * In the case that the dictionary is empty, 0 bytes are required for
6045 * the serialisation.
6047 * If we add an item "width" that maps to the int32 value of 500 then
6048 * we will use 4 byte to store the int32 (so 6 for the variant
6049 * containing it) and 6 bytes for the string. The variant must be
6050 * aligned to 8 after the 6 bytes of the string, so that's 2 extra
6051 * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
6052 * for the dictionary entry. An additional 1 byte is added to the
6053 * array as a framing offset making a total of 15 bytes.
6055 * If we add another entry, "title" that maps to a nullable string
6056 * that happens to have a value of null, then we use 0 bytes for the
6057 * null value (and 3 bytes for the variant to contain it along with
6058 * its type string) plus 6 bytes for the string. Again, we need 2
6059 * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
6061 * We now require extra padding between the two items in the array.
6062 * After the 14 bytes of the first item, that's 2 bytes required.
6063 * We now require 2 framing offsets for an extra two
6064 * bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item
6067 * ## Type Information Cache
6069 * For each GVariant type that currently exists in the program a type
6070 * information structure is kept in the type information cache. The
6071 * type information structure is required for rapid deserialisation.
6073 * Continuing with the above example, if a #GVariant exists with the
6074 * type "a{sv}" then a type information struct will exist for
6075 * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
6076 * will share the same type information. Additionally, all
6077 * single-digit types are stored in read-only static memory and do
6078 * not contribute to the writable memory footprint of a program using
6081 * Aside from the type information structures stored in read-only
6082 * memory, there are two forms of type information. One is used for
6083 * container types where there is a single element type: arrays and
6084 * maybe types. The other is used for container types where there
6085 * are multiple element types: tuples and dictionary entries.
6087 * Array type info structures are 6 * sizeof (void *), plus the
6088 * memory required to store the type string itself. This means that
6089 * on 32-bit systems, the cache entry for "a{sv}" would require 30
6090 * bytes of memory (plus malloc overhead).
6092 * Tuple type info structures are 6 * sizeof (void *), plus 4 *
6093 * sizeof (void *) for each item in the tuple, plus the memory
6094 * required to store the type string itself. A 2-item tuple, for
6095 * example, would have a type information structure that consumed
6096 * writable memory in the size of 14 * sizeof (void *) (plus type
6097 * string) This means that on 32-bit systems, the cache entry for
6098 * "{sv}" would require 61 bytes of memory (plus malloc overhead).
6100 * This means that in total, for our "a{sv}" example, 91 bytes of
6101 * type information would be allocated.
6103 * The type information cache, additionally, uses a #GHashTable to
6104 * store and lookup the cached items and stores a pointer to this
6105 * hash table in static storage. The hash table is freed when there
6106 * are zero items in the type cache.
6108 * Although these sizes may seem large it is important to remember
6109 * that a program will probably only have a very small number of
6110 * different types of values in it and that only one type information
6111 * structure is required for many different values of the same type.
6113 * ## Buffer Management Memory
6115 * #GVariant uses an internal buffer management structure to deal
6116 * with the various different possible sources of serialised data
6117 * that it uses. The buffer is responsible for ensuring that the
6118 * correct call is made when the data is no longer in use by
6119 * #GVariant. This may involve a g_free() or a g_slice_free() or
6120 * even g_mapped_file_unref().
6122 * One buffer management structure is used for each chunk of
6123 * serialised data. The size of the buffer management structure
6124 * is 4 * (void *). On 32-bit systems, that's 16 bytes.
6126 * ## GVariant structure
6128 * The size of a #GVariant structure is 6 * (void *). On 32-bit
6129 * systems, that's 24 bytes.
6131 * #GVariant structures only exist if they are explicitly created
6132 * with API calls. For example, if a #GVariant is constructed out of
6133 * serialised data for the example given above (with the dictionary)
6134 * then although there are 9 individual values that comprise the
6135 * entire dictionary (two keys, two values, two variants containing
6136 * the values, two dictionary entries, plus the dictionary itself),
6137 * only 1 #GVariant instance exists -- the one referring to the
6140 * If calls are made to start accessing the other values then
6141 * #GVariant instances will exist for those values only for as long
6142 * as they are in use (ie: until you call g_variant_unref()). The
6143 * type information is shared. The serialised data and the buffer
6144 * management structure for that serialised data is shared by the
6149 * To put the entire example together, for our dictionary mapping
6150 * strings to variants (with two entries, as given above), we are
6151 * using 91 bytes of memory for type information, 29 byes of memory
6152 * for the serialised data, 16 bytes for buffer management and 24
6153 * bytes for the #GVariant instance, or a total of 160 bytes, plus
6154 * malloc overhead. If we were to use g_variant_get_child_value() to
6155 * access the two dictionary entries, we would use an additional 48
6156 * bytes. If we were to have other dictionaries of the same type, we
6157 * would use more memory for the serialised data and buffer
6158 * management for those dictionaries, but the type information would
6164 * SECTION:gvarianttype
6165 * @title: GVariantType
6166 * @short_description: introduction to the GVariant type system
6167 * @see_also: #GVariantType, #GVariant
6169 * This section introduces the GVariant type system. It is based, in
6170 * large part, on the D-Bus type system, with two major changes and
6171 * some minor lifting of restrictions. The
6172 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
6173 * therefore, provides a significant amount of
6174 * information that is useful when working with GVariant.
6176 * The first major change with respect to the D-Bus type system is the
6177 * introduction of maybe (or "nullable") types. Any type in GVariant can be
6178 * converted to a maybe type, in which case, "nothing" (or "null") becomes a
6179 * valid value. Maybe types have been added by introducing the
6180 * character "m" to type strings.
6182 * The second major change is that the GVariant type system supports the
6183 * concept of "indefinite types" -- types that are less specific than
6184 * the normal types found in D-Bus. For example, it is possible to speak
6185 * of "an array of any type" in GVariant, where the D-Bus type system
6186 * would require you to speak of "an array of integers" or "an array of
6187 * strings". Indefinite types have been added by introducing the
6188 * characters "*", "?" and "r" to type strings.
6190 * Finally, all arbitrary restrictions relating to the complexity of
6191 * types are lifted along with the restriction that dictionary entries
6192 * may only appear nested inside of arrays.
6194 * Just as in D-Bus, GVariant types are described with strings ("type
6195 * strings"). Subject to the differences mentioned above, these strings
6196 * are of the same form as those found in DBus. Note, however: D-Bus
6197 * always works in terms of messages and therefore individual type
6198 * strings appear nowhere in its interface. Instead, "signatures"
6199 * are a concatenation of the strings of the type of each argument in a
6200 * message. GVariant deals with single values directly so GVariant type
6201 * strings always describe the type of exactly one value. This means
6202 * that a D-Bus signature string is generally not a valid GVariant type
6203 * string -- except in the case that it is the signature of a message
6204 * containing exactly one argument.
6206 * An indefinite type is similar in spirit to what may be called an
6207 * abstract type in other type systems. No value can exist that has an
6208 * indefinite type as its type, but values can exist that have types
6209 * that are subtypes of indefinite types. That is to say,
6210 * g_variant_get_type() will never return an indefinite type, but
6211 * calling g_variant_is_of_type() with an indefinite type may return
6212 * %TRUE. For example, you cannot have a value that represents "an
6213 * array of no particular type", but you can have an "array of integers"
6214 * which certainly matches the type of "an array of no particular type",
6215 * since "array of integers" is a subtype of "array of no particular
6218 * This is similar to how instances of abstract classes may not
6219 * directly exist in other type systems, but instances of their
6220 * non-abstract subtypes may. For example, in GTK, no object that has
6221 * the type of #GtkBin can exist (since #GtkBin is an abstract class),
6222 * but a #GtkWindow can certainly be instantiated, and you would say
6223 * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
6226 * ## GVariant Type Strings
6228 * A GVariant type string can be any of the following:
6230 * - any basic type string (listed below)
6234 * - one of the characters 'a' or 'm', followed by another type string
6236 * - the character '(', followed by a concatenation of zero or more other
6237 * type strings, followed by the character ')'
6239 * - the character '{', followed by a basic type string (see below),
6240 * followed by another type string, followed by the character '}'
6242 * A basic type string describes a basic type (as per
6243 * g_variant_type_is_basic()) and is always a single character in length.
6244 * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
6245 * "h", "d", "s", "o", "g" and "?".
6247 * The above definition is recursive to arbitrary depth. "aaaaai" and
6248 * "(ui(nq((y)))s)" are both valid type strings, as is
6249 * "a(aa(ui)(qna{ya(yd)}))".
6251 * The meaning of each of the characters is as follows:
6252 * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
6253 * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte.
6254 * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer.
6255 * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer.
6256 * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer.
6257 * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer.
6258 * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer.
6259 * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer.
6260 * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value
6261 * that, by convention, is used as an index into an array of file
6262 * descriptors that are sent alongside a D-Bus message.
6263 * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
6264 * floating point value.
6265 * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string.
6266 * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form
6267 * of a D-Bus object path.
6268 * - `g`: the type string of %G_VARIANT_TYPE_STRING; a string in the form of
6269 * a D-Bus type signature.
6270 * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that
6271 * is a supertype of any of the basic types.
6272 * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that
6273 * contain any other type of value.
6274 * - `a`: used as a prefix on another type string to mean an array of that
6275 * type; the type string "ai", for example, is the type of an array of
6276 * signed 32-bit integers.
6277 * - `m`: used as a prefix on another type string to mean a "maybe", or
6278 * "nullable", version of that type; the type string "ms", for example,
6279 * is the type of a value that maybe contains a string, or maybe contains
6281 * - `()`: used to enclose zero or more other concatenated type strings to
6282 * create a tuple type; the type string "(is)", for example, is the type of
6283 * a pair of an integer and a string.
6284 * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is
6285 * a supertype of any tuple type, regardless of the number of items.
6286 * - `{}`: used to enclose a basic type string concatenated with another type
6287 * string to create a dictionary entry type, which usually appears inside of
6288 * an array to form a dictionary; the type string "a{sd}", for example, is
6289 * the type of a dictionary that maps strings to double precision floating
6292 * The first type (the basic type) is the key type and the second type is
6293 * the value type. The reason that the first type is restricted to being a
6294 * basic type is so that it can easily be hashed.
6295 * - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is
6296 * a supertype of all types. Note that, as with all type strings, this
6297 * character represents exactly one type. It cannot be used inside of tuples
6298 * to mean "any number of items".
6300 * Any type string of a container that contains an indefinite type is,
6301 * itself, an indefinite type. For example, the type string "a*"
6302 * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
6303 * that is a supertype of every array type. "(*s)" is a supertype
6304 * of all tuples that contain exactly two items where the second
6307 * "a{?*}" is an indefinite type that is a supertype of all arrays
6308 * containing dictionary entries where the key is any basic type and
6309 * the value is any type at all. This is, by definition, a dictionary,
6310 * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
6311 * that, due to the restriction that the key of a dictionary entry must
6312 * be a basic type, "{**}" is not a valid type string.
6317 * SECTION:hash_tables
6318 * @title: Hash Tables
6319 * @short_description: associations between keys and values so that
6320 * given a key the value can be found quickly
6322 * A #GHashTable provides associations between keys and values which is
6323 * optimized so that given a key, the associated value can be found
6326 * Note that neither keys nor values are copied when inserted into the
6327 * #GHashTable, so they must exist for the lifetime of the #GHashTable.
6328 * This means that the use of static strings is OK, but temporary
6329 * strings (i.e. those created in buffers and those returned by GTK+
6330 * widgets) should be copied with g_strdup() before being inserted.
6332 * If keys or values are dynamically allocated, you must be careful to
6333 * ensure that they are freed when they are removed from the
6334 * #GHashTable, and also when they are overwritten by new insertions
6335 * into the #GHashTable. It is also not advisable to mix static strings
6336 * and dynamically-allocated strings in a #GHashTable, because it then
6337 * becomes difficult to determine whether the string should be freed.
6339 * To create a #GHashTable, use g_hash_table_new().
6341 * To insert a key and value into a #GHashTable, use
6342 * g_hash_table_insert().
6344 * To lookup a value corresponding to a given key, use
6345 * g_hash_table_lookup() and g_hash_table_lookup_extended().
6347 * g_hash_table_lookup_extended() can also be used to simply
6348 * check if a key is present in the hash table.
6350 * To remove a key and value, use g_hash_table_remove().
6352 * To call a function for each key and value pair use
6353 * g_hash_table_foreach() or use a iterator to iterate over the
6354 * key/value pairs in the hash table, see #GHashTableIter.
6356 * To destroy a #GHashTable use g_hash_table_destroy().
6358 * A common use-case for hash tables is to store information about a
6359 * set of keys, without associating any particular value with each
6360 * key. GHashTable optimizes one way of doing so: If you store only
6361 * key-value pairs where key == value, then GHashTable does not
6362 * allocate memory to store the values, which can be a considerable
6363 * space saving, if your set is large. The functions
6364 * g_hash_table_add() and g_hash_table_contains() are designed to be
6365 * used when using #GHashTable this way.
6371 * @title: Secure HMAC Digests
6372 * @short_description: computes the HMAC for data
6374 * HMACs should be used when producing a cookie or hash based on data
6375 * and a key. Simple mechanisms for using SHA1 and other algorithms to
6376 * digest a key and data together are vulnerable to various security
6378 * [HMAC](http://en.wikipedia.org/wiki/HMAC)
6379 * uses algorithms like SHA1 in a secure way to produce a digest of a
6382 * Both the key and data are arbitrary byte arrays of bytes or characters.
6384 * Support for HMAC Digests has been added in GLib 2.30.
6390 * @title: Hook Functions
6391 * @short_description: support for manipulating lists of hook functions
6393 * The #GHookList, #GHook and their related functions provide support for
6394 * lists of hook functions. Functions can be added and removed from the lists,
6395 * and the list of hook functions can be invoked.
6401 * @title: Internationalization
6402 * @short_description: gettext support macros
6403 * @see_also: the gettext manual
6405 * GLib doesn't force any particular localization method upon its users.
6406 * But since GLib itself is localized using the gettext() mechanism, it seems
6407 * natural to offer the de-facto standard gettext() support macros in an
6410 * In order to use these macros in an application, you must include
6411 * `<glib/gi18n.h>`. For use in a library, you must include
6412 * `<glib/gi18n-lib.h>`
6413 * after defining the %GETTEXT_PACKAGE macro suitably for your library:
6414 * |[<!-- language="C" -->
6415 * #define GETTEXT_PACKAGE "gtk20"
6416 * #include <glib/gi18n-lib.h>
6418 * For an application, note that you also have to call bindtextdomain(),
6419 * bind_textdomain_codeset(), textdomain() and setlocale() early on in your
6420 * main() to make gettext() work.
6422 * For a library, you only have to call bindtextdomain() and
6423 * bind_textdomain_codeset() in your initialization function. If your library
6424 * doesn't have an initialization function, you can call the functions before
6425 * the first translated message.
6427 * The gettext manual covers details of how to set up message extraction
6433 * SECTION:iochannels
6434 * @title: IO Channels
6435 * @short_description: portable support for using files, pipes and sockets
6436 * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(),
6439 * The #GIOChannel data type aims to provide a portable method for
6440 * using file descriptors, pipes, and sockets, and integrating them
6441 * into the [main event loop][glib-The-Main-Event-Loop]. Currently,
6442 * full support is available on UNIX platforms, support for Windows
6443 * is only partially complete.
6445 * To create a new #GIOChannel on UNIX systems use
6446 * g_io_channel_unix_new(). This works for plain file descriptors,
6447 * pipes and sockets. Alternatively, a channel can be created for a
6448 * file in a system independent manner using g_io_channel_new_file().
6450 * Once a #GIOChannel has been created, it can be used in a generic
6451 * manner with the functions g_io_channel_read_chars(),
6452 * g_io_channel_write_chars(), g_io_channel_seek_position(), and
6453 * g_io_channel_shutdown().
6455 * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop],
6456 * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which
6457 * events you are interested in on the #GIOChannel, and provide a
6458 * function to be called whenever these events occur.
6460 * #GIOChannel instances are created with an initial reference count of
6461 * 1. g_io_channel_ref() and g_io_channel_unref() can be used to
6462 * increment or decrement the reference count respectively. When the
6463 * reference count falls to 0, the #GIOChannel is freed. (Though it
6464 * isn't closed automatically, unless it was created using
6465 * g_io_channel_new_file().) Using g_io_add_watch() or
6466 * g_io_add_watch_full() increments a channel's reference count.
6468 * The new functions g_io_channel_read_chars(),
6469 * g_io_channel_read_line(), g_io_channel_read_line_string(),
6470 * g_io_channel_read_to_end(), g_io_channel_write_chars(),
6471 * g_io_channel_seek_position(), and g_io_channel_flush() should not be
6472 * mixed with the deprecated functions g_io_channel_read(),
6473 * g_io_channel_write(), and g_io_channel_seek() on the same channel.
6479 * @title: Key-value file parser
6480 * @short_description: parses .ini-like config files
6482 * #GKeyFile lets you parse, edit or create files containing groups of
6483 * key-value pairs, which we call "key files" for lack of a better name.
6484 * Several freedesktop.org specifications use key files now, e.g the
6485 * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
6487 * [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).
6489 * The syntax of key files is described in detail in the
6490 * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
6491 * here is a quick summary: Key files
6492 * consists of groups of key-value pairs, interspersed with comments.
6495 * # this is just an example
6496 * # there can be comments before the first group
6500 * Name=Key File Example\tthis value shows\nescaping
6502 * # localized strings are stored in multiple key-value pairs
6505 * Welcome[fr_FR]=Bonjour
6507 * Welcome[be@latin]=Hello
6511 * Numbers=2;20;-200;0
6513 * Booleans=true;false;true;true
6516 * Lines beginning with a '#' and blank lines are considered comments.
6518 * Groups are started by a header line containing the group name enclosed
6519 * in '[' and ']', and ended implicitly by the start of the next group or
6520 * the end of the file. Each key-value pair must be contained in a group.
6522 * Key-value pairs generally have the form `key=value`, with the
6523 * exception of localized strings, which have the form
6524 * `key[locale]=value`, with a locale identifier of the
6525 * form `lang_COUNTRY\@MODIFIER` where `COUNTRY` and `MODIFIER`
6527 * Space before and after the '=' character are ignored. Newline, tab,
6528 * carriage return and backslash characters in value are escaped as \n,
6529 * \t, \r, and \\, respectively. To preserve leading spaces in values,
6530 * these can also be escaped as \s.
6532 * Key files can store strings (possibly with localized variants), integers,
6533 * booleans and lists of these. Lists are separated by a separator character,
6534 * typically ';' or ','. To use the list separator character in a value in
6535 * a list, it has to be escaped by prefixing it with a backslash.
6537 * This syntax is obviously inspired by the .ini files commonly met
6538 * on Windows, but there are some important differences:
6540 * - .ini files use the ';' character to begin comments,
6541 * key files use the '#' character.
6543 * - Key files do not allow for ungrouped keys meaning only
6544 * comments can precede the first group.
6546 * - Key files are always encoded in UTF-8.
6548 * - Key and Group names are case-sensitive. For example, a group called
6549 * [GROUP] is a different from [group].
6551 * - .ini files don't have a strongly typed boolean entry type,
6552 * they only have GetProfileInt(). In key files, only
6553 * true and false (in lower case) are allowed.
6555 * Note that in contrast to the
6556 * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
6557 * groups in key files may contain the same
6558 * key multiple times; the last entry wins. Key files may also contain
6559 * multiple groups with the same name; they are merged together.
6560 * Another difference is that keys and group names in key files are not
6561 * restricted to ASCII characters.
6566 * SECTION:linked_lists_double
6567 * @title: Doubly-Linked Lists
6568 * @short_description: linked lists that can be iterated over in both directions
6570 * The #GList structure and its associated functions provide a standard
6571 * doubly-linked list data structure.
6573 * Each element in the list contains a piece of data, together with
6574 * pointers which link to the previous and next elements in the list.
6575 * Using these pointers it is possible to move through the list in both
6576 * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists],
6577 * which only allows movement through the list in the forward direction).
6579 * The double linked list does not keep track of the number of items
6580 * and does not keep track of both the start and end of the list. If
6581 * you want fast access to both the start and the end of the list,
6582 * and/or the number of items in the list, use a
6583 * [GQueue][glib-Double-ended-Queues] instead.
6585 * The data contained in each element can be either integer values, by
6586 * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
6587 * or simply pointers to any type of data.
6589 * List elements are allocated from the [slice allocator][glib-Memory-Slices],
6590 * which is more efficient than allocating elements individually.
6592 * Note that most of the #GList functions expect to be passed a pointer
6593 * to the first element in the list. The functions which insert
6594 * elements return the new start of the list, which may have changed.
6596 * There is no function to create a #GList. %NULL is considered to be
6597 * a valid, empty list so you simply set a #GList* to %NULL to initialize
6600 * To add elements, use g_list_append(), g_list_prepend(),
6601 * g_list_insert() and g_list_insert_sorted().
6603 * To visit all elements in the list, use a loop over the list:
6604 * |[<!-- language="C" -->
6606 * for (l = list; l != NULL; l = l->next)
6608 * // do something with l->data
6612 * To call a function for each element in the list, use g_list_foreach().
6614 * To loop over the list and modify it (e.g. remove a certain element)
6615 * a while loop is more appropriate, for example:
6616 * |[<!-- language="C" -->
6620 * GList *next = l->next;
6621 * if (should_be_removed (l))
6623 * // possibly free l->data
6624 * list = g_list_delete_link (list, l);
6630 * To remove elements, use g_list_remove().
6632 * To navigate in a list, use g_list_first(), g_list_last(),
6633 * g_list_next(), g_list_previous().
6635 * To find elements in the list use g_list_nth(), g_list_nth_data(),
6636 * g_list_find() and g_list_find_custom().
6638 * To find the index of an element use g_list_position() and
6641 * To free the entire list, use g_list_free() or g_list_free_full().
6646 * SECTION:linked_lists_single
6647 * @title: Singly-Linked Lists
6648 * @short_description: linked lists that can be iterated in one direction
6650 * The #GSList structure and its associated functions provide a
6651 * standard singly-linked list data structure.
6653 * Each element in the list contains a piece of data, together with a
6654 * pointer which links to the next element in the list. Using this
6655 * pointer it is possible to move through the list in one direction
6656 * only (unlike the [double-linked lists][glib-Doubly-Linked-Lists],
6657 * which allow movement in both directions).
6659 * The data contained in each element can be either integer values, by
6660 * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
6661 * or simply pointers to any type of data.
6663 * List elements are allocated from the [slice allocator][glib-Memory-Slices],
6664 * which is more efficient than allocating elements individually.
6666 * Note that most of the #GSList functions expect to be passed a
6667 * pointer to the first element in the list. The functions which insert
6668 * elements return the new start of the list, which may have changed.
6670 * There is no function to create a #GSList. %NULL is considered to be
6671 * the empty list so you simply set a #GSList* to %NULL.
6673 * To add elements, use g_slist_append(), g_slist_prepend(),
6674 * g_slist_insert() and g_slist_insert_sorted().
6676 * To remove elements, use g_slist_remove().
6678 * To find elements in the list use g_slist_last(), g_slist_next(),
6679 * g_slist_nth(), g_slist_nth_data(), g_slist_find() and
6680 * g_slist_find_custom().
6682 * To find the index of an element use g_slist_position() and
6685 * To call a function for each element in the list use
6686 * g_slist_foreach().
6688 * To free the entire list, use g_slist_free().
6694 * @title: Standard Macros
6695 * @short_description: commonly-used macros
6697 * These macros provide a few commonly-used features.
6702 * SECTION:macros_misc
6703 * @title: Miscellaneous Macros
6704 * @short_description: specialized macros which are not used often
6706 * These macros provide more specialized features which are not
6707 * needed so often by application programmers.
6713 * @title: The Main Event Loop
6714 * @short_description: manages all available sources of events
6716 * The main event loop manages all the available sources of events for
6717 * GLib and GTK+ applications. These events can come from any number of
6718 * different types of sources such as file descriptors (plain files,
6719 * pipes or sockets) and timeouts. New types of event sources can also
6720 * be added using g_source_attach().
6722 * To allow multiple independent sets of sources to be handled in
6723 * different threads, each source is associated with a #GMainContext.
6724 * A GMainContext can only be running in a single thread, but
6725 * sources can be added to it and removed from it from other threads.
6727 * Each event source is assigned a priority. The default priority,
6728 * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
6729 * Values greater than 0 denote lower priorities. Events from high priority
6730 * sources are always processed before events from lower priority sources.
6732 * Idle functions can also be added, and assigned a priority. These will
6733 * be run whenever no events with a higher priority are ready to be processed.
6735 * The #GMainLoop data type represents a main event loop. A GMainLoop is
6736 * created with g_main_loop_new(). After adding the initial event sources,
6737 * g_main_loop_run() is called. This continuously checks for new events from
6738 * each of the event sources and dispatches them. Finally, the processing of
6739 * an event from one of the sources leads to a call to g_main_loop_quit() to
6740 * exit the main loop, and g_main_loop_run() returns.
6742 * It is possible to create new instances of #GMainLoop recursively.
6743 * This is often used in GTK+ applications when showing modal dialog
6744 * boxes. Note that event sources are associated with a particular
6745 * #GMainContext, and will be checked and dispatched for all main
6746 * loops associated with that GMainContext.
6748 * GTK+ contains wrappers of some of these functions, e.g. gtk_main(),
6749 * gtk_main_quit() and gtk_events_pending().
6751 * ## Creating new source types
6753 * One of the unusual features of the #GMainLoop functionality
6754 * is that new types of event source can be created and used in
6755 * addition to the builtin type of event source. A new event source
6756 * type is used for handling GDK events. A new source type is created
6757 * by "deriving" from the #GSource structure. The derived type of
6758 * source is represented by a structure that has the #GSource structure
6759 * as a first element, and other elements specific to the new source
6760 * type. To create an instance of the new source type, call
6761 * g_source_new() passing in the size of the derived structure and
6762 * a table of functions. These #GSourceFuncs determine the behavior of
6763 * the new source type.
6765 * New source types basically interact with the main context
6766 * in two ways. Their prepare function in #GSourceFuncs can set a timeout
6767 * to determine the maximum amount of time that the main loop will sleep
6768 * before checking the source again. In addition, or as well, the source
6769 * can add file descriptors to the set that the main context checks using
6770 * g_source_add_poll().
6772 * ## Customizing the main loop iteration
6774 * Single iterations of a #GMainContext can be run with
6775 * g_main_context_iteration(). In some cases, more detailed control
6776 * of exactly how the details of the main loop work is desired, for
6777 * instance, when integrating the #GMainLoop with an external main loop.
6778 * In such cases, you can call the component functions of
6779 * g_main_context_iteration() directly. These functions are
6780 * g_main_context_prepare(), g_main_context_query(),
6781 * g_main_context_check() and g_main_context_dispatch().
6783 * ## State of a Main Context # {#mainloop-states}
6785 * The operation of these functions can best be seen in terms
6786 * of a state diagram, as shown in this image.
6788 * ![](mainloop-states.gif)
6790 * On UNIX, the GLib mainloop is incompatible with fork(). Any program
6791 * using the mainloop must either exec() or exit() from the child
6792 * without returning to the mainloop.
6798 * @Title: Simple XML Subset Parser * @Short_description: parses a subset of XML
6799 * @See_also: [XML Specification](http://www.w3.org/TR/REC-xml/)
6801 * The "GMarkup" parser is intended to parse a simple markup format
6802 * that's a subset of XML. This is a small, efficient, easy-to-use
6803 * parser. It should not be used if you expect to interoperate with
6804 * other applications generating full-scale XML. However, it's very
6805 * useful for application data files, config files, etc. where you
6806 * know your application will be the only one writing the file.
6807 * Full-scale XML parsers should be able to parse the subset used by
6808 * GMarkup, so you can easily migrate to full-scale XML at a later
6809 * time if the need arises.
6811 * GMarkup is not guaranteed to signal an error on all invalid XML;
6812 * the parser may accept documents that an XML parser would not.
6813 * However, XML documents which are not well-formed (which is a
6814 * weaker condition than being valid. See the
6815 * [XML specification](http://www.w3.org/TR/REC-xml/)
6816 * for definitions of these terms.) are not considered valid GMarkup
6819 * Simplifications to XML include:
6821 * - Only UTF-8 encoding is allowed
6823 * - No user-defined entities
6825 * - Processing instructions, comments and the doctype declaration
6826 * are "passed through" but are not interpreted in any way
6828 * - No DTD or validation
6830 * The markup format does support:
6836 * - 5 standard entities: & < > " '
6838 * - Character references
6840 * - Sections marked as CDATA
6846 * @Short_Description: general memory-handling
6847 * @Title: Memory Allocation
6849 * These functions provide support for allocating and freeing memory.
6851 * If any call to allocate memory fails, the application is terminated.
6852 * This also means that there is no need to check if the call succeeded.
6854 * It's important to match g_malloc() (and wrappers such as g_new()) with
6855 * g_free(), g_slice_alloc() and wrappers such as g_slice_new()) with
6856 * g_slice_free(), plain malloc() with free(), and (if you're using C++)
6857 * new with delete and new[] with delete[]. Otherwise bad things can happen,
6858 * since these allocators may use different memory pools (and new/delete call
6859 * constructors and destructors). See also g_mem_set_vtable().
6864 * SECTION:memory_slices
6865 * @title: Memory Slices
6866 * @short_description: efficient way to allocate groups of equal-sized
6869 * Memory slices provide a space-efficient and multi-processing scalable
6870 * way to allocate equal-sized pieces of memory, just like the original
6871 * #GMemChunks (from GLib 2.8), while avoiding their excessive
6872 * memory-waste, scalability and performance problems.
6874 * To achieve these goals, the slice allocator uses a sophisticated,
6875 * layered design that has been inspired by Bonwick's slab allocator
6876 * ([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html)
6877 * Jeff Bonwick, The slab allocator: An object-caching kernel
6878 * memory allocator. USENIX 1994, and
6879 * [Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html)
6880 * Bonwick and Jonathan Adams, Magazines and vmem: Extending the
6881 * slab allocator to many cpu's and arbitrary resources. USENIX 2001)
6883 * It uses posix_memalign() to optimize allocations of many equally-sized
6884 * chunks, and has per-thread free lists (the so-called magazine layer)
6885 * to quickly satisfy allocation requests of already known structure sizes.
6886 * This is accompanied by extra caching logic to keep freed memory around
6887 * for some time before returning it to the system. Memory that is unused
6888 * due to alignment constraints is used for cache colorization (random
6889 * distribution of chunk addresses) to improve CPU cache utilization. The
6890 * caching layer of the slice allocator adapts itself to high lock contention
6891 * to improve scalability.
6893 * The slice allocator can allocate blocks as small as two pointers, and
6894 * unlike malloc(), it does not reserve extra space per block. For large block
6895 * sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the
6896 * system malloc() implementation. For newly written code it is recommended
6897 * to use the new `g_slice` API instead of g_malloc() and
6898 * friends, as long as objects are not resized during their lifetime and the
6899 * object size used at allocation time is still available when freeing.
6901 * Here is an example for using the slice allocator:
6902 * |[<!-- language="C" -->
6903 * gchar *mem[10000];
6906 * // Allocate 10000 blocks.
6907 * for (i = 0; i < 10000; i++)
6909 * mem[i] = g_slice_alloc (50);
6911 * // Fill in the memory with some junk.
6912 * for (j = 0; j < 50; j++)
6913 * mem[i][j] = i * j;
6916 * // Now free all of the blocks.
6917 * for (i = 0; i < 10000; i++)
6918 * g_slice_free1 (50, mem[i]);
6921 * And here is an example for using the using the slice allocator
6922 * with data structures:
6923 * |[<!-- language="C" -->
6924 * GRealArray *array;
6926 * // Allocate one block, using the g_slice_new() macro.
6927 * array = g_slice_new (GRealArray);
6929 * // We can now use array just like a normal pointer to a structure.
6930 * array->data = NULL;
6933 * array->zero_terminated = (zero_terminated ? 1 : 0);
6934 * array->clear = (clear ? 1 : 0);
6935 * array->elt_size = elt_size;
6937 * // We can free the block, so it can be reused.
6938 * g_slice_free (GRealArray, array);
6945 * @title: Message Logging
6946 * @short_description: versatile support for logging messages
6947 * with different levels of importance
6949 * These functions provide support for logging error messages
6950 * or messages used for debugging.
6952 * There are several built-in levels of messages, defined in
6953 * #GLogLevelFlags. These can be extended with user-defined levels.
6958 * SECTION:misc_utils
6959 * @title: Miscellaneous Utility Functions
6960 * @short_description: a selection of portable utility functions
6962 * These are portable utility functions.
6968 * @title: Numerical Definitions
6969 * @short_description: mathematical constants, and floating point decomposition
6971 * GLib offers mathematical constants such as #G_PI for the value of pi;
6972 * many platforms have these in the C library, but some don't, the GLib
6973 * versions always exist.
6975 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
6976 * sign, mantissa and exponent of IEEE floats and doubles. These unions are
6977 * defined as appropriate for a given platform. IEEE floats and doubles are
6978 * supported (used for storage) by at least Intel, PPC and Sparc. See
6979 * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
6980 * for more information about IEEE number formats.
6986 * @Short_description: parses commandline options
6987 * @Title: Commandline option parser
6989 * The GOption commandline parser is intended to be a simpler replacement
6990 * for the popt library. It supports short and long commandline options,
6991 * as shown in the following example:
6993 * `testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2`
6995 * The example demonstrates a number of features of the GOption
6996 * commandline parser:
6998 * - Options can be single letters, prefixed by a single dash.
7000 * - Multiple short options can be grouped behind a single dash.
7002 * - Long options are prefixed by two consecutive dashes.
7004 * - Options can have an extra argument, which can be a number, a string or
7005 * a filename. For long options, the extra argument can be appended with
7006 * an equals sign after the option name, which is useful if the extra
7007 * argument starts with a dash, which would otherwise cause it to be
7008 * interpreted as another option.
7010 * - Non-option arguments are returned to the application as rest arguments.
7012 * - An argument consisting solely of two dashes turns off further parsing,
7013 * any remaining arguments (even those starting with a dash) are returned
7014 * to the application as rest arguments.
7016 * Another important feature of GOption is that it can automatically
7017 * generate nicely formatted help output. Unless it is explicitly turned
7018 * off with g_option_context_set_help_enabled(), GOption will recognize
7019 * the `--help`, `-?`, `--help-all` and `--help-groupname` options
7020 * (where `groupname` is the name of a #GOptionGroup) and write a text
7021 * similar to the one shown in the following example to stdout.
7025 * testtreemodel [OPTION...] - test tree model performance
7028 * -h, --help Show help options
7029 * --help-all Show all help options
7030 * --help-gtk Show GTK+ Options
7032 * Application Options:
7033 * -r, --repeats=N Average over N repetitions
7034 * -m, --max-size=M Test up to 2^M items
7035 * --display=DISPLAY X display to use
7036 * -v, --verbose Be verbose
7037 * -b, --beep Beep when done
7038 * --rand Randomize the data
7041 * GOption groups options in #GOptionGroups, which makes it easy to
7042 * incorporate options from multiple sources. The intended use for this is
7043 * to let applications collect option groups from the libraries it uses,
7044 * add them to their #GOptionContext, and parse all options by a single call
7045 * to g_option_context_parse(). See gtk_get_option_group() for an example.
7047 * If an option is declared to be of type string or filename, GOption takes
7048 * care of converting it to the right encoding; strings are returned in
7049 * UTF-8, filenames are returned in the GLib filename encoding. Note that
7050 * this only works if setlocale() has been called before
7051 * g_option_context_parse().
7053 * Here is a complete example of setting up GOption to parse the example
7054 * commandline above and produce the example help output.
7055 * |[<!-- language="C" -->
7056 * static gint repeats = 2;
7057 * static gint max_size = 8;
7058 * static gboolean verbose = FALSE;
7059 * static gboolean beep = FALSE;
7060 * static gboolean randomize = FALSE;
7062 * static GOptionEntry entries[] =
7064 * { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
7065 * { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
7066 * { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
7067 * { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
7068 * { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL },
7073 * main (int argc, char *argv[])
7075 * GError *error = NULL;
7076 * GOptionContext *context;
7078 * context = g_option_context_new ("- test tree model performance");
7079 * g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
7080 * g_option_context_add_group (context, gtk_get_option_group (TRUE));
7081 * if (!g_option_context_parse (context, &argc, &argv, &error))
7083 * g_print ("option parsing failed: %s\n", error->message);
7092 * On UNIX systems, the argv that is passed to main() has no particular
7093 * encoding, even to the extent that different parts of it may have
7094 * different encodings. In general, normal arguments and flags will be
7095 * in the current locale and filenames should be considered to be opaque
7096 * byte strings. Proper use of %G_OPTION_ARG_FILENAME vs
7097 * %G_OPTION_ARG_STRING is therefore important.
7099 * Note that on Windows, filenames do have an encoding, but using
7100 * #GOptionContext with the argv as passed to main() will result in a
7101 * program that can only accept commandline arguments with characters
7102 * from the system codepage. This can cause problems when attempting to
7103 * deal with filenames containing Unicode characters that fall outside
7106 * A solution to this is to use g_win32_get_command_line() and
7107 * g_option_context_parse_strv() which will properly handle full Unicode
7108 * filenames. If you are using #GApplication, this is done
7109 * automatically for you.
7111 * The following example shows how you can use #GOptionContext directly
7112 * in order to correctly deal with Unicode filenames on Windows:
7114 * |[<!-- language="C" -->
7116 * main (int argc, char **argv)
7118 * GError *error = NULL;
7119 * GOptionContext *context;
7123 * args = g_win32_get_command_line ();
7125 * args = g_strdupv (argv);
7130 * if (!g_option_context_parse_strv (context, &args, &error))
7137 * g_strfreev (args);
7147 * @title: Glob-style pattern matching
7148 * @short_description: matches strings against patterns containing '*'
7149 * (wildcard) and '?' (joker)
7151 * The g_pattern_match* functions match a string
7152 * against a pattern containing '*' and '?' wildcards with similar
7153 * semantics as the standard glob() function: '*' matches an arbitrary,
7154 * possibly empty, string, '?' matches an arbitrary character.
7156 * Note that in contrast to glob(), the '/' character can be matched by
7157 * the wildcards, there are no '[...]' character ranges and '*' and '?'
7158 * can not be escaped to include them literally in a pattern.
7160 * When multiple strings must be matched against the same pattern, it
7161 * is better to compile the pattern to a #GPatternSpec using
7162 * g_pattern_spec_new() and use g_pattern_match_string() instead of
7163 * g_pattern_match_simple(). This avoids the overhead of repeated
7164 * pattern compilation.
7171 * @short_description: a 2-way association between a string and a
7172 * unique integer identifier
7174 * Quarks are associations between strings and integer identifiers.
7175 * Given either the string or the #GQuark identifier it is possible to
7176 * retrieve the other.
7178 * Quarks are used for both [datasets][glib-Datasets] and
7179 * [keyed data lists][glib-Keyed-Data-Lists].
7181 * To create a new quark from a string, use g_quark_from_string() or
7182 * g_quark_from_static_string().
7184 * To find the string corresponding to a given #GQuark, use
7185 * g_quark_to_string().
7187 * To find the #GQuark corresponding to a given string, use
7188 * g_quark_try_string().
7190 * Another use for the string pool maintained for the quark functions
7191 * is string interning, using g_intern_string() or
7192 * g_intern_static_string(). An interned string is a canonical
7193 * representation for a string. One important advantage of interned
7194 * strings is that they can be compared for equality by a simple
7195 * pointer comparison, rather than using strcmp().
7201 * @Title: Double-ended Queues
7202 * @Short_description: double-ended queue data structure
7204 * The #GQueue structure and its associated functions provide a standard
7205 * queue data structure. Internally, GQueue uses the same data structure
7206 * as #GList to store elements.
7208 * The data contained in each element can be either integer values, by
7209 * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
7210 * or simply pointers to any type of data.
7212 * To create a new GQueue, use g_queue_new().
7214 * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or
7217 * To add elements, use g_queue_push_head(), g_queue_push_head_link(),
7218 * g_queue_push_tail() and g_queue_push_tail_link().
7220 * To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
7222 * To free the entire queue, use g_queue_free().
7227 * SECTION:random_numbers
7228 * @title: Random Numbers
7229 * @short_description: pseudo-random number generator
7231 * The following functions allow you to use a portable, fast and good
7232 * pseudo-random number generator (PRNG).
7234 * Do not use this API for cryptographic purposes such as key
7235 * generation, nonces, salts or one-time pads.
7237 * This PRNG is suitable for non-cryptographic use such as in games
7238 * (shuffling a card deck, generating levels), generating data for
7239 * a test suite, etc. If you need random data for cryptographic
7240 * purposes, it is recommended to use platform-specific APIs such
7241 * as `/dev/random` on UNIX, or CryptGenRandom() on Windows.
7243 * GRand uses the Mersenne Twister PRNG, which was originally
7244 * developed by Makoto Matsumoto and Takuji Nishimura. Further
7245 * information can be found at
7246 * [this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html).
7248 * If you just need a random number, you simply call the g_random_*
7249 * functions, which will create a globally used #GRand and use the
7250 * according g_rand_* functions internally. Whenever you need a
7251 * stream of reproducible random numbers, you better create a
7252 * #GRand yourself and use the g_rand_* functions directly, which
7253 * will also be slightly faster. Initializing a #GRand with a
7254 * certain seed will produce exactly the same series of random
7255 * numbers on all platforms. This can thus be used as a seed for
7258 * The g_rand*_range functions will return high quality equally
7259 * distributed random numbers, whereas for example the
7260 * `(g_random_int()\%max)` approach often
7261 * doesn't yield equally distributed numbers.
7263 * GLib changed the seeding algorithm for the pseudo-random number
7264 * generator Mersenne Twister, as used by #GRand. This was necessary,
7265 * because some seeds would yield very bad pseudo-random streams.
7266 * Also the pseudo-random integers generated by g_rand*_int_range()
7267 * will have a slightly better equal distribution with the new
7270 * The original seeding and generation algorithms, as found in
7271 * GLib 2.0.x, can be used instead of the new ones by setting the
7272 * environment variable `G_RANDOM_VERSION` to the value of '2.0'.
7273 * Use the GLib-2.0 algorithms only if you have sequences of numbers
7274 * generated with Glib-2.0 that you need to reproduce exactly.
7280 * @title: Lexical Scanner
7281 * @short_description: a general purpose lexical scanner
7283 * The #GScanner and its associated functions provide a
7284 * general purpose lexical scanner.
7291 * @short_description: scalable lists
7293 * The #GSequence data structure has the API of a list, but is
7294 * implemented internally with a balanced binary tree. This means that
7295 * it is possible to maintain a sorted list of n elements in time O(n log n).
7296 * The data contained in each element can be either integer values, by using
7297 * of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply
7298 * pointers to any type of data.
7300 * A #GSequence is accessed through "iterators", represented by a
7301 * #GSequenceIter. An iterator represents a position between two
7302 * elements of the sequence. For example, the "begin" iterator
7303 * represents the gap immediately before the first element of the
7304 * sequence, and the "end" iterator represents the gap immediately
7305 * after the last element. In an empty sequence, the begin and end
7306 * iterators are the same.
7308 * Some methods on #GSequence operate on ranges of items. For example
7309 * g_sequence_foreach_range() will call a user-specified function on
7310 * each element with the given range. The range is delimited by the
7311 * gaps represented by the passed-in iterators, so if you pass in the
7312 * begin and end iterators, the range in question is the entire
7315 * The function g_sequence_get() is used with an iterator to access the
7316 * element immediately following the gap that the iterator represents.
7317 * The iterator is said to "point" to that element.
7319 * Iterators are stable across most operations on a #GSequence. For
7320 * example an iterator pointing to some element of a sequence will
7321 * continue to point to that element even after the sequence is sorted.
7322 * Even moving an element to another sequence using for example
7323 * g_sequence_move_range() will not invalidate the iterators pointing
7324 * to it. The only operation that will invalidate an iterator is when
7325 * the element it points to is removed from any sequence.
7331 * @title: Shell-related Utilities
7332 * @short_description: shell-like commandline handling
7338 * @Short_description: process launching
7339 * @Title: Spawning Processes
7344 * SECTION:string_chunks
7345 * @title: String Chunks
7346 * @short_description: efficient storage of groups of strings
7348 * String chunks are used to store groups of strings. Memory is
7349 * allocated in blocks, and as strings are added to the #GStringChunk
7350 * they are copied into the next free position in a block. When a block
7351 * is full a new block is allocated.
7353 * When storing a large number of strings, string chunks are more
7354 * efficient than using g_strdup() since fewer calls to malloc() are
7355 * needed, and less memory is wasted in memory allocation overheads.
7357 * By adding strings with g_string_chunk_insert_const() it is also
7358 * possible to remove duplicates.
7360 * To create a new #GStringChunk use g_string_chunk_new().
7362 * To add strings to a #GStringChunk use g_string_chunk_insert().
7364 * To add strings to a #GStringChunk, but without duplicating strings
7365 * which are already in the #GStringChunk, use
7366 * g_string_chunk_insert_const().
7368 * To free the entire #GStringChunk use g_string_chunk_free(). It is
7369 * not possible to free individual strings.
7374 * SECTION:string_utils
7375 * @title: String Utility Functions
7376 * @short_description: various string-related functions
7378 * This section describes a number of utility functions for creating,
7379 * duplicating, and manipulating strings.
7381 * Note that the functions g_printf(), g_fprintf(), g_sprintf(),
7382 * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
7383 * are declared in the header `gprintf.h` which is not included in `glib.h`
7384 * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
7385 * explicitly include `<glib/gprintf.h>` in order to use the GLib
7386 * printf() functions.
7388 * ## String precision pitfalls # {#string-precision}
7390 * While you may use the printf() functions to format UTF-8 strings,
7391 * notice that the precision of a \%Ns parameter is interpreted
7392 * as the number of bytes, not characters to print. On top of that,
7393 * the GNU libc implementation of the printf() functions has the
7394 * "feature" that it checks that the string given for the \%Ns
7395 * parameter consists of a whole number of characters in the current
7396 * encoding. So, unless you are sure you are always going to be in an
7397 * UTF-8 locale or your know your text is restricted to ASCII, avoid
7398 * using \%Ns. If your intention is to format strings for a
7399 * certain number of columns, then \%Ns is not a correct solution
7400 * anyway, since it fails to take wide characters (see g_unichar_iswide())
7408 * @short_description: text buffers which grow automatically
7411 * A #GString is an object that handles the memory management of a C
7412 * string for you. The emphasis of #GString is on text, typically
7413 * UTF-8. Crucially, the "str" member of a #GString is guaranteed to
7414 * have a trailing nul character, and it is therefore always safe to
7415 * call functions such as strchr() or g_strdup() on it.
7417 * However, a #GString can also hold arbitrary binary data, because it
7418 * has a "len" member, which includes any possible embedded nul
7419 * characters in the data. Conceptually then, #GString is like a
7420 * #GByteArray with the addition of many convenience methods for text,
7421 * and a guaranteed nul terminator.
7428 * @short_description: a test framework
7429 * @see_also: [gtester][gtester], [gtester-report][gtester-report]
7431 * GLib provides a framework for writing and maintaining unit tests
7432 * in parallel to the code they are testing. The API is designed according
7433 * to established concepts found in the other test frameworks (JUnit, NUnit,
7434 * RUnit), which in turn is based on smalltalk unit testing concepts.
7436 * - Test case: Tests (test methods) are grouped together with their
7437 * fixture into test cases.
7439 * - Fixture: A test fixture consists of fixture data and setup and
7440 * teardown methods to establish the environment for the test
7441 * functions. We use fresh fixtures, i.e. fixtures are newly set
7442 * up and torn down around each test invocation to avoid dependencies
7445 * - Test suite: Test cases can be grouped into test suites, to allow
7446 * subsets of the available tests to be run. Test suites can be
7447 * grouped into other test suites as well.
7449 * The API is designed to handle creation and registration of test suites
7450 * and test cases implicitly. A simple call like
7451 * |[<!-- language="C" -->
7452 * g_test_add_func ("/misc/assertions", test_assertions);
7454 * creates a test suite called "misc" with a single test case named
7455 * "assertions", which consists of running the test_assertions function.
7457 * In addition to the traditional g_assert(), the test framework provides
7458 * an extended set of assertions for string and numerical comparisons:
7459 * g_assert_cmpfloat(), g_assert_cmpint(), g_assert_cmpuint(),
7460 * g_assert_cmphex(), g_assert_cmpstr(). The advantage of these variants
7461 * over plain g_assert() is that the assertion messages can be more
7462 * elaborate, and include the values of the compared entities.
7464 * GLib ships with two utilities called gtester and gtester-report to
7465 * facilitate running tests and producing nicely formatted test reports.
7470 * SECTION:thread_pools
7471 * @title: Thread Pools
7472 * @short_description: pools of threads to execute work concurrently
7473 * @see_also: #GThread
7475 * Sometimes you wish to asynchronously fork out the execution of work
7476 * and continue working in your own thread. If that will happen often,
7477 * the overhead of starting and destroying a thread each time might be
7478 * too high. In such cases reusing already started threads seems like a
7479 * good idea. And it indeed is, but implementing this can be tedious
7482 * Therefore GLib provides thread pools for your convenience. An added
7483 * advantage is, that the threads can be shared between the different
7484 * subsystems of your program, when they are using GLib.
7486 * To create a new thread pool, you use g_thread_pool_new().
7487 * It is destroyed by g_thread_pool_free().
7489 * If you want to execute a certain task within a thread pool,
7490 * you call g_thread_pool_push().
7492 * To get the current number of running threads you call
7493 * g_thread_pool_get_num_threads(). To get the number of still
7494 * unprocessed tasks you call g_thread_pool_unprocessed(). To control
7495 * the maximal number of threads for a thread pool, you use
7496 * g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
7498 * Finally you can control the number of unused threads, that are kept
7499 * alive by GLib for future use. The current number can be fetched with
7500 * g_thread_pool_get_num_unused_threads(). The maximal number can be
7501 * controlled by g_thread_pool_get_max_unused_threads() and
7502 * g_thread_pool_set_max_unused_threads(). All currently unused threads
7503 * can be stopped by calling g_thread_pool_stop_unused_threads().
7510 * @short_description: portable support for threads, mutexes, locks,
7511 * conditions and thread private data
7512 * @see_also: #GThreadPool, #GAsyncQueue
7514 * Threads act almost like processes, but unlike processes all threads
7515 * of one process share the same memory. This is good, as it provides
7516 * easy communication between the involved threads via this shared
7517 * memory, and it is bad, because strange things (so called
7518 * "Heisenbugs") might happen if the program is not carefully designed.
7519 * In particular, due to the concurrent nature of threads, no
7520 * assumptions on the order of execution of code running in different
7521 * threads can be made, unless order is explicitly forced by the
7522 * programmer through synchronization primitives.
7524 * The aim of the thread-related functions in GLib is to provide a
7525 * portable means for writing multi-threaded software. There are
7526 * primitives for mutexes to protect the access to portions of memory
7527 * (#GMutex, #GRecMutex and #GRWLock). There is a facility to use
7528 * individual bits for locks (g_bit_lock()). There are primitives
7529 * for condition variables to allow synchronization of threads (#GCond).
7530 * There are primitives for thread-private data - data that every
7531 * thread has a private instance of (#GPrivate). There are facilities
7532 * for one-time initialization (#GOnce, g_once_init_enter()). Finally,
7533 * there are primitives to create and manage threads (#GThread).
7535 * The GLib threading system used to be initialized with g_thread_init().
7536 * This is no longer necessary. Since version 2.32, the GLib threading
7537 * system is automatically initialized at the start of your program,
7538 * and all thread-creation functions and synchronization primitives
7539 * are available right away.
7541 * Note that it is not safe to assume that your program has no threads
7542 * even if you don't call g_thread_new() yourself. GLib and GIO can
7543 * and will create threads for their own purposes in some cases, such
7544 * as when using g_unix_signal_source_new() or when using GDBus.
7546 * Originally, UNIX did not have threads, and therefore some traditional
7547 * UNIX APIs are problematic in threaded programs. Some notable examples
7550 * - C library functions that return data in statically allocated
7551 * buffers, such as strtok() or strerror(). For many of these,
7552 * there are thread-safe variants with a _r suffix, or you can
7553 * look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
7555 * - The functions setenv() and unsetenv() manipulate the process
7556 * environment in a not thread-safe way, and may interfere with getenv()
7557 * calls in other threads. Note that getenv() calls may be hidden behind
7558 * other APIs. For example, GNU gettext() calls getenv() under the
7559 * covers. In general, it is best to treat the environment as readonly.
7560 * If you absolutely have to modify the environment, do it early in
7561 * main(), when no other threads are around yet.
7563 * - The setlocale() function changes the locale for the entire process,
7564 * affecting all threads. Temporary changes to the locale are often made
7565 * to change the behavior of string scanning or formatting functions
7566 * like scanf() or printf(). GLib offers a number of string APIs
7567 * (like g_ascii_formatd() or g_ascii_strtod()) that can often be
7568 * used as an alternative. Or you can use the uselocale() function
7569 * to change the locale only for the current thread.
7571 * - The fork() function only takes the calling thread into the child's
7572 * copy of the process image. If other threads were executing in critical
7573 * sections they could have left mutexes locked which could easily
7574 * cause deadlocks in the new child. For this reason, you should
7575 * call exit() or exec() as soon as possible in the child and only
7576 * make signal-safe library calls before that.
7578 * - The daemon() function uses fork() in a way contrary to what is
7579 * described above. It should not be used with GLib programs.
7581 * GLib itself is internally completely thread-safe (all global data is
7582 * automatically locked), but individual data structure instances are
7583 * not automatically locked for performance reasons. For example,
7584 * you must coordinate accesses to the same #GHashTable from multiple
7585 * threads. The two notable exceptions from this rule are #GMainLoop
7586 * and #GAsyncQueue, which are thread-safe and need no further
7587 * application-level locking to be accessed from multiple threads.
7588 * Most refcounting functions such as g_object_ref() are also thread-safe.
7595 * @short_description: keep track of elapsed time
7597 * #GTimer records a start time, and counts microseconds elapsed since
7598 * that time. This is done somewhat differently on different platforms,
7599 * and can be tricky to get exactly right, so #GTimer provides a
7600 * portable/convenient interface.
7607 * @short_description: a structure representing a time zone
7608 * @see_also: #GDateTime
7610 * #GTimeZone is a structure that represents a time zone, at no
7611 * particular point in time. It is refcounted and immutable.
7613 * A time zone contains a number of intervals. Each interval has
7614 * an abbreviation to describe it, an offet to UTC and a flag indicating
7615 * if the daylight savings time is in effect during that interval. A
7616 * time zone always has at least one interval -- interval 0.
7618 * Every UTC time is contained within exactly one interval, but a given
7619 * local time may be contained within zero, one or two intervals (due to
7620 * incontinuities associated with daylight savings time).
7622 * An interval may refer to a specific period of time (eg: the duration
7623 * of daylight savings time during 2010) or it may refer to many periods
7624 * of time that share the same properties (eg: all periods of daylight
7625 * savings time). It is also possible (usually for political reasons)
7626 * that some properties (like the abbreviation) change between intervals
7627 * without other properties changing.
7629 * #GTimeZone is available since GLib 2.26.
7634 * SECTION:trash_stack
7635 * @title: Trash Stacks
7636 * @short_description: maintain a stack of unused allocated memory chunks
7638 * A #GTrashStack is an efficient way to keep a stack of unused allocated
7639 * memory chunks. Each memory chunk is required to be large enough to hold
7640 * a #gpointer. This allows the stack to be maintained without any space
7641 * overhead, since the stack pointers can be stored inside the memory chunks.
7643 * There is no function to create a #GTrashStack. A %NULL #GTrashStack*
7644 * is a perfectly valid empty stack.
7649 * SECTION:trees-binary
7650 * @title: Balanced Binary Trees
7651 * @short_description: a sorted collection of key/value pairs optimized
7652 * for searching and traversing in order
7654 * The #GTree structure and its associated functions provide a sorted
7655 * collection of key/value pairs optimized for searching and traversing
7658 * To create a new #GTree use g_tree_new().
7660 * To insert a key/value pair into a #GTree use g_tree_insert().
7662 * To lookup the value corresponding to a given key, use
7663 * g_tree_lookup() and g_tree_lookup_extended().
7665 * To find out the number of nodes in a #GTree, use g_tree_nnodes(). To
7666 * get the height of a #GTree, use g_tree_height().
7668 * To traverse a #GTree, calling a function for each node visited in
7669 * the traversal, use g_tree_foreach().
7671 * To remove a key/value pair use g_tree_remove().
7673 * To destroy a #GTree, use g_tree_destroy().
7678 * SECTION:trees-nary
7679 * @title: N-ary Trees
7680 * @short_description: trees of data with any number of branches
7682 * The #GNode struct and its associated functions provide a N-ary tree
7683 * data structure, where nodes in the tree can contain arbitrary data.
7685 * To create a new tree use g_node_new().
7687 * To insert a node into a tree use g_node_insert(),
7688 * g_node_insert_before(), g_node_append() and g_node_prepend().
7690 * To create a new node and insert it into a tree use
7691 * g_node_insert_data(), g_node_insert_data_after(),
7692 * g_node_insert_data_before(), g_node_append_data()
7693 * and g_node_prepend_data().
7695 * To reverse the children of a node use g_node_reverse_children().
7697 * To find a node use g_node_get_root(), g_node_find(),
7698 * g_node_find_child(), g_node_child_index(), g_node_child_position(),
7699 * g_node_first_child(), g_node_last_child(), g_node_nth_child(),
7700 * g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling()
7701 * or g_node_last_sibling().
7703 * To get information about a node or tree use G_NODE_IS_LEAF(),
7704 * G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(),
7705 * g_node_n_children(), g_node_is_ancestor() or g_node_max_height().
7707 * To traverse a tree, calling a function for each node visited in the
7708 * traversal, use g_node_traverse() or g_node_children_foreach().
7710 * To remove a node or subtree from a tree use g_node_unlink() or
7716 * SECTION:type_conversion
7717 * @title: Type Conversion Macros
7718 * @short_description: portably storing integers in pointer variables
7720 * Many times GLib, GTK+, and other libraries allow you to pass "user
7721 * data" to a callback, in the form of a void pointer. From time to time
7722 * you want to pass an integer instead of a pointer. You could allocate
7723 * an integer, with something like:
7724 * |[<!-- language="C" -->
7725 * int *ip = g_new (int, 1);
7728 * But this is inconvenient, and it's annoying to have to free the
7729 * memory at some later time.
7731 * Pointers are always at least 32 bits in size (on all platforms GLib
7732 * intends to support). Thus you can store at least 32-bit integer values
7733 * in a pointer value. Naively, you might try this, but it's incorrect:
7734 * |[<!-- language="C" -->
7740 * Again, that example was not correct, don't copy it.
7741 * The problem is that on some systems you need to do this:
7742 * |[<!-- language="C" -->
7745 * p = (void*) (long) 42;
7746 * i = (int) (long) p;
7748 * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
7749 * to do the right thing on the every platform.
7751 * Warning: You may not store pointers in integers. This is not
7752 * portable in any way, shape or form. These macros only allow storing
7753 * integers in pointers, and only preserve 32 bits of the integer; values
7754 * outside the range of a 32-bit integer will be mangled.
7760 * @title: Basic Types
7761 * @short_description: standard GLib types, defined for ease-of-use
7764 * GLib defines a number of commonly used types, which can be divided
7766 * - New types which are not part of standard C (but are defined in
7767 * various C standard library header files) - #gboolean, #gsize,
7768 * #gssize, #goffset, #gintptr, #guintptr.
7769 * - Integer types which are guaranteed to be the same size across
7770 * all platforms - #gint8, #guint8, #gint16, #guint16, #gint32,
7771 * #guint32, #gint64, #guint64.
7772 * - Types which are easier to use than their standard C counterparts -
7773 * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
7774 * - Types which correspond exactly to standard C types, but are
7775 * included for completeness - #gchar, #gint, #gshort, #glong,
7776 * #gfloat, #gdouble.
7778 * GLib also defines macros for the limits of some of the standard
7779 * integer and floating point types, as well as macros for suitable
7780 * printf() formats for these types.
7786 * @Title: Unicode Manipulation
7787 * @Short_description: functions operating on Unicode characters and
7789 * @See_also: g_locale_to_utf8(), g_locale_from_utf8()
7791 * This section describes a number of functions for dealing with
7792 * Unicode characters and strings. There are analogues of the
7793 * traditional `ctype.h` character classification and case conversion
7794 * functions, UTF-8 analogues of some string utility functions,
7795 * functions to perform normalization, case conversion and collation
7796 * on UTF-8 strings and finally functions to convert between the UTF-8,
7797 * UTF-16 and UCS-4 encodings of Unicode.
7799 * The implementations of the Unicode functions in GLib are based
7800 * on the Unicode Character Data tables, which are available from
7801 * [www.unicode.org](http://www.unicode.org/).
7802 * GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1,
7803 * GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1,
7804 * GLib 2.30 supports Unicode 6.0.
7810 * @Title: Version Information
7811 * @Short_description: variables and functions to check the GLib version
7813 * GLib provides version information, primarily useful in configure
7814 * checks for builds that have a configure script. Applications will
7815 * not typically use the features described here.
7817 * The GLib headers annotate deprecated APIs in a way that produces
7818 * compiler warnings if these deprecated APIs are used. The warnings
7819 * can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS
7820 * before including the glib.h header.
7822 * GLib also provides support for building applications against
7823 * defined subsets of deprecated or new GLib APIs. Define the macro
7824 * %GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib
7825 * you want to receive warnings about deprecated APIs. Define the
7826 * macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of
7827 * GLib whose API you want to use.
7833 * @Title: Message Output and Debugging Functions
7834 * @Short_description: functions to output messages and help debug applications
7836 * These functions provide support for outputting messages.
7838 * The g_return family of macros (g_return_if_fail(),
7839 * g_return_val_if_fail(), g_return_if_reached(),
7840 * g_return_val_if_reached()) should only be used for programming
7841 * errors, a typical use case is checking for invalid parameters at
7842 * the beginning of a public function. They should not be used if
7843 * you just mean "if (error) return", they should only be used if
7844 * you mean "if (bug in program) return". The program behavior is
7845 * generally considered undefined after one of these checks fails.
7846 * They are not intended for normal control flow, only to give a
7847 * perhaps-helpful warning before giving up.
7853 * @title: Windows Compatibility Functions
7854 * @short_description: UNIX emulation on Windows
7856 * These functions provide some level of UNIX emulation on the
7857 * Windows platform. If your application really needs the POSIX
7858 * APIs, we suggest you try the Cygwin project.
7865 * Defines the %TRUE value for the #gboolean type.
7871 * @String: the string to be translated
7873 * Marks a string for translation, gets replaced with the translated string
7881 * _glib_get_locale_dir:
7883 * Return the path to the share\locale or lib\locale subfolder of the
7884 * GLib installation folder. The path is in the system codepage. We
7885 * have to use system codepage as bindtextdomain() doesn't have a
7892 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
7893 * @mode: as in access()
7895 * A wrapper for the POSIX access() function. This function is used to
7896 * test a pathname for one or several of read, write or execute
7897 * permissions, or just existence.
7899 * On Windows, the file protection mechanism is not at all POSIX-like,
7900 * and the underlying function in the C library only checks the
7901 * FAT-style READONLY attribute, and does not look at the ACL of a
7902 * file at all. This function is this in practise almost useless on
7903 * Windows. Software that needs to handle file permissions on Windows
7904 * more exactly should use the Win32 API.
7906 * See your C library manual for more details about access().
7908 * Returns: zero if the pathname refers to an existing file system
7909 * object that has all the tested permissions, or -1 otherwise
7916 * g_array_append_val:
7918 * @v: the value to append to the #GArray
7920 * Adds the value on to the end of the array. The array will grow in
7921 * size automatically if necessary.
7923 * g_array_append_val() is a macro which uses a reference to the value
7924 * parameter @v. This means that you cannot use it with literal values
7925 * such as "27". You must use variables.
7927 * Returns: the #GArray
7932 * g_array_append_vals:
7934 * @data: a pointer to the elements to append to the end of the array
7935 * @len: the number of elements to append
7937 * Adds @len elements onto the end of the array.
7939 * Returns: the #GArray
7946 * @free_segment: if %TRUE the actual element data is freed as well
7948 * Frees the memory allocated for the #GArray. If @free_segment is
7949 * %TRUE it frees the memory block holding the elements as well and
7950 * also each element if @array has a @element_free_func set. Pass
7951 * %FALSE if you want to free the #GArray wrapper but preserve the
7952 * underlying array for use elsewhere. If the reference count of @array
7953 * is greater than one, the #GArray wrapper is preserved but the size
7954 * of @array will be set to zero.
7956 * If array elements contain dynamically-allocated memory, they should
7957 * be freed separately.
7959 * Returns: the element data if @free_segment is %FALSE, otherwise
7960 * %NULL. The element data should be freed using g_free().
7965 * g_array_get_element_size:
7968 * Gets the size of the elements in @array.
7970 * Returns: Size of each element, in bytes
7978 * @t: the type of the elements
7979 * @i: the index of the element to return
7981 * Returns the element of a #GArray at the given index. The return
7982 * value is cast to the given type.
7984 * This example gets a pointer to an element in a #GArray:
7985 * |[<!-- language="C" -->
7986 * EDayViewEvent *event;
7987 * // This gets a pointer to the 4th element in the array of
7988 * // EDayViewEvent structs.
7989 * event = &g_array_index (events, EDayViewEvent, 3);
7992 * Returns: the element of the #GArray at the index given by @i
7997 * g_array_insert_val:
7999 * @i: the index to place the element at
8000 * @v: the value to insert into the array
8002 * Inserts an element into an array at the given index.
8004 * g_array_insert_val() is a macro which uses a reference to the value
8005 * parameter @v. This means that you cannot use it with literal values
8006 * such as "27". You must use variables.
8008 * Returns: the #GArray
8013 * g_array_insert_vals:
8015 * @index_: the index to place the elements at
8016 * @data: a pointer to the elements to insert
8017 * @len: the number of elements to insert
8019 * Inserts @len elements into a #GArray at the given index.
8021 * Returns: the #GArray
8027 * @zero_terminated: %TRUE if the array should have an extra element at
8028 * the end which is set to 0
8029 * @clear_: %TRUE if #GArray elements should be automatically cleared
8030 * to 0 when they are allocated
8031 * @element_size: the size of each element in bytes
8033 * Creates a new #GArray with a reference count of 1.
8035 * Returns: the new #GArray
8040 * g_array_prepend_val:
8042 * @v: the value to prepend to the #GArray
8044 * Adds the value on to the start of the array. The array will grow in
8045 * size automatically if necessary.
8047 * This operation is slower than g_array_append_val() since the
8048 * existing elements in the array have to be moved to make space for
8051 * g_array_prepend_val() is a macro which uses a reference to the value
8052 * parameter @v. This means that you cannot use it with literal values
8053 * such as "27". You must use variables.
8055 * Returns: the #GArray
8060 * g_array_prepend_vals:
8062 * @data: a pointer to the elements to prepend to the start of the array
8063 * @len: the number of elements to prepend
8065 * Adds @len elements onto the start of the array.
8067 * This operation is slower than g_array_append_vals() since the
8068 * existing elements in the array have to be moved to make space for
8071 * Returns: the #GArray
8079 * Atomically increments the reference count of @array by one.
8080 * This function is MT-safe and may be called from any thread.
8082 * Returns: The passed in #GArray
8088 * g_array_remove_index:
8090 * @index_: the index of the element to remove
8092 * Removes the element at the given index from a #GArray. The following
8093 * elements are moved down one place.
8095 * Returns: the #GArray
8100 * g_array_remove_index_fast:
8102 * @index_: the index of the element to remove
8104 * Removes the element at the given index from a #GArray. The last
8105 * element in the array is used to fill in the space, so this function
8106 * does not preserve the order of the #GArray. But it is faster than
8107 * g_array_remove_index().
8109 * Returns: the #GArray
8114 * g_array_remove_range:
8116 * @index_: the index of the first element to remove
8117 * @length: the number of elements to remove
8119 * Removes the given number of elements starting at the given index
8120 * from a #GArray. The following elements are moved to close the gap.
8122 * Returns: the #GArray
8128 * g_array_set_clear_func:
8130 * @clear_func: a function to clear an element of @array
8132 * Sets a function to clear an element of @array.
8134 * The @clear_func will be called when an element in the array
8135 * data segment is removed and when the array is freed and data
8136 * segment is deallocated as well.
8138 * Note that in contrast with other uses of #GDestroyNotify
8139 * functions, @clear_func is expected to clear the contents of
8140 * the array element it is given, but not free the element itself.
8149 * @length: the new size of the #GArray
8151 * Sets the size of the array, expanding it if necessary. If the array
8152 * was created with @clear_ set to %TRUE, the new elements are set to 0.
8154 * Returns: the #GArray
8159 * g_array_sized_new:
8160 * @zero_terminated: %TRUE if the array should have an extra element at
8161 * the end with all bits cleared
8162 * @clear_: %TRUE if all bits in the array should be cleared to 0 on
8164 * @element_size: size of each element in the array
8165 * @reserved_size: number of elements preallocated
8167 * Creates a new #GArray with @reserved_size elements preallocated and
8168 * a reference count of 1. This avoids frequent reallocation, if you
8169 * are going to add many elements to the array. Note however that the
8170 * size of the array is still 0.
8172 * Returns: the new #GArray
8179 * @compare_func: comparison function
8181 * Sorts a #GArray using @compare_func which should be a qsort()-style
8182 * comparison function (returns less than zero for first arg is less
8183 * than second arg, zero for equal, greater zero if first arg is
8184 * greater than second arg).
8186 * This is guaranteed to be a stable sort since version 2.32.
8191 * g_array_sort_with_data:
8193 * @compare_func: comparison function
8194 * @user_data: data to pass to @compare_func
8196 * Like g_array_sort(), but the comparison function receives an extra
8197 * user data argument.
8199 * This is guaranteed to be a stable sort since version 2.32.
8201 * There used to be a comment here about making the sort stable by
8202 * using the addresses of the elements in the comparison function.
8203 * This did not actually work, so any such code should be removed.
8211 * Atomically decrements the reference count of @array by one. If the
8212 * reference count drops to 0, all memory allocated by the array is
8213 * released. This function is MT-safe and may be called from any
8221 * g_ascii_digit_value:
8222 * @c: an ASCII character
8224 * Determines the numeric value of a character as a decimal digit.
8225 * Differs from g_unichar_digit_value() because it takes a char, so
8226 * there's no worry about sign extension if characters are signed.
8228 * Returns: If @c is a decimal digit (according to g_ascii_isdigit()),
8229 * its numeric value. Otherwise, -1.
8235 * @buffer: A buffer to place the resulting string in
8236 * @buf_len: The length of the buffer.
8237 * @d: The #gdouble to convert
8239 * Converts a #gdouble to a string, using the '.' as
8242 * This function generates enough precision that converting
8243 * the string back using g_ascii_strtod() gives the same machine-number
8244 * (on machines with IEEE compatible 64bit doubles). It is
8245 * guaranteed that the size of the resulting string will never
8246 * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes.
8248 * Returns: The pointer to the buffer with the converted string.
8254 * @buffer: A buffer to place the resulting string in
8255 * @buf_len: The length of the buffer.
8256 * @format: The printf()-style format to use for the
8257 * code to use for converting.
8258 * @d: The #gdouble to convert
8260 * Converts a #gdouble to a string, using the '.' as
8261 * decimal point. To format the number you pass in
8262 * a printf()-style format string. Allowed conversion
8263 * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
8265 * If you just want to want to serialize the value into a
8266 * string, use g_ascii_dtostr().
8268 * Returns: The pointer to the buffer with the converted string.
8276 * Determines whether a character is alphanumeric.
8278 * Unlike the standard C library isalnum() function, this only
8279 * recognizes standard ASCII letters and ignores the locale,
8280 * returning %FALSE for all non-ASCII characters. Also, unlike
8281 * the standard library function, this takes a char, not an int,
8282 * so don't call it on %EOF, but no need to cast to #guchar before
8283 * passing a possibly non-ASCII character in.
8285 * Returns: %TRUE if @c is an ASCII alphanumeric character
8293 * Determines whether a character is alphabetic (i.e. a letter).
8295 * Unlike the standard C library isalpha() function, this only
8296 * recognizes standard ASCII letters and ignores the locale,
8297 * returning %FALSE for all non-ASCII characters. Also, unlike
8298 * the standard library function, this takes a char, not an int,
8299 * so don't call it on %EOF, but no need to cast to #guchar before
8300 * passing a possibly non-ASCII character in.
8302 * Returns: %TRUE if @c is an ASCII alphabetic character
8310 * Determines whether a character is a control character.
8312 * Unlike the standard C library iscntrl() function, this only
8313 * recognizes standard ASCII control characters and ignores the
8314 * locale, returning %FALSE for all non-ASCII characters. Also,
8315 * unlike the standard library function, this takes a char, not
8316 * an int, so don't call it on %EOF, but no need to cast to #guchar
8317 * before passing a possibly non-ASCII character in.
8319 * Returns: %TRUE if @c is an ASCII control character.
8327 * Determines whether a character is digit (0-9).
8329 * Unlike the standard C library isdigit() function, this takes
8330 * a char, not an int, so don't call it on %EOF, but no need to
8331 * cast to #guchar before passing a possibly non-ASCII character in.
8333 * Returns: %TRUE if @c is an ASCII digit.
8341 * Determines whether a character is a printing character and not a space.
8343 * Unlike the standard C library isgraph() function, this only
8344 * recognizes standard ASCII characters and ignores the locale,
8345 * returning %FALSE for all non-ASCII characters. Also, unlike
8346 * the standard library function, this takes a char, not an int,
8347 * so don't call it on %EOF, but no need to cast to #guchar before
8348 * passing a possibly non-ASCII character in.
8350 * Returns: %TRUE if @c is an ASCII printing character other than space.
8358 * Determines whether a character is an ASCII lower case letter.
8360 * Unlike the standard C library islower() function, this only
8361 * recognizes standard ASCII letters and ignores the locale,
8362 * returning %FALSE for all non-ASCII characters. Also, unlike
8363 * the standard library function, this takes a char, not an int,
8364 * so don't call it on %EOF, but no need to worry about casting
8365 * to #guchar before passing a possibly non-ASCII character in.
8367 * Returns: %TRUE if @c is an ASCII lower case letter
8375 * Determines whether a character is a printing character.
8377 * Unlike the standard C library isprint() function, this only
8378 * recognizes standard ASCII characters and ignores the locale,
8379 * returning %FALSE for all non-ASCII characters. Also, unlike
8380 * the standard library function, this takes a char, not an int,
8381 * so don't call it on %EOF, but no need to cast to #guchar before
8382 * passing a possibly non-ASCII character in.
8384 * Returns: %TRUE if @c is an ASCII printing character.
8392 * Determines whether a character is a punctuation character.
8394 * Unlike the standard C library ispunct() function, this only
8395 * recognizes standard ASCII letters and ignores the locale,
8396 * returning %FALSE for all non-ASCII characters. Also, unlike
8397 * the standard library function, this takes a char, not an int,
8398 * so don't call it on %EOF, but no need to cast to #guchar before
8399 * passing a possibly non-ASCII character in.
8401 * Returns: %TRUE if @c is an ASCII punctuation character.
8409 * Determines whether a character is a white-space character.
8411 * Unlike the standard C library isspace() function, this only
8412 * recognizes standard ASCII white-space and ignores the locale,
8413 * returning %FALSE for all non-ASCII characters. Also, unlike
8414 * the standard library function, this takes a char, not an int,
8415 * so don't call it on %EOF, but no need to cast to #guchar before
8416 * passing a possibly non-ASCII character in.
8418 * Returns: %TRUE if @c is an ASCII white-space character
8426 * Determines whether a character is an ASCII upper case letter.
8428 * Unlike the standard C library isupper() function, this only
8429 * recognizes standard ASCII letters and ignores the locale,
8430 * returning %FALSE for all non-ASCII characters. Also, unlike
8431 * the standard library function, this takes a char, not an int,
8432 * so don't call it on %EOF, but no need to worry about casting
8433 * to #guchar before passing a possibly non-ASCII character in.
8435 * Returns: %TRUE if @c is an ASCII upper case letter
8443 * Determines whether a character is a hexadecimal-digit character.
8445 * Unlike the standard C library isxdigit() function, this takes
8446 * a char, not an int, so don't call it on %EOF, but no need to
8447 * cast to #guchar before passing a possibly non-ASCII character in.
8449 * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
8454 * g_ascii_strcasecmp:
8455 * @s1: string to compare with @s2
8456 * @s2: string to compare with @s1
8458 * Compare two strings, ignoring the case of ASCII characters.
8460 * Unlike the BSD strcasecmp() function, this only recognizes standard
8461 * ASCII letters and ignores the locale, treating all non-ASCII
8462 * bytes as if they are not letters.
8464 * This function should be used only on strings that are known to be
8465 * in encodings where the bytes corresponding to ASCII letters always
8466 * represent themselves. This includes UTF-8 and the ISO-8859-*
8467 * charsets, but not for instance double-byte encodings like the
8468 * Windows Codepage 932, where the trailing bytes of double-byte
8469 * characters include all ASCII letters. If you compare two CP932
8470 * strings using this function, you will get false matches.
8472 * Both @s1 and @s2 must be non-%NULL.
8474 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
8475 * or a positive value if @s1 > @s2.
8482 * @len: length of @str in bytes, or -1 if @str is nul-terminated
8484 * Converts all upper case ASCII letters to lower case ASCII letters.
8486 * Returns: a newly-allocated string, with all the upper case
8487 * characters in @str converted to lower case, with semantics that
8488 * exactly match g_ascii_tolower(). (Note that this is unlike the
8489 * old g_strdown(), which modified the string in place.)
8494 * g_ascii_strncasecmp:
8495 * @s1: string to compare with @s2
8496 * @s2: string to compare with @s1
8497 * @n: number of characters to compare
8499 * Compare @s1 and @s2, ignoring the case of ASCII characters and any
8500 * characters after the first @n in each string.
8502 * Unlike the BSD strcasecmp() function, this only recognizes standard
8503 * ASCII letters and ignores the locale, treating all non-ASCII
8504 * characters as if they are not letters.
8506 * The same warning as in g_ascii_strcasecmp() applies: Use this
8507 * function only on strings known to be in encodings where bytes
8508 * corresponding to ASCII letters always represent themselves.
8510 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
8511 * or a positive value if @s1 > @s2.
8517 * @nptr: the string to convert to a numeric value.
8518 * @endptr: if non-%NULL, it returns the character after
8519 * the last character used in the conversion.
8521 * Converts a string to a #gdouble value.
8523 * This function behaves like the standard strtod() function
8524 * does in the C locale. It does this without actually changing
8525 * the current locale, since that would not be thread-safe.
8526 * A limitation of the implementation is that this function
8527 * will still accept localized versions of infinities and NANs.
8529 * This function is typically used when reading configuration
8530 * files or other non-user input that should be locale independent.
8531 * To handle input from the user you should normally use the
8532 * locale-sensitive system strtod() function.
8534 * To convert from a #gdouble to a string in a locale-insensitive
8535 * way, use g_ascii_dtostr().
8537 * If the correct value would cause overflow, plus or minus %HUGE_VAL
8538 * is returned (according to the sign of the value), and %ERANGE is
8539 * stored in %errno. If the correct value would cause underflow,
8540 * zero is returned and %ERANGE is stored in %errno.
8542 * This function resets %errno before calling strtod() so that
8543 * you can reliably detect overflow and underflow.
8545 * Returns: the #gdouble value.
8551 * @nptr: the string to convert to a numeric value.
8552 * @endptr: if non-%NULL, it returns the character after
8553 * the last character used in the conversion.
8554 * @base: to be used for the conversion, 2..36 or 0
8556 * Converts a string to a #gint64 value.
8557 * This function behaves like the standard strtoll() function
8558 * does in the C locale. It does this without actually
8559 * changing the current locale, since that would not be
8562 * This function is typically used when reading configuration
8563 * files or other non-user input that should be locale independent.
8564 * To handle input from the user you should normally use the
8565 * locale-sensitive system strtoll() function.
8567 * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
8568 * is returned, and `ERANGE` is stored in `errno`.
8569 * If the base is outside the valid range, zero is returned, and
8570 * `EINVAL` is stored in `errno`. If the
8571 * string conversion fails, zero is returned, and @endptr returns @nptr
8572 * (if @endptr is non-%NULL).
8574 * Returns: the #gint64 value or zero on error.
8581 * @nptr: the string to convert to a numeric value.
8582 * @endptr: if non-%NULL, it returns the character after
8583 * the last character used in the conversion.
8584 * @base: to be used for the conversion, 2..36 or 0
8586 * Converts a string to a #guint64 value.
8587 * This function behaves like the standard strtoull() function
8588 * does in the C locale. It does this without actually
8589 * changing the current locale, since that would not be
8592 * This function is typically used when reading configuration
8593 * files or other non-user input that should be locale independent.
8594 * To handle input from the user you should normally use the
8595 * locale-sensitive system strtoull() function.
8597 * If the correct value would cause overflow, %G_MAXUINT64
8598 * is returned, and `ERANGE` is stored in `errno`.
8599 * If the base is outside the valid range, zero is returned, and
8600 * `EINVAL` is stored in `errno`.
8601 * If the string conversion fails, zero is returned, and @endptr returns
8602 * @nptr (if @endptr is non-%NULL).
8604 * Returns: the #guint64 value or zero on error.
8612 * @len: length of @str in bytes, or -1 if @str is nul-terminated
8614 * Converts all lower case ASCII letters to upper case ASCII letters.
8616 * Returns: a newly allocated string, with all the lower case
8617 * characters in @str converted to upper case, with semantics that
8618 * exactly match g_ascii_toupper(). (Note that this is unlike the
8619 * old g_strup(), which modified the string in place.)
8627 * Convert a character to ASCII lower case.
8629 * Unlike the standard C library tolower() function, this only
8630 * recognizes standard ASCII letters and ignores the locale, returning
8631 * all non-ASCII characters unchanged, even if they are lower case
8632 * letters in a particular character set. Also unlike the standard
8633 * library function, this takes and returns a char, not an int, so
8634 * don't call it on %EOF but no need to worry about casting to #guchar
8635 * before passing a possibly non-ASCII character in.
8637 * Returns: the result of converting @c to lower case. If @c is
8638 * not an ASCII upper case letter, @c is returned unchanged.
8646 * Convert a character to ASCII upper case.
8648 * Unlike the standard C library toupper() function, this only
8649 * recognizes standard ASCII letters and ignores the locale, returning
8650 * all non-ASCII characters unchanged, even if they are upper case
8651 * letters in a particular character set. Also unlike the standard
8652 * library function, this takes and returns a char, not an int, so
8653 * don't call it on %EOF but no need to worry about casting to #guchar
8654 * before passing a possibly non-ASCII character in.
8656 * Returns: the result of converting @c to upper case. If @c is not
8657 * an ASCII lower case letter, @c is returned unchanged.
8662 * g_ascii_xdigit_value:
8663 * @c: an ASCII character.
8665 * Determines the numeric value of a character as a hexidecimal
8666 * digit. Differs from g_unichar_xdigit_value() because it takes
8667 * a char, so there's no worry about sign extension if characters
8670 * Returns: If @c is a hex digit (according to g_ascii_isxdigit()),
8671 * its numeric value. Otherwise, -1.
8677 * @expr: the expression to check
8679 * Debugging macro to terminate the application if the assertion
8680 * fails. If the assertion fails (i.e. the expression is not true),
8681 * an error message is logged and the application is terminated.
8683 * The macro can be turned off in final releases of code by defining
8684 * `G_DISABLE_ASSERT` when compiling the application.
8689 * g_assert_cmpfloat:
8690 * @n1: an floating point number
8691 * @cmp: The comparison operator to use.
8692 * One of ==, !=, <, >, <=, >=.
8693 * @n2: another floating point number
8695 * Debugging macro to compare two floating point numbers.
8697 * The effect of `g_assert_cmpfloat (n1, op, n2)` is
8698 * the same as `g_assert_true (n1 op n2)`. The advantage
8699 * of this macro is that it can produce a message that includes the
8700 * actual values of @n1 and @n2.
8708 * @n1: an unsigned integer
8709 * @cmp: The comparison operator to use.
8710 * One of ==, !=, <, >, <=, >=.
8711 * @n2: another unsigned integer
8713 * Debugging macro to compare to unsigned integers.
8715 * This is a variant of g_assert_cmpuint() that displays the numbers
8716 * in hexadecimal notation in the message.
8725 * @cmp: The comparison operator to use.
8726 * One of ==, !=, <, >, <=, >=.
8727 * @n2: another integer
8729 * Debugging macro to compare two integers.
8731 * The effect of `g_assert_cmpint (n1, op, n2)` is
8732 * the same as `g_assert_true (n1 op n2)`. The advantage
8733 * of this macro is that it can produce a message that includes the
8734 * actual values of @n1 and @n2.
8742 * @s1: a string (may be %NULL)
8743 * @cmp: The comparison operator to use.
8744 * One of ==, !=, <, >, <=, >=.
8745 * @s2: another string (may be %NULL)
8747 * Debugging macro to compare two strings. If the comparison fails,
8748 * an error message is logged and the application is either terminated
8749 * or the testcase marked as failed.
8750 * The strings are compared using g_strcmp0().
8752 * The effect of `g_assert_cmpstr (s1, op, s2)` is
8753 * the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`.
8754 * The advantage of this macro is that it can produce a message that
8755 * includes the actual values of @s1 and @s2.
8757 * |[<!-- language="C" -->
8758 * g_assert_cmpstr (mystring, ==, "fubar");
8767 * @n1: an unsigned integer
8768 * @cmp: The comparison operator to use.
8769 * One of ==, !=, <, >, <=, >=.
8770 * @n2: another unsigned integer
8772 * Debugging macro to compare two unsigned integers.
8774 * The effect of `g_assert_cmpuint (n1, op, n2)` is
8775 * the same as `g_assert_true (n1 op n2)`. The advantage
8776 * of this macro is that it can produce a message that includes the
8777 * actual values of @n1 and @n2.
8785 * @err: a #GError, possibly %NULL
8786 * @dom: the expected error domain (a #GQuark)
8787 * @c: the expected error code
8789 * Debugging macro to check that a method has returned
8790 * the correct #GError.
8792 * The effect of `g_assert_error (err, dom, c)` is
8793 * the same as `g_assert_true (err != NULL && err->domain
8794 * == dom && err->code == c)`. The advantage of this
8795 * macro is that it can produce a message that includes the incorrect
8796 * error message and code.
8798 * This can only be used to test for a specific error. If you want to
8799 * test that @err is set, but don't care what it's set to, just use
8800 * `g_assert (err != NULL)`
8808 * @expr: the expression to check
8810 * Debugging macro to check an expression is false.
8812 * If the assertion fails (i.e. the expression is not false),
8813 * an error message is logged and the application is either
8814 * terminated or the testcase marked as failed.
8816 * See g_test_set_nonfatal_assertions().
8823 * g_assert_no_error:
8824 * @err: a #GError, possibly %NULL
8826 * Debugging macro to check that a #GError is not set.
8828 * The effect of `g_assert_no_error (err)` is
8829 * the same as `g_assert_true (err == NULL)`. The advantage
8830 * of this macro is that it can produce a message that includes
8831 * the error message and code.
8839 * @expr: the expression to check
8841 * Debugging macro to check an expression is not %NULL.
8843 * If the assertion fails (i.e. the expression is %NULL),
8844 * an error message is logged and the application is either
8845 * terminated or the testcase marked as failed.
8847 * See g_test_set_nonfatal_assertions().
8854 * g_assert_not_reached:
8856 * Debugging macro to terminate the application if it is ever
8857 * reached. If it is reached, an error message is logged and the
8858 * application is terminated.
8860 * The macro can be turned off in final releases of code by defining
8861 * `G_DISABLE_ASSERT` when compiling the application.
8867 * @expr: the expression to check
8869 * Debugging macro to check an expression is %NULL.
8871 * If the assertion fails (i.e. the expression is not %NULL),
8872 * an error message is logged and the application is either
8873 * terminated or the testcase marked as failed.
8875 * See g_test_set_nonfatal_assertions().
8883 * @expr: the expression to check
8885 * Debugging macro to check that an expression is true.
8887 * If the assertion fails (i.e. the expression is not true),
8888 * an error message is logged and the application is either
8889 * terminated or the testcase marked as failed.
8891 * See g_test_set_nonfatal_assertions().
8898 * g_async_queue_length:
8899 * @queue: a #GAsyncQueue.
8901 * Returns the length of the queue.
8903 * Actually this function returns the number of data items in
8904 * the queue minus the number of waiting threads, so a negative
8905 * value means waiting threads, and a positive value means available
8906 * entries in the @queue. A return value of 0 could mean n entries
8907 * in the queue and n threads waiting. This can happen due to locking
8908 * of the queue or due to scheduling.
8910 * Returns: the length of the @queue
8915 * g_async_queue_length_unlocked:
8916 * @queue: a #GAsyncQueue
8918 * Returns the length of the queue.
8920 * Actually this function returns the number of data items in
8921 * the queue minus the number of waiting threads, so a negative
8922 * value means waiting threads, and a positive value means available
8923 * entries in the @queue. A return value of 0 could mean n entries
8924 * in the queue and n threads waiting. This can happen due to locking
8925 * of the queue or due to scheduling.
8927 * This function must be called while holding the @queue's lock.
8929 * Returns: the length of the @queue.
8934 * g_async_queue_lock:
8935 * @queue: a #GAsyncQueue
8937 * Acquires the @queue's lock. If another thread is already
8938 * holding the lock, this call will block until the lock
8939 * becomes available.
8941 * Call g_async_queue_unlock() to drop the lock again.
8943 * While holding the lock, you can only call the
8944 * g_async_queue_*_unlocked() functions on @queue. Otherwise,
8945 * deadlock may occur.
8950 * g_async_queue_new:
8952 * Creates a new asynchronous queue.
8954 * Returns: a new #GAsyncQueue. Free with g_async_queue_unref()
8959 * g_async_queue_new_full:
8960 * @item_free_func: function to free queue elements
8962 * Creates a new asynchronous queue and sets up a destroy notify
8963 * function that is used to free any remaining queue items when
8964 * the queue is destroyed after the final unref.
8966 * Returns: a new #GAsyncQueue. Free with g_async_queue_unref()
8972 * g_async_queue_pop:
8973 * @queue: a #GAsyncQueue
8975 * Pops data from the @queue. If @queue is empty, this function
8976 * blocks until data becomes available.
8978 * Returns: data from the queue
8983 * g_async_queue_pop_unlocked:
8984 * @queue: a #GAsyncQueue
8986 * Pops data from the @queue. If @queue is empty, this function
8987 * blocks until data becomes available.
8989 * This function must be called while holding the @queue's lock.
8991 * Returns: data from the queue.
8996 * g_async_queue_push:
8997 * @queue: a #GAsyncQueue
8998 * @data: @data to push into the @queue
9000 * Pushes the @data into the @queue. @data must not be %NULL.
9005 * g_async_queue_push_sorted:
9006 * @queue: a #GAsyncQueue
9007 * @data: the @data to push into the @queue
9008 * @func: the #GCompareDataFunc is used to sort @queue
9009 * @user_data: user data passed to @func.
9011 * Inserts @data into @queue using @func to determine the new
9014 * This function requires that the @queue is sorted before pushing on
9015 * new elements, see g_async_queue_sort().
9017 * This function will lock @queue before it sorts the queue and unlock
9018 * it when it is finished.
9020 * For an example of @func see g_async_queue_sort().
9027 * g_async_queue_push_sorted_unlocked:
9028 * @queue: a #GAsyncQueue
9029 * @data: the @data to push into the @queue
9030 * @func: the #GCompareDataFunc is used to sort @queue
9031 * @user_data: user data passed to @func.
9033 * Inserts @data into @queue using @func to determine the new
9036 * The sort function @func is passed two elements of the @queue.
9037 * It should return 0 if they are equal, a negative value if the
9038 * first element should be higher in the @queue or a positive value
9039 * if the first element should be lower in the @queue than the second
9042 * This function requires that the @queue is sorted before pushing on
9043 * new elements, see g_async_queue_sort().
9045 * This function must be called while holding the @queue's lock.
9047 * For an example of @func see g_async_queue_sort().
9054 * g_async_queue_push_unlocked:
9055 * @queue: a #GAsyncQueue
9056 * @data: @data to push into the @queue
9058 * Pushes the @data into the @queue. @data must not be %NULL.
9060 * This function must be called while holding the @queue's lock.
9065 * g_async_queue_ref:
9066 * @queue: a #GAsyncQueue
9068 * Increases the reference count of the asynchronous @queue by 1.
9069 * You do not need to hold the lock to call this function.
9071 * Returns: the @queue that was passed in (since 2.6)
9076 * g_async_queue_ref_unlocked:
9077 * @queue: a #GAsyncQueue
9079 * Increases the reference count of the asynchronous @queue by 1.
9081 * Deprecated: 2.8: Reference counting is done atomically.
9082 * so g_async_queue_ref() can be used regardless of the @queue's
9088 * g_async_queue_sort:
9089 * @queue: a #GAsyncQueue
9090 * @func: the #GCompareDataFunc is used to sort @queue
9091 * @user_data: user data passed to @func
9093 * Sorts @queue using @func.
9095 * The sort function @func is passed two elements of the @queue.
9096 * It should return 0 if they are equal, a negative value if the
9097 * first element should be higher in the @queue or a positive value
9098 * if the first element should be lower in the @queue than the second
9101 * This function will lock @queue before it sorts the queue and unlock
9102 * it when it is finished.
9104 * If you were sorting a list of priority numbers to make sure the
9105 * lowest priority would be at the top of the queue, you could use:
9106 * |[<!-- language="C" -->
9110 * id1 = GPOINTER_TO_INT (element1);
9111 * id2 = GPOINTER_TO_INT (element2);
9113 * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
9121 * g_async_queue_sort_unlocked:
9122 * @queue: a #GAsyncQueue
9123 * @func: the #GCompareDataFunc is used to sort @queue
9124 * @user_data: user data passed to @func
9126 * Sorts @queue using @func.
9128 * The sort function @func is passed two elements of the @queue.
9129 * It should return 0 if they are equal, a negative value if the
9130 * first element should be higher in the @queue or a positive value
9131 * if the first element should be lower in the @queue than the second
9134 * This function must be called while holding the @queue's lock.
9141 * g_async_queue_timed_pop:
9142 * @queue: a #GAsyncQueue
9143 * @end_time: a #GTimeVal, determining the final time
9145 * Pops data from the @queue. If the queue is empty, blocks until
9146 * @end_time or until data becomes available.
9148 * If no data is received before @end_time, %NULL is returned.
9150 * To easily calculate @end_time, a combination of g_get_current_time()
9151 * and g_time_val_add() can be used.
9153 * Returns: data from the queue or %NULL, when no data is
9154 * received before @end_time.
9155 * Deprecated: use g_async_queue_timeout_pop().
9160 * g_async_queue_timed_pop_unlocked:
9161 * @queue: a #GAsyncQueue
9162 * @end_time: a #GTimeVal, determining the final time
9164 * Pops data from the @queue. If the queue is empty, blocks until
9165 * @end_time or until data becomes available.
9167 * If no data is received before @end_time, %NULL is returned.
9169 * To easily calculate @end_time, a combination of g_get_current_time()
9170 * and g_time_val_add() can be used.
9172 * This function must be called while holding the @queue's lock.
9174 * Returns: data from the queue or %NULL, when no data is
9175 * received before @end_time.
9176 * Deprecated: use g_async_queue_timeout_pop_unlocked().
9181 * g_async_queue_timeout_pop:
9182 * @queue: a #GAsyncQueue
9183 * @timeout: the number of microseconds to wait
9185 * Pops data from the @queue. If the queue is empty, blocks for
9186 * @timeout microseconds, or until data becomes available.
9188 * If no data is received before the timeout, %NULL is returned.
9190 * Returns: data from the queue or %NULL, when no data is
9191 * received before the timeout.
9196 * g_async_queue_timeout_pop_unlocked:
9197 * @queue: a #GAsyncQueue
9198 * @timeout: the number of microseconds to wait
9200 * Pops data from the @queue. If the queue is empty, blocks for
9201 * @timeout microseconds, or until data becomes available.
9203 * If no data is received before the timeout, %NULL is returned.
9205 * This function must be called while holding the @queue's lock.
9207 * Returns: data from the queue or %NULL, when no data is
9208 * received before the timeout.
9213 * g_async_queue_try_pop:
9214 * @queue: a #GAsyncQueue
9216 * Tries to pop data from the @queue. If no data is available,
9217 * %NULL is returned.
9219 * Returns: data from the queue or %NULL, when no data is
9220 * available immediately.
9225 * g_async_queue_try_pop_unlocked:
9226 * @queue: a #GAsyncQueue
9228 * Tries to pop data from the @queue. If no data is available,
9229 * %NULL is returned.
9231 * This function must be called while holding the @queue's lock.
9233 * Returns: data from the queue or %NULL, when no data is
9234 * available immediately.
9239 * g_async_queue_unlock:
9240 * @queue: a #GAsyncQueue
9242 * Releases the queue's lock.
9244 * Calling this function when you have not acquired
9245 * the with g_async_queue_lock() leads to undefined
9251 * g_async_queue_unref:
9252 * @queue: a #GAsyncQueue.
9254 * Decreases the reference count of the asynchronous @queue by 1.
9256 * If the reference count went to 0, the @queue will be destroyed
9257 * and the memory allocated will be freed. So you are not allowed
9258 * to use the @queue afterwards, as it might have disappeared.
9259 * You do not need to hold the lock to call this function.
9264 * g_async_queue_unref_and_unlock:
9265 * @queue: a #GAsyncQueue
9267 * Decreases the reference count of the asynchronous @queue by 1
9268 * and releases the lock. This function must be called while holding
9269 * the @queue's lock. If the reference count went to 0, the @queue
9270 * will be destroyed and the memory allocated will be freed.
9272 * Deprecated: 2.8: Reference counting is done atomically.
9273 * so g_async_queue_unref() can be used regardless of the @queue's
9280 * @func: (scope async): the function to call on normal program termination.
9282 * Specifies a function to be called at normal program termination.
9284 * Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor
9285 * macro that maps to a call to the atexit() function in the C
9286 * library. This means that in case the code that calls g_atexit(),
9287 * i.e. atexit(), is in a DLL, the function will be called when the
9288 * DLL is detached from the program. This typically makes more sense
9289 * than that the function is called when the GLib DLL is detached,
9290 * which happened earlier when g_atexit() was a function in the GLib
9293 * The behaviour of atexit() in the context of dynamically loaded
9294 * modules is not formally specified and varies wildly.
9296 * On POSIX systems, calling g_atexit() (or atexit()) in a dynamically
9297 * loaded module which is unloaded before the program terminates might
9298 * well cause a crash at program exit.
9300 * Some POSIX systems implement atexit() like Windows, and have each
9301 * dynamically loaded module maintain an own atexit chain that is
9302 * called when the module is unloaded.
9304 * On other POSIX systems, before a dynamically loaded module is
9305 * unloaded, the registered atexit functions (if any) residing in that
9306 * module are called, regardless where the code that registered them
9307 * resided. This is presumably the most robust approach.
9309 * As can be seen from the above, for portability it's best to avoid
9310 * calling g_atexit() (or atexit()) except in the main executable of a
9313 * Deprecated: 2.32: It is best to avoid g_atexit().
9319 * @atomic: a pointer to a #gint or #guint
9320 * @val: the value to add
9322 * Atomically adds @val to the value of @atomic.
9324 * Think of this operation as an atomic version of
9325 * `{ tmp = *atomic; *atomic += val; return tmp; }`.
9327 * This call acts as a full compiler and hardware memory barrier.
9329 * Before version 2.30, this function did not return a value
9330 * (but g_atomic_int_exchange_and_add() did, and had the same meaning).
9332 * Returns: the value of @atomic before the add, signed
9339 * @atomic: a pointer to a #gint or #guint
9340 * @val: the value to 'and'
9342 * Performs an atomic bitwise 'and' of the value of @atomic and @val,
9343 * storing the result back in @atomic.
9345 * This call acts as a full compiler and hardware memory barrier.
9347 * Think of this operation as an atomic version of
9348 * `{ tmp = *atomic; *atomic &= val; return tmp; }`.
9350 * Returns: the value of @atomic before the operation, unsigned
9356 * g_atomic_int_compare_and_exchange:
9357 * @atomic: a pointer to a #gint or #guint
9358 * @oldval: the value to compare with
9359 * @newval: the value to conditionally replace with
9361 * Compares @atomic to @oldval and, if equal, sets it to @newval.
9362 * If @atomic was not equal to @oldval then no change occurs.
9364 * This compare and exchange is done atomically.
9366 * Think of this operation as an atomic version of
9367 * `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
9369 * This call acts as a full compiler and hardware memory barrier.
9371 * Returns: %TRUE if the exchange took place
9377 * g_atomic_int_dec_and_test:
9378 * @atomic: a pointer to a #gint or #guint
9380 * Decrements the value of @atomic by 1.
9382 * Think of this operation as an atomic version of
9383 * `{ *atomic -= 1; return (*atomic == 0); }`.
9385 * This call acts as a full compiler and hardware memory barrier.
9387 * Returns: %TRUE if the resultant value is zero
9393 * g_atomic_int_exchange_and_add:
9394 * @atomic: a pointer to a #gint
9395 * @val: the value to add
9397 * This function existed before g_atomic_int_add() returned the prior
9398 * value of the integer (which it now does). It is retained only for
9399 * compatibility reasons. Don't use this function in new code.
9401 * Returns: the value of @atomic before the add, signed
9403 * Deprecated: 2.30: Use g_atomic_int_add() instead.
9409 * @atomic: a pointer to a #gint or #guint
9411 * Gets the current value of @atomic.
9413 * This call acts as a full compiler and hardware
9414 * memory barrier (before the get).
9416 * Returns: the value of the integer
9423 * @atomic: a pointer to a #gint or #guint
9425 * Increments the value of @atomic by 1.
9427 * Think of this operation as an atomic version of `{ *atomic += 1; }`.
9429 * This call acts as a full compiler and hardware memory barrier.
9437 * @atomic: a pointer to a #gint or #guint
9438 * @val: the value to 'or'
9440 * Performs an atomic bitwise 'or' of the value of @atomic and @val,
9441 * storing the result back in @atomic.
9443 * Think of this operation as an atomic version of
9444 * `{ tmp = *atomic; *atomic |= val; return tmp; }`.
9446 * This call acts as a full compiler and hardware memory barrier.
9448 * Returns: the value of @atomic before the operation, unsigned
9455 * @atomic: a pointer to a #gint or #guint
9456 * @newval: a new value to store
9458 * Sets the value of @atomic to @newval.
9460 * This call acts as a full compiler and hardware
9461 * memory barrier (after the set).
9469 * @atomic: a pointer to a #gint or #guint
9470 * @val: the value to 'xor'
9472 * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
9473 * storing the result back in @atomic.
9475 * Think of this operation as an atomic version of
9476 * `{ tmp = *atomic; *atomic ^= val; return tmp; }`.
9478 * This call acts as a full compiler and hardware memory barrier.
9480 * Returns: the value of @atomic before the operation, unsigned
9486 * g_atomic_pointer_add:
9487 * @atomic: a pointer to a #gpointer-sized value
9488 * @val: the value to add
9490 * Atomically adds @val to the value of @atomic.
9492 * Think of this operation as an atomic version of
9493 * `{ tmp = *atomic; *atomic += val; return tmp; }`.
9495 * This call acts as a full compiler and hardware memory barrier.
9497 * Returns: the value of @atomic before the add, signed
9503 * g_atomic_pointer_and:
9504 * @atomic: a pointer to a #gpointer-sized value
9505 * @val: the value to 'and'
9507 * Performs an atomic bitwise 'and' of the value of @atomic and @val,
9508 * storing the result back in @atomic.
9510 * Think of this operation as an atomic version of
9511 * `{ tmp = *atomic; *atomic &= val; return tmp; }`.
9513 * This call acts as a full compiler and hardware memory barrier.
9515 * Returns: the value of @atomic before the operation, unsigned
9521 * g_atomic_pointer_compare_and_exchange:
9522 * @atomic: a pointer to a #gpointer-sized value
9523 * @oldval: the value to compare with
9524 * @newval: the value to conditionally replace with
9526 * Compares @atomic to @oldval and, if equal, sets it to @newval.
9527 * If @atomic was not equal to @oldval then no change occurs.
9529 * This compare and exchange is done atomically.
9531 * Think of this operation as an atomic version of
9532 * `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
9534 * This call acts as a full compiler and hardware memory barrier.
9536 * Returns: %TRUE if the exchange took place
9542 * g_atomic_pointer_get:
9543 * @atomic: a pointer to a #gpointer-sized value
9545 * Gets the current value of @atomic.
9547 * This call acts as a full compiler and hardware
9548 * memory barrier (before the get).
9550 * Returns: the value of the pointer
9556 * g_atomic_pointer_or:
9557 * @atomic: a pointer to a #gpointer-sized value
9558 * @val: the value to 'or'
9560 * Performs an atomic bitwise 'or' of the value of @atomic and @val,
9561 * storing the result back in @atomic.
9563 * Think of this operation as an atomic version of
9564 * `{ tmp = *atomic; *atomic |= val; return tmp; }`.
9566 * This call acts as a full compiler and hardware memory barrier.
9568 * Returns: the value of @atomic before the operation, unsigned
9574 * g_atomic_pointer_set:
9575 * @atomic: a pointer to a #gpointer-sized value
9576 * @newval: a new value to store
9578 * Sets the value of @atomic to @newval.
9580 * This call acts as a full compiler and hardware
9581 * memory barrier (after the set).
9588 * g_atomic_pointer_xor:
9589 * @atomic: a pointer to a #gpointer-sized value
9590 * @val: the value to 'xor'
9592 * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
9593 * storing the result back in @atomic.
9595 * Think of this operation as an atomic version of
9596 * `{ tmp = *atomic; *atomic ^= val; return tmp; }`.
9598 * This call acts as a full compiler and hardware memory barrier.
9600 * Returns: the value of @atomic before the operation, unsigned
9607 * @text: zero-terminated string with base64 text to decode
9608 * @out_len: (out): The length of the decoded data is written here
9610 * Decode a sequence of Base-64 encoded text into binary data. Note
9611 * that the returned binary data is not necessarily zero-terminated,
9612 * so it should not be used as a character string.
9614 * Returns: (transfer full) (array length=out_len) (element-type guint8):
9615 * newly allocated buffer containing the binary data
9616 * that @text represents. The returned buffer must
9617 * be freed with g_free().
9623 * g_base64_decode_inplace:
9624 * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated
9625 * string with base64 text to decode
9626 * @out_len: (inout): The length of the decoded data is written here
9628 * Decode a sequence of Base-64 encoded text into binary data
9629 * by overwriting the input data.
9631 * Returns: (transfer none): The binary data that @text responds. This pointer
9632 * is the same as the input @text.
9638 * g_base64_decode_step:
9639 * @in: (array length=len) (element-type guint8): binary input data
9640 * @len: max length of @in data to decode
9641 * @out: (out) (array) (element-type guint8): output buffer
9642 * @state: (inout): Saved state between steps, initialize to 0
9643 * @save: (inout): Saved state between steps, initialize to 0
9645 * Incrementally decode a sequence of binary data from its Base-64 stringified
9646 * representation. By calling this function multiple times you can convert
9647 * data in chunks to avoid having to have the full encoded data in memory.
9649 * The output buffer must be large enough to fit all the data that will
9650 * be written to it. Since base64 encodes 3 bytes in 4 chars you need
9651 * at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
9654 * Returns: The number of bytes of output that was written
9661 * @data: (array length=len) (element-type guint8): the binary data to encode
9662 * @len: the length of @data
9664 * Encode a sequence of binary data into its Base-64 stringified
9667 * Returns: (transfer full): a newly allocated, zero-terminated Base-64
9668 * encoded string representing @data. The returned string must
9669 * be freed with g_free().
9675 * g_base64_encode_close:
9676 * @break_lines: whether to break long lines
9677 * @out: (out) (array) (element-type guint8): pointer to destination buffer
9678 * @state: (inout): Saved state from g_base64_encode_step()
9679 * @save: (inout): Saved state from g_base64_encode_step()
9681 * Flush the status from a sequence of calls to g_base64_encode_step().
9683 * The output buffer must be large enough to fit all the data that will
9684 * be written to it. It will need up to 4 bytes, or up to 5 bytes if
9685 * line-breaking is enabled.
9687 * Returns: The number of bytes of output that was written
9693 * g_base64_encode_step:
9694 * @in: (array length=len) (element-type guint8): the binary data to encode
9695 * @len: the length of @in
9696 * @break_lines: whether to break long lines
9697 * @out: (out) (array) (element-type guint8): pointer to destination buffer
9698 * @state: (inout): Saved state between steps, initialize to 0
9699 * @save: (inout): Saved state between steps, initialize to 0
9701 * Incrementally encode a sequence of binary data into its Base-64 stringified
9702 * representation. By calling this function multiple times you can convert
9703 * data in chunks to avoid having to have the full encoded data in memory.
9705 * When all of the data has been converted you must call
9706 * g_base64_encode_close() to flush the saved state.
9708 * The output buffer must be large enough to fit all the data that will
9709 * be written to it. Due to the way base64 encodes you will need
9710 * at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
9711 * non-zero state). If you enable line-breaking you will need at least:
9712 * ((@len / 3 + 1) * 4 + 4) / 72 + 1 bytes of extra space.
9714 * @break_lines is typically used when putting base64-encoded data in emails.
9715 * It breaks the lines at 72 columns instead of putting all of the text on
9716 * the same line. This avoids problems with long lines in the email system.
9717 * Note however that it breaks the lines with `LF` characters, not
9718 * `CR LF` sequences, so the result cannot be passed directly to SMTP
9719 * or certain other protocols.
9721 * Returns: The number of bytes of output that was written
9728 * @file_name: the name of the file
9730 * Gets the name of the file without any leading directory
9731 * components. It returns a pointer into the given file name
9734 * Returns: the name of the file without any leading
9735 * directory components
9736 * Deprecated: 2.2: Use g_path_get_basename() instead, but notice
9737 * that g_path_get_basename() allocates new memory for the
9738 * returned string, unlike this function which returns a pointer
9739 * into the argument.
9745 * @address: a pointer to an integer
9746 * @lock_bit: a bit value between 0 and 31
9748 * Sets the indicated @lock_bit in @address. If the bit is already
9749 * set, this call will block until g_bit_unlock() unsets the
9750 * corresponding bit.
9752 * Attempting to lock on two different bits within the same integer is
9753 * not supported and will very probably cause deadlocks.
9755 * The value of the bit that is set is (1u << @bit). If @bit is not
9756 * between 0 and 31 then the result is undefined.
9758 * This function accesses @address atomically. All other accesses to
9759 * @address must be atomic in order for this function to work
9768 * @mask: a #gulong containing flags
9769 * @nth_bit: the index of the bit to start the search from
9771 * Find the position of the first bit set in @mask, searching
9772 * from (but not including) @nth_bit upwards. Bits are numbered
9773 * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
9774 * usually). To start searching from the 0th bit, set @nth_bit to -1.
9776 * Returns: the index of the first bit set which is higher than @nth_bit
9782 * @mask: a #gulong containing flags
9783 * @nth_bit: the index of the bit to start the search from
9785 * Find the position of the first bit set in @mask, searching
9786 * from (but not including) @nth_bit downwards. Bits are numbered
9787 * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
9788 * usually). To start searching from the last bit, set @nth_bit to
9789 * -1 or GLIB_SIZEOF_LONG * 8.
9791 * Returns: the index of the first bit set which is lower than @nth_bit
9799 * Gets the number of bits used to hold @number,
9800 * e.g. if @number is 4, 3 bits are needed.
9802 * Returns: the number of bits used to hold @number
9808 * @address: a pointer to an integer
9809 * @lock_bit: a bit value between 0 and 31
9811 * Sets the indicated @lock_bit in @address, returning %TRUE if
9812 * successful. If the bit is already set, returns %FALSE immediately.
9814 * Attempting to lock on two different bits within the same integer is
9817 * The value of the bit that is set is (1u << @bit). If @bit is not
9818 * between 0 and 31 then the result is undefined.
9820 * This function accesses @address atomically. All other accesses to
9821 * @address must be atomic in order for this function to work
9824 * Returns: %TRUE if the lock was acquired
9831 * @address: a pointer to an integer
9832 * @lock_bit: a bit value between 0 and 31
9834 * Clears the indicated @lock_bit in @address. If another thread is
9835 * currently blocked in g_bit_lock() on this same bit then it will be
9838 * This function accesses @address atomically. All other accesses to
9839 * @address must be atomic in order for this function to work
9847 * g_bookmark_file_add_application:
9848 * @bookmark: a #GBookmarkFile
9850 * @name: (allow-none): the name of the application registering the bookmark
9852 * @exec: (allow-none): command line to be used to launch the bookmark or %NULL
9854 * Adds the application with @name and @exec to the list of
9855 * applications that have registered a bookmark for @uri into
9858 * Every bookmark inside a #GBookmarkFile must have at least an
9859 * application registered. Each application must provide a name, a
9860 * command line useful for launching the bookmark, the number of times
9861 * the bookmark has been registered by the application and the last
9862 * time the application registered this bookmark.
9864 * If @name is %NULL, the name of the application will be the
9865 * same returned by g_get_application_name(); if @exec is %NULL, the
9866 * command line will be a composition of the program name as
9867 * returned by g_get_prgname() and the "\%u" modifier, which will be
9868 * expanded to the bookmark's URI.
9870 * This function will automatically take care of updating the
9871 * registrations count and timestamping in case an application
9872 * with the same @name had already registered a bookmark for
9873 * @uri inside @bookmark.
9875 * If no bookmark for @uri is found, one is created.
9882 * g_bookmark_file_add_group:
9883 * @bookmark: a #GBookmarkFile
9885 * @group: the group name to be added
9887 * Adds @group to the list of groups to which the bookmark for @uri
9890 * If no bookmark for @uri is found then it is created.
9897 * g_bookmark_file_free:
9898 * @bookmark: a #GBookmarkFile
9900 * Frees a #GBookmarkFile.
9907 * g_bookmark_file_get_added:
9908 * @bookmark: a #GBookmarkFile
9910 * @error: return location for a #GError, or %NULL
9912 * Gets the time the bookmark for @uri was added to @bookmark
9914 * In the event the URI cannot be found, -1 is returned and
9915 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
9917 * Returns: a timestamp
9923 * g_bookmark_file_get_app_info:
9924 * @bookmark: a #GBookmarkFile
9926 * @name: an application's name
9927 * @exec: (allow-none) (out): return location for the command line of the application, or %NULL
9928 * @count: (allow-none) (out): return location for the registration count, or %NULL
9929 * @stamp: (allow-none) (out): return location for the last registration time, or %NULL
9930 * @error: return location for a #GError, or %NULL
9932 * Gets the registration informations of @app_name for the bookmark for
9933 * @uri. See g_bookmark_file_set_app_info() for more informations about
9934 * the returned data.
9936 * The string returned in @app_exec must be freed.
9938 * In the event the URI cannot be found, %FALSE is returned and
9939 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
9940 * event that no application with name @app_name has registered a bookmark
9941 * for @uri, %FALSE is returned and error is set to
9942 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
9943 * the command line fails, an error of the #G_SHELL_ERROR domain is
9944 * set and %FALSE is returned.
9946 * Returns: %TRUE on success.
9952 * g_bookmark_file_get_applications:
9953 * @bookmark: a #GBookmarkFile
9955 * @length: (allow-none) (out): return location of the length of the returned list, or %NULL
9956 * @error: return location for a #GError, or %NULL
9958 * Retrieves the names of the applications that have registered the
9959 * bookmark for @uri.
9961 * In the event the URI cannot be found, %NULL is returned and
9962 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
9964 * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings.
9965 * Use g_strfreev() to free it.
9971 * g_bookmark_file_get_description:
9972 * @bookmark: a #GBookmarkFile
9974 * @error: return location for a #GError, or %NULL
9976 * Retrieves the description of the bookmark for @uri.
9978 * In the event the URI cannot be found, %NULL is returned and
9979 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
9981 * Returns: a newly allocated string or %NULL if the specified
9982 * URI cannot be found.
9988 * g_bookmark_file_get_groups:
9989 * @bookmark: a #GBookmarkFile
9991 * @length: (allow-none) (out): return location for the length of the returned string, or %NULL
9992 * @error: return location for a #GError, or %NULL
9994 * Retrieves the list of group names of the bookmark for @uri.
9996 * In the event the URI cannot be found, %NULL is returned and
9997 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
9999 * The returned array is %NULL terminated, so @length may optionally
10002 * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names.
10003 * Use g_strfreev() to free it.
10009 * g_bookmark_file_get_icon:
10010 * @bookmark: a #GBookmarkFile
10011 * @uri: a valid URI
10012 * @href: (allow-none) (out): return location for the icon's location or %NULL
10013 * @mime_type: (allow-none) (out): return location for the icon's MIME type or %NULL
10014 * @error: return location for a #GError or %NULL
10016 * Gets the icon of the bookmark for @uri.
10018 * In the event the URI cannot be found, %FALSE is returned and
10019 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10021 * Returns: %TRUE if the icon for the bookmark for the URI was found.
10022 * You should free the returned strings.
10028 * g_bookmark_file_get_is_private:
10029 * @bookmark: a #GBookmarkFile
10030 * @uri: a valid URI
10031 * @error: return location for a #GError, or %NULL
10033 * Gets whether the private flag of the bookmark for @uri is set.
10035 * In the event the URI cannot be found, %FALSE is returned and
10036 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
10037 * event that the private flag cannot be found, %FALSE is returned and
10038 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
10040 * Returns: %TRUE if the private flag is set, %FALSE otherwise.
10046 * g_bookmark_file_get_mime_type:
10047 * @bookmark: a #GBookmarkFile
10048 * @uri: a valid URI
10049 * @error: return location for a #GError, or %NULL
10051 * Retrieves the MIME type of the resource pointed by @uri.
10053 * In the event the URI cannot be found, %NULL is returned and
10054 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
10055 * event that the MIME type cannot be found, %NULL is returned and
10056 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
10058 * Returns: a newly allocated string or %NULL if the specified
10059 * URI cannot be found.
10065 * g_bookmark_file_get_modified:
10066 * @bookmark: a #GBookmarkFile
10067 * @uri: a valid URI
10068 * @error: return location for a #GError, or %NULL
10070 * Gets the time when the bookmark for @uri was last modified.
10072 * In the event the URI cannot be found, -1 is returned and
10073 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10075 * Returns: a timestamp
10081 * g_bookmark_file_get_size:
10082 * @bookmark: a #GBookmarkFile
10084 * Gets the number of bookmarks inside @bookmark.
10086 * Returns: the number of bookmarks
10092 * g_bookmark_file_get_title:
10093 * @bookmark: a #GBookmarkFile
10094 * @uri: (allow-none): a valid URI or %NULL
10095 * @error: return location for a #GError, or %NULL
10097 * Returns the title of the bookmark for @uri.
10099 * If @uri is %NULL, the title of @bookmark is returned.
10101 * In the event the URI cannot be found, %NULL is returned and
10102 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10104 * Returns: a newly allocated string or %NULL if the specified
10105 * URI cannot be found.
10111 * g_bookmark_file_get_uris:
10112 * @bookmark: a #GBookmarkFile
10113 * @length: (allow-none) (out): return location for the number of returned URIs, or %NULL
10115 * Returns all URIs of the bookmarks in the bookmark file @bookmark.
10116 * The array of returned URIs will be %NULL-terminated, so @length may
10117 * optionally be %NULL.
10119 * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings.
10120 * Use g_strfreev() to free it.
10126 * g_bookmark_file_get_visited:
10127 * @bookmark: a #GBookmarkFile
10128 * @uri: a valid URI
10129 * @error: return location for a #GError, or %NULL
10131 * Gets the time the bookmark for @uri was last visited.
10133 * In the event the URI cannot be found, -1 is returned and
10134 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10136 * Returns: a timestamp.
10142 * g_bookmark_file_has_application:
10143 * @bookmark: a #GBookmarkFile
10144 * @uri: a valid URI
10145 * @name: the name of the application
10146 * @error: return location for a #GError or %NULL
10148 * Checks whether the bookmark for @uri inside @bookmark has been
10149 * registered by application @name.
10151 * In the event the URI cannot be found, %FALSE is returned and
10152 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10154 * Returns: %TRUE if the application @name was found
10160 * g_bookmark_file_has_group:
10161 * @bookmark: a #GBookmarkFile
10162 * @uri: a valid URI
10163 * @group: the group name to be searched
10164 * @error: return location for a #GError, or %NULL
10166 * Checks whether @group appears in the list of groups to which
10167 * the bookmark for @uri belongs to.
10169 * In the event the URI cannot be found, %FALSE is returned and
10170 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10172 * Returns: %TRUE if @group was found.
10178 * g_bookmark_file_has_item:
10179 * @bookmark: a #GBookmarkFile
10180 * @uri: a valid URI
10182 * Looks whether the desktop bookmark has an item with its URI set to @uri.
10184 * Returns: %TRUE if @uri is inside @bookmark, %FALSE otherwise
10190 * g_bookmark_file_load_from_data:
10191 * @bookmark: an empty #GBookmarkFile struct
10192 * @data: desktop bookmarks loaded in memory
10193 * @length: the length of @data in bytes
10194 * @error: return location for a #GError, or %NULL
10196 * Loads a bookmark file from memory into an empty #GBookmarkFile
10197 * structure. If the object cannot be created then @error is set to a
10198 * #GBookmarkFileError.
10200 * Returns: %TRUE if a desktop bookmark could be loaded.
10206 * g_bookmark_file_load_from_data_dirs:
10207 * @bookmark: a #GBookmarkFile
10208 * @file: a relative path to a filename to open and parse
10209 * @full_path: (allow-none): return location for a string containing the full path
10210 * of the file, or %NULL
10211 * @error: return location for a #GError, or %NULL
10213 * This function looks for a desktop bookmark file named @file in the
10214 * paths returned from g_get_user_data_dir() and g_get_system_data_dirs(),
10215 * loads the file into @bookmark and returns the file's full path in
10216 * @full_path. If the file could not be loaded then an %error is
10217 * set to either a #GFileError or #GBookmarkFileError.
10219 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
10225 * g_bookmark_file_load_from_file:
10226 * @bookmark: an empty #GBookmarkFile struct
10227 * @filename: the path of a filename to load, in the GLib file name encoding
10228 * @error: return location for a #GError, or %NULL
10230 * Loads a desktop bookmark file into an empty #GBookmarkFile structure.
10231 * If the file could not be loaded then @error is set to either a #GFileError
10232 * or #GBookmarkFileError.
10234 * Returns: %TRUE if a desktop bookmark file could be loaded
10240 * g_bookmark_file_move_item:
10241 * @bookmark: a #GBookmarkFile
10242 * @old_uri: a valid URI
10243 * @new_uri: (allow-none): a valid URI, or %NULL
10244 * @error: return location for a #GError or %NULL
10246 * Changes the URI of a bookmark item from @old_uri to @new_uri. Any
10247 * existing bookmark for @new_uri will be overwritten. If @new_uri is
10248 * %NULL, then the bookmark is removed.
10250 * In the event the URI cannot be found, %FALSE is returned and
10251 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10253 * Returns: %TRUE if the URI was successfully changed
10259 * g_bookmark_file_new:
10261 * Creates a new empty #GBookmarkFile object.
10263 * Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data()
10264 * or g_bookmark_file_load_from_data_dirs() to read an existing bookmark
10267 * Returns: an empty #GBookmarkFile
10273 * g_bookmark_file_remove_application:
10274 * @bookmark: a #GBookmarkFile
10275 * @uri: a valid URI
10276 * @name: the name of the application
10277 * @error: return location for a #GError or %NULL
10279 * Removes application registered with @name from the list of applications
10280 * that have registered a bookmark for @uri inside @bookmark.
10282 * In the event the URI cannot be found, %FALSE is returned and
10283 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10284 * In the event that no application with name @app_name has registered
10285 * a bookmark for @uri, %FALSE is returned and error is set to
10286 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.
10288 * Returns: %TRUE if the application was successfully removed.
10294 * g_bookmark_file_remove_group:
10295 * @bookmark: a #GBookmarkFile
10296 * @uri: a valid URI
10297 * @group: the group name to be removed
10298 * @error: return location for a #GError, or %NULL
10300 * Removes @group from the list of groups to which the bookmark
10301 * for @uri belongs to.
10303 * In the event the URI cannot be found, %FALSE is returned and
10304 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10305 * In the event no group was defined, %FALSE is returned and
10306 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
10308 * Returns: %TRUE if @group was successfully removed.
10314 * g_bookmark_file_remove_item:
10315 * @bookmark: a #GBookmarkFile
10316 * @uri: a valid URI
10317 * @error: return location for a #GError, or %NULL
10319 * Removes the bookmark for @uri from the bookmark file @bookmark.
10321 * Returns: %TRUE if the bookmark was removed successfully.
10327 * g_bookmark_file_set_added:
10328 * @bookmark: a #GBookmarkFile
10329 * @uri: a valid URI
10330 * @added: a timestamp or -1 to use the current time
10332 * Sets the time the bookmark for @uri was added into @bookmark.
10334 * If no bookmark for @uri is found then it is created.
10341 * g_bookmark_file_set_app_info:
10342 * @bookmark: a #GBookmarkFile
10343 * @uri: a valid URI
10344 * @name: an application's name
10345 * @exec: an application's command line
10346 * @count: the number of registrations done for this application
10347 * @stamp: the time of the last registration for this application
10348 * @error: return location for a #GError or %NULL
10350 * Sets the meta-data of application @name inside the list of
10351 * applications that have registered a bookmark for @uri inside
10354 * You should rarely use this function; use g_bookmark_file_add_application()
10355 * and g_bookmark_file_remove_application() instead.
10357 * @name can be any UTF-8 encoded string used to identify an
10359 * @exec can have one of these two modifiers: "\%f", which will
10360 * be expanded as the local file name retrieved from the bookmark's
10361 * URI; "\%u", which will be expanded as the bookmark's URI.
10362 * The expansion is done automatically when retrieving the stored
10363 * command line using the g_bookmark_file_get_app_info() function.
10364 * @count is the number of times the application has registered the
10365 * bookmark; if is < 0, the current registration count will be increased
10366 * by one, if is 0, the application with @name will be removed from
10367 * the list of registered applications.
10368 * @stamp is the Unix time of the last registration; if it is -1, the
10369 * current time will be used.
10371 * If you try to remove an application by setting its registration count to
10372 * zero, and no bookmark for @uri is found, %FALSE is returned and
10373 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
10374 * in the event that no application @name has registered a bookmark
10375 * for @uri, %FALSE is returned and error is set to
10376 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
10377 * for @uri is found, one is created.
10379 * Returns: %TRUE if the application's meta-data was successfully
10386 * g_bookmark_file_set_description:
10387 * @bookmark: a #GBookmarkFile
10388 * @uri: (allow-none): a valid URI or %NULL
10389 * @description: a string
10391 * Sets @description as the description of the bookmark for @uri.
10393 * If @uri is %NULL, the description of @bookmark is set.
10395 * If a bookmark for @uri cannot be found then it is created.
10402 * g_bookmark_file_set_groups:
10403 * @bookmark: a #GBookmarkFile
10404 * @uri: an item's URI
10405 * @groups: (allow-none): an array of group names, or %NULL to remove all groups
10406 * @length: number of group name values in @groups
10408 * Sets a list of group names for the item with URI @uri. Each previously
10409 * set group name list is removed.
10411 * If @uri cannot be found then an item for it is created.
10418 * g_bookmark_file_set_icon:
10419 * @bookmark: a #GBookmarkFile
10420 * @uri: a valid URI
10421 * @href: (allow-none): the URI of the icon for the bookmark, or %NULL
10422 * @mime_type: the MIME type of the icon for the bookmark
10424 * Sets the icon for the bookmark for @uri. If @href is %NULL, unsets
10425 * the currently set icon. @href can either be a full URL for the icon
10426 * file or the icon name following the Icon Naming specification.
10428 * If no bookmark for @uri is found one is created.
10435 * g_bookmark_file_set_is_private:
10436 * @bookmark: a #GBookmarkFile
10437 * @uri: a valid URI
10438 * @is_private: %TRUE if the bookmark should be marked as private
10440 * Sets the private flag of the bookmark for @uri.
10442 * If a bookmark for @uri cannot be found then it is created.
10449 * g_bookmark_file_set_mime_type:
10450 * @bookmark: a #GBookmarkFile
10451 * @uri: a valid URI
10452 * @mime_type: a MIME type
10454 * Sets @mime_type as the MIME type of the bookmark for @uri.
10456 * If a bookmark for @uri cannot be found then it is created.
10463 * g_bookmark_file_set_modified:
10464 * @bookmark: a #GBookmarkFile
10465 * @uri: a valid URI
10466 * @modified: a timestamp or -1 to use the current time
10468 * Sets the last time the bookmark for @uri was last modified.
10470 * If no bookmark for @uri is found then it is created.
10472 * The "modified" time should only be set when the bookmark's meta-data
10473 * was actually changed. Every function of #GBookmarkFile that
10474 * modifies a bookmark also changes the modification time, except for
10475 * g_bookmark_file_set_visited().
10482 * g_bookmark_file_set_title:
10483 * @bookmark: a #GBookmarkFile
10484 * @uri: (allow-none): a valid URI or %NULL
10485 * @title: a UTF-8 encoded string
10487 * Sets @title as the title of the bookmark for @uri inside the
10488 * bookmark file @bookmark.
10490 * If @uri is %NULL, the title of @bookmark is set.
10492 * If a bookmark for @uri cannot be found then it is created.
10499 * g_bookmark_file_set_visited:
10500 * @bookmark: a #GBookmarkFile
10501 * @uri: a valid URI
10502 * @visited: a timestamp or -1 to use the current time
10504 * Sets the time the bookmark for @uri was last visited.
10506 * If no bookmark for @uri is found then it is created.
10508 * The "visited" time should only be set if the bookmark was launched,
10509 * either using the command line retrieved by g_bookmark_file_get_app_info()
10510 * or by the default application for the bookmark's MIME type, retrieved
10511 * using g_bookmark_file_get_mime_type(). Changing the "visited" time
10512 * does not affect the "modified" time.
10519 * g_bookmark_file_to_data:
10520 * @bookmark: a #GBookmarkFile
10521 * @length: (allow-none) (out): return location for the length of the returned string, or %NULL
10522 * @error: return location for a #GError, or %NULL
10524 * This function outputs @bookmark as a string.
10526 * Returns: a newly allocated string holding
10527 * the contents of the #GBookmarkFile
10533 * g_bookmark_file_to_file:
10534 * @bookmark: a #GBookmarkFile
10535 * @filename: path of the output file
10536 * @error: return location for a #GError, or %NULL
10538 * This function outputs @bookmark into a file. The write process is
10539 * guaranteed to be atomic by using g_file_set_contents() internally.
10541 * Returns: %TRUE if the file was successfully written.
10547 * g_build_filename:
10548 * @first_element: the first element in the path
10549 * @...: remaining elements in path, terminated by %NULL
10551 * Creates a filename from a series of elements using the correct
10552 * separator for filenames.
10554 * On Unix, this function behaves identically to `g_build_path
10555 * (G_DIR_SEPARATOR_S, first_element, ....)`.
10557 * On Windows, it takes into account that either the backslash
10558 * (`\` or slash (`/`) can be used as separator in filenames, but
10559 * otherwise behaves as on UNIX. When file pathname separators need
10560 * to be inserted, the one that last previously occurred in the
10561 * parameters (reading from left to right) is used.
10563 * No attempt is made to force the resulting filename to be an absolute
10564 * path. If the first element is a relative path, the result will
10565 * be a relative path.
10567 * Returns: a newly-allocated string that must be freed with g_free().
10572 * g_build_filenamev:
10573 * @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
10575 * Behaves exactly like g_build_filename(), but takes the path elements
10576 * as a string array, instead of varargs. This function is mainly
10577 * meant for language bindings.
10579 * Returns: a newly-allocated string that must be freed with g_free().
10586 * @separator: a string used to separator the elements of the path.
10587 * @first_element: the first element in the path
10588 * @...: remaining elements in path, terminated by %NULL
10590 * Creates a path from a series of elements using @separator as the
10591 * separator between elements. At the boundary between two elements,
10592 * any trailing occurrences of separator in the first element, or
10593 * leading occurrences of separator in the second element are removed
10594 * and exactly one copy of the separator is inserted.
10596 * Empty elements are ignored.
10598 * The number of leading copies of the separator on the result is
10599 * the same as the number of leading copies of the separator on
10600 * the first non-empty element.
10602 * The number of trailing copies of the separator on the result is
10603 * the same as the number of trailing copies of the separator on
10604 * the last non-empty element. (Determination of the number of
10605 * trailing copies is done without stripping leading copies, so
10606 * if the separator is `ABA`, then `ABABA` has 1 trailing copy.)
10608 * However, if there is only a single non-empty element, and there
10609 * are no characters in that element not part of the leading or
10610 * trailing separators, then the result is exactly the original value
10613 * Other than for determination of the number of leading and trailing
10614 * copies of the separator, elements consisting only of copies
10615 * of the separator are ignored.
10617 * Returns: a newly-allocated string that must be freed with g_free().
10623 * @separator: a string used to separator the elements of the path.
10624 * @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
10626 * Behaves exactly like g_build_path(), but takes the path elements
10627 * as a string array, instead of varargs. This function is mainly
10628 * meant for language bindings.
10630 * Returns: a newly-allocated string that must be freed with g_free().
10636 * g_byte_array_append:
10637 * @array: a #GByteArray
10638 * @data: the byte data to be added
10639 * @len: the number of bytes to add
10641 * Adds the given bytes to the end of the #GByteArray.
10642 * The array will grow in size automatically if necessary.
10644 * Returns: the #GByteArray
10649 * g_byte_array_free:
10650 * @array: a #GByteArray
10651 * @free_segment: if %TRUE the actual byte data is freed as well
10653 * Frees the memory allocated by the #GByteArray. If @free_segment is
10654 * %TRUE it frees the actual byte data. If the reference count of
10655 * @array is greater than one, the #GByteArray wrapper is preserved but
10656 * the size of @array will be set to zero.
10658 * Returns: the element data if @free_segment is %FALSE, otherwise
10659 * %NULL. The element data should be freed using g_free().
10664 * g_byte_array_free_to_bytes:
10665 * @array: (transfer full): a #GByteArray
10667 * Transfers the data from the #GByteArray into a new immutable #GBytes.
10669 * The #GByteArray is freed unless the reference count of @array is greater
10670 * than one, the #GByteArray wrapper is preserved but the size of @array
10671 * will be set to zero.
10673 * This is identical to using g_bytes_new_take() and g_byte_array_free()
10677 * Returns: (transfer full): a new immutable #GBytes representing same
10678 * byte data that was in the array
10683 * g_byte_array_new:
10685 * Creates a new #GByteArray with a reference count of 1.
10687 * Returns: (transfer full): the new #GByteArray
10692 * g_byte_array_new_take:
10693 * @data: (transfer full) (array length=len): byte data for the array
10694 * @len: length of @data
10696 * Create byte array containing the data. The data will be owned by the array
10697 * and will be freed with g_free(), i.e. it could be allocated using g_strdup().
10700 * Returns: (transfer full): a new #GByteArray
10705 * g_byte_array_prepend:
10706 * @array: a #GByteArray
10707 * @data: the byte data to be added
10708 * @len: the number of bytes to add
10710 * Adds the given data to the start of the #GByteArray.
10711 * The array will grow in size automatically if necessary.
10713 * Returns: the #GByteArray
10718 * g_byte_array_ref:
10719 * @array: A #GByteArray
10721 * Atomically increments the reference count of @array by one.
10722 * This function is thread-safe and may be called from any thread.
10724 * Returns: The passed in #GByteArray
10730 * g_byte_array_remove_index:
10731 * @array: a #GByteArray
10732 * @index_: the index of the byte to remove
10734 * Removes the byte at the given index from a #GByteArray.
10735 * The following bytes are moved down one place.
10737 * Returns: the #GByteArray
10742 * g_byte_array_remove_index_fast:
10743 * @array: a #GByteArray
10744 * @index_: the index of the byte to remove
10746 * Removes the byte at the given index from a #GByteArray. The last
10747 * element in the array is used to fill in the space, so this function
10748 * does not preserve the order of the #GByteArray. But it is faster
10749 * than g_byte_array_remove_index().
10751 * Returns: the #GByteArray
10756 * g_byte_array_remove_range:
10757 * @array: a @GByteArray
10758 * @index_: the index of the first byte to remove
10759 * @length: the number of bytes to remove
10761 * Removes the given number of bytes starting at the given index from a
10762 * #GByteArray. The following elements are moved to close the gap.
10764 * Returns: the #GByteArray
10770 * g_byte_array_set_size:
10771 * @array: a #GByteArray
10772 * @length: the new size of the #GByteArray
10774 * Sets the size of the #GByteArray, expanding it if necessary.
10776 * Returns: the #GByteArray
10781 * g_byte_array_sized_new:
10782 * @reserved_size: number of bytes preallocated
10784 * Creates a new #GByteArray with @reserved_size bytes preallocated.
10785 * This avoids frequent reallocation, if you are going to add many
10786 * bytes to the array. Note however that the size of the array is still
10789 * Returns: the new #GByteArray
10794 * g_byte_array_sort:
10795 * @array: a #GByteArray
10796 * @compare_func: comparison function
10798 * Sorts a byte array, using @compare_func which should be a
10799 * qsort()-style comparison function (returns less than zero for first
10800 * arg is less than second arg, zero for equal, greater than zero if
10801 * first arg is greater than second arg).
10803 * If two array elements compare equal, their order in the sorted array
10804 * is undefined. If you want equal elements to keep their order (i.e.
10805 * you want a stable sort) you can write a comparison function that,
10806 * if two elements would otherwise compare equal, compares them by
10812 * g_byte_array_sort_with_data:
10813 * @array: a #GByteArray
10814 * @compare_func: comparison function
10815 * @user_data: data to pass to @compare_func
10817 * Like g_byte_array_sort(), but the comparison function takes an extra
10818 * user data argument.
10823 * g_byte_array_unref:
10824 * @array: A #GByteArray
10826 * Atomically decrements the reference count of @array by one. If the
10827 * reference count drops to 0, all memory allocated by the array is
10828 * released. This function is thread-safe and may be called from any
10837 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
10838 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
10840 * Compares the two #GBytes values.
10842 * This function can be used to sort GBytes instances in lexographical order.
10844 * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is
10845 * greater, and zero if bytes2 is equal to bytes1
10852 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
10853 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
10855 * Compares the two #GBytes values being pointed to and returns
10856 * %TRUE if they are equal.
10858 * This function can be passed to g_hash_table_new() as the @key_equal_func
10859 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
10861 * Returns: %TRUE if the two keys match.
10867 * g_bytes_get_data:
10868 * @bytes: a #GBytes
10869 * @size: (out) (allow-none): location to return size of byte data
10871 * Get the byte data in the #GBytes. This data should not be modified.
10873 * This function will always return the same pointer for a given #GBytes.
10875 * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
10876 * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
10877 * not be returned if @size is non-zero.
10879 * Returns: (transfer none) (array length=size) (type guint8) (allow-none): a pointer to the
10880 * byte data, or %NULL
10886 * g_bytes_get_size:
10887 * @bytes: a #GBytes
10889 * Get the size of the byte data in the #GBytes.
10891 * This function will always return the same value for a given #GBytes.
10893 * Returns: the size
10900 * @bytes: (type GLib.Bytes): a pointer to a #GBytes key
10902 * Creates an integer hash code for the byte data in the #GBytes.
10904 * This function can be passed to g_hash_table_new() as the @key_equal_func
10905 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
10907 * Returns: a hash value corresponding to the key.
10914 * @data: (transfer none) (array length=size) (element-type guint8) (allow-none):
10915 * the data to be used for the bytes
10916 * @size: the size of @data
10918 * Creates a new #GBytes from @data.
10920 * @data is copied. If @size is 0, @data may be %NULL.
10922 * Returns: (transfer full): a new #GBytes
10928 * g_bytes_new_from_bytes:
10929 * @bytes: a #GBytes
10930 * @offset: offset which subsection starts at
10931 * @length: length of subsection
10933 * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
10934 * @length may not be longer than the size of @bytes.
10936 * A reference to @bytes will be held by the newly created #GBytes until
10937 * the byte data is no longer needed.
10939 * Returns: (transfer full): a new #GBytes
10945 * g_bytes_new_static: (skip)
10946 * @data: (transfer full) (array length=size) (element-type guint8) (allow-none):
10947 * the data to be used for the bytes
10948 * @size: the size of @data
10950 * Creates a new #GBytes from static data.
10952 * @data must be static (ie: never modified or freed). It may be %NULL if @size
10955 * Returns: (transfer full): a new #GBytes
10961 * g_bytes_new_take:
10962 * @data: (transfer full) (array length=size) (element-type guint8) (allow-none):
10963 * the data to be used for the bytes
10964 * @size: the size of @data
10966 * Creates a new #GBytes from @data.
10968 * After this call, @data belongs to the bytes and may no longer be
10969 * modified by the caller. g_free() will be called on @data when the
10970 * bytes is no longer in use. Because of this @data must have been created by
10971 * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
10972 * functions that wrap these calls (such as g_new(), g_strdup(), etc).
10974 * For creating #GBytes with memory from other allocators, see
10975 * g_bytes_new_with_free_func().
10977 * @data may be %NULL if @size is 0.
10979 * Returns: (transfer full): a new #GBytes
10985 * g_bytes_new_with_free_func:
10986 * @data: (array length=size) (allow-none): the data to be used for the bytes
10987 * @size: the size of @data
10988 * @free_func: the function to call to release the data
10989 * @user_data: data to pass to @free_func
10991 * Creates a #GBytes from @data.
10993 * When the last reference is dropped, @free_func will be called with the
10994 * @user_data argument.
10996 * @data must not be modified after this call is made until @free_func has
10997 * been called to indicate that the bytes is no longer in use.
10999 * @data may be %NULL if @size is 0.
11001 * Returns: (transfer full): a new #GBytes
11008 * @bytes: a #GBytes
11010 * Increase the reference count on @bytes.
11012 * Returns: the #GBytes
11019 * @bytes: (allow-none): a #GBytes
11021 * Releases a reference on @bytes. This may result in the bytes being
11029 * g_bytes_unref_to_array:
11030 * @bytes: (transfer full): a #GBytes
11032 * Unreferences the bytes, and returns a new mutable #GByteArray containing
11033 * the same byte data.
11035 * As an optimization, the byte data is transferred to the array without copying
11036 * if this was the last reference to bytes and bytes was created with
11037 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
11038 * other cases the data is copied.
11040 * Returns: (transfer full): a new mutable #GByteArray containing the same byte data
11046 * g_bytes_unref_to_data:
11047 * @bytes: (transfer full): a #GBytes
11048 * @size: location to place the length of the returned data
11050 * Unreferences the bytes, and returns a pointer the same byte data
11053 * As an optimization, the byte data is returned without copying if this was
11054 * the last reference to bytes and bytes was created with g_bytes_new(),
11055 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
11058 * Returns: (transfer full): a pointer to the same byte data, which should
11059 * be freed with g_free()
11066 * @path: a pathname in the GLib file name encoding (UTF-8 on Windows)
11068 * A wrapper for the POSIX chdir() function. The function changes the
11069 * current directory of the process to @path.
11071 * See your C library manual for more details about chdir().
11073 * Returns: 0 on success, -1 if an error occurred.
11080 * @checksum: the #GChecksum to copy
11082 * Copies a #GChecksum. If @checksum has been closed, by calling
11083 * g_checksum_get_string() or g_checksum_get_digest(), the copied
11084 * checksum will be closed as well.
11086 * Returns: the copy of the passed #GChecksum. Use g_checksum_free()
11087 * when finished using it.
11094 * @checksum: a #GChecksum
11096 * Frees the memory allocated for @checksum.
11103 * g_checksum_get_digest: (skip)
11104 * @checksum: a #GChecksum
11105 * @buffer: output buffer
11106 * @digest_len: an inout parameter. The caller initializes it to the size of @buffer.
11107 * After the call it contains the length of the digest.
11109 * Gets the digest from @checksum as a raw binary vector and places it
11110 * into @buffer. The size of the digest depends on the type of checksum.
11112 * Once this function has been called, the #GChecksum is closed and can
11113 * no longer be updated with g_checksum_update().
11120 * g_checksum_get_string:
11121 * @checksum: a #GChecksum
11123 * Gets the digest as an hexadecimal string.
11125 * Once this function has been called the #GChecksum can no longer be
11126 * updated with g_checksum_update().
11128 * The hexadecimal characters will be lower case.
11130 * Returns: the hexadecimal representation of the checksum. The
11131 * returned string is owned by the checksum and should not be modified
11139 * @checksum_type: the desired type of checksum
11141 * Creates a new #GChecksum, using the checksum algorithm @checksum_type.
11142 * If the @checksum_type is not known, %NULL is returned.
11143 * A #GChecksum can be used to compute the checksum, or digest, of an
11144 * arbitrary binary blob, using different hashing algorithms.
11146 * A #GChecksum works by feeding a binary blob through g_checksum_update()
11147 * until there is data to be checked; the digest can then be extracted
11148 * using g_checksum_get_string(), which will return the checksum as a
11149 * hexadecimal string; or g_checksum_get_digest(), which will return a
11150 * vector of raw bytes. Once either g_checksum_get_string() or
11151 * g_checksum_get_digest() have been called on a #GChecksum, the checksum
11152 * will be closed and it won't be possible to call g_checksum_update()
11155 * Returns: (transfer full): the newly created #GChecksum, or %NULL.
11156 * Use g_checksum_free() to free the memory allocated by it.
11162 * g_checksum_reset:
11163 * @checksum: the #GChecksum to reset
11165 * Resets the state of the @checksum back to its initial state.
11172 * g_checksum_type_get_length:
11173 * @checksum_type: a #GChecksumType
11175 * Gets the length in bytes of digests of type @checksum_type
11177 * Returns: the checksum length, or -1 if @checksum_type is
11184 * g_checksum_update:
11185 * @checksum: a #GChecksum
11186 * @data: (array length=length) (element-type guint8): buffer used to compute the checksum
11187 * @length: size of the buffer, or -1 if it is a null-terminated string.
11189 * Feeds @data into an existing #GChecksum. The checksum must still be
11190 * open, that is g_checksum_get_string() or g_checksum_get_digest() must
11191 * not have been called on @checksum.
11198 * g_child_watch_add:
11199 * @pid: process id to watch. On POSIX the positive pid of a child
11200 * process. On Windows a handle for a process (which doesn't have to be
11202 * @function: function to call
11203 * @data: data to pass to @function
11205 * Sets a function to be called when the child indicated by @pid
11206 * exits, at a default priority, #G_PRIORITY_DEFAULT.
11208 * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
11209 * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
11210 * the spawn function for the child watching to work.
11212 * Note that on platforms where #GPid must be explicitly closed
11213 * (see g_spawn_close_pid()) @pid must not be closed while the
11214 * source is still active. Typically, you will want to call
11215 * g_spawn_close_pid() in the callback function for the source.
11217 * GLib supports only a single callback per process id.
11219 * This internally creates a main loop source using
11220 * g_child_watch_source_new() and attaches it to the main loop context
11221 * using g_source_attach(). You can do these steps manually if you
11222 * need greater control.
11224 * Returns: the ID (greater than 0) of the event source.
11230 * g_child_watch_add_full: (rename-to g_child_watch_add)
11231 * @priority: the priority of the idle source. Typically this will be in the
11232 * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
11233 * @pid: process to watch. On POSIX the positive pid of a child process. On
11234 * Windows a handle for a process (which doesn't have to be a child).
11235 * @function: function to call
11236 * @data: data to pass to @function
11237 * @notify: (allow-none): function to call when the idle is removed, or %NULL
11239 * Sets a function to be called when the child indicated by @pid
11240 * exits, at the priority @priority.
11242 * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
11243 * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
11244 * the spawn function for the child watching to work.
11246 * In many programs, you will want to call g_spawn_check_exit_status()
11247 * in the callback to determine whether or not the child exited
11250 * Also, note that on platforms where #GPid must be explicitly closed
11251 * (see g_spawn_close_pid()) @pid must not be closed while the source
11252 * is still active. Typically, you should invoke g_spawn_close_pid()
11253 * in the callback function for the source.
11255 * GLib supports only a single callback per process id.
11257 * This internally creates a main loop source using
11258 * g_child_watch_source_new() and attaches it to the main loop context
11259 * using g_source_attach(). You can do these steps manually if you
11260 * need greater control.
11262 * Returns: the ID (greater than 0) of the event source.
11268 * g_child_watch_source_new:
11269 * @pid: process to watch. On POSIX the positive pid of a child process. On
11270 * Windows a handle for a process (which doesn't have to be a child).
11272 * Creates a new child_watch source.
11274 * The source will not initially be associated with any #GMainContext
11275 * and must be added to one with g_source_attach() before it will be
11278 * Note that child watch sources can only be used in conjunction with
11279 * `g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used.
11281 * Note that on platforms where #GPid must be explicitly closed
11282 * (see g_spawn_close_pid()) @pid must not be closed while the
11283 * source is still active. Typically, you will want to call
11284 * g_spawn_close_pid() in the callback function for the source.
11286 * Note further that using g_child_watch_source_new() is not
11287 * compatible with calling `waitpid` with a nonpositive first
11288 * argument in the application. Calling waitpid() for individual
11289 * pids will still work fine.
11291 * Similarly, on POSIX platforms, the @pid passed to this function must
11292 * be greater than 0 (i.e. this function must wait for a specific child,
11293 * and cannot wait for one of many children by using a nonpositive argument).
11295 * Returns: the newly-created child watch source
11302 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
11303 * @mode: as in chmod()
11305 * A wrapper for the POSIX chmod() function. The chmod() function is
11306 * used to set the permissions of a file system object.
11308 * On Windows the file protection mechanism is not at all POSIX-like,
11309 * and the underlying chmod() function in the C library just sets or
11310 * clears the FAT-style READONLY attribute. It does not touch any
11311 * ACL. Software that needs to manage file permissions on Windows
11312 * exactly should use the Win32 API.
11314 * See your C library manual for more details about chmod().
11316 * Returns: 0 if the operation succeeded, -1 on error
11323 * @err: a #GError return location
11325 * If @err is %NULL, does nothing. If @err is non-%NULL,
11326 * calls g_error_free() on *@err and sets *@err to %NULL.
11331 * g_clear_pointer: (skip)
11332 * @pp: a pointer to a variable, struct member etc. holding a pointer
11333 * @destroy: a function to which a gpointer can be passed, to destroy *@pp
11335 * Clears a reference to a variable.
11337 * @pp must not be %NULL.
11339 * If the reference is %NULL then this function does nothing.
11340 * Otherwise, the variable is destroyed using @destroy and the
11341 * pointer is set to %NULL.
11343 * This function is threadsafe and modifies the pointer atomically,
11344 * using memory barriers where needed.
11346 * A macro is also included that allows this function to be used without
11355 * @fd: A file descriptor
11356 * @error: a #GError
11358 * This wraps the close() call; in case of error, %errno will be
11359 * preserved, but the error will also be stored as a #GError in @error.
11361 * Besides using #GError, there is another major reason to prefer this
11362 * function over the call provided by the system; on Unix, it will
11363 * attempt to correctly handle %EINTR, which has platform-specific
11371 * g_compute_checksum_for_bytes:
11372 * @checksum_type: a #GChecksumType
11373 * @data: binary blob to compute the digest of
11375 * Computes the checksum for a binary @data. This is a
11376 * convenience wrapper for g_checksum_new(), g_checksum_get_string()
11377 * and g_checksum_free().
11379 * The hexadecimal string returned will be in lower case.
11381 * Returns: the digest of the binary data as a string in hexadecimal.
11382 * The returned string should be freed with g_free() when done using it.
11388 * g_compute_checksum_for_data:
11389 * @checksum_type: a #GChecksumType
11390 * @data: (array length=length) (element-type guint8): binary blob to compute the digest of
11391 * @length: length of @data
11393 * Computes the checksum for a binary @data of @length. This is a
11394 * convenience wrapper for g_checksum_new(), g_checksum_get_string()
11395 * and g_checksum_free().
11397 * The hexadecimal string returned will be in lower case.
11399 * Returns: the digest of the binary data as a string in hexadecimal.
11400 * The returned string should be freed with g_free() when done using it.
11406 * g_compute_checksum_for_string:
11407 * @checksum_type: a #GChecksumType
11408 * @str: the string to compute the checksum of
11409 * @length: the length of the string, or -1 if the string is null-terminated.
11411 * Computes the checksum of a string.
11413 * The hexadecimal string returned will be in lower case.
11415 * Returns: the checksum as a hexadecimal string. The returned string
11416 * should be freed with g_free() when done using it.
11422 * g_compute_hmac_for_data:
11423 * @digest_type: a #GChecksumType to use for the HMAC
11424 * @key: (array length=key_len): the key to use in the HMAC
11425 * @key_len: the length of the key
11426 * @data: binary blob to compute the HMAC of
11427 * @length: length of @data
11429 * Computes the HMAC for a binary @data of @length. This is a
11430 * convenience wrapper for g_hmac_new(), g_hmac_get_string()
11431 * and g_hmac_unref().
11433 * The hexadecimal string returned will be in lower case.
11435 * Returns: the HMAC of the binary data as a string in hexadecimal.
11436 * The returned string should be freed with g_free() when done using it.
11442 * g_compute_hmac_for_string:
11443 * @digest_type: a #GChecksumType to use for the HMAC
11444 * @key: (array length=key_len): the key to use in the HMAC
11445 * @key_len: the length of the key
11446 * @str: the string to compute the HMAC for
11447 * @length: the length of the string, or -1 if the string is nul-terminated
11449 * Computes the HMAC for a string.
11451 * The hexadecimal string returned will be in lower case.
11453 * Returns: the HMAC as a hexadecimal string.
11454 * The returned string should be freed with g_free()
11455 * when done using it.
11461 * g_cond_broadcast:
11464 * If threads are waiting for @cond, all of them are unblocked.
11465 * If no threads are waiting for @cond, this function has no effect.
11466 * It is good practice to lock the same mutex as the waiting threads
11467 * while calling this function, though not required.
11473 * @cond: an initialised #GCond
11475 * Frees the resources allocated to a #GCond with g_cond_init().
11477 * This function should not be used with a #GCond that has been
11478 * statically allocated.
11480 * Calling g_cond_clear() for a #GCond on which threads are
11481 * blocking leads to undefined behaviour.
11489 * @cond: an uninitialized #GCond
11491 * Initialises a #GCond so that it can be used.
11493 * This function is useful to initialise a #GCond that has been
11494 * allocated as part of a larger structure. It is not necessary to
11495 * initialise a #GCond that has been statically allocated.
11497 * To undo the effect of g_cond_init() when a #GCond is no longer
11498 * needed, use g_cond_clear().
11500 * Calling g_cond_init() on an already-initialised #GCond leads
11501 * to undefined behaviour.
11511 * If threads are waiting for @cond, at least one of them is unblocked.
11512 * If no threads are waiting for @cond, this function has no effect.
11513 * It is good practice to hold the same lock as the waiting thread
11514 * while calling this function, though not required.
11521 * @mutex: a #GMutex that is currently locked
11523 * Atomically releases @mutex and waits until @cond is signalled.
11524 * When this function returns, @mutex is locked again and owned by the
11527 * When using condition variables, it is possible that a spurious wakeup
11528 * may occur (ie: g_cond_wait() returns even though g_cond_signal() was
11529 * not called). It's also possible that a stolen wakeup may occur.
11530 * This is when g_cond_signal() is called, but another thread acquires
11531 * @mutex before this thread and modifies the state of the program in
11532 * such a way that when g_cond_wait() is able to return, the expected
11533 * condition is no longer met.
11535 * For this reason, g_cond_wait() must always be used in a loop. See
11536 * the documentation for #GCond for a complete example.
11541 * g_cond_wait_until:
11543 * @mutex: a #GMutex that is currently locked
11544 * @end_time: the monotonic time to wait until
11546 * Waits until either @cond is signalled or @end_time has passed.
11548 * As with g_cond_wait() it is possible that a spurious or stolen wakeup
11549 * could occur. For that reason, waiting on a condition variable should
11550 * always be in a loop, based on an explicitly-checked predicate.
11552 * %TRUE is returned if the condition variable was signalled (or in the
11553 * case of a spurious wakeup). %FALSE is returned if @end_time has
11556 * The following code shows how to correctly perform a timed wait on a
11557 * condition variable (extending the example presented in the
11558 * documentation for #GCond):
11560 * |[<!-- language="C" -->
11562 * pop_data_timed (void)
11567 * g_mutex_lock (&data_mutex);
11569 * end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
11570 * while (!current_data)
11571 * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
11573 * // timeout has passed.
11574 * g_mutex_unlock (&data_mutex);
11578 * // there is data for us
11579 * data = current_data;
11580 * current_data = NULL;
11582 * g_mutex_unlock (&data_mutex);
11588 * Notice that the end time is calculated once, before entering the
11589 * loop and reused. This is the motivation behind the use of absolute
11590 * time on this API -- if a relative time of 5 seconds were passed
11591 * directly to the call and a spurious wakeup occurred, the program would
11592 * have to start over waiting again (which would lead to a total wait
11593 * time of more than 5 seconds).
11595 * Returns: %TRUE on a signal, %FALSE on a timeout
11602 * @str: the string to convert
11603 * @len: the length of the string, or -1 if the string is
11604 * nul-terminated (Note that some encodings may allow nul
11605 * bytes to occur inside strings. In that case, using -1
11606 * for the @len parameter is unsafe)
11607 * @to_codeset: name of character set into which to convert @str
11608 * @from_codeset: character set of @str.
11609 * @bytes_read: (out): location to store the number of bytes in the
11610 * input string that were successfully converted, or %NULL.
11611 * Even if the conversion was successful, this may be
11612 * less than @len if there were partial characters
11613 * at the end of the input. If the error
11614 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
11615 * stored will the byte offset after the last valid
11617 * @bytes_written: (out): the number of bytes stored in the output buffer (not
11618 * including the terminating nul).
11619 * @error: location to store the error occurring, or %NULL to ignore
11620 * errors. Any of the errors in #GConvertError may occur.
11622 * Converts a string from one character set to another.
11624 * Note that you should use g_iconv() for streaming conversions.
11625 * Despite the fact that @byes_read can return information about partial
11626 * characters, the g_convert_... functions are not generally suitable
11627 * for streaming. If the underlying converter maintains internal state,
11628 * then this won't be preserved across successive calls to g_convert(),
11629 * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
11630 * this is the GNU C converter for CP1255 which does not emit a base
11631 * character until it knows that the next character is not a mark that
11632 * could combine with the base character.)
11634 * Using extensions such as "//TRANSLIT" may not work (or may not work
11635 * well) on many platforms. Consider using g_str_to_ascii() instead.
11637 * Returns: If the conversion was successful, a newly allocated
11638 * nul-terminated string, which must be freed with
11639 * g_free(). Otherwise %NULL and @error will be set.
11644 * g_convert_with_fallback:
11645 * @str: the string to convert
11646 * @len: the length of the string, or -1 if the string is
11647 * nul-terminated (Note that some encodings may allow nul
11648 * bytes to occur inside strings. In that case, using -1
11649 * for the @len parameter is unsafe)
11650 * @to_codeset: name of character set into which to convert @str
11651 * @from_codeset: character set of @str.
11652 * @fallback: UTF-8 string to use in place of character not
11653 * present in the target encoding. (The string must be
11654 * representable in the target encoding).
11655 * If %NULL, characters not in the target encoding will
11656 * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
11657 * @bytes_read: location to store the number of bytes in the
11658 * input string that were successfully converted, or %NULL.
11659 * Even if the conversion was successful, this may be
11660 * less than @len if there were partial characters
11661 * at the end of the input.
11662 * @bytes_written: the number of bytes stored in the output buffer (not
11663 * including the terminating nul).
11664 * @error: location to store the error occurring, or %NULL to ignore
11665 * errors. Any of the errors in #GConvertError may occur.
11667 * Converts a string from one character set to another, possibly
11668 * including fallback sequences for characters not representable
11669 * in the output. Note that it is not guaranteed that the specification
11670 * for the fallback sequences in @fallback will be honored. Some
11671 * systems may do an approximate conversion from @from_codeset
11672 * to @to_codeset in their iconv() functions,
11673 * in which case GLib will simply return that approximate conversion.
11675 * Note that you should use g_iconv() for streaming conversions.
11676 * Despite the fact that @byes_read can return information about partial
11677 * characters, the g_convert_... functions are not generally suitable
11678 * for streaming. If the underlying converter maintains internal state,
11679 * then this won't be preserved across successive calls to g_convert(),
11680 * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
11681 * this is the GNU C converter for CP1255 which does not emit a base
11682 * character until it knows that the next character is not a mark that
11683 * could combine with the base character.)
11685 * Returns: If the conversion was successful, a newly allocated
11686 * nul-terminated string, which must be freed with
11687 * g_free(). Otherwise %NULL and @error will be set.
11692 * g_convert_with_iconv:
11693 * @str: the string to convert
11694 * @len: the length of the string, or -1 if the string is
11695 * nul-terminated (Note that some encodings may allow nul
11696 * bytes to occur inside strings. In that case, using -1
11697 * for the @len parameter is unsafe)
11698 * @converter: conversion descriptor from g_iconv_open()
11699 * @bytes_read: location to store the number of bytes in the
11700 * input string that were successfully converted, or %NULL.
11701 * Even if the conversion was successful, this may be
11702 * less than @len if there were partial characters
11703 * at the end of the input. If the error
11704 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
11705 * stored will the byte offset after the last valid
11707 * @bytes_written: the number of bytes stored in the output buffer (not
11708 * including the terminating nul).
11709 * @error: location to store the error occurring, or %NULL to ignore
11710 * errors. Any of the errors in #GConvertError may occur.
11712 * Converts a string from one character set to another.
11714 * Note that you should use g_iconv() for streaming conversions.
11715 * Despite the fact that @byes_read can return information about partial
11716 * characters, the g_convert_... functions are not generally suitable
11717 * for streaming. If the underlying converter maintains internal state,
11718 * then this won't be preserved across successive calls to g_convert(),
11719 * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
11720 * this is the GNU C converter for CP1255 which does not emit a base
11721 * character until it knows that the next character is not a mark that
11722 * could combine with the base character.)
11724 * Returns: If the conversion was successful, a newly allocated
11725 * nul-terminated string, which must be freed with
11726 * g_free(). Otherwise %NULL and @error will be set.
11732 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
11733 * @mode: as in creat()
11735 * A wrapper for the POSIX creat() function. The creat() function is
11736 * used to convert a pathname into a file descriptor, creating a file
11739 * On POSIX systems file descriptors are implemented by the operating
11740 * system. On Windows, it's the C library that implements creat() and
11741 * file descriptors. The actual Windows API for opening files is
11742 * different, see MSDN documentation for CreateFile(). The Win32 API
11743 * uses file handles, which are more randomish integers, not small
11744 * integers like file descriptors.
11746 * Because file descriptors are specific to the C library on Windows,
11747 * the file descriptor returned by this function makes sense only to
11748 * functions in the same C library. Thus if the GLib-using code uses a
11749 * different C library than GLib does, the file descriptor returned by
11750 * this function cannot be passed to C library functions like write()
11753 * See your C library manual for more details about creat().
11755 * Returns: a new file descriptor, or -1 if an error occurred.
11756 * The return value can be used exactly like the return value
11764 * @...: format string, followed by parameters to insert
11765 * into the format string (as with printf())
11767 * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL).
11768 * It's more or less application-defined what constitutes
11769 * a critical vs. a regular warning. You could call
11770 * g_log_set_always_fatal() to make critical warnings exit
11771 * the program, then use g_critical() for fatal errors, for
11774 * You can also make critical warnings fatal at runtime by
11775 * setting the `G_DEBUG` environment variable (see
11776 * [Running GLib Applications](glib-running.html)).
11778 * If g_log_default_handler() is used as the log handler function, a new-line
11779 * character will automatically be appended to @..., and need not be entered
11785 * g_datalist_clear:
11786 * @datalist: a datalist.
11788 * Frees all the data elements of the datalist.
11789 * The data elements' destroy functions are called
11790 * if they have been set.
11795 * g_datalist_foreach:
11796 * @datalist: a datalist.
11797 * @func: the function to call for each data element.
11798 * @user_data: user data to pass to the function.
11800 * Calls the given function for each data element of the datalist. The
11801 * function is called with each data element's #GQuark id and data,
11802 * together with the given @user_data parameter. Note that this
11803 * function is NOT thread-safe. So unless @datalist can be protected
11804 * from any modifications during invocation of this function, it should
11810 * g_datalist_get_data:
11811 * @datalist: a datalist.
11812 * @key: the string identifying a data element.
11814 * Gets a data element, using its string identifier. This is slower than
11815 * g_datalist_id_get_data() because it compares strings.
11817 * Returns: the data element, or %NULL if it is not found.
11822 * g_datalist_get_flags:
11823 * @datalist: pointer to the location that holds a list
11825 * Gets flags values packed in together with the datalist.
11826 * See g_datalist_set_flags().
11828 * Returns: the flags of the datalist
11834 * g_datalist_id_dup_data:
11835 * @datalist: location of a datalist
11836 * @key_id: the #GQuark identifying a data element
11837 * @dup_func: (allow-none): function to duplicate the old value
11838 * @user_data: (allow-none): passed as user_data to @dup_func
11840 * This is a variant of g_datalist_id_get_data() which
11841 * returns a 'duplicate' of the value. @dup_func defines the
11842 * meaning of 'duplicate' in this context, it could e.g.
11843 * take a reference on a ref-counted object.
11845 * If the @key_id is not set in the datalist then @dup_func
11846 * will be called with a %NULL argument.
11848 * Note that @dup_func is called while the datalist is locked, so it
11849 * is not allowed to read or modify the datalist.
11851 * This function can be useful to avoid races when multiple
11852 * threads are using the same datalist and the same key.
11854 * Returns: the result of calling @dup_func on the value
11855 * associated with @key_id in @datalist, or %NULL if not set.
11856 * If @dup_func is %NULL, the value is returned unmodified.
11862 * g_datalist_id_get_data:
11863 * @datalist: a datalist.
11864 * @key_id: the #GQuark identifying a data element.
11866 * Retrieves the data element corresponding to @key_id.
11868 * Returns: the data element, or %NULL if it is not found.
11873 * g_datalist_id_remove_data:
11875 * @q: the #GQuark identifying the data element.
11877 * Removes an element, using its #GQuark identifier.
11882 * g_datalist_id_remove_no_notify:
11883 * @datalist: a datalist.
11884 * @key_id: the #GQuark identifying a data element.
11886 * Removes an element, without calling its destroy notification
11889 * Returns: the data previously stored at @key_id, or %NULL if none.
11894 * g_datalist_id_replace_data:
11895 * @datalist: location of a datalist
11896 * @key_id: the #GQuark identifying a data element
11897 * @oldval: (allow-none): the old value to compare against
11898 * @newval: (allow-none): the new value to replace it with
11899 * @destroy: (allow-none): destroy notify for the new value
11900 * @old_destroy: (allow-none): destroy notify for the existing value
11902 * Compares the member that is associated with @key_id in
11903 * @datalist to @oldval, and if they are the same, replace
11904 * @oldval with @newval.
11906 * This is like a typical atomic compare-and-exchange
11907 * operation, for a member of @datalist.
11909 * If the previous value was replaced then ownership of the
11910 * old value (@oldval) is passed to the caller, including
11911 * the registred destroy notify for it (passed out in @old_destroy).
11912 * Its up to the caller to free this as he wishes, which may
11913 * or may not include using @old_destroy as sometimes replacement
11914 * should not destroy the object in the normal way.
11916 * Returns: %TRUE if the existing value for @key_id was replaced
11917 * by @newval, %FALSE otherwise.
11923 * g_datalist_id_set_data:
11925 * @q: the #GQuark to identify the data element.
11926 * @d: (allow-none): the data element, or %NULL to remove any previous element
11927 * corresponding to @q.
11929 * Sets the data corresponding to the given #GQuark id. Any previous
11930 * data with the same key is removed, and its destroy function is
11936 * g_datalist_id_set_data_full:
11937 * @datalist: a datalist.
11938 * @key_id: the #GQuark to identify the data element.
11939 * @data: (allow-none): the data element or %NULL to remove any previous element
11940 * corresponding to @key_id.
11941 * @destroy_func: the function to call when the data element is
11942 * removed. This function will be called with the data
11943 * element and can be used to free any memory allocated
11944 * for it. If @data is %NULL, then @destroy_func must
11947 * Sets the data corresponding to the given #GQuark id, and the
11948 * function to be called when the element is removed from the datalist.
11949 * Any previous data with the same key is removed, and its destroy
11950 * function is called.
11956 * @datalist: a pointer to a pointer to a datalist.
11958 * Resets the datalist to %NULL. It does not free any memory or call
11959 * any destroy functions.
11964 * g_datalist_remove_data:
11966 * @k: the string identifying the data element.
11968 * Removes an element using its string identifier. The data element's
11969 * destroy function is called if it has been set.
11974 * g_datalist_remove_no_notify:
11976 * @k: the string identifying the data element.
11978 * Removes an element, without calling its destroy notifier.
11983 * g_datalist_set_data:
11985 * @k: the string to identify the data element.
11986 * @d: (allow-none): the data element, or %NULL to remove any previous element
11987 * corresponding to @k.
11989 * Sets the data element corresponding to the given string identifier.
11994 * g_datalist_set_data_full:
11996 * @k: the string to identify the data element.
11997 * @d: (allow-none): the data element, or %NULL to remove any previous element
11998 * corresponding to @k.
11999 * @f: the function to call when the data element is removed. This
12000 * function will be called with the data element and can be used to
12001 * free any memory allocated for it. If @d is %NULL, then @f must
12004 * Sets the data element corresponding to the given string identifier,
12005 * and the function to be called when the data element is removed.
12010 * g_datalist_set_flags:
12011 * @datalist: pointer to the location that holds a list
12012 * @flags: the flags to turn on. The values of the flags are
12013 * restricted by %G_DATALIST_FLAGS_MASK (currently
12014 * 3; giving two possible boolean flags).
12015 * A value for @flags that doesn't fit within the mask is
12018 * Turns on flag values for a data list. This function is used
12019 * to keep a small number of boolean flags in an object with
12020 * a data list without using any additional space. It is
12021 * not generally useful except in circumstances where space
12022 * is very tight. (It is used in the base #GObject type, for
12030 * g_datalist_unset_flags:
12031 * @datalist: pointer to the location that holds a list
12032 * @flags: the flags to turn off. The values of the flags are
12033 * restricted by %G_DATALIST_FLAGS_MASK (currently
12034 * 3: giving two possible boolean flags).
12035 * A value for @flags that doesn't fit within the mask is
12038 * Turns off flag values for a data list. See g_datalist_unset_flags()
12045 * g_dataset_destroy:
12046 * @dataset_location: the location identifying the dataset.
12048 * Destroys the dataset, freeing all memory allocated, and calling any
12049 * destroy functions set for data elements.
12054 * g_dataset_foreach:
12055 * @dataset_location: the location identifying the dataset.
12056 * @func: the function to call for each data element.
12057 * @user_data: user data to pass to the function.
12059 * Calls the given function for each data element which is associated
12060 * with the given location. Note that this function is NOT thread-safe.
12061 * So unless @datalist can be protected from any modifications during
12062 * invocation of this function, it should not be called.
12067 * g_dataset_get_data:
12068 * @l: the location identifying the dataset.
12069 * @k: the string identifying the data element.
12071 * Gets the data element corresponding to a string.
12073 * Returns: the data element corresponding to the string, or %NULL if
12079 * g_dataset_id_get_data:
12080 * @dataset_location: the location identifying the dataset.
12081 * @key_id: the #GQuark id to identify the data element.
12083 * Gets the data element corresponding to a #GQuark.
12085 * Returns: the data element corresponding to the #GQuark, or %NULL if
12091 * g_dataset_id_remove_data:
12092 * @l: the location identifying the dataset.
12093 * @k: the #GQuark id identifying the data element.
12095 * Removes a data element from a dataset. The data element's destroy
12096 * function is called if it has been set.
12101 * g_dataset_id_remove_no_notify:
12102 * @dataset_location: the location identifying the dataset.
12103 * @key_id: the #GQuark ID identifying the data element.
12105 * Removes an element, without calling its destroy notification
12108 * Returns: the data previously stored at @key_id, or %NULL if none.
12113 * g_dataset_id_set_data:
12114 * @l: the location identifying the dataset.
12115 * @k: the #GQuark id to identify the data element.
12116 * @d: the data element.
12118 * Sets the data element associated with the given #GQuark id. Any
12119 * previous data with the same key is removed, and its destroy function
12125 * g_dataset_id_set_data_full:
12126 * @dataset_location: the location identifying the dataset.
12127 * @key_id: the #GQuark id to identify the data element.
12128 * @data: the data element.
12129 * @destroy_func: the function to call when the data element is
12130 * removed. This function will be called with the data
12131 * element and can be used to free any memory allocated
12134 * Sets the data element associated with the given #GQuark id, and also
12135 * the function to call when the data element is destroyed. Any
12136 * previous data with the same key is removed, and its destroy function
12142 * g_dataset_remove_data:
12143 * @l: the location identifying the dataset.
12144 * @k: the string identifying the data element.
12146 * Removes a data element corresponding to a string. Its destroy
12147 * function is called if it has been set.
12152 * g_dataset_remove_no_notify:
12153 * @l: the location identifying the dataset.
12154 * @k: the string identifying the data element.
12156 * Removes an element, without calling its destroy notifier.
12161 * g_dataset_set_data:
12162 * @l: the location identifying the dataset.
12163 * @k: the string to identify the data element.
12164 * @d: the data element.
12166 * Sets the data corresponding to the given string identifier.
12171 * g_dataset_set_data_full:
12172 * @l: the location identifying the dataset.
12173 * @k: the string to identify the data element.
12174 * @d: the data element.
12175 * @f: the function to call when the data element is removed. This
12176 * function will be called with the data element and can be used to
12177 * free any memory allocated for it.
12179 * Sets the data corresponding to the given string identifier, and the
12180 * function to call when the data element is destroyed.
12186 * @date: a #GDate to increment
12187 * @n_days: number of days to move the date forward
12189 * Increments a date some number of days.
12190 * To move forward by weeks, add weeks*7 days.
12191 * The date must be valid.
12196 * g_date_add_months:
12197 * @date: a #GDate to increment
12198 * @n_months: number of months to move forward
12200 * Increments a date by some number of months.
12201 * If the day of the month is greater than 28,
12202 * this routine may change the day of the month
12203 * (because the destination month may not have
12204 * the current day in it). The date must be valid.
12209 * g_date_add_years:
12210 * @date: a #GDate to increment
12211 * @n_years: number of years to move forward
12213 * Increments a date by some number of years.
12214 * If the date is February 29, and the destination
12215 * year is not a leap year, the date will be changed
12216 * to February 28. The date must be valid.
12222 * @date: a #GDate to clamp
12223 * @min_date: minimum accepted value for @date
12224 * @max_date: maximum accepted value for @date
12226 * If @date is prior to @min_date, sets @date equal to @min_date.
12227 * If @date falls after @max_date, sets @date equal to @max_date.
12228 * Otherwise, @date is unchanged.
12229 * Either of @min_date and @max_date may be %NULL.
12230 * All non-%NULL dates must be valid.
12236 * @date: pointer to one or more dates to clear
12237 * @n_dates: number of dates to clear
12239 * Initializes one or more #GDate structs to a sane but invalid
12240 * state. The cleared dates will not represent an existing date, but will
12241 * not contain garbage. Useful to init a date declared on the stack.
12242 * Validity can be tested with g_date_valid().
12248 * @lhs: first date to compare
12249 * @rhs: second date to compare
12251 * qsort()-style comparison function for dates.
12252 * Both dates must be valid.
12254 * Returns: 0 for equal, less than zero if @lhs is less than @rhs,
12255 * greater than zero if @lhs is greater than @rhs
12260 * g_date_days_between:
12261 * @date1: the first date
12262 * @date2: the second date
12264 * Computes the number of days between two dates.
12265 * If @date2 is prior to @date1, the returned value is negative.
12266 * Both dates must be valid.
12268 * Returns: the number of days between @date1 and @date2
12274 * @date: a #GDate to free
12276 * Frees a #GDate returned from g_date_new().
12282 * @date: a #GDate to extract the day of the month from
12284 * Returns the day of the month. The date must be valid.
12286 * Returns: day of the month
12291 * g_date_get_day_of_year:
12292 * @date: a #GDate to extract day of year from
12294 * Returns the day of the year, where Jan 1 is the first day of the
12295 * year. The date must be valid.
12297 * Returns: day of the year
12302 * g_date_get_days_in_month:
12306 * Returns the number of days in a month, taking leap
12307 * years into account.
12309 * Returns: number of days in @month during the @year
12314 * g_date_get_iso8601_week_of_year:
12315 * @date: a valid #GDate
12317 * Returns the week of the year, where weeks are interpreted according
12320 * Returns: ISO 8601 week number of the year.
12326 * g_date_get_julian:
12327 * @date: a #GDate to extract the Julian day from
12329 * Returns the Julian day or "serial number" of the #GDate. The
12330 * Julian day is simply the number of days since January 1, Year 1; i.e.,
12331 * January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
12332 * etc. The date must be valid.
12334 * Returns: Julian day
12339 * g_date_get_monday_week_of_year:
12342 * Returns the week of the year, where weeks are understood to start on
12343 * Monday. If the date is before the first Monday of the year, return
12344 * 0. The date must be valid.
12346 * Returns: week of the year
12351 * g_date_get_monday_weeks_in_year:
12354 * Returns the number of weeks in the year, where weeks
12355 * are taken to start on Monday. Will be 52 or 53. The
12356 * date must be valid. (Years always have 52 7-day periods,
12357 * plus 1 or 2 extra days depending on whether it's a leap
12358 * year. This function is basically telling you how many
12359 * Mondays are in the year, i.e. there are 53 Mondays if
12360 * one of the extra days happens to be a Monday.)
12362 * Returns: number of Mondays in the year
12367 * g_date_get_month:
12368 * @date: a #GDate to get the month from
12370 * Returns the month of the year. The date must be valid.
12372 * Returns: month of the year as a #GDateMonth
12377 * g_date_get_sunday_week_of_year:
12380 * Returns the week of the year during which this date falls, if weeks
12381 * are understood to being on Sunday. The date must be valid. Can return
12382 * 0 if the day is before the first Sunday of the year.
12384 * Returns: week number
12389 * g_date_get_sunday_weeks_in_year:
12390 * @year: year to count weeks in
12392 * Returns the number of weeks in the year, where weeks
12393 * are taken to start on Sunday. Will be 52 or 53. The
12394 * date must be valid. (Years always have 52 7-day periods,
12395 * plus 1 or 2 extra days depending on whether it's a leap
12396 * year. This function is basically telling you how many
12397 * Sundays are in the year, i.e. there are 53 Sundays if
12398 * one of the extra days happens to be a Sunday.)
12400 * Returns: the number of weeks in @year
12405 * g_date_get_weekday:
12408 * Returns the day of the week for a #GDate. The date must be valid.
12410 * Returns: day of the week as a #GDateWeekday.
12418 * Returns the year of a #GDate. The date must be valid.
12420 * Returns: year in which the date falls
12425 * g_date_is_first_of_month:
12426 * @date: a #GDate to check
12428 * Returns %TRUE if the date is on the first of a month.
12429 * The date must be valid.
12431 * Returns: %TRUE if the date is the first of the month
12436 * g_date_is_last_of_month:
12437 * @date: a #GDate to check
12439 * Returns %TRUE if the date is the last day of the month.
12440 * The date must be valid.
12442 * Returns: %TRUE if the date is the last day of the month
12447 * g_date_is_leap_year:
12448 * @year: year to check
12450 * Returns %TRUE if the year is a leap year.
12452 * For the purposes of this function, leap year is every year
12453 * divisible by 4 unless that year is divisible by 100. If it
12454 * is divisible by 100 it would be a leap year only if that year
12455 * is also divisible by 400.
12457 * Returns: %TRUE if the year is a leap year
12464 * Allocates a #GDate and initializes
12465 * it to a sane state. The new date will
12466 * be cleared (as if you'd called g_date_clear()) but invalid (it won't
12467 * represent an existing day). Free the return value with g_date_free().
12469 * Returns: a newly-allocated #GDate
12475 * @day: day of the month
12476 * @month: month of the year
12479 * Like g_date_new(), but also sets the value of the date. Assuming the
12480 * day-month-year triplet you pass in represents an existing day, the
12481 * returned date will be valid.
12483 * Returns: a newly-allocated #GDate initialized with @day, @month, and @year
12488 * g_date_new_julian:
12489 * @julian_day: days since January 1, Year 1
12491 * Like g_date_new(), but also sets the value of the date. Assuming the
12492 * Julian day number you pass in is valid (greater than 0, less than an
12493 * unreasonably large number), the returned date will be valid.
12495 * Returns: a newly-allocated #GDate initialized with @julian_day
12501 * @date1: the first date
12502 * @date2: the second date
12504 * Checks if @date1 is less than or equal to @date2,
12505 * and swap the values if this is not the case.
12514 * Sets the day of the month for a #GDate. If the resulting
12515 * day-month-year triplet is invalid, the date will be invalid.
12526 * Sets the value of a #GDate from a day, month, and year.
12527 * The day-month-year triplet must be valid; if you aren't
12528 * sure it is, call g_date_valid_dmy() to check before you
12534 * g_date_set_julian:
12536 * @julian_date: Julian day number (days since January 1, Year 1)
12538 * Sets the value of a #GDate from a Julian day number.
12543 * g_date_set_month:
12545 * @month: month to set
12547 * Sets the month of the year for a #GDate. If the resulting
12548 * day-month-year triplet is invalid, the date will be invalid.
12553 * g_date_set_parse:
12554 * @date: a #GDate to fill in
12555 * @str: string to parse
12557 * Parses a user-inputted string @str, and try to figure out what date it
12558 * represents, taking the [current locale][setlocale] into account. If the
12559 * string is successfully parsed, the date will be valid after the call.
12560 * Otherwise, it will be invalid. You should check using g_date_valid()
12561 * to see whether the parsing succeeded.
12563 * This function is not appropriate for file formats and the like; it
12564 * isn't very precise, and its exact behavior varies with the locale.
12565 * It's intended to be a heuristic routine that guesses what the user
12566 * means by a given string (and it does work pretty well in that
12574 * @time_: #GTime value to set.
12576 * Sets the value of a date from a #GTime value.
12577 * The time to date conversion is done using the user's current timezone.
12579 * Deprecated: 2.10: Use g_date_set_time_t() instead.
12584 * g_date_set_time_t:
12586 * @timet: time_t value to set
12588 * Sets the value of a date to the date corresponding to a time
12589 * specified as a time_t. The time to date conversion is done using
12590 * the user's current timezone.
12592 * To set the value of a date to the current day, you could write:
12593 * |[<!-- language="C" -->
12594 * g_date_set_time_t (date, time (NULL));
12602 * g_date_set_time_val:
12604 * @timeval: #GTimeVal value to set
12606 * Sets the value of a date from a #GTimeVal value. Note that the
12607 * @tv_usec member is ignored, because #GDate can't make use of the
12608 * additional precision.
12610 * The time to date conversion is done using the user's current timezone.
12619 * @year: year to set
12621 * Sets the year for a #GDate. If the resulting day-month-year
12622 * triplet is invalid, the date will be invalid.
12628 * @s: destination buffer
12629 * @slen: buffer size
12630 * @format: format string
12631 * @date: valid #GDate
12633 * Generates a printed representation of the date, in a
12634 * [locale][setlocale]-specific way.
12635 * Works just like the platform's C library strftime() function,
12636 * but only accepts date-related formats; time-related formats
12637 * give undefined results. Date must be valid. Unlike strftime()
12638 * (which uses the locale encoding), works on a UTF-8 format
12639 * string and stores a UTF-8 result.
12641 * This function does not provide any conversion specifiers in
12642 * addition to those implemented by the platform's C library.
12643 * For example, don't expect that using g_date_strftime() would
12644 * make the \%F provided by the C99 strftime() work on Windows
12645 * where the C library only complies to C89.
12647 * Returns: number of characters written to the buffer, or 0 the buffer was too small
12652 * g_date_subtract_days:
12653 * @date: a #GDate to decrement
12654 * @n_days: number of days to move
12656 * Moves a date some number of days into the past.
12657 * To move by weeks, just move by weeks*7 days.
12658 * The date must be valid.
12663 * g_date_subtract_months:
12664 * @date: a #GDate to decrement
12665 * @n_months: number of months to move
12667 * Moves a date some number of months into the past.
12668 * If the current day of the month doesn't exist in
12669 * the destination month, the day of the month
12670 * may change. The date must be valid.
12675 * g_date_subtract_years:
12676 * @date: a #GDate to decrement
12677 * @n_years: number of years to move
12679 * Moves a date some number of years into the past.
12680 * If the current day doesn't exist in the destination
12681 * year (i.e. it's February 29 and you move to a non-leap-year)
12682 * then the day is changed to February 29. The date
12689 * @datetime: a #GDateTime
12690 * @timespan: a #GTimeSpan
12692 * Creates a copy of @datetime and adds the specified timespan to the copy.
12694 * Returns: the newly created #GDateTime which should be freed with
12695 * g_date_time_unref().
12701 * g_date_time_add_days:
12702 * @datetime: a #GDateTime
12703 * @days: the number of days
12705 * Creates a copy of @datetime and adds the specified number of days to the
12706 * copy. Add negative values to subtract days.
12708 * Returns: the newly created #GDateTime which should be freed with
12709 * g_date_time_unref().
12715 * g_date_time_add_full:
12716 * @datetime: a #GDateTime
12717 * @years: the number of years to add
12718 * @months: the number of months to add
12719 * @days: the number of days to add
12720 * @hours: the number of hours to add
12721 * @minutes: the number of minutes to add
12722 * @seconds: the number of seconds to add
12724 * Creates a new #GDateTime adding the specified values to the current date and
12725 * time in @datetime. Add negative values to subtract.
12727 * Returns: the newly created #GDateTime that should be freed with
12728 * g_date_time_unref().
12734 * g_date_time_add_hours:
12735 * @datetime: a #GDateTime
12736 * @hours: the number of hours to add
12738 * Creates a copy of @datetime and adds the specified number of hours.
12739 * Add negative values to subtract hours.
12741 * Returns: the newly created #GDateTime which should be freed with
12742 * g_date_time_unref().
12748 * g_date_time_add_minutes:
12749 * @datetime: a #GDateTime
12750 * @minutes: the number of minutes to add
12752 * Creates a copy of @datetime adding the specified number of minutes.
12753 * Add negative values to subtract minutes.
12755 * Returns: the newly created #GDateTime which should be freed with
12756 * g_date_time_unref().
12762 * g_date_time_add_months:
12763 * @datetime: a #GDateTime
12764 * @months: the number of months
12766 * Creates a copy of @datetime and adds the specified number of months to the
12767 * copy. Add negative values to subtract months.
12769 * Returns: the newly created #GDateTime which should be freed with
12770 * g_date_time_unref().
12776 * g_date_time_add_seconds:
12777 * @datetime: a #GDateTime
12778 * @seconds: the number of seconds to add
12780 * Creates a copy of @datetime and adds the specified number of seconds.
12781 * Add negative values to subtract seconds.
12783 * Returns: the newly created #GDateTime which should be freed with
12784 * g_date_time_unref().
12790 * g_date_time_add_weeks:
12791 * @datetime: a #GDateTime
12792 * @weeks: the number of weeks
12794 * Creates a copy of @datetime and adds the specified number of weeks to the
12795 * copy. Add negative values to subtract weeks.
12797 * Returns: the newly created #GDateTime which should be freed with
12798 * g_date_time_unref().
12804 * g_date_time_add_years:
12805 * @datetime: a #GDateTime
12806 * @years: the number of years
12808 * Creates a copy of @datetime and adds the specified number of years to the
12809 * copy. Add negative values to subtract years.
12811 * Returns: the newly created #GDateTime which should be freed with
12812 * g_date_time_unref().
12818 * g_date_time_compare:
12819 * @dt1: first #GDateTime to compare
12820 * @dt2: second #GDateTime to compare
12822 * A comparison function for #GDateTimes that is suitable
12823 * as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
12825 * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
12832 * g_date_time_difference:
12833 * @end: a #GDateTime
12834 * @begin: a #GDateTime
12836 * Calculates the difference in time between @end and @begin. The
12837 * #GTimeSpan that is returned is effectively @end - @begin (ie:
12838 * positive if the first parameter is larger).
12840 * Returns: the difference between the two #GDateTime, as a time
12841 * span expressed in microseconds.
12847 * g_date_time_equal:
12848 * @dt1: a #GDateTime
12849 * @dt2: a #GDateTime
12851 * Checks to see if @dt1 and @dt2 are equal.
12853 * Equal here means that they represent the same moment after converting
12854 * them to the same time zone.
12856 * Returns: %TRUE if @dt1 and @dt2 are equal
12862 * g_date_time_format:
12863 * @datetime: A #GDateTime
12864 * @format: a valid UTF-8 string, containing the format for the
12867 * Creates a newly allocated string representing the requested @format.
12869 * The format strings understood by this function are a subset of the
12870 * strftime() format language as specified by C99. The \%D, \%U and \%W
12871 * conversions are not supported, nor is the 'E' modifier. The GNU
12872 * extensions \%k, \%l, \%s and \%P are supported, however, as are the
12873 * '0', '_' and '-' modifiers.
12875 * In contrast to strftime(), this function always produces a UTF-8
12876 * string, regardless of the current locale. Note that the rendering of
12877 * many formats is locale-dependent and may not match the strftime()
12880 * The following format specifiers are supported:
12882 * - \%a: the abbreviated weekday name according to the current locale
12883 * - \%A: the full weekday name according to the current locale
12884 * - \%b: the abbreviated month name according to the current locale
12885 * - \%B: the full month name according to the current locale
12886 * - \%c: the preferred date and time rpresentation for the current locale
12887 * - \%C: the century number (year/100) as a 2-digit integer (00-99)
12888 * - \%d: the day of the month as a decimal number (range 01 to 31)
12889 * - \%e: the day of the month as a decimal number (range 1 to 31)
12890 * - \%F: equivalent to `\%Y-\%m-\%d` (the ISO 8601 date format)
12891 * - \%g: the last two digits of the ISO 8601 week-based year as a
12892 * decimal number (00-99). This works well with \%V and \%u.
12893 * - \%G: the ISO 8601 week-based year as a decimal number. This works
12894 * well with \%V and \%u.
12895 * - \%h: equivalent to \%b
12896 * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
12897 * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
12898 * - \%j: the day of the year as a decimal number (range 001 to 366)
12899 * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
12900 * single digits are preceded by a blank
12901 * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
12902 * single digits are preceded by a blank
12903 * - \%m: the month as a decimal number (range 01 to 12)
12904 * - \%M: the minute as a decimal number (range 00 to 59)
12905 * - \%p: either "AM" or "PM" according to the given time value, or the
12906 * corresponding strings for the current locale. Noon is treated as
12907 * "PM" and midnight as "AM".
12908 * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
12909 * the current locale
12910 * - \%r: the time in a.m. or p.m. notation
12911 * - \%R: the time in 24-hour notation (\%H:\%M)
12912 * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01
12914 * - \%S: the second as a decimal number (range 00 to 60)
12915 * - \%t: a tab character
12916 * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
12917 * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
12918 * Monday being 1. This works well with \%G and \%V.
12919 * - \%V: the ISO 8601 standard week number of the current year as a decimal
12920 * number, range 01 to 53, where week 1 is the first week that has at
12921 * least 4 days in the new year. See g_date_time_get_week_of_year().
12922 * This works well with \%G and \%u.
12923 * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
12924 * This is not the ISO 8601 standard format -- use \%u instead.
12925 * - \%x: the preferred date representation for the current locale without
12927 * - \%X: the preferred time representation for the current locale without
12929 * - \%y: the year as a decimal number without the century
12930 * - \%Y: the year as a decimal number including the century
12931 * - \%z: the time zone as an offset from UTC (+hhmm)
12932 * - \%:z: the time zone as an offset from UTC (+hh:mm).
12933 * This is a gnulib strftime() extension. Since: 2.38
12934 * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
12935 * gnulib strftime() extension. Since: 2.38
12936 * - \%:::z: the time zone as an offset from UTC, with : to necessary
12937 * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
12938 * - \%Z: the time zone or name or abbreviation
12939 * - \%\%: a literal \% character
12941 * Some conversion specifications can be modified by preceding the
12942 * conversion specifier by one or more modifier characters. The
12943 * following modifiers are supported for many of the numeric
12946 * - O: Use alternative numeric symbols, if the current locale supports those.
12947 * - _: Pad a numeric result with spaces. This overrides the default padding
12948 * for the specifier.
12949 * - -: Do not pad a numeric result. This overrides the default padding
12950 * for the specifier.
12951 * - 0: Pad a numeric result with zeros. This overrides the default padding
12952 * for the specifier.
12954 * Returns: a newly allocated string formatted to the requested format
12955 * or %NULL in the case that there was an error. The string
12956 * should be freed with g_free().
12962 * g_date_time_get_day_of_month:
12963 * @datetime: a #GDateTime
12965 * Retrieves the day of the month represented by @datetime in the gregorian
12968 * Returns: the day of the month
12974 * g_date_time_get_day_of_week:
12975 * @datetime: a #GDateTime
12977 * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
12978 * Monday, 2 is Tuesday... 7 is Sunday).
12980 * Returns: the day of the week
12986 * g_date_time_get_day_of_year:
12987 * @datetime: a #GDateTime
12989 * Retrieves the day of the year represented by @datetime in the Gregorian
12992 * Returns: the day of the year
12998 * g_date_time_get_hour:
12999 * @datetime: a #GDateTime
13001 * Retrieves the hour of the day represented by @datetime
13003 * Returns: the hour of the day
13009 * g_date_time_get_microsecond:
13010 * @datetime: a #GDateTime
13012 * Retrieves the microsecond of the date represented by @datetime
13014 * Returns: the microsecond of the second
13020 * g_date_time_get_minute:
13021 * @datetime: a #GDateTime
13023 * Retrieves the minute of the hour represented by @datetime
13025 * Returns: the minute of the hour
13031 * g_date_time_get_month:
13032 * @datetime: a #GDateTime
13034 * Retrieves the month of the year represented by @datetime in the Gregorian
13037 * Returns: the month represented by @datetime
13043 * g_date_time_get_second:
13044 * @datetime: a #GDateTime
13046 * Retrieves the second of the minute represented by @datetime
13048 * Returns: the second represented by @datetime
13054 * g_date_time_get_seconds:
13055 * @datetime: a #GDateTime
13057 * Retrieves the number of seconds since the start of the last minute,
13058 * including the fractional part.
13060 * Returns: the number of seconds
13066 * g_date_time_get_timezone_abbreviation:
13067 * @datetime: a #GDateTime
13069 * Determines the time zone abbreviation to be used at the time and in
13070 * the time zone of @datetime.
13072 * For example, in Toronto this is currently "EST" during the winter
13073 * months and "EDT" during the summer months when daylight savings
13074 * time is in effect.
13076 * Returns: (transfer none): the time zone abbreviation. The returned
13077 * string is owned by the #GDateTime and it should not be
13078 * modified or freed
13084 * g_date_time_get_utc_offset:
13085 * @datetime: a #GDateTime
13087 * Determines the offset to UTC in effect at the time and in the time
13088 * zone of @datetime.
13090 * The offset is the number of microseconds that you add to UTC time to
13091 * arrive at local time for the time zone (ie: negative numbers for time
13092 * zones west of GMT, positive numbers for east).
13094 * If @datetime represents UTC time, then the offset is always zero.
13096 * Returns: the number of microseconds that should be added to UTC to
13097 * get the local time
13103 * g_date_time_get_week_numbering_year:
13104 * @datetime: a #GDateTime
13106 * Returns the ISO 8601 week-numbering year in which the week containing
13109 * This function, taken together with g_date_time_get_week_of_year() and
13110 * g_date_time_get_day_of_week() can be used to determine the full ISO
13111 * week date on which @datetime falls.
13113 * This is usually equal to the normal Gregorian year (as returned by
13114 * g_date_time_get_year()), except as detailed below:
13116 * For Thursday, the week-numbering year is always equal to the usual
13117 * calendar year. For other days, the number is such that every day
13118 * within a complete week (Monday to Sunday) is contained within the
13119 * same week-numbering year.
13121 * For Monday, Tuesday and Wednesday occurring near the end of the year,
13122 * this may mean that the week-numbering year is one greater than the
13123 * calendar year (so that these days have the same week-numbering year
13124 * as the Thursday occurring early in the next year).
13126 * For Friday, Saturaday and Sunday occurring near the start of the year,
13127 * this may mean that the week-numbering year is one less than the
13128 * calendar year (so that these days have the same week-numbering year
13129 * as the Thursday occurring late in the previous year).
13131 * An equivalent description is that the week-numbering year is equal to
13132 * the calendar year containing the majority of the days in the current
13133 * week (Monday to Sunday).
13135 * Note that January 1 0001 in the proleptic Gregorian calendar is a
13136 * Monday, so this function never returns 0.
13138 * Returns: the ISO 8601 week-numbering year for @datetime
13144 * g_date_time_get_week_of_year:
13145 * @datetime: a #GDateTime
13147 * Returns the ISO 8601 week number for the week containing @datetime.
13148 * The ISO 8601 week number is the same for every day of the week (from
13149 * Moday through Sunday). That can produce some unusual results
13150 * (described below).
13152 * The first week of the year is week 1. This is the week that contains
13153 * the first Thursday of the year. Equivalently, this is the first week
13154 * that has more than 4 of its days falling within the calendar year.
13156 * The value 0 is never returned by this function. Days contained
13157 * within a year but occurring before the first ISO 8601 week of that
13158 * year are considered as being contained in the last week of the
13159 * previous year. Similarly, the final days of a calendar year may be
13160 * considered as being part of the first ISO 8601 week of the next year
13161 * if 4 or more days of that week are contained within the new year.
13163 * Returns: the ISO 8601 week number for @datetime.
13169 * g_date_time_get_year:
13170 * @datetime: A #GDateTime
13172 * Retrieves the year represented by @datetime in the Gregorian calendar.
13174 * Returns: the year represented by @datetime
13180 * g_date_time_get_ymd:
13181 * @datetime: a #GDateTime.
13182 * @year: (out) (allow-none): the return location for the gregorian year, or %NULL.
13183 * @month: (out) (allow-none): the return location for the month of the year, or %NULL.
13184 * @day: (out) (allow-none): the return location for the day of the month, or %NULL.
13186 * Retrieves the Gregorian day, month, and year of a given #GDateTime.
13193 * g_date_time_hash:
13194 * @datetime: a #GDateTime
13196 * Hashes @datetime into a #guint, suitable for use within #GHashTable.
13198 * Returns: a #guint containing the hash
13204 * g_date_time_is_daylight_savings:
13205 * @datetime: a #GDateTime
13207 * Determines if daylight savings time is in effect at the time and in
13208 * the time zone of @datetime.
13210 * Returns: %TRUE if daylight savings time is in effect
13217 * @tz: a #GTimeZone
13218 * @year: the year component of the date
13219 * @month: the month component of the date
13220 * @day: the day component of the date
13221 * @hour: the hour component of the date
13222 * @minute: the minute component of the date
13223 * @seconds: the number of seconds past the minute
13225 * Creates a new #GDateTime corresponding to the given date and time in
13226 * the time zone @tz.
13228 * The @year must be between 1 and 9999, @month between 1 and 12 and @day
13229 * between 1 and 28, 29, 30 or 31 depending on the month and the year.
13231 * @hour must be between 0 and 23 and @minute must be between 0 and 59.
13233 * @seconds must be at least 0.0 and must be strictly less than 60.0.
13234 * It will be rounded down to the nearest microsecond.
13236 * If the given time is not representable in the given time zone (for
13237 * example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
13238 * time) then the time will be rounded up to the nearest existing time
13239 * (in this case, 03:00). If this matters to you then you should verify
13240 * the return value for containing the same as the numbers you gave.
13242 * In the case that the given time is ambiguous in the given time zone
13243 * (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
13244 * savings time) then the time falling within standard (ie:
13245 * non-daylight) time is taken.
13247 * It not considered a programmer error for the values to this function
13248 * to be out of range, but in the case that they are, the function will
13251 * You should release the return value by calling g_date_time_unref()
13252 * when you are done with it.
13254 * Returns: a new #GDateTime, or %NULL
13260 * g_date_time_new_from_timeval_local:
13263 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
13266 * The time contained in a #GTimeVal is always stored in the form of
13267 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
13268 * local time offset.
13270 * This call can fail (returning %NULL) if @tv represents a time outside
13271 * of the supported range of #GDateTime.
13273 * You should release the return value by calling g_date_time_unref()
13274 * when you are done with it.
13276 * Returns: a new #GDateTime, or %NULL
13282 * g_date_time_new_from_timeval_utc:
13285 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
13287 * The time contained in a #GTimeVal is always stored in the form of
13288 * seconds elapsed since 1970-01-01 00:00:00 UTC.
13290 * This call can fail (returning %NULL) if @tv represents a time outside
13291 * of the supported range of #GDateTime.
13293 * You should release the return value by calling g_date_time_unref()
13294 * when you are done with it.
13296 * Returns: a new #GDateTime, or %NULL
13302 * g_date_time_new_from_unix_local:
13303 * @t: the Unix time
13305 * Creates a #GDateTime corresponding to the given Unix time @t in the
13308 * Unix time is the number of seconds that have elapsed since 1970-01-01
13309 * 00:00:00 UTC, regardless of the local time offset.
13311 * This call can fail (returning %NULL) if @t represents a time outside
13312 * of the supported range of #GDateTime.
13314 * You should release the return value by calling g_date_time_unref()
13315 * when you are done with it.
13317 * Returns: a new #GDateTime, or %NULL
13323 * g_date_time_new_from_unix_utc:
13324 * @t: the Unix time
13326 * Creates a #GDateTime corresponding to the given Unix time @t in UTC.
13328 * Unix time is the number of seconds that have elapsed since 1970-01-01
13331 * This call can fail (returning %NULL) if @t represents a time outside
13332 * of the supported range of #GDateTime.
13334 * You should release the return value by calling g_date_time_unref()
13335 * when you are done with it.
13337 * Returns: a new #GDateTime, or %NULL
13343 * g_date_time_new_local:
13344 * @year: the year component of the date
13345 * @month: the month component of the date
13346 * @day: the day component of the date
13347 * @hour: the hour component of the date
13348 * @minute: the minute component of the date
13349 * @seconds: the number of seconds past the minute
13351 * Creates a new #GDateTime corresponding to the given date and time in
13352 * the local time zone.
13354 * This call is equivalent to calling g_date_time_new() with the time
13355 * zone returned by g_time_zone_new_local().
13357 * Returns: a #GDateTime, or %NULL
13363 * g_date_time_new_now:
13364 * @tz: a #GTimeZone
13366 * Creates a #GDateTime corresponding to this exact instant in the given
13367 * time zone @tz. The time is as accurate as the system allows, to a
13368 * maximum accuracy of 1 microsecond.
13370 * This function will always succeed unless the system clock is set to
13371 * truly insane values (or unless GLib is still being used after the
13374 * You should release the return value by calling g_date_time_unref()
13375 * when you are done with it.
13377 * Returns: a new #GDateTime, or %NULL
13383 * g_date_time_new_now_local:
13385 * Creates a #GDateTime corresponding to this exact instant in the local
13388 * This is equivalent to calling g_date_time_new_now() with the time
13389 * zone returned by g_time_zone_new_local().
13391 * Returns: a new #GDateTime, or %NULL
13397 * g_date_time_new_now_utc:
13399 * Creates a #GDateTime corresponding to this exact instant in UTC.
13401 * This is equivalent to calling g_date_time_new_now() with the time
13402 * zone returned by g_time_zone_new_utc().
13404 * Returns: a new #GDateTime, or %NULL
13410 * g_date_time_new_utc:
13411 * @year: the year component of the date
13412 * @month: the month component of the date
13413 * @day: the day component of the date
13414 * @hour: the hour component of the date
13415 * @minute: the minute component of the date
13416 * @seconds: the number of seconds past the minute
13418 * Creates a new #GDateTime corresponding to the given date and time in
13421 * This call is equivalent to calling g_date_time_new() with the time
13422 * zone returned by g_time_zone_new_utc().
13424 * Returns: a #GDateTime, or %NULL
13431 * @datetime: a #GDateTime
13433 * Atomically increments the reference count of @datetime by one.
13435 * Returns: the #GDateTime with the reference count increased
13441 * g_date_time_to_local:
13442 * @datetime: a #GDateTime
13444 * Creates a new #GDateTime corresponding to the same instant in time as
13445 * @datetime, but in the local time zone.
13447 * This call is equivalent to calling g_date_time_to_timezone() with the
13448 * time zone returned by g_time_zone_new_local().
13450 * Returns: the newly created #GDateTime
13456 * g_date_time_to_timeval:
13457 * @datetime: a #GDateTime
13458 * @tv: a #GTimeVal to modify
13460 * Stores the instant in time that @datetime represents into @tv.
13462 * The time contained in a #GTimeVal is always stored in the form of
13463 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
13464 * zone associated with @datetime.
13466 * On systems where 'long' is 32bit (ie: all 32bit systems and all
13467 * Windows systems), a #GTimeVal is incapable of storing the entire
13468 * range of values that #GDateTime is capable of expressing. On those
13469 * systems, this function returns %FALSE to indicate that the time is
13472 * On systems where 'long' is 64bit, this function never fails.
13474 * Returns: %TRUE if successful, else %FALSE
13480 * g_date_time_to_timezone:
13481 * @datetime: a #GDateTime
13482 * @tz: the new #GTimeZone
13484 * Create a new #GDateTime corresponding to the same instant in time as
13485 * @datetime, but in the time zone @tz.
13487 * This call can fail in the case that the time goes out of bounds. For
13488 * example, converting 0001-01-01 00:00:00 UTC to a time zone west of
13489 * Greenwich will fail (due to the year 0 being out of range).
13491 * You should release the return value by calling g_date_time_unref()
13492 * when you are done with it.
13494 * Returns: a new #GDateTime, or %NULL
13500 * g_date_time_to_unix:
13501 * @datetime: a #GDateTime
13503 * Gives the Unix time corresponding to @datetime, rounding down to the
13506 * Unix time is the number of seconds that have elapsed since 1970-01-01
13507 * 00:00:00 UTC, regardless of the time zone associated with @datetime.
13509 * Returns: the Unix time corresponding to @datetime
13515 * g_date_time_to_utc:
13516 * @datetime: a #GDateTime
13518 * Creates a new #GDateTime corresponding to the same instant in time as
13519 * @datetime, but in UTC.
13521 * This call is equivalent to calling g_date_time_to_timezone() with the
13522 * time zone returned by g_time_zone_new_utc().
13524 * Returns: the newly created #GDateTime
13530 * g_date_time_unref:
13531 * @datetime: a #GDateTime
13533 * Atomically decrements the reference count of @datetime by one.
13535 * When the reference count reaches zero, the resources allocated by
13536 * @datetime are freed
13543 * g_date_to_struct_tm:
13544 * @date: a #GDate to set the struct tm from
13545 * @tm: struct tm to fill
13547 * Fills in the date-related bits of a struct tm using the @date value.
13548 * Initializes the non-date parts with something sane but meaningless.
13554 * @date: a #GDate to check
13556 * Returns %TRUE if the #GDate represents an existing day. The date must not
13557 * contain garbage; it should have been initialized with g_date_clear()
13558 * if it wasn't allocated by one of the g_date_new() variants.
13560 * Returns: Whether the date is valid
13565 * g_date_valid_day:
13566 * @day: day to check
13568 * Returns %TRUE if the day of the month is valid (a day is valid if it's
13569 * between 1 and 31 inclusive).
13571 * Returns: %TRUE if the day is valid
13576 * g_date_valid_dmy:
13581 * Returns %TRUE if the day-month-year triplet forms a valid, existing day
13582 * in the range of days #GDate understands (Year 1 or later, no more than
13583 * a few thousand years in the future).
13585 * Returns: %TRUE if the date is a valid one
13590 * g_date_valid_julian:
13591 * @julian_date: Julian day to check
13593 * Returns %TRUE if the Julian day is valid. Anything greater than zero
13594 * is basically a valid Julian, though there is a 32-bit limit.
13596 * Returns: %TRUE if the Julian day is valid
13601 * g_date_valid_month:
13604 * Returns %TRUE if the month value is valid. The 12 #GDateMonth
13605 * enumeration values are the only valid months.
13607 * Returns: %TRUE if the month is valid
13612 * g_date_valid_weekday:
13613 * @weekday: weekday
13615 * Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
13616 * values are the only valid weekdays.
13618 * Returns: %TRUE if the weekday is valid
13623 * g_date_valid_year:
13626 * Returns %TRUE if the year is valid. Any year greater than 0 is valid,
13627 * though there is a 16-bit limit to what #GDate will understand.
13629 * Returns: %TRUE if the year is valid
13635 * @domain: (allow-none): the translation domain to use, or %NULL to use
13636 * the domain set with textdomain()
13637 * @msgid: message to translate
13638 * @category: a locale category
13640 * This is a variant of g_dgettext() that allows specifying a locale
13641 * category instead of always using `LC_MESSAGES`. See g_dgettext() for
13642 * more information about how this functions differs from calling
13643 * dcgettext() directly.
13645 * Returns: the translated string for the given locale category
13652 * @...: format string, followed by parameters to insert
13653 * into the format string (as with printf())
13655 * A convenience function/macro to log a debug message.
13657 * If g_log_default_handler() is used as the log handler function, a new-line
13658 * character will automatically be appended to @..., and need not be entered
13661 * Such messages are suppressed by the g_log_default_handler() unless
13662 * the G_MESSAGES_DEBUG environment variable is set appropriately.
13670 * @domain: (allow-none): the translation domain to use, or %NULL to use
13671 * the domain set with textdomain()
13672 * @msgid: message to translate
13674 * This function is a wrapper of dgettext() which does not translate
13675 * the message if the default domain as set with textdomain() has no
13676 * translations for the current locale.
13678 * The advantage of using this function over dgettext() proper is that
13679 * libraries using this function (like GTK+) will not use translations
13680 * if the application using the library does not have translations for
13681 * the current locale. This results in a consistent English-only
13682 * interface instead of one having partial translations. For this
13683 * feature to work, the call to textdomain() and setlocale() should
13684 * precede any g_dgettext() invocations. For GTK+, it means calling
13685 * textdomain() before gtk_init or its variants.
13687 * This function disables translations if and only if upon its first
13688 * call all the following conditions hold:
13690 * - @domain is not %NULL
13692 * - textdomain() has been called to set a default text domain
13694 * - there is no translations available for the default text domain
13695 * and the current locale
13697 * - current locale is not "C" or any English locales (those
13698 * starting with "en_")
13700 * Note that this behavior may not be desired for example if an application
13701 * has its untranslated messages in a language other than English. In those
13702 * cases the application should call textdomain() after initializing GTK+.
13704 * Applications should normally not use this function directly,
13705 * but use the _() macro for translations.
13707 * Returns: The translated string
13714 * @dir: a #GDir* created by g_dir_open()
13716 * Closes the directory and deallocates all related resources.
13722 * @tmpl: (type filename) (allow-none): Template for directory name,
13723 * as in g_mkdtemp(), basename only, or %NULL for a default template
13724 * @error: return location for a #GError
13726 * Creates a subdirectory in the preferred directory for temporary
13727 * files (as returned by g_get_tmp_dir()).
13729 * @tmpl should be a string in the GLib file name encoding containing
13730 * a sequence of six 'X' characters, as the parameter to g_mkstemp().
13731 * However, unlike these functions, the template should only be a
13732 * basename, no directory components are allowed. If template is
13733 * %NULL, a default template is used.
13735 * Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not
13736 * modified, and might thus be a read-only literal string.
13738 * Returns: (type filename): The actual name used. This string
13739 * should be freed with g_free() when not needed any longer and is
13740 * is in the GLib file name encoding. In case of errors, %NULL is
13741 * returned and @error will be set.
13748 * @path: the path to the directory you are interested in. On Unix
13749 * in the on-disk encoding. On Windows in UTF-8
13750 * @flags: Currently must be set to 0. Reserved for future use.
13751 * @error: return location for a #GError, or %NULL.
13752 * If non-%NULL, an error will be set if and only if
13753 * g_dir_open() fails.
13755 * Opens a directory for reading. The names of the files in the
13756 * directory can then be retrieved using g_dir_read_name(). Note
13757 * that the ordering is not defined.
13759 * Returns: a newly allocated #GDir on success, %NULL on failure.
13760 * If non-%NULL, you must free the result with g_dir_close()
13761 * when you are finished with it.
13767 * @dir: a #GDir* created by g_dir_open()
13769 * Retrieves the name of another entry in the directory, or %NULL.
13770 * The order of entries returned from this function is not defined,
13771 * and may vary by file system or other operating-system dependent
13774 * %NULL may also be returned in case of errors. On Unix, you can
13775 * check `errno` to find out if %NULL was returned because of an error.
13777 * On Unix, the '.' and '..' entries are omitted, and the returned
13778 * name is in the on-disk encoding.
13780 * On Windows, as is true of all GLib functions which operate on
13781 * filenames, the returned name is in UTF-8.
13783 * Returns: The entry's name or %NULL if there are no
13784 * more entries. The return value is owned by GLib and
13785 * must not be modified or freed.
13791 * @dir: a #GDir* created by g_dir_open()
13793 * Resets the given directory. The next call to g_dir_read_name()
13794 * will return the first entry again.
13800 * @v1: (allow-none): a key
13801 * @v2: (allow-none): a key to compare with @v1
13803 * Compares two #gpointer arguments and returns %TRUE if they are equal.
13804 * It can be passed to g_hash_table_new() as the @key_equal_func
13805 * parameter, when using opaque pointers compared by pointer value as
13806 * keys in a #GHashTable.
13808 * This equality function is also appropriate for keys that are integers
13809 * stored in pointers, such as `GINT_TO_POINTER (n)`.
13811 * Returns: %TRUE if the two keys match.
13817 * @v: (allow-none): a #gpointer key
13819 * Converts a gpointer to a hash value.
13820 * It can be passed to g_hash_table_new() as the @hash_func parameter,
13821 * when using opaque pointers compared by pointer value as keys in a
13824 * This hash function is also appropriate for keys that are integers
13825 * stored in pointers, such as `GINT_TO_POINTER (n)`.
13827 * Returns: a hash value corresponding to the key.
13833 * @file_name: the name of the file
13835 * Gets the directory components of a file name.
13837 * If the file name has no directory components "." is returned.
13838 * The returned string should be freed when no longer needed.
13840 * Returns: the directory components of the file
13841 * Deprecated: use g_path_get_dirname() instead
13847 * @domain: (allow-none): the translation domain to use, or %NULL to use
13848 * the domain set with textdomain()
13849 * @msgid: message to translate
13850 * @msgid_plural: plural form of the message
13851 * @n: the quantity for which translation is needed
13853 * This function is a wrapper of dngettext() which does not translate
13854 * the message if the default domain as set with textdomain() has no
13855 * translations for the current locale.
13857 * See g_dgettext() for details of how this differs from dngettext()
13860 * Returns: The translated string
13867 * @v1: a pointer to a #gdouble key
13868 * @v2: a pointer to a #gdouble key to compare with @v1
13870 * Compares the two #gdouble values being pointed to and returns
13871 * %TRUE if they are equal.
13872 * It can be passed to g_hash_table_new() as the @key_equal_func
13873 * parameter, when using non-%NULL pointers to doubles as keys in a
13876 * Returns: %TRUE if the two keys match.
13883 * @v: a pointer to a #gdouble key
13885 * Converts a pointer to a #gdouble to a hash value.
13886 * It can be passed to g_hash_table_new() as the @hash_func parameter,
13887 * It can be passed to g_hash_table_new() as the @hash_func parameter,
13888 * when using non-%NULL pointers to doubles as keys in a #GHashTable.
13890 * Returns: a hash value corresponding to the key.
13897 * @domain: (allow-none): the translation domain to use, or %NULL to use
13898 * the domain set with textdomain()
13899 * @msgctxtid: a combined message context and message id, separated
13900 * by a \004 character
13901 * @msgidoffset: the offset of the message id in @msgctxid
13903 * This function is a variant of g_dgettext() which supports
13904 * a disambiguating message context. GNU gettext uses the
13905 * '\004' character to separate the message context and
13906 * message id in @msgctxtid.
13907 * If 0 is passed as @msgidoffset, this function will fall back to
13908 * trying to use the deprecated convention of using "|" as a separation
13911 * This uses g_dgettext() internally. See that functions for differences
13912 * with dgettext() proper.
13914 * Applications should normally not use this function directly,
13915 * but use the C_() macro for translations with context.
13917 * Returns: The translated string
13924 * @domain: (allow-none): the translation domain to use, or %NULL to use
13925 * the domain set with textdomain()
13926 * @context: the message context
13927 * @msgid: the message
13929 * This function is a variant of g_dgettext() which supports
13930 * a disambiguating message context. GNU gettext uses the
13931 * '\004' character to separate the message context and
13932 * message id in @msgctxtid.
13934 * This uses g_dgettext() internally. See that functions for differences
13935 * with dgettext() proper.
13937 * This function differs from C_() in that it is not a macro and
13938 * thus you may use non-string-literals as context and msgid arguments.
13940 * Returns: The translated string
13946 * g_environ_getenv:
13947 * @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment
13948 * list (eg, as returned from g_get_environ()), or %NULL
13949 * for an empty environment list
13950 * @variable: the environment variable to get, in the GLib file name
13953 * Returns the value of the environment variable @variable in the
13954 * provided list @envp.
13956 * Returns: the value of the environment variable, or %NULL if
13957 * the environment variable is not set in @envp. The returned
13958 * string is owned by @envp, and will be freed if @variable is
13959 * set or unset again.
13965 * g_environ_setenv:
13966 * @envp: (allow-none) (array zero-terminated=1) (transfer full): an
13967 * environment list that can be freed using g_strfreev() (e.g., as
13968 * returned from g_get_environ()), or %NULL for an empty
13970 * @variable: the environment variable to set, must not contain '='
13971 * @value: the value for to set the variable to
13972 * @overwrite: whether to change the variable if it already exists
13974 * Sets the environment variable @variable in the provided list
13977 * Returns: (array zero-terminated=1) (transfer full): the
13978 * updated environment list. Free it using g_strfreev().
13984 * g_environ_unsetenv:
13985 * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment
13986 * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()),
13987 * or %NULL for an empty environment list
13988 * @variable: the environment variable to remove, must not contain '='
13990 * Removes the environment variable @variable from the provided
13991 * environment @envp.
13993 * Returns: (array zero-terminated=1) (transfer full): the
13994 * updated environment list. Free it using g_strfreev().
14001 * @...: format string, followed by parameters to insert
14002 * into the format string (as with printf())
14004 * A convenience function/macro to log an error message.
14006 * Error messages are always fatal, resulting in a call to
14007 * abort() to terminate the application. This function will
14008 * result in a core dump; don't use it for errors you expect.
14009 * Using this function indicates a bug in your program, i.e.
14010 * an assertion failure.
14012 * If g_log_default_handler() is used as the log handler function, a new-line
14013 * character will automatically be appended to @..., and need not be entered
14020 * @error: a #GError
14022 * Makes a copy of @error.
14024 * Returns: a new #GError
14030 * @error: a #GError
14032 * Frees a #GError and associated resources.
14038 * @error: (allow-none): a #GError or %NULL
14039 * @domain: an error domain
14040 * @code: an error code
14042 * Returns %TRUE if @error matches @domain and @code, %FALSE
14043 * otherwise. In particular, when @error is %NULL, %FALSE will
14046 * Returns: whether @error has @domain and @code
14052 * @domain: error domain
14053 * @code: error code
14054 * @format: printf()-style format for error message
14055 * @...: parameters for message format
14057 * Creates a new #GError with the given @domain and @code,
14058 * and a message formatted with @format.
14060 * Returns: a new #GError
14065 * g_error_new_literal:
14066 * @domain: error domain
14067 * @code: error code
14068 * @message: error message
14070 * Creates a new #GError; unlike g_error_new(), @message is
14071 * not a printf()-style format string. Use this function if
14072 * @message contains text you don't have control over,
14073 * that could include printf() escape sequences.
14075 * Returns: a new #GError
14080 * g_error_new_valist:
14081 * @domain: error domain
14082 * @code: error code
14083 * @format: printf()-style format for error message
14084 * @args: #va_list of parameters for the message format
14086 * Creates a new #GError with the given @domain and @code,
14087 * and a message formatted with @format.
14089 * Returns: a new #GError
14095 * g_file_error_from_errno:
14096 * @err_no: an "errno" value
14098 * Gets a #GFileError constant based on the passed-in @err_no.
14099 * For example, if you pass in `EEXIST` this function returns
14100 * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
14101 * assume that all #GFileError values will exist.
14103 * Normally a #GFileError value goes into a #GError returned
14104 * from a function that manipulates files. So you would use
14105 * g_file_error_from_errno() when constructing a #GError.
14107 * Returns: #GFileError corresponding to the given @errno
14112 * g_file_get_contents:
14113 * @filename: (type filename): name of a file to read contents from, in the GLib file name encoding
14114 * @contents: (out) (array length=length) (element-type guint8): location to store an allocated string, use g_free() to free
14115 * the returned string
14116 * @length: (allow-none): location to store length in bytes of the contents, or %NULL
14117 * @error: return location for a #GError, or %NULL
14119 * Reads an entire file into allocated memory, with good error
14122 * If the call was successful, it returns %TRUE and sets @contents to the file
14123 * contents and @length to the length of the file contents in bytes. The string
14124 * stored in @contents will be nul-terminated, so for text files you can pass
14125 * %NULL for the @length argument. If the call was not successful, it returns
14126 * %FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error
14127 * codes are those in the #GFileError enumeration. In the error case,
14128 * @contents is set to %NULL and @length is set to zero.
14130 * Returns: %TRUE on success, %FALSE if an error occurred
14136 * @tmpl: (type filename) (allow-none): Template for file name, as in
14137 * g_mkstemp(), basename only, or %NULL for a default template
14138 * @name_used: (out) (type filename): location to store actual name used,
14140 * @error: return location for a #GError
14142 * Opens a file for writing in the preferred directory for temporary
14143 * files (as returned by g_get_tmp_dir()).
14145 * @tmpl should be a string in the GLib file name encoding containing
14146 * a sequence of six 'X' characters, as the parameter to g_mkstemp().
14147 * However, unlike these functions, the template should only be a
14148 * basename, no directory components are allowed. If template is
14149 * %NULL, a default template is used.
14151 * Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not
14152 * modified, and might thus be a read-only literal string.
14154 * Upon success, and if @name_used is non-%NULL, the actual name used
14155 * is returned in @name_used. This string should be freed with g_free()
14156 * when not needed any longer. The returned name is in the GLib file
14159 * Returns: A file handle (as from open()) to the file opened for
14160 * reading and writing. The file is opened in binary mode on platforms
14161 * where there is a difference. The file handle should be closed with
14162 * close(). In case of errors, -1 is returned and @error will be set.
14167 * g_file_read_link:
14168 * @filename: the symbolic link
14169 * @error: return location for a #GError
14171 * Reads the contents of the symbolic link @filename like the POSIX
14172 * readlink() function. The returned string is in the encoding used
14173 * for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
14175 * Returns: A newly-allocated string with the contents of the symbolic link,
14176 * or %NULL if an error occurred.
14182 * g_file_set_contents:
14183 * @filename: (type filename): name of a file to write @contents to, in the GLib file name
14185 * @contents: (array length=length) (element-type guint8): string to write to the file
14186 * @length: length of @contents, or -1 if @contents is a nul-terminated string
14187 * @error: return location for a #GError, or %NULL
14189 * Writes all of @contents to a file named @filename, with good error checking.
14190 * If a file called @filename already exists it will be overwritten.
14192 * This write is atomic in the sense that it is first written to a temporary
14193 * file which is then renamed to the final name. Notes:
14195 * - On UNIX, if @filename already exists hard links to @filename will break.
14196 * Also since the file is recreated, existing permissions, access control
14197 * lists, metadata etc. may be lost. If @filename is a symbolic link,
14198 * the link itself will be replaced, not the linked file.
14200 * - On Windows renaming a file will not remove an existing file with the
14201 * new name, so on Windows there is a race condition between the existing
14202 * file being removed and the temporary file being renamed.
14204 * - On Windows there is no way to remove a file that is open to some
14205 * process, or mapped into memory. Thus, this function will fail if
14206 * @filename already exists and is open.
14208 * If the call was successful, it returns %TRUE. If the call was not successful,
14209 * it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR.
14210 * Possible error codes are those in the #GFileError enumeration.
14212 * Note that the name for the temporary file is constructed by appending up
14213 * to 7 characters to @filename.
14215 * Returns: %TRUE on success, %FALSE if an error occurred
14222 * @filename: a filename to test in the GLib file name encoding
14223 * @test: bitfield of #GFileTest flags
14225 * Returns %TRUE if any of the tests in the bitfield @test are
14226 * %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
14227 * will return %TRUE if the file exists; the check whether it's a
14228 * directory doesn't matter since the existence test is %TRUE. With
14229 * the current set of available tests, there's no point passing in
14230 * more than one test at a time.
14232 * Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
14233 * so for a symbolic link to a regular file g_file_test() will return
14234 * %TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR.
14236 * Note, that for a dangling symbolic link g_file_test() will return
14237 * %TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags.
14239 * You should never use g_file_test() to test whether it is safe
14240 * to perform an operation, because there is always the possibility
14241 * of the condition changing before you actually perform the operation.
14242 * For example, you might think you could use %G_FILE_TEST_IS_SYMLINK
14243 * to know whether it is safe to write to a file without being
14244 * tricked into writing into a different location. It doesn't work!
14245 * |[<!-- language="C" -->
14247 * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
14249 * fd = g_open (filename, O_WRONLY);
14254 * Another thing to note is that %G_FILE_TEST_EXISTS and
14255 * %G_FILE_TEST_IS_EXECUTABLE are implemented using the access()
14256 * system call. This usually doesn't matter, but if your program
14257 * is setuid or setgid it means that these tests will give you
14258 * the answer for the real user ID and group ID, rather than the
14259 * effective user ID and group ID.
14261 * On Windows, there are no symlinks, so testing for
14262 * %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
14263 * %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
14264 * its name indicates that it is executable, checking for well-known
14265 * extensions and those listed in the `PATHEXT` environment variable.
14267 * Returns: whether a test was %TRUE
14272 * g_filename_display_basename:
14273 * @filename: an absolute pathname in the GLib file name encoding
14275 * Returns the display basename for the particular filename, guaranteed
14276 * to be valid UTF-8. The display name might not be identical to the filename,
14277 * for instance there might be problems converting it to UTF-8, and some files
14278 * can be translated in the display.
14280 * If GLib cannot make sense of the encoding of @filename, as a last resort it
14281 * replaces unknown characters with U+FFFD, the Unicode replacement character.
14282 * You can search the result for the UTF-8 encoding of this character (which is
14283 * "\357\277\275" in octal notation) to find out if @filename was in an invalid
14286 * You must pass the whole absolute pathname to this functions so that
14287 * translation of well known locations can be done.
14289 * This function is preferred over g_filename_display_name() if you know the
14290 * whole path, as it allows translation.
14292 * Returns: a newly allocated string containing
14293 * a rendition of the basename of the filename in valid UTF-8
14299 * g_filename_display_name:
14300 * @filename: a pathname hopefully in the GLib file name encoding
14302 * Converts a filename into a valid UTF-8 string. The conversion is
14303 * not necessarily reversible, so you should keep the original around
14304 * and use the return value of this function only for display purposes.
14305 * Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL
14306 * even if the filename actually isn't in the GLib file name encoding.
14308 * If GLib cannot make sense of the encoding of @filename, as a last resort it
14309 * replaces unknown characters with U+FFFD, the Unicode replacement character.
14310 * You can search the result for the UTF-8 encoding of this character (which is
14311 * "\357\277\275" in octal notation) to find out if @filename was in an invalid
14314 * If you know the whole pathname of the file you should use
14315 * g_filename_display_basename(), since that allows location-based
14316 * translation of filenames.
14318 * Returns: a newly allocated string containing
14319 * a rendition of the filename in valid UTF-8
14325 * g_filename_from_uri:
14326 * @uri: a uri describing a filename (escaped, encoded in ASCII).
14327 * @hostname: (out) (allow-none): Location to store hostname for the URI, or %NULL.
14328 * If there is no hostname in the URI, %NULL will be
14329 * stored in this location.
14330 * @error: location to store the error occurring, or %NULL to ignore
14331 * errors. Any of the errors in #GConvertError may occur.
14333 * Converts an escaped ASCII-encoded URI to a local filename in the
14334 * encoding used for filenames.
14336 * Returns: (type filename): a newly-allocated string holding
14337 * the resulting filename, or %NULL on an error.
14342 * g_filename_from_utf8:
14343 * @utf8string: a UTF-8 encoded string.
14344 * @len: the length of the string, or -1 if the string is
14346 * @bytes_read: (out) (allow-none): location to store the number of bytes in
14347 * the input string that were successfully converted, or %NULL.
14348 * Even if the conversion was successful, this may be
14349 * less than @len if there were partial characters
14350 * at the end of the input. If the error
14351 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
14352 * stored will the byte offset after the last valid
14354 * @bytes_written: (out): the number of bytes stored in the output buffer (not
14355 * including the terminating nul).
14356 * @error: location to store the error occurring, or %NULL to ignore
14357 * errors. Any of the errors in #GConvertError may occur.
14359 * Converts a string from UTF-8 to the encoding GLib uses for
14360 * filenames. Note that on Windows GLib uses UTF-8 for filenames;
14361 * on other platforms, this function indirectly depends on the
14362 * [current locale][setlocale].
14364 * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
14365 * The converted string, or %NULL on an error.
14370 * g_filename_to_uri:
14371 * @filename: an absolute filename specified in the GLib file name encoding,
14372 * which is the on-disk file name bytes on Unix, and UTF-8 on
14374 * @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none.
14375 * @error: location to store the error occurring, or %NULL to ignore
14376 * errors. Any of the errors in #GConvertError may occur.
14378 * Converts an absolute filename to an escaped ASCII-encoded URI, with the path
14379 * component following Section 3.3. of RFC 2396.
14381 * Returns: a newly-allocated string holding the resulting
14382 * URI, or %NULL on an error.
14387 * g_filename_to_utf8:
14388 * @opsysstring: a string in the encoding for filenames
14389 * @len: the length of the string, or -1 if the string is
14390 * nul-terminated (Note that some encodings may allow nul
14391 * bytes to occur inside strings. In that case, using -1
14392 * for the @len parameter is unsafe)
14393 * @bytes_read: location to store the number of bytes in the
14394 * input string that were successfully converted, or %NULL.
14395 * Even if the conversion was successful, this may be
14396 * less than @len if there were partial characters
14397 * at the end of the input. If the error
14398 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
14399 * stored will the byte offset after the last valid
14401 * @bytes_written: the number of bytes stored in the output buffer (not
14402 * including the terminating nul).
14403 * @error: location to store the error occurring, or %NULL to ignore
14404 * errors. Any of the errors in #GConvertError may occur.
14406 * Converts a string which is in the encoding used by GLib for
14407 * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
14408 * for filenames; on other platforms, this function indirectly depends on
14409 * the [current locale][setlocale].
14411 * Returns: The converted string, or %NULL on an error.
14416 * g_find_program_in_path:
14417 * @program: a program name in the GLib file name encoding
14419 * Locates the first executable named @program in the user's path, in the
14420 * same way that execvp() would locate it. Returns an allocated string
14421 * with the absolute path name, or %NULL if the program is not found in
14422 * the path. If @program is already an absolute path, returns a copy of
14423 * @program if @program exists and is executable, and %NULL otherwise.
14425 * On Windows, if @program does not have a file type suffix, tries
14426 * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
14427 * the `PATHEXT` environment variable.
14429 * On Windows, it looks for the file in the same way as CreateProcess()
14430 * would. This means first in the directory where the executing
14431 * program was loaded from, then in the current directory, then in the
14432 * Windows 32-bit system directory, then in the Windows directory, and
14433 * finally in the directories in the `PATH` environment variable. If
14434 * the program is found, the return value contains the full name
14435 * including the type suffix.
14437 * Returns: a newly-allocated string with the absolute path, or %NULL
14443 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
14444 * @mode: a string describing the mode in which the file should be opened
14446 * A wrapper for the stdio fopen() function. The fopen() function
14447 * opens a file and associates a new stream with it.
14449 * Because file descriptors are specific to the C library on Windows,
14450 * and a file descriptor is part of the FILE struct, the FILE* returned
14451 * by this function makes sense only to functions in the same C library.
14452 * Thus if the GLib-using code uses a different C library than GLib does,
14453 * the FILE* returned by this function cannot be passed to C library
14454 * functions like fprintf() or fread().
14456 * See your C library manual for more details about fopen().
14458 * Returns: A FILE* if the file was successfully opened, or %NULL if
14459 * an error occurred
14466 * @size: a size in bytes
14468 * Formats a size (for example the size of a file) into a human readable
14469 * string. Sizes are rounded to the nearest size prefix (kB, MB, GB)
14470 * and are displayed rounded to the nearest tenth. E.g. the file size
14471 * 3292528 bytes will be converted into the string "3.2 MB".
14473 * The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
14475 * This string should be freed with g_free() when not needed any longer.
14477 * See g_format_size_full() for more options about how the size might be
14480 * Returns: a newly-allocated formatted string containing a human readable
14487 * g_format_size_for_display:
14488 * @size: a size in bytes
14490 * Formats a size (for example the size of a file) into a human
14491 * readable string. Sizes are rounded to the nearest size prefix
14492 * (KB, MB, GB) and are displayed rounded to the nearest tenth.
14493 * E.g. the file size 3292528 bytes will be converted into the
14496 * The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
14498 * This string should be freed with g_free() when not needed any longer.
14500 * Returns: a newly-allocated formatted string containing a human
14501 * readable file size
14503 * Deprecated: 2.30: This function is broken due to its use of SI
14504 * suffixes to denote IEC units. Use g_format_size() instead.
14509 * g_format_size_full:
14510 * @size: a size in bytes
14511 * @flags: #GFormatSizeFlags to modify the output
14515 * This function is similar to g_format_size() but allows for flags
14516 * that modify the output. See #GFormatSizeFlags.
14518 * Returns: a newly-allocated formatted string containing a human
14519 * readable file size
14526 * @file: the stream to write to.
14527 * @format: a standard printf() format string, but notice
14528 * [string precision pitfalls][string-precision]
14529 * @...: the arguments to insert in the output.
14531 * An implementation of the standard fprintf() function which supports
14532 * positional parameters, as specified in the Single Unix Specification.
14534 * Returns: the number of bytes printed.
14541 * @mem: (allow-none): the memory to free
14543 * Frees the memory pointed to by @mem.
14544 * If @mem is %NULL it simply returns.
14550 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
14551 * @mode: a string describing the mode in which the file should be opened
14552 * @stream: (allow-none): an existing stream which will be reused, or %NULL
14554 * A wrapper for the POSIX freopen() function. The freopen() function
14555 * opens a file and associates it with an existing stream.
14557 * See your C library manual for more details about freopen().
14559 * Returns: A FILE* if the file was successfully opened, or %NULL if
14560 * an error occurred.
14566 * g_get_application_name:
14568 * Gets a human-readable name for the application, as set by
14569 * g_set_application_name(). This name should be localized if
14570 * possible, and is intended for display to the user. Contrast with
14571 * g_get_prgname(), which gets a non-localized name. If
14572 * g_set_application_name() has not been called, returns the result of
14573 * g_get_prgname() (which may be %NULL if g_set_prgname() has also not
14576 * Returns: human-readable application name. may return %NULL
14583 * @charset: return location for character set name
14585 * Obtains the character set for the [current locale][setlocale]; you
14586 * might use this character set as an argument to g_convert(), to convert
14587 * from the current locale's encoding to some other encoding. (Frequently
14588 * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.)
14590 * On Windows the character set returned by this function is the
14591 * so-called system default ANSI code-page. That is the character set
14592 * used by the "narrow" versions of C library and Win32 functions that
14593 * handle file names. It might be different from the character set
14594 * used by the C library's current locale.
14596 * The return value is %TRUE if the locale's encoding is UTF-8, in that
14597 * case you can perhaps avoid calling g_convert().
14599 * The string returned in @charset is not allocated, and should not be
14602 * Returns: %TRUE if the returned charset is UTF-8
14609 * Gets the character set for the current locale.
14611 * Returns: a newly allocated string containing the name
14612 * of the character set. This string must be freed with g_free().
14617 * g_get_current_dir:
14619 * Gets the current directory.
14621 * The returned string should be freed when no longer needed.
14622 * The encoding of the returned string is system defined.
14623 * On Windows, it is always UTF-8.
14625 * Since GLib 2.40, this function will return the value of the "PWD"
14626 * environment variable if it is set and it happens to be the same as
14627 * the current directory. This can make a difference in the case that
14628 * the current directory is the target of a symbolic link.
14630 * Returns: the current directory
14635 * g_get_current_time:
14636 * @result: #GTimeVal structure in which to store current time.
14638 * Equivalent to the UNIX gettimeofday() function, but portable.
14640 * You may find g_get_real_time() to be more convenient.
14647 * Gets the list of environment variables for the current process.
14649 * The list is %NULL terminated and each item in the list is of the
14650 * form 'NAME=VALUE'.
14652 * This is equivalent to direct access to the 'environ' global variable,
14655 * The return value is freshly allocated and it should be freed with
14656 * g_strfreev() when it is no longer needed.
14658 * Returns: (array zero-terminated=1) (transfer full): the list of
14659 * environment variables
14665 * g_get_filename_charsets:
14666 * @charsets: return location for the %NULL-terminated list of encoding names
14668 * Determines the preferred character sets used for filenames.
14669 * The first character set from the @charsets is the filename encoding, the
14670 * subsequent character sets are used when trying to generate a displayable
14671 * representation of a filename, see g_filename_display_name().
14673 * On Unix, the character sets are determined by consulting the
14674 * environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
14675 * On Windows, the character set used in the GLib API is always UTF-8
14676 * and said environment variables have no effect.
14678 * `G_FILENAME_ENCODING` may be set to a comma-separated list of
14679 * character set names. The special token "@locale" is taken
14680 * to mean the character set for the [current locale][setlocale].
14681 * If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
14682 * the character set of the current locale is taken as the filename
14683 * encoding. If neither environment variable is set, UTF-8 is taken
14684 * as the filename encoding, but the character set of the current locale
14685 * is also put in the list of encodings.
14687 * The returned @charsets belong to GLib and must not be freed.
14689 * Note that on Unix, regardless of the locale character set or
14690 * `G_FILENAME_ENCODING` value, the actual file names present
14691 * on a system might be in any random encoding or just gibberish.
14693 * Returns: %TRUE if the filename encoding is UTF-8.
14701 * Gets the current user's home directory.
14703 * As with most UNIX tools, this function will return the value of the
14704 * `HOME` environment variable if it is set to an existing absolute path
14705 * name, falling back to the `passwd` file in the case that it is unset.
14707 * If the path given in `HOME` is non-absolute, does not exist, or is
14708 * not a directory, the result is undefined.
14710 * Before version 2.36 this function would ignore the `HOME` environment
14711 * variable, taking the value from the `passwd` database instead. This was
14712 * changed to increase the compatibility of GLib with other programs (and
14713 * the XDG basedir specification) and to increase testability of programs
14714 * based on GLib (by making it easier to run them from test frameworks).
14716 * If your program has a strong requirement for either the new or the
14717 * old behaviour (and if you don't wish to increase your GLib
14718 * dependency to ensure that the new behaviour is in effect) then you
14719 * should either directly check the `HOME` environment variable yourself
14720 * or unset it before calling any functions in GLib.
14722 * Returns: the current user's home directory
14729 * Return a name for the machine.
14731 * The returned name is not necessarily a fully-qualified domain name,
14732 * or even present in DNS or some other name service at all. It need
14733 * not even be unique on your local network or site, but usually it
14734 * is. Callers should not rely on the return value having any specific
14735 * properties like uniqueness for security purposes. Even if the name
14736 * of the machine is changed while an application is running, the
14737 * return value from this function does not change. The returned
14738 * string is owned by GLib and should not be modified or freed. If no
14739 * name can be determined, a default fixed string "localhost" is
14742 * Returns: the host name of the machine.
14748 * g_get_language_names:
14750 * Computes a list of applicable locale names, which can be used to
14751 * e.g. construct locale-dependent filenames or search paths. The returned
14752 * list is sorted from most desirable to least desirable and always contains
14753 * the default locale "C".
14755 * For example, if LANGUAGE=de:en_US, then the returned list is
14756 * "de", "en_US", "en", "C".
14758 * This function consults the environment variables `LANGUAGE`, `LC_ALL`,
14759 * `LC_MESSAGES` and `LANG` to find the list of locales specified by the
14762 * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib
14763 * that must not be modified or freed.
14769 * g_get_locale_variants:
14770 * @locale: a locale identifier
14772 * Returns a list of derived variants of @locale, which can be used to
14773 * e.g. construct locale-dependent filenames or search paths. The returned
14774 * list is sorted from most desirable to least desirable.
14775 * This function handles territory, charset and extra locale modifiers.
14777 * For example, if @locale is "fr_BE", then the returned list
14778 * is "fr_BE", "fr".
14780 * If you need the list of variants for the current locale,
14781 * use g_get_language_names().
14783 * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly
14784 * allocated array of newly allocated strings with the locale variants. Free with
14791 * g_get_monotonic_time:
14793 * Queries the system monotonic time.
14795 * The monotonic clock will always increase and doesn't suffer
14796 * discontinuities when the user (or NTP) changes the system time. It
14797 * may or may not continue to tick during times where the machine is
14800 * We try to use the clock that corresponds as closely as possible to
14801 * the passage of time as measured by system calls such as poll() but it
14802 * may not always be possible to do this.
14804 * Returns: the monotonic time, in microseconds
14810 * g_get_num_processors:
14812 * Determine the approximate number of threads that the system will
14813 * schedule simultaneously for this process. This is intended to be
14814 * used as a parameter to g_thread_pool_new() for CPU bound tasks and
14817 * Returns: Number of schedulable threads, always greater than 0
14825 * Gets the name of the program. This name should not be localized,
14826 * in contrast to g_get_application_name().
14828 * If you are using GDK or GTK+ the program name is set in gdk_init(),
14829 * which is called by gtk_init(). The program name is found by taking
14830 * the last component of @argv[0].
14832 * Returns: the name of the program. The returned string belongs
14833 * to GLib and must not be modified or freed.
14840 * Gets the real name of the user. This usually comes from the user's
14841 * entry in the `passwd` file. The encoding of the returned string is
14842 * system-defined. (On Windows, it is, however, always UTF-8.) If the
14843 * real user name cannot be determined, the string "Unknown" is
14846 * Returns: the user's real name.
14853 * Queries the system wall-clock time.
14855 * This call is functionally equivalent to g_get_current_time() except
14856 * that the return value is often more convenient than dealing with a
14859 * You should only use this call if you are actually interested in the real
14860 * wall-clock time. g_get_monotonic_time() is probably more useful for
14861 * measuring intervals.
14863 * Returns: the number of microseconds since January 1, 1970 UTC.
14869 * g_get_system_config_dirs:
14871 * Returns an ordered list of base directories in which to access
14872 * system-wide configuration information.
14874 * On UNIX platforms this is determined using the mechanisms described
14876 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
14877 * In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
14879 * On Windows is the directory that contains application data for all users.
14880 * A typical path is C:\Documents and Settings\All Users\Application Data.
14881 * This folder is used for application data that is not user specific.
14882 * For example, an application can store a spell-check dictionary, a database
14883 * of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
14884 * This information will not roam and is available to anyone using the computer.
14886 * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
14887 * not be modified or freed.
14893 * g_get_system_data_dirs:
14895 * Returns an ordered list of base directories in which to access
14896 * system-wide application data.
14898 * On UNIX platforms this is determined using the mechanisms described
14900 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
14901 * In this case the list of directories retrieved will be XDG_DATA_DIRS.
14903 * On Windows the first elements in the list are the Application Data
14904 * and Documents folders for All Users. (These can be determined only
14905 * on Windows 2000 or later and are not present in the list on other
14906 * Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
14907 * CSIDL_COMMON_DOCUMENTS.
14909 * Then follows the "share" subfolder in the installation folder for
14910 * the package containing the DLL that calls this function, if it can
14913 * Finally the list contains the "share" subfolder in the installation
14914 * folder for GLib, and in the installation folder for the package the
14915 * application's .exe file belongs to.
14917 * The installation folders above are determined by looking up the
14918 * folder where the module (DLL or EXE) in question is located. If the
14919 * folder's name is "bin", its parent is used, otherwise the folder
14922 * Note that on Windows the returned list can vary depending on where
14923 * this function is called.
14925 * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
14926 * not be modified or freed.
14934 * Gets the directory to use for temporary files.
14936 * On UNIX, this is taken from the `TMPDIR` environment variable.
14937 * If the variable is not set, `P_tmpdir` is
14938 * used, as defined by the system C library. Failing that, a
14939 * hard-coded default of "/tmp" is returned.
14941 * On Windows, the `TEMP` environment variable is used, with the
14942 * root directory of the Windows installation (eg: "C:\") used
14945 * The encoding of the returned string is system-defined. On Windows,
14946 * it is always UTF-8. The return value is never %NULL or the empty
14949 * Returns: the directory to use for temporary files.
14954 * g_get_user_cache_dir:
14956 * Returns a base directory in which to store non-essential, cached
14957 * data specific to particular user.
14959 * On UNIX platforms this is determined using the mechanisms described
14961 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
14962 * In this case the directory retrieved will be XDG_CACHE_HOME.
14964 * On Windows is the directory that serves as a common repository for
14965 * temporary Internet files. A typical path is
14966 * C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
14967 * See documentation for CSIDL_INTERNET_CACHE.
14969 * Returns: a string owned by GLib that must not be modified
14976 * g_get_user_config_dir:
14978 * Returns a base directory in which to store user-specific application
14979 * configuration information such as user preferences and settings.
14981 * On UNIX platforms this is determined using the mechanisms described
14983 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
14984 * In this case the directory retrieved will be `XDG_CONFIG_HOME`.
14986 * On Windows this is the folder to use for local (as opposed to
14987 * roaming) application data. See documentation for
14988 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
14989 * what g_get_user_data_dir() returns.
14991 * Returns: a string owned by GLib that must not be modified
14998 * g_get_user_data_dir:
15000 * Returns a base directory in which to access application data such
15001 * as icons that is customized for a particular user.
15003 * On UNIX platforms this is determined using the mechanisms described
15005 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
15006 * In this case the directory retrieved will be `XDG_DATA_HOME`.
15008 * On Windows this is the folder to use for local (as opposed to
15009 * roaming) application data. See documentation for
15010 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
15011 * what g_get_user_config_dir() returns.
15013 * Returns: a string owned by GLib that must not be modified
15022 * Gets the user name of the current user. The encoding of the returned
15023 * string is system-defined. On UNIX, it might be the preferred file name
15024 * encoding, or something else, and there is no guarantee that it is even
15025 * consistent on a machine. On Windows, it is always UTF-8.
15027 * Returns: the user name of the current user.
15032 * g_get_user_runtime_dir:
15034 * Returns a directory that is unique to the current user on the local
15037 * On UNIX platforms this is determined using the mechanisms described
15039 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
15040 * This is the directory
15041 * specified in the `XDG_RUNTIME_DIR` environment variable.
15042 * In the case that this variable is not set, GLib will issue a warning
15043 * message to stderr and return the value of g_get_user_cache_dir().
15045 * On Windows this is the folder to use for local (as opposed to
15046 * roaming) application data. See documentation for
15047 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
15048 * what g_get_user_config_dir() returns.
15050 * Returns: a string owned by GLib that must not be modified or freed.
15056 * g_get_user_special_dir:
15057 * @directory: the logical id of special directory
15059 * Returns the full path of a special directory using its logical id.
15061 * On UNIX this is done using the XDG special user directories.
15062 * For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
15063 * falls back to `$HOME/Desktop` when XDG special user directories have
15066 * Depending on the platform, the user might be able to change the path
15067 * of the special directory without requiring the session to restart; GLib
15068 * will not reflect any change once the special directories are loaded.
15070 * Returns: the path to the specified special directory, or %NULL
15071 * if the logical id was not found. The returned string is owned by
15072 * GLib and should not be modified or freed.
15079 * @variable: the environment variable to get, in the GLib file name
15082 * Returns the value of an environment variable.
15084 * The name and value are in the GLib file name encoding. On UNIX,
15085 * this means the actual bytes which might or might not be in some
15086 * consistent character set and encoding. On Windows, it is in UTF-8.
15087 * On Windows, in case the environment variable's value contains
15088 * references to other environment variables, they are expanded.
15090 * Returns: the value of the environment variable, or %NULL if
15091 * the environment variable is not found. The returned string
15092 * may be overwritten by the next call to g_getenv(), g_setenv()
15098 * g_hash_table_add:
15099 * @hash_table: a #GHashTable
15100 * @key: a key to insert
15102 * This is a convenience function for using a #GHashTable as a set. It
15103 * is equivalent to calling g_hash_table_replace() with @key as both the
15104 * key and the value.
15106 * When a hash table only ever contains keys that have themselves as the
15107 * corresponding value it is able to be stored more efficiently. See
15108 * the discussion in the section description.
15110 * Returns: %TRUE if the key did not exist yet
15116 * g_hash_table_contains:
15117 * @hash_table: a #GHashTable
15118 * @key: a key to check
15120 * Checks if @key is in @hash_table.
15127 * g_hash_table_destroy:
15128 * @hash_table: a #GHashTable
15130 * Destroys all keys and values in the #GHashTable and decrements its
15131 * reference count by 1. If keys and/or values are dynamically allocated,
15132 * you should either free them first or create the #GHashTable with destroy
15133 * notifiers using g_hash_table_new_full(). In the latter case the destroy
15134 * functions you supplied will be called on all keys and values during the
15135 * destruction phase.
15140 * g_hash_table_find:
15141 * @hash_table: a #GHashTable
15142 * @predicate: function to test the key/value pairs for a certain property
15143 * @user_data: user data to pass to the function
15145 * Calls the given function for key/value pairs in the #GHashTable
15146 * until @predicate returns %TRUE. The function is passed the key
15147 * and value of each pair, and the given @user_data parameter. The
15148 * hash table may not be modified while iterating over it (you can't
15149 * add/remove items).
15151 * Note, that hash tables are really only optimized for forward
15152 * lookups, i.e. g_hash_table_lookup(). So code that frequently issues
15153 * g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of
15154 * once per every entry in a hash table) should probably be reworked
15155 * to use additional or different data structures for reverse lookups
15156 * (keep in mind that an O(n) find/foreach operation issued for all n
15157 * values in a hash table ends up needing O(n*n) operations).
15159 * Returns: (allow-none): The value of the first key/value pair is returned,
15160 * for which @predicate evaluates to %TRUE. If no pair with the
15161 * requested property is found, %NULL is returned.
15167 * g_hash_table_foreach:
15168 * @hash_table: a #GHashTable
15169 * @func: the function to call for each key/value pair
15170 * @user_data: user data to pass to the function
15172 * Calls the given function for each of the key/value pairs in the
15173 * #GHashTable. The function is passed the key and value of each
15174 * pair, and the given @user_data parameter. The hash table may not
15175 * be modified while iterating over it (you can't add/remove
15176 * items). To remove all items matching a predicate, use
15177 * g_hash_table_foreach_remove().
15179 * See g_hash_table_find() for performance caveats for linear
15180 * order searches in contrast to g_hash_table_lookup().
15185 * g_hash_table_foreach_remove:
15186 * @hash_table: a #GHashTable
15187 * @func: the function to call for each key/value pair
15188 * @user_data: user data to pass to the function
15190 * Calls the given function for each key/value pair in the
15191 * #GHashTable. If the function returns %TRUE, then the key/value
15192 * pair is removed from the #GHashTable. If you supplied key or
15193 * value destroy functions when creating the #GHashTable, they are
15194 * used to free the memory allocated for the removed keys and values.
15196 * See #GHashTableIter for an alternative way to loop over the
15197 * key/value pairs in the hash table.
15199 * Returns: the number of key/value pairs removed
15204 * g_hash_table_foreach_steal:
15205 * @hash_table: a #GHashTable
15206 * @func: the function to call for each key/value pair
15207 * @user_data: user data to pass to the function
15209 * Calls the given function for each key/value pair in the
15210 * #GHashTable. If the function returns %TRUE, then the key/value
15211 * pair is removed from the #GHashTable, but no key or value
15212 * destroy functions are called.
15214 * See #GHashTableIter for an alternative way to loop over the
15215 * key/value pairs in the hash table.
15217 * Returns: the number of key/value pairs removed.
15222 * g_hash_table_freeze:
15223 * @hash_table: a #GHashTable
15225 * This function is deprecated and will be removed in the next major
15226 * release of GLib. It does nothing.
15231 * g_hash_table_get_keys:
15232 * @hash_table: a #GHashTable
15234 * Retrieves every key inside @hash_table. The returned data is valid
15235 * until changes to the hash release those keys.
15237 * Returns: a #GList containing all the keys inside the hash
15238 * table. The content of the list is owned by the hash table and
15239 * should not be modified or freed. Use g_list_free() when done
15246 * g_hash_table_get_keys_as_array:
15247 * @hash_table: a #GHashTable
15248 * @length: (out): the length of the returned array
15250 * Retrieves every key inside @hash_table, as an array.
15252 * The returned array is %NULL-terminated but may contain %NULL as a
15253 * key. Use @length to determine the true length if it's possible that
15254 * %NULL was used as the value for a key.
15256 * Note: in the common case of a string-keyed #GHashTable, the return
15257 * value of this function can be conveniently cast to (gchar **).
15259 * You should always free the return result with g_free(). In the
15260 * above-mentioned case of a string-keyed hash table, it may be
15261 * appropriate to use g_strfreev() if you call g_hash_table_steal_all()
15262 * first to transfer ownership of the keys.
15264 * Returns: (array length=length) (transfer container): a
15265 * %NULL-terminated array containing each key from the table.
15271 * g_hash_table_get_values:
15272 * @hash_table: a #GHashTable
15274 * Retrieves every value inside @hash_table. The returned data
15275 * is valid until @hash_table is modified.
15277 * Returns: a #GList containing all the values inside the hash
15278 * table. The content of the list is owned by the hash table and
15279 * should not be modified or freed. Use g_list_free() when done
15286 * g_hash_table_insert:
15287 * @hash_table: a #GHashTable
15288 * @key: a key to insert
15289 * @value: the value to associate with the key
15291 * Inserts a new key and value into a #GHashTable.
15293 * If the key already exists in the #GHashTable its current
15294 * value is replaced with the new value. If you supplied a
15295 * @value_destroy_func when creating the #GHashTable, the old
15296 * value is freed using that function. If you supplied a
15297 * @key_destroy_func when creating the #GHashTable, the passed
15298 * key is freed using that function.
15300 * Returns: %TRUE if the key did not exist yet
15305 * g_hash_table_iter_get_hash_table:
15306 * @iter: an initialized #GHashTableIter
15308 * Returns the #GHashTable associated with @iter.
15310 * Returns: the #GHashTable associated with @iter.
15316 * g_hash_table_iter_init:
15317 * @iter: an uninitialized #GHashTableIter
15318 * @hash_table: a #GHashTable
15320 * Initializes a key/value pair iterator and associates it with
15321 * @hash_table. Modifying the hash table after calling this function
15322 * invalidates the returned iterator.
15323 * |[<!-- language="C" -->
15324 * GHashTableIter iter;
15325 * gpointer key, value;
15327 * g_hash_table_iter_init (&iter, hash_table);
15328 * while (g_hash_table_iter_next (&iter, &key, &value))
15330 * // do something with key and value
15339 * g_hash_table_iter_next:
15340 * @iter: an initialized #GHashTableIter
15341 * @key: (allow-none): a location to store the key, or %NULL
15342 * @value: (allow-none): a location to store the value, or %NULL
15344 * Advances @iter and retrieves the key and/or value that are now
15345 * pointed to as a result of this advancement. If %FALSE is returned,
15346 * @key and @value are not set, and the iterator becomes invalid.
15348 * Returns: %FALSE if the end of the #GHashTable has been reached.
15354 * g_hash_table_iter_remove:
15355 * @iter: an initialized #GHashTableIter
15357 * Removes the key/value pair currently pointed to by the iterator
15358 * from its associated #GHashTable. Can only be called after
15359 * g_hash_table_iter_next() returned %TRUE, and cannot be called
15360 * more than once for the same key/value pair.
15362 * If the #GHashTable was created using g_hash_table_new_full(),
15363 * the key and value are freed using the supplied destroy functions,
15364 * otherwise you have to make sure that any dynamically allocated
15365 * values are freed yourself.
15367 * It is safe to continue iterating the #GHashTable afterward:
15369 * while (g_hash_table_iter_next (&iter, &key, &value))
15372 * g_hash_table_iter_remove (&iter);
15381 * g_hash_table_iter_replace:
15382 * @iter: an initialized #GHashTableIter
15383 * @value: the value to replace with
15385 * Replaces the value currently pointed to by the iterator
15386 * from its associated #GHashTable. Can only be called after
15387 * g_hash_table_iter_next() returned %TRUE.
15389 * If you supplied a @value_destroy_func when creating the
15390 * #GHashTable, the old value is freed using that function.
15397 * g_hash_table_iter_steal:
15398 * @iter: an initialized #GHashTableIter
15400 * Removes the key/value pair currently pointed to by the
15401 * iterator from its associated #GHashTable, without calling
15402 * the key and value destroy functions. Can only be called
15403 * after g_hash_table_iter_next() returned %TRUE, and cannot
15404 * be called more than once for the same key/value pair.
15411 * g_hash_table_lookup:
15412 * @hash_table: a #GHashTable
15413 * @key: the key to look up
15415 * Looks up a key in a #GHashTable. Note that this function cannot
15416 * distinguish between a key that is not present and one which is present
15417 * and has the value %NULL. If you need this distinction, use
15418 * g_hash_table_lookup_extended().
15420 * Returns: (allow-none): the associated value, or %NULL if the key is not found
15425 * g_hash_table_lookup_extended:
15426 * @hash_table: a #GHashTable
15427 * @lookup_key: the key to look up
15428 * @orig_key: (allow-none): return location for the original key, or %NULL
15429 * @value: (allow-none): return location for the value associated with the key, or %NULL
15431 * Looks up a key in the #GHashTable, returning the original key and the
15432 * associated value and a #gboolean which is %TRUE if the key was found. This
15433 * is useful if you need to free the memory allocated for the original key,
15434 * for example before calling g_hash_table_remove().
15436 * You can actually pass %NULL for @lookup_key to test
15437 * whether the %NULL key exists, provided the hash and equal functions
15438 * of @hash_table are %NULL-safe.
15440 * Returns: %TRUE if the key was found in the #GHashTable
15445 * g_hash_table_new:
15446 * @hash_func: a function to create a hash value from a key
15447 * @key_equal_func: a function to check two keys for equality
15449 * Creates a new #GHashTable with a reference count of 1.
15451 * Hash values returned by @hash_func are used to determine where keys
15452 * are stored within the #GHashTable data structure. The g_direct_hash(),
15453 * g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash()
15454 * functions are provided for some common types of keys.
15455 * If @hash_func is %NULL, g_direct_hash() is used.
15457 * @key_equal_func is used when looking up keys in the #GHashTable.
15458 * The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal()
15459 * and g_str_equal() functions are provided for the most common types
15460 * of keys. If @key_equal_func is %NULL, keys are compared directly in
15461 * a similar fashion to g_direct_equal(), but without the overhead of
15464 * Returns: a new #GHashTable
15469 * g_hash_table_new_full:
15470 * @hash_func: a function to create a hash value from a key
15471 * @key_equal_func: a function to check two keys for equality
15472 * @key_destroy_func: (allow-none): a function to free the memory allocated for the key
15473 * used when removing the entry from the #GHashTable, or %NULL
15474 * if you don't want to supply such a function.
15475 * @value_destroy_func: (allow-none): a function to free the memory allocated for the
15476 * value used when removing the entry from the #GHashTable, or %NULL
15477 * if you don't want to supply such a function.
15479 * Creates a new #GHashTable like g_hash_table_new() with a reference
15480 * count of 1 and allows to specify functions to free the memory
15481 * allocated for the key and value that get called when removing the
15482 * entry from the #GHashTable.
15484 * Returns: a new #GHashTable
15489 * g_hash_table_ref:
15490 * @hash_table: a valid #GHashTable
15492 * Atomically increments the reference count of @hash_table by one.
15493 * This function is MT-safe and may be called from any thread.
15495 * Returns: the passed in #GHashTable
15501 * g_hash_table_remove:
15502 * @hash_table: a #GHashTable
15503 * @key: the key to remove
15505 * Removes a key and its associated value from a #GHashTable.
15507 * If the #GHashTable was created using g_hash_table_new_full(), the
15508 * key and value are freed using the supplied destroy functions, otherwise
15509 * you have to make sure that any dynamically allocated values are freed
15512 * Returns: %TRUE if the key was found and removed from the #GHashTable
15517 * g_hash_table_remove_all:
15518 * @hash_table: a #GHashTable
15520 * Removes all keys and their associated values from a #GHashTable.
15522 * If the #GHashTable was created using g_hash_table_new_full(),
15523 * the keys and values are freed using the supplied destroy functions,
15524 * otherwise you have to make sure that any dynamically allocated
15525 * values are freed yourself.
15532 * g_hash_table_replace:
15533 * @hash_table: a #GHashTable
15534 * @key: a key to insert
15535 * @value: the value to associate with the key
15537 * Inserts a new key and value into a #GHashTable similar to
15538 * g_hash_table_insert(). The difference is that if the key
15539 * already exists in the #GHashTable, it gets replaced by the
15540 * new key. If you supplied a @value_destroy_func when creating
15541 * the #GHashTable, the old value is freed using that function.
15542 * If you supplied a @key_destroy_func when creating the
15543 * #GHashTable, the old key is freed using that function.
15545 * Returns: %TRUE of the key did not exist yet
15550 * g_hash_table_size:
15551 * @hash_table: a #GHashTable
15553 * Returns the number of elements contained in the #GHashTable.
15555 * Returns: the number of key/value pairs in the #GHashTable.
15560 * g_hash_table_steal:
15561 * @hash_table: a #GHashTable
15562 * @key: the key to remove
15564 * Removes a key and its associated value from a #GHashTable without
15565 * calling the key and value destroy functions.
15567 * Returns: %TRUE if the key was found and removed from the #GHashTable
15572 * g_hash_table_steal_all:
15573 * @hash_table: a #GHashTable
15575 * Removes all keys and their associated values from a #GHashTable
15576 * without calling the key and value destroy functions.
15583 * g_hash_table_thaw:
15584 * @hash_table: a #GHashTable
15586 * This function is deprecated and will be removed in the next major
15587 * release of GLib. It does nothing.
15592 * g_hash_table_unref:
15593 * @hash_table: a valid #GHashTable
15595 * Atomically decrements the reference count of @hash_table by one.
15596 * If the reference count drops to 0, all keys and values will be
15597 * destroyed, and all memory allocated by the hash table is released.
15598 * This function is MT-safe and may be called from any thread.
15606 * @hmac: the #GHmac to copy
15608 * Copies a #GHmac. If @hmac has been closed, by calling
15609 * g_hmac_get_string() or g_hmac_get_digest(), the copied
15610 * HMAC will be closed as well.
15612 * Returns: the copy of the passed #GHmac. Use g_hmac_unref()
15613 * when finished using it.
15619 * g_hmac_get_digest:
15621 * @buffer: output buffer
15622 * @digest_len: an inout parameter. The caller initializes it to the
15623 * size of @buffer. After the call it contains the length of the digest
15625 * Gets the digest from @checksum as a raw binary array and places it
15626 * into @buffer. The size of the digest depends on the type of checksum.
15628 * Once this function has been called, the #GHmac is closed and can
15629 * no longer be updated with g_checksum_update().
15636 * g_hmac_get_string:
15639 * Gets the HMAC as an hexadecimal string.
15641 * Once this function has been called the #GHmac can no longer be
15642 * updated with g_hmac_update().
15644 * The hexadecimal characters will be lower case.
15646 * Returns: the hexadecimal representation of the HMAC. The
15647 * returned string is owned by the HMAC and should not be modified
15655 * @digest_type: the desired type of digest
15656 * @key: (array length=key_len): the key for the HMAC
15657 * @key_len: the length of the keys
15659 * Creates a new #GHmac, using the digest algorithm @digest_type.
15660 * If the @digest_type is not known, %NULL is returned.
15661 * A #GHmac can be used to compute the HMAC of a key and an
15662 * arbitrary binary blob, using different hashing algorithms.
15664 * A #GHmac works by feeding a binary blob through g_hmac_update()
15665 * until the data is complete; the digest can then be extracted
15666 * using g_hmac_get_string(), which will return the checksum as a
15667 * hexadecimal string; or g_hmac_get_digest(), which will return a
15668 * array of raw bytes. Once either g_hmac_get_string() or
15669 * g_hmac_get_digest() have been called on a #GHmac, the HMAC
15670 * will be closed and it won't be possible to call g_hmac_update()
15673 * Returns: the newly created #GHmac, or %NULL.
15674 * Use g_hmac_unref() to free the memory allocated by it.
15681 * @hmac: a valid #GHmac
15683 * Atomically increments the reference count of @hmac by one.
15685 * This function is MT-safe and may be called from any thread.
15687 * Returns: the passed in #GHmac.
15696 * Atomically decrements the reference count of @hmac by one.
15698 * If the reference count drops to 0, all keys and values will be
15699 * destroyed, and all memory allocated by the hash table is released.
15700 * This function is MT-safe and may be called from any thread.
15701 * Frees the memory allocated for @hmac.
15710 * @data: (array length=length): buffer used to compute the checksum
15711 * @length: size of the buffer, or -1 if it is a nul-terminated string
15713 * Feeds @data into an existing #GHmac.
15715 * The HMAC must still be open, that is g_hmac_get_string() or
15716 * g_hmac_get_digest() must not have been called on @hmac.
15724 * @hook_list: a #GHookList
15726 * Allocates space for a #GHook and initializes it.
15728 * Returns: a new #GHook
15734 * @hook_list: a #GHookList
15735 * @hook: the #GHook to add to the end of @hook_list
15737 * Appends a #GHook onto the end of a #GHookList.
15742 * g_hook_compare_ids:
15743 * @new_hook: a #GHook
15744 * @sibling: a #GHook to compare with @new_hook
15746 * Compares the ids of two #GHook elements, returning a negative value
15747 * if the second id is greater than the first.
15749 * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook
15755 * @hook_list: a #GHookList
15756 * @hook_id: a hook ID
15758 * Destroys a #GHook, given its ID.
15760 * Returns: %TRUE if the #GHook was found in the #GHookList and destroyed
15765 * g_hook_destroy_link:
15766 * @hook_list: a #GHookList
15767 * @hook: the #GHook to remove
15769 * Removes one #GHook from a #GHookList, marking it
15770 * inactive and calling g_hook_unref() on it.
15776 * @hook_list: a #GHookList
15777 * @need_valids: %TRUE if #GHook elements which have been destroyed
15778 * should be skipped
15779 * @func: the function to call for each #GHook, which should return
15780 * %TRUE when the #GHook has been found
15781 * @data: the data to pass to @func
15783 * Finds a #GHook in a #GHookList using the given function to
15784 * test for a match.
15786 * Returns: the found #GHook or %NULL if no matching #GHook is found
15791 * g_hook_find_data:
15792 * @hook_list: a #GHookList
15793 * @need_valids: %TRUE if #GHook elements which have been destroyed
15794 * should be skipped
15795 * @data: the data to find
15797 * Finds a #GHook in a #GHookList with the given data.
15799 * Returns: the #GHook with the given @data or %NULL if no matching
15805 * g_hook_find_func:
15806 * @hook_list: a #GHookList
15807 * @need_valids: %TRUE if #GHook elements which have been destroyed
15808 * should be skipped
15809 * @func: the function to find
15811 * Finds a #GHook in a #GHookList with the given function.
15813 * Returns: the #GHook with the given @func or %NULL if no matching
15819 * g_hook_find_func_data:
15820 * @hook_list: a #GHookList
15821 * @need_valids: %TRUE if #GHook elements which have been destroyed
15822 * should be skipped
15823 * @func: the function to find
15824 * @data: the data to find
15826 * Finds a #GHook in a #GHookList with the given function and data.
15828 * Returns: the #GHook with the given @func and @data or %NULL if
15829 * no matching #GHook is found
15834 * g_hook_first_valid:
15835 * @hook_list: a #GHookList
15836 * @may_be_in_call: %TRUE if hooks which are currently running
15837 * (e.g. in another thread) are considered valid. If set to %FALSE,
15838 * these are skipped
15840 * Returns the first #GHook in a #GHookList which has not been destroyed.
15841 * The reference count for the #GHook is incremented, so you must call
15842 * g_hook_unref() to restore it when no longer needed. (Or call
15843 * g_hook_next_valid() if you are stepping through the #GHookList.)
15845 * Returns: the first valid #GHook, or %NULL if none are valid
15851 * @hook_list: a #GHookList
15852 * @hook: the #GHook to free
15854 * Calls the #GHookList @finalize_hook function if it exists,
15855 * and frees the memory allocated for the #GHook.
15861 * @hook_list: a #GHookList
15862 * @hook_id: a hook id
15864 * Returns the #GHook with the given id, or %NULL if it is not found.
15866 * Returns: the #GHook with the given id, or %NULL if it is not found
15871 * g_hook_insert_before:
15872 * @hook_list: a #GHookList
15873 * @sibling: the #GHook to insert the new #GHook before
15874 * @hook: the #GHook to insert
15876 * Inserts a #GHook into a #GHookList, before a given #GHook.
15881 * g_hook_insert_sorted:
15882 * @hook_list: a #GHookList
15883 * @hook: the #GHook to insert
15884 * @func: the comparison function used to sort the #GHook elements
15886 * Inserts a #GHook into a #GHookList, sorted by the given function.
15891 * g_hook_list_clear:
15892 * @hook_list: a #GHookList
15894 * Removes all the #GHook elements from a #GHookList.
15899 * g_hook_list_init:
15900 * @hook_list: a #GHookList
15901 * @hook_size: the size of each element in the #GHookList,
15902 * typically `sizeof (GHook)`.
15904 * Initializes a #GHookList.
15905 * This must be called before the #GHookList is used.
15910 * g_hook_list_invoke:
15911 * @hook_list: a #GHookList
15912 * @may_recurse: %TRUE if functions which are already running
15913 * (e.g. in another thread) can be called. If set to %FALSE,
15914 * these are skipped
15916 * Calls all of the #GHook functions in a #GHookList.
15921 * g_hook_list_invoke_check:
15922 * @hook_list: a #GHookList
15923 * @may_recurse: %TRUE if functions which are already running
15924 * (e.g. in another thread) can be called. If set to %FALSE,
15925 * these are skipped
15927 * Calls all of the #GHook functions in a #GHookList.
15928 * Any function which returns %FALSE is removed from the #GHookList.
15933 * g_hook_list_marshal:
15934 * @hook_list: a #GHookList
15935 * @may_recurse: %TRUE if hooks which are currently running
15936 * (e.g. in another thread) are considered valid. If set to %FALSE,
15937 * these are skipped
15938 * @marshaller: the function to call for each #GHook
15939 * @marshal_data: data to pass to @marshaller
15941 * Calls a function on each valid #GHook.
15946 * g_hook_list_marshal_check:
15947 * @hook_list: a #GHookList
15948 * @may_recurse: %TRUE if hooks which are currently running
15949 * (e.g. in another thread) are considered valid. If set to %FALSE,
15950 * these are skipped
15951 * @marshaller: the function to call for each #GHook
15952 * @marshal_data: data to pass to @marshaller
15954 * Calls a function on each valid #GHook and destroys it if the
15955 * function returns %FALSE.
15960 * g_hook_next_valid:
15961 * @hook_list: a #GHookList
15962 * @hook: the current #GHook
15963 * @may_be_in_call: %TRUE if hooks which are currently running
15964 * (e.g. in another thread) are considered valid. If set to %FALSE,
15965 * these are skipped
15967 * Returns the next #GHook in a #GHookList which has not been destroyed.
15968 * The reference count for the #GHook is incremented, so you must call
15969 * g_hook_unref() to restore it when no longer needed. (Or continue to call
15970 * g_hook_next_valid() until %NULL is returned.)
15972 * Returns: the next valid #GHook, or %NULL if none are valid
15978 * @hook_list: a #GHookList
15979 * @hook: the #GHook to add to the start of @hook_list
15981 * Prepends a #GHook on the start of a #GHookList.
15987 * @hook_list: a #GHookList
15988 * @hook: the #GHook to increment the reference count of
15990 * Increments the reference count for a #GHook.
15992 * Returns: the @hook that was passed in (since 2.6)
15998 * @hook_list: a #GHookList
15999 * @hook: the #GHook to unref
16001 * Decrements the reference count of a #GHook.
16002 * If the reference count falls to 0, the #GHook is removed
16003 * from the #GHookList and g_hook_free() is called to free it.
16008 * g_hostname_is_ascii_encoded:
16009 * @hostname: a hostname
16011 * Tests if @hostname contains segments with an ASCII-compatible
16012 * encoding of an Internationalized Domain Name. If this returns
16013 * %TRUE, you should decode the hostname with g_hostname_to_unicode()
16014 * before displaying it to the user.
16016 * Note that a hostname might contain a mix of encoded and unencoded
16017 * segments, and so it is possible for g_hostname_is_non_ascii() and
16018 * g_hostname_is_ascii_encoded() to both return %TRUE for a name.
16020 * Returns: %TRUE if @hostname contains any ASCII-encoded
16027 * g_hostname_is_ip_address:
16028 * @hostname: a hostname (or IP address in string form)
16030 * Tests if @hostname is the string form of an IPv4 or IPv6 address.
16031 * (Eg, "192.168.0.1".)
16033 * Returns: %TRUE if @hostname is an IP address
16039 * g_hostname_is_non_ascii:
16040 * @hostname: a hostname
16042 * Tests if @hostname contains Unicode characters. If this returns
16043 * %TRUE, you need to encode the hostname with g_hostname_to_ascii()
16044 * before using it in non-IDN-aware contexts.
16046 * Note that a hostname might contain a mix of encoded and unencoded
16047 * segments, and so it is possible for g_hostname_is_non_ascii() and
16048 * g_hostname_is_ascii_encoded() to both return %TRUE for a name.
16050 * Returns: %TRUE if @hostname contains any non-ASCII characters
16056 * g_hostname_to_ascii:
16057 * @hostname: a valid UTF-8 or ASCII hostname
16059 * Converts @hostname to its canonical ASCII form; an ASCII-only
16060 * string containing no uppercase letters and not ending with a
16063 * Returns: an ASCII hostname, which must be freed, or %NULL if
16064 * @hostname is in some way invalid.
16070 * g_hostname_to_unicode:
16071 * @hostname: a valid UTF-8 or ASCII hostname
16073 * Converts @hostname to its canonical presentation form; a UTF-8
16074 * string in Unicode normalization form C, containing no uppercase
16075 * letters, no forbidden characters, and no ASCII-encoded segments,
16076 * and not ending with a trailing dot.
16078 * Of course if @hostname is not an internationalized hostname, then
16079 * the canonical presentation form will be entirely ASCII.
16081 * Returns: a UTF-8 hostname, which must be freed, or %NULL if
16082 * @hostname is in some way invalid.
16089 * @val: a 32-bit integer value in host byte order
16091 * Converts a 32-bit integer value from host to network byte order.
16093 * Returns: @val converted to network byte order
16099 * @val: a 16-bit integer value in host byte order
16101 * Converts a 16-bit integer value from host to network byte order.
16103 * Returns: @val converted to network byte order
16109 * @converter: conversion descriptor from g_iconv_open()
16110 * @inbuf: bytes to convert
16111 * @inbytes_left: inout parameter, bytes remaining to convert in @inbuf
16112 * @outbuf: converted output bytes
16113 * @outbytes_left: inout parameter, bytes available to fill in @outbuf
16115 * Same as the standard UNIX routine iconv(), but
16116 * may be implemented via libiconv on UNIX flavors that lack
16117 * a native implementation.
16119 * GLib provides g_convert() and g_locale_to_utf8() which are likely
16120 * more convenient than the raw iconv wrappers.
16122 * Returns: count of non-reversible conversions, or -1 on error
16128 * @converter: a conversion descriptor from g_iconv_open()
16130 * Same as the standard UNIX routine iconv_close(), but
16131 * may be implemented via libiconv on UNIX flavors that lack
16132 * a native implementation. Should be called to clean up
16133 * the conversion descriptor from g_iconv_open() when
16134 * you are done converting things.
16136 * GLib provides g_convert() and g_locale_to_utf8() which are likely
16137 * more convenient than the raw iconv wrappers.
16139 * Returns: -1 on error, 0 on success
16145 * @to_codeset: destination codeset
16146 * @from_codeset: source codeset
16148 * Same as the standard UNIX routine iconv_open(), but
16149 * may be implemented via libiconv on UNIX flavors that lack
16150 * a native implementation.
16152 * GLib provides g_convert() and g_locale_to_utf8() which are likely
16153 * more convenient than the raw iconv wrappers.
16155 * Returns: a "conversion descriptor", or (GIConv)-1 if
16156 * opening the converter failed.
16162 * @function: function to call
16163 * @data: data to pass to @function.
16165 * Adds a function to be called whenever there are no higher priority
16166 * events pending to the default main loop. The function is given the
16167 * default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function
16168 * returns %FALSE it is automatically removed from the list of event
16169 * sources and will not be called again.
16171 * This internally creates a main loop source using g_idle_source_new()
16172 * and attaches it to the main loop context using g_source_attach().
16173 * You can do these steps manually if you need greater control.
16175 * Returns: the ID (greater than 0) of the event source.
16180 * g_idle_add_full: (rename-to g_idle_add)
16181 * @priority: the priority of the idle source. Typically this will be in the
16182 * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
16183 * @function: function to call
16184 * @data: data to pass to @function
16185 * @notify: (allow-none): function to call when the idle is removed, or %NULL
16187 * Adds a function to be called whenever there are no higher priority
16188 * events pending. If the function returns %FALSE it is automatically
16189 * removed from the list of event sources and will not be called again.
16191 * This internally creates a main loop source using g_idle_source_new()
16192 * and attaches it to the main loop context using g_source_attach().
16193 * You can do these steps manually if you need greater control.
16195 * Returns: the ID (greater than 0) of the event source.
16200 * g_idle_remove_by_data:
16201 * @data: the data for the idle source's callback.
16203 * Removes the idle function with the given data.
16205 * Returns: %TRUE if an idle source was found and removed.
16210 * g_idle_source_new:
16212 * Creates a new idle source.
16214 * The source will not initially be associated with any #GMainContext
16215 * and must be added to one with g_source_attach() before it will be
16216 * executed. Note that the default priority for idle sources is
16217 * %G_PRIORITY_DEFAULT_IDLE, as compared to other sources which
16218 * have a default priority of %G_PRIORITY_DEFAULT.
16220 * Returns: the newly-created idle source
16226 * @...: format string, followed by parameters to insert
16227 * into the format string (as with printf())
16229 * A convenience function/macro to log an informational message. Seldom used.
16231 * If g_log_default_handler() is used as the log handler function, a new-line
16232 * character will automatically be appended to @..., and need not be entered
16235 * Such messages are suppressed by the g_log_default_handler() unless
16236 * the G_MESSAGES_DEBUG environment variable is set appropriately.
16244 * @v1: a pointer to a #gint64 key
16245 * @v2: a pointer to a #gint64 key to compare with @v1
16247 * Compares the two #gint64 values being pointed to and returns
16248 * %TRUE if they are equal.
16249 * It can be passed to g_hash_table_new() as the @key_equal_func
16250 * parameter, when using non-%NULL pointers to 64-bit integers as keys in a
16253 * Returns: %TRUE if the two keys match.
16260 * @v: a pointer to a #gint64 key
16262 * Converts a pointer to a #gint64 to a hash value.
16264 * It can be passed to g_hash_table_new() as the @hash_func parameter,
16265 * when using non-%NULL pointers to 64-bit integer values as keys in a
16268 * Returns: a hash value corresponding to the key.
16275 * @v1: a pointer to a #gint key
16276 * @v2: a pointer to a #gint key to compare with @v1
16278 * Compares the two #gint values being pointed to and returns
16279 * %TRUE if they are equal.
16280 * It can be passed to g_hash_table_new() as the @key_equal_func
16281 * parameter, when using non-%NULL pointers to integers as keys in a
16284 * Note that this function acts on pointers to #gint, not on #gint
16285 * directly: if your hash table's keys are of the form
16286 * `GINT_TO_POINTER (n)`, use g_direct_equal() instead.
16288 * Returns: %TRUE if the two keys match.
16294 * @v: a pointer to a #gint key
16296 * Converts a pointer to a #gint to a hash value.
16297 * It can be passed to g_hash_table_new() as the @hash_func parameter,
16298 * when using non-%NULL pointers to integer values as keys in a #GHashTable.
16300 * Note that this function acts on pointers to #gint, not on #gint
16301 * directly: if your hash table's keys are of the form
16302 * `GINT_TO_POINTER (n)`, use g_direct_hash() instead.
16304 * Returns: a hash value corresponding to the key.
16309 * g_intern_static_string:
16310 * @string: (allow-none): a static string
16312 * Returns a canonical representation for @string. Interned strings
16313 * can be compared for equality by comparing the pointers, instead of
16314 * using strcmp(). g_intern_static_string() does not copy the string,
16315 * therefore @string must not be freed or modified.
16317 * Returns: a canonical representation for the string
16324 * @string: (allow-none): a string
16326 * Returns a canonical representation for @string. Interned strings
16327 * can be compared for equality by comparing the pointers, instead of
16330 * Returns: a canonical representation for the string
16337 * @channel: a #GIOChannel
16338 * @condition: the condition to watch for
16339 * @func: the function to call when the condition is satisfied
16340 * @user_data: user data to pass to @func
16342 * Adds the #GIOChannel into the default main loop context
16343 * with the default priority.
16345 * Returns: the event source id
16350 * g_io_add_watch_full: (rename-to g_io_add_watch)
16351 * @channel: a #GIOChannel
16352 * @priority: the priority of the #GIOChannel source
16353 * @condition: the condition to watch for
16354 * @func: the function to call when the condition is satisfied
16355 * @user_data: user data to pass to @func
16356 * @notify: the function to call when the source is removed
16358 * Adds the #GIOChannel into the default main loop context
16359 * with the given priority.
16361 * This internally creates a main loop source using g_io_create_watch()
16362 * and attaches it to the main loop context with g_source_attach().
16363 * You can do these steps manually if you need greater control.
16365 * Returns: the event source id
16370 * g_io_channel_close:
16371 * @channel: A #GIOChannel
16373 * Close an IO channel. Any pending data to be written will be
16374 * flushed, ignoring errors. The channel will not be freed until the
16375 * last reference is dropped using g_io_channel_unref().
16377 * Deprecated: 2.2: Use g_io_channel_shutdown() instead.
16382 * g_io_channel_error_from_errno:
16383 * @en: an `errno` error number, e.g. `EINVAL`
16385 * Converts an `errno` error number to a #GIOChannelError.
16387 * Returns: a #GIOChannelError error number, e.g.
16388 * %G_IO_CHANNEL_ERROR_INVAL.
16393 * g_io_channel_error_quark:
16395 * Returns: the quark used as %G_IO_CHANNEL_ERROR
16400 * g_io_channel_flush:
16401 * @channel: a #GIOChannel
16402 * @error: location to store an error of type #GIOChannelError
16404 * Flushes the write buffer for the GIOChannel.
16406 * Returns: the status of the operation: One of
16407 * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or
16408 * #G_IO_STATUS_ERROR.
16413 * g_io_channel_get_buffer_condition:
16414 * @channel: A #GIOChannel
16416 * This function returns a #GIOCondition depending on whether there
16417 * is data to be read/space to write data in the internal buffers in
16418 * the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set.
16420 * Returns: A #GIOCondition
16425 * g_io_channel_get_buffer_size:
16426 * @channel: a #GIOChannel
16428 * Gets the buffer size.
16430 * Returns: the size of the buffer.
16435 * g_io_channel_get_buffered:
16436 * @channel: a #GIOChannel
16438 * Returns whether @channel is buffered.
16440 * Returns: %TRUE if the @channel is buffered.
16445 * g_io_channel_get_close_on_unref:
16446 * @channel: a #GIOChannel.
16448 * Returns whether the file/socket/whatever associated with @channel
16449 * will be closed when @channel receives its final unref and is
16450 * destroyed. The default value of this is %TRUE for channels created
16451 * by g_io_channel_new_file (), and %FALSE for all other channels.
16453 * Returns: Whether the channel will be closed on the final unref of
16454 * the GIOChannel data structure.
16459 * g_io_channel_get_encoding:
16460 * @channel: a #GIOChannel
16462 * Gets the encoding for the input/output of the channel.
16463 * The internal encoding is always UTF-8. The encoding %NULL
16464 * makes the channel safe for binary data.
16466 * Returns: A string containing the encoding, this string is
16467 * owned by GLib and must not be freed.
16472 * g_io_channel_get_flags:
16473 * @channel: a #GIOChannel
16475 * Gets the current flags for a #GIOChannel, including read-only
16476 * flags such as %G_IO_FLAG_IS_READABLE.
16478 * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE
16479 * are cached for internal use by the channel when it is created.
16480 * If they should change at some later point (e.g. partial shutdown
16481 * of a socket with the UNIX shutdown() function), the user
16482 * should immediately call g_io_channel_get_flags() to update
16483 * the internal values of these flags.
16485 * Returns: the flags which are set on the channel
16490 * g_io_channel_get_line_term:
16491 * @channel: a #GIOChannel
16492 * @length: a location to return the length of the line terminator
16494 * This returns the string that #GIOChannel uses to determine
16495 * where in the file a line break occurs. A value of %NULL
16496 * indicates autodetection.
16498 * Returns: The line termination string. This value
16499 * is owned by GLib and must not be freed.
16504 * g_io_channel_init:
16505 * @channel: a #GIOChannel
16507 * Initializes a #GIOChannel struct.
16509 * This is called by each of the above functions when creating a
16510 * #GIOChannel, and so is not often needed by the application
16511 * programmer (unless you are creating a new type of #GIOChannel).
16516 * g_io_channel_new_file:
16517 * @filename: A string containing the name of a file
16518 * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
16519 * the same meaning as in fopen()
16520 * @error: A location to return an error of type %G_FILE_ERROR
16522 * Open a file @filename as a #GIOChannel using mode @mode. This
16523 * channel will be closed when the last reference to it is dropped,
16524 * so there is no need to call g_io_channel_close() (though doing
16525 * so will not cause problems, as long as no attempt is made to
16526 * access the channel after it is closed).
16528 * Returns: A #GIOChannel on success, %NULL on failure.
16533 * g_io_channel_read:
16534 * @channel: a #GIOChannel
16535 * @buf: a buffer to read the data into (which should be at least
16536 * count bytes long)
16537 * @count: the number of bytes to read from the #GIOChannel
16538 * @bytes_read: returns the number of bytes actually read
16540 * Reads data from a #GIOChannel.
16542 * Returns: %G_IO_ERROR_NONE if the operation was successful.
16543 * Deprecated: 2.2: Use g_io_channel_read_chars() instead.
16548 * g_io_channel_read_chars:
16549 * @channel: a #GIOChannel
16550 * @buf: (out caller-allocates) (array length=count) (element-type guint8):
16551 * a buffer to read data into
16552 * @count: (in): the size of the buffer. Note that the buffer may not be
16553 * complelely filled even if there is data in the buffer if the
16554 * remaining data is not a complete character.
16555 * @bytes_read: (allow-none) (out): The number of bytes read. This may be
16556 * zero even on success if count < 6 and the channel's encoding
16557 * is non-%NULL. This indicates that the next UTF-8 character is
16558 * too wide for the buffer.
16559 * @error: a location to return an error of type #GConvertError
16560 * or #GIOChannelError.
16562 * Replacement for g_io_channel_read() with the new API.
16564 * Returns: the status of the operation.
16569 * g_io_channel_read_line:
16570 * @channel: a #GIOChannel
16571 * @str_return: (out): The line read from the #GIOChannel, including the
16572 * line terminator. This data should be freed with g_free()
16573 * when no longer needed. This is a nul-terminated string.
16574 * If a @length of zero is returned, this will be %NULL instead.
16575 * @length: (allow-none) (out): location to store length of the read data, or %NULL
16576 * @terminator_pos: (allow-none) (out): location to store position of line terminator, or %NULL
16577 * @error: A location to return an error of type #GConvertError
16578 * or #GIOChannelError
16580 * Reads a line, including the terminating character(s),
16581 * from a #GIOChannel into a newly-allocated string.
16582 * @str_return will contain allocated memory if the return
16583 * is %G_IO_STATUS_NORMAL.
16585 * Returns: the status of the operation.
16590 * g_io_channel_read_line_string:
16591 * @channel: a #GIOChannel
16592 * @buffer: a #GString into which the line will be written.
16593 * If @buffer already contains data, the old data will
16595 * @terminator_pos: (allow-none): location to store position of line terminator, or %NULL
16596 * @error: a location to store an error of type #GConvertError
16597 * or #GIOChannelError
16599 * Reads a line from a #GIOChannel, using a #GString as a buffer.
16601 * Returns: the status of the operation.
16606 * g_io_channel_read_to_end:
16607 * @channel: a #GIOChannel
16608 * @str_return: (out) (array length=length) (element-type guint8): Location to
16609 * store a pointer to a string holding the remaining data in the
16610 * #GIOChannel. This data should be freed with g_free() when no
16611 * longer needed. This data is terminated by an extra nul
16612 * character, but there may be other nuls in the intervening data.
16613 * @length: (out): location to store length of the data
16614 * @error: location to return an error of type #GConvertError
16615 * or #GIOChannelError
16617 * Reads all the remaining data from the file.
16619 * Returns: %G_IO_STATUS_NORMAL on success.
16620 * This function never returns %G_IO_STATUS_EOF.
16625 * g_io_channel_read_unichar:
16626 * @channel: a #GIOChannel
16627 * @thechar: (out): a location to return a character
16628 * @error: a location to return an error of type #GConvertError
16629 * or #GIOChannelError
16631 * Reads a Unicode character from @channel.
16632 * This function cannot be called on a channel with %NULL encoding.
16634 * Returns: a #GIOStatus
16639 * g_io_channel_ref:
16640 * @channel: a #GIOChannel
16642 * Increments the reference count of a #GIOChannel.
16644 * Returns: the @channel that was passed in (since 2.6)
16649 * g_io_channel_seek:
16650 * @channel: a #GIOChannel
16651 * @offset: an offset, in bytes, which is added to the position specified
16653 * @type: the position in the file, which can be %G_SEEK_CUR (the current
16654 * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END
16655 * (the end of the file)
16657 * Sets the current position in the #GIOChannel, similar to the standard
16658 * library function fseek().
16660 * Returns: %G_IO_ERROR_NONE if the operation was successful.
16661 * Deprecated: 2.2: Use g_io_channel_seek_position() instead.
16666 * g_io_channel_seek_position:
16667 * @channel: a #GIOChannel
16668 * @offset: The offset in bytes from the position specified by @type
16669 * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those
16670 * cases where a call to g_io_channel_set_encoding ()
16671 * is allowed. See the documentation for
16672 * g_io_channel_set_encoding () for details.
16673 * @error: A location to return an error of type #GIOChannelError
16675 * Replacement for g_io_channel_seek() with the new API.
16677 * Returns: the status of the operation.
16682 * g_io_channel_set_buffer_size:
16683 * @channel: a #GIOChannel
16684 * @size: the size of the buffer, or 0 to let GLib pick a good size
16686 * Sets the buffer size.
16691 * g_io_channel_set_buffered:
16692 * @channel: a #GIOChannel
16693 * @buffered: whether to set the channel buffered or unbuffered
16695 * The buffering state can only be set if the channel's encoding
16696 * is %NULL. For any other encoding, the channel must be buffered.
16698 * A buffered channel can only be set unbuffered if the channel's
16699 * internal buffers have been flushed. Newly created channels or
16700 * channels which have returned %G_IO_STATUS_EOF
16701 * not require such a flush. For write-only channels, a call to
16702 * g_io_channel_flush () is sufficient. For all other channels,
16703 * the buffers may be flushed by a call to g_io_channel_seek_position ().
16704 * This includes the possibility of seeking with seek type %G_SEEK_CUR
16705 * and an offset of zero. Note that this means that socket-based
16706 * channels cannot be set unbuffered once they have had data
16709 * On unbuffered channels, it is safe to mix read and write
16710 * calls from the new and old APIs, if this is necessary for
16711 * maintaining old code.
16713 * The default state of the channel is buffered.
16718 * g_io_channel_set_close_on_unref:
16719 * @channel: a #GIOChannel
16720 * @do_close: Whether to close the channel on the final unref of
16721 * the GIOChannel data structure. The default value of
16722 * this is %TRUE for channels created by g_io_channel_new_file (),
16723 * and %FALSE for all other channels.
16725 * Setting this flag to %TRUE for a channel you have already closed
16726 * can cause problems.
16731 * g_io_channel_set_encoding:
16732 * @channel: a #GIOChannel
16733 * @encoding: (allow-none): the encoding type
16734 * @error: location to store an error of type #GConvertError
16736 * Sets the encoding for the input/output of the channel.
16737 * The internal encoding is always UTF-8. The default encoding
16738 * for the external file is UTF-8.
16740 * The encoding %NULL is safe to use with binary data.
16742 * The encoding can only be set if one of the following conditions
16745 * - The channel was just created, and has not been written to or read from yet.
16747 * - The channel is write-only.
16749 * - The channel is a file, and the file pointer was just repositioned
16750 * by a call to g_io_channel_seek_position(). (This flushes all the
16751 * internal buffers.)
16753 * - The current encoding is %NULL or UTF-8.
16755 * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF
16756 * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
16758 * - One of the functions g_io_channel_read_chars() or
16759 * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
16760 * %G_IO_STATUS_ERROR. This may be useful in the case of
16761 * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
16762 * Returning one of these statuses from g_io_channel_read_line(),
16763 * g_io_channel_read_line_string(), or g_io_channel_read_to_end()
16764 * does not guarantee that the encoding can be changed.
16766 * Channels which do not meet one of the above conditions cannot call
16767 * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
16768 * they are "seekable", cannot call g_io_channel_write_chars() after
16769 * calling one of the API "read" functions.
16771 * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set
16776 * g_io_channel_set_flags:
16777 * @channel: a #GIOChannel
16778 * @flags: the flags to set on the IO channel
16779 * @error: A location to return an error of type #GIOChannelError
16781 * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).
16783 * Returns: the status of the operation.
16788 * g_io_channel_set_line_term:
16789 * @channel: a #GIOChannel
16790 * @line_term: (allow-none): The line termination string. Use %NULL for
16791 * autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0",
16792 * and the Unicode paragraph separator. Autodetection should not be
16793 * used for anything other than file-based channels.
16794 * @length: The length of the termination string. If -1 is passed, the
16795 * string is assumed to be nul-terminated. This option allows
16796 * termination strings with embedded nuls.
16798 * This sets the string that #GIOChannel uses to determine
16799 * where in the file a line break occurs.
16804 * g_io_channel_shutdown:
16805 * @channel: a #GIOChannel
16806 * @flush: if %TRUE, flush pending
16807 * @err: location to store a #GIOChannelError
16809 * Close an IO channel. Any pending data to be written will be
16810 * flushed if @flush is %TRUE. The channel will not be freed until the
16811 * last reference is dropped using g_io_channel_unref().
16813 * Returns: the status of the operation.
16818 * g_io_channel_unix_get_fd:
16819 * @channel: a #GIOChannel, created with g_io_channel_unix_new().
16821 * Returns the file descriptor of the #GIOChannel.
16823 * On Windows this function returns the file descriptor or socket of
16826 * Returns: the file descriptor of the #GIOChannel.
16831 * g_io_channel_unix_new:
16832 * @fd: a file descriptor.
16834 * Creates a new #GIOChannel given a file descriptor. On UNIX systems
16835 * this works for plain files, pipes, and sockets.
16837 * The returned #GIOChannel has a reference count of 1.
16839 * The default encoding for #GIOChannel is UTF-8. If your application
16840 * is reading output from a command using via pipe, you may need to set
16841 * the encoding to the encoding of the current locale (see
16842 * g_get_charset()) with the g_io_channel_set_encoding() function.
16844 * If you want to read raw binary data without interpretation, then
16845 * call the g_io_channel_set_encoding() function with %NULL for the
16846 * encoding argument.
16848 * This function is available in GLib on Windows, too, but you should
16849 * avoid using it on Windows. The domain of file descriptors and
16850 * sockets overlap. There is no way for GLib to know which one you mean
16851 * in case the argument you pass to this function happens to be both a
16852 * valid file descriptor and socket. If that happens a warning is
16853 * issued, and GLib assumes that it is the file descriptor you mean.
16855 * Returns: a new #GIOChannel.
16860 * g_io_channel_unref:
16861 * @channel: a #GIOChannel
16863 * Decrements the reference count of a #GIOChannel.
16868 * g_io_channel_win32_new_fd:
16869 * @fd: a C library file descriptor.
16871 * Creates a new #GIOChannel given a file descriptor on Windows. This
16872 * works for file descriptors from the C runtime.
16874 * This function works for file descriptors as returned by the open(),
16875 * creat(), pipe() and fileno() calls in the Microsoft C runtime. In
16876 * order to meaningfully use this function your code should use the
16877 * same C runtime as GLib uses, which is msvcrt.dll. Note that in
16878 * current Microsoft compilers it is near impossible to convince it to
16879 * build code that would use msvcrt.dll. The last Microsoft compiler
16880 * version that supported using msvcrt.dll as the C runtime was version
16881 * 6. The GNU compiler and toolchain for Windows, also known as Mingw,
16882 * fully supports msvcrt.dll.
16884 * If you have created a #GIOChannel for a file descriptor and started
16885 * watching (polling) it, you shouldn't call read() on the file
16886 * descriptor. This is because adding polling for a file descriptor is
16887 * implemented in GLib on Windows by starting a thread that sits
16888 * blocked in a read() from the file descriptor most of the time. All
16889 * reads from the file descriptor should be done by this internal GLib
16890 * thread. Your code should call only g_io_channel_read().
16892 * This function is available only in GLib on Windows.
16894 * Returns: a new #GIOChannel.
16899 * g_io_channel_win32_new_messages:
16900 * @hwnd: a window handle.
16902 * Creates a new #GIOChannel given a window handle on Windows.
16904 * This function creates a #GIOChannel that can be used to poll for
16905 * Windows messages for the window in question.
16907 * Returns: a new #GIOChannel.
16912 * g_io_channel_win32_new_socket:
16913 * @socket: a Winsock socket
16915 * Creates a new #GIOChannel given a socket on Windows.
16917 * This function works for sockets created by Winsock. It's available
16918 * only in GLib on Windows.
16920 * Polling a #GSource created to watch a channel for a socket puts the
16921 * socket in non-blocking mode. This is a side-effect of the
16922 * implementation and unavoidable.
16924 * Returns: a new #GIOChannel
16929 * g_io_channel_write:
16930 * @channel: a #GIOChannel
16931 * @buf: the buffer containing the data to write
16932 * @count: the number of bytes to write
16933 * @bytes_written: the number of bytes actually written
16935 * Writes data to a #GIOChannel.
16937 * Returns: %G_IO_ERROR_NONE if the operation was successful.
16938 * Deprecated: 2.2: Use g_io_channel_write_chars() instead.
16943 * g_io_channel_write_chars:
16944 * @channel: a #GIOChannel
16945 * @buf: (array) (element-type guint8): a buffer to write data from
16946 * @count: the size of the buffer. If -1, the buffer
16947 * is taken to be a nul-terminated string.
16948 * @bytes_written: (out): The number of bytes written. This can be nonzero
16949 * even if the return value is not %G_IO_STATUS_NORMAL.
16950 * If the return value is %G_IO_STATUS_NORMAL and the
16951 * channel is blocking, this will always be equal
16952 * to @count if @count >= 0.
16953 * @error: a location to return an error of type #GConvertError
16954 * or #GIOChannelError
16956 * Replacement for g_io_channel_write() with the new API.
16958 * On seekable channels with encodings other than %NULL or UTF-8, generic
16959 * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
16960 * may only be made on a channel from which data has been read in the
16961 * cases described in the documentation for g_io_channel_set_encoding ().
16963 * Returns: the status of the operation.
16968 * g_io_channel_write_unichar:
16969 * @channel: a #GIOChannel
16970 * @thechar: a character
16971 * @error: location to return an error of type #GConvertError
16972 * or #GIOChannelError
16974 * Writes a Unicode character to @channel.
16975 * This function cannot be called on a channel with %NULL encoding.
16977 * Returns: a #GIOStatus
16982 * g_io_create_watch:
16983 * @channel: a #GIOChannel to watch
16984 * @condition: conditions to watch for
16986 * Creates a #GSource that's dispatched when @condition is met for the
16987 * given @channel. For example, if condition is #G_IO_IN, the source will
16988 * be dispatched when there's data available for reading.
16990 * g_io_add_watch() is a simpler interface to this same functionality, for
16991 * the case where you want to add the source to the default main loop context
16992 * at the default priority.
16994 * On Windows, polling a #GSource created to watch a channel for a socket
16995 * puts the socket in non-blocking mode. This is a side-effect of the
16996 * implementation and unavoidable.
16998 * Returns: a new #GSource
17003 * g_key_file_free: (skip)
17004 * @key_file: a #GKeyFile
17006 * Clears all keys and groups from @key_file, and decreases the
17007 * reference count by 1. If the reference count reaches zero,
17008 * frees the key file and all its allocated memory.
17015 * g_key_file_get_boolean:
17016 * @key_file: a #GKeyFile
17017 * @group_name: a group name
17019 * @error: return location for a #GError
17021 * Returns the value associated with @key under @group_name as a
17024 * If @key cannot be found then %FALSE is returned and @error is set
17025 * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
17026 * associated with @key cannot be interpreted as a boolean then %FALSE
17027 * is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17029 * Returns: the value associated with the key as a boolean,
17030 * or %FALSE if the key was not found or could not be parsed.
17036 * g_key_file_get_boolean_list:
17037 * @key_file: a #GKeyFile
17038 * @group_name: a group name
17040 * @length: (out): the number of booleans returned
17041 * @error: return location for a #GError
17043 * Returns the values associated with @key under @group_name as
17046 * If @key cannot be found then %NULL is returned and @error is set to
17047 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
17048 * with @key cannot be interpreted as booleans then %NULL is returned
17049 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17051 * Returns: (array length=length) (element-type gboolean) (transfer container):
17052 * the values associated with the key as a list of booleans, or %NULL if the
17053 * key was not found or could not be parsed. The returned list of booleans
17054 * should be freed with g_free() when no longer needed.
17060 * g_key_file_get_comment:
17061 * @key_file: a #GKeyFile
17062 * @group_name: (allow-none): a group name, or %NULL
17064 * @error: return location for a #GError
17066 * Retrieves a comment above @key from @group_name.
17067 * If @key is %NULL then @comment will be read from above
17068 * @group_name. If both @key and @group_name are %NULL, then
17069 * @comment will be read from above the first group in the file.
17071 * Returns: a comment that should be freed with g_free()
17077 * g_key_file_get_double:
17078 * @key_file: a #GKeyFile
17079 * @group_name: a group name
17081 * @error: return location for a #GError
17083 * Returns the value associated with @key under @group_name as a
17084 * double. If @group_name is %NULL, the start_group is used.
17086 * If @key cannot be found then 0.0 is returned and @error is set to
17087 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
17088 * with @key cannot be interpreted as a double then 0.0 is returned
17089 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17091 * Returns: the value associated with the key as a double, or
17092 * 0.0 if the key was not found or could not be parsed.
17098 * g_key_file_get_double_list:
17099 * @key_file: a #GKeyFile
17100 * @group_name: a group name
17102 * @length: (out): the number of doubles returned
17103 * @error: return location for a #GError
17105 * Returns the values associated with @key under @group_name as
17108 * If @key cannot be found then %NULL is returned and @error is set to
17109 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
17110 * with @key cannot be interpreted as doubles then %NULL is returned
17111 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17113 * Returns: (array length=length) (element-type gdouble) (transfer container):
17114 * the values associated with the key as a list of doubles, or %NULL if the
17115 * key was not found or could not be parsed. The returned list of doubles
17116 * should be freed with g_free() when no longer needed.
17122 * g_key_file_get_groups:
17123 * @key_file: a #GKeyFile
17124 * @length: (out) (allow-none): return location for the number of returned groups, or %NULL
17126 * Returns all groups in the key file loaded with @key_file.
17127 * The array of returned groups will be %NULL-terminated, so
17128 * @length may optionally be %NULL.
17130 * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings.
17131 * Use g_strfreev() to free it.
17137 * g_key_file_get_int64:
17138 * @key_file: a non-%NULL #GKeyFile
17139 * @group_name: a non-%NULL group name
17140 * @key: a non-%NULL key
17141 * @error: return location for a #GError
17143 * Returns the value associated with @key under @group_name as a signed
17144 * 64-bit integer. This is similar to g_key_file_get_integer() but can return
17145 * 64-bit results without truncation.
17147 * Returns: the value associated with the key as a signed 64-bit integer, or
17148 * 0 if the key was not found or could not be parsed.
17154 * g_key_file_get_integer:
17155 * @key_file: a #GKeyFile
17156 * @group_name: a group name
17158 * @error: return location for a #GError
17160 * Returns the value associated with @key under @group_name as an
17163 * If @key cannot be found then 0 is returned and @error is set to
17164 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
17165 * with @key cannot be interpreted as an integer then 0 is returned
17166 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17168 * Returns: the value associated with the key as an integer, or
17169 * 0 if the key was not found or could not be parsed.
17175 * g_key_file_get_integer_list:
17176 * @key_file: a #GKeyFile
17177 * @group_name: a group name
17179 * @length: (out): the number of integers returned
17180 * @error: return location for a #GError
17182 * Returns the values associated with @key under @group_name as
17185 * If @key cannot be found then %NULL is returned and @error is set to
17186 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
17187 * with @key cannot be interpreted as integers then %NULL is returned
17188 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17190 * Returns: (array length=length) (element-type gint) (transfer container):
17191 * the values associated with the key as a list of integers, or %NULL if
17192 * the key was not found or could not be parsed. The returned list of
17193 * integers should be freed with g_free() when no longer needed.
17199 * g_key_file_get_keys:
17200 * @key_file: a #GKeyFile
17201 * @group_name: a group name
17202 * @length: (out) (allow-none): return location for the number of keys returned, or %NULL
17203 * @error: return location for a #GError, or %NULL
17205 * Returns all keys for the group name @group_name. The array of
17206 * returned keys will be %NULL-terminated, so @length may
17207 * optionally be %NULL. In the event that the @group_name cannot
17208 * be found, %NULL is returned and @error is set to
17209 * #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
17211 * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings.
17212 * Use g_strfreev() to free it.
17218 * g_key_file_get_locale_string:
17219 * @key_file: a #GKeyFile
17220 * @group_name: a group name
17222 * @locale: (allow-none): a locale identifier or %NULL
17223 * @error: return location for a #GError, or %NULL
17225 * Returns the value associated with @key under @group_name
17226 * translated in the given @locale if available. If @locale is
17227 * %NULL then the current locale is assumed.
17229 * If @key cannot be found then %NULL is returned and @error is set
17230 * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
17231 * with @key cannot be interpreted or no suitable translation can
17232 * be found then the untranslated value is returned.
17234 * Returns: a newly allocated string or %NULL if the specified
17235 * key cannot be found.
17241 * g_key_file_get_locale_string_list:
17242 * @key_file: a #GKeyFile
17243 * @group_name: a group name
17245 * @locale: (allow-none): a locale identifier or %NULL
17246 * @length: (out) (allow-none): return location for the number of returned strings or %NULL
17247 * @error: return location for a #GError or %NULL
17249 * Returns the values associated with @key under @group_name
17250 * translated in the given @locale if available. If @locale is
17251 * %NULL then the current locale is assumed.
17253 * If @key cannot be found then %NULL is returned and @error is set
17254 * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
17255 * with @key cannot be interpreted or no suitable translations
17256 * can be found then the untranslated values are returned. The
17257 * returned array is %NULL-terminated, so @length may optionally
17260 * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array
17261 * or %NULL if the key isn't found. The string array should be freed
17262 * with g_strfreev().
17268 * g_key_file_get_start_group:
17269 * @key_file: a #GKeyFile
17271 * Returns the name of the start group of the file.
17273 * Returns: The start group of the key file.
17279 * g_key_file_get_string:
17280 * @key_file: a #GKeyFile
17281 * @group_name: a group name
17283 * @error: return location for a #GError, or %NULL
17285 * Returns the string value associated with @key under @group_name.
17286 * Unlike g_key_file_get_value(), this function handles escape sequences
17289 * In the event the key cannot be found, %NULL is returned and
17290 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
17291 * event that the @group_name cannot be found, %NULL is returned
17292 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
17294 * Returns: a newly allocated string or %NULL if the specified
17295 * key cannot be found.
17301 * g_key_file_get_string_list:
17302 * @key_file: a #GKeyFile
17303 * @group_name: a group name
17305 * @length: (out) (allow-none): return location for the number of returned strings, or %NULL
17306 * @error: return location for a #GError, or %NULL
17308 * Returns the values associated with @key under @group_name.
17310 * In the event the key cannot be found, %NULL is returned and
17311 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
17312 * event that the @group_name cannot be found, %NULL is returned
17313 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
17315 * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full):
17316 * a %NULL-terminated string array or %NULL if the specified
17317 * key cannot be found. The array should be freed with g_strfreev().
17323 * g_key_file_get_uint64:
17324 * @key_file: a non-%NULL #GKeyFile
17325 * @group_name: a non-%NULL group name
17326 * @key: a non-%NULL key
17327 * @error: return location for a #GError
17329 * Returns the value associated with @key under @group_name as an unsigned
17330 * 64-bit integer. This is similar to g_key_file_get_integer() but can return
17331 * large positive results without truncation.
17333 * Returns: the value associated with the key as an unsigned 64-bit integer,
17334 * or 0 if the key was not found or could not be parsed.
17340 * g_key_file_get_value:
17341 * @key_file: a #GKeyFile
17342 * @group_name: a group name
17344 * @error: return location for a #GError, or %NULL
17346 * Returns the raw value associated with @key under @group_name.
17347 * Use g_key_file_get_string() to retrieve an unescaped UTF-8 string.
17349 * In the event the key cannot be found, %NULL is returned and
17350 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
17351 * event that the @group_name cannot be found, %NULL is returned
17352 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
17354 * Returns: a newly allocated string or %NULL if the specified
17355 * key cannot be found.
17361 * g_key_file_has_group:
17362 * @key_file: a #GKeyFile
17363 * @group_name: a group name
17365 * Looks whether the key file has the group @group_name.
17367 * Returns: %TRUE if @group_name is a part of @key_file, %FALSE
17374 * g_key_file_has_key: (skip)
17375 * @key_file: a #GKeyFile
17376 * @group_name: a group name
17378 * @error: return location for a #GError
17380 * Looks whether the key file has the key @key in the group
17383 * Note that this function does not follow the rules for #GError strictly;
17384 * the return value both carries meaning and signals an error. To use
17385 * this function, you must pass a #GError pointer in @error, and check
17386 * whether it is not %NULL to see if an error occurred.
17388 * Language bindings should use g_key_file_get_value() to test whether
17389 * or not a key exists.
17391 * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise
17397 * g_key_file_load_from_data:
17398 * @key_file: an empty #GKeyFile struct
17399 * @data: key file loaded in memory
17400 * @length: the length of @data in bytes (or (gsize)-1 if data is nul-terminated)
17401 * @flags: flags from #GKeyFileFlags
17402 * @error: return location for a #GError, or %NULL
17404 * Loads a key file from memory into an empty #GKeyFile structure.
17405 * If the object cannot be created then %error is set to a #GKeyFileError.
17407 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
17413 * g_key_file_load_from_data_dirs:
17414 * @key_file: an empty #GKeyFile struct
17415 * @file: (type filename): a relative path to a filename to open and parse
17416 * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path
17417 * of the file, or %NULL
17418 * @flags: flags from #GKeyFileFlags
17419 * @error: return location for a #GError, or %NULL
17421 * This function looks for a key file named @file in the paths
17422 * returned from g_get_user_data_dir() and g_get_system_data_dirs(),
17423 * loads the file into @key_file and returns the file's full path in
17424 * @full_path. If the file could not be loaded then an %error is
17425 * set to either a #GFileError or #GKeyFileError.
17427 * Returns: %TRUE if a key file could be loaded, %FALSE othewise
17433 * g_key_file_load_from_dirs:
17434 * @key_file: an empty #GKeyFile struct
17435 * @file: (type filename): a relative path to a filename to open and parse
17436 * @search_dirs: (array zero-terminated=1) (element-type filename): %NULL-terminated array of directories to search
17437 * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path
17438 * of the file, or %NULL
17439 * @flags: flags from #GKeyFileFlags
17440 * @error: return location for a #GError, or %NULL
17442 * This function looks for a key file named @file in the paths
17443 * specified in @search_dirs, loads the file into @key_file and
17444 * returns the file's full path in @full_path. If the file could not
17445 * be loaded then an %error is set to either a #GFileError or
17448 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
17454 * g_key_file_load_from_file:
17455 * @key_file: an empty #GKeyFile struct
17456 * @file: (type filename): the path of a filename to load, in the GLib filename encoding
17457 * @flags: flags from #GKeyFileFlags
17458 * @error: return location for a #GError, or %NULL
17460 * Loads a key file into an empty #GKeyFile structure.
17461 * If the file could not be loaded then @error is set to
17462 * either a #GFileError or #GKeyFileError.
17464 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
17472 * Creates a new empty #GKeyFile object. Use
17473 * g_key_file_load_from_file(), g_key_file_load_from_data(),
17474 * g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to
17475 * read an existing key file.
17477 * Returns: (transfer full): an empty #GKeyFile.
17483 * g_key_file_ref: (skip)
17484 * @key_file: a #GKeyFile
17486 * Increases the reference count of @key_file.
17488 * Returns: the same @key_file.
17494 * g_key_file_remove_comment:
17495 * @key_file: a #GKeyFile
17496 * @group_name: (allow-none): a group name, or %NULL
17497 * @key: (allow-none): a key
17498 * @error: return location for a #GError
17500 * Removes a comment above @key from @group_name.
17501 * If @key is %NULL then @comment will be removed above @group_name.
17502 * If both @key and @group_name are %NULL, then @comment will
17503 * be removed above the first group in the file.
17505 * Returns: %TRUE if the comment was removed, %FALSE otherwise
17511 * g_key_file_remove_group:
17512 * @key_file: a #GKeyFile
17513 * @group_name: a group name
17514 * @error: return location for a #GError or %NULL
17516 * Removes the specified group, @group_name,
17517 * from the key file.
17519 * Returns: %TRUE if the group was removed, %FALSE otherwise
17525 * g_key_file_remove_key:
17526 * @key_file: a #GKeyFile
17527 * @group_name: a group name
17528 * @key: a key name to remove
17529 * @error: return location for a #GError or %NULL
17531 * Removes @key in @group_name from the key file.
17533 * Returns: %TRUE if the key was removed, %FALSE otherwise
17539 * g_key_file_save_to_file:
17540 * @key_file: a #GKeyFile
17541 * @filename: the name of the file to write to
17542 * @error: a pointer to a %NULL #GError, or %NULL
17544 * Writes the contents of @key_file to @filename using
17545 * g_file_set_contents().
17547 * This function can fail for any of the reasons that
17548 * g_file_set_contents() may fail.
17550 * Returns: %TRUE if successful, else %FALSE with @error set
17556 * g_key_file_set_boolean:
17557 * @key_file: a #GKeyFile
17558 * @group_name: a group name
17560 * @value: %TRUE or %FALSE
17562 * Associates a new boolean value with @key under @group_name.
17563 * If @key cannot be found then it is created.
17570 * g_key_file_set_boolean_list:
17571 * @key_file: a #GKeyFile
17572 * @group_name: a group name
17574 * @list: (array length=length): an array of boolean values
17575 * @length: length of @list
17577 * Associates a list of boolean values with @key under @group_name.
17578 * If @key cannot be found then it is created.
17579 * If @group_name is %NULL, the start_group is used.
17586 * g_key_file_set_comment:
17587 * @key_file: a #GKeyFile
17588 * @group_name: (allow-none): a group name, or %NULL
17589 * @key: (allow-none): a key
17590 * @comment: a comment
17591 * @error: return location for a #GError
17593 * Places a comment above @key from @group_name.
17594 * If @key is %NULL then @comment will be written above @group_name.
17595 * If both @key and @group_name are %NULL, then @comment will be
17596 * written above the first group in the file.
17598 * Returns: %TRUE if the comment was written, %FALSE otherwise
17604 * g_key_file_set_double:
17605 * @key_file: a #GKeyFile
17606 * @group_name: a group name
17608 * @value: an double value
17610 * Associates a new double value with @key under @group_name.
17611 * If @key cannot be found then it is created.
17618 * g_key_file_set_double_list:
17619 * @key_file: a #GKeyFile
17620 * @group_name: a group name
17622 * @list: (array length=length): an array of double values
17623 * @length: number of double values in @list
17625 * Associates a list of double values with @key under
17626 * @group_name. If @key cannot be found then it is created.
17633 * g_key_file_set_int64:
17634 * @key_file: a #GKeyFile
17635 * @group_name: a group name
17637 * @value: an integer value
17639 * Associates a new integer value with @key under @group_name.
17640 * If @key cannot be found then it is created.
17647 * g_key_file_set_integer:
17648 * @key_file: a #GKeyFile
17649 * @group_name: a group name
17651 * @value: an integer value
17653 * Associates a new integer value with @key under @group_name.
17654 * If @key cannot be found then it is created.
17661 * g_key_file_set_integer_list:
17662 * @key_file: a #GKeyFile
17663 * @group_name: a group name
17665 * @list: (array length=length): an array of integer values
17666 * @length: number of integer values in @list
17668 * Associates a list of integer values with @key under @group_name.
17669 * If @key cannot be found then it is created.
17676 * g_key_file_set_list_separator:
17677 * @key_file: a #GKeyFile
17678 * @separator: the separator
17680 * Sets the character which is used to separate
17681 * values in lists. Typically ';' or ',' are used
17682 * as separators. The default list separator is ';'.
17689 * g_key_file_set_locale_string:
17690 * @key_file: a #GKeyFile
17691 * @group_name: a group name
17693 * @locale: a locale identifier
17694 * @string: a string
17696 * Associates a string value for @key and @locale under @group_name.
17697 * If the translation for @key cannot be found then it is created.
17704 * g_key_file_set_locale_string_list:
17705 * @key_file: a #GKeyFile
17706 * @group_name: a group name
17708 * @locale: a locale identifier
17709 * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values
17710 * @length: the length of @list
17712 * Associates a list of string values for @key and @locale under
17713 * @group_name. If the translation for @key cannot be found then
17721 * g_key_file_set_string:
17722 * @key_file: a #GKeyFile
17723 * @group_name: a group name
17725 * @string: a string
17727 * Associates a new string value with @key under @group_name.
17728 * If @key cannot be found then it is created.
17729 * If @group_name cannot be found then it is created.
17730 * Unlike g_key_file_set_value(), this function handles characters
17731 * that need escaping, such as newlines.
17738 * g_key_file_set_string_list:
17739 * @key_file: a #GKeyFile
17740 * @group_name: a group name
17742 * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values
17743 * @length: number of string values in @list
17745 * Associates a list of string values for @key under @group_name.
17746 * If @key cannot be found then it is created.
17747 * If @group_name cannot be found then it is created.
17754 * g_key_file_set_uint64:
17755 * @key_file: a #GKeyFile
17756 * @group_name: a group name
17758 * @value: an integer value
17760 * Associates a new integer value with @key under @group_name.
17761 * If @key cannot be found then it is created.
17768 * g_key_file_set_value:
17769 * @key_file: a #GKeyFile
17770 * @group_name: a group name
17774 * Associates a new value with @key under @group_name.
17776 * If @key cannot be found then it is created. If @group_name cannot
17777 * be found then it is created. To set an UTF-8 string which may contain
17778 * characters that need escaping (such as newlines or spaces), use
17779 * g_key_file_set_string().
17786 * g_key_file_to_data:
17787 * @key_file: a #GKeyFile
17788 * @length: (out) (allow-none): return location for the length of the
17789 * returned string, or %NULL
17790 * @error: return location for a #GError, or %NULL
17792 * This function outputs @key_file as a string.
17794 * Note that this function never reports an error,
17795 * so it is safe to pass %NULL as @error.
17797 * Returns: a newly allocated string holding
17798 * the contents of the #GKeyFile
17804 * g_key_file_unref:
17805 * @key_file: a #GKeyFile
17807 * Decreases the reference count of @key_file by 1. If the reference count
17808 * reaches zero, frees the key file and all its allocated memory.
17817 * Allocates space for one #GList element. It is called by
17818 * g_list_append(), g_list_prepend(), g_list_insert() and
17819 * g_list_insert_sorted() and so is rarely used on its own.
17821 * Returns: a pointer to the newly-allocated #GList element
17827 * @list: a pointer to a #GList
17828 * @data: the data for the new element
17830 * Adds a new element on to the end of the list.
17832 * Note that the return value is the new start of the list,
17833 * if @list was empty; make sure you store the new value.
17835 * g_list_append() has to traverse the entire list to find the end,
17836 * which is inefficient when adding multiple elements. A common idiom
17837 * to avoid the inefficiency is to use g_list_prepend() and reverse
17838 * the list with g_list_reverse() when all elements have been added.
17840 * |[<!-- language="C" -->
17841 * // Notice that these are initialized to the empty list.
17842 * GList *string_list = NULL, *number_list = NULL;
17844 * // This is a list of strings.
17845 * string_list = g_list_append (string_list, "first");
17846 * string_list = g_list_append (string_list, "second");
17848 * // This is a list of integers.
17849 * number_list = g_list_append (number_list, GINT_TO_POINTER (27));
17850 * number_list = g_list_append (number_list, GINT_TO_POINTER (14));
17853 * Returns: either @list or the new start of the #GList if @list was %NULL
17859 * @list1: a #GList, this must point to the top of the list
17860 * @list2: the #GList to add to the end of the first #GList,
17861 * this must point to the top of the list
17863 * Adds the second #GList onto the end of the first #GList.
17864 * Note that the elements of the second #GList are not copied.
17865 * They are used directly.
17867 * This function is for example used to move an element in the list.
17868 * The following example moves an element to the top of the list:
17869 * |[<!-- language="C" -->
17870 * list = g_list_remove_link (list, llink);
17871 * list = g_list_concat (llink, list);
17874 * Returns: the start of the new #GList, which equals @list1 if not %NULL
17880 * @list: a #GList, this must point to the top of the list
17884 * Note that this is a "shallow" copy. If the list elements
17885 * consist of pointers to data, the pointers are copied but
17886 * the actual data is not. See g_list_copy_deep() if you need
17887 * to copy the data as well.
17889 * Returns: the start of the new list that holds the same data as @list
17894 * g_list_copy_deep:
17895 * @list: a #GList, this must point to the top of the list
17896 * @func: a copy function used to copy every element in the list
17897 * @user_data: user data passed to the copy function @func, or %NULL
17899 * Makes a full (deep) copy of a #GList.
17901 * In contrast with g_list_copy(), this function uses @func to make
17902 * a copy of each list element, in addition to copying the list
17903 * container itself.
17905 * @func, as a #GCopyFunc, takes two arguments, the data to be copied
17906 * and a @user_data pointer. It's safe to pass %NULL as user_data,
17907 * if the copy function takes only one argument.
17909 * For instance, if @list holds a list of GObjects, you can do:
17910 * |[<!-- language="C" -->
17911 * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
17914 * And, to entirely free the new list, you could do:
17915 * |[<!-- language="C" -->
17916 * g_list_free_full (another_list, g_object_unref);
17919 * Returns: the start of the new list that holds a full copy of @list,
17920 * use g_list_free_full() to free it
17926 * g_list_delete_link:
17927 * @list: a #GList, this must point to the top of the list
17928 * @link_: node to delete from @list
17930 * Removes the node link_ from the list and frees it.
17931 * Compare this to g_list_remove_link() which removes the node
17932 * without freeing it.
17934 * Returns: the (possibly changed) start of the #GList
17940 * @list: a #GList, this must point to the top of the list
17941 * @data: the element data to find
17943 * Finds the element in a #GList which contains the given data.
17945 * Returns: the found #GList element, or %NULL if it is not found
17950 * g_list_find_custom:
17951 * @list: a #GList, this must point to the top of the list
17952 * @data: user data passed to the function
17953 * @func: the function to call for each element.
17954 * It should return 0 when the desired element is found
17956 * Finds an element in a #GList, using a supplied function to
17957 * find the desired element. It iterates over the list, calling
17958 * the given function which should return 0 when the desired
17959 * element is found. The function takes two #gconstpointer arguments,
17960 * the #GList element's data as the first argument and the
17963 * Returns: the found #GList element, or %NULL if it is not found
17969 * @list: any #GList element
17971 * Gets the first element in a #GList.
17973 * Returns: the first element in the #GList,
17974 * or %NULL if the #GList has no elements
17980 * @list: a #GList, this must point to the top of the list
17981 * @func: the function to call with each element's data
17982 * @user_data: user data to pass to the function
17984 * Calls a function for each element of a #GList.
17992 * Frees all of the memory used by a #GList.
17993 * The freed elements are returned to the slice allocator.
17995 * If list elements contain dynamically-allocated memory, you should
17996 * either use g_list_free_full() or free them manually first.
18003 * Another name for g_list_free_1().
18009 * @list: a #GList element
18011 * Frees one #GList element.
18012 * It is usually used after g_list_remove_link().
18017 * g_list_free_full:
18018 * @list: a pointer to a #GList
18019 * @free_func: the function to be called to free each element's data
18021 * Convenience method, which frees all the memory used by a #GList,
18022 * and calls @free_func on every element's data.
18030 * @list: a #GList, this must point to the top of the list
18031 * @data: the data to find
18033 * Gets the position of the element containing
18034 * the given data (starting from 0).
18036 * Returns: the index of the element containing the data,
18037 * or -1 if the data is not found
18043 * @list: a pointer to a #GList, this must point to the top of the list
18044 * @data: the data for the new element
18045 * @position: the position to insert the element. If this is
18046 * negative, or is larger than the number of elements in the
18047 * list, the new element is added on to the end of the list.
18049 * Inserts a new element into the list at the given position.
18051 * Returns: the (possibly changed) start of the #GList
18056 * g_list_insert_before:
18057 * @list: a pointer to a #GList, this must point to the top of the list
18058 * @sibling: the list element before which the new element
18059 * is inserted or %NULL to insert at the end of the list
18060 * @data: the data for the new element
18062 * Inserts a new element into the list before the given position.
18064 * Returns: the (possibly changed) start of the #GList
18069 * g_list_insert_sorted:
18070 * @list: a pointer to a #GList, this must point to the top of the
18071 * already sorted list
18072 * @data: the data for the new element
18073 * @func: the function to compare elements in the list. It should
18074 * return a number > 0 if the first parameter comes after the
18075 * second parameter in the sort order.
18077 * Inserts a new element into the list, using the given comparison
18078 * function to determine its position.
18080 * If you are adding many new elements to a list, and the number of
18081 * new elements is much larger than the length of the list, use
18082 * g_list_prepend() to add the new items and sort the list afterwards
18083 * with g_list_sort().
18085 * Returns: the (possibly changed) start of the #GList
18090 * g_list_insert_sorted_with_data:
18091 * @list: a pointer to a #GList, this must point to the top of the
18092 * already sorted list
18093 * @data: the data for the new element
18094 * @func: the function to compare elements in the list. It should
18095 * return a number > 0 if the first parameter comes after the
18096 * second parameter in the sort order.
18097 * @user_data: user data to pass to comparison function
18099 * Inserts a new element into the list, using the given comparison
18100 * function to determine its position.
18102 * If you are adding many new elements to a list, and the number of
18103 * new elements is much larger than the length of the list, use
18104 * g_list_prepend() to add the new items and sort the list afterwards
18105 * with g_list_sort().
18107 * Returns: the (possibly changed) start of the #GList
18114 * @list: any #GList element
18116 * Gets the last element in a #GList.
18118 * Returns: the last element in the #GList,
18119 * or %NULL if the #GList has no elements
18125 * @list: a #GList, this must point to the top of the list
18127 * Gets the number of elements in a #GList.
18129 * This function iterates over the whole list to count its elements.
18130 * Use a #GQueue instead of a GList if you regularly need the number
18133 * Returns: the number of elements in the #GList
18139 * @list: an element in a #GList
18141 * A convenience macro to get the next element in a #GList.
18142 * Note that it is considered perfectly acceptable to access
18143 * @list->next directly.
18145 * Returns: the next element, or %NULL if there are no more elements
18151 * @list: a #GList, this must point to the top of the list
18152 * @n: the position of the element, counting from 0
18154 * Gets the element at the given position in a #GList.
18156 * Returns: the element, or %NULL if the position is off
18157 * the end of the #GList
18163 * @list: a #GList, this must point to the top of the list
18164 * @n: the position of the element
18166 * Gets the data of the element at the given position.
18168 * Returns: the element's data, or %NULL if the position
18169 * is off the end of the #GList
18176 * @n: the position of the element, counting from 0
18178 * Gets the element @n places before @list.
18180 * Returns: the element, or %NULL if the position is
18181 * off the end of the #GList
18187 * @list: a #GList, this must point to the top of the list
18188 * @llink: an element in the #GList
18190 * Gets the position of the given element
18191 * in the #GList (starting from 0).
18193 * Returns: the position of the element in the #GList,
18194 * or -1 if the element is not found
18200 * @list: a pointer to a #GList, this must point to the top of the list
18201 * @data: the data for the new element
18203 * Prepends a new element on to the start of the list.
18205 * Note that the return value is the new start of the list,
18206 * which will have changed, so make sure you store the new value.
18208 * |[<!-- language="C" -->
18209 * // Notice that it is initialized to the empty list.
18210 * GList *list = NULL;
18212 * list = g_list_prepend (list, "last");
18213 * list = g_list_prepend (list, "first");
18216 * Do not use this function to prepend a new element to a different
18217 * element than the start of the list. Use g_list_insert_before() instead.
18219 * Returns: a pointer to the newly prepended element, which is the new
18220 * start of the #GList
18226 * @list: an element in a #GList
18228 * A convenience macro to get the previous element in a #GList.
18229 * Note that it is considered perfectly acceptable to access
18230 * @list->previous directly.
18232 * Returns: the previous element, or %NULL if there are no previous
18239 * @list: a #GList, this must point to the top of the list
18240 * @data: the data of the element to remove
18242 * Removes an element from a #GList.
18243 * If two elements contain the same data, only the first is removed.
18244 * If none of the elements contain the data, the #GList is unchanged.
18246 * Returns: the (possibly changed) start of the #GList
18251 * g_list_remove_all:
18252 * @list: a #GList, this must point to the top of the list
18253 * @data: data to remove
18255 * Removes all list nodes with data equal to @data.
18256 * Returns the new head of the list. Contrast with
18257 * g_list_remove() which removes only the first node
18258 * matching the given data.
18260 * Returns: the (possibly changed) start of the #GList
18265 * g_list_remove_link:
18266 * @list: a #GList, this must point to the top of the list
18267 * @llink: an element in the #GList
18269 * Removes an element from a #GList, without freeing the element.
18270 * The removed element's prev and next links are set to %NULL, so
18271 * that it becomes a self-contained list with one element.
18273 * This function is for example used to move an element in the list
18274 * (see the example for g_list_concat()) or to remove an element in
18275 * the list before freeing its data:
18276 * |[<!-- language="C" -->
18277 * list = g_list_remove_link (list, llink);
18278 * free_some_data_that_may_access_the_list_again (llink->data);
18279 * g_list_free (llink);
18282 * Returns: the (possibly changed) start of the #GList
18288 * @list: a #GList, this must point to the top of the list
18290 * Reverses a #GList.
18291 * It simply switches the next and prev pointers of each element.
18293 * Returns: the start of the reversed #GList
18299 * @list: a #GList, this must point to the top of the list
18300 * @compare_func: the comparison function used to sort the #GList.
18301 * This function is passed the data from 2 elements of the #GList
18302 * and should return 0 if they are equal, a negative value if the
18303 * first element comes before the second, or a positive value if
18304 * the first element comes after the second.
18306 * Sorts a #GList using the given comparison function. The algorithm
18307 * used is a stable sort.
18309 * Returns: the (possibly changed) start of the #GList
18314 * g_list_sort_with_data:
18315 * @list: a #GList, this must point to the top of the list
18316 * @compare_func: comparison function
18317 * @user_data: user data to pass to comparison function
18319 * Like g_list_sort(), but the comparison function accepts
18320 * a user data argument.
18322 * Returns: the (possibly changed) start of the #GList
18329 * Gets the names of all variables set in the environment.
18331 * Programs that want to be portable to Windows should typically use
18332 * this function and g_getenv() instead of using the environ array
18333 * from the C library directly. On Windows, the strings in the environ
18334 * array are in system codepage encoding, while in most of the typical
18335 * use cases for environment variables in GLib-using programs you want
18336 * the UTF-8 encoding that this function and g_getenv() provide.
18338 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated
18339 * list of strings which must be freed with g_strfreev().
18345 * g_locale_from_utf8:
18346 * @utf8string: a UTF-8 encoded string
18347 * @len: the length of the string, or -1 if the string is
18348 * nul-terminated (Note that some encodings may allow nul
18349 * bytes to occur inside strings. In that case, using -1
18350 * for the @len parameter is unsafe)
18351 * @bytes_read: location to store the number of bytes in the
18352 * input string that were successfully converted, or %NULL.
18353 * Even if the conversion was successful, this may be
18354 * less than @len if there were partial characters
18355 * at the end of the input. If the error
18356 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
18357 * stored will the byte offset after the last valid
18359 * @bytes_written: the number of bytes stored in the output buffer (not
18360 * including the terminating nul).
18361 * @error: location to store the error occurring, or %NULL to ignore
18362 * errors. Any of the errors in #GConvertError may occur.
18364 * Converts a string from UTF-8 to the encoding used for strings by
18365 * the C runtime (usually the same as that used by the operating
18366 * system) in the [current locale][setlocale]. On Windows this means
18367 * the system codepage.
18369 * Returns: A newly-allocated buffer containing the converted string,
18370 * or %NULL on an error, and error will be set.
18375 * g_locale_to_utf8:
18376 * @opsysstring: a string in the encoding of the current locale. On Windows
18377 * this means the system codepage.
18378 * @len: the length of the string, or -1 if the string is
18379 * nul-terminated (Note that some encodings may allow nul
18380 * bytes to occur inside strings. In that case, using -1
18381 * for the @len parameter is unsafe)
18382 * @bytes_read: location to store the number of bytes in the
18383 * input string that were successfully converted, or %NULL.
18384 * Even if the conversion was successful, this may be
18385 * less than @len if there were partial characters
18386 * at the end of the input. If the error
18387 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
18388 * stored will the byte offset after the last valid
18390 * @bytes_written: the number of bytes stored in the output buffer (not
18391 * including the terminating nul).
18392 * @error: location to store the error occurring, or %NULL to ignore
18393 * errors. Any of the errors in #GConvertError may occur.
18395 * Converts a string which is in the encoding used for strings by
18396 * the C runtime (usually the same as that used by the operating
18397 * system) in the [current locale][setlocale] into a UTF-8 string.
18399 * Returns: A newly-allocated buffer containing the converted string,
18400 * or %NULL on an error, and error will be set.
18406 * @log_domain: the log domain, usually #G_LOG_DOMAIN
18407 * @log_level: the log level, either from #GLogLevelFlags
18408 * or a user-defined level
18409 * @format: the message format. See the printf() documentation
18410 * @...: the parameters to insert into the format string
18412 * Logs an error or debugging message.
18414 * If the log level has been set as fatal, the abort()
18415 * function is called to terminate the program.
18417 * If g_log_default_handler() is used as the log handler function, a new-line
18418 * character will automatically be appended to @..., and need not be entered
18424 * g_log_default_handler:
18425 * @log_domain: the log domain of the message
18426 * @log_level: the level of the message
18427 * @message: the message
18428 * @unused_data: data passed from g_log() which is unused
18430 * The default log handler set up by GLib; g_log_set_default_handler()
18431 * allows to install an alternate default log handler.
18432 * This is used if no log handler has been set for the particular log
18433 * domain and log level combination. It outputs the message to stderr
18434 * or stdout and if the log level is fatal it calls abort(). It automatically
18435 * prints a new-line character after the message, so one does not need to be
18436 * manually included in @message.
18438 * The behavior of this log handler can be influenced by a number of
18439 * environment variables:
18441 * - `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which
18442 * messages should be prefixed by the program name and PID of the
18445 * - `G_MESSAGES_DEBUG`: A space-separated list of log domains for
18446 * which debug and informational messages are printed. By default
18447 * these messages are not printed.
18449 * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
18450 * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for
18456 * g_log_remove_handler:
18457 * @log_domain: the log domain
18458 * @handler_id: the id of the handler, which was returned
18459 * in g_log_set_handler()
18461 * Removes the log handler.
18466 * g_log_set_always_fatal:
18467 * @fatal_mask: the mask containing bits set for each level
18468 * of error which is to be fatal
18470 * Sets the message levels which are always fatal, in any log domain.
18471 * When a message with any of these levels is logged the program terminates.
18472 * You can only set the levels defined by GLib to be fatal.
18473 * %G_LOG_LEVEL_ERROR is always fatal.
18475 * You can also make some message levels fatal at runtime by setting
18476 * the `G_DEBUG` environment variable (see
18477 * [Running GLib Applications](glib-running.html)).
18479 * Returns: the old fatal mask
18484 * g_log_set_default_handler:
18485 * @log_func: the log handler function
18486 * @user_data: data passed to the log handler
18488 * Installs a default log handler which is used if no
18489 * log handler has been set for the particular log domain
18490 * and log level combination. By default, GLib uses
18491 * g_log_default_handler() as default log handler.
18493 * Returns: the previous default log handler
18499 * g_log_set_fatal_mask:
18500 * @log_domain: the log domain
18501 * @fatal_mask: the new fatal mask
18503 * Sets the log levels which are fatal in the given domain.
18504 * %G_LOG_LEVEL_ERROR is always fatal.
18506 * Returns: the old fatal mask for the log domain
18511 * g_log_set_handler:
18512 * @log_domain: (allow-none): the log domain, or %NULL for the default ""
18513 * application domain
18514 * @log_levels: the log levels to apply the log handler for.
18515 * To handle fatal and recursive messages as well, combine
18516 * the log levels with the #G_LOG_FLAG_FATAL and
18517 * #G_LOG_FLAG_RECURSION bit flags.
18518 * @log_func: the log handler function
18519 * @user_data: data passed to the log handler
18521 * Sets the log handler for a domain and a set of log levels.
18522 * To handle fatal and recursive messages the @log_levels parameter
18523 * must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION
18526 * Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
18527 * you want to set a handler for this log level you must combine it with
18528 * #G_LOG_FLAG_FATAL.
18530 * Here is an example for adding a log handler for all warning messages
18531 * in the default domain:
18532 * |[<!-- language="C" -->
18533 * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
18534 * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
18537 * This example adds a log handler for all critical messages from GTK+:
18538 * |[<!-- language="C" -->
18539 * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
18540 * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
18543 * This example adds a log handler for all messages from GLib:
18544 * |[<!-- language="C" -->
18545 * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
18546 * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
18549 * Returns: the id of the new handler
18555 * @log_domain: the log domain
18556 * @log_level: the log level
18557 * @format: the message format. See the printf() documentation
18558 * @args: the parameters to insert into the format string
18560 * Logs an error or debugging message.
18562 * If the log level has been set as fatal, the abort()
18563 * function is called to terminate the program.
18565 * If g_log_default_handler() is used as the log handler function, a new-line
18566 * character will automatically be appended to @..., and need not be entered
18573 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
18574 * @buf: a pointer to a stat struct, which will be filled with the file
18577 * A wrapper for the POSIX lstat() function. The lstat() function is
18578 * like stat() except that in the case of symbolic links, it returns
18579 * information about the symbolic link itself and not the file that it
18580 * refers to. If the system does not support symbolic links g_lstat()
18581 * is identical to g_stat().
18583 * See your C library manual for more details about lstat().
18585 * Returns: 0 if the information was successfully retrieved,
18586 * -1 if an error occurred
18592 * g_main_context_acquire:
18593 * @context: a #GMainContext
18595 * Tries to become the owner of the specified context.
18596 * If some other thread is the owner of the context,
18597 * returns %FALSE immediately. Ownership is properly
18598 * recursive: the owner can require ownership again
18599 * and will release ownership when g_main_context_release()
18600 * is called as many times as g_main_context_acquire().
18602 * You must be the owner of a context before you
18603 * can call g_main_context_prepare(), g_main_context_query(),
18604 * g_main_context_check(), g_main_context_dispatch().
18606 * Returns: %TRUE if the operation succeeded, and
18607 * this thread is now the owner of @context.
18612 * g_main_context_add_poll:
18613 * @context: (allow-none): a #GMainContext (or %NULL for the default context)
18614 * @fd: a #GPollFD structure holding information about a file
18615 * descriptor to watch.
18616 * @priority: the priority for this file descriptor which should be
18617 * the same as the priority used for g_source_attach() to ensure that the
18618 * file descriptor is polled whenever the results may be needed.
18620 * Adds a file descriptor to the set of file descriptors polled for
18621 * this context. This will very seldom be used directly. Instead
18622 * a typical event source will use g_source_add_unix_fd() instead.
18627 * g_main_context_check:
18628 * @context: a #GMainContext
18629 * @max_priority: the maximum numerical priority of sources to check
18630 * @fds: (array length=n_fds): array of #GPollFD's that was passed to
18631 * the last call to g_main_context_query()
18632 * @n_fds: return value of g_main_context_query()
18634 * Passes the results of polling back to the main loop.
18636 * You must have successfully acquired the context with
18637 * g_main_context_acquire() before you may call this function.
18639 * Returns: %TRUE if some sources are ready to be dispatched.
18644 * g_main_context_default:
18646 * Returns the global default main context. This is the main context
18647 * used for main loop functions when a main loop is not explicitly
18648 * specified, and corresponds to the "main" main loop. See also
18649 * g_main_context_get_thread_default().
18651 * Returns: (transfer none): the global default main context.
18656 * g_main_context_dispatch:
18657 * @context: a #GMainContext
18659 * Dispatches all pending sources.
18661 * You must have successfully acquired the context with
18662 * g_main_context_acquire() before you may call this function.
18667 * g_main_context_find_source_by_funcs_user_data:
18668 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used).
18669 * @funcs: the @source_funcs passed to g_source_new().
18670 * @user_data: the user data from the callback.
18672 * Finds a source with the given source functions and user data. If
18673 * multiple sources exist with the same source function and user data,
18674 * the first one found will be returned.
18676 * Returns: (transfer none): the source, if one was found, otherwise %NULL
18681 * g_main_context_find_source_by_id:
18682 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
18683 * @source_id: the source ID, as returned by g_source_get_id().
18685 * Finds a #GSource given a pair of context and ID.
18687 * Returns: (transfer none): the #GSource if found, otherwise, %NULL
18692 * g_main_context_find_source_by_user_data:
18693 * @context: a #GMainContext
18694 * @user_data: the user_data for the callback.
18696 * Finds a source with the given user data for the callback. If
18697 * multiple sources exist with the same user data, the first
18698 * one found will be returned.
18700 * Returns: (transfer none): the source, if one was found, otherwise %NULL
18705 * g_main_context_get_poll_func:
18706 * @context: a #GMainContext
18708 * Gets the poll function set by g_main_context_set_poll_func().
18710 * Returns: the poll function
18715 * g_main_context_get_thread_default:
18717 * Gets the thread-default #GMainContext for this thread. Asynchronous
18718 * operations that want to be able to be run in contexts other than
18719 * the default one should call this method or
18720 * g_main_context_ref_thread_default() to get a #GMainContext to add
18721 * their #GSources to. (Note that even in single-threaded
18722 * programs applications may sometimes want to temporarily push a
18723 * non-default context, so it is not safe to assume that this will
18724 * always return %NULL if you are running in the default thread.)
18726 * If you need to hold a reference on the context, use
18727 * g_main_context_ref_thread_default() instead.
18729 * Returns: (transfer none): the thread-default #GMainContext, or
18730 * %NULL if the thread-default context is the global default context.
18736 * g_main_context_invoke:
18737 * @context: (allow-none): a #GMainContext, or %NULL
18738 * @function: function to call
18739 * @data: data to pass to @function
18741 * Invokes a function in such a way that @context is owned during the
18742 * invocation of @function.
18744 * If @context is %NULL then the global default main context — as
18745 * returned by g_main_context_default() — is used.
18747 * If @context is owned by the current thread, @function is called
18748 * directly. Otherwise, if @context is the thread-default main context
18749 * of the current thread and g_main_context_acquire() succeeds, then
18750 * @function is called and g_main_context_release() is called
18753 * In any other case, an idle source is created to call @function and
18754 * that source is attached to @context (presumably to be run in another
18755 * thread). The idle source is attached with #G_PRIORITY_DEFAULT
18756 * priority. If you want a different priority, use
18757 * g_main_context_invoke_full().
18759 * Note that, as with normal idle functions, @function should probably
18760 * return %FALSE. If it returns %TRUE, it will be continuously run in a
18761 * loop (and may prevent this call from returning).
18768 * g_main_context_invoke_full:
18769 * @context: (allow-none): a #GMainContext, or %NULL
18770 * @priority: the priority at which to run @function
18771 * @function: function to call
18772 * @data: data to pass to @function
18773 * @notify: (allow-none): a function to call when @data is no longer in use, or %NULL.
18775 * Invokes a function in such a way that @context is owned during the
18776 * invocation of @function.
18778 * This function is the same as g_main_context_invoke() except that it
18779 * lets you specify the priority incase @function ends up being
18780 * scheduled as an idle and also lets you give a #GDestroyNotify for @data.
18782 * @notify should not assume that it is called from any particular
18783 * thread or with any particular context acquired.
18790 * g_main_context_is_owner:
18791 * @context: a #GMainContext
18793 * Determines whether this thread holds the (recursive)
18794 * ownership of this #GMainContext. This is useful to
18795 * know before waiting on another thread that may be
18796 * blocking to get ownership of @context.
18798 * Returns: %TRUE if current thread is owner of @context.
18804 * g_main_context_iteration:
18805 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
18806 * @may_block: whether the call may block.
18808 * Runs a single iteration for the given main loop. This involves
18809 * checking to see if any event sources are ready to be processed,
18810 * then if no events sources are ready and @may_block is %TRUE, waiting
18811 * for a source to become ready, then dispatching the highest priority
18812 * events sources that are ready. Otherwise, if @may_block is %FALSE
18813 * sources are not waited to become ready, only those highest priority
18814 * events sources will be dispatched (if any), that are ready at this
18815 * given moment without further waiting.
18817 * Note that even when @may_block is %TRUE, it is still possible for
18818 * g_main_context_iteration() to return %FALSE, since the wait may
18819 * be interrupted for other reasons than an event source becoming ready.
18821 * Returns: %TRUE if events were dispatched.
18826 * g_main_context_new:
18828 * Creates a new #GMainContext structure.
18830 * Returns: the new #GMainContext
18835 * g_main_context_pending:
18836 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
18838 * Checks if any sources have pending events for the given context.
18840 * Returns: %TRUE if events are pending.
18845 * g_main_context_pop_thread_default:
18846 * @context: (allow-none): a #GMainContext object, or %NULL
18848 * Pops @context off the thread-default context stack (verifying that
18849 * it was on the top of the stack).
18856 * g_main_context_prepare:
18857 * @context: a #GMainContext
18858 * @priority: location to store priority of highest priority
18859 * source already ready.
18861 * Prepares to poll sources within a main loop. The resulting information
18862 * for polling is determined by calling g_main_context_query ().
18864 * You must have successfully acquired the context with
18865 * g_main_context_acquire() before you may call this function.
18867 * Returns: %TRUE if some source is ready to be dispatched
18868 * prior to polling.
18873 * g_main_context_push_thread_default:
18874 * @context: (allow-none): a #GMainContext, or %NULL for the global default context
18876 * Acquires @context and sets it as the thread-default context for the
18877 * current thread. This will cause certain asynchronous operations
18878 * (such as most [gio][gio]-based I/O) which are
18879 * started in this thread to run under @context and deliver their
18880 * results to its main loop, rather than running under the global
18881 * default context in the main thread. Note that calling this function
18882 * changes the context returned by g_main_context_get_thread_default(),
18883 * not the one returned by g_main_context_default(), so it does not affect
18884 * the context used by functions like g_idle_add().
18886 * Normally you would call this function shortly after creating a new
18887 * thread, passing it a #GMainContext which will be run by a
18888 * #GMainLoop in that thread, to set a new default context for all
18889 * async operations in that thread. (In this case, you don't need to
18890 * ever call g_main_context_pop_thread_default().) In some cases
18891 * however, you may want to schedule a single operation in a
18892 * non-default context, or temporarily use a non-default context in
18893 * the main thread. In that case, you can wrap the call to the
18894 * asynchronous operation inside a
18895 * g_main_context_push_thread_default() /
18896 * g_main_context_pop_thread_default() pair, but it is up to you to
18897 * ensure that no other asynchronous operations accidentally get
18898 * started while the non-default context is active.
18900 * Beware that libraries that predate this function may not correctly
18901 * handle being used from a thread with a thread-default context. Eg,
18902 * see g_file_supports_thread_contexts().
18909 * g_main_context_query:
18910 * @context: a #GMainContext
18911 * @max_priority: maximum priority source to check
18912 * @timeout_: (out): location to store timeout to be used in polling
18913 * @fds: (out caller-allocates) (array length=n_fds): location to
18914 * store #GPollFD records that need to be polled.
18915 * @n_fds: length of @fds.
18917 * Determines information necessary to poll this main loop.
18919 * You must have successfully acquired the context with
18920 * g_main_context_acquire() before you may call this function.
18922 * Returns: the number of records actually stored in @fds,
18923 * or, if more than @n_fds records need to be stored, the number
18924 * of records that need to be stored.
18929 * g_main_context_ref:
18930 * @context: a #GMainContext
18932 * Increases the reference count on a #GMainContext object by one.
18934 * Returns: the @context that was passed in (since 2.6)
18939 * g_main_context_ref_thread_default:
18941 * Gets the thread-default #GMainContext for this thread, as with
18942 * g_main_context_get_thread_default(), but also adds a reference to
18943 * it with g_main_context_ref(). In addition, unlike
18944 * g_main_context_get_thread_default(), if the thread-default context
18945 * is the global default context, this will return that #GMainContext
18946 * (with a ref added to it) rather than returning %NULL.
18948 * Returns: (transfer full): the thread-default #GMainContext. Unref
18949 * with g_main_context_unref() when you are done with it.
18955 * g_main_context_release:
18956 * @context: a #GMainContext
18958 * Releases ownership of a context previously acquired by this thread
18959 * with g_main_context_acquire(). If the context was acquired multiple
18960 * times, the ownership will be released only when g_main_context_release()
18961 * is called as many times as it was acquired.
18966 * g_main_context_remove_poll:
18967 * @context: a #GMainContext
18968 * @fd: a #GPollFD descriptor previously added with g_main_context_add_poll()
18970 * Removes file descriptor from the set of file descriptors to be
18971 * polled for a particular context.
18976 * g_main_context_set_poll_func:
18977 * @context: a #GMainContext
18978 * @func: the function to call to poll all file descriptors
18980 * Sets the function to use to handle polling of file descriptors. It
18981 * will be used instead of the poll() system call
18982 * (or GLib's replacement function, which is used where
18983 * poll() isn't available).
18985 * This function could possibly be used to integrate the GLib event
18986 * loop with an external event loop.
18991 * g_main_context_unref:
18992 * @context: a #GMainContext
18994 * Decreases the reference count on a #GMainContext object by one. If
18995 * the result is zero, free the context and free all associated memory.
19000 * g_main_context_wait:
19001 * @context: a #GMainContext
19002 * @cond: a condition variable
19003 * @mutex: a mutex, currently held
19005 * Tries to become the owner of the specified context,
19006 * as with g_main_context_acquire(). But if another thread
19007 * is the owner, atomically drop @mutex and wait on @cond until
19008 * that owner releases ownership or until @cond is signaled, then
19009 * try again (once) to become the owner.
19011 * Returns: %TRUE if the operation succeeded, and
19012 * this thread is now the owner of @context.
19017 * g_main_context_wakeup:
19018 * @context: a #GMainContext
19020 * If @context is currently blocking in g_main_context_iteration()
19021 * waiting for a source to become ready, cause it to stop blocking
19022 * and return. Otherwise, cause the next invocation of
19023 * g_main_context_iteration() to return without blocking.
19025 * This API is useful for low-level control over #GMainContext; for
19026 * example, integrating it with main loop implementations such as
19029 * Another related use for this function is when implementing a main
19030 * loop with a termination condition, computed from multiple threads:
19032 * |[<!-- language="C" -->
19033 * #define NUM_TASKS 10
19034 * static volatile gint tasks_remaining = NUM_TASKS;
19037 * while (g_atomic_int_get (&tasks_remaining) != 0)
19038 * g_main_context_iteration (NULL, TRUE);
19041 * Then in a thread:
19042 * |[<!-- language="C" -->
19045 * if (g_atomic_int_dec_and_test (&tasks_remaining))
19046 * g_main_context_wakeup (NULL);
19052 * g_main_current_source:
19054 * Returns the currently firing source for this thread.
19056 * Returns: (transfer none): The currently firing source or %NULL.
19064 * Returns the depth of the stack of calls to
19065 * g_main_context_dispatch() on any #GMainContext in the current thread.
19066 * That is, when called from the toplevel, it gives 0. When
19067 * called from within a callback from g_main_context_iteration()
19068 * (or g_main_loop_run(), etc.) it returns 1. When called from within
19069 * a callback to a recursive call to g_main_context_iteration(),
19070 * it returns 2. And so forth.
19072 * This function is useful in a situation like the following:
19073 * Imagine an extremely simple "garbage collected" system.
19075 * |[<!-- language="C" -->
19076 * static GList *free_list;
19079 * allocate_memory (gsize size)
19081 * gpointer result = g_malloc (size);
19082 * free_list = g_list_prepend (free_list, result);
19087 * free_allocated_memory (void)
19090 * for (l = free_list; l; l = l->next);
19091 * g_free (l->data);
19092 * g_list_free (free_list);
19093 * free_list = NULL;
19100 * g_main_context_iteration (NULL, TRUE);
19101 * free_allocated_memory();
19105 * This works from an application, however, if you want to do the same
19106 * thing from a library, it gets more difficult, since you no longer
19107 * control the main loop. You might think you can simply use an idle
19108 * function to make the call to free_allocated_memory(), but that
19109 * doesn't work, since the idle function could be called from a
19110 * recursive callback. This can be fixed by using g_main_depth()
19112 * |[<!-- language="C" -->
19114 * allocate_memory (gsize size)
19116 * FreeListBlock *block = g_new (FreeListBlock, 1);
19117 * block->mem = g_malloc (size);
19118 * block->depth = g_main_depth ();
19119 * free_list = g_list_prepend (free_list, block);
19120 * return block->mem;
19124 * free_allocated_memory (void)
19128 * int depth = g_main_depth ();
19129 * for (l = free_list; l; );
19131 * GList *next = l->next;
19132 * FreeListBlock *block = l->data;
19133 * if (block->depth > depth)
19135 * g_free (block->mem);
19137 * free_list = g_list_delete_link (free_list, l);
19145 * There is a temptation to use g_main_depth() to solve
19146 * problems with reentrancy. For instance, while waiting for data
19147 * to be received from the network in response to a menu item,
19148 * the menu item might be selected again. It might seem that
19149 * one could make the menu item's callback return immediately
19150 * and do nothing if g_main_depth() returns a value greater than 1.
19151 * However, this should be avoided since the user then sees selecting
19152 * the menu item do nothing. Furthermore, you'll find yourself adding
19153 * these checks all over your code, since there are doubtless many,
19154 * many things that the user could do. Instead, you can use the
19155 * following techniques:
19157 * 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent
19158 * the user from interacting with elements while the main
19159 * loop is recursing.
19161 * 2. Avoid main loop recursion in situations where you can't handle
19162 * arbitrary callbacks. Instead, structure your code so that you
19163 * simply return to the main loop and then get called again when
19164 * there is more work to do.
19166 * Returns: The main loop recursion level in the current thread
19171 * g_main_loop_get_context:
19172 * @loop: a #GMainLoop.
19174 * Returns the #GMainContext of @loop.
19176 * Returns: (transfer none): the #GMainContext of @loop
19181 * g_main_loop_is_running:
19182 * @loop: a #GMainLoop.
19184 * Checks to see if the main loop is currently being run via g_main_loop_run().
19186 * Returns: %TRUE if the mainloop is currently being run.
19192 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used).
19193 * @is_running: set to %TRUE to indicate that the loop is running. This
19194 * is not very important since calling g_main_loop_run() will set this to
19197 * Creates a new #GMainLoop structure.
19199 * Returns: a new #GMainLoop.
19204 * g_main_loop_quit:
19205 * @loop: a #GMainLoop
19207 * Stops a #GMainLoop from running. Any calls to g_main_loop_run()
19208 * for the loop will return.
19210 * Note that sources that have already been dispatched when
19211 * g_main_loop_quit() is called will still be executed.
19217 * @loop: a #GMainLoop
19219 * Increases the reference count on a #GMainLoop object by one.
19227 * @loop: a #GMainLoop
19229 * Runs a main loop until g_main_loop_quit() is called on the loop.
19230 * If this is called for the thread of the loop's #GMainContext,
19231 * it will process events from the loop, otherwise it will
19237 * g_main_loop_unref:
19238 * @loop: a #GMainLoop
19240 * Decreases the reference count on a #GMainLoop object by one. If
19241 * the result is zero, free the loop and free all associated memory.
19247 * @n_bytes: the number of bytes to allocate
19249 * Allocates @n_bytes bytes of memory.
19250 * If @n_bytes is 0 it returns %NULL.
19252 * Returns: a pointer to the allocated memory
19258 * @n_bytes: the number of bytes to allocate
19260 * Allocates @n_bytes bytes of memory, initialized to 0's.
19261 * If @n_bytes is 0 it returns %NULL.
19263 * Returns: a pointer to the allocated memory
19269 * @n_blocks: the number of blocks to allocate
19270 * @n_block_bytes: the size of each block in bytes
19272 * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
19273 * but care is taken to detect possible overflow during multiplication.
19276 * Returns: a pointer to the allocated memory
19282 * @n_blocks: the number of blocks to allocate
19283 * @n_block_bytes: the size of each block in bytes
19285 * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
19286 * but care is taken to detect possible overflow during multiplication.
19289 * Returns: a pointer to the allocated memory
19294 * g_mapped_file_free:
19295 * @file: a #GMappedFile
19297 * This call existed before #GMappedFile had refcounting and is currently
19298 * exactly the same as g_mapped_file_unref().
19301 * Deprecated: 2.22: Use g_mapped_file_unref() instead.
19306 * g_mapped_file_get_bytes:
19307 * @file: a #GMappedFile
19309 * Creates a new #GBytes which references the data mapped from @file.
19310 * The mapped contents of the file must not be modified after creating this
19311 * bytes object, because a #GBytes should be immutable.
19313 * Returns: (transfer full): A newly allocated #GBytes referencing data
19320 * g_mapped_file_get_contents:
19321 * @file: a #GMappedFile
19323 * Returns the contents of a #GMappedFile.
19325 * Note that the contents may not be zero-terminated,
19326 * even if the #GMappedFile is backed by a text file.
19328 * If the file is empty then %NULL is returned.
19330 * Returns: the contents of @file, or %NULL.
19336 * g_mapped_file_get_length:
19337 * @file: a #GMappedFile
19339 * Returns the length of the contents of a #GMappedFile.
19341 * Returns: the length of the contents of @file.
19347 * g_mapped_file_new:
19348 * @filename: The path of the file to load, in the GLib filename encoding
19349 * @writable: whether the mapping should be writable
19350 * @error: return location for a #GError, or %NULL
19352 * Maps a file into memory. On UNIX, this is using the mmap() function.
19354 * If @writable is %TRUE, the mapped buffer may be modified, otherwise
19355 * it is an error to modify the mapped buffer. Modifications to the buffer
19356 * are not visible to other processes mapping the same file, and are not
19357 * written back to the file.
19359 * Note that modifications of the underlying file might affect the contents
19360 * of the #GMappedFile. Therefore, mapping should only be used if the file
19361 * will not be modified, or if all modifications of the file are done
19362 * atomically (e.g. using g_file_set_contents()).
19364 * If @filename is the name of an empty, regular file, the function
19365 * will successfully return an empty #GMappedFile. In other cases of
19366 * size 0 (e.g. device files such as /dev/null), @error will be set
19367 * to the #GFileError value #G_FILE_ERROR_INVAL.
19369 * Returns: a newly allocated #GMappedFile which must be unref'd
19370 * with g_mapped_file_unref(), or %NULL if the mapping failed.
19376 * g_mapped_file_new_from_fd:
19377 * @fd: The file descriptor of the file to load
19378 * @writable: whether the mapping should be writable
19379 * @error: return location for a #GError, or %NULL
19381 * Maps a file into memory. On UNIX, this is using the mmap() function.
19383 * If @writable is %TRUE, the mapped buffer may be modified, otherwise
19384 * it is an error to modify the mapped buffer. Modifications to the buffer
19385 * are not visible to other processes mapping the same file, and are not
19386 * written back to the file.
19388 * Note that modifications of the underlying file might affect the contents
19389 * of the #GMappedFile. Therefore, mapping should only be used if the file
19390 * will not be modified, or if all modifications of the file are done
19391 * atomically (e.g. using g_file_set_contents()).
19393 * Returns: a newly allocated #GMappedFile which must be unref'd
19394 * with g_mapped_file_unref(), or %NULL if the mapping failed.
19400 * g_mapped_file_ref:
19401 * @file: a #GMappedFile
19403 * Increments the reference count of @file by one. It is safe to call
19404 * this function from any thread.
19406 * Returns: the passed in #GMappedFile.
19412 * g_mapped_file_unref:
19413 * @file: a #GMappedFile
19415 * Decrements the reference count of @file by one. If the reference count
19416 * drops to 0, unmaps the buffer of @file and frees it.
19418 * It is safe to call this function from any thread.
19425 * g_markup_collect_attributes:
19426 * @element_name: the current tag name
19427 * @attribute_names: the attribute names
19428 * @attribute_values: the attribute values
19429 * @error: a pointer to a #GError or %NULL
19430 * @first_type: the #GMarkupCollectType of the first attribute
19431 * @first_attr: the name of the first attribute
19432 * @...: a pointer to the storage location of the first attribute
19433 * (or %NULL), followed by more types names and pointers, ending
19434 * with %G_MARKUP_COLLECT_INVALID
19436 * Collects the attributes of the element from the data passed to the
19437 * #GMarkupParser start_element function, dealing with common error
19438 * conditions and supporting boolean values.
19440 * This utility function is not required to write a parser but can save
19443 * The @element_name, @attribute_names, @attribute_values and @error
19444 * parameters passed to the start_element callback should be passed
19445 * unmodified to this function.
19447 * Following these arguments is a list of "supported" attributes to collect.
19448 * It is an error to specify multiple attributes with the same name. If any
19449 * attribute not in the list appears in the @attribute_names array then an
19450 * unknown attribute error will result.
19452 * The #GMarkupCollectType field allows specifying the type of collection
19453 * to perform and if a given attribute must appear or is optional.
19455 * The attribute name is simply the name of the attribute to collect.
19457 * The pointer should be of the appropriate type (see the descriptions
19458 * under #GMarkupCollectType) and may be %NULL in case a particular
19459 * attribute is to be allowed but ignored.
19461 * This function deals with issuing errors for missing attributes
19462 * (of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes
19463 * (of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate
19464 * attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well
19465 * as parse errors for boolean-valued attributes (again of type
19466 * %G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE
19467 * will be returned and @error will be set as appropriate.
19469 * Returns: %TRUE if successful
19475 * g_markup_escape_text:
19476 * @text: some valid UTF-8 text
19477 * @length: length of @text in bytes, or -1 if the text is nul-terminated
19479 * Escapes text so that the markup parser will parse it verbatim.
19480 * Less than, greater than, ampersand, etc. are replaced with the
19481 * corresponding entities. This function would typically be used
19482 * when writing out a file to be parsed with the markup parser.
19484 * Note that this function doesn't protect whitespace and line endings
19485 * from being processed according to the XML rules for normalization
19486 * of line endings and attribute values.
19488 * Note also that this function will produce character references in
19489 * the range of  ...  for all control sequences
19490 * except for tabstop, newline and carriage return. The character
19491 * references in this range are not valid XML 1.0, but they are
19492 * valid XML 1.1 and will be accepted by the GMarkup parser.
19494 * Returns: a newly allocated string with the escaped text
19499 * g_markup_parse_context_end_parse:
19500 * @context: a #GMarkupParseContext
19501 * @error: return location for a #GError
19503 * Signals to the #GMarkupParseContext that all data has been
19504 * fed into the parse context with g_markup_parse_context_parse().
19506 * This function reports an error if the document isn't complete,
19507 * for example if elements are still open.
19509 * Returns: %TRUE on success, %FALSE if an error was set
19514 * g_markup_parse_context_free:
19515 * @context: a #GMarkupParseContext
19517 * Frees a #GMarkupParseContext.
19519 * This function can't be called from inside one of the
19520 * #GMarkupParser functions or while a subparser is pushed.
19525 * g_markup_parse_context_get_element:
19526 * @context: a #GMarkupParseContext
19528 * Retrieves the name of the currently open element.
19530 * If called from the start_element or end_element handlers this will
19531 * give the element_name as passed to those functions. For the parent
19532 * elements, see g_markup_parse_context_get_element_stack().
19534 * Returns: the name of the currently open element, or %NULL
19540 * g_markup_parse_context_get_element_stack:
19541 * @context: a #GMarkupParseContext
19543 * Retrieves the element stack from the internal state of the parser.
19545 * The returned #GSList is a list of strings where the first item is
19546 * the currently open tag (as would be returned by
19547 * g_markup_parse_context_get_element()) and the next item is its
19548 * immediate parent.
19550 * This function is intended to be used in the start_element and
19551 * end_element handlers where g_markup_parse_context_get_element()
19552 * would merely return the name of the element that is being
19555 * Returns: the element stack, which must not be modified
19561 * g_markup_parse_context_get_position:
19562 * @context: a #GMarkupParseContext
19563 * @line_number: (allow-none): return location for a line number, or %NULL
19564 * @char_number: (allow-none): return location for a char-on-line number, or %NULL
19566 * Retrieves the current line number and the number of the character on
19567 * that line. Intended for use in error messages; there are no strict
19568 * semantics for what constitutes the "current" line number other than
19569 * "the best number we could come up with for error messages."
19574 * g_markup_parse_context_get_user_data:
19575 * @context: a #GMarkupParseContext
19577 * Returns the user_data associated with @context.
19579 * This will either be the user_data that was provided to
19580 * g_markup_parse_context_new() or to the most recent call
19581 * of g_markup_parse_context_push().
19583 * Returns: the provided user_data. The returned data belongs to
19584 * the markup context and will be freed when
19585 * g_markup_parse_context_free() is called.
19591 * g_markup_parse_context_new:
19592 * @parser: a #GMarkupParser
19593 * @flags: one or more #GMarkupParseFlags
19594 * @user_data: user data to pass to #GMarkupParser functions
19595 * @user_data_dnotify: user data destroy notifier called when
19596 * the parse context is freed
19598 * Creates a new parse context. A parse context is used to parse
19599 * marked-up documents. You can feed any number of documents into
19600 * a context, as long as no errors occur; once an error occurs,
19601 * the parse context can't continue to parse text (you have to
19602 * free it and create a new parse context).
19604 * Returns: a new #GMarkupParseContext
19609 * g_markup_parse_context_parse:
19610 * @context: a #GMarkupParseContext
19611 * @text: chunk of text to parse
19612 * @text_len: length of @text in bytes
19613 * @error: return location for a #GError
19615 * Feed some data to the #GMarkupParseContext.
19617 * The data need not be valid UTF-8; an error will be signaled if
19618 * it's invalid. The data need not be an entire document; you can
19619 * feed a document into the parser incrementally, via multiple calls
19620 * to this function. Typically, as you receive data from a network
19621 * connection or file, you feed each received chunk of data into this
19622 * function, aborting the process if an error occurs. Once an error
19623 * is reported, no further data may be fed to the #GMarkupParseContext;
19624 * all errors are fatal.
19626 * Returns: %FALSE if an error occurred, %TRUE on success
19631 * g_markup_parse_context_pop:
19632 * @context: a #GMarkupParseContext
19634 * Completes the process of a temporary sub-parser redirection.
19636 * This function exists to collect the user_data allocated by a
19637 * matching call to g_markup_parse_context_push(). It must be called
19638 * in the end_element handler corresponding to the start_element
19639 * handler during which g_markup_parse_context_push() was called.
19640 * You must not call this function from the error callback -- the
19641 * @user_data is provided directly to the callback in that case.
19643 * This function is not intended to be directly called by users
19644 * interested in invoking subparsers. Instead, it is intended to
19645 * be used by the subparsers themselves to implement a higher-level
19648 * Returns: the user data passed to g_markup_parse_context_push()
19654 * g_markup_parse_context_push:
19655 * @context: a #GMarkupParseContext
19656 * @parser: a #GMarkupParser
19657 * @user_data: user data to pass to #GMarkupParser functions
19659 * Temporarily redirects markup data to a sub-parser.
19661 * This function may only be called from the start_element handler of
19662 * a #GMarkupParser. It must be matched with a corresponding call to
19663 * g_markup_parse_context_pop() in the matching end_element handler
19664 * (except in the case that the parser aborts due to an error).
19666 * All tags, text and other data between the matching tags is
19667 * redirected to the subparser given by @parser. @user_data is used
19668 * as the user_data for that parser. @user_data is also passed to the
19669 * error callback in the event that an error occurs. This includes
19670 * errors that occur in subparsers of the subparser.
19672 * The end tag matching the start tag for which this call was made is
19673 * handled by the previous parser (which is given its own user_data)
19674 * which is why g_markup_parse_context_pop() is provided to allow "one
19675 * last access" to the @user_data provided to this function. In the
19676 * case of error, the @user_data provided here is passed directly to
19677 * the error callback of the subparser and g_markup_parse_context_pop()
19678 * should not be called. In either case, if @user_data was allocated
19679 * then it ought to be freed from both of these locations.
19681 * This function is not intended to be directly called by users
19682 * interested in invoking subparsers. Instead, it is intended to be
19683 * used by the subparsers themselves to implement a higher-level
19686 * As an example, see the following implementation of a simple
19687 * parser that counts the number of tags encountered.
19689 * |[<!-- language="C" -->
19696 * counter_start_element (GMarkupParseContext *context,
19697 * const gchar *element_name,
19698 * const gchar **attribute_names,
19699 * const gchar **attribute_values,
19700 * gpointer user_data,
19703 * CounterData *data = user_data;
19705 * data->tag_count++;
19709 * counter_error (GMarkupParseContext *context,
19711 * gpointer user_data)
19713 * CounterData *data = user_data;
19715 * g_slice_free (CounterData, data);
19718 * static GMarkupParser counter_subparser =
19720 * counter_start_element,
19728 * In order to allow this parser to be easily used as a subparser, the
19729 * following interface is provided:
19731 * |[<!-- language="C" -->
19733 * start_counting (GMarkupParseContext *context)
19735 * CounterData *data = g_slice_new (CounterData);
19737 * data->tag_count = 0;
19738 * g_markup_parse_context_push (context, &counter_subparser, data);
19742 * end_counting (GMarkupParseContext *context)
19744 * CounterData *data = g_markup_parse_context_pop (context);
19747 * result = data->tag_count;
19748 * g_slice_free (CounterData, data);
19754 * The subparser would then be used as follows:
19756 * |[<!-- language="C" -->
19757 * static void start_element (context, element_name, ...)
19759 * if (strcmp (element_name, "count-these") == 0)
19760 * start_counting (context);
19762 * // else, handle other tags...
19765 * static void end_element (context, element_name, ...)
19767 * if (strcmp (element_name, "count-these") == 0)
19768 * g_print ("Counted %d tags\n", end_counting (context));
19770 * // else, handle other tags...
19779 * g_markup_parse_context_ref:
19780 * @context: a #GMarkupParseContext
19782 * Increases the reference count of @context.
19784 * Returns: the same @context
19790 * g_markup_parse_context_unref:
19791 * @context: a #GMarkupParseContext
19793 * Decreases the reference count of @context. When its reference count
19794 * drops to 0, it is freed.
19801 * g_markup_printf_escaped:
19802 * @format: printf() style format string
19803 * @...: the arguments to insert in the format string
19805 * Formats arguments according to @format, escaping
19806 * all string and character arguments in the fashion
19807 * of g_markup_escape_text(). This is useful when you
19808 * want to insert literal strings into XML-style markup
19809 * output, without having to worry that the strings
19810 * might themselves contain markup.
19812 * |[<!-- language="C" -->
19813 * const char *store = "Fortnum & Mason";
19814 * const char *item = "Tea";
19817 * output = g_markup_printf_escaped ("<purchase>"
19818 * "<store>%s</store>"
19819 * "<item>%s</item>"
19824 * Returns: newly allocated result from formatting
19825 * operation. Free with g_free().
19831 * g_markup_vprintf_escaped:
19832 * @format: printf() style format string
19833 * @args: variable argument list, similar to vprintf()
19835 * Formats the data in @args according to @format, escaping
19836 * all string and character arguments in the fashion
19837 * of g_markup_escape_text(). See g_markup_printf_escaped().
19839 * Returns: newly allocated result from formatting
19840 * operation. Free with g_free().
19846 * g_match_info_expand_references:
19847 * @match_info: (allow-none): a #GMatchInfo or %NULL
19848 * @string_to_expand: the string to expand
19849 * @error: location to store the error occurring, or %NULL to ignore errors
19851 * Returns a new string containing the text in @string_to_expand with
19852 * references and escape sequences expanded. References refer to the last
19853 * match done with @string against @regex and have the same syntax used by
19854 * g_regex_replace().
19856 * The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was
19857 * passed to g_regex_new().
19859 * The backreferences are extracted from the string passed to the match
19860 * function, so you cannot call this function after freeing the string.
19862 * @match_info may be %NULL in which case @string_to_expand must not
19863 * contain references. For instance "foo\n" does not refer to an actual
19864 * pattern and '\n' merely will be replaced with \n character,
19865 * while to expand "\0" (whole match) one needs the result of a match.
19866 * Use g_regex_check_replacement() to find out whether @string_to_expand
19867 * contains references.
19869 * Returns: (allow-none): the expanded string, or %NULL if an error occurred
19875 * g_match_info_fetch:
19876 * @match_info: #GMatchInfo structure
19877 * @match_num: number of the sub expression
19879 * Retrieves the text matching the @match_num'th capturing
19880 * parentheses. 0 is the full text of the match, 1 is the first paren
19881 * set, 2 the second, and so on.
19883 * If @match_num is a valid sub pattern but it didn't match anything
19884 * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
19885 * string is returned.
19887 * If the match was obtained using the DFA algorithm, that is using
19888 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
19889 * string is not that of a set of parentheses but that of a matched
19890 * substring. Substrings are matched in reverse order of length, so
19891 * 0 is the longest match.
19893 * The string is fetched from the string passed to the match function,
19894 * so you cannot call this function after freeing the string.
19896 * Returns: (allow-none): The matched substring, or %NULL if an error
19897 * occurred. You have to free the string yourself
19903 * g_match_info_fetch_all:
19904 * @match_info: a #GMatchInfo structure
19906 * Bundles up pointers to each of the matching substrings from a match
19907 * and stores them in an array of gchar pointers. The first element in
19908 * the returned array is the match number 0, i.e. the entire matched
19911 * If a sub pattern didn't match anything (e.g. sub pattern 1, matching
19912 * "b" against "(a)?b") then an empty string is inserted.
19914 * If the last match was obtained using the DFA algorithm, that is using
19915 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
19916 * strings are not that matched by sets of parentheses but that of the
19917 * matched substring. Substrings are matched in reverse order of length,
19918 * so the first one is the longest match.
19920 * The strings are fetched from the string passed to the match function,
19921 * so you cannot call this function after freeing the string.
19923 * Returns: (transfer full): a %NULL-terminated array of gchar *
19924 * pointers. It must be freed using g_strfreev(). If the previous
19925 * match failed %NULL is returned
19931 * g_match_info_fetch_named:
19932 * @match_info: #GMatchInfo structure
19933 * @name: name of the subexpression
19935 * Retrieves the text matching the capturing parentheses named @name.
19937 * If @name is a valid sub pattern name but it didn't match anything
19938 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
19939 * then an empty string is returned.
19941 * The string is fetched from the string passed to the match function,
19942 * so you cannot call this function after freeing the string.
19944 * Returns: (allow-none): The matched substring, or %NULL if an error
19945 * occurred. You have to free the string yourself
19951 * g_match_info_fetch_named_pos:
19952 * @match_info: #GMatchInfo structure
19953 * @name: name of the subexpression
19954 * @start_pos: (out) (allow-none): pointer to location where to store
19955 * the start position, or %NULL
19956 * @end_pos: (out) (allow-none): pointer to location where to store
19957 * the end position, or %NULL
19959 * Retrieves the position in bytes of the capturing parentheses named @name.
19961 * If @name is a valid sub pattern name but it didn't match anything
19962 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
19963 * then @start_pos and @end_pos are set to -1 and %TRUE is returned.
19965 * Returns: %TRUE if the position was fetched, %FALSE otherwise.
19966 * If the position cannot be fetched, @start_pos and @end_pos
19967 * are left unchanged.
19973 * g_match_info_fetch_pos:
19974 * @match_info: #GMatchInfo structure
19975 * @match_num: number of the sub expression
19976 * @start_pos: (out) (allow-none): pointer to location where to store
19977 * the start position, or %NULL
19978 * @end_pos: (out) (allow-none): pointer to location where to store
19979 * the end position, or %NULL
19981 * Retrieves the position in bytes of the @match_num'th capturing
19982 * parentheses. 0 is the full text of the match, 1 is the first
19983 * paren set, 2 the second, and so on.
19985 * If @match_num is a valid sub pattern but it didn't match anything
19986 * (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos
19987 * and @end_pos are set to -1 and %TRUE is returned.
19989 * If the match was obtained using the DFA algorithm, that is using
19990 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
19991 * position is not that of a set of parentheses but that of a matched
19992 * substring. Substrings are matched in reverse order of length, so
19993 * 0 is the longest match.
19995 * Returns: %TRUE if the position was fetched, %FALSE otherwise. If
19996 * the position cannot be fetched, @start_pos and @end_pos are left
20003 * g_match_info_free:
20004 * @match_info: (allow-none): a #GMatchInfo, or %NULL
20006 * If @match_info is not %NULL, calls g_match_info_unref(); otherwise does
20014 * g_match_info_get_match_count:
20015 * @match_info: a #GMatchInfo structure
20017 * Retrieves the number of matched substrings (including substring 0,
20018 * that is the whole matched text), so 1 is returned if the pattern
20019 * has no substrings in it and 0 is returned if the match failed.
20021 * If the last match was obtained using the DFA algorithm, that is
20022 * using g_regex_match_all() or g_regex_match_all_full(), the retrieved
20023 * count is not that of the number of capturing parentheses but that of
20024 * the number of matched substrings.
20026 * Returns: Number of matched substrings, or -1 if an error occurred
20032 * g_match_info_get_regex:
20033 * @match_info: a #GMatchInfo
20035 * Returns #GRegex object used in @match_info. It belongs to Glib
20036 * and must not be freed. Use g_regex_ref() if you need to keep it
20037 * after you free @match_info object.
20039 * Returns: #GRegex object used in @match_info
20045 * g_match_info_get_string:
20046 * @match_info: a #GMatchInfo
20048 * Returns the string searched with @match_info. This is the
20049 * string passed to g_regex_match() or g_regex_replace() so
20050 * you may not free it before calling this function.
20052 * Returns: the string searched with @match_info
20058 * g_match_info_is_partial_match:
20059 * @match_info: a #GMatchInfo structure
20061 * Usually if the string passed to g_regex_match*() matches as far as
20062 * it goes, but is too short to match the entire pattern, %FALSE is
20063 * returned. There are circumstances where it might be helpful to
20064 * distinguish this case from other cases in which there is no match.
20066 * Consider, for example, an application where a human is required to
20067 * type in data for a field with specific formatting requirements. An
20068 * example might be a date in the form ddmmmyy, defined by the pattern
20069 * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
20070 * If the application sees the user’s keystrokes one by one, and can
20071 * check that what has been typed so far is potentially valid, it is
20072 * able to raise an error as soon as a mistake is made.
20074 * GRegex supports the concept of partial matching by means of the
20075 * #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags.
20076 * When they are used, the return code for
20077 * g_regex_match() or g_regex_match_full() is, as usual, %TRUE
20078 * for a complete match, %FALSE otherwise. But, when these functions
20079 * return %FALSE, you can check if the match was partial calling
20080 * g_match_info_is_partial_match().
20082 * The difference between #G_REGEX_MATCH_PARTIAL_SOFT and
20083 * #G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered
20084 * with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a
20085 * possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching
20086 * stops at the partial match.
20087 * When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD
20088 * are set, the latter takes precedence.
20090 * There were formerly some restrictions on the pattern for partial matching.
20091 * The restrictions no longer apply.
20093 * See pcrepartial(3) for more information on partial matching.
20095 * Returns: %TRUE if the match was partial, %FALSE otherwise
20101 * g_match_info_matches:
20102 * @match_info: a #GMatchInfo structure
20104 * Returns whether the previous match operation succeeded.
20106 * Returns: %TRUE if the previous match operation succeeded,
20113 * g_match_info_next:
20114 * @match_info: a #GMatchInfo structure
20115 * @error: location to store the error occurring, or %NULL to ignore errors
20117 * Scans for the next match using the same parameters of the previous
20118 * call to g_regex_match_full() or g_regex_match() that returned
20121 * The match is done on the string passed to the match function, so you
20122 * cannot free it before calling this function.
20124 * Returns: %TRUE is the string matched, %FALSE otherwise
20130 * g_match_info_ref:
20131 * @match_info: a #GMatchInfo
20133 * Increases reference count of @match_info by 1.
20135 * Returns: @match_info
20141 * g_match_info_unref:
20142 * @match_info: a #GMatchInfo
20144 * Decreases reference count of @match_info by 1. When reference count drops
20145 * to zero, it frees all the memory associated with the match_info structure.
20152 * g_mem_gc_friendly:
20154 * This variable is %TRUE if the `G_DEBUG` environment variable
20155 * includes the key `gc-friendly`.
20160 * g_mem_is_system_malloc:
20162 * Checks whether the allocator used by g_malloc() is the system's
20163 * malloc implementation. If it returns %TRUE memory allocated with
20164 * malloc() can be used interchangeable with memory allocated using g_malloc().
20165 * This function is useful for avoiding an extra copy of allocated memory returned
20166 * by a non-GLib-based API.
20168 * A different allocator can be set using g_mem_set_vtable().
20170 * Returns: if %TRUE, malloc() and g_malloc() can be mixed.
20177 * Outputs a summary of memory usage.
20179 * It outputs the frequency of allocations of different sizes,
20180 * the total number of bytes which have been allocated,
20181 * the total number of bytes which have been freed,
20182 * and the difference between the previous two values, i.e. the number of bytes
20185 * Note that this function will not output anything unless you have
20186 * previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
20191 * g_mem_set_vtable:
20192 * @vtable: table of memory allocation routines.
20194 * Sets the #GMemVTable to use for memory allocation. You can use this
20195 * to provide custom memory allocation routines.
20197 * The @vtable only needs to provide malloc(), realloc(), and free()
20198 * functions; GLib can provide default implementations of the others.
20199 * The malloc() and realloc() implementations should return %NULL on
20200 * failure, GLib will handle error-checking for you. @vtable is copied,
20201 * so need not persist after this function has been called.
20203 * Note that this function must be called before using any other GLib
20210 * @mem: the memory to copy.
20211 * @byte_size: the number of bytes to copy.
20213 * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
20214 * from @mem. If @mem is %NULL it returns %NULL.
20216 * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
20223 * @dest: the destination address to copy the bytes to.
20224 * @src: the source address to copy the bytes from.
20225 * @len: the number of bytes to copy.
20227 * Copies a block of memory @len bytes long, from @src to @dest.
20228 * The source and destination areas may overlap.
20230 * Deprecated: 2.40: Just use memmove().
20236 * @...: format string, followed by parameters to insert
20237 * into the format string (as with printf())
20239 * A convenience function/macro to log a normal message.
20241 * If g_log_default_handler() is used as the log handler function, a new-line
20242 * character will automatically be appended to @..., and need not be entered
20249 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
20250 * @mode: permissions to use for the newly created directory
20252 * A wrapper for the POSIX mkdir() function. The mkdir() function
20253 * attempts to create a directory with the given name and permissions.
20254 * The mode argument is ignored on Windows.
20256 * See your C library manual for more details about mkdir().
20258 * Returns: 0 if the directory was successfully created, -1 if an error
20265 * g_mkdir_with_parents:
20266 * @pathname: a pathname in the GLib file name encoding
20267 * @mode: permissions to use for newly created directories
20269 * Create a directory if it doesn't already exist. Create intermediate
20270 * parent directories as needed, too.
20272 * Returns: 0 if the directory already exists, or was successfully
20273 * created. Returns -1 if an error occurred, with errno set.
20280 * @tmpl: (type filename): template directory name
20282 * Creates a temporary directory. See the mkdtemp() documentation
20283 * on most UNIX-like systems.
20285 * The parameter is a string that should follow the rules for
20286 * mkdtemp() templates, i.e. contain the string "XXXXXX".
20287 * g_mkdtemp() is slightly more flexible than mkdtemp() in that the
20288 * sequence does not have to occur at the very end of the template
20289 * and you can pass a @mode and additional @flags. The X string will
20290 * be modified to form the name of a directory that didn't exist.
20291 * The string should be in the GLib file name encoding. Most importantly,
20292 * on Windows it should be in UTF-8.
20294 * Returns: A pointer to @tmpl, which has been modified
20295 * to hold the directory name. In case of errors, %NULL is
20296 * returned and %errno will be set.
20303 * @tmpl: (type filename): template directory name
20304 * @mode: permissions to create the temporary directory with
20306 * Creates a temporary directory. See the mkdtemp() documentation
20307 * on most UNIX-like systems.
20309 * The parameter is a string that should follow the rules for
20310 * mkdtemp() templates, i.e. contain the string "XXXXXX".
20311 * g_mkdtemp() is slightly more flexible than mkdtemp() in that the
20312 * sequence does not have to occur at the very end of the template
20313 * and you can pass a @mode. The X string will be modified to form
20314 * the name of a directory that didn't exist. The string should be
20315 * in the GLib file name encoding. Most importantly, on Windows it
20316 * should be in UTF-8.
20318 * Returns: A pointer to @tmpl, which has been modified
20319 * to hold the directory name. In case of errors, %NULL is
20320 * returned, and %errno will be set.
20327 * @tmpl: (type filename): template filename
20329 * Opens a temporary file. See the mkstemp() documentation
20330 * on most UNIX-like systems.
20332 * The parameter is a string that should follow the rules for
20333 * mkstemp() templates, i.e. contain the string "XXXXXX".
20334 * g_mkstemp() is slightly more flexible than mkstemp() in that the
20335 * sequence does not have to occur at the very end of the template.
20336 * The X string will be modified to form the name of a file that
20337 * didn't exist. The string should be in the GLib file name encoding.
20338 * Most importantly, on Windows it should be in UTF-8.
20340 * Returns: A file handle (as from open()) to the file
20341 * opened for reading and writing. The file is opened in binary
20342 * mode on platforms where there is a difference. The file handle
20343 * should be closed with close(). In case of errors, -1 is
20344 * returned and %errno will be set.
20350 * @tmpl: (type filename): template filename
20351 * @flags: flags to pass to an open() call in addition to O_EXCL
20352 * and O_CREAT, which are passed automatically
20353 * @mode: permissions to create the temporary file with
20355 * Opens a temporary file. See the mkstemp() documentation
20356 * on most UNIX-like systems.
20358 * The parameter is a string that should follow the rules for
20359 * mkstemp() templates, i.e. contain the string "XXXXXX".
20360 * g_mkstemp_full() is slightly more flexible than mkstemp()
20361 * in that the sequence does not have to occur at the very end of the
20362 * template and you can pass a @mode and additional @flags. The X
20363 * string will be modified to form the name of a file that didn't exist.
20364 * The string should be in the GLib file name encoding. Most importantly,
20365 * on Windows it should be in UTF-8.
20367 * Returns: A file handle (as from open()) to the file
20368 * opened for reading and writing. The file handle should be
20369 * closed with close(). In case of errors, -1 is returned
20370 * and %errno will be set.
20377 * @mutex: an initialized #GMutex
20379 * Frees the resources allocated to a mutex with g_mutex_init().
20381 * This function should not be used with a #GMutex that has been
20382 * statically allocated.
20384 * Calling g_mutex_clear() on a locked mutex leads to undefined
20393 * @mutex: an uninitialized #GMutex
20395 * Initializes a #GMutex so that it can be used.
20397 * This function is useful to initialize a mutex that has been
20398 * allocated on the stack, or as part of a larger structure.
20399 * It is not necessary to initialize a mutex that has been
20400 * statically allocated.
20402 * |[<!-- language="C" -->
20410 * b = g_new (Blob, 1);
20411 * g_mutex_init (&b->m);
20414 * To undo the effect of g_mutex_init() when a mutex is no longer
20415 * needed, use g_mutex_clear().
20417 * Calling g_mutex_init() on an already initialized #GMutex leads
20418 * to undefined behaviour.
20426 * @mutex: a #GMutex
20428 * Locks @mutex. If @mutex is already locked by another thread, the
20429 * current thread will block until @mutex is unlocked by the other
20432 * #GMutex is neither guaranteed to be recursive nor to be
20433 * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
20434 * already been locked by the same thread results in undefined behaviour
20435 * (including but not limited to deadlocks).
20441 * @mutex: a #GMutex
20443 * Tries to lock @mutex. If @mutex is already locked by another thread,
20444 * it immediately returns %FALSE. Otherwise it locks @mutex and returns
20447 * #GMutex is neither guaranteed to be recursive nor to be
20448 * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
20449 * already been locked by the same thread results in undefined behaviour
20450 * (including but not limited to deadlocks or arbitrary return values).
20452 * Returns: %TRUE if @mutex could be locked
20458 * @mutex: a #GMutex
20460 * Unlocks @mutex. If another thread is blocked in a g_mutex_lock()
20461 * call for @mutex, it will become unblocked and can lock @mutex itself.
20463 * Calling g_mutex_unlock() on a mutex that is not locked by the
20464 * current thread leads to undefined behaviour.
20469 * g_node_child_index:
20471 * @data: the data to find
20473 * Gets the position of the first child of a #GNode
20474 * which contains the given data.
20476 * Returns: the index of the child of @node which contains
20477 * @data, or -1 if the data is not found
20482 * g_node_child_position:
20484 * @child: a child of @node
20486 * Gets the position of a #GNode with respect to its siblings.
20487 * @child must be a child of @node. The first child is numbered 0,
20488 * the second 1, and so on.
20490 * Returns: the position of @child with respect to its siblings
20495 * g_node_children_foreach:
20497 * @flags: which types of children are to be visited, one of
20498 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
20499 * @func: the function to call for each visited node
20500 * @data: user data to pass to the function
20502 * Calls a function for each of the children of a #GNode.
20503 * Note that it doesn't descend beneath the child nodes.
20511 * Recursively copies a #GNode (but does not deep-copy the data inside the
20512 * nodes, see g_node_copy_deep() if you need that).
20514 * Returns: a new #GNode containing the same data pointers
20519 * g_node_copy_deep:
20521 * @copy_func: the function which is called to copy the data inside each node,
20522 * or %NULL to use the original data.
20523 * @data: data to pass to @copy_func
20525 * Recursively copies a #GNode and its data.
20527 * Returns: a new #GNode containing copies of the data in @node.
20536 * Gets the depth of a #GNode.
20538 * If @node is %NULL the depth is 0. The root node has a depth of 1.
20539 * For the children of the root node the depth is 2. And so on.
20541 * Returns: the depth of the #GNode
20547 * @root: the root of the tree/subtree to destroy
20549 * Removes @root and its children from the tree, freeing any memory
20556 * @root: the root #GNode of the tree to search
20557 * @order: the order in which nodes are visited - %G_IN_ORDER,
20558 * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER
20559 * @flags: which types of children are to be searched, one of
20560 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
20561 * @data: the data to find
20563 * Finds a #GNode in a tree.
20565 * Returns: the found #GNode, or %NULL if the data is not found
20570 * g_node_find_child:
20572 * @flags: which types of children are to be searched, one of
20573 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
20574 * @data: the data to find
20576 * Finds the first child of a #GNode with the given data.
20578 * Returns: the found child #GNode, or %NULL if the data is not found
20583 * g_node_first_sibling:
20586 * Gets the first sibling of a #GNode.
20587 * This could possibly be the node itself.
20589 * Returns: the first sibling of @node
20597 * Gets the root of a tree.
20599 * Returns: the root of the tree
20605 * @parent: the #GNode to place @node under
20606 * @position: the position to place @node at, with respect to its siblings
20607 * If position is -1, @node is inserted as the last child of @parent
20608 * @node: the #GNode to insert
20610 * Inserts a #GNode beneath the parent at the given position.
20612 * Returns: the inserted #GNode
20617 * g_node_insert_after:
20618 * @parent: the #GNode to place @node under
20619 * @sibling: the sibling #GNode to place @node after.
20620 * If sibling is %NULL, the node is inserted as the first child of @parent.
20621 * @node: the #GNode to insert
20623 * Inserts a #GNode beneath the parent after the given sibling.
20625 * Returns: the inserted #GNode
20630 * g_node_insert_before:
20631 * @parent: the #GNode to place @node under
20632 * @sibling: the sibling #GNode to place @node before.
20633 * If sibling is %NULL, the node is inserted as the last child of @parent.
20634 * @node: the #GNode to insert
20636 * Inserts a #GNode beneath the parent before the given sibling.
20638 * Returns: the inserted #GNode
20643 * g_node_is_ancestor:
20645 * @descendant: a #GNode
20647 * Returns %TRUE if @node is an ancestor of @descendant.
20648 * This is true if node is the parent of @descendant,
20649 * or if node is the grandparent of @descendant etc.
20651 * Returns: %TRUE if @node is an ancestor of @descendant
20656 * g_node_last_child:
20657 * @node: a #GNode (must not be %NULL)
20659 * Gets the last child of a #GNode.
20661 * Returns: the last child of @node, or %NULL if @node has no children
20666 * g_node_last_sibling:
20669 * Gets the last sibling of a #GNode.
20670 * This could possibly be the node itself.
20672 * Returns: the last sibling of @node
20677 * g_node_max_height:
20680 * Gets the maximum height of all branches beneath a #GNode.
20681 * This is the maximum distance from the #GNode to all leaf nodes.
20683 * If @root is %NULL, 0 is returned. If @root has no children,
20684 * 1 is returned. If @root has children, 2 is returned. And so on.
20686 * Returns: the maximum height of the tree beneath @root
20691 * g_node_n_children:
20694 * Gets the number of children of a #GNode.
20696 * Returns: the number of children of @node
20703 * @flags: which types of children are to be counted, one of
20704 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
20706 * Gets the number of nodes in a tree.
20708 * Returns: the number of nodes in the tree
20714 * @data: the data of the new node
20716 * Creates a new #GNode containing the given data.
20717 * Used to create the first node in a tree.
20719 * Returns: a new #GNode
20724 * g_node_nth_child:
20726 * @n: the index of the desired child
20728 * Gets a child of a #GNode, using the given index.
20729 * The first child is at index 0. If the index is
20730 * too big, %NULL is returned.
20732 * Returns: the child of @node at index @n
20738 * @parent: the #GNode to place the new #GNode under
20739 * @node: the #GNode to insert
20741 * Inserts a #GNode as the first child of the given parent.
20743 * Returns: the inserted #GNode
20748 * g_node_reverse_children:
20751 * Reverses the order of the children of a #GNode.
20752 * (It doesn't change the order of the grandchildren.)
20758 * @root: the root #GNode of the tree to traverse
20759 * @order: the order in which nodes are visited - %G_IN_ORDER,
20760 * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER.
20761 * @flags: which types of children are to be visited, one of
20762 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
20763 * @max_depth: the maximum depth of the traversal. Nodes below this
20764 * depth will not be visited. If max_depth is -1 all nodes in
20765 * the tree are visited. If depth is 1, only the root is visited.
20766 * If depth is 2, the root and its children are visited. And so on.
20767 * @func: the function to call for each visited #GNode
20768 * @data: user data to pass to the function
20770 * Traverses a tree starting at the given root #GNode.
20771 * It calls the given function for each node visited.
20772 * The traversal can be halted at any point by returning %TRUE from @func.
20778 * @node: the #GNode to unlink, which becomes the root of a new tree
20780 * Unlinks a #GNode from a tree, resulting in two separate trees.
20786 * @val: a 32-bit integer value in network byte order
20788 * Converts a 32-bit integer value from network to host byte order.
20790 * Returns: @val converted to host byte order.
20796 * @val: a 16-bit integer value in network byte order
20798 * Converts a 16-bit integer value from network to host byte order.
20800 * Returns: @val converted to host byte order
20805 * g_nullify_pointer:
20806 * @nullify_location: the memory address of the pointer.
20808 * Set the pointer at the specified location to %NULL.
20813 * g_on_error_query:
20814 * @prg_name: the program name, needed by gdb for the "[S]tack trace"
20815 * option. If @prg_name is %NULL, g_get_prgname() is called to get
20816 * the program name (which will work correctly if gdk_init() or
20817 * gtk_init() has been called)
20819 * Prompts the user with
20820 * `[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
20821 * This function is intended to be used for debugging use only.
20822 * The following example shows how it can be used together with
20823 * the g_log() functions.
20825 * |[<!-- language="C" -->
20826 * #include <glib.h>
20829 * log_handler (const gchar *log_domain,
20830 * GLogLevelFlags log_level,
20831 * const gchar *message,
20832 * gpointer user_data)
20834 * g_log_default_handler (log_domain, log_level, message, user_data);
20836 * g_on_error_query (MY_PROGRAM_NAME);
20840 * main (int argc, char *argv[])
20842 * g_log_set_handler (MY_LOG_DOMAIN,
20843 * G_LOG_LEVEL_WARNING |
20844 * G_LOG_LEVEL_ERROR |
20845 * G_LOG_LEVEL_CRITICAL,
20851 * If "[E]xit" is selected, the application terminates with a call
20854 * If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
20855 * This invokes gdb, which attaches to the current process and shows
20856 * a stack trace. The prompt is then shown again.
20858 * If "[P]roceed" is selected, the function returns.
20860 * This function may cause different actions on non-UNIX platforms.
20865 * g_on_error_stack_trace:
20866 * @prg_name: the program name, needed by gdb for the "[S]tack trace"
20869 * Invokes gdb, which attaches to the current process and shows a
20870 * stack trace. Called by g_on_error_query() when the "[S]tack trace"
20871 * option is selected. You can get the current process's program name
20872 * with g_get_prgname(), assuming that you have called gtk_init() or
20875 * This function may cause different actions on non-UNIX platforms.
20881 * @once: a #GOnce structure
20882 * @func: the #GThreadFunc function associated to @once. This function
20883 * is called only once, regardless of the number of times it and
20884 * its associated #GOnce struct are passed to g_once().
20885 * @arg: data to be passed to @func
20887 * The first call to this routine by a process with a given #GOnce
20888 * struct calls @func with the given argument. Thereafter, subsequent
20889 * calls to g_once() with the same #GOnce struct do not call @func
20890 * again, but return the stored result of the first call. On return
20891 * from g_once(), the status of @once will be %G_ONCE_STATUS_READY.
20893 * For example, a mutex or a thread-specific data key must be created
20894 * exactly once. In a threaded environment, calling g_once() ensures
20895 * that the initialization is serialized across multiple threads.
20897 * Calling g_once() recursively on the same #GOnce struct in
20898 * @func will lead to a deadlock.
20900 * |[<!-- language="C" -->
20902 * get_debug_flags (void)
20904 * static GOnce my_once = G_ONCE_INIT;
20906 * g_once (&my_once, parse_debug_flags, NULL);
20908 * return my_once.retval;
20917 * g_once_init_enter:
20918 * @location: location of a static initializable variable containing 0
20920 * Function to be called when starting a critical initialization
20921 * section. The argument @location must point to a static
20922 * 0-initialized variable that will be set to a value other than 0 at
20923 * the end of the initialization section. In combination with
20924 * g_once_init_leave() and the unique address @value_location, it can
20925 * be ensured that an initialization section will be executed only once
20926 * during a program's life time, and that concurrent threads are
20927 * blocked until initialization completed. To be used in constructs
20930 * |[<!-- language="C" -->
20931 * static gsize initialization_value = 0;
20933 * if (g_once_init_enter (&initialization_value))
20935 * gsize setup_value = 42; // initialization code here
20937 * g_once_init_leave (&initialization_value, setup_value);
20940 * // use initialization_value here
20943 * Returns: %TRUE if the initialization section should be entered,
20944 * %FALSE and blocks otherwise
20950 * g_once_init_leave:
20951 * @location: location of a static initializable variable containing 0
20952 * @result: new non-0 value for *@value_location
20954 * Counterpart to g_once_init_enter(). Expects a location of a static
20955 * 0-initialized initialization variable, and an initialization value
20956 * other than 0. Sets the variable to the initialization value, and
20957 * releases concurrent threads blocking in g_once_init_enter() on this
20958 * initialization variable.
20966 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
20967 * @flags: as in open()
20968 * @mode: as in open()
20970 * A wrapper for the POSIX open() function. The open() function is
20971 * used to convert a pathname into a file descriptor.
20973 * On POSIX systems file descriptors are implemented by the operating
20974 * system. On Windows, it's the C library that implements open() and
20975 * file descriptors. The actual Win32 API for opening files is quite
20976 * different, see MSDN documentation for CreateFile(). The Win32 API
20977 * uses file handles, which are more randomish integers, not small
20978 * integers like file descriptors.
20980 * Because file descriptors are specific to the C library on Windows,
20981 * the file descriptor returned by this function makes sense only to
20982 * functions in the same C library. Thus if the GLib-using code uses a
20983 * different C library than GLib does, the file descriptor returned by
20984 * this function cannot be passed to C library functions like write()
20987 * See your C library manual for more details about open().
20989 * Returns: a new file descriptor, or -1 if an error occurred.
20990 * The return value can be used exactly like the return value
20997 * g_option_context_add_group:
20998 * @context: a #GOptionContext
20999 * @group: the group to add
21001 * Adds a #GOptionGroup to the @context, so that parsing with @context
21002 * will recognize the options in the group. Note that the group will
21003 * be freed together with the context when g_option_context_free() is
21004 * called, so you must not free the group yourself after adding it
21012 * g_option_context_add_main_entries:
21013 * @context: a #GOptionContext
21014 * @entries: a %NULL-terminated array of #GOptionEntrys
21015 * @translation_domain: (allow-none): a translation domain to use for translating
21016 * the `--help` output for the options in @entries
21017 * with gettext(), or %NULL
21019 * A convenience function which creates a main group if it doesn't
21020 * exist, adds the @entries to it and sets the translation domain.
21027 * g_option_context_free:
21028 * @context: a #GOptionContext
21030 * Frees context and all the groups which have been
21033 * Please note that parsed arguments need to be freed separately (see
21041 * g_option_context_get_description:
21042 * @context: a #GOptionContext
21044 * Returns the description. See g_option_context_set_description().
21046 * Returns: the description
21052 * g_option_context_get_help:
21053 * @context: a #GOptionContext
21054 * @main_help: if %TRUE, only include the main group
21055 * @group: (allow-none): the #GOptionGroup to create help for, or %NULL
21057 * Returns a formatted, translated help text for the given context.
21058 * To obtain the text produced by `--help`, call
21059 * `g_option_context_get_help (context, TRUE, NULL)`.
21060 * To obtain the text produced by `--help-all`, call
21061 * `g_option_context_get_help (context, FALSE, NULL)`.
21062 * To obtain the help text for an option group, call
21063 * `g_option_context_get_help (context, FALSE, group)`.
21065 * Returns: A newly allocated string containing the help text
21071 * g_option_context_get_help_enabled:
21072 * @context: a #GOptionContext
21074 * Returns whether automatic `--help` generation
21075 * is turned on for @context. See g_option_context_set_help_enabled().
21077 * Returns: %TRUE if automatic help generation is turned on.
21083 * g_option_context_get_ignore_unknown_options:
21084 * @context: a #GOptionContext
21086 * Returns whether unknown options are ignored or not. See
21087 * g_option_context_set_ignore_unknown_options().
21089 * Returns: %TRUE if unknown options are ignored.
21095 * g_option_context_get_main_group:
21096 * @context: a #GOptionContext
21098 * Returns a pointer to the main group of @context.
21100 * Returns: the main group of @context, or %NULL if @context doesn't
21101 * have a main group. Note that group belongs to @context and should
21102 * not be modified or freed.
21108 * g_option_context_get_summary:
21109 * @context: a #GOptionContext
21111 * Returns the summary. See g_option_context_set_summary().
21113 * Returns: the summary
21119 * g_option_context_new:
21120 * @parameter_string: (allow-none): a string which is displayed in
21121 * the first line of `--help` output, after the usage summary
21122 * `programname [OPTION...]`
21124 * Creates a new option context.
21126 * The @parameter_string can serve multiple purposes. It can be used
21127 * to add descriptions for "rest" arguments, which are not parsed by
21128 * the #GOptionContext, typically something like "FILES" or
21129 * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for
21130 * collecting "rest" arguments, GLib handles this automatically by
21131 * using the @arg_description of the corresponding #GOptionEntry in
21132 * the usage summary.
21134 * Another usage is to give a short summary of the program
21135 * functionality, like " - frob the strings", which will be displayed
21136 * in the same line as the usage. For a longer description of the
21137 * program functionality that should be displayed as a paragraph
21138 * below the usage line, use g_option_context_set_summary().
21140 * Note that the @parameter_string is translated using the
21141 * function set with g_option_context_set_translate_func(), so
21142 * it should normally be passed untranslated.
21144 * Returns: a newly created #GOptionContext, which must be
21145 * freed with g_option_context_free() after use.
21151 * g_option_context_parse:
21152 * @context: a #GOptionContext
21153 * @argc: (inout) (allow-none): a pointer to the number of command line arguments
21154 * @argv: (inout) (array length=argc) (allow-none): a pointer to the array of command line arguments
21155 * @error: a return location for errors
21157 * Parses the command line arguments, recognizing options
21158 * which have been added to @context. A side-effect of
21159 * calling this function is that g_set_prgname() will be
21162 * If the parsing is successful, any parsed arguments are
21163 * removed from the array and @argc and @argv are updated
21164 * accordingly. A '--' option is stripped from @argv
21165 * unless there are unparsed options before and after it,
21166 * or some of the options after it start with '-'. In case
21167 * of an error, @argc and @argv are left unmodified.
21169 * If automatic `--help` support is enabled
21170 * (see g_option_context_set_help_enabled()), and the
21171 * @argv array contains one of the recognized help options,
21172 * this function will produce help output to stdout and
21175 * Note that function depends on the [current locale][setlocale] for
21176 * automatic character set conversion of string and filename
21179 * Returns: %TRUE if the parsing was successful,
21180 * %FALSE if an error occurred
21186 * g_option_context_parse_strv:
21187 * @context: a #GOptionContext
21188 * @arguments: (inout) (array null-terminated=1): a pointer to the
21189 * command line arguments (which must be in UTF-8 on Windows)
21190 * @error: a return location for errors
21192 * Parses the command line arguments.
21194 * This function is similar to g_option_context_parse() except that it
21195 * respects the normal memory rules when dealing with a strv instead of
21196 * assuming that the passed-in array is the argv of the main function.
21198 * In particular, strings that are removed from the arguments list will
21199 * be freed using g_free().
21201 * On Windows, the strings are expected to be in UTF-8. This is in
21202 * contrast to g_option_context_parse() which expects them to be in the
21203 * system codepage, which is how they are passed as @argv to main().
21204 * See g_win32_get_command_line() for a solution.
21206 * This function is useful if you are trying to use #GOptionContext with
21209 * Returns: %TRUE if the parsing was successful,
21210 * %FALSE if an error occurred
21216 * g_option_context_set_description:
21217 * @context: a #GOptionContext
21218 * @description: (allow-none): a string to be shown in `--help` output
21219 * after the list of options, or %NULL
21221 * Adds a string to be displayed in `--help` output after the list
21222 * of options. This text often includes a bug reporting address.
21224 * Note that the summary is translated (see
21225 * g_option_context_set_translate_func()).
21232 * g_option_context_set_help_enabled:
21233 * @context: a #GOptionContext
21234 * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it
21236 * Enables or disables automatic generation of `--help` output.
21237 * By default, g_option_context_parse() recognizes `--help`, `-h`,
21238 * `-?`, `--help-all` and `--help-groupname` and creates suitable
21239 * output to stdout.
21246 * g_option_context_set_ignore_unknown_options:
21247 * @context: a #GOptionContext
21248 * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce
21249 * an error when unknown options are met
21251 * Sets whether to ignore unknown options or not. If an argument is
21252 * ignored, it is left in the @argv array after parsing. By default,
21253 * g_option_context_parse() treats unknown options as error.
21255 * This setting does not affect non-option arguments (i.e. arguments
21256 * which don't start with a dash). But note that GOption cannot reliably
21257 * determine whether a non-option belongs to a preceding unknown option.
21264 * g_option_context_set_main_group:
21265 * @context: a #GOptionContext
21266 * @group: the group to set as main group
21268 * Sets a #GOptionGroup as main group of the @context.
21269 * This has the same effect as calling g_option_context_add_group(),
21270 * the only difference is that the options in the main group are
21271 * treated differently when generating `--help` output.
21278 * g_option_context_set_summary:
21279 * @context: a #GOptionContext
21280 * @summary: (allow-none): a string to be shown in `--help` output
21281 * before the list of options, or %NULL
21283 * Adds a string to be displayed in `--help` output before the list
21284 * of options. This is typically a summary of the program functionality.
21286 * Note that the summary is translated (see
21287 * g_option_context_set_translate_func() and
21288 * g_option_context_set_translation_domain()).
21295 * g_option_context_set_translate_func:
21296 * @context: a #GOptionContext
21297 * @func: (allow-none): the #GTranslateFunc, or %NULL
21298 * @data: (allow-none): user data to pass to @func, or %NULL
21299 * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL
21301 * Sets the function which is used to translate the contexts
21302 * user-visible strings, for `--help` output. If @func is %NULL,
21303 * strings are not translated.
21305 * Note that option groups have their own translation functions,
21306 * this function only affects the @parameter_string (see g_option_context_new()),
21307 * the summary (see g_option_context_set_summary()) and the description
21308 * (see g_option_context_set_description()).
21310 * If you are using gettext(), you only need to set the translation
21311 * domain, see g_option_context_set_translation_domain().
21318 * g_option_context_set_translation_domain:
21319 * @context: a #GOptionContext
21320 * @domain: the domain to use
21322 * A convenience function to use gettext() for translating
21323 * user-visible strings.
21330 * g_option_group_add_entries:
21331 * @group: a #GOptionGroup
21332 * @entries: a %NULL-terminated array of #GOptionEntrys
21334 * Adds the options specified in @entries to @group.
21341 * g_option_group_free:
21342 * @group: a #GOptionGroup
21344 * Frees a #GOptionGroup. Note that you must not free groups
21345 * which have been added to a #GOptionContext.
21352 * g_option_group_new:
21353 * @name: the name for the option group, this is used to provide
21354 * help for the options in this group with `--help-`@name
21355 * @description: a description for this group to be shown in
21356 * `--help`. This string is translated using the translation
21357 * domain or translation function of the group
21358 * @help_description: a description for the `--help-`@name option.
21359 * This string is translated using the translation domain or translation function
21361 * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks,
21362 * the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL
21363 * @destroy: (allow-none): a function that will be called to free @user_data, or %NULL
21365 * Creates a new #GOptionGroup.
21367 * Returns: a newly created option group. It should be added
21368 * to a #GOptionContext or freed with g_option_group_free().
21374 * g_option_group_set_error_hook:
21375 * @group: a #GOptionGroup
21376 * @error_func: a function to call when an error occurs
21378 * Associates a function with @group which will be called
21379 * from g_option_context_parse() when an error occurs.
21381 * Note that the user data to be passed to @error_func can be
21382 * specified when constructing the group with g_option_group_new().
21389 * g_option_group_set_parse_hooks:
21390 * @group: a #GOptionGroup
21391 * @pre_parse_func: (allow-none): a function to call before parsing, or %NULL
21392 * @post_parse_func: (allow-none): a function to call after parsing, or %NULL
21394 * Associates two functions with @group which will be called
21395 * from g_option_context_parse() before the first option is parsed
21396 * and after the last option has been parsed, respectively.
21398 * Note that the user data to be passed to @pre_parse_func and
21399 * @post_parse_func can be specified when constructing the group
21400 * with g_option_group_new().
21407 * g_option_group_set_translate_func:
21408 * @group: a #GOptionGroup
21409 * @func: (allow-none): the #GTranslateFunc, or %NULL
21410 * @data: (allow-none): user data to pass to @func, or %NULL
21411 * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL
21413 * Sets the function which is used to translate user-visible strings,
21414 * for `--help` output. Different groups can use different
21415 * #GTranslateFuncs. If @func is %NULL, strings are not translated.
21417 * If you are using gettext(), you only need to set the translation
21418 * domain, see g_option_group_set_translation_domain().
21425 * g_option_group_set_translation_domain:
21426 * @group: a #GOptionGroup
21427 * @domain: the domain to use
21429 * A convenience function to use gettext() for translating
21430 * user-visible strings.
21437 * g_parse_debug_string:
21438 * @string: (allow-none): a list of debug options separated by colons, spaces, or
21439 * commas, or %NULL.
21440 * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate
21441 * strings with bit flags.
21442 * @nkeys: the number of #GDebugKeys in the array.
21444 * Parses a string containing debugging options
21445 * into a %guint containing bit flags. This is used
21446 * within GDK and GTK+ to parse the debug options passed on the
21447 * command line or through environment variables.
21449 * If @string is equal to "all", all flags are set. Any flags
21450 * specified along with "all" in @string are inverted; thus,
21451 * "all,foo,bar" or "foo,bar,all" sets all flags except those
21452 * corresponding to "foo" and "bar".
21454 * If @string is equal to "help", all the available keys in @keys
21455 * are printed out to standard error.
21457 * Returns: the combined set of bit flags.
21462 * g_path_get_basename:
21463 * @file_name: the name of the file
21465 * Gets the last component of the filename.
21467 * If @file_name ends with a directory separator it gets the component
21468 * before the last slash. If @file_name consists only of directory
21469 * separators (and on Windows, possibly a drive letter), a single
21470 * separator is returned. If @file_name is empty, it gets ".".
21472 * Returns: a newly allocated string containing the last
21473 * component of the filename
21478 * g_path_get_dirname:
21479 * @file_name: the name of the file
21481 * Gets the directory components of a file name.
21483 * If the file name has no directory components "." is returned.
21484 * The returned string should be freed when no longer needed.
21486 * Returns: the directory components of the file
21491 * g_path_is_absolute:
21492 * @file_name: a file name
21494 * Returns %TRUE if the given @file_name is an absolute file name.
21495 * Note that this is a somewhat vague concept on Windows.
21497 * On POSIX systems, an absolute file name is well-defined. It always
21498 * starts from the single root directory. For example "/usr/local".
21500 * On Windows, the concepts of current drive and drive-specific
21501 * current directory introduce vagueness. This function interprets as
21502 * an absolute file name one that either begins with a directory
21503 * separator such as "\Users\tml" or begins with the root on a drive,
21504 * for example "C:\Windows". The first case also includes UNC paths
21505 * such as "\\myserver\docs\foo". In all cases, either slashes or
21506 * backslashes are accepted.
21508 * Note that a file name relative to the current drive root does not
21509 * truly specify a file uniquely over time and across processes, as
21510 * the current drive is a per-process value and can be changed.
21512 * File names relative the current directory on some specific drive,
21513 * such as "D:foo/bar", are not interpreted as absolute by this
21514 * function, but they obviously are not relative to the normal current
21515 * directory as returned by getcwd() or g_get_current_dir()
21516 * either. Such paths should be avoided, or need to be handled using
21517 * Windows-specific code.
21519 * Returns: %TRUE if @file_name is absolute
21524 * g_path_skip_root:
21525 * @file_name: a file name
21527 * Returns a pointer into @file_name after the root component,
21528 * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
21529 * is not an absolute path it returns %NULL.
21531 * Returns: a pointer into @file_name after the root component
21537 * @pspec: a #GPatternSpec
21538 * @string_length: the length of @string (in bytes, i.e. strlen(),
21539 * not g_utf8_strlen())
21540 * @string: the UTF-8 encoded string to match
21541 * @string_reversed: (allow-none): the reverse of @string or %NULL
21543 * Matches a string against a compiled pattern. Passing the correct
21544 * length of the string given is mandatory. The reversed string can be
21545 * omitted by passing %NULL, this is more efficient if the reversed
21546 * version of the string to be matched is not at hand, as
21547 * g_pattern_match() will only construct it if the compiled pattern
21548 * requires reverse matches.
21550 * Note that, if the user code will (possibly) match a string against a
21551 * multitude of patterns containing wildcards, chances are high that
21552 * some patterns will require a reversed string. In this case, it's
21553 * more efficient to provide the reversed string to avoid multiple
21554 * constructions thereof in the various calls to g_pattern_match().
21556 * Note also that the reverse of a UTF-8 encoded string can in general
21557 * not be obtained by g_strreverse(). This works only if the string
21558 * does not contain any multibyte characters. GLib offers the
21559 * g_utf8_strreverse() function to reverse UTF-8 encoded strings.
21561 * Returns: %TRUE if @string matches @pspec
21566 * g_pattern_match_simple:
21567 * @pattern: the UTF-8 encoded pattern
21568 * @string: the UTF-8 encoded string to match
21570 * Matches a string against a pattern given as a string. If this
21571 * function is to be called in a loop, it's more efficient to compile
21572 * the pattern once with g_pattern_spec_new() and call
21573 * g_pattern_match_string() repeatedly.
21575 * Returns: %TRUE if @string matches @pspec
21580 * g_pattern_match_string:
21581 * @pspec: a #GPatternSpec
21582 * @string: the UTF-8 encoded string to match
21584 * Matches a string against a compiled pattern. If the string is to be
21585 * matched against more than one pattern, consider using
21586 * g_pattern_match() instead while supplying the reversed string.
21588 * Returns: %TRUE if @string matches @pspec
21593 * g_pattern_spec_equal:
21594 * @pspec1: a #GPatternSpec
21595 * @pspec2: another #GPatternSpec
21597 * Compares two compiled pattern specs and returns whether they will
21598 * match the same set of strings.
21600 * Returns: Whether the compiled patterns are equal
21605 * g_pattern_spec_free:
21606 * @pspec: a #GPatternSpec
21608 * Frees the memory allocated for the #GPatternSpec.
21613 * g_pattern_spec_new:
21614 * @pattern: a zero-terminated UTF-8 encoded string
21616 * Compiles a pattern to a #GPatternSpec.
21618 * Returns: a newly-allocated #GPatternSpec
21623 * g_pointer_bit_lock:
21624 * @address: a pointer to a #gpointer-sized value
21625 * @lock_bit: a bit value between 0 and 31
21627 * This is equivalent to g_bit_lock, but working on pointers (or other
21628 * pointer-sized values).
21630 * For portability reasons, you may only lock on the bottom 32 bits of
21638 * g_pointer_bit_trylock:
21639 * @address: a pointer to a #gpointer-sized value
21640 * @lock_bit: a bit value between 0 and 31
21642 * This is equivalent to g_bit_trylock, but working on pointers (or
21643 * other pointer-sized values).
21645 * For portability reasons, you may only lock on the bottom 32 bits of
21648 * Returns: %TRUE if the lock was acquired
21654 * g_pointer_bit_unlock:
21655 * @address: a pointer to a #gpointer-sized value
21656 * @lock_bit: a bit value between 0 and 31
21658 * This is equivalent to g_bit_unlock, but working on pointers (or other
21659 * pointer-sized values).
21661 * For portability reasons, you may only lock on the bottom 32 bits of
21670 * @fds: file descriptors to poll
21671 * @nfds: the number of file descriptors in @fds
21672 * @timeout: amount of time to wait, in milliseconds, or -1 to wait forever
21674 * Polls @fds, as with the poll() system call, but portably. (On
21675 * systems that don't have poll(), it is emulated using select().)
21676 * This is used internally by #GMainContext, but it can be called
21677 * directly if you need to block until a file descriptor is ready, but
21678 * don't want to run the full main loop.
21680 * Each element of @fds is a #GPollFD describing a single file
21681 * descriptor to poll. The %fd field indicates the file descriptor,
21682 * and the %events field indicates the events to poll for. On return,
21683 * the %revents fields will be filled with the events that actually
21686 * On POSIX systems, the file descriptors in @fds can be any sort of
21687 * file descriptor, but the situation is much more complicated on
21688 * Windows. If you need to use g_poll() in code that has to run on
21689 * Windows, the easiest solution is to construct all of your
21690 * #GPollFDs with g_io_channel_win32_make_pollfd().
21692 * Returns: the number of entries in @fds whose %revents fields
21693 * were filled in, or 0 if the operation timed out, or -1 on error or
21694 * if the call was interrupted.
21701 * @err: (allow-none): a return location for a #GError, or %NULL
21702 * @format: printf()-style format string
21703 * @...: arguments to @format
21705 * Formats a string according to @format and prefix it to an existing
21706 * error message. If @err is %NULL (ie: no error variable) then do
21709 * If *@err is %NULL (ie: an error variable is present but there is no
21710 * error condition) then also do nothing. Whether or not it makes sense
21711 * to take advantage of this feature is up to you.
21719 * @format: the message format. See the printf() documentation
21720 * @...: the parameters to insert into the format string
21722 * Outputs a formatted message via the print handler.
21723 * The default print handler simply outputs the message to stdout, without
21724 * appending a trailing new-line character. Typically, @format should end with
21725 * its own new-line character.
21727 * g_print() should not be used from within libraries for debugging
21728 * messages, since it may be redirected by applications to special
21729 * purpose message windows or even files. Instead, libraries should
21730 * use g_log(), or the convenience functions g_message(), g_warning()
21737 * @format: the message format. See the printf() documentation
21738 * @...: the parameters to insert into the format string
21740 * Outputs a formatted message via the error message handler.
21741 * The default handler simply outputs the message to stderr, without appending
21742 * a trailing new-line character. Typically, @format should end with its own
21743 * new-line character.
21745 * g_printerr() should not be used from within libraries.
21746 * Instead g_log() should be used, or the convenience functions
21747 * g_message(), g_warning() and g_error().
21753 * @format: a standard printf() format string, but notice
21754 * [string precision pitfalls][string-precision]
21755 * @...: the arguments to insert in the output.
21757 * An implementation of the standard printf() function which supports
21758 * positional parameters, as specified in the Single Unix Specification.
21760 * As with the standard printf(), this does not automatically append a trailing
21761 * new-line character to the message, so typically @format should end with its
21762 * own new-line character.
21764 * Returns: the number of bytes printed.
21770 * g_printf_string_upper_bound:
21771 * @format: the format string. See the printf() documentation
21772 * @args: the parameters to be inserted into the format string
21774 * Calculates the maximum space needed to store the output
21775 * of the sprintf() function.
21777 * Returns: the maximum space needed to store the formatted string
21783 * @key: a #GPrivate
21785 * Returns the current value of the thread local variable @key.
21787 * If the value has not yet been set in this thread, %NULL is returned.
21788 * Values are never copied between threads (when a new thread is
21789 * created, for example).
21791 * Returns: the thread-local value
21796 * g_private_replace:
21797 * @key: a #GPrivate
21798 * @value: the new value
21800 * Sets the thread local variable @key to have the value @value in the
21803 * This function differs from g_private_set() in the following way: if
21804 * the previous value was non-%NULL then the #GDestroyNotify handler for
21805 * @key is run on it.
21813 * @key: a #GPrivate
21814 * @value: the new value
21816 * Sets the thread local variable @key to have the value @value in the
21819 * This function differs from g_private_replace() in the following way:
21820 * the #GDestroyNotify for @key is not called on the old value.
21825 * g_propagate_error:
21826 * @dest: error return location
21827 * @src: error to move into the return location
21829 * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
21830 * The error variable @dest points to must be %NULL.
21835 * g_propagate_prefixed_error:
21836 * @dest: error return location
21837 * @src: error to move into the return location
21838 * @format: printf()-style format string
21839 * @...: arguments to @format
21841 * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
21842 * *@dest must be %NULL. After the move, add a prefix as with
21843 * g_prefix_error().
21851 * @array: a #GPtrArray
21852 * @data: the pointer to add
21854 * Adds a pointer to the end of the pointer array. The array will grow
21855 * in size automatically if necessary.
21860 * g_ptr_array_foreach:
21861 * @array: a #GPtrArray
21862 * @func: the function to call for each array element
21863 * @user_data: user data to pass to the function
21865 * Calls a function for each element of a #GPtrArray.
21872 * g_ptr_array_free:
21873 * @array: a #GPtrArray
21874 * @free_seg: if %TRUE the actual pointer array is freed as well
21876 * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
21877 * it frees the memory block holding the elements as well. Pass %FALSE
21878 * if you want to free the #GPtrArray wrapper but preserve the
21879 * underlying array for use elsewhere. If the reference count of @array
21880 * is greater than one, the #GPtrArray wrapper is preserved but the
21881 * size of @array will be set to zero.
21883 * If array contents point to dynamically-allocated memory, they should
21884 * be freed separately if @free_seg is %TRUE and no #GDestroyNotify
21885 * function has been set for @array.
21887 * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
21888 * The pointer array should be freed using g_free().
21893 * g_ptr_array_index:
21894 * @array: a #GPtrArray
21895 * @index_: the index of the pointer to return
21897 * Returns the pointer at the given index of the pointer array.
21899 * This does not perform bounds checking on the given @index_,
21900 * so you are responsible for checking it against the array length.
21902 * Returns: the pointer at the given index
21907 * g_ptr_array_insert:
21908 * @array: a #GPtrArray
21909 * @index_: the index to place the new element at, or -1 to append
21910 * @data: the pointer to add.
21912 * Inserts an element into the pointer array at the given index. The
21913 * array will grow in size automatically if necessary.
21922 * Creates a new #GPtrArray with a reference count of 1.
21924 * Returns: the new #GPtrArray
21929 * g_ptr_array_new_full:
21930 * @reserved_size: number of pointers preallocated
21931 * @element_free_func: (allow-none): A function to free elements with
21932 * destroy @array or %NULL
21934 * Creates a new #GPtrArray with @reserved_size pointers preallocated
21935 * and a reference count of 1. This avoids frequent reallocation, if
21936 * you are going to add many pointers to the array. Note however that
21937 * the size of the array is still 0. It also set @element_free_func
21938 * for freeing each element when the array is destroyed either via
21939 * g_ptr_array_unref(), when g_ptr_array_free() is called with
21940 * @free_segment set to %TRUE or when removing elements.
21942 * Returns: A new #GPtrArray
21948 * g_ptr_array_new_with_free_func:
21949 * @element_free_func: (allow-none): A function to free elements with
21950 * destroy @array or %NULL
21952 * Creates a new #GPtrArray with a reference count of 1 and use
21953 * @element_free_func for freeing each element when the array is destroyed
21954 * either via g_ptr_array_unref(), when g_ptr_array_free() is called with
21955 * @free_segment set to %TRUE or when removing elements.
21957 * Returns: A new #GPtrArray
21964 * @array: a #GPtrArray
21966 * Atomically increments the reference count of @array by one.
21967 * This function is thread-safe and may be called from any thread.
21969 * Returns: The passed in #GPtrArray
21975 * g_ptr_array_remove:
21976 * @array: a #GPtrArray
21977 * @data: the pointer to remove
21979 * Removes the first occurrence of the given pointer from the pointer
21980 * array. The following elements are moved down one place. If @array
21981 * has a non-%NULL #GDestroyNotify function it is called for the
21984 * It returns %TRUE if the pointer was removed, or %FALSE if the
21985 * pointer was not found.
21987 * Returns: %TRUE if the pointer is removed, %FALSE if the pointer
21988 * is not found in the array
21993 * g_ptr_array_remove_fast:
21994 * @array: a #GPtrArray
21995 * @data: the pointer to remove
21997 * Removes the first occurrence of the given pointer from the pointer
21998 * array. The last element in the array is used to fill in the space,
21999 * so this function does not preserve the order of the array. But it
22000 * is faster than g_ptr_array_remove(). If @array has a non-%NULL
22001 * #GDestroyNotify function it is called for the removed element.
22003 * It returns %TRUE if the pointer was removed, or %FALSE if the
22004 * pointer was not found.
22006 * Returns: %TRUE if the pointer was found in the array
22011 * g_ptr_array_remove_index:
22012 * @array: a #GPtrArray
22013 * @index_: the index of the pointer to remove
22015 * Removes the pointer at the given index from the pointer array.
22016 * The following elements are moved down one place. If @array has
22017 * a non-%NULL #GDestroyNotify function it is called for the removed
22020 * Returns: the pointer which was removed
22025 * g_ptr_array_remove_index_fast:
22026 * @array: a #GPtrArray
22027 * @index_: the index of the pointer to remove
22029 * Removes the pointer at the given index from the pointer array.
22030 * The last element in the array is used to fill in the space, so
22031 * this function does not preserve the order of the array. But it
22032 * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
22033 * #GDestroyNotify function it is called for the removed element.
22035 * Returns: the pointer which was removed
22040 * g_ptr_array_remove_range:
22041 * @array: a @GPtrArray
22042 * @index_: the index of the first pointer to remove
22043 * @length: the number of pointers to remove
22045 * Removes the given number of pointers starting at the given index
22046 * from a #GPtrArray. The following elements are moved to close the
22047 * gap. If @array has a non-%NULL #GDestroyNotify function it is
22048 * called for the removed elements.
22050 * Returns: the @array
22056 * g_ptr_array_set_free_func:
22057 * @array: A #GPtrArray
22058 * @element_free_func: (allow-none): A function to free elements with
22059 * destroy @array or %NULL
22061 * Sets a function for freeing each element when @array is destroyed
22062 * either via g_ptr_array_unref(), when g_ptr_array_free() is called
22063 * with @free_segment set to %TRUE or when removing elements.
22070 * g_ptr_array_set_size:
22071 * @array: a #GPtrArray
22072 * @length: the new length of the pointer array
22074 * Sets the size of the array. When making the array larger,
22075 * newly-added elements will be set to %NULL. When making it smaller,
22076 * if @array has a non-%NULL #GDestroyNotify function then it will be
22077 * called for the removed elements.
22082 * g_ptr_array_sized_new:
22083 * @reserved_size: number of pointers preallocated
22085 * Creates a new #GPtrArray with @reserved_size pointers preallocated
22086 * and a reference count of 1. This avoids frequent reallocation, if
22087 * you are going to add many pointers to the array. Note however that
22088 * the size of the array is still 0.
22090 * Returns: the new #GPtrArray
22095 * g_ptr_array_sort:
22096 * @array: a #GPtrArray
22097 * @compare_func: comparison function
22099 * Sorts the array, using @compare_func which should be a qsort()-style
22100 * comparison function (returns less than zero for first arg is less
22101 * than second arg, zero for equal, greater than zero if irst arg is
22102 * greater than second arg).
22104 * Note that the comparison function for g_ptr_array_sort() doesn't
22105 * take the pointers from the array as arguments, it takes pointers to
22106 * the pointers in the array.
22108 * This is guaranteed to be a stable sort since version 2.32.
22113 * g_ptr_array_sort_with_data:
22114 * @array: a #GPtrArray
22115 * @compare_func: comparison function
22116 * @user_data: data to pass to @compare_func
22118 * Like g_ptr_array_sort(), but the comparison function has an extra
22119 * user data argument.
22121 * Note that the comparison function for g_ptr_array_sort_with_data()
22122 * doesn't take the pointers from the array as arguments, it takes
22123 * pointers to the pointers in the array.
22125 * This is guaranteed to be a stable sort since version 2.32.
22130 * g_ptr_array_unref:
22131 * @array: A #GPtrArray
22133 * Atomically decrements the reference count of @array by one. If the
22134 * reference count drops to 0, the effect is the same as calling
22135 * g_ptr_array_free() with @free_segment set to %TRUE. This function
22136 * is MT-safe and may be called from any thread.
22143 * g_qsort_with_data:
22144 * @pbase: start of array to sort
22145 * @total_elems: elements in the array
22146 * @size: size of each element
22147 * @compare_func: function to compare elements
22148 * @user_data: data to pass to @compare_func
22150 * This is just like the standard C qsort() function, but
22151 * the comparison routine accepts a user data argument.
22153 * This is guaranteed to be a stable sort since version 2.32.
22158 * g_quark_from_static_string:
22159 * @string: (allow-none): a string
22161 * Gets the #GQuark identifying the given (static) string. If the
22162 * string does not currently have an associated #GQuark, a new #GQuark
22163 * is created, linked to the given string.
22165 * Note that this function is identical to g_quark_from_string() except
22166 * that if a new #GQuark is created the string itself is used rather
22167 * than a copy. This saves memory, but can only be used if the string
22168 * will continue to exist until the program terminates. It can be used
22169 * with statically allocated strings in the main program, but not with
22170 * statically allocated memory in dynamically loaded modules, if you
22171 * expect to ever unload the module again (e.g. do not use this
22172 * function in GTK+ theme engines).
22174 * Returns: the #GQuark identifying the string, or 0 if @string is %NULL
22179 * g_quark_from_string:
22180 * @string: (allow-none): a string
22182 * Gets the #GQuark identifying the given string. If the string does
22183 * not currently have an associated #GQuark, a new #GQuark is created,
22184 * using a copy of the string.
22186 * Returns: the #GQuark identifying the string, or 0 if @string is %NULL
22191 * g_quark_to_string:
22192 * @quark: a #GQuark.
22194 * Gets the string associated with the given #GQuark.
22196 * Returns: the string associated with the #GQuark
22201 * g_quark_try_string:
22202 * @string: (allow-none): a string
22204 * Gets the #GQuark associated with the given string, or 0 if string is
22205 * %NULL or it has no associated #GQuark.
22207 * If you want the GQuark to be created if it doesn't already exist,
22208 * use g_quark_from_string() or g_quark_from_static_string().
22210 * Returns: the #GQuark associated with the string, or 0 if @string is
22211 * %NULL or there is no #GQuark associated with it
22217 * @queue: a #GQueue
22219 * Removes all the elements in @queue. If queue elements contain
22220 * dynamically-allocated memory, they should be freed first.
22228 * @queue: a #GQueue
22230 * Copies a @queue. Note that is a shallow copy. If the elements in the
22231 * queue consist of pointers to data, the pointers are copied, but the
22232 * actual data is not.
22234 * Returns: a copy of @queue
22240 * g_queue_delete_link:
22241 * @queue: a #GQueue
22242 * @link_: a #GList link that must be part of @queue
22244 * Removes @link_ from @queue and frees it.
22246 * @link_ must be part of @queue.
22254 * @queue: a #GQueue
22255 * @data: data to find
22257 * Finds the first link in @queue which contains @data.
22259 * Returns: the first link in @queue which contains @data
22265 * g_queue_find_custom:
22266 * @queue: a #GQueue
22267 * @data: user data passed to @func
22268 * @func: a #GCompareFunc to call for each element. It should return 0
22269 * when the desired element is found
22271 * Finds an element in a #GQueue, using a supplied function to find the
22272 * desired element. It iterates over the queue, calling the given function
22273 * which should return 0 when the desired element is found. The function
22274 * takes two gconstpointer arguments, the #GQueue element's data as the
22275 * first argument and the given user data as the second argument.
22277 * Returns: the found link, or %NULL if it wasn't found
22284 * @queue: a #GQueue
22285 * @func: the function to call for each element's data
22286 * @user_data: user data to pass to @func
22288 * Calls @func for each element in the queue passing @user_data to the
22297 * @queue: a #GQueue
22299 * Frees the memory allocated for the #GQueue. Only call this function
22300 * if @queue was created with g_queue_new(). If queue elements contain
22301 * dynamically-allocated memory, they should be freed first.
22303 * If queue elements contain dynamically-allocated memory, you should
22304 * either use g_queue_free_full() or free them manually first.
22309 * g_queue_free_full:
22310 * @queue: a pointer to a #GQueue
22311 * @free_func: the function to be called to free each element's data
22313 * Convenience method, which frees all the memory used by a #GQueue,
22314 * and calls the specified destroy function on every element's data.
22321 * g_queue_get_length:
22322 * @queue: a #GQueue
22324 * Returns the number of items in @queue.
22326 * Returns: the number of items in @queue
22333 * @queue: a #GQueue
22334 * @data: the data to find
22336 * Returns the position of the first element in @queue which contains @data.
22338 * Returns: the position of the first element in @queue which
22339 * contains @data, or -1 if no element in @queue contains @data
22346 * @queue: an uninitialized #GQueue
22348 * A statically-allocated #GQueue must be initialized with this function
22349 * before it can be used. Alternatively you can initialize it with
22350 * #G_QUEUE_INIT. It is not necessary to initialize queues created with
22358 * g_queue_insert_after:
22359 * @queue: a #GQueue
22360 * @sibling: a #GList link that must be part of @queue
22361 * @data: the data to insert
22363 * Inserts @data into @queue after @sibling
22365 * @sibling must be part of @queue
22372 * g_queue_insert_before:
22373 * @queue: a #GQueue
22374 * @sibling: a #GList link that must be part of @queue
22375 * @data: the data to insert
22377 * Inserts @data into @queue before @sibling.
22379 * @sibling must be part of @queue.
22386 * g_queue_insert_sorted:
22387 * @queue: a #GQueue
22388 * @data: the data to insert
22389 * @func: the #GCompareDataFunc used to compare elements in the queue. It is
22390 * called with two elements of the @queue and @user_data. It should
22391 * return 0 if the elements are equal, a negative value if the first
22392 * element comes before the second, and a positive value if the second
22393 * element comes before the first.
22394 * @user_data: user data passed to @func
22396 * Inserts @data into @queue using @func to determine the new position.
22403 * g_queue_is_empty:
22404 * @queue: a #GQueue.
22406 * Returns %TRUE if the queue is empty.
22408 * Returns: %TRUE if the queue is empty
22413 * g_queue_link_index:
22414 * @queue: a #GQueue
22415 * @link_: a #GList link
22417 * Returns the position of @link_ in @queue.
22419 * Returns: the position of @link_, or -1 if the link is
22420 * not part of @queue
22428 * Creates a new #GQueue.
22430 * Returns: a newly allocated #GQueue
22435 * g_queue_peek_head:
22436 * @queue: a #GQueue
22438 * Returns the first element of the queue.
22440 * Returns: the data of the first element in the queue, or %NULL
22441 * if the queue is empty
22446 * g_queue_peek_head_link:
22447 * @queue: a #GQueue
22449 * Returns the first link in @queue.
22451 * Returns: the first link in @queue, or %NULL if @queue is empty
22457 * g_queue_peek_nth:
22458 * @queue: a #GQueue
22459 * @n: the position of the element
22461 * Returns the @n'th element of @queue.
22463 * Returns: the data for the @n'th element of @queue,
22464 * or %NULL if @n is off the end of @queue
22470 * g_queue_peek_nth_link:
22471 * @queue: a #GQueue
22472 * @n: the position of the link
22474 * Returns the link at the given position
22476 * Returns: the link at the @n'th position, or %NULL
22477 * if @n is off the end of the list
22483 * g_queue_peek_tail:
22484 * @queue: a #GQueue
22486 * Returns the last element of the queue.
22488 * Returns: the data of the last element in the queue, or %NULL
22489 * if the queue is empty
22494 * g_queue_peek_tail_link:
22495 * @queue: a #GQueue
22497 * Returns the last link in @queue.
22499 * Returns: the last link in @queue, or %NULL if @queue is empty
22505 * g_queue_pop_head:
22506 * @queue: a #GQueue
22508 * Removes the first element of the queue and returns its data.
22510 * Returns: the data of the first element in the queue, or %NULL
22511 * if the queue is empty
22516 * g_queue_pop_head_link:
22517 * @queue: a #GQueue
22519 * Removes and returns the first element of the queue.
22521 * Returns: the #GList element at the head of the queue, or %NULL
22522 * if the queue is empty
22528 * @queue: a #GQueue
22529 * @n: the position of the element
22531 * Removes the @n'th element of @queue and returns its data.
22533 * Returns: the element's data, or %NULL if @n is off the end of @queue
22539 * g_queue_pop_nth_link:
22540 * @queue: a #GQueue
22541 * @n: the link's position
22543 * Removes and returns the link at the given position.
22545 * Returns: the @n'th link, or %NULL if @n is off the end of @queue
22551 * g_queue_pop_tail:
22552 * @queue: a #GQueue
22554 * Removes the last element of the queue and returns its data.
22556 * Returns: the data of the last element in the queue, or %NULL
22557 * if the queue is empty
22562 * g_queue_pop_tail_link:
22563 * @queue: a #GQueue
22565 * Removes and returns the last element of the queue.
22567 * Returns: the #GList element at the tail of the queue, or %NULL
22568 * if the queue is empty
22573 * g_queue_push_head:
22574 * @queue: a #GQueue.
22575 * @data: the data for the new element.
22577 * Adds a new element at the head of the queue.
22582 * g_queue_push_head_link:
22583 * @queue: a #GQueue
22584 * @link_: a single #GList element, not a list with more than one element
22586 * Adds a new element at the head of the queue.
22591 * g_queue_push_nth:
22592 * @queue: a #GQueue
22593 * @data: the data for the new element
22594 * @n: the position to insert the new element. If @n is negative or
22595 * larger than the number of elements in the @queue, the element is
22596 * added to the end of the queue.
22598 * Inserts a new element into @queue at the given position.
22605 * g_queue_push_nth_link:
22606 * @queue: a #GQueue
22607 * @n: the position to insert the link. If this is negative or larger than
22608 * the number of elements in @queue, the link is added to the end of
22610 * @link_: the link to add to @queue
22612 * Inserts @link into @queue at the given position.
22619 * g_queue_push_tail:
22620 * @queue: a #GQueue
22621 * @data: the data for the new element
22623 * Adds a new element at the tail of the queue.
22628 * g_queue_push_tail_link:
22629 * @queue: a #GQueue
22630 * @link_: a single #GList element, not a list with more than one element
22632 * Adds a new element at the tail of the queue.
22638 * @queue: a #GQueue
22639 * @data: the data to remove
22641 * Removes the first element in @queue that contains @data.
22643 * Returns: %TRUE if @data was found and removed from @queue
22649 * g_queue_remove_all:
22650 * @queue: a #GQueue
22651 * @data: the data to remove
22653 * Remove all elements whose data equals @data from @queue.
22655 * Returns: the number of elements removed from @queue
22662 * @queue: a #GQueue
22664 * Reverses the order of the items in @queue.
22672 * @queue: a #GQueue
22673 * @compare_func: the #GCompareDataFunc used to sort @queue. This function
22674 * is passed two elements of the queue and should return 0 if they are
22675 * equal, a negative value if the first comes before the second, and
22676 * a positive value if the second comes before the first.
22677 * @user_data: user data passed to @compare_func
22679 * Sorts @queue using @compare_func.
22687 * @queue: a #GQueue
22688 * @link_: a #GList link that must be part of @queue
22690 * Unlinks @link_ so that it will no longer be part of @queue.
22691 * The link is not freed.
22693 * @link_ must be part of @queue.
22703 * Returns a random #gboolean from @rand_.
22704 * This corresponds to a unbiased coin toss.
22706 * Returns: a random #gboolean
22714 * Copies a #GRand into a new one with the same exact state as before.
22715 * This way you can take a snapshot of the random number generator for
22718 * Returns: the new #GRand
22727 * Returns the next random #gdouble from @rand_ equally distributed over
22728 * the range [0..1).
22730 * Returns: a random number
22735 * g_rand_double_range:
22737 * @begin: lower closed bound of the interval
22738 * @end: upper open bound of the interval
22740 * Returns the next random #gdouble from @rand_ equally distributed over
22741 * the range [@begin..@end).
22743 * Returns: a random number
22751 * Frees the memory allocated for the #GRand.
22759 * Returns the next random #guint32 from @rand_ equally distributed over
22760 * the range [0..2^32-1].
22762 * Returns: a random number
22767 * g_rand_int_range:
22769 * @begin: lower closed bound of the interval
22770 * @end: upper open bound of the interval
22772 * Returns the next random #gint32 from @rand_ equally distributed over
22773 * the range [@begin..@end-1].
22775 * Returns: a random number
22782 * Creates a new random number generator initialized with a seed taken
22783 * either from `/dev/urandom` (if existing) or from the current time
22786 * On Windows, the seed is taken from rand_s().
22788 * Returns: the new #GRand
22793 * g_rand_new_with_seed:
22794 * @seed: a value to initialize the random number generator
22796 * Creates a new random number generator initialized with @seed.
22798 * Returns: the new #GRand
22803 * g_rand_new_with_seed_array:
22804 * @seed: an array of seeds to initialize the random number generator
22805 * @seed_length: an array of seeds to initialize the random number
22808 * Creates a new random number generator initialized with @seed.
22810 * Returns: the new #GRand
22818 * @seed: a value to reinitialize the random number generator
22820 * Sets the seed for the random number generator #GRand to @seed.
22825 * g_rand_set_seed_array:
22827 * @seed: array to initialize with
22828 * @seed_length: length of array
22830 * Initializes the random number generator by an array of longs.
22831 * Array can be of arbitrary size, though only the first 624 values
22832 * are taken. This function is useful if you have many low entropy
22833 * seeds, or if you require more then 32 bits of actual entropy for
22834 * your application.
22841 * g_random_boolean:
22843 * Returns a random #gboolean.
22844 * This corresponds to a unbiased coin toss.
22846 * Returns: a random #gboolean
22853 * Returns a random #gdouble equally distributed over the range [0..1).
22855 * Returns: a random number
22860 * g_random_double_range:
22861 * @begin: lower closed bound of the interval
22862 * @end: upper open bound of the interval
22864 * Returns a random #gdouble equally distributed over the range
22867 * Returns: a random number
22874 * Return a random #guint32 equally distributed over the range
22877 * Returns: a random number
22882 * g_random_int_range:
22883 * @begin: lower closed bound of the interval
22884 * @end: upper open bound of the interval
22886 * Returns a random #gint32 equally distributed over the range
22887 * [@begin..@end-1].
22889 * Returns: a random number
22894 * g_random_set_seed:
22895 * @seed: a value to reinitialize the global random number generator
22897 * Sets the seed for the global random number generator, which is used
22898 * by the g_random_* functions, to @seed.
22904 * @mem: (allow-none): the memory to reallocate
22905 * @n_bytes: new size of the memory in bytes
22907 * Reallocates the memory pointed to by @mem, so that it now has space for
22908 * @n_bytes bytes of memory. It returns the new address of the memory, which may
22909 * have been moved. @mem may be %NULL, in which case it's considered to
22910 * have zero-length. @n_bytes may be 0, in which case %NULL will be returned
22911 * and @mem will be freed unless it is %NULL.
22913 * Returns: the new address of the allocated memory
22919 * @mem: (allow-none): the memory to reallocate
22920 * @n_blocks: the number of blocks to allocate
22921 * @n_block_bytes: the size of each block in bytes
22923 * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
22924 * but care is taken to detect possible overflow during multiplication.
22927 * Returns: the new address of the allocated memory
22932 * g_rec_mutex_clear:
22933 * @rec_mutex: an initialized #GRecMutex
22935 * Frees the resources allocated to a recursive mutex with
22936 * g_rec_mutex_init().
22938 * This function should not be used with a #GRecMutex that has been
22939 * statically allocated.
22941 * Calling g_rec_mutex_clear() on a locked recursive mutex leads
22942 * to undefined behaviour.
22949 * g_rec_mutex_init:
22950 * @rec_mutex: an uninitialized #GRecMutex
22952 * Initializes a #GRecMutex so that it can be used.
22954 * This function is useful to initialize a recursive mutex
22955 * that has been allocated on the stack, or as part of a larger
22958 * It is not necessary to initialise a recursive mutex that has been
22959 * statically allocated.
22961 * |[<!-- language="C" -->
22969 * b = g_new (Blob, 1);
22970 * g_rec_mutex_init (&b->m);
22973 * Calling g_rec_mutex_init() on an already initialized #GRecMutex
22974 * leads to undefined behaviour.
22976 * To undo the effect of g_rec_mutex_init() when a recursive mutex
22977 * is no longer needed, use g_rec_mutex_clear().
22984 * g_rec_mutex_lock:
22985 * @rec_mutex: a #GRecMutex
22987 * Locks @rec_mutex. If @rec_mutex is already locked by another
22988 * thread, the current thread will block until @rec_mutex is
22989 * unlocked by the other thread. If @rec_mutex is already locked
22990 * by the current thread, the 'lock count' of @rec_mutex is increased.
22991 * The mutex will only become available again when it is unlocked
22992 * as many times as it has been locked.
22999 * g_rec_mutex_trylock:
23000 * @rec_mutex: a #GRecMutex
23002 * Tries to lock @rec_mutex. If @rec_mutex is already locked
23003 * by another thread, it immediately returns %FALSE. Otherwise
23004 * it locks @rec_mutex and returns %TRUE.
23006 * Returns: %TRUE if @rec_mutex could be locked
23012 * g_rec_mutex_unlock:
23013 * @rec_mutex: a #GRecMutex
23015 * Unlocks @rec_mutex. If another thread is blocked in a
23016 * g_rec_mutex_lock() call for @rec_mutex, it will become unblocked
23017 * and can lock @rec_mutex itself.
23019 * Calling g_rec_mutex_unlock() on a recursive mutex that is not
23020 * locked by the current thread leads to undefined behaviour.
23027 * g_regex_check_replacement:
23028 * @replacement: the replacement string
23029 * @has_references: (out) (allow-none): location to store information about
23030 * references in @replacement or %NULL
23031 * @error: location to store error
23033 * Checks whether @replacement is a valid replacement string
23034 * (see g_regex_replace()), i.e. that all escape sequences in
23037 * If @has_references is not %NULL then @replacement is checked
23038 * for pattern references. For instance, replacement text 'foo\n'
23039 * does not contain references and may be evaluated without information
23040 * about actual match, but '\0\1' (whole match followed by first
23041 * subpattern) requires valid #GMatchInfo object.
23043 * Returns: whether @replacement is a valid replacement string
23049 * g_regex_escape_nul:
23050 * @string: the string to escape
23051 * @length: the length of @string
23053 * Escapes the nul characters in @string to "\x00". It can be used
23054 * to compile a regex with embedded nul characters.
23056 * For completeness, @length can be -1 for a nul-terminated string.
23057 * In this case the output string will be of course equal to @string.
23059 * Returns: a newly-allocated escaped string
23065 * g_regex_escape_string:
23066 * @string: (array length=length): the string to escape
23067 * @length: the length of @string, or -1 if @string is nul-terminated
23069 * Escapes the special characters used for regular expressions
23070 * in @string, for instance "a.b*c" becomes "a\.b\*c". This
23071 * function is useful to dynamically generate regular expressions.
23073 * @string can contain nul characters that are replaced with "\0",
23074 * in this case remember to specify the correct length of @string
23077 * Returns: a newly-allocated escaped string
23083 * g_regex_get_capture_count:
23084 * @regex: a #GRegex
23086 * Returns the number of capturing subpatterns in the pattern.
23088 * Returns: the number of capturing subpatterns
23094 * g_regex_get_compile_flags:
23095 * @regex: a #GRegex
23097 * Returns the compile options that @regex was created with.
23099 * Returns: flags from #GRegexCompileFlags
23105 * g_regex_get_has_cr_or_lf:
23106 * @regex: a #GRegex structure
23108 * Checks whether the pattern contains explicit CR or LF references.
23110 * Returns: %TRUE if the pattern contains explicit CR or LF references
23116 * g_regex_get_match_flags:
23117 * @regex: a #GRegex
23119 * Returns the match options that @regex was created with.
23121 * Returns: flags from #GRegexMatchFlags
23127 * g_regex_get_max_backref:
23128 * @regex: a #GRegex
23130 * Returns the number of the highest back reference
23131 * in the pattern, or 0 if the pattern does not contain
23134 * Returns: the number of the highest back reference
23140 * g_regex_get_max_lookbehind:
23141 * @regex: a #GRegex structure
23143 * Gets the number of characters in the longest lookbehind assertion in the
23144 * pattern. This information is useful when doing multi-segment matching using
23145 * the partial matching facilities.
23147 * Returns: the number of characters in the longest lookbehind assertion.
23153 * g_regex_get_pattern:
23154 * @regex: a #GRegex structure
23156 * Gets the pattern string associated with @regex, i.e. a copy of
23157 * the string passed to g_regex_new().
23159 * Returns: the pattern of @regex
23165 * g_regex_get_string_number:
23166 * @regex: #GRegex structure
23167 * @name: name of the subexpression
23169 * Retrieves the number of the subexpression named @name.
23171 * Returns: The number of the subexpression or -1 if @name
23179 * @regex: a #GRegex structure from g_regex_new()
23180 * @string: the string to scan for matches
23181 * @match_options: match options
23182 * @match_info: (out) (allow-none): pointer to location where to store
23183 * the #GMatchInfo, or %NULL if you do not need it
23185 * Scans for a match in string for the pattern in @regex.
23186 * The @match_options are combined with the match options specified
23187 * when the @regex structure was created, letting you have more
23188 * flexibility in reusing #GRegex structures.
23190 * A #GMatchInfo structure, used to get information on the match,
23191 * is stored in @match_info if not %NULL. Note that if @match_info
23192 * is not %NULL then it is created even if the function returns %FALSE,
23193 * i.e. you must free it regardless if regular expression actually matched.
23195 * To retrieve all the non-overlapping matches of the pattern in
23196 * string you can use g_match_info_next().
23198 * |[<!-- language="C" -->
23200 * print_uppercase_words (const gchar *string)
23202 * // Print all uppercase-only words.
23204 * GMatchInfo *match_info;
23206 * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
23207 * g_regex_match (regex, string, 0, &match_info);
23208 * while (g_match_info_matches (match_info))
23210 * gchar *word = g_match_info_fetch (match_info, 0);
23211 * g_print ("Found: %s\n", word);
23213 * g_match_info_next (match_info, NULL);
23215 * g_match_info_free (match_info);
23216 * g_regex_unref (regex);
23220 * @string is not copied and is used in #GMatchInfo internally. If
23221 * you use any #GMatchInfo method (except g_match_info_free()) after
23222 * freeing or modifying @string then the behaviour is undefined.
23224 * Returns: %TRUE is the string matched, %FALSE otherwise
23230 * g_regex_match_all:
23231 * @regex: a #GRegex structure from g_regex_new()
23232 * @string: the string to scan for matches
23233 * @match_options: match options
23234 * @match_info: (out) (allow-none): pointer to location where to store
23235 * the #GMatchInfo, or %NULL if you do not need it
23237 * Using the standard algorithm for regular expression matching only
23238 * the longest match in the string is retrieved. This function uses
23239 * a different algorithm so it can retrieve all the possible matches.
23240 * For more documentation see g_regex_match_all_full().
23242 * A #GMatchInfo structure, used to get information on the match, is
23243 * stored in @match_info if not %NULL. Note that if @match_info is
23244 * not %NULL then it is created even if the function returns %FALSE,
23245 * i.e. you must free it regardless if regular expression actually
23248 * @string is not copied and is used in #GMatchInfo internally. If
23249 * you use any #GMatchInfo method (except g_match_info_free()) after
23250 * freeing or modifying @string then the behaviour is undefined.
23252 * Returns: %TRUE is the string matched, %FALSE otherwise
23258 * g_regex_match_all_full:
23259 * @regex: a #GRegex structure from g_regex_new()
23260 * @string: (array length=string_len): the string to scan for matches
23261 * @string_len: the length of @string, or -1 if @string is nul-terminated
23262 * @start_position: starting index of the string to match
23263 * @match_options: match options
23264 * @match_info: (out) (allow-none): pointer to location where to store
23265 * the #GMatchInfo, or %NULL if you do not need it
23266 * @error: location to store the error occurring, or %NULL to ignore errors
23268 * Using the standard algorithm for regular expression matching only
23269 * the longest match in the string is retrieved, it is not possible
23270 * to obtain all the available matches. For instance matching
23271 * "<a> <b> <c>" against the pattern "<.*>"
23272 * you get "<a> <b> <c>".
23274 * This function uses a different algorithm (called DFA, i.e. deterministic
23275 * finite automaton), so it can retrieve all the possible matches, all
23276 * starting at the same point in the string. For instance matching
23277 * "<a> <b> <c>" against the pattern "<.*>;"
23278 * you would obtain three matches: "<a> <b> <c>",
23279 * "<a> <b>" and "<a>".
23281 * The number of matched strings is retrieved using
23282 * g_match_info_get_match_count(). To obtain the matched strings and
23283 * their position you can use, respectively, g_match_info_fetch() and
23284 * g_match_info_fetch_pos(). Note that the strings are returned in
23285 * reverse order of length; that is, the longest matching string is
23288 * Note that the DFA algorithm is slower than the standard one and it
23289 * is not able to capture substrings, so backreferences do not work.
23291 * Setting @start_position differs from just passing over a shortened
23292 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
23293 * that begins with any kind of lookbehind assertion, such as "\b".
23295 * A #GMatchInfo structure, used to get information on the match, is
23296 * stored in @match_info if not %NULL. Note that if @match_info is
23297 * not %NULL then it is created even if the function returns %FALSE,
23298 * i.e. you must free it regardless if regular expression actually
23301 * @string is not copied and is used in #GMatchInfo internally. If
23302 * you use any #GMatchInfo method (except g_match_info_free()) after
23303 * freeing or modifying @string then the behaviour is undefined.
23305 * Returns: %TRUE is the string matched, %FALSE otherwise
23311 * g_regex_match_full:
23312 * @regex: a #GRegex structure from g_regex_new()
23313 * @string: (array length=string_len): the string to scan for matches
23314 * @string_len: the length of @string, or -1 if @string is nul-terminated
23315 * @start_position: starting index of the string to match
23316 * @match_options: match options
23317 * @match_info: (out) (allow-none): pointer to location where to store
23318 * the #GMatchInfo, or %NULL if you do not need it
23319 * @error: location to store the error occurring, or %NULL to ignore errors
23321 * Scans for a match in string for the pattern in @regex.
23322 * The @match_options are combined with the match options specified
23323 * when the @regex structure was created, letting you have more
23324 * flexibility in reusing #GRegex structures.
23326 * Setting @start_position differs from just passing over a shortened
23327 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
23328 * that begins with any kind of lookbehind assertion, such as "\b".
23330 * A #GMatchInfo structure, used to get information on the match, is
23331 * stored in @match_info if not %NULL. Note that if @match_info is
23332 * not %NULL then it is created even if the function returns %FALSE,
23333 * i.e. you must free it regardless if regular expression actually
23336 * @string is not copied and is used in #GMatchInfo internally. If
23337 * you use any #GMatchInfo method (except g_match_info_free()) after
23338 * freeing or modifying @string then the behaviour is undefined.
23340 * To retrieve all the non-overlapping matches of the pattern in
23341 * string you can use g_match_info_next().
23343 * |[<!-- language="C" -->
23345 * print_uppercase_words (const gchar *string)
23347 * // Print all uppercase-only words.
23349 * GMatchInfo *match_info;
23350 * GError *error = NULL;
23352 * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
23353 * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
23354 * while (g_match_info_matches (match_info))
23356 * gchar *word = g_match_info_fetch (match_info, 0);
23357 * g_print ("Found: %s\n", word);
23359 * g_match_info_next (match_info, &error);
23361 * g_match_info_free (match_info);
23362 * g_regex_unref (regex);
23363 * if (error != NULL)
23365 * g_printerr ("Error while matching: %s\n", error->message);
23366 * g_error_free (error);
23371 * Returns: %TRUE is the string matched, %FALSE otherwise
23377 * g_regex_match_simple:
23378 * @pattern: the regular expression
23379 * @string: the string to scan for matches
23380 * @compile_options: compile options for the regular expression, or 0
23381 * @match_options: match options, or 0
23383 * Scans for a match in @string for @pattern.
23385 * This function is equivalent to g_regex_match() but it does not
23386 * require to compile the pattern with g_regex_new(), avoiding some
23387 * lines of code when you need just to do a match without extracting
23388 * substrings, capture counts, and so on.
23390 * If this function is to be called on the same @pattern more than
23391 * once, it's more efficient to compile the pattern once with
23392 * g_regex_new() and then use g_regex_match().
23394 * Returns: %TRUE if the string matched, %FALSE otherwise
23401 * @pattern: the regular expression
23402 * @compile_options: compile options for the regular expression, or 0
23403 * @match_options: match options for the regular expression, or 0
23404 * @error: return location for a #GError
23406 * Compiles the regular expression to an internal form, and does
23407 * the initial setup of the #GRegex structure.
23409 * Returns: a #GRegex structure. Call g_regex_unref() when you
23417 * @regex: a #GRegex
23419 * Increases reference count of @regex by 1.
23428 * @regex: a #GRegex structure
23429 * @string: (array length=string_len): the string to perform matches against
23430 * @string_len: the length of @string, or -1 if @string is nul-terminated
23431 * @start_position: starting index of the string to match
23432 * @replacement: text to replace each match with
23433 * @match_options: options for the match
23434 * @error: location to store the error occurring, or %NULL to ignore errors
23436 * Replaces all occurrences of the pattern in @regex with the
23437 * replacement text. Backreferences of the form '\number' or
23438 * '\g<number>' in the replacement text are interpolated by the
23439 * number-th captured subexpression of the match, '\g<name>' refers
23440 * to the captured subexpression with the given name. '\0' refers
23441 * to the complete match, but '\0' followed by a number is the octal
23442 * representation of a character. To include a literal '\' in the
23443 * replacement, write '\\'.
23445 * There are also escapes that changes the case of the following text:
23447 * - \l: Convert to lower case the next character
23448 * - \u: Convert to upper case the next character
23449 * - \L: Convert to lower case till \E
23450 * - \U: Convert to upper case till \E
23451 * - \E: End case modification
23453 * If you do not need to use backreferences use g_regex_replace_literal().
23455 * The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was
23456 * passed to g_regex_new(). If you want to use not UTF-8 encoded stings
23457 * you can use g_regex_replace_literal().
23459 * Setting @start_position differs from just passing over a shortened
23460 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that
23461 * begins with any kind of lookbehind assertion, such as "\b".
23463 * Returns: a newly allocated string containing the replacements
23469 * g_regex_replace_eval:
23470 * @regex: a #GRegex structure from g_regex_new()
23471 * @string: (array length=string_len): string to perform matches against
23472 * @string_len: the length of @string, or -1 if @string is nul-terminated
23473 * @start_position: starting index of the string to match
23474 * @match_options: options for the match
23475 * @eval: a function to call for each match
23476 * @user_data: user data to pass to the function
23477 * @error: location to store the error occurring, or %NULL to ignore errors
23479 * Replaces occurrences of the pattern in regex with the output of
23480 * @eval for that occurrence.
23482 * Setting @start_position differs from just passing over a shortened
23483 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
23484 * that begins with any kind of lookbehind assertion, such as "\b".
23486 * The following example uses g_regex_replace_eval() to replace multiple
23488 * |[<!-- language="C" -->
23490 * eval_cb (const GMatchInfo *info,
23497 * match = g_match_info_fetch (info, 0);
23498 * r = g_hash_table_lookup ((GHashTable *)data, match);
23499 * g_string_append (res, r);
23511 * h = g_hash_table_new (g_str_hash, g_str_equal);
23513 * g_hash_table_insert (h, "1", "ONE");
23514 * g_hash_table_insert (h, "2", "TWO");
23515 * g_hash_table_insert (h, "3", "THREE");
23516 * g_hash_table_insert (h, "4", "FOUR");
23518 * reg = g_regex_new ("1|2|3|4", 0, 0, NULL);
23519 * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
23520 * g_hash_table_destroy (h);
23525 * Returns: a newly allocated string containing the replacements
23531 * g_regex_replace_literal:
23532 * @regex: a #GRegex structure
23533 * @string: (array length=string_len): the string to perform matches against
23534 * @string_len: the length of @string, or -1 if @string is nul-terminated
23535 * @start_position: starting index of the string to match
23536 * @replacement: text to replace each match with
23537 * @match_options: options for the match
23538 * @error: location to store the error occurring, or %NULL to ignore errors
23540 * Replaces all occurrences of the pattern in @regex with the
23541 * replacement text. @replacement is replaced literally, to
23542 * include backreferences use g_regex_replace().
23544 * Setting @start_position differs from just passing over a
23545 * shortened string and setting #G_REGEX_MATCH_NOTBOL in the
23546 * case of a pattern that begins with any kind of lookbehind
23547 * assertion, such as "\b".
23549 * Returns: a newly allocated string containing the replacements
23556 * @regex: a #GRegex structure
23557 * @string: the string to split with the pattern
23558 * @match_options: match time option flags
23560 * Breaks the string on the pattern, and returns an array of the tokens.
23561 * If the pattern contains capturing parentheses, then the text for each
23562 * of the substrings will also be returned. If the pattern does not match
23563 * anywhere in the string, then the whole string is returned as the first
23566 * As a special case, the result of splitting the empty string "" is an
23567 * empty vector, not a vector containing a single string. The reason for
23568 * this special case is that being able to represent a empty vector is
23569 * typically more useful than consistent handling of empty elements. If
23570 * you do need to represent empty elements, you'll need to check for the
23571 * empty string before calling this function.
23573 * A pattern that can match empty strings splits @string into separate
23574 * characters wherever it matches the empty string between characters.
23575 * For example splitting "ab c" using as a separator "\s*", you will get
23576 * "a", "b" and "c".
23578 * Returns: (transfer full): a %NULL-terminated gchar ** array. Free
23579 * it using g_strfreev()
23585 * g_regex_split_full:
23586 * @regex: a #GRegex structure
23587 * @string: (array length=string_len): the string to split with the pattern
23588 * @string_len: the length of @string, or -1 if @string is nul-terminated
23589 * @start_position: starting index of the string to match
23590 * @match_options: match time option flags
23591 * @max_tokens: the maximum number of tokens to split @string into.
23592 * If this is less than 1, the string is split completely
23593 * @error: return location for a #GError
23595 * Breaks the string on the pattern, and returns an array of the tokens.
23596 * If the pattern contains capturing parentheses, then the text for each
23597 * of the substrings will also be returned. If the pattern does not match
23598 * anywhere in the string, then the whole string is returned as the first
23601 * As a special case, the result of splitting the empty string "" is an
23602 * empty vector, not a vector containing a single string. The reason for
23603 * this special case is that being able to represent a empty vector is
23604 * typically more useful than consistent handling of empty elements. If
23605 * you do need to represent empty elements, you'll need to check for the
23606 * empty string before calling this function.
23608 * A pattern that can match empty strings splits @string into separate
23609 * characters wherever it matches the empty string between characters.
23610 * For example splitting "ab c" using as a separator "\s*", you will get
23611 * "a", "b" and "c".
23613 * Setting @start_position differs from just passing over a shortened
23614 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
23615 * that begins with any kind of lookbehind assertion, such as "\b".
23617 * Returns: (transfer full): a %NULL-terminated gchar ** array. Free
23618 * it using g_strfreev()
23624 * g_regex_split_simple:
23625 * @pattern: the regular expression
23626 * @string: the string to scan for matches
23627 * @compile_options: compile options for the regular expression, or 0
23628 * @match_options: match options, or 0
23630 * Breaks the string on the pattern, and returns an array of
23631 * the tokens. If the pattern contains capturing parentheses,
23632 * then the text for each of the substrings will also be returned.
23633 * If the pattern does not match anywhere in the string, then the
23634 * whole string is returned as the first token.
23636 * This function is equivalent to g_regex_split() but it does
23637 * not require to compile the pattern with g_regex_new(), avoiding
23638 * some lines of code when you need just to do a split without
23639 * extracting substrings, capture counts, and so on.
23641 * If this function is to be called on the same @pattern more than
23642 * once, it's more efficient to compile the pattern once with
23643 * g_regex_new() and then use g_regex_split().
23645 * As a special case, the result of splitting the empty string ""
23646 * is an empty vector, not a vector containing a single string.
23647 * The reason for this special case is that being able to represent
23648 * a empty vector is typically more useful than consistent handling
23649 * of empty elements. If you do need to represent empty elements,
23650 * you'll need to check for the empty string before calling this
23653 * A pattern that can match empty strings splits @string into
23654 * separate characters wherever it matches the empty string between
23655 * characters. For example splitting "ab c" using as a separator
23656 * "\s*", you will get "a", "b" and "c".
23658 * Returns: (transfer full): a %NULL-terminated array of strings. Free
23659 * it using g_strfreev()
23666 * @regex: a #GRegex
23668 * Decreases reference count of @regex by 1. When reference count drops
23669 * to zero, it frees all the memory associated with the regex structure.
23676 * g_reload_user_special_dirs_cache:
23678 * Resets the cache used for g_get_user_special_dir(), so
23679 * that the latest on-disk version is used. Call this only
23680 * if you just changed the data on disk yourself.
23682 * Due to threadsafety issues this may cause leaking of strings
23683 * that were previously returned from g_get_user_special_dir()
23684 * that can't be freed. We ensure to only leak the data for
23685 * the directories that actually changed value though.
23693 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
23695 * A wrapper for the POSIX remove() function. The remove() function
23696 * deletes a name from the filesystem.
23698 * See your C library manual for more details about how remove() works
23699 * on your system. On Unix, remove() removes also directories, as it
23700 * calls unlink() for files and rmdir() for directories. On Windows,
23701 * although remove() in the C library only works for files, this
23702 * function tries first remove() and then if that fails rmdir(), and
23703 * thus works for both files and directories. Note however, that on
23704 * Windows, it is in general not possible to remove a file that is
23705 * open to some process, or mapped into memory.
23707 * If this function fails on Windows you can't infer too much from the
23708 * errno value. rmdir() is tried regardless of what caused remove() to
23709 * fail. Any errno value set by remove() will be overwritten by that
23712 * Returns: 0 if the file was successfully removed, -1 if an error
23720 * @oldfilename: a pathname in the GLib file name encoding (UTF-8 on Windows)
23721 * @newfilename: a pathname in the GLib file name encoding
23723 * A wrapper for the POSIX rename() function. The rename() function
23724 * renames a file, moving it between directories if required.
23726 * See your C library manual for more details about how rename() works
23727 * on your system. It is not possible in general on Windows to rename
23728 * a file that is open to some process.
23730 * Returns: 0 if the renaming succeeded, -1 if an error occurred
23737 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
23739 * A wrapper for the POSIX rmdir() function. The rmdir() function
23740 * deletes a directory from the filesystem.
23742 * See your C library manual for more details about how rmdir() works
23745 * Returns: 0 if the directory was successfully removed, -1 if an error
23753 * @rw_lock: an initialized #GRWLock
23755 * Frees the resources allocated to a lock with g_rw_lock_init().
23757 * This function should not be used with a #GRWLock that has been
23758 * statically allocated.
23760 * Calling g_rw_lock_clear() when any thread holds the lock
23761 * leads to undefined behaviour.
23769 * @rw_lock: an uninitialized #GRWLock
23771 * Initializes a #GRWLock so that it can be used.
23773 * This function is useful to initialize a lock that has been
23774 * allocated on the stack, or as part of a larger structure. It is not
23775 * necessary to initialise a reader-writer lock that has been statically
23778 * |[<!-- language="C" -->
23786 * b = g_new (Blob, 1);
23787 * g_rw_lock_init (&b->l);
23790 * To undo the effect of g_rw_lock_init() when a lock is no longer
23791 * needed, use g_rw_lock_clear().
23793 * Calling g_rw_lock_init() on an already initialized #GRWLock leads
23794 * to undefined behaviour.
23801 * g_rw_lock_reader_lock:
23802 * @rw_lock: a #GRWLock
23804 * Obtain a read lock on @rw_lock. If another thread currently holds
23805 * the write lock on @rw_lock or blocks waiting for it, the current
23806 * thread will block. Read locks can be taken recursively.
23808 * It is implementation-defined how many threads are allowed to
23809 * hold read locks on the same lock simultaneously.
23816 * g_rw_lock_reader_trylock:
23817 * @rw_lock: a #GRWLock
23819 * Tries to obtain a read lock on @rw_lock and returns %TRUE if
23820 * the read lock was successfully obtained. Otherwise it
23823 * Returns: %TRUE if @rw_lock could be locked
23829 * g_rw_lock_reader_unlock:
23830 * @rw_lock: a #GRWLock
23832 * Release a read lock on @rw_lock.
23834 * Calling g_rw_lock_reader_unlock() on a lock that is not held
23835 * by the current thread leads to undefined behaviour.
23842 * g_rw_lock_writer_lock:
23843 * @rw_lock: a #GRWLock
23845 * Obtain a write lock on @rw_lock. If any thread already holds
23846 * a read or write lock on @rw_lock, the current thread will block
23847 * until all other threads have dropped their locks on @rw_lock.
23854 * g_rw_lock_writer_trylock:
23855 * @rw_lock: a #GRWLock
23857 * Tries to obtain a write lock on @rw_lock. If any other thread holds
23858 * a read or write lock on @rw_lock, it immediately returns %FALSE.
23859 * Otherwise it locks @rw_lock and returns %TRUE.
23861 * Returns: %TRUE if @rw_lock could be locked
23867 * g_rw_lock_writer_unlock:
23868 * @rw_lock: a #GRWLock
23870 * Release a write lock on @rw_lock.
23872 * Calling g_rw_lock_writer_unlock() on a lock that is not held
23873 * by the current thread leads to undefined behaviour.
23880 * g_scanner_add_symbol:
23881 * @scanner: a #GScanner
23882 * @symbol: the symbol to add
23883 * @value: the value of the symbol
23885 * Adds a symbol to the default scope.
23887 * Deprecated: 2.2: Use g_scanner_scope_add_symbol() instead.
23892 * g_scanner_cur_line:
23893 * @scanner: a #GScanner
23895 * Returns the current line in the input stream (counting
23896 * from 1). This is the line of the last token parsed via
23897 * g_scanner_get_next_token().
23899 * Returns: the current line
23904 * g_scanner_cur_position:
23905 * @scanner: a #GScanner
23907 * Returns the current position in the current line (counting
23908 * from 0). This is the position of the last token parsed via
23909 * g_scanner_get_next_token().
23911 * Returns: the current position on the line
23916 * g_scanner_cur_token:
23917 * @scanner: a #GScanner
23919 * Gets the current token type. This is simply the @token
23920 * field in the #GScanner structure.
23922 * Returns: the current token type
23927 * g_scanner_cur_value:
23928 * @scanner: a #GScanner
23930 * Gets the current token value. This is simply the @value
23931 * field in the #GScanner structure.
23933 * Returns: the current token value
23938 * g_scanner_destroy:
23939 * @scanner: a #GScanner
23941 * Frees all memory used by the #GScanner.
23947 * @scanner: a #GScanner
23949 * Returns %TRUE if the scanner has reached the end of
23950 * the file or text buffer.
23952 * Returns: %TRUE if the scanner has reached the end of
23953 * the file or text buffer
23959 * @scanner: a #GScanner
23960 * @format: the message format. See the printf() documentation
23961 * @...: the parameters to insert into the format string
23963 * Outputs an error message, via the #GScanner message handler.
23968 * g_scanner_foreach_symbol:
23969 * @scanner: a #GScanner
23970 * @func: the function to call with each symbol
23971 * @data: data to pass to the function
23973 * Calls a function for each symbol in the default scope.
23975 * Deprecated: 2.2: Use g_scanner_scope_foreach_symbol() instead.
23980 * g_scanner_freeze_symbol_table:
23981 * @scanner: a #GScanner
23983 * There is no reason to use this macro, since it does nothing.
23985 * Deprecated: 2.2: This macro does nothing.
23990 * g_scanner_get_next_token:
23991 * @scanner: a #GScanner
23993 * Parses the next token just like g_scanner_peek_next_token()
23994 * and also removes it from the input stream. The token data is
23995 * placed in the @token, @value, @line, and @position fields of
23996 * the #GScanner structure.
23998 * Returns: the type of the token
24003 * g_scanner_input_file:
24004 * @scanner: a #GScanner
24005 * @input_fd: a file descriptor
24007 * Prepares to scan a file.
24012 * g_scanner_input_text:
24013 * @scanner: a #GScanner
24014 * @text: the text buffer to scan
24015 * @text_len: the length of the text buffer
24017 * Prepares to scan a text buffer.
24022 * g_scanner_lookup_symbol:
24023 * @scanner: a #GScanner
24024 * @symbol: the symbol to look up
24026 * Looks up a symbol in the current scope and return its value.
24027 * If the symbol is not bound in the current scope, %NULL is
24030 * Returns: the value of @symbol in the current scope, or %NULL
24031 * if @symbol is not bound in the current scope
24037 * @config_templ: the initial scanner settings
24039 * Creates a new #GScanner.
24041 * The @config_templ structure specifies the initial settings
24042 * of the scanner, which are copied into the #GScanner
24043 * @config field. If you pass %NULL then the default settings
24046 * Returns: the new #GScanner
24051 * g_scanner_peek_next_token:
24052 * @scanner: a #GScanner
24054 * Parses the next token, without removing it from the input stream.
24055 * The token data is placed in the @next_token, @next_value, @next_line,
24056 * and @next_position fields of the #GScanner structure.
24058 * Note that, while the token is not removed from the input stream
24059 * (i.e. the next call to g_scanner_get_next_token() will return the
24060 * same token), it will not be reevaluated. This can lead to surprising
24061 * results when changing scope or the scanner configuration after peeking
24062 * the next token. Getting the next token after switching the scope or
24063 * configuration will return whatever was peeked before, regardless of
24064 * any symbols that may have been added or removed in the new scope.
24066 * Returns: the type of the token
24071 * g_scanner_remove_symbol:
24072 * @scanner: a #GScanner
24073 * @symbol: the symbol to remove
24075 * Removes a symbol from the default scope.
24077 * Deprecated: 2.2: Use g_scanner_scope_remove_symbol() instead.
24082 * g_scanner_scope_add_symbol:
24083 * @scanner: a #GScanner
24084 * @scope_id: the scope id
24085 * @symbol: the symbol to add
24086 * @value: the value of the symbol
24088 * Adds a symbol to the given scope.
24093 * g_scanner_scope_foreach_symbol:
24094 * @scanner: a #GScanner
24095 * @scope_id: the scope id
24096 * @func: the function to call for each symbol/value pair
24097 * @user_data: user data to pass to the function
24099 * Calls the given function for each of the symbol/value pairs
24100 * in the given scope of the #GScanner. The function is passed
24101 * the symbol and value of each pair, and the given @user_data
24107 * g_scanner_scope_lookup_symbol:
24108 * @scanner: a #GScanner
24109 * @scope_id: the scope id
24110 * @symbol: the symbol to look up
24112 * Looks up a symbol in a scope and return its value. If the
24113 * symbol is not bound in the scope, %NULL is returned.
24115 * Returns: the value of @symbol in the given scope, or %NULL
24116 * if @symbol is not bound in the given scope.
24121 * g_scanner_scope_remove_symbol:
24122 * @scanner: a #GScanner
24123 * @scope_id: the scope id
24124 * @symbol: the symbol to remove
24126 * Removes a symbol from a scope.
24131 * g_scanner_set_scope:
24132 * @scanner: a #GScanner
24133 * @scope_id: the new scope id
24135 * Sets the current scope.
24137 * Returns: the old scope id
24142 * g_scanner_sync_file_offset:
24143 * @scanner: a #GScanner
24145 * Rewinds the filedescriptor to the current buffer position
24146 * and blows the file read ahead buffer. This is useful for
24147 * third party uses of the scanners filedescriptor, which hooks
24148 * onto the current scanning position.
24153 * g_scanner_thaw_symbol_table:
24154 * @scanner: a #GScanner
24156 * There is no reason to use this macro, since it does nothing.
24158 * Deprecated: 2.2: This macro does nothing.
24163 * g_scanner_unexp_token:
24164 * @scanner: a #GScanner
24165 * @expected_token: the expected token
24166 * @identifier_spec: a string describing how the scanner's user
24167 * refers to identifiers (%NULL defaults to "identifier").
24168 * This is used if @expected_token is %G_TOKEN_IDENTIFIER or
24169 * %G_TOKEN_IDENTIFIER_NULL.
24170 * @symbol_spec: a string describing how the scanner's user refers
24171 * to symbols (%NULL defaults to "symbol"). This is used if
24172 * @expected_token is %G_TOKEN_SYMBOL or any token value greater
24173 * than %G_TOKEN_LAST.
24174 * @symbol_name: the name of the symbol, if the scanner's current
24175 * token is a symbol.
24176 * @message: a message string to output at the end of the
24177 * warning/error, or %NULL.
24178 * @is_error: if %TRUE it is output as an error. If %FALSE it is
24179 * output as a warning.
24181 * Outputs a message through the scanner's msg_handler,
24182 * resulting from an unexpected token in the input stream.
24183 * Note that you should not call g_scanner_peek_next_token()
24184 * followed by g_scanner_unexp_token() without an intermediate
24185 * call to g_scanner_get_next_token(), as g_scanner_unexp_token()
24186 * evaluates the scanner's current token (not the peeked token)
24187 * to construct part of the message.
24193 * @scanner: a #GScanner
24194 * @format: the message format. See the printf() documentation
24195 * @...: the parameters to insert into the format string
24197 * Outputs a warning message, via the #GScanner message handler.
24202 * g_sequence_append:
24203 * @seq: a #GSequence
24204 * @data: the data for the new item
24206 * Adds a new item to the end of @seq.
24208 * Returns: an iterator pointing to the new item
24214 * g_sequence_foreach:
24215 * @seq: a #GSequence
24216 * @func: the function to call for each item in @seq
24217 * @user_data: user data passed to @func
24219 * Calls @func for each item in the sequence passing @user_data
24227 * g_sequence_foreach_range:
24228 * @begin: a #GSequenceIter
24229 * @end: a #GSequenceIter
24231 * @user_data: user data passed to @func
24233 * Calls @func for each item in the range (@begin, @end) passing
24234 * @user_data to the function.
24242 * @seq: a #GSequence
24244 * Frees the memory allocated for @seq. If @seq has a data destroy
24245 * function associated with it, that function is called on all items
24254 * @iter: a #GSequenceIter
24256 * Returns the data that @iter points to.
24258 * Returns: the data that @iter points to
24264 * g_sequence_get_begin_iter:
24265 * @seq: a #GSequence
24267 * Returns the begin iterator for @seq.
24269 * Returns: the begin iterator for @seq.
24275 * g_sequence_get_end_iter:
24276 * @seq: a #GSequence
24278 * Returns the end iterator for @seg
24280 * Returns: the end iterator for @seq
24286 * g_sequence_get_iter_at_pos:
24287 * @seq: a #GSequence
24288 * @pos: a position in @seq, or -1 for the end
24290 * Returns the iterator at position @pos. If @pos is negative or larger
24291 * than the number of items in @seq, the end iterator is returned.
24293 * Returns: The #GSequenceIter at position @pos
24299 * g_sequence_get_length:
24300 * @seq: a #GSequence
24302 * Returns the length of @seq
24304 * Returns: the length of @seq
24310 * g_sequence_insert_before:
24311 * @iter: a #GSequenceIter
24312 * @data: the data for the new item
24314 * Inserts a new item just before the item pointed to by @iter.
24316 * Returns: an iterator pointing to the new item
24322 * g_sequence_insert_sorted:
24323 * @seq: a #GSequence
24324 * @data: the data to insert
24325 * @cmp_func: the function used to compare items in the sequence
24326 * @cmp_data: user data passed to @cmp_func.
24328 * Inserts @data into @sequence using @func to determine the new
24329 * position. The sequence must already be sorted according to @cmp_func;
24330 * otherwise the new position of @data is undefined.
24332 * @cmp_func is called with two items of the @seq and @user_data.
24333 * It should return 0 if the items are equal, a negative value
24334 * if the first item comes before the second, and a positive value
24335 * if the second item comes before the first.
24337 * Returns: a #GSequenceIter pointing to the new item.
24343 * g_sequence_insert_sorted_iter:
24344 * @seq: a #GSequence
24345 * @data: data for the new item
24346 * @iter_cmp: the function used to compare iterators in the sequence
24347 * @cmp_data: user data passed to @cmp_func
24349 * Like g_sequence_insert_sorted(), but uses
24350 * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
24351 * the compare function.
24353 * @iter_cmp is called with two iterators pointing into @seq.
24354 * It should return 0 if the iterators are equal, a negative
24355 * value if the first iterator comes before the second, and a
24356 * positive value if the second iterator comes before the first.
24358 * It is called with two iterators pointing into @seq. It should
24359 * return 0 if the iterators are equal, a negative value if the
24360 * first iterator comes before the second, and a positive value
24361 * if the second iterator comes before the first.
24363 * Returns: a #GSequenceIter pointing to the new item
24369 * g_sequence_iter_compare:
24370 * @a: a #GSequenceIter
24371 * @b: a #GSequenceIter
24373 * Returns a negative number if @a comes before @b, 0 if they are equal,
24374 * and a positive number if @a comes after @b.
24376 * The @a and @b iterators must point into the same sequence.
24378 * Returns: a negative number if @a comes before @b, 0 if they are
24379 * equal, and a positive number if @a comes after @b
24385 * g_sequence_iter_get_position:
24386 * @iter: a #GSequenceIter
24388 * Returns the position of @iter
24390 * Returns: the position of @iter
24396 * g_sequence_iter_get_sequence:
24397 * @iter: a #GSequenceIter
24399 * Returns the #GSequence that @iter points into.
24401 * Returns: the #GSequence that @iter points into
24407 * g_sequence_iter_is_begin:
24408 * @iter: a #GSequenceIter
24410 * Returns whether @iter is the begin iterator
24412 * Returns: whether @iter is the begin iterator
24418 * g_sequence_iter_is_end:
24419 * @iter: a #GSequenceIter
24421 * Returns whether @iter is the end iterator
24423 * Returns: Whether @iter is the end iterator
24429 * g_sequence_iter_move:
24430 * @iter: a #GSequenceIter
24431 * @delta: A positive or negative number indicating how many positions away
24432 * from @iter the returned #GSequenceIter will be
24434 * Returns the #GSequenceIter which is @delta positions away from @iter.
24435 * If @iter is closer than -@delta positions to the beginning of the sequence,
24436 * the begin iterator is returned. If @iter is closer than @delta positions
24437 * to the end of the sequence, the end iterator is returned.
24439 * Returns: a #GSequenceIter which is @delta positions away from @iter
24445 * g_sequence_iter_next:
24446 * @iter: a #GSequenceIter
24448 * Returns an iterator pointing to the next position after @iter.
24449 * If @iter is the end iterator, the end iterator is returned.
24451 * Returns: a #GSequenceIter pointing to the next position after @iter
24457 * g_sequence_iter_prev:
24458 * @iter: a #GSequenceIter
24460 * Returns an iterator pointing to the previous position before @iter.
24461 * If @iter is the begin iterator, the begin iterator is returned.
24463 * Returns: a #GSequenceIter pointing to the previous position
24470 * g_sequence_lookup:
24471 * @seq: a #GSequence
24472 * @data: data to lookup
24473 * @cmp_func: the function used to compare items in the sequence
24474 * @cmp_data: user data passed to @cmp_func
24476 * Returns an iterator pointing to the position of the first item found
24477 * equal to @data according to @cmp_func and @cmp_data. If more than one
24478 * item is equal, it is not guaranteed that it is the first which is
24479 * returned. In that case, you can use g_sequence_iter_next() and
24480 * g_sequence_iter_prev() to get others.
24482 * @cmp_func is called with two items of the @seq and @user_data.
24483 * It should return 0 if the items are equal, a negative value if
24484 * the first item comes before the second, and a positive value if
24485 * the second item comes before the first.
24487 * This function will fail if the data contained in the sequence is
24488 * unsorted. Use g_sequence_insert_sorted() or
24489 * g_sequence_insert_sorted_iter() to add data to your sequence or, if
24490 * you want to add a large amount of data, call g_sequence_sort() after
24491 * doing unsorted insertions.
24493 * Returns: an #GSequenceIter pointing to the position of the
24494 * first item found equal to @data according to @cmp_func and
24495 * @cmp_data, or %NULL if no such item exists
24501 * g_sequence_lookup_iter:
24502 * @seq: a #GSequence
24503 * @data: data to lookup
24504 * @iter_cmp: the function used to compare iterators in the sequence
24505 * @cmp_data: user data passed to @iter_cmp
24507 * Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc
24508 * instead of a #GCompareDataFunc as the compare function.
24510 * @iter_cmp is called with two iterators pointing into @seq.
24511 * It should return 0 if the iterators are equal, a negative value
24512 * if the first iterator comes before the second, and a positive
24513 * value if the second iterator comes before the first.
24515 * This function will fail if the data contained in the sequence is
24516 * unsorted. Use g_sequence_insert_sorted() or
24517 * g_sequence_insert_sorted_iter() to add data to your sequence or, if
24518 * you want to add a large amount of data, call g_sequence_sort() after
24519 * doing unsorted insertions.
24521 * Returns: an #GSequenceIter pointing to the position of
24522 * the first item found equal to @data according to @cmp_func
24523 * and @cmp_data, or %NULL if no such item exists
24530 * @src: a #GSequenceIter pointing to the item to move
24531 * @dest: a #GSequenceIter pointing to the position to which
24532 * the item is moved
24534 * Moves the item pointed to by @src to the position indicated by @dest.
24535 * After calling this function @dest will point to the position immediately
24536 * after @src. It is allowed for @src and @dest to point into different
24544 * g_sequence_move_range:
24545 * @dest: a #GSequenceIter
24546 * @begin: a #GSequenceIter
24547 * @end: a #GSequenceIter
24549 * Inserts the (@begin, @end) range at the destination pointed to by ptr.
24550 * The @begin and @end iters must point into the same sequence. It is
24551 * allowed for @dest to point to a different sequence than the one pointed
24552 * into by @begin and @end.
24554 * If @dest is NULL, the range indicated by @begin and @end is
24555 * removed from the sequence. If @dest iter points to a place within
24556 * the (@begin, @end) range, the range does not move.
24564 * @data_destroy: (allow-none): a #GDestroyNotify function, or %NULL
24566 * Creates a new GSequence. The @data_destroy function, if non-%NULL will
24567 * be called on all items when the sequence is destroyed and on items that
24568 * are removed from the sequence.
24570 * Returns: a new #GSequence
24576 * g_sequence_prepend:
24577 * @seq: a #GSequence
24578 * @data: the data for the new item
24580 * Adds a new item to the front of @seq
24582 * Returns: an iterator pointing to the new item
24588 * g_sequence_range_get_midpoint:
24589 * @begin: a #GSequenceIter
24590 * @end: a #GSequenceIter
24592 * Finds an iterator somewhere in the range (@begin, @end). This
24593 * iterator will be close to the middle of the range, but is not
24594 * guaranteed to be exactly in the middle.
24596 * The @begin and @end iterators must both point to the same sequence
24597 * and @begin must come before or be equal to @end in the sequence.
24599 * Returns: a #GSequenceIter pointing somewhere in the
24600 * (@begin, @end) range
24606 * g_sequence_remove:
24607 * @iter: a #GSequenceIter
24609 * Removes the item pointed to by @iter. It is an error to pass the
24610 * end iterator to this function.
24612 * If the sequence has a data destroy function associated with it, this
24613 * function is called on the data for the removed item.
24620 * g_sequence_remove_range:
24621 * @begin: a #GSequenceIter
24622 * @end: a #GSequenceIter
24624 * Removes all items in the (@begin, @end) range.
24626 * If the sequence has a data destroy function associated with it, this
24627 * function is called on the data for the removed items.
24634 * g_sequence_search:
24635 * @seq: a #GSequence
24636 * @data: data for the new item
24637 * @cmp_func: the function used to compare items in the sequence
24638 * @cmp_data: user data passed to @cmp_func
24640 * Returns an iterator pointing to the position where @data would
24641 * be inserted according to @cmp_func and @cmp_data.
24643 * @cmp_func is called with two items of the @seq and @user_data.
24644 * It should return 0 if the items are equal, a negative value if
24645 * the first item comes before the second, and a positive value if
24646 * the second item comes before the first.
24648 * If you are simply searching for an existing element of the sequence,
24649 * consider using g_sequence_lookup().
24651 * This function will fail if the data contained in the sequence is
24652 * unsorted. Use g_sequence_insert_sorted() or
24653 * g_sequence_insert_sorted_iter() to add data to your sequence or, if
24654 * you want to add a large amount of data, call g_sequence_sort() after
24655 * doing unsorted insertions.
24657 * Returns: an #GSequenceIter pointing to the position where @data
24658 * would have been inserted according to @cmp_func and @cmp_data
24664 * g_sequence_search_iter:
24665 * @seq: a #GSequence
24666 * @data: data for the new item
24667 * @iter_cmp: the function used to compare iterators in the sequence
24668 * @cmp_data: user data passed to @iter_cmp
24670 * Like g_sequence_search(), but uses a #GSequenceIterCompareFunc
24671 * instead of a #GCompareDataFunc as the compare function.
24673 * @iter_cmp is called with two iterators pointing into @seq.
24674 * It should return 0 if the iterators are equal, a negative value
24675 * if the first iterator comes before the second, and a positive
24676 * value if the second iterator comes before the first.
24678 * If you are simply searching for an existing element of the sequence,
24679 * consider using g_sequence_lookup_iter().
24681 * This function will fail if the data contained in the sequence is
24682 * unsorted. Use g_sequence_insert_sorted() or
24683 * g_sequence_insert_sorted_iter() to add data to your sequence or, if
24684 * you want to add a large amount of data, call g_sequence_sort() after
24685 * doing unsorted insertions.
24687 * Returns: a #GSequenceIter pointing to the position in @seq
24688 * where @data would have been inserted according to @iter_cmp
24696 * @iter: a #GSequenceIter
24697 * @data: new data for the item
24699 * Changes the data for the item pointed to by @iter to be @data. If
24700 * the sequence has a data destroy function associated with it, that
24701 * function is called on the existing data that @iter pointed to.
24709 * @seq: a #GSequence
24710 * @cmp_func: the function used to sort the sequence
24711 * @cmp_data: user data passed to @cmp_func
24713 * Sorts @seq using @cmp_func.
24715 * @cmp_func is passed two items of @seq and should
24716 * return 0 if they are equal, a negative value if the
24717 * first comes before the second, and a positive value
24718 * if the second comes before the first.
24725 * g_sequence_sort_changed:
24726 * @iter: A #GSequenceIter
24727 * @cmp_func: the function used to compare items in the sequence
24728 * @cmp_data: user data passed to @cmp_func.
24730 * Moves the data pointed to a new position as indicated by @cmp_func. This
24731 * function should be called for items in a sequence already sorted according
24732 * to @cmp_func whenever some aspect of an item changes so that @cmp_func
24733 * may return different values for that item.
24735 * @cmp_func is called with two items of the @seq and @user_data.
24736 * It should return 0 if the items are equal, a negative value if
24737 * the first item comes before the second, and a positive value if
24738 * the second item comes before the first.
24745 * g_sequence_sort_changed_iter:
24746 * @iter: a #GSequenceIter
24747 * @iter_cmp: the function used to compare iterators in the sequence
24748 * @cmp_data: user data passed to @cmp_func
24750 * Like g_sequence_sort_changed(), but uses
24751 * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
24752 * the compare function.
24754 * @iter_cmp is called with two iterators pointing into @seq. It should
24755 * return 0 if the iterators are equal, a negative value if the first
24756 * iterator comes before the second, and a positive value if the second
24757 * iterator comes before the first.
24764 * g_sequence_sort_iter:
24765 * @seq: a #GSequence
24766 * @cmp_func: the function used to compare iterators in the sequence
24767 * @cmp_data: user data passed to @cmp_func
24769 * Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead
24770 * of a GCompareDataFunc as the compare function
24772 * @cmp_func is called with two iterators pointing into @seq. It should
24773 * return 0 if the iterators are equal, a negative value if the first
24774 * iterator comes before the second, and a positive value if the second
24775 * iterator comes before the first.
24783 * @a: a #GSequenceIter
24784 * @b: a #GSequenceIter
24786 * Swaps the items pointed to by @a and @b. It is allowed for @a and @b
24787 * to point into difference sequences.
24794 * g_set_application_name:
24795 * @application_name: localized name of the application
24797 * Sets a human-readable name for the application. This name should be
24798 * localized if possible, and is intended for display to the user.
24799 * Contrast with g_set_prgname(), which sets a non-localized name.
24800 * g_set_prgname() will be called automatically by gtk_init(),
24801 * but g_set_application_name() will not.
24803 * Note that for thread safety reasons, this function can only
24806 * The application name will be used in contexts such as error messages,
24807 * or when displaying an application's name in the task list.
24815 * @err: (allow-none): a return location for a #GError, or %NULL
24816 * @domain: error domain
24817 * @code: error code
24818 * @format: printf()-style format
24819 * @...: args for @format
24821 * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
24822 * must be %NULL. A new #GError is created and assigned to *@err.
24827 * g_set_error_literal:
24828 * @err: (allow-none): a return location for a #GError, or %NULL
24829 * @domain: error domain
24830 * @code: error code
24831 * @message: error message
24833 * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
24834 * must be %NULL. A new #GError is created and assigned to *@err.
24835 * Unlike g_set_error(), @message is not a printf()-style format string.
24836 * Use this function if @message contains text you don't have control over,
24837 * that could include printf() escape sequences.
24845 * @prgname: the name of the program.
24847 * Sets the name of the program. This name should not be localized,
24848 * in contrast to g_set_application_name().
24850 * Note that for thread-safety reasons this function can only be called once.
24855 * g_set_print_handler:
24856 * @func: the new print handler
24858 * Sets the print handler.
24860 * Any messages passed to g_print() will be output via
24861 * the new handler. The default handler simply outputs
24862 * the message to stdout. By providing your own handler
24863 * you can redirect the output, to a GTK+ widget or a
24864 * log file for example.
24866 * Returns: the old print handler
24871 * g_set_printerr_handler:
24872 * @func: the new error message handler
24874 * Sets the handler for printing error messages.
24876 * Any messages passed to g_printerr() will be output via
24877 * the new handler. The default handler simply outputs the
24878 * message to stderr. By providing your own handler you can
24879 * redirect the output, to a GTK+ widget or a log file for
24882 * Returns: the old error message handler
24888 * @variable: the environment variable to set, must not contain '='.
24889 * @value: the value for to set the variable to.
24890 * @overwrite: whether to change the variable if it already exists.
24892 * Sets an environment variable. Both the variable's name and value
24893 * should be in the GLib file name encoding. On UNIX, this means that
24894 * they can be arbitrary byte strings. On Windows, they should be in
24897 * Note that on some systems, when variables are overwritten, the memory
24898 * used for the previous variables and its value isn't reclaimed.
24900 * You should be mindful fo the fact that environment variable handling
24901 * in UNIX is not thread-safe, and your program may crash if one thread
24902 * calls g_setenv() while another thread is calling getenv(). (And note
24903 * that many functions, such as gettext(), call getenv() internally.)
24904 * This function is only safe to use at the very start of your program,
24905 * before creating any other threads (or creating objects that create
24906 * worker threads of their own).
24908 * If you need to set up the environment for a child process, you can
24909 * use g_get_environ() to get an environment array, modify that with
24910 * g_environ_setenv() and g_environ_unsetenv(), and then pass that
24911 * array directly to execvpe(), g_spawn_async(), or the like.
24913 * Returns: %FALSE if the environment variable couldn't be set.
24919 * g_shell_parse_argv:
24920 * @command_line: command line to parse
24921 * @argcp: (out): return location for number of args
24922 * @argvp: (out) (array length=argcp zero-terminated=1): return location for array of args
24923 * @error: return location for error
24925 * Parses a command line into an argument vector, in much the same way
24926 * the shell would, but without many of the expansions the shell would
24927 * perform (variable expansion, globs, operators, filename expansion,
24928 * etc. are not supported). The results are defined to be the same as
24929 * those you would get from a UNIX98 /bin/sh, as long as the input
24930 * contains none of the unsupported shell expansions. If the input
24931 * does contain such expansions, they are passed through
24932 * literally. Possible errors are those from the #G_SHELL_ERROR
24933 * domain. Free the returned vector with g_strfreev().
24935 * Returns: %TRUE on success, %FALSE if error set
24941 * @unquoted_string: a literal string
24943 * Quotes a string so that the shell (/bin/sh) will interpret the
24944 * quoted string to mean @unquoted_string. If you pass a filename to
24945 * the shell, for example, you should first quote it with this
24946 * function. The return value must be freed with g_free(). The
24947 * quoting style used is undefined (single or double quotes may be
24950 * Returns: quoted string
24956 * @quoted_string: shell-quoted string
24957 * @error: error return location or NULL
24959 * Unquotes a string as the shell (/bin/sh) would. Only handles
24960 * quotes; if a string contains file globs, arithmetic operators,
24961 * variables, backticks, redirections, or other special-to-the-shell
24962 * features, the result will be different from the result a real shell
24963 * would produce (the variables, backticks, etc. will be passed
24964 * through literally instead of being expanded). This function is
24965 * guaranteed to succeed if applied to the result of
24966 * g_shell_quote(). If it fails, it returns %NULL and sets the
24967 * error. The @quoted_string need not actually contain quoted or
24968 * escaped text; g_shell_unquote() simply goes through the string and
24969 * unquotes/unescapes anything that the shell would. Both single and
24970 * double quotes are handled, as are escapes including escaped
24971 * newlines. The return value must be freed with g_free(). Possible
24972 * errors are in the #G_SHELL_ERROR domain.
24974 * Shell quoting rules are a bit strange. Single quotes preserve the
24975 * literal string exactly. escape sequences are not allowed; not even
24976 * \' - if you want a ' in the quoted text, you have to do something
24977 * like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to
24978 * be escaped with backslash. Otherwise double quotes preserve things
24981 * Returns: an unquoted string
24987 * @block_size: the number of bytes to allocate
24989 * Allocates a block of memory from the slice allocator.
24990 * The block adress handed out can be expected to be aligned
24991 * to at least 1 * sizeof (void*),
24992 * though in general slices are 2 * sizeof (void*) bytes aligned,
24993 * if a malloc() fallback implementation is used instead,
24994 * the alignment may be reduced in a libc dependent fashion.
24995 * Note that the underlying slice allocation mechanism can
24996 * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
24997 * environment variable.
24999 * Returns: a pointer to the allocated memory block
25006 * @block_size: the number of bytes to allocate
25008 * Allocates a block of memory via g_slice_alloc() and initializes
25009 * the returned memory to 0. Note that the underlying slice allocation
25010 * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
25011 * environment variable.
25013 * Returns: a pointer to the allocated block
25020 * @block_size: the number of bytes to allocate
25021 * @mem_block: the memory to copy
25023 * Allocates a block of memory from the slice allocator
25024 * and copies @block_size bytes into it from @mem_block.
25026 * Returns: a pointer to the allocated memory block
25033 * @type: the type to duplicate, typically a structure name
25034 * @mem: the memory to copy into the allocated block
25036 * A convenience macro to duplicate a block of memory using
25037 * the slice allocator.
25039 * It calls g_slice_copy() with `sizeof (@type)`
25040 * and casts the returned pointer to a pointer of the given type,
25041 * avoiding a type cast in the source code.
25042 * Note that the underlying slice allocation mechanism can
25043 * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
25044 * environment variable.
25046 * Returns: a pointer to the allocated block, cast to a pointer to @type
25053 * @type: the type of the block to free, typically a structure name
25054 * @mem: a pointer to the block to free
25056 * A convenience macro to free a block of memory that has
25057 * been allocated from the slice allocator.
25059 * It calls g_slice_free1() using `sizeof (type)`
25060 * as the block size.
25061 * Note that the exact release behaviour can be changed with the
25062 * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
25063 * [`G_SLICE`][G_SLICE] for related debugging options.
25071 * @block_size: the size of the block
25072 * @mem_block: a pointer to the block to free
25074 * Frees a block of memory.
25076 * The memory must have been allocated via g_slice_alloc() or
25077 * g_slice_alloc0() and the @block_size has to match the size
25078 * specified upon allocation. Note that the exact release behaviour
25079 * can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment
25080 * variable, also see [`G_SLICE`][G_SLICE] for related debugging options.
25087 * g_slice_free_chain:
25088 * @type: the type of the @mem_chain blocks
25089 * @mem_chain: a pointer to the first block of the chain
25090 * @next: the field name of the next pointer in @type
25092 * Frees a linked list of memory blocks of structure type @type.
25093 * The memory blocks must be equal-sized, allocated via
25094 * g_slice_alloc() or g_slice_alloc0() and linked together by
25095 * a @next pointer (similar to #GSList). The name of the
25096 * @next field in @type is passed as third argument.
25097 * Note that the exact release behaviour can be changed with the
25098 * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
25099 * [`G_SLICE`][G_SLICE] for related debugging options.
25106 * g_slice_free_chain_with_offset:
25107 * @block_size: the size of the blocks
25108 * @mem_chain: a pointer to the first block of the chain
25109 * @next_offset: the offset of the @next field in the blocks
25111 * Frees a linked list of memory blocks of structure type @type.
25113 * The memory blocks must be equal-sized, allocated via
25114 * g_slice_alloc() or g_slice_alloc0() and linked together by a
25115 * @next pointer (similar to #GSList). The offset of the @next
25116 * field in each block is passed as third argument.
25117 * Note that the exact release behaviour can be changed with the
25118 * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
25119 * [`G_SLICE`][G_SLICE] for related debugging options.
25127 * @type: the type to allocate, typically a structure name
25129 * A convenience macro to allocate a block of memory from the
25132 * It calls g_slice_alloc() with `sizeof (@type)` and casts the
25133 * returned pointer to a pointer of the given type, avoiding a type
25134 * cast in the source code. Note that the underlying slice allocation
25135 * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
25136 * environment variable.
25138 * Returns: a pointer to the allocated block, cast to a pointer to @type
25145 * @type: the type to allocate, typically a structure name
25147 * A convenience macro to allocate a block of memory from the
25148 * slice allocator and set the memory to 0.
25150 * It calls g_slice_alloc0() with `sizeof (@type)`
25151 * and casts the returned pointer to a pointer of the given type,
25152 * avoiding a type cast in the source code.
25153 * Note that the underlying slice allocation mechanism can
25154 * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
25155 * environment variable.
25164 * Allocates space for one #GSList element. It is called by the
25165 * g_slist_append(), g_slist_prepend(), g_slist_insert() and
25166 * g_slist_insert_sorted() functions and so is rarely used on its own.
25168 * Returns: a pointer to the newly-allocated #GSList element.
25175 * @data: the data for the new element
25177 * Adds a new element on to the end of the list.
25179 * The return value is the new start of the list, which may
25180 * have changed, so make sure you store the new value.
25182 * Note that g_slist_append() has to traverse the entire list
25183 * to find the end, which is inefficient when adding multiple
25184 * elements. A common idiom to avoid the inefficiency is to prepend
25185 * the elements and reverse the list when all elements have been added.
25187 * |[<!-- language="C" -->
25188 * // Notice that these are initialized to the empty list.
25189 * GSList *list = NULL, *number_list = NULL;
25191 * // This is a list of strings.
25192 * list = g_slist_append (list, "first");
25193 * list = g_slist_append (list, "second");
25195 * // This is a list of integers.
25196 * number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
25197 * number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
25200 * Returns: the new start of the #GSList
25206 * @list1: a #GSList
25207 * @list2: the #GSList to add to the end of the first #GSList
25209 * Adds the second #GSList onto the end of the first #GSList.
25210 * Note that the elements of the second #GSList are not copied.
25211 * They are used directly.
25213 * Returns: the start of the new #GSList
25221 * Copies a #GSList.
25223 * Note that this is a "shallow" copy. If the list elements
25224 * consist of pointers to data, the pointers are copied but
25225 * the actual data isn't. See g_slist_copy_deep() if you need
25226 * to copy the data as well.
25228 * Returns: a copy of @list
25233 * g_slist_copy_deep:
25235 * @func: a copy function used to copy every element in the list
25236 * @user_data: user data passed to the copy function @func, or #NULL
25238 * Makes a full (deep) copy of a #GSList.
25240 * In contrast with g_slist_copy(), this function uses @func to make a copy of
25241 * each list element, in addition to copying the list container itself.
25243 * @func, as a #GCopyFunc, takes two arguments, the data to be copied and a user
25244 * pointer. It's safe to pass #NULL as user_data, if the copy function takes only
25247 * For instance, if @list holds a list of GObjects, you can do:
25248 * |[<!-- language="C" -->
25249 * another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
25252 * And, to entirely free the new list, you could do:
25253 * |[<!-- language="C" -->
25254 * g_slist_free_full (another_list, g_object_unref);
25257 * Returns: a full copy of @list, use #g_slist_free_full to free it
25263 * g_slist_delete_link:
25265 * @link_: node to delete
25267 * Removes the node link_ from the list and frees it.
25268 * Compare this to g_slist_remove_link() which removes the node
25269 * without freeing it.
25271 * Removing arbitrary nodes from a singly-linked list requires time
25272 * that is proportional to the length of the list (ie. O(n)). If you
25273 * find yourself using g_slist_delete_link() frequently, you should
25274 * consider a different data structure, such as the doubly-linked
25277 * Returns: the new head of @list
25284 * @data: the element data to find
25286 * Finds the element in a #GSList which
25287 * contains the given data.
25289 * Returns: the found #GSList element,
25290 * or %NULL if it is not found
25295 * g_slist_find_custom:
25297 * @data: user data passed to the function
25298 * @func: the function to call for each element.
25299 * It should return 0 when the desired element is found
25301 * Finds an element in a #GSList, using a supplied function to
25302 * find the desired element. It iterates over the list, calling
25303 * the given function which should return 0 when the desired
25304 * element is found. The function takes two #gconstpointer arguments,
25305 * the #GSList element's data as the first argument and the
25308 * Returns: the found #GSList element, or %NULL if it is not found
25315 * @func: the function to call with each element's data
25316 * @user_data: user data to pass to the function
25318 * Calls a function for each element of a #GSList.
25326 * Frees all of the memory used by a #GSList.
25327 * The freed elements are returned to the slice allocator.
25329 * If list elements contain dynamically-allocated memory,
25330 * you should either use g_slist_free_full() or free them manually
25338 * A macro which does the same as g_slist_free_1().
25346 * @list: a #GSList element
25348 * Frees one #GSList element.
25349 * It is usually used after g_slist_remove_link().
25354 * g_slist_free_full:
25355 * @list: a pointer to a #GSList
25356 * @free_func: the function to be called to free each element's data
25358 * Convenience method, which frees all the memory used by a #GSList, and
25359 * calls the specified destroy function on every element's data.
25368 * @data: the data to find
25370 * Gets the position of the element containing
25371 * the given data (starting from 0).
25373 * Returns: the index of the element containing the data,
25374 * or -1 if the data is not found
25381 * @data: the data for the new element
25382 * @position: the position to insert the element.
25383 * If this is negative, or is larger than the number
25384 * of elements in the list, the new element is added on
25385 * to the end of the list.
25387 * Inserts a new element into the list at the given position.
25389 * Returns: the new start of the #GSList
25394 * g_slist_insert_before:
25395 * @slist: a #GSList
25396 * @sibling: node to insert @data before
25397 * @data: data to put in the newly-inserted node
25399 * Inserts a node before @sibling containing @data.
25401 * Returns: the new head of the list.
25406 * g_slist_insert_sorted:
25408 * @data: the data for the new element
25409 * @func: the function to compare elements in the list.
25410 * It should return a number > 0 if the first parameter
25411 * comes after the second parameter in the sort order.
25413 * Inserts a new element into the list, using the given
25414 * comparison function to determine its position.
25416 * Returns: the new start of the #GSList
25421 * g_slist_insert_sorted_with_data:
25423 * @data: the data for the new element
25424 * @func: the function to compare elements in the list.
25425 * It should return a number > 0 if the first parameter
25426 * comes after the second parameter in the sort order.
25427 * @user_data: data to pass to comparison function
25429 * Inserts a new element into the list, using the given
25430 * comparison function to determine its position.
25432 * Returns: the new start of the #GSList
25441 * Gets the last element in a #GSList.
25443 * This function iterates over the whole list.
25445 * Returns: the last element in the #GSList,
25446 * or %NULL if the #GSList has no elements
25454 * Gets the number of elements in a #GSList.
25456 * This function iterates over the whole list to
25457 * count its elements.
25459 * Returns: the number of elements in the #GSList
25465 * @slist: an element in a #GSList.
25467 * A convenience macro to get the next element in a #GSList.
25469 * Returns: the next element, or %NULL if there are no more elements.
25476 * @n: the position of the element, counting from 0
25478 * Gets the element at the given position in a #GSList.
25480 * Returns: the element, or %NULL if the position is off
25481 * the end of the #GSList
25486 * g_slist_nth_data:
25488 * @n: the position of the element
25490 * Gets the data of the element at the given position.
25492 * Returns: the element's data, or %NULL if the position
25493 * is off the end of the #GSList
25498 * g_slist_position:
25500 * @llink: an element in the #GSList
25502 * Gets the position of the given element
25503 * in the #GSList (starting from 0).
25505 * Returns: the position of the element in the #GSList,
25506 * or -1 if the element is not found
25513 * @data: the data for the new element
25515 * Adds a new element on to the start of the list.
25517 * The return value is the new start of the list, which
25518 * may have changed, so make sure you store the new value.
25520 * |[<!-- language="C" -->
25521 * // Notice that it is initialized to the empty list.
25522 * GSList *list = NULL;
25523 * list = g_slist_prepend (list, "last");
25524 * list = g_slist_prepend (list, "first");
25527 * Returns: the new start of the #GSList
25534 * @data: the data of the element to remove
25536 * Removes an element from a #GSList.
25537 * If two elements contain the same data, only the first is removed.
25538 * If none of the elements contain the data, the #GSList is unchanged.
25540 * Returns: the new start of the #GSList
25545 * g_slist_remove_all:
25547 * @data: data to remove
25549 * Removes all list nodes with data equal to @data.
25550 * Returns the new head of the list. Contrast with
25551 * g_slist_remove() which removes only the first node
25552 * matching the given data.
25554 * Returns: new head of @list
25559 * g_slist_remove_link:
25561 * @link_: an element in the #GSList
25563 * Removes an element from a #GSList, without
25564 * freeing the element. The removed element's next
25565 * link is set to %NULL, so that it becomes a
25566 * self-contained list with one element.
25568 * Removing arbitrary nodes from a singly-linked list
25569 * requires time that is proportional to the length of the list
25570 * (ie. O(n)). If you find yourself using g_slist_remove_link()
25571 * frequently, you should consider a different data structure,
25572 * such as the doubly-linked #GList.
25574 * Returns: the new start of the #GSList, without the element
25582 * Reverses a #GSList.
25584 * Returns: the start of the reversed #GSList
25591 * @compare_func: the comparison function used to sort the #GSList.
25592 * This function is passed the data from 2 elements of the #GSList
25593 * and should return 0 if they are equal, a negative value if the
25594 * first element comes before the second, or a positive value if
25595 * the first element comes after the second.
25597 * Sorts a #GSList using the given comparison function.
25599 * Returns: the start of the sorted #GSList
25604 * g_slist_sort_with_data:
25606 * @compare_func: comparison function
25607 * @user_data: data to pass to comparison function
25609 * Like g_slist_sort(), but the sort function accepts a user data argument.
25611 * Returns: new head of the list
25617 * @string: the buffer to hold the output.
25618 * @n: the maximum number of bytes to produce (including the
25619 * terminating nul character).
25620 * @format: a standard printf() format string, but notice
25621 * [string precision pitfalls][string-precision]
25622 * @...: the arguments to insert in the output.
25624 * A safer form of the standard sprintf() function. The output is guaranteed
25625 * to not exceed @n characters (including the terminating nul character), so
25626 * it is easy to ensure that a buffer overflow cannot occur.
25628 * See also g_strdup_printf().
25630 * In versions of GLib prior to 1.2.3, this function may return -1 if the
25631 * output was truncated, and the truncated string may not be nul-terminated.
25632 * In versions prior to 1.3.12, this function returns the length of the output
25635 * The return value of g_snprintf() conforms to the snprintf()
25636 * function as standardized in ISO C99. Note that this is different from
25637 * traditional snprintf(), which returns the length of the output string.
25639 * The format string may contain positional parameters, as specified in
25640 * the Single Unix Specification.
25642 * Returns: the number of bytes which would be produced if the buffer
25643 * was large enough.
25648 * g_source_add_child_source:
25649 * @source: a #GSource
25650 * @child_source: a second #GSource that @source should "poll"
25652 * Adds @child_source to @source as a "polled" source; when @source is
25653 * added to a #GMainContext, @child_source will be automatically added
25654 * with the same priority, when @child_source is triggered, it will
25655 * cause @source to dispatch (in addition to calling its own
25656 * callback), and when @source is destroyed, it will destroy
25657 * @child_source as well. (@source will also still be dispatched if
25658 * its own prepare/check functions indicate that it is ready.)
25660 * If you don't need @child_source to do anything on its own when it
25661 * triggers, you can call g_source_set_dummy_callback() on it to set a
25662 * callback that does nothing (except return %TRUE if appropriate).
25664 * @source will hold a reference on @child_source while @child_source
25665 * is attached to it.
25667 * This API is only intended to be used by implementations of #GSource.
25668 * Do not call this API on a #GSource that you did not create.
25675 * g_source_add_poll:
25676 * @source: a #GSource
25677 * @fd: a #GPollFD structure holding information about a file
25678 * descriptor to watch.
25680 * Adds a file descriptor to the set of file descriptors polled for
25681 * this source. This is usually combined with g_source_new() to add an
25682 * event source. The event source's check function will typically test
25683 * the @revents field in the #GPollFD struct and return %TRUE if events need
25686 * This API is only intended to be used by implementations of #GSource.
25687 * Do not call this API on a #GSource that you did not create.
25689 * Using this API forces the linear scanning of event sources on each
25690 * main loop iteration. Newly-written event sources should try to use
25691 * g_source_add_unix_fd() instead of this API.
25696 * g_source_add_unix_fd:
25697 * @source: a #GSource
25698 * @fd: the fd to monitor
25699 * @events: an event mask
25701 * Monitors @fd for the IO events in @events.
25703 * The tag returned by this function can be used to remove or modify the
25704 * monitoring of the fd using g_source_remove_unix_fd() or
25705 * g_source_modify_unix_fd().
25707 * It is not necessary to remove the fd before destroying the source; it
25708 * will be cleaned up automatically.
25710 * This API is only intended to be used by implementations of #GSource.
25711 * Do not call this API on a #GSource that you did not create.
25713 * As the name suggests, this function is not available on Windows.
25715 * Returns: an opaque tag
25722 * @source: a #GSource
25723 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
25725 * Adds a #GSource to a @context so that it will be executed within
25726 * that context. Remove it by calling g_source_destroy().
25728 * Returns: the ID (greater than 0) for the source within the
25734 * g_source_destroy:
25735 * @source: a #GSource
25737 * Removes a source from its #GMainContext, if any, and mark it as
25738 * destroyed. The source cannot be subsequently added to another
25739 * context. It is safe to call this on sources which have already been
25740 * removed from their context.
25745 * g_source_get_can_recurse:
25746 * @source: a #GSource
25748 * Checks whether a source is allowed to be called recursively.
25749 * see g_source_set_can_recurse().
25751 * Returns: whether recursion is allowed.
25756 * g_source_get_context:
25757 * @source: a #GSource
25759 * Gets the #GMainContext with which the source is associated.
25761 * You can call this on a source that has been destroyed, provided
25762 * that the #GMainContext it was attached to still exists (in which
25763 * case it will return that #GMainContext). In particular, you can
25764 * always call this function on the source returned from
25765 * g_main_current_source(). But calling this function on a source
25766 * whose #GMainContext has been destroyed is an error.
25768 * Returns: (transfer none) (allow-none): the #GMainContext with which the
25769 * source is associated, or %NULL if the context has not
25770 * yet been added to a source.
25775 * g_source_get_current_time:
25776 * @source: a #GSource
25777 * @timeval: #GTimeVal structure in which to store current time.
25779 * This function ignores @source and is otherwise the same as
25780 * g_get_current_time().
25782 * Deprecated: 2.28: use g_source_get_time() instead
25788 * @source: a #GSource
25790 * Returns the numeric ID for a particular source. The ID of a source
25791 * is a positive integer which is unique within a particular main loop
25792 * context. The reverse
25793 * mapping from ID to source is done by g_main_context_find_source_by_id().
25795 * Returns: the ID (greater than 0) for the source
25800 * g_source_get_name:
25801 * @source: a #GSource
25803 * Gets a name for the source, used in debugging and profiling.
25804 * The name may be #NULL if it has never been set with
25805 * g_source_set_name().
25807 * Returns: the name of the source
25813 * g_source_get_priority:
25814 * @source: a #GSource
25816 * Gets the priority of a source.
25818 * Returns: the priority of the source
25823 * g_source_get_ready_time:
25824 * @source: a #GSource
25826 * Gets the "ready time" of @source, as set by
25827 * g_source_set_ready_time().
25829 * Any time before the current monotonic time (including 0) is an
25830 * indication that the source will fire immediately.
25832 * Returns: the monotonic ready time, -1 for "never"
25837 * g_source_get_time:
25838 * @source: a #GSource
25840 * Gets the time to be used when checking this source. The advantage of
25841 * calling this function over calling g_get_monotonic_time() directly is
25842 * that when checking multiple sources, GLib can cache a single value
25843 * instead of having to repeatedly get the system monotonic time.
25845 * The time here is the system monotonic time, if available, or some
25846 * other reasonable alternative otherwise. See g_get_monotonic_time().
25848 * Returns: the monotonic time in microseconds
25854 * g_source_is_destroyed:
25855 * @source: a #GSource
25857 * Returns whether @source has been destroyed.
25859 * This is important when you operate upon your objects
25860 * from within idle handlers, but may have freed the object
25861 * before the dispatch of your idle handler.
25863 * |[<!-- language="C" -->
25865 * idle_callback (gpointer data)
25867 * SomeWidget *self = data;
25869 * GDK_THREADS_ENTER ();
25870 * // do stuff with self
25871 * self->idle_id = 0;
25872 * GDK_THREADS_LEAVE ();
25874 * return G_SOURCE_REMOVE;
25878 * some_widget_do_stuff_later (SomeWidget *self)
25880 * self->idle_id = g_idle_add (idle_callback, self);
25884 * some_widget_finalize (GObject *object)
25886 * SomeWidget *self = SOME_WIDGET (object);
25888 * if (self->idle_id)
25889 * g_source_remove (self->idle_id);
25891 * G_OBJECT_CLASS (parent_class)->finalize (object);
25895 * This will fail in a multi-threaded application if the
25896 * widget is destroyed before the idle handler fires due
25897 * to the use after free in the callback. A solution, to
25898 * this particular problem, is to check to if the source
25899 * has already been destroy within the callback.
25901 * |[<!-- language="C" -->
25903 * idle_callback (gpointer data)
25905 * SomeWidget *self = data;
25907 * GDK_THREADS_ENTER ();
25908 * if (!g_source_is_destroyed (g_main_current_source ()))
25910 * // do stuff with self
25912 * GDK_THREADS_LEAVE ();
25918 * Returns: %TRUE if the source has been destroyed
25924 * g_source_modify_unix_fd:
25925 * @source: a #GSource
25926 * @tag: the tag from g_source_add_unix_fd()
25927 * @new_events: the new event mask to watch
25929 * Updates the event mask to watch for the fd identified by @tag.
25931 * @tag is the tag returned from g_source_add_unix_fd().
25933 * If you want to remove a fd, don't set its event mask to zero.
25934 * Instead, call g_source_remove_unix_fd().
25936 * This API is only intended to be used by implementations of #GSource.
25937 * Do not call this API on a #GSource that you did not create.
25939 * As the name suggests, this function is not available on Windows.
25947 * @source_funcs: structure containing functions that implement
25948 * the sources behavior.
25949 * @struct_size: size of the #GSource structure to create.
25951 * Creates a new #GSource structure. The size is specified to
25952 * allow creating structures derived from #GSource that contain
25953 * additional data. The size passed in must be at least
25954 * `sizeof (GSource)`.
25956 * The source will not initially be associated with any #GMainContext
25957 * and must be added to one with g_source_attach() before it will be
25960 * Returns: the newly-created #GSource.
25965 * g_source_query_unix_fd:
25966 * @source: a #GSource
25967 * @tag: the tag from g_source_add_unix_fd()
25969 * Queries the events reported for the fd corresponding to @tag on
25970 * @source during the last poll.
25972 * The return value of this function is only defined when the function
25973 * is called from the check or dispatch functions for @source.
25975 * This API is only intended to be used by implementations of #GSource.
25976 * Do not call this API on a #GSource that you did not create.
25978 * As the name suggests, this function is not available on Windows.
25980 * Returns: the conditions reported on the fd
25987 * @source: a #GSource
25989 * Increases the reference count on a source by one.
25997 * @tag: the ID of the source to remove.
25999 * Removes the source with the given id from the default main context.
26001 * The id of a #GSource is given by g_source_get_id(), or will be
26002 * returned by the functions g_source_attach(), g_idle_add(),
26003 * g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
26004 * g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
26005 * g_io_add_watch_full().
26007 * See also g_source_destroy(). You must use g_source_destroy() for sources
26008 * added to a non-default main context.
26010 * It is a programmer error to attempt to remove a non-existent source.
26012 * Returns: For historical reasons, this function always returns %TRUE
26017 * g_source_remove_by_funcs_user_data:
26018 * @funcs: The @source_funcs passed to g_source_new()
26019 * @user_data: the user data for the callback
26021 * Removes a source from the default main loop context given the
26022 * source functions and user data. If multiple sources exist with the
26023 * same source functions and user data, only one will be destroyed.
26025 * Returns: %TRUE if a source was found and removed.
26030 * g_source_remove_by_user_data:
26031 * @user_data: the user_data for the callback.
26033 * Removes a source from the default main loop context given the user
26034 * data for the callback. If multiple sources exist with the same user
26035 * data, only one will be destroyed.
26037 * Returns: %TRUE if a source was found and removed.
26042 * g_source_remove_child_source:
26043 * @source: a #GSource
26044 * @child_source: a #GSource previously passed to
26045 * g_source_add_child_source().
26047 * Detaches @child_source from @source and destroys it.
26049 * This API is only intended to be used by implementations of #GSource.
26050 * Do not call this API on a #GSource that you did not create.
26057 * g_source_remove_poll:
26058 * @source: a #GSource
26059 * @fd: a #GPollFD structure previously passed to g_source_add_poll().
26061 * Removes a file descriptor from the set of file descriptors polled for
26064 * This API is only intended to be used by implementations of #GSource.
26065 * Do not call this API on a #GSource that you did not create.
26070 * g_source_remove_unix_fd:
26071 * @source: a #GSource
26072 * @tag: the tag from g_source_add_unix_fd()
26074 * Reverses the effect of a previous call to g_source_add_unix_fd().
26076 * You only need to call this if you want to remove an fd from being
26077 * watched while keeping the same source around. In the normal case you
26078 * will just want to destroy the source.
26080 * This API is only intended to be used by implementations of #GSource.
26081 * Do not call this API on a #GSource that you did not create.
26083 * As the name suggests, this function is not available on Windows.
26090 * g_source_set_callback:
26091 * @source: the source
26092 * @func: a callback function
26093 * @data: the data to pass to callback function
26094 * @notify: (allow-none): a function to call when @data is no longer in use, or %NULL.
26096 * Sets the callback function for a source. The callback for a source is
26097 * called from the source's dispatch function.
26099 * The exact type of @func depends on the type of source; ie. you
26100 * should not count on @func being called with @data as its first
26103 * Typically, you won't use this function. Instead use functions specific
26104 * to the type of source you are using.
26109 * g_source_set_callback_indirect:
26110 * @source: the source
26111 * @callback_data: pointer to callback data "object"
26112 * @callback_funcs: functions for reference counting @callback_data
26113 * and getting the callback and data
26115 * Sets the callback function storing the data as a refcounted callback
26116 * "object". This is used internally. Note that calling
26117 * g_source_set_callback_indirect() assumes
26118 * an initial reference count on @callback_data, and thus
26119 * @callback_funcs->unref will eventually be called once more
26120 * than @callback_funcs->ref.
26125 * g_source_set_can_recurse:
26126 * @source: a #GSource
26127 * @can_recurse: whether recursion is allowed for this source
26129 * Sets whether a source can be called recursively. If @can_recurse is
26130 * %TRUE, then while the source is being dispatched then this source
26131 * will be processed normally. Otherwise, all processing of this
26132 * source is blocked until the dispatch function returns.
26137 * g_source_set_funcs:
26138 * @source: a #GSource
26139 * @funcs: the new #GSourceFuncs
26141 * Sets the source functions (can be used to override
26142 * default implementations) of an unattached source.
26149 * g_source_set_name:
26150 * @source: a #GSource
26151 * @name: debug name for the source
26153 * Sets a name for the source, used in debugging and profiling.
26154 * The name defaults to #NULL.
26156 * The source name should describe in a human-readable way
26157 * what the source does. For example, "X11 event queue"
26158 * or "GTK+ repaint idle handler" or whatever it is.
26160 * It is permitted to call this function multiple times, but is not
26161 * recommended due to the potential performance impact. For example,
26162 * one could change the name in the "check" function of a #GSourceFuncs
26163 * to include details like the event type in the source name.
26170 * g_source_set_name_by_id:
26171 * @tag: a #GSource ID
26172 * @name: debug name for the source
26174 * Sets the name of a source using its ID.
26176 * This is a convenience utility to set source names from the return
26177 * value of g_idle_add(), g_timeout_add(), etc.
26184 * g_source_set_priority:
26185 * @source: a #GSource
26186 * @priority: the new priority.
26188 * Sets the priority of a source. While the main loop is being run, a
26189 * source will be dispatched if it is ready to be dispatched and no
26190 * sources at a higher (numerically smaller) priority are ready to be
26193 * A child source always has the same priority as its parent. It is not
26194 * permitted to change the priority of a source once it has been added
26195 * as a child of another source.
26200 * g_source_set_ready_time:
26201 * @source: a #GSource
26202 * @ready_time: the monotonic time at which the source will be ready,
26203 * 0 for "immediately", -1 for "never"
26205 * Sets a #GSource to be dispatched when the given monotonic time is
26206 * reached (or passed). If the monotonic time is in the past (as it
26207 * always will be if @ready_time is 0) then the source will be
26208 * dispatched immediately.
26210 * If @ready_time is -1 then the source is never woken up on the basis
26211 * of the passage of time.
26213 * Dispatching the source does not reset the ready time. You should do
26214 * so yourself, from the source dispatch function.
26216 * Note that if you have a pair of sources where the ready time of one
26217 * suggests that it will be delivered first but the priority for the
26218 * other suggests that it would be delivered first, and the ready time
26219 * for both sources is reached during the same main context iteration
26220 * then the order of dispatch is undefined.
26222 * This API is only intended to be used by implementations of #GSource.
26223 * Do not call this API on a #GSource that you did not create.
26231 * @source: a #GSource
26233 * Decreases the reference count of a source by one. If the
26234 * resulting reference count is zero the source and associated
26235 * memory will be destroyed.
26240 * g_spaced_primes_closest:
26243 * Gets the smallest prime number from a built-in array of primes which
26244 * is larger than @num. This is used within GLib to calculate the optimum
26245 * size of a #GHashTable.
26247 * The built-in array of primes ranges from 11 to 13845163 such that
26248 * each prime is approximately 1.5-2 times the previous prime.
26250 * Returns: the smallest prime number from a built-in array of primes
26251 * which is larger than @num
26257 * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's
26258 * @argv: (array zero-terminated=1): child's argument vector
26259 * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
26260 * @flags: flags from #GSpawnFlags
26261 * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
26262 * @user_data: (closure): user data for @child_setup
26263 * @child_pid: (out) (allow-none): return location for child process reference, or %NULL
26264 * @error: return location for error
26266 * See g_spawn_async_with_pipes() for a full description; this function
26267 * simply calls the g_spawn_async_with_pipes() without any pipes.
26269 * You should call g_spawn_close_pid() on the returned child process
26270 * reference when you don't need it any more.
26272 * If you are writing a GTK+ application, and the program you are
26273 * spawning is a graphical application, too, then you may want to
26274 * use gdk_spawn_on_screen() instead to ensure that the spawned program
26275 * opens its windows on the right screen.
26277 * Note that the returned @child_pid on Windows is a handle to the child
26278 * process and not its identifier. Process handles and process identifiers
26279 * are different concepts on Windows.
26281 * Returns: %TRUE on success, %FALSE if error is set
26286 * g_spawn_async_with_pipes:
26287 * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
26288 * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding
26289 * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
26290 * @flags: flags from #GSpawnFlags
26291 * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
26292 * @user_data: (closure): user data for @child_setup
26293 * @child_pid: (out) (allow-none): return location for child process ID, or %NULL
26294 * @standard_input: (out) (allow-none): return location for file descriptor to write to child's stdin, or %NULL
26295 * @standard_output: (out) (allow-none): return location for file descriptor to read child's stdout, or %NULL
26296 * @standard_error: (out) (allow-none): return location for file descriptor to read child's stderr, or %NULL
26297 * @error: return location for error
26299 * Executes a child program asynchronously (your program will not
26300 * block waiting for the child to exit). The child program is
26301 * specified by the only argument that must be provided, @argv.
26302 * @argv should be a %NULL-terminated array of strings, to be passed
26303 * as the argument vector for the child. The first string in @argv
26304 * is of course the name of the program to execute. By default, the
26305 * name of the program must be a full path. If @flags contains the
26306 * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
26307 * used to search for the executable. If @flags contains the
26308 * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
26309 * @envp is used to search for the executable. If both the
26310 * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
26311 * are set, the `PATH` variable from @envp takes precedence over
26312 * the environment variable.
26314 * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
26315 * used, then the program will be run from the current directory (or
26316 * @working_directory, if specified); this might be unexpected or even
26317 * dangerous in some cases when the current directory is world-writable.
26319 * On Windows, note that all the string or string vector arguments to
26320 * this function and the other g_spawn*() functions are in UTF-8, the
26321 * GLib file name encoding. Unicode characters that are not part of
26322 * the system codepage passed in these arguments will be correctly
26323 * available in the spawned program only if it uses wide character API
26324 * to retrieve its command line. For C programs built with Microsoft's
26325 * tools it is enough to make the program have a wmain() instead of
26326 * main(). wmain() has a wide character argument vector as parameter.
26328 * At least currently, mingw doesn't support wmain(), so if you use
26329 * mingw to develop the spawned program, it will have to call the
26330 * undocumented function __wgetmainargs() to get the wide character
26331 * argument vector and environment. See gspawn-win32-helper.c in the
26332 * GLib sources or init.c in the mingw runtime sources for a prototype
26333 * for that function. Alternatively, you can retrieve the Win32 system
26334 * level wide character command line passed to the spawned program
26335 * using the GetCommandLineW() function.
26337 * On Windows the low-level child process creation API CreateProcess()
26338 * doesn't use argument vectors, but a command line. The C runtime
26339 * library's spawn*() family of functions (which g_spawn_async_with_pipes()
26340 * eventually calls) paste the argument vector elements together into
26341 * a command line, and the C runtime startup code does a corresponding
26342 * reconstruction of an argument vector from the command line, to be
26343 * passed to main(). Complications arise when you have argument vector
26344 * elements that contain spaces of double quotes. The spawn*() functions
26345 * don't do any quoting or escaping, but on the other hand the startup
26346 * code does do unquoting and unescaping in order to enable receiving
26347 * arguments with embedded spaces or double quotes. To work around this
26348 * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
26349 * argument vector elements that need it before calling the C runtime
26350 * spawn() function.
26352 * The returned @child_pid on Windows is a handle to the child
26353 * process, not its identifier. Process handles and process
26354 * identifiers are different concepts on Windows.
26356 * @envp is a %NULL-terminated array of strings, where each string
26357 * has the form `KEY=VALUE`. This will become the child's environment.
26358 * If @envp is %NULL, the child inherits its parent's environment.
26360 * @flags should be the bitwise OR of any flags you want to affect the
26361 * function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
26362 * child will not automatically be reaped; you must use a child watch to
26363 * be notified about the death of the child process. Eventually you must
26364 * call g_spawn_close_pid() on the @child_pid, in order to free
26365 * resources which may be associated with the child process. (On Unix,
26366 * using a child watch is equivalent to calling waitpid() or handling
26367 * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
26368 * is equivalent to calling CloseHandle() on the process handle returned
26369 * in @child_pid). See g_child_watch_add().
26371 * %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file
26372 * descriptors will be inherited by the child; otherwise all descriptors
26373 * except stdin/stdout/stderr will be closed before calling exec() in
26374 * the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
26375 * absolute path, it will be looked for in the `PATH` environment
26376 * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
26377 * absolute path, it will be looked for in the `PATH` variable from
26378 * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
26379 * are used, the value from @envp takes precedence over the environment.
26380 * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
26381 * will be discarded, instead of going to the same location as the parent's
26382 * standard output. If you use this flag, @standard_output must be %NULL.
26383 * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
26384 * will be discarded, instead of going to the same location as the parent's
26385 * standard error. If you use this flag, @standard_error must be %NULL.
26386 * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
26387 * standard input (by default, the child's standard input is attached to
26388 * /dev/null). If you use this flag, @standard_input must be %NULL.
26389 * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
26390 * the file to execute, while the remaining elements are the actual
26391 * argument vector to pass to the file. Normally g_spawn_async_with_pipes()
26392 * uses @argv[0] as the file to execute, and passes all of @argv to the child.
26394 * @child_setup and @user_data are a function and user data. On POSIX
26395 * platforms, the function is called in the child after GLib has
26396 * performed all the setup it plans to perform (including creating
26397 * pipes, closing file descriptors, etc.) but before calling exec().
26398 * That is, @child_setup is called just before calling exec() in the
26399 * child. Obviously actions taken in this function will only affect
26400 * the child, not the parent.
26402 * On Windows, there is no separate fork() and exec() functionality.
26403 * Child processes are created and run with a single API call,
26404 * CreateProcess(). There is no sensible thing @child_setup
26405 * could be used for on Windows so it is ignored and not called.
26407 * If non-%NULL, @child_pid will on Unix be filled with the child's
26408 * process ID. You can use the process ID to send signals to the child,
26409 * or to use g_child_watch_add() (or waitpid()) if you specified the
26410 * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
26411 * filled with a handle to the child process only if you specified the
26412 * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
26413 * process using the Win32 API, for example wait for its termination
26414 * with the WaitFor*() functions, or examine its exit code with
26415 * GetExitCodeProcess(). You should close the handle with CloseHandle()
26416 * or g_spawn_close_pid() when you no longer need it.
26418 * If non-%NULL, the @standard_input, @standard_output, @standard_error
26419 * locations will be filled with file descriptors for writing to the child's
26420 * standard input or reading from its standard output or standard error.
26421 * The caller of g_spawn_async_with_pipes() must close these file descriptors
26422 * when they are no longer in use. If these parameters are %NULL, the
26423 * corresponding pipe won't be created.
26425 * If @standard_input is NULL, the child's standard input is attached to
26426 * /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
26428 * If @standard_error is NULL, the child's standard error goes to the same
26429 * location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
26432 * If @standard_output is NULL, the child's standard output goes to the same
26433 * location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL
26436 * @error can be %NULL to ignore errors, or non-%NULL to report errors.
26437 * If an error is set, the function returns %FALSE. Errors are reported
26438 * even if they occur in the child (for example if the executable in
26439 * @argv[0] is not found). Typically the `message` field of returned
26440 * errors should be displayed to users. Possible errors are those from
26441 * the #G_SPAWN_ERROR domain.
26443 * If an error occurs, @child_pid, @standard_input, @standard_output,
26444 * and @standard_error will not be filled with valid values.
26446 * If @child_pid is not %NULL and an error does not occur then the returned
26447 * process reference must be closed using g_spawn_close_pid().
26449 * If you are writing a GTK+ application, and the program you
26450 * are spawning is a graphical application, too, then you may
26451 * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
26452 * the spawned program opens its windows on the right screen.
26454 * Returns: %TRUE on success, %FALSE if an error was set
26459 * g_spawn_check_exit_status:
26460 * @exit_status: An exit code as returned from g_spawn_sync()
26461 * @error: a #GError
26463 * Set @error if @exit_status indicates the child exited abnormally
26464 * (e.g. with a nonzero exit code, or via a fatal signal).
26466 * The g_spawn_sync() and g_child_watch_add() family of APIs return an
26467 * exit status for subprocesses encoded in a platform-specific way.
26468 * On Unix, this is guaranteed to be in the same format waitpid() returns,
26469 * and on Windows it is guaranteed to be the result of GetExitCodeProcess().
26471 * Prior to the introduction of this function in GLib 2.34, interpreting
26472 * @exit_status required use of platform-specific APIs, which is problematic
26473 * for software using GLib as a cross-platform layer.
26475 * Additionally, many programs simply want to determine whether or not
26476 * the child exited successfully, and either propagate a #GError or
26477 * print a message to standard error. In that common case, this function
26478 * can be used. Note that the error message in @error will contain
26479 * human-readable information about the exit status.
26481 * The @domain and @code of @error have special semantics in the case
26482 * where the process has an "exit code", as opposed to being killed by
26483 * a signal. On Unix, this happens if WIFEXITED() would be true of
26484 * @exit_status. On Windows, it is always the case.
26486 * The special semantics are that the actual exit code will be the
26487 * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.
26488 * This allows you to differentiate between different exit codes.
26490 * If the process was terminated by some means other than an exit
26491 * status, the domain will be %G_SPAWN_ERROR, and the code will be
26492 * %G_SPAWN_ERROR_FAILED.
26494 * This function just offers convenience; you can of course also check
26495 * the available platform via a macro such as %G_OS_UNIX, and use
26496 * WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt
26497 * to scan or parse the error message string; it may be translated and/or
26498 * change in future versions of GLib.
26500 * Returns: %TRUE if child exited successfully, %FALSE otherwise (and
26501 * @error will be set)
26507 * g_spawn_close_pid:
26508 * @pid: The process reference to close
26510 * On some platforms, notably Windows, the #GPid type represents a resource
26511 * which must be closed to prevent resource leaking. g_spawn_close_pid()
26512 * is provided for this purpose. It should be used on all platforms, even
26513 * though it doesn't do anything under UNIX.
26518 * g_spawn_command_line_async:
26519 * @command_line: a command line
26520 * @error: return location for errors
26522 * A simple version of g_spawn_async() that parses a command line with
26523 * g_shell_parse_argv() and passes it to g_spawn_async(). Runs a
26524 * command line in the background. Unlike g_spawn_async(), the
26525 * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
26526 * that %G_SPAWN_SEARCH_PATH can have security implications, so
26527 * consider using g_spawn_async() directly if appropriate. Possible
26528 * errors are those from g_shell_parse_argv() and g_spawn_async().
26530 * The same concerns on Windows apply as for g_spawn_command_line_sync().
26532 * Returns: %TRUE on success, %FALSE if error is set
26537 * g_spawn_command_line_sync:
26538 * @command_line: a command line
26539 * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child output
26540 * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child errors
26541 * @exit_status: (out) (allow-none): return location for child exit status, as returned by waitpid()
26542 * @error: return location for errors
26544 * A simple version of g_spawn_sync() with little-used parameters
26545 * removed, taking a command line instead of an argument vector. See
26546 * g_spawn_sync() for full details. @command_line will be parsed by
26547 * g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag
26548 * is enabled. Note that %G_SPAWN_SEARCH_PATH can have security
26549 * implications, so consider using g_spawn_sync() directly if
26550 * appropriate. Possible errors are those from g_spawn_sync() and those
26551 * from g_shell_parse_argv().
26553 * If @exit_status is non-%NULL, the platform-specific exit status of
26554 * the child is stored there; see the documentation of
26555 * g_spawn_check_exit_status() for how to use and interpret this.
26557 * On Windows, please note the implications of g_shell_parse_argv()
26558 * parsing @command_line. Parsing is done according to Unix shell rules, not
26559 * Windows command interpreter rules.
26560 * Space is a separator, and backslashes are
26561 * special. Thus you cannot simply pass a @command_line containing
26562 * canonical Windows paths, like "c:\\program files\\app\\app.exe", as
26563 * the backslashes will be eaten, and the space will act as a
26564 * separator. You need to enclose such paths with single quotes, like
26565 * "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".
26567 * Returns: %TRUE on success, %FALSE if an error was set
26573 * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's
26574 * @argv: (array zero-terminated=1): child's argument vector
26575 * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
26576 * @flags: flags from #GSpawnFlags
26577 * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
26578 * @user_data: (closure): user data for @child_setup
26579 * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child output, or %NULL
26580 * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child error messages, or %NULL
26581 * @exit_status: (out) (allow-none): return location for child exit status, as returned by waitpid(), or %NULL
26582 * @error: return location for error, or %NULL
26584 * Executes a child synchronously (waits for the child to exit before returning).
26585 * All output from the child is stored in @standard_output and @standard_error,
26586 * if those parameters are non-%NULL. Note that you must set the
26587 * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
26588 * passing %NULL for @standard_output and @standard_error.
26590 * If @exit_status is non-%NULL, the platform-specific exit status of
26591 * the child is stored there; see the documentation of
26592 * g_spawn_check_exit_status() for how to use and interpret this.
26593 * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in
26596 * If an error occurs, no data is returned in @standard_output,
26597 * @standard_error, or @exit_status.
26599 * This function calls g_spawn_async_with_pipes() internally; see that
26600 * function for full details on the other parameters and details on
26601 * how these functions work on Windows.
26603 * Returns: %TRUE on success, %FALSE if an error was set
26609 * @string: A pointer to a memory buffer to contain the resulting string. It
26610 * is up to the caller to ensure that the allocated buffer is large
26611 * enough to hold the formatted result
26612 * @format: a standard printf() format string, but notice
26613 * [string precision pitfalls][string-precision]
26614 * @...: the arguments to insert in the output.
26616 * An implementation of the standard sprintf() function which supports
26617 * positional parameters, as specified in the Single Unix Specification.
26619 * Note that it is usually better to use g_snprintf(), to avoid the
26620 * risk of buffer overflow.
26622 * See also g_strdup_printf().
26624 * Returns: the number of bytes printed.
26631 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
26632 * @buf: a pointer to a stat struct, which will be filled with the file
26635 * A wrapper for the POSIX stat() function. The stat() function
26636 * returns information about a file. On Windows the stat() function in
26637 * the C library checks only the FAT-style READONLY attribute and does
26638 * not look at the ACL at all. Thus on Windows the protection bits in
26639 * the @st_mode field are a fabrication of little use.
26641 * On Windows the Microsoft C libraries have several variants of the
26642 * stat struct and stat() function with names like _stat(), _stat32(),
26643 * _stat32i64() and _stat64i32(). The one used here is for 32-bit code
26644 * the one with 32-bit size and time fields, specifically called _stat32().
26646 * In Microsoft's compiler, by default struct stat means one with
26647 * 64-bit time fields while in MinGW struct stat is the legacy one
26648 * with 32-bit fields. To hopefully clear up this messs, the gstdio.h
26649 * header defines a type #GStatBuf which is the appropriate struct type
26650 * depending on the platform and/or compiler being used. On POSIX it
26651 * is just struct stat, but note that even on POSIX platforms, stat()
26652 * might be a macro.
26654 * See your C library manual for more details about stat().
26656 * Returns: 0 if the information was successfully retrieved,
26657 * -1 if an error occurred
26664 * @dest: destination buffer.
26665 * @src: source string.
26667 * Copies a nul-terminated string into the dest buffer, include the
26668 * trailing nul, and return a pointer to the trailing nul byte.
26669 * This is useful for concatenating multiple strings together
26670 * without having to repeatedly scan for the end.
26672 * Returns: a pointer to trailing nul byte.
26679 * @v2: a key to compare with @v1
26681 * Compares two strings for byte-by-byte equality and returns %TRUE
26682 * if they are equal. It can be passed to g_hash_table_new() as the
26683 * @key_equal_func parameter, when using non-%NULL strings as keys in a
26686 * Note that this function is primarily meant as a hash table comparison
26687 * function. For a general-purpose, %NULL-safe string comparison function,
26690 * Returns: %TRUE if the two keys match
26695 * g_str_has_prefix:
26696 * @str: a nul-terminated string
26697 * @prefix: the nul-terminated prefix to look for
26699 * Looks whether the string @str begins with @prefix.
26701 * Returns: %TRUE if @str begins with @prefix, %FALSE otherwise.
26707 * g_str_has_suffix:
26708 * @str: a nul-terminated string
26709 * @suffix: the nul-terminated suffix to look for
26711 * Looks whether the string @str ends with @suffix.
26713 * Returns: %TRUE if @str end with @suffix, %FALSE otherwise.
26722 * Converts a string to a hash value.
26724 * This function implements the widely used "djb" hash apparently
26725 * posted by Daniel Bernstein to comp.lang.c some time ago. The 32
26726 * bit unsigned hash value starts at 5381 and for each byte 'c' in
26727 * the string, is updated: `hash = hash * 33 + c`. This function
26728 * uses the signed value of each byte.
26730 * It can be passed to g_hash_table_new() as the @hash_func parameter,
26731 * when using non-%NULL strings as keys in a #GHashTable.
26733 * Returns: a hash value corresponding to the key
26741 * Determines if a string is pure ASCII. A string is pure ASCII if it
26742 * contains no bytes with the high bit set.
26744 * Returns: %TRUE if @str is ASCII
26750 * g_str_match_string:
26751 * @search_term: the search term from the user
26752 * @potential_hit: the text that may be a hit
26753 * @accept_alternates: %TRUE to accept ASCII alternates
26755 * Checks if a search conducted for @search_term should match
26758 * This function calls g_str_tokenize_and_fold() on both
26759 * @search_term and @potential_hit. ASCII alternates are never taken
26760 * for @search_term but will be taken for @potential_hit according to
26761 * the value of @accept_alternates.
26763 * A hit occurs when each folded token in @search_term is a prefix of a
26764 * folded token from @potential_hit.
26766 * Depending on how you're performing the search, it will typically be
26767 * faster to call g_str_tokenize_and_fold() on each string in
26768 * your corpus and build an index on the returned folded tokens, then
26769 * call g_str_tokenize_and_fold() on the search term and
26770 * perform lookups into that index.
26772 * As some examples, searching for "fred" would match the potential hit
26773 * "Smith, Fred" and also "Frédéric". Searching for "Fréd" would match
26774 * "Frédéric" but not "Frederic" (due to the one-directional nature of
26775 * accent matching). Searching "fo" would match "Foo" and "Bar Foo
26776 * Baz", but not "SFO" (because no word as "fo" as a prefix).
26778 * Returns: %TRUE if @potential_hit is a hit
26785 * @str: a string, in UTF-8
26786 * @from_locale: (allow-none): the source locale, if known
26788 * Transliterate @str to plain ASCII.
26790 * For best results, @str should be in composed normalised form.
26792 * This function performs a reasonably good set of character
26793 * replacements. The particular set of replacements that is done may
26794 * change by version or even by runtime environment.
26796 * If the source language of @str is known, it can used to improve the
26797 * accuracy of the translation by passing it as @from_locale. It should
26798 * be a valid POSIX locale string (of the form
26799 * "language[_territory][.codeset][@modifier]").
26801 * If @from_locale is %NULL then the current locale is used.
26803 * If you want to do translation for no specific locale, and you want it
26804 * to be done independently of the currently locale, specify "C" for
26807 * Returns: a string in plain ASCII
26812 * g_str_tokenize_and_fold:
26813 * @string: a string
26814 * @translit_locale: (allow-none): the language code (like 'de' or
26815 * 'en_GB') from which @string originates
26816 * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a
26817 * return location for ASCII alternates
26819 * Tokenises @string and performs folding on each token.
26821 * A token is a non-empty sequence of alphanumeric characters in the
26822 * source string, separated by non-alphanumeric characters. An
26823 * "alphanumeric" character for this purpose is one that matches
26824 * g_unichar_isalnum() or g_unichar_ismark().
26826 * Each token is then (Unicode) normalised and case-folded. If
26827 * @ascii_alternates is non-%NULL and some of the returned tokens
26828 * contain non-ASCII characters, ASCII alternatives will be generated.
26830 * The number of ASCII alternatives that are generated and the method
26831 * for doing so is unspecified, but @translit_locale (if specified) may
26832 * improve the transliteration if the language of the source string is
26835 * Returns: (transfer full) (array zero-terminated=1): the folded tokens
26842 * @string: a nul-terminated array of bytes
26843 * @valid_chars: bytes permitted in @string
26844 * @substitutor: replacement character for disallowed bytes
26846 * For each character in @string, if the character is not in @valid_chars,
26847 * replaces the character with @substitutor. Modifies @string in place,
26848 * and return @string itself, not a copy. The return value is to allow
26850 * |[<!-- language="C" -->
26851 * g_ascii_strup (g_strcanon (str, "abc", '?'))
26861 * @s2: a string to compare with @s1
26863 * A case-insensitive string comparison, corresponding to the standard
26864 * strcasecmp() function on platforms which support it.
26866 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
26867 * or a positive value if @s1 > @s2.
26868 * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this
26869 * function is deprecated and how to replace it.
26875 * @string: a string to remove the trailing whitespace from
26877 * Removes trailing whitespace from a string.
26879 * This function doesn't allocate or reallocate any memory;
26880 * it modifies @string in place. Therefore, it cannot be used
26881 * on statically allocated strings.
26883 * The pointer to @string is returned to allow the nesting of functions.
26885 * Also see g_strchug() and g_strstrip().
26893 * @string: a string to remove the leading whitespace from
26895 * Removes leading whitespace from a string, by moving the rest
26896 * of the characters forward.
26898 * This function doesn't allocate or reallocate any memory;
26899 * it modifies @string in place. Therefore, it cannot be used on
26900 * statically allocated strings.
26902 * The pointer to @string is returned to allow the nesting of functions.
26904 * Also see g_strchomp() and g_strstrip().
26912 * @str1: (allow-none): a C string or %NULL
26913 * @str2: (allow-none): another C string or %NULL
26915 * Compares @str1 and @str2 like strcmp(). Handles %NULL
26916 * gracefully by sorting it before non-%NULL strings.
26917 * Comparing two %NULL pointers returns 0.
26919 * Returns: an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2.
26926 * @source: a string to compress
26928 * Replaces all escaped characters with their one byte equivalent.
26930 * This function does the reverse conversion of g_strescape().
26932 * Returns: a newly-allocated copy of @source with all escaped
26933 * character compressed
26939 * @string1: the first string to add, which must not be %NULL
26940 * @...: a %NULL-terminated list of strings to append to the string
26942 * Concatenates all of the given strings into one long string. The
26943 * returned string should be freed with g_free() when no longer needed.
26945 * The variable argument list must end with %NULL. If you forget the %NULL,
26946 * g_strconcat() will start appending random memory junk to your string.
26948 * Note that this function is usually not the right function to use to
26949 * assemble a translated message from pieces, since proper translation
26950 * often requires the pieces to be reordered.
26952 * Returns: a newly-allocated string containing all the string arguments
26958 * @string: the string to convert
26959 * @delimiters: (allow-none): a string containing the current delimiters,
26960 * or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS
26961 * @new_delimiter: the new delimiter character
26963 * Converts any delimiter characters in @string to @new_delimiter.
26964 * Any characters in @string which are found in @delimiters are
26965 * changed to the @new_delimiter character. Modifies @string in place,
26966 * and returns @string itself, not a copy. The return value is to
26967 * allow nesting such as
26968 * |[<!-- language="C" -->
26969 * g_ascii_strup (g_strdelimit (str, "abc", '?'))
26978 * @string: the string to convert.
26980 * Converts a string to lower case.
26982 * Returns: the string
26983 * Deprecated: 2.2: This function is totally broken for the reasons discussed
26984 * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
26991 * @str: the string to duplicate
26993 * Duplicates a string. If @str is %NULL it returns %NULL.
26994 * The returned string should be freed with g_free()
26995 * when no longer needed.
26997 * Returns: a newly-allocated copy of @str
27003 * @format: a standard printf() format string, but notice
27004 * [string precision pitfalls][string-precision]
27005 * @...: the parameters to insert into the format string
27007 * Similar to the standard C sprintf() function but safer, since it
27008 * calculates the maximum space required and allocates memory to hold
27009 * the result. The returned string should be freed with g_free() when no
27012 * Returns: a newly-allocated string holding the result
27017 * g_strdup_vprintf:
27018 * @format: a standard printf() format string, but notice
27019 * [string precision pitfalls][string-precision]
27020 * @args: the list of parameters to insert into the format string
27022 * Similar to the standard C vsprintf() function but safer, since it
27023 * calculates the maximum space required and allocates memory to hold
27024 * the result. The returned string should be freed with g_free() when
27025 * no longer needed.
27027 * See also g_vasprintf(), which offers the same functionality, but
27028 * additionally returns the length of the allocated string.
27030 * Returns: a newly-allocated string holding the result
27036 * @str_array: a %NULL-terminated array of strings
27038 * Copies %NULL-terminated array of strings. The copy is a deep copy;
27039 * the new array should be freed by first freeing each string, then
27040 * the array itself. g_strfreev() does this for you. If called
27041 * on a %NULL value, g_strdupv() simply returns %NULL.
27043 * Returns: a new %NULL-terminated array of strings.
27049 * @errnum: the system error number. See the standard C %errno
27052 * Returns a string corresponding to the given error code, e.g.
27053 * "no such process". You should use this function in preference to
27054 * strerror(), because it returns a string in UTF-8 encoding, and since
27055 * not all platforms support the strerror() function.
27057 * Returns: a UTF-8 string describing the error code. If the error code
27058 * is unknown, it returns "unknown error (<code>)".
27064 * @source: a string to escape
27065 * @exceptions: a string of characters not to escape in @source
27067 * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
27068 * and '"' in the string @source by inserting a '\' before
27069 * them. Additionally all characters in the range 0x01-0x1F (everything
27070 * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
27071 * replaced with a '\' followed by their octal representation.
27072 * Characters supplied in @exceptions are not escaped.
27074 * g_strcompress() does the reverse conversion.
27076 * Returns: a newly-allocated copy of @source with certain
27077 * characters escaped. See above.
27083 * @str_array: a %NULL-terminated array of strings to free
27085 * Frees a %NULL-terminated array of strings, and the array itself.
27086 * If called on a %NULL value, g_strfreev() simply returns.
27092 * @string: a #GString
27093 * @val: the string to append onto the end of @string
27095 * Adds a string onto the end of a #GString, expanding
27103 * g_string_append_c:
27104 * @string: a #GString
27105 * @c: the byte to append onto the end of @string
27107 * Adds a byte onto the end of a #GString, expanding
27115 * g_string_append_len:
27116 * @string: a #GString
27117 * @val: bytes to append
27118 * @len: number of bytes of @val to use
27120 * Appends @len bytes of @val to @string. Because @len is
27121 * provided, @val may contain embedded nuls and need not
27122 * be nul-terminated.
27124 * Since this function does not stop at nul bytes, it is
27125 * the caller's responsibility to ensure that @val has at
27126 * least @len addressable bytes.
27133 * g_string_append_printf:
27134 * @string: a #GString
27135 * @format: the string format. See the printf() documentation
27136 * @...: the parameters to insert into the format string
27138 * Appends a formatted string onto the end of a #GString.
27139 * This function is similar to g_string_printf() except
27140 * that the text is appended to the #GString.
27145 * g_string_append_unichar:
27146 * @string: a #GString
27147 * @wc: a Unicode character
27149 * Converts a Unicode character into UTF-8, and appends it
27157 * g_string_append_uri_escaped:
27158 * @string: a #GString
27159 * @unescaped: a string
27160 * @reserved_chars_allowed: a string of reserved characters allowed
27161 * to be used, or %NULL
27162 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
27164 * Appends @unescaped to @string, escaped any characters that
27165 * are reserved in URIs using URI-style escape sequences.
27173 * g_string_append_vprintf:
27174 * @string: a #GString
27175 * @format: the string format. See the printf() documentation
27176 * @args: the list of arguments to insert in the output
27178 * Appends a formatted string onto the end of a #GString.
27179 * This function is similar to g_string_append_printf()
27180 * except that the arguments to the format string are passed
27188 * g_string_ascii_down:
27189 * @string: a GString
27191 * Converts all uppercase ASCII letters to lowercase ASCII letters.
27193 * Returns: passed-in @string pointer, with all the
27194 * uppercase characters converted to lowercase in place,
27195 * with semantics that exactly match g_ascii_tolower().
27200 * g_string_ascii_up:
27201 * @string: a GString
27203 * Converts all lowercase ASCII letters to uppercase ASCII letters.
27205 * Returns: passed-in @string pointer, with all the
27206 * lowercase characters converted to uppercase in place,
27207 * with semantics that exactly match g_ascii_toupper().
27213 * @string: the destination #GString. Its current contents
27215 * @rval: the string to copy into @string
27217 * Copies the bytes from a string into a #GString,
27218 * destroying any previous contents. It is rather like
27219 * the standard strcpy() function, except that you do not
27220 * have to worry about having enough space to copy the string.
27227 * g_string_chunk_clear:
27228 * @chunk: a #GStringChunk
27230 * Frees all strings contained within the #GStringChunk.
27231 * After calling g_string_chunk_clear() it is not safe to
27232 * access any of the strings which were contained within it.
27239 * g_string_chunk_free:
27240 * @chunk: a #GStringChunk
27242 * Frees all memory allocated by the #GStringChunk.
27243 * After calling g_string_chunk_free() it is not safe to
27244 * access any of the strings which were contained within it.
27249 * g_string_chunk_insert:
27250 * @chunk: a #GStringChunk
27251 * @string: the string to add
27253 * Adds a copy of @string to the #GStringChunk.
27254 * It returns a pointer to the new copy of the string
27255 * in the #GStringChunk. The characters in the string
27256 * can be changed, if necessary, though you should not
27257 * change anything after the end of the string.
27259 * Unlike g_string_chunk_insert_const(), this function
27260 * does not check for duplicates. Also strings added
27261 * with g_string_chunk_insert() will not be searched
27262 * by g_string_chunk_insert_const() when looking for
27265 * Returns: a pointer to the copy of @string within
27266 * the #GStringChunk
27271 * g_string_chunk_insert_const:
27272 * @chunk: a #GStringChunk
27273 * @string: the string to add
27275 * Adds a copy of @string to the #GStringChunk, unless the same
27276 * string has already been added to the #GStringChunk with
27277 * g_string_chunk_insert_const().
27279 * This function is useful if you need to copy a large number
27280 * of strings but do not want to waste space storing duplicates.
27281 * But you must remember that there may be several pointers to
27282 * the same string, and so any changes made to the strings
27283 * should be done very carefully.
27285 * Note that g_string_chunk_insert_const() will not return a
27286 * pointer to a string added with g_string_chunk_insert(), even
27287 * if they do match.
27289 * Returns: a pointer to the new or existing copy of @string
27290 * within the #GStringChunk
27295 * g_string_chunk_insert_len:
27296 * @chunk: a #GStringChunk
27297 * @string: bytes to insert
27298 * @len: number of bytes of @string to insert, or -1 to insert a
27299 * nul-terminated string
27301 * Adds a copy of the first @len bytes of @string to the #GStringChunk.
27302 * The copy is nul-terminated.
27304 * Since this function does not stop at nul bytes, it is the caller's
27305 * responsibility to ensure that @string has at least @len addressable
27308 * The characters in the returned string can be changed, if necessary,
27309 * though you should not change anything after the end of the string.
27311 * Returns: a pointer to the copy of @string within the #GStringChunk
27317 * g_string_chunk_new:
27318 * @size: the default size of the blocks of memory which are
27319 * allocated to store the strings. If a particular string
27320 * is larger than this default size, a larger block of
27321 * memory will be allocated for it.
27323 * Creates a new #GStringChunk.
27325 * Returns: a new #GStringChunk
27331 * @string: a #GString
27333 * Converts a #GString to lowercase.
27335 * Returns: the #GString
27336 * Deprecated: 2.2: This function uses the locale-specific
27337 * tolower() function, which is almost never the right thing.
27338 * Use g_string_ascii_down() or g_utf8_strdown() instead.
27345 * @v2: another #GString
27347 * Compares two strings for equality, returning %TRUE if they are equal.
27348 * For use with #GHashTable.
27350 * Returns: %TRUE if the strings are the same length and contain the
27357 * @string: a #GString
27358 * @pos: the position of the content to remove
27359 * @len: the number of bytes to remove, or -1 to remove all
27362 * Removes @len bytes from a #GString, starting at position @pos.
27363 * The rest of the #GString is shifted down to fill the gap.
27371 * @string: a #GString
27372 * @free_segment: if %TRUE, the actual character data is freed as well
27374 * Frees the memory allocated for the #GString.
27375 * If @free_segment is %TRUE it also frees the character data. If
27376 * it's %FALSE, the caller gains ownership of the buffer and must
27377 * free it after use with g_free().
27379 * Returns: the character data of @string
27380 * (i.e. %NULL if @free_segment is %TRUE)
27385 * g_string_free_to_bytes:
27386 * @string: (transfer full): a #GString
27388 * Transfers ownership of the contents of @string to a newly allocated
27389 * #GBytes. The #GString structure itself is deallocated, and it is
27390 * therefore invalid to use @string after invoking this function.
27392 * Note that while #GString ensures that its buffer always has a
27393 * trailing nul character (not reflected in its "len"), the returned
27394 * #GBytes does not include this extra nul; i.e. it has length exactly
27395 * equal to the "len" member.
27397 * Returns: A newly allocated #GBytes containing contents of @string; @string itself is freed
27404 * @str: a string to hash
27406 * Creates a hash code for @str; for use with #GHashTable.
27408 * Returns: hash code for @str
27414 * @string: a #GString
27415 * @pos: the position to insert the copy of the string
27416 * @val: the string to insert
27418 * Inserts a copy of a string into a #GString,
27419 * expanding it if necessary.
27426 * g_string_insert_c:
27427 * @string: a #GString
27428 * @pos: the position to insert the byte
27429 * @c: the byte to insert
27431 * Inserts a byte into a #GString, expanding it if necessary.
27438 * g_string_insert_len:
27439 * @string: a #GString
27440 * @pos: position in @string where insertion should
27441 * happen, or -1 for at the end
27442 * @val: bytes to insert
27443 * @len: number of bytes of @val to insert
27445 * Inserts @len bytes of @val into @string at @pos.
27446 * Because @len is provided, @val may contain embedded
27447 * nuls and need not be nul-terminated. If @pos is -1,
27448 * bytes are inserted at the end of the string.
27450 * Since this function does not stop at nul bytes, it is
27451 * the caller's responsibility to ensure that @val has at
27452 * least @len addressable bytes.
27459 * g_string_insert_unichar:
27460 * @string: a #GString
27461 * @pos: the position at which to insert character, or -1
27462 * to append at the end of the string
27463 * @wc: a Unicode character
27465 * Converts a Unicode character into UTF-8, and insert it
27466 * into the string at the given position.
27474 * @init: the initial text to copy into the string
27476 * Creates a new #GString, initialized with the given string.
27478 * Returns: the new #GString
27483 * g_string_new_len:
27484 * @init: initial contents of the string
27485 * @len: length of @init to use
27487 * Creates a new #GString with @len bytes of the @init buffer.
27488 * Because a length is provided, @init need not be nul-terminated,
27489 * and can contain embedded nul bytes.
27491 * Since this function does not stop at nul bytes, it is the caller's
27492 * responsibility to ensure that @init has at least @len addressable
27495 * Returns: a new #GString
27500 * g_string_overwrite:
27501 * @string: a #GString
27502 * @pos: the position at which to start overwriting
27503 * @val: the string that will overwrite the @string starting at @pos
27505 * Overwrites part of a string, lengthening it if necessary.
27513 * g_string_overwrite_len:
27514 * @string: a #GString
27515 * @pos: the position at which to start overwriting
27516 * @val: the string that will overwrite the @string starting at @pos
27517 * @len: the number of bytes to write from @val
27519 * Overwrites part of a string, lengthening it if necessary.
27520 * This function will work with embedded nuls.
27528 * g_string_prepend:
27529 * @string: a #GString
27530 * @val: the string to prepend on the start of @string
27532 * Adds a string on to the start of a #GString,
27533 * expanding it if necessary.
27540 * g_string_prepend_c:
27541 * @string: a #GString
27542 * @c: the byte to prepend on the start of the #GString
27544 * Adds a byte onto the start of a #GString,
27545 * expanding it if necessary.
27552 * g_string_prepend_len:
27553 * @string: a #GString
27554 * @val: bytes to prepend
27555 * @len: number of bytes in @val to prepend
27557 * Prepends @len bytes of @val to @string.
27558 * Because @len is provided, @val may contain
27559 * embedded nuls and need not be nul-terminated.
27561 * Since this function does not stop at nul bytes,
27562 * it is the caller's responsibility to ensure that
27563 * @val has at least @len addressable bytes.
27570 * g_string_prepend_unichar:
27571 * @string: a #GString
27572 * @wc: a Unicode character
27574 * Converts a Unicode character into UTF-8, and prepends it
27583 * @string: a #GString
27584 * @format: the string format. See the printf() documentation
27585 * @...: the parameters to insert into the format string
27587 * Writes a formatted string into a #GString.
27588 * This is similar to the standard sprintf() function,
27589 * except that the #GString buffer automatically expands
27590 * to contain the results. The previous contents of the
27591 * #GString are destroyed.
27596 * g_string_set_size:
27597 * @string: a #GString
27598 * @len: the new length
27600 * Sets the length of a #GString. If the length is less than
27601 * the current length, the string will be truncated. If the
27602 * length is greater than the current length, the contents
27603 * of the newly added area are undefined. (However, as
27604 * always, string->str[string->len] will be a nul byte.)
27611 * g_string_sized_new:
27612 * @dfl_size: the default size of the space allocated to
27615 * Creates a new #GString, with enough space for @dfl_size
27616 * bytes. This is useful if you are going to add a lot of
27617 * text to the string and don't want it to be reallocated
27620 * Returns: the new #GString
27625 * g_string_sprintf:
27626 * @string: a #GString
27627 * @format: the string format. See the sprintf() documentation
27628 * @...: the parameters to insert into the format string
27630 * Writes a formatted string into a #GString.
27631 * This is similar to the standard sprintf() function,
27632 * except that the #GString buffer automatically expands
27633 * to contain the results. The previous contents of the
27634 * #GString are destroyed.
27636 * Deprecated: This function has been renamed to g_string_printf().
27641 * g_string_sprintfa:
27642 * @string: a #GString
27643 * @format: the string format. See the sprintf() documentation
27644 * @...: the parameters to insert into the format string
27646 * Appends a formatted string onto the end of a #GString.
27647 * This function is similar to g_string_sprintf() except that
27648 * the text is appended to the #GString.
27650 * Deprecated: This function has been renamed to g_string_append_printf()
27655 * g_string_truncate:
27656 * @string: a #GString
27657 * @len: the new size of @string
27659 * Cuts off the end of the GString, leaving the first @len bytes.
27667 * @string: a #GString
27669 * Converts a #GString to uppercase.
27672 * Deprecated: 2.2: This function uses the locale-specific
27673 * toupper() function, which is almost never the right thing.
27674 * Use g_string_ascii_up() or g_utf8_strup() instead.
27679 * g_string_vprintf:
27680 * @string: a #GString
27681 * @format: the string format. See the printf() documentation
27682 * @args: the parameters to insert into the format string
27684 * Writes a formatted string into a #GString.
27685 * This function is similar to g_string_printf() except that
27686 * the arguments to the format string are passed as a va_list.
27695 * @msgval: another string
27697 * An auxiliary function for gettext() support (see Q_()).
27699 * Returns: @msgval, unless @msgval is identical to @msgid
27700 * and contains a '|' character, in which case a pointer to
27701 * the substring of msgid after the first '|' character is returned.
27708 * @separator: (allow-none): a string to insert between each of the
27709 * strings, or %NULL
27710 * @...: a %NULL-terminated list of strings to join
27712 * Joins a number of strings together to form one long string, with the
27713 * optional @separator inserted between each of them. The returned string
27714 * should be freed with g_free().
27716 * Returns: a newly-allocated string containing all of the strings joined
27717 * together, with @separator between them
27723 * @separator: (allow-none): a string to insert between each of the
27724 * strings, or %NULL
27725 * @str_array: a %NULL-terminated array of strings to join
27727 * Joins a number of strings together to form one long string, with the
27728 * optional @separator inserted between each of them. The returned string
27729 * should be freed with g_free().
27731 * Returns: a newly-allocated string containing all of the strings joined
27732 * together, with @separator between them
27738 * @dest: destination buffer, already containing one nul-terminated string
27739 * @src: source buffer
27740 * @dest_size: length of @dest buffer in bytes (not length of existing string
27743 * Portability wrapper that calls strlcat() on systems which have it,
27744 * and emulates it otherwise. Appends nul-terminated @src string to @dest,
27745 * guaranteeing nul-termination for @dest. The total size of @dest won't
27746 * exceed @dest_size.
27748 * At most @dest_size - 1 characters will be copied. Unlike strncat(),
27749 * @dest_size is the full size of dest, not the space left over. This
27750 * function does not allocate memory. It always nul-terminates (unless
27751 * @dest_size == 0 or there were no nul characters in the @dest_size
27752 * characters of dest to start with).
27754 * Caveat: this is supposedly a more secure alternative to strcat() or
27755 * strncat(), but for real security g_strconcat() is harder to mess up.
27757 * Returns: size of attempted result, which is MIN (dest_size, strlen
27758 * (original dest)) + strlen (src), so if retval >= dest_size,
27759 * truncation occurred.
27765 * @dest: destination buffer
27766 * @src: source buffer
27767 * @dest_size: length of @dest in bytes
27769 * Portability wrapper that calls strlcpy() on systems which have it,
27770 * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
27771 * guaranteed to be nul-terminated; @src must be nul-terminated;
27772 * @dest_size is the buffer size, not the number of bytes to copy.
27774 * At most @dest_size - 1 characters will be copied. Always nul-terminates
27775 * (unless @dest_size is 0). This function does not allocate memory. Unlike
27776 * strncpy(), this function doesn't pad @dest (so it's often faster). It
27777 * returns the size of the attempted result, strlen (src), so if
27778 * @retval >= @dest_size, truncation occurred.
27780 * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
27781 * but if you really want to avoid screwups, g_strdup() is an even better
27784 * Returns: length of @src
27791 * @s2: a string to compare with @s1
27792 * @n: the maximum number of characters to compare
27794 * A case-insensitive string comparison, corresponding to the standard
27795 * strncasecmp() function on platforms which support it. It is similar
27796 * to g_strcasecmp() except it only compares the first @n characters of
27799 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
27800 * or a positive value if @s1 > @s2.
27801 * Deprecated: 2.2: The problem with g_strncasecmp() is that it does
27802 * the comparison by calling toupper()/tolower(). These functions
27803 * are locale-specific and operate on single bytes. However, it is
27804 * impossible to handle things correctly from an internationalization
27805 * standpoint by operating on bytes, since characters may be multibyte.
27806 * Thus g_strncasecmp() is broken if your string is guaranteed to be
27807 * ASCII, since it is locale-sensitive, and it's broken if your string
27808 * is localized, since it doesn't work on many encodings at all,
27809 * including UTF-8, EUC-JP, etc.
27811 * There are therefore two replacement techniques: g_ascii_strncasecmp(),
27812 * which only works on ASCII and is not locale-sensitive, and
27813 * g_utf8_casefold() followed by strcmp() on the resulting strings,
27814 * which is good for case-insensitive sorting of UTF-8.
27820 * @str: the string to duplicate
27821 * @n: the maximum number of bytes to copy from @str
27823 * Duplicates the first @n bytes of a string, returning a newly-allocated
27824 * buffer @n + 1 bytes long which will always be nul-terminated. If @str
27825 * is less than @n bytes long the buffer is padded with nuls. If @str is
27826 * %NULL it returns %NULL. The returned value should be freed when no longer
27829 * To copy a number of characters from a UTF-8 encoded string,
27830 * use g_utf8_strncpy() instead.
27832 * Returns: a newly-allocated buffer containing the first @n bytes
27833 * of @str, nul-terminated
27839 * @length: the length of the new string
27840 * @fill_char: the byte to fill the string with
27842 * Creates a new string @length bytes long filled with @fill_char.
27843 * The returned string should be freed when no longer needed.
27845 * Returns: a newly-allocated string filled the @fill_char
27851 * @string: the string to reverse
27853 * Reverses all of the bytes in a string. For example,
27854 * `g_strreverse ("abcdef")` will result in "fedcba".
27856 * Note that g_strreverse() doesn't work on UTF-8 strings
27857 * containing multibyte characters. For that purpose, use
27858 * g_utf8_strreverse().
27860 * Returns: the same pointer passed in as @string
27866 * @haystack: a nul-terminated string
27867 * @needle: the nul-terminated string to search for
27869 * Searches the string @haystack for the last occurrence
27870 * of the string @needle.
27872 * Returns: a pointer to the found occurrence, or
27873 * %NULL if not found.
27879 * @haystack: a nul-terminated string
27880 * @haystack_len: the maximum length of @haystack
27881 * @needle: the nul-terminated string to search for
27883 * Searches the string @haystack for the last occurrence
27884 * of the string @needle, limiting the length of the search
27885 * to @haystack_len.
27887 * Returns: a pointer to the found occurrence, or
27888 * %NULL if not found.
27894 * @signum: the signal number. See the `signal` documentation
27896 * Returns a string describing the given signal, e.g. "Segmentation fault".
27897 * You should use this function in preference to strsignal(), because it
27898 * returns a string in UTF-8 encoding, and since not all platforms support
27899 * the strsignal() function.
27901 * Returns: a UTF-8 string describing the signal. If the signal is unknown,
27902 * it returns "unknown signal (<signum>)".
27908 * @string: a string to split
27909 * @delimiter: a string which specifies the places at which to split
27910 * the string. The delimiter is not included in any of the resulting
27911 * strings, unless @max_tokens is reached.
27912 * @max_tokens: the maximum number of pieces to split @string into.
27913 * If this is less than 1, the string is split completely.
27915 * Splits a string into a maximum of @max_tokens pieces, using the given
27916 * @delimiter. If @max_tokens is reached, the remainder of @string is
27917 * appended to the last token.
27919 * As a special case, the result of splitting the empty string "" is an empty
27920 * vector, not a vector containing a single string. The reason for this
27921 * special case is that being able to represent a empty vector is typically
27922 * more useful than consistent handling of empty elements. If you do need
27923 * to represent empty elements, you'll need to check for the empty string
27924 * before calling g_strsplit().
27926 * Returns: a newly-allocated %NULL-terminated array of strings. Use
27927 * g_strfreev() to free it.
27933 * @string: The string to be tokenized
27934 * @delimiters: A nul-terminated string containing bytes that are used
27935 * to split the string.
27936 * @max_tokens: The maximum number of tokens to split @string into.
27937 * If this is less than 1, the string is split completely
27939 * Splits @string into a number of tokens not containing any of the characters
27940 * in @delimiter. A token is the (possibly empty) longest string that does not
27941 * contain any of the characters in @delimiters. If @max_tokens is reached, the
27942 * remainder is appended to the last token.
27944 * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
27945 * %NULL-terminated vector containing the three strings "abc", "def",
27948 * The result if g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
27949 * vector containing the four strings "", "def", "ghi", and "".
27951 * As a special case, the result of splitting the empty string "" is an empty
27952 * vector, not a vector containing a single string. The reason for this
27953 * special case is that being able to represent a empty vector is typically
27954 * more useful than consistent handling of empty elements. If you do need
27955 * to represent empty elements, you'll need to check for the empty string
27956 * before calling g_strsplit_set().
27958 * Note that this function works on bytes not characters, so it can't be used
27959 * to delimit UTF-8 strings for anything but ASCII characters.
27961 * Returns: a newly-allocated %NULL-terminated array of strings. Use
27962 * g_strfreev() to free it.
27969 * @haystack: a string
27970 * @haystack_len: the maximum length of @haystack. Note that -1 is
27971 * a valid length, if @haystack is nul-terminated, meaning it will
27972 * search through the whole string.
27973 * @needle: the string to search for
27975 * Searches the string @haystack for the first occurrence
27976 * of the string @needle, limiting the length of the search
27977 * to @haystack_len.
27979 * Returns: a pointer to the found occurrence, or
27980 * %NULL if not found.
27986 * @string: a string to remove the leading and trailing whitespace from
27988 * Removes leading and trailing whitespace from a string.
27989 * See g_strchomp() and g_strchug().
27997 * @nptr: the string to convert to a numeric value.
27998 * @endptr: if non-%NULL, it returns the character after
27999 * the last character used in the conversion.
28001 * Converts a string to a #gdouble value.
28002 * It calls the standard strtod() function to handle the conversion, but
28003 * if the string is not completely converted it attempts the conversion
28004 * again with g_ascii_strtod(), and returns the best match.
28006 * This function should seldom be used. The normal situation when reading
28007 * numbers not for human consumption is to use g_ascii_strtod(). Only when
28008 * you know that you must expect both locale formatted and C formatted numbers
28009 * should you use this. Make sure that you don't pass strings such as comma
28010 * separated lists of values, since the commas may be interpreted as a decimal
28011 * point in some locales, causing unexpected results.
28013 * Returns: the #gdouble value.
28019 * @string: the string to convert
28021 * Converts a string to upper case.
28023 * Returns: the string
28024 * Deprecated: 2.2: This function is totally broken for the reasons
28025 * discussed in the g_strncasecmp() docs - use g_ascii_strup()
28026 * or g_utf8_strup() instead.
28032 * @str_array: a %NULL-terminated array of strings
28034 * Returns the length of the given %NULL-terminated
28035 * string array @str_array.
28037 * Returns: length of @str_array.
28044 * @testpath: The test path for a new test case.
28045 * @Fixture: The type of a fixture data structure.
28046 * @tdata: Data argument for the test functions.
28047 * @fsetup: The function to set up the fixture data.
28048 * @ftest: The actual test function.
28049 * @fteardown: The function to tear down the fixture data.
28051 * Hook up a new test case at @testpath, similar to g_test_add_func().
28052 * A fixture data structure with setup and teardown function may be provided
28053 * though, similar to g_test_create_case().
28054 * g_test_add() is implemented as a macro, so that the fsetup(), ftest() and
28055 * fteardown() callbacks can expect a @Fixture pointer as first argument in
28056 * a type safe manner.
28063 * g_test_add_data_func:
28064 * @testpath: /-separated test case path name for the test.
28065 * @test_data: Test data argument for the test function.
28066 * @test_func: The test function to invoke for this test.
28068 * Create a new test case, similar to g_test_create_case(). However
28069 * the test is assumed to use no fixture, and test suites are automatically
28070 * created on the fly and added to the root fixture, based on the
28071 * slash-separated portions of @testpath. The @test_data argument
28072 * will be passed as first argument to @test_func.
28074 * If @testpath includes the component "subprocess" anywhere in it,
28075 * the test will be skipped by default, and only run if explicitly
28076 * required via the `-p` command-line option or g_test_trap_subprocess().
28083 * g_test_add_data_func_full:
28084 * @testpath: /-separated test case path name for the test.
28085 * @test_data: Test data argument for the test function.
28086 * @test_func: The test function to invoke for this test.
28087 * @data_free_func: #GDestroyNotify for @test_data.
28089 * Create a new test case, as with g_test_add_data_func(), but freeing
28090 * @test_data after the test run is complete.
28098 * @testpath: /-separated test case path name for the test.
28099 * @test_func: The test function to invoke for this test.
28101 * Create a new test case, similar to g_test_create_case(). However
28102 * the test is assumed to use no fixture, and test suites are automatically
28103 * created on the fly and added to the root fixture, based on the
28104 * slash-separated portions of @testpath.
28106 * If @testpath includes the component "subprocess" anywhere in it,
28107 * the test will be skipped by default, and only run if explicitly
28108 * required via the `-p` command-line option or g_test_trap_subprocess().
28115 * g_test_assert_expected_messages:
28117 * Asserts that all messages previously indicated via
28118 * g_test_expect_message() have been seen and suppressed.
28120 * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly
28121 * expected via g_test_expect_message() then they will be ignored.
28129 * @bug_uri_snippet: Bug specific bug tracker URI portion.
28131 * This function adds a message to test reports that
28132 * associates a bug URI with a test case.
28133 * Bug URIs are constructed from a base URI set with g_test_bug_base()
28134 * and @bug_uri_snippet.
28142 * @uri_pattern: the base pattern for bug URIs
28144 * Specify the base URI for bug reports.
28146 * The base URI is used to construct bug report messages for
28147 * g_test_message() when g_test_bug() is called.
28148 * Calling this function outside of a test case sets the
28149 * default base URI for all test cases. Calling it from within
28150 * a test case changes the base URI for the scope of the test
28152 * Bug URIs are constructed by appending a bug specific URI
28153 * portion to @uri_pattern, or by replacing the special string
28154 * '\%s' within @uri_pattern if that is present.
28161 * g_test_build_filename:
28162 * @file_type: the type of file (built vs. distributed)
28163 * @first_path: the first segment of the pathname
28164 * @...: %NULL-terminated additional path segments
28166 * Creates the pathname to a data file that is required for a test.
28168 * This function is conceptually similar to g_build_filename() except
28169 * that the first argument has been replaced with a #GTestFileType
28172 * The data file should either have been distributed with the module
28173 * containing the test (%G_TEST_DIST) or built as part of the build
28174 * system of that module (%G_TEST_BUILT).
28176 * In order for this function to work in srcdir != builddir situations,
28177 * the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to
28178 * have been defined. As of 2.38, this is done by the glib.mk
28179 * included in GLib. Please ensure that your copy is up to date before
28180 * using this function.
28182 * In case neither variable is set, this function will fall back to
28183 * using the dirname portion of argv[0], possibly removing ".libs".
28184 * This allows for casual running of tests directly from the commandline
28185 * in the srcdir == builddir case and should also support running of
28186 * installed tests, assuming the data files have been installed in the
28187 * same relative path as the test binary.
28189 * Returns: the path of the file, to be freed using g_free()
28195 * g_test_create_case:
28196 * @test_name: the name for the test case
28197 * @data_size: the size of the fixture data structure
28198 * @test_data: test data argument for the test functions
28199 * @data_setup: the function to set up the fixture data
28200 * @data_test: the actual test function
28201 * @data_teardown: the function to teardown the fixture data
28203 * Create a new #GTestCase, named @test_name, this API is fairly
28204 * low level, calling g_test_add() or g_test_add_func() is preferable.
28205 * When this test is executed, a fixture structure of size @data_size
28206 * will be allocated and filled with 0s. Then @data_setup is called
28207 * to initialize the fixture. After fixture setup, the actual test
28208 * function @data_test is called. Once the test run completed, the
28209 * fixture structure is torn down by calling @data_teardown and
28210 * after that the memory is released.
28212 * Splitting up a test run into fixture setup, test function and
28213 * fixture teardown is most usful if the same fixture is used for
28214 * multiple tests. In this cases, g_test_create_case() will be
28215 * called with the same fixture, but varying @test_name and
28216 * @data_test arguments.
28218 * Returns: a newly allocated #GTestCase.
28224 * g_test_create_suite:
28225 * @suite_name: a name for the suite
28227 * Create a new test suite with the name @suite_name.
28229 * Returns: A newly allocated #GTestSuite instance.
28235 * g_test_expect_message:
28236 * @log_domain: (allow-none): the log domain of the message
28237 * @log_level: the log level of the message
28238 * @pattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
28240 * Indicates that a message with the given @log_domain and @log_level,
28241 * with text matching @pattern, is expected to be logged. When this
28242 * message is logged, it will not be printed, and the test case will
28245 * Use g_test_assert_expected_messages() to assert that all
28246 * previously-expected messages have been seen and suppressed.
28248 * You can call this multiple times in a row, if multiple messages are
28249 * expected as a result of a single call. (The messages must appear in
28250 * the same order as the calls to g_test_expect_message().)
28254 * |[<!-- language="C" -->
28255 * // g_main_context_push_thread_default() should fail if the
28256 * // context is already owned by another thread.
28257 * g_test_expect_message (G_LOG_DOMAIN,
28258 * G_LOG_LEVEL_CRITICAL,
28259 * "assertion*acquired_context*failed");
28260 * g_main_context_push_thread_default (bad_context);
28261 * g_test_assert_expected_messages ();
28264 * Note that you cannot use this to test g_error() messages, since
28265 * g_error() intentionally never returns even if the program doesn't
28266 * abort; use g_test_trap_subprocess() in this case.
28268 * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly
28269 * expected via g_test_expect_message() then they will be ignored.
28278 * Indicates that a test failed. This function can be called
28279 * multiple times from the same test. You can use this function
28280 * if your test failed in a recoverable way.
28282 * Do not use this function if the failure of a test could cause
28283 * other tests to malfunction.
28285 * Calling this function will not stop the test from running, you
28286 * need to return from the test function yourself. So you can
28287 * produce additional diagnostic messages or even continue running
28290 * If not called from inside a test, this function does nothing.
28299 * Returns whether a test has already failed. This will
28300 * be the case when g_test_fail(), g_test_incomplete()
28301 * or g_test_skip() have been called, but also if an
28302 * assertion has failed.
28304 * This can be useful to return early from a test if
28305 * continuing after a failed assertion might be harmful.
28307 * The return value of this function is only meaningful
28308 * if it is called from inside a test function.
28310 * Returns: %TRUE if the test has failed
28317 * @file_type: the type of file (built vs. distributed)
28319 * Gets the pathname of the directory containing test files of the type
28320 * specified by @file_type.
28322 * This is approximately the same as calling g_test_build_filename("."),
28323 * but you don't need to free the return value.
28325 * Returns: the path of the directory, owned by GLib
28331 * g_test_get_filename:
28332 * @file_type: the type of file (built vs. distributed)
28333 * @first_path: the first segment of the pathname
28334 * @...: %NULL-terminated additional path segments
28336 * Gets the pathname to a data file that is required for a test.
28338 * This is the same as g_test_build_filename() with two differences.
28339 * The first difference is that must only use this function from within
28340 * a testcase function. The second difference is that you need not free
28341 * the return value -- it will be automatically freed when the testcase
28342 * finishes running.
28344 * It is safe to use this function from a thread inside of a testcase
28345 * but you must ensure that all such uses occur before the main testcase
28346 * function returns (ie: it is best to ensure that all threads have been
28349 * Returns: the path, automatically freed at the end of the testcase
28357 * Get the toplevel test suite for the test path API.
28359 * Returns: the toplevel #GTestSuite
28365 * g_test_incomplete:
28366 * @msg: (allow-none): explanation
28368 * Indicates that a test failed because of some incomplete
28369 * functionality. This function can be called multiple times
28370 * from the same test.
28372 * Calling this function will not stop the test from running, you
28373 * need to return from the test function yourself. So you can
28374 * produce additional diagnostic messages or even continue running
28377 * If not called from inside a test, this function does nothing.
28385 * @argc: Address of the @argc parameter of the main() function.
28386 * Changed if any arguments were handled.
28387 * @argv: Address of the @argv parameter of main().
28388 * Any parameters understood by g_test_init() stripped before return.
28389 * @...: %NULL-terminated list of special options. Currently the only
28390 * defined option is `"no_g_set_prgname"`, which
28391 * will cause g_test_init() to not call g_set_prgname().
28393 * Initialize the GLib testing framework, e.g. by seeding the
28394 * test random number generator, the name for g_get_prgname()
28395 * and parsing test related command line args.
28397 * So far, the following arguments are understood:
28399 * - `-l`: List test cases available in a test executable.
28400 * - `--seed=SEED`: Provide a random seed to reproduce test
28401 * runs using random numbers.
28402 * - `--verbose`: Run tests verbosely.
28403 * - `-q`, `--quiet`: Run tests quietly.
28404 * - `-p PATH`: Execute all tests matching the given path.
28405 * This can also be used to force a test to run that would otherwise
28406 * be skipped (ie, a test whose name contains "/subprocess").
28407 * - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes:
28409 * `perf`: Performance tests, may take long and report results.
28411 * `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage.
28413 * `quick`: Quick tests, should run really quickly and give good coverage.
28415 * `undefined`: Tests for undefined behaviour, may provoke programming errors
28416 * under g_test_trap_subprocess() or g_test_expect_messages() to check
28417 * that appropriate assertions or warnings are given
28419 * `no-undefined`: Avoid tests for undefined behaviour
28421 * - `--debug-log`: Debug test logging output.
28428 * g_test_initialized:
28430 * Returns %TRUE if g_test_init() has been called.
28432 * Returns: %TRUE if g_test_init() has been called.
28438 * g_test_log_buffer_free:
28440 * Internal function for gtester to free test log messages, no ABI guarantees provided.
28445 * g_test_log_buffer_new:
28447 * Internal function for gtester to decode test log messages, no ABI guarantees provided.
28452 * g_test_log_buffer_pop:
28454 * Internal function for gtester to retrieve test log messages, no ABI guarantees provided.
28459 * g_test_log_buffer_push:
28461 * Internal function for gtester to decode test log messages, no ABI guarantees provided.
28466 * g_test_log_msg_free:
28468 * Internal function for gtester to free test log messages, no ABI guarantees provided.
28473 * g_test_log_set_fatal_handler:
28474 * @log_func: the log handler function.
28475 * @user_data: data passed to the log handler.
28477 * Installs a non-error fatal log handler which can be
28478 * used to decide whether log messages which are counted
28479 * as fatal abort the program.
28481 * The use case here is that you are running a test case
28482 * that depends on particular libraries or circumstances
28483 * and cannot prevent certain known critical or warning
28484 * messages. So you install a handler that compares the
28485 * domain and message to precisely not abort in such a case.
28487 * Note that the handler is reset at the beginning of
28488 * any test case, so you have to set it inside each test
28489 * function which needs the special behavior.
28491 * This handler has no effect on g_error messages.
28498 * g_test_maximized_result:
28499 * @maximized_quantity: the reported value
28500 * @format: the format string of the report message
28501 * @...: arguments to pass to the printf() function
28503 * Report the result of a performance or measurement test.
28504 * The test should generally strive to maximize the reported
28505 * quantities (larger values are better than smaller ones),
28506 * this and @maximized_quantity can determine sorting
28507 * order for test result reports.
28515 * @format: the format string
28516 * @...: printf-like arguments to @format
28518 * Add a message to the test report.
28525 * g_test_minimized_result:
28526 * @minimized_quantity: the reported value
28527 * @format: the format string of the report message
28528 * @...: arguments to pass to the printf() function
28530 * Report the result of a performance or measurement test.
28531 * The test should generally strive to minimize the reported
28532 * quantities (smaller values are better than larger ones),
28533 * this and @minimized_quantity can determine sorting
28534 * order for test result reports.
28543 * Returns %TRUE if tests are run in performance mode.
28545 * Returns: %TRUE if in performance mode
28550 * g_test_queue_destroy:
28551 * @destroy_func: Destroy callback for teardown phase.
28552 * @destroy_data: Destroy callback data.
28554 * This function enqueus a callback @destroy_func to be executed
28555 * during the next test case teardown phase. This is most useful
28556 * to auto destruct allocted test resources at the end of a test run.
28557 * Resources are released in reverse queue order, that means enqueueing
28558 * callback A before callback B will cause B() to be called before
28559 * A() during teardown.
28566 * g_test_queue_free:
28567 * @gfree_pointer: the pointer to be stored.
28569 * Enqueue a pointer to be released with g_free() during the next
28570 * teardown phase. This is equivalent to calling g_test_queue_destroy()
28571 * with a destroy callback of g_free().
28578 * g_test_queue_unref:
28579 * @gobject: the object to unref
28581 * Enqueue an object to be released with g_object_unref() during
28582 * the next teardown phase. This is equivalent to calling
28583 * g_test_queue_destroy() with a destroy callback of g_object_unref().
28592 * Returns %TRUE if tests are run in quick mode.
28593 * Exactly one of g_test_quick() and g_test_slow() is active in any run;
28594 * there is no "medium speed".
28596 * Returns: %TRUE if in quick mode
28603 * Returns %TRUE if tests are run in quiet mode.
28604 * The default is neither g_test_verbose() nor g_test_quiet().
28606 * Returns: %TRUE if in quiet mode
28613 * Get a reproducible random bit (0 or 1), see g_test_rand_int()
28614 * for details on test case random numbers.
28621 * g_test_rand_double:
28623 * Get a reproducible random floating point number,
28624 * see g_test_rand_int() for details on test case random numbers.
28626 * Returns: a random number from the seeded random number generator.
28632 * g_test_rand_double_range:
28633 * @range_start: the minimum value returned by this function
28634 * @range_end: the minimum value not returned by this function
28636 * Get a reproducible random floating pointer number out of a specified range,
28637 * see g_test_rand_int() for details on test case random numbers.
28639 * Returns: a number with @range_start <= number < @range_end.
28647 * Get a reproducible random integer number.
28649 * The random numbers generated by the g_test_rand_*() family of functions
28650 * change with every new test program start, unless the --seed option is
28651 * given when starting test programs.
28653 * For individual test cases however, the random number generator is
28654 * reseeded, to avoid dependencies between tests and to make --seed
28655 * effective for all test cases.
28657 * Returns: a random number from the seeded random number generator.
28663 * g_test_rand_int_range:
28664 * @begin: the minimum value returned by this function
28665 * @end: the smallest value not to be returned by this function
28667 * Get a reproducible random integer number out of a specified range,
28668 * see g_test_rand_int() for details on test case random numbers.
28670 * Returns: a number with @begin <= number < @end.
28678 * Runs all tests under the toplevel suite which can be retrieved
28679 * with g_test_get_root(). Similar to g_test_run_suite(), the test
28680 * cases to be run are filtered according to test path arguments
28681 * (`-p testpath`) as parsed by g_test_init(). g_test_run_suite()
28682 * or g_test_run() may only be called once in a program.
28684 * In general, the tests and sub-suites within each suite are run in
28685 * the order in which they are defined. However, note that prior to
28686 * GLib 2.36, there was a bug in the `g_test_add_*`
28687 * functions which caused them to create multiple suites with the same
28688 * name, meaning that if you created tests "/foo/simple",
28689 * "/bar/simple", and "/foo/using-bar" in that order, they would get
28690 * run in that order (since g_test_run() would run the first "/foo"
28691 * suite, then the "/bar" suite, then the second "/foo" suite). As of
28692 * 2.36, this bug is fixed, and adding the tests in that order would
28693 * result in a running order of "/foo/simple", "/foo/using-bar",
28694 * "/bar/simple". If this new ordering is sub-optimal (because it puts
28695 * more-complicated tests before simpler ones, making it harder to
28696 * figure out exactly what has failed), you can fix it by changing the
28697 * test paths to group tests by suite in a way that will result in the
28698 * desired running order. Eg, "/simple/foo", "/simple/bar",
28699 * "/complex/foo-using-bar".
28701 * However, you should never make the actual result of a test depend
28702 * on the order that tests are run in. If you need to ensure that some
28703 * particular code runs before or after a given test case, use
28704 * g_test_add(), which lets you specify setup and teardown functions.
28706 * If all tests are skipped, this function will return 0 if
28707 * producing TAP output, or 77 (treated as "skip test" by Automake) otherwise.
28709 * Returns: 0 on success, 1 on failure (assuming it returns at all),
28710 * 0 or 77 if all tests were skipped with g_test_skip()
28716 * g_test_run_suite:
28717 * @suite: a #GTestSuite
28719 * Execute the tests within @suite and all nested #GTestSuites.
28720 * The test suites to be executed are filtered according to
28721 * test path arguments (`-p testpath`) as parsed by g_test_init().
28722 * See the g_test_run() documentation for more information on the
28723 * order that tests are run in.
28725 * g_test_run_suite() or g_test_run() may only be called once
28728 * Returns: 0 on success
28734 * g_test_set_nonfatal_assertions:
28736 * Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(),
28737 * g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(),
28738 * g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(),
28739 * g_assert_error(), g_test_assert_expected_messages() and the various
28740 * g_test_trap_assert_*() macros to not abort to program, but instead
28741 * call g_test_fail() and continue. (This also changes the behavior of
28742 * g_test_fail() so that it will not cause the test program to abort
28743 * after completing the failed test.)
28745 * Note that the g_assert_not_reached() and g_assert() are not
28746 * affected by this.
28748 * This function can only be called after g_test_init().
28756 * @msg: (allow-none): explanation
28758 * Indicates that a test was skipped.
28760 * Calling this function will not stop the test from running, you
28761 * need to return from the test function yourself. So you can
28762 * produce additional diagnostic messages or even continue running
28765 * If not called from inside a test, this function does nothing.
28774 * Returns %TRUE if tests are run in slow mode.
28775 * Exactly one of g_test_quick() and g_test_slow() is active in any run;
28776 * there is no "medium speed".
28778 * Returns: the opposite of g_test_quick()
28783 * g_test_subprocess:
28785 * Returns %TRUE (after g_test_init() has been called) if the test
28786 * program is running under g_test_trap_subprocess().
28788 * Returns: %TRUE if the test program is running under
28789 * g_test_trap_subprocess().
28795 * g_test_suite_add:
28796 * @suite: a #GTestSuite
28797 * @test_case: a #GTestCase
28799 * Adds @test_case to @suite.
28806 * g_test_suite_add_suite:
28807 * @suite: a #GTestSuite
28808 * @nestedsuite: another #GTestSuite
28810 * Adds @nestedsuite to @suite.
28819 * Returns %TRUE if tests are run in thorough mode, equivalent to
28822 * Returns: the same thing as g_test_slow()
28827 * g_test_timer_elapsed:
28829 * Get the time since the last start of the timer with g_test_timer_start().
28831 * Returns: the time since the last start of the timer, as a double
28837 * g_test_timer_last:
28839 * Report the last result of g_test_timer_elapsed().
28841 * Returns: the last result of g_test_timer_elapsed(), as a double
28847 * g_test_timer_start:
28849 * Start a timing test. Call g_test_timer_elapsed() when the task is supposed
28850 * to be done. Call this function again to restart the timer.
28857 * g_test_trap_assert_failed:
28859 * Assert that the last test subprocess failed.
28860 * See g_test_trap_subprocess().
28862 * This is sometimes used to test situations that are formally considered to
28863 * be undefined behaviour, like inputs that fail a g_return_if_fail()
28864 * check. In these situations you should skip the entire test, including the
28865 * call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE
28866 * to indicate that undefined behaviour may be tested.
28873 * g_test_trap_assert_passed:
28875 * Assert that the last test subprocess passed.
28876 * See g_test_trap_subprocess().
28883 * g_test_trap_assert_stderr:
28884 * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
28886 * Assert that the stderr output of the last test subprocess
28887 * matches @serrpattern. See g_test_trap_subprocess().
28889 * This is sometimes used to test situations that are formally
28890 * considered to be undefined behaviour, like code that hits a
28891 * g_assert() or g_error(). In these situations you should skip the
28892 * entire test, including the call to g_test_trap_subprocess(), unless
28893 * g_test_undefined() returns %TRUE to indicate that undefined
28894 * behaviour may be tested.
28901 * g_test_trap_assert_stderr_unmatched:
28902 * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
28904 * Assert that the stderr output of the last test subprocess
28905 * does not match @serrpattern. See g_test_trap_subprocess().
28912 * g_test_trap_assert_stdout:
28913 * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
28915 * Assert that the stdout output of the last test subprocess matches
28916 * @soutpattern. See g_test_trap_subprocess().
28923 * g_test_trap_assert_stdout_unmatched:
28924 * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
28926 * Assert that the stdout output of the last test subprocess
28927 * does not match @soutpattern. See g_test_trap_subprocess().
28934 * g_test_trap_fork:
28935 * @usec_timeout: Timeout for the forked test in micro seconds.
28936 * @test_trap_flags: Flags to modify forking behaviour.
28938 * Fork the current test program to execute a test case that might
28939 * not return or that might abort.
28941 * If @usec_timeout is non-0, the forked test case is aborted and
28942 * considered failing if its run time exceeds it.
28944 * The forking behavior can be configured with the #GTestTrapFlags flags.
28946 * In the following example, the test code forks, the forked child
28947 * process produces some sample output and exits successfully.
28948 * The forking parent process then asserts successful child program
28949 * termination and validates child program outputs.
28951 * |[<!-- language="C" -->
28953 * test_fork_patterns (void)
28955 * if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
28957 * g_print ("some stdout text: somagic17\n");
28958 * g_printerr ("some stderr text: semagic43\n");
28959 * exit (0); // successful test run
28961 * g_test_trap_assert_passed ();
28962 * g_test_trap_assert_stdout ("*somagic17*");
28963 * g_test_trap_assert_stderr ("*semagic43*");
28967 * Returns: %TRUE for the forked child and %FALSE for the executing parent process.
28969 * Deprecated: This function is implemented only on Unix platforms,
28970 * and is not always reliable due to problems inherent in
28971 * fork-without-exec. Use g_test_trap_subprocess() instead.
28976 * g_test_trap_has_passed:
28978 * Check the result of the last g_test_trap_subprocess() call.
28980 * Returns: %TRUE if the last test subprocess terminated successfully.
28986 * g_test_trap_reached_timeout:
28988 * Check the result of the last g_test_trap_subprocess() call.
28990 * Returns: %TRUE if the last test subprocess got killed due to a timeout.
28996 * g_test_trap_subprocess:
28997 * @test_path: (allow-none): Test to run in a subprocess
28998 * @usec_timeout: Timeout for the subprocess test in micro seconds.
28999 * @test_flags: Flags to modify subprocess behaviour.
29001 * Respawns the test program to run only @test_path in a subprocess.
29002 * This can be used for a test case that might not return, or that
29005 * If @test_path is %NULL then the same test is re-run in a subprocess.
29006 * You can use g_test_subprocess() to determine whether the test is in
29007 * a subprocess or not.
29009 * @test_path can also be the name of the parent test, followed by
29010 * "`/subprocess/`" and then a name for the specific subtest (or just
29011 * ending with "`/subprocess`" if the test only has one child test);
29012 * tests with names of this form will automatically be skipped in the
29015 * If @usec_timeout is non-0, the test subprocess is aborted and
29016 * considered failing if its run time exceeds it.
29018 * The subprocess behavior can be configured with the
29019 * #GTestSubprocessFlags flags.
29021 * You can use methods such as g_test_trap_assert_passed(),
29022 * g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to
29023 * check the results of the subprocess. (But note that
29024 * g_test_trap_assert_stdout() and g_test_trap_assert_stderr()
29025 * cannot be used if @test_flags specifies that the child should
29026 * inherit the parent stdout/stderr.)
29028 * If your `main ()` needs to behave differently in
29029 * the subprocess, you can call g_test_subprocess() (after calling
29030 * g_test_init()) to see whether you are in a subprocess.
29032 * The following example tests that calling
29033 * `my_object_new(1000000)` will abort with an error
29036 * |[<!-- language="C" -->
29038 * test_create_large_object_subprocess (void)
29040 * if (g_test_subprocess ())
29042 * my_object_new (1000000);
29046 * // Reruns this same test in a subprocess
29047 * g_test_trap_subprocess (NULL, 0, 0);
29048 * g_test_trap_assert_failed ();
29049 * g_test_trap_assert_stderr ("*ERROR*too large*");
29053 * main (int argc, char **argv)
29055 * g_test_init (&argc, &argv, NULL);
29057 * g_test_add_func ("/myobject/create_large_object",
29058 * test_create_large_object);
29059 * return g_test_run ();
29068 * g_test_undefined:
29070 * Returns %TRUE if tests may provoke assertions and other formally-undefined
29071 * behaviour, to verify that appropriate warnings are given. It might, in some
29072 * cases, be useful to turn this off if running tests under valgrind.
29074 * Returns: %TRUE if tests may provoke programming errors
29081 * Returns %TRUE if tests are run in verbose mode.
29082 * The default is neither g_test_verbose() nor g_test_quiet().
29084 * Returns: %TRUE if in verbose mode
29090 * @retval: the return value of this thread
29092 * Terminates the current thread.
29094 * If another thread is waiting for us using g_thread_join() then the
29095 * waiting thread will be woken up and get @retval as the return value
29096 * of g_thread_join().
29098 * Calling g_thread_exit() with a parameter @retval is equivalent to
29099 * returning @retval from the function @func, as given to g_thread_new().
29101 * You must only call g_thread_exit() from a thread that you created
29102 * yourself with g_thread_new() or related APIs. You must not call
29103 * this function from a thread created with another threading library
29104 * or or from within a #GThreadPool.
29110 * @thread: a #GThread
29112 * Waits until @thread finishes, i.e. the function @func, as
29113 * given to g_thread_new(), returns or g_thread_exit() is called.
29114 * If @thread has already terminated, then g_thread_join()
29115 * returns immediately.
29117 * Any thread can wait for any other thread by calling g_thread_join(),
29118 * not just its 'creator'. Calling g_thread_join() from multiple threads
29119 * for the same @thread leads to undefined behaviour.
29121 * The value returned by @func or given to g_thread_exit() is
29122 * returned by this function.
29124 * g_thread_join() consumes the reference to the passed-in @thread.
29125 * This will usually cause the #GThread struct and associated resources
29126 * to be freed. Use g_thread_ref() to obtain an extra reference if you
29127 * want to keep the GThread alive beyond the g_thread_join() call.
29129 * Returns: the return value of the thread
29135 * @name: (allow-none): an (optional) name for the new thread
29136 * @func: a function to execute in the new thread
29137 * @data: an argument to supply to the new thread
29139 * This function creates a new thread. The new thread starts by invoking
29140 * @func with the argument data. The thread will run until @func returns
29141 * or until g_thread_exit() is called from the new thread. The return value
29142 * of @func becomes the return value of the thread, which can be obtained
29143 * with g_thread_join().
29145 * The @name can be useful for discriminating threads in a debugger.
29146 * It is not used for other purposes and does not have to be unique.
29147 * Some systems restrict the length of @name to 16 bytes.
29149 * If the thread can not be created the program aborts. See
29150 * g_thread_try_new() if you want to attempt to deal with failures.
29152 * To free the struct returned by this function, use g_thread_unref().
29153 * Note that g_thread_join() implicitly unrefs the #GThread as well.
29155 * Returns: the new #GThread
29161 * g_thread_pool_free:
29162 * @pool: a #GThreadPool
29163 * @immediate: should @pool shut down immediately?
29164 * @wait_: should the function wait for all tasks to be finished?
29166 * Frees all resources allocated for @pool.
29168 * If @immediate is %TRUE, no new task is processed for @pool.
29169 * Otherwise @pool is not freed before the last task is processed.
29170 * Note however, that no thread of this pool is interrupted while
29171 * processing a task. Instead at least all still running threads
29172 * can finish their tasks before the @pool is freed.
29174 * If @wait_ is %TRUE, the functions does not return before all
29175 * tasks to be processed (dependent on @immediate, whether all
29176 * or only the currently running) are ready.
29177 * Otherwise the function returns immediately.
29179 * After calling this function @pool must not be used anymore.
29184 * g_thread_pool_get_max_idle_time:
29186 * This function will return the maximum @interval that a
29187 * thread will wait in the thread pool for new tasks before
29190 * If this function returns 0, threads waiting in the thread
29191 * pool for new work are not stopped.
29193 * Returns: the maximum @interval (milliseconds) to wait
29194 * for new tasks in the thread pool before stopping the
29201 * g_thread_pool_get_max_threads:
29202 * @pool: a #GThreadPool
29204 * Returns the maximal number of threads for @pool.
29206 * Returns: the maximal number of threads
29211 * g_thread_pool_get_max_unused_threads:
29213 * Returns the maximal allowed number of unused threads.
29215 * Returns: the maximal number of unused threads
29220 * g_thread_pool_get_num_threads:
29221 * @pool: a #GThreadPool
29223 * Returns the number of threads currently running in @pool.
29225 * Returns: the number of threads currently running
29230 * g_thread_pool_get_num_unused_threads:
29232 * Returns the number of currently unused threads.
29234 * Returns: the number of currently unused threads
29239 * g_thread_pool_new:
29240 * @func: a function to execute in the threads of the new thread pool
29241 * @user_data: user data that is handed over to @func every time it
29243 * @max_threads: the maximal number of threads to execute concurrently
29244 * in the new thread pool, -1 means no limit
29245 * @exclusive: should this thread pool be exclusive?
29246 * @error: return location for error, or %NULL
29248 * This function creates a new thread pool.
29250 * Whenever you call g_thread_pool_push(), either a new thread is
29251 * created or an unused one is reused. At most @max_threads threads
29252 * are running concurrently for this thread pool. @max_threads = -1
29253 * allows unlimited threads to be created for this thread pool. The
29254 * newly created or reused thread now executes the function @func
29255 * with the two arguments. The first one is the parameter to
29256 * g_thread_pool_push() and the second one is @user_data.
29258 * The parameter @exclusive determines whether the thread pool owns
29259 * all threads exclusive or shares them with other thread pools.
29260 * If @exclusive is %TRUE, @max_threads threads are started
29261 * immediately and they will run exclusively for this thread pool
29262 * until it is destroyed by g_thread_pool_free(). If @exclusive is
29263 * %FALSE, threads are created when needed and shared between all
29264 * non-exclusive thread pools. This implies that @max_threads may
29265 * not be -1 for exclusive thread pools.
29267 * @error can be %NULL to ignore errors, or non-%NULL to report
29268 * errors. An error can only occur when @exclusive is set to %TRUE
29269 * and not all @max_threads threads could be created.
29271 * Returns: the new #GThreadPool
29276 * g_thread_pool_push:
29277 * @pool: a #GThreadPool
29278 * @data: a new task for @pool
29279 * @error: return location for error, or %NULL
29281 * Inserts @data into the list of tasks to be executed by @pool.
29283 * When the number of currently running threads is lower than the
29284 * maximal allowed number of threads, a new thread is started (or
29285 * reused) with the properties given to g_thread_pool_new().
29286 * Otherwise, @data stays in the queue until a thread in this pool
29287 * finishes its previous task and processes @data.
29289 * @error can be %NULL to ignore errors, or non-%NULL to report
29290 * errors. An error can only occur when a new thread couldn't be
29291 * created. In that case @data is simply appended to the queue of
29294 * Before version 2.32, this function did not return a success status.
29296 * Returns: %TRUE on success, %FALSE if an error occurred
29301 * g_thread_pool_set_max_idle_time:
29302 * @interval: the maximum @interval (in milliseconds)
29303 * a thread can be idle
29305 * This function will set the maximum @interval that a thread
29306 * waiting in the pool for new tasks can be idle for before
29307 * being stopped. This function is similar to calling
29308 * g_thread_pool_stop_unused_threads() on a regular timeout,
29309 * except this is done on a per thread basis.
29311 * By setting @interval to 0, idle threads will not be stopped.
29313 * The default value is 15000 (15 seconds).
29320 * g_thread_pool_set_max_threads:
29321 * @pool: a #GThreadPool
29322 * @max_threads: a new maximal number of threads for @pool,
29323 * or -1 for unlimited
29324 * @error: return location for error, or %NULL
29326 * Sets the maximal allowed number of threads for @pool.
29327 * A value of -1 means that the maximal number of threads
29328 * is unlimited. If @pool is an exclusive thread pool, setting
29329 * the maximal number of threads to -1 is not allowed.
29331 * Setting @max_threads to 0 means stopping all work for @pool.
29332 * It is effectively frozen until @max_threads is set to a non-zero
29335 * A thread is never terminated while calling @func, as supplied by
29336 * g_thread_pool_new(). Instead the maximal number of threads only
29337 * has effect for the allocation of new threads in g_thread_pool_push().
29338 * A new thread is allocated, whenever the number of currently
29339 * running threads in @pool is smaller than the maximal number.
29341 * @error can be %NULL to ignore errors, or non-%NULL to report
29342 * errors. An error can only occur when a new thread couldn't be
29345 * Before version 2.32, this function did not return a success status.
29347 * Returns: %TRUE on success, %FALSE if an error occurred
29352 * g_thread_pool_set_max_unused_threads:
29353 * @max_threads: maximal number of unused threads
29355 * Sets the maximal number of unused threads to @max_threads.
29356 * If @max_threads is -1, no limit is imposed on the number
29357 * of unused threads.
29359 * The default value is 2.
29364 * g_thread_pool_set_sort_function:
29365 * @pool: a #GThreadPool
29366 * @func: the #GCompareDataFunc used to sort the list of tasks.
29367 * This function is passed two tasks. It should return
29368 * 0 if the order in which they are handled does not matter,
29369 * a negative value if the first task should be processed before
29370 * the second or a positive value if the second task should be
29372 * @user_data: user data passed to @func
29374 * Sets the function used to sort the list of tasks. This allows the
29375 * tasks to be processed by a priority determined by @func, and not
29376 * just in the order in which they were added to the pool.
29378 * Note, if the maximum number of threads is more than 1, the order
29379 * that threads are executed cannot be guaranteed 100%. Threads are
29380 * scheduled by the operating system and are executed at random. It
29381 * cannot be assumed that threads are executed in the order they are
29389 * g_thread_pool_stop_unused_threads:
29391 * Stops all currently unused threads. This does not change the
29392 * maximal number of unused threads. This function can be used to
29393 * regularly stop all unused threads e.g. from g_timeout_add().
29398 * g_thread_pool_unprocessed:
29399 * @pool: a #GThreadPool
29401 * Returns the number of tasks still unprocessed in @pool.
29403 * Returns: the number of unprocessed tasks
29409 * @thread: a #GThread
29411 * Increase the reference count on @thread.
29413 * Returns: a new reference to @thread
29421 * This functions returns the #GThread corresponding to the
29422 * current thread. Note that this function does not increase
29423 * the reference count of the returned struct.
29425 * This function will return a #GThread even for threads that
29426 * were not created by GLib (i.e. those created by other threading
29427 * APIs). This may be useful for thread identification purposes
29428 * (i.e. comparisons) but you must not use GLib functions (such
29429 * as g_thread_join()) on these threads.
29431 * Returns: the #GThread representing the current thread
29436 * g_thread_supported:
29438 * This macro returns %TRUE if the thread system is initialized,
29439 * and %FALSE if it is not.
29441 * For language bindings, g_thread_get_initialized() provides
29442 * the same functionality as a function.
29444 * Returns: %TRUE, if the thread system is initialized
29449 * g_thread_try_new:
29450 * @name: (allow-none): an (optional) name for the new thread
29451 * @func: a function to execute in the new thread
29452 * @data: an argument to supply to the new thread
29453 * @error: return location for error, or %NULL
29455 * This function is the same as g_thread_new() except that
29456 * it allows for the possibility of failure.
29458 * If a thread can not be created (due to resource limits),
29459 * @error is set and %NULL is returned.
29461 * Returns: the new #GThread, or %NULL if an error occurred
29468 * @thread: a #GThread
29470 * Decrease the reference count on @thread, possibly freeing all
29471 * resources associated with it.
29473 * Note that each thread holds a reference to its #GThread while
29474 * it is running, so it is safe to drop your own reference to it
29475 * if you don't need it anymore.
29484 * Causes the calling thread to voluntarily relinquish the CPU, so
29485 * that other threads can run.
29487 * This function is often used as a method to make busy wait less evil.
29493 * @time_: a #GTimeVal
29494 * @microseconds: number of microseconds to add to @time
29496 * Adds the given number of microseconds to @time_. @microseconds can
29497 * also be negative to decrease the value of @time_.
29502 * g_time_val_from_iso8601:
29503 * @iso_date: an ISO 8601 encoded date string
29504 * @time_: (out): a #GTimeVal
29506 * Converts a string containing an ISO 8601 encoded date and time
29507 * to a #GTimeVal and puts it into @time_.
29509 * @iso_date must include year, month, day, hours, minutes, and
29510 * seconds. It can optionally include fractions of a second and a time
29511 * zone indicator. (In the absence of any time zone indication, the
29512 * timestamp is assumed to be in local time.)
29514 * Returns: %TRUE if the conversion was successful.
29520 * g_time_val_to_iso8601:
29521 * @time_: a #GTimeVal
29523 * Converts @time_ into an RFC 3339 encoded string, relative to the
29524 * Coordinated Universal Time (UTC). This is one of the many formats
29525 * allowed by ISO 8601.
29527 * ISO 8601 allows a large number of date/time formats, with or without
29528 * punctuation and optional elements. The format returned by this function
29529 * is a complete date and time, with optional punctuation included, the
29530 * UTC time zone represented as "Z", and the @tv_usec part included if
29531 * and only if it is nonzero, i.e. either
29532 * "YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ".
29534 * This corresponds to the Internet date/time format defined by
29535 * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt),
29536 * and to either of the two most-precise formats defined by
29538 * [Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827).
29539 * Both of these documents are profiles of ISO 8601.
29541 * Use g_date_time_format() or g_strdup_printf() if a different
29542 * variation of ISO 8601 format is required.
29544 * Returns: a newly allocated string containing an ISO 8601 date
29550 * g_time_zone_adjust_time:
29551 * @tz: a #GTimeZone
29552 * @type: the #GTimeType of @time_
29553 * @time_: a pointer to a number of seconds since January 1, 1970
29555 * Finds an interval within @tz that corresponds to the given @time_,
29556 * possibly adjusting @time_ if required to fit into an interval.
29557 * The meaning of @time_ depends on @type.
29559 * This function is similar to g_time_zone_find_interval(), with the
29560 * difference that it always succeeds (by making the adjustments
29561 * described below).
29563 * In any of the cases where g_time_zone_find_interval() succeeds then
29564 * this function returns the same value, without modifying @time_.
29566 * This function may, however, modify @time_ in order to deal with
29567 * non-existent times. If the non-existent local @time_ of 02:30 were
29568 * requested on March 14th 2010 in Toronto then this function would
29569 * adjust @time_ to be 03:00 and return the interval containing the
29572 * Returns: the interval containing @time_, never -1
29578 * g_time_zone_find_interval:
29579 * @tz: a #GTimeZone
29580 * @type: the #GTimeType of @time_
29581 * @time_: a number of seconds since January 1, 1970
29583 * Finds an the interval within @tz that corresponds to the given @time_.
29584 * The meaning of @time_ depends on @type.
29586 * If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
29587 * succeed (since universal time is monotonic and continuous).
29589 * Otherwise @time_ is treated is local time. The distinction between
29590 * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
29591 * the case that the given @time_ is ambiguous. In Toronto, for example,
29592 * 01:30 on November 7th 2010 occurred twice (once inside of daylight
29593 * savings time and the next, an hour later, outside of daylight savings
29594 * time). In this case, the different value of @type would result in a
29595 * different interval being returned.
29597 * It is still possible for this function to fail. In Toronto, for
29598 * example, 02:00 on March 14th 2010 does not exist (due to the leap
29599 * forward to begin daylight savings time). -1 is returned in that
29602 * Returns: the interval containing @time_, or -1 in case of failure
29608 * g_time_zone_get_abbreviation:
29609 * @tz: a #GTimeZone
29610 * @interval: an interval within the timezone
29612 * Determines the time zone abbreviation to be used during a particular
29613 * @interval of time in the time zone @tz.
29615 * For example, in Toronto this is currently "EST" during the winter
29616 * months and "EDT" during the summer months when daylight savings time
29619 * Returns: the time zone abbreviation, which belongs to @tz
29625 * g_time_zone_get_offset:
29626 * @tz: a #GTimeZone
29627 * @interval: an interval within the timezone
29629 * Determines the offset to UTC in effect during a particular @interval
29630 * of time in the time zone @tz.
29632 * The offset is the number of seconds that you add to UTC time to
29633 * arrive at local time for @tz (ie: negative numbers for time zones
29634 * west of GMT, positive numbers for east).
29636 * Returns: the number of seconds that should be added to UTC to get the
29637 * local time in @tz
29643 * g_time_zone_is_dst:
29644 * @tz: a #GTimeZone
29645 * @interval: an interval within the timezone
29647 * Determines if daylight savings time is in effect during a particular
29648 * @interval of time in the time zone @tz.
29650 * Returns: %TRUE if daylight savings time is in effect
29657 * @identifier: (allow-none): a timezone identifier
29659 * Creates a #GTimeZone corresponding to @identifier.
29661 * @identifier can either be an RFC3339/ISO 8601 time offset or
29662 * something that would pass as a valid value for the `TZ` environment
29663 * variable (including %NULL).
29665 * In Windows, @identifier can also be the unlocalized name of a time
29666 * zone for standard time, for example "Pacific Standard Time".
29668 * Valid RFC3339 time offsets are `"Z"` (for UTC) or
29669 * `"±hh:mm"`. ISO 8601 additionally specifies
29670 * `"±hhmm"` and `"±hh"`. Offsets are
29671 * time values to be added to Coordinated Universal Time (UTC) to get
29674 * In UNIX, the `TZ` environment variable typically corresponds
29675 * to the name of a file in the zoneinfo database, or string in
29676 * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
29677 * There are no spaces in the specification. The name of standard
29678 * and daylight savings time zone must be three or more alphabetic
29679 * characters. Offsets are time values to be added to local time to
29680 * get Coordinated Universal Time (UTC) and should be
29681 * `"[±]hh[[:]mm[:ss]]"`. Dates are either
29682 * `"Jn"` (Julian day with n between 1 and 365, leap
29683 * years not counted), `"n"` (zero-based Julian day
29684 * with n between 0 and 365) or `"Mm.w.d"` (day d
29685 * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
29686 * 0 is a Sunday). Times are in local wall clock time, the default is
29689 * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
29690 * accepts POSIX format. The Windows format uses US rules for all time
29691 * zones; daylight savings time is 60 minutes behind the standard time
29692 * with date and time of change taken from Pacific Standard Time.
29693 * Offsets are time values to be added to the local time to get
29694 * Coordinated Universal Time (UTC).
29696 * g_time_zone_new_local() calls this function with the value of the
29697 * `TZ` environment variable. This function itself is independent of
29698 * the value of `TZ`, but if @identifier is %NULL then `/etc/localtime`
29699 * will be consulted to discover the correct time zone on UNIX and the
29700 * registry will be consulted or GetTimeZoneInformation() will be used
29701 * to get the local time zone on Windows.
29703 * If intervals are not available, only time zone rules from `TZ`
29704 * environment variable or other means, then they will be computed
29705 * from year 1900 to 2037. If the maximum year for the rules is
29706 * available and it is greater than 2037, then it will followed
29710 * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
29711 * for a precise definition of valid RFC3339 time offsets
29712 * (the `time-offset` expansion) and ISO 8601 for the
29713 * full list of valid time offsets. See
29714 * [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
29715 * for an explanation of the possible
29716 * values of the `TZ` environment variable. See
29717 * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
29718 * for the list of time zones on Windows.
29720 * You should release the return value by calling g_time_zone_unref()
29721 * when you are done with it.
29723 * Returns: the requested timezone
29729 * g_time_zone_new_local:
29731 * Creates a #GTimeZone corresponding to local time. The local time
29732 * zone may change between invocations to this function; for example,
29733 * if the system administrator changes it.
29735 * This is equivalent to calling g_time_zone_new() with the value of
29736 * the `TZ` environment variable (including the possibility of %NULL).
29738 * You should release the return value by calling g_time_zone_unref()
29739 * when you are done with it.
29741 * Returns: the local timezone
29747 * g_time_zone_new_utc:
29749 * Creates a #GTimeZone corresponding to UTC.
29751 * This is equivalent to calling g_time_zone_new() with a value like
29752 * "Z", "UTC", "+00", etc.
29754 * You should release the return value by calling g_time_zone_unref()
29755 * when you are done with it.
29757 * Returns: the universal timezone
29764 * @tz: a #GTimeZone
29766 * Increases the reference count on @tz.
29768 * Returns: a new reference to @tz.
29774 * g_time_zone_unref:
29775 * @tz: a #GTimeZone
29777 * Decreases the reference count on @tz.
29785 * @interval: the time between calls to the function, in milliseconds
29786 * (1/1000ths of a second)
29787 * @function: function to call
29788 * @data: data to pass to @function
29790 * Sets a function to be called at regular intervals, with the default
29791 * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly
29792 * until it returns %FALSE, at which point the timeout is automatically
29793 * destroyed and the function will not be called again. The first call
29794 * to the function will be at the end of the first @interval.
29796 * Note that timeout functions may be delayed, due to the processing of other
29797 * event sources. Thus they should not be relied on for precise timing.
29798 * After each call to the timeout function, the time of the next
29799 * timeout is recalculated based on the current time and the given interval
29800 * (it does not try to 'catch up' time lost in delays).
29802 * If you want to have a timer in the "seconds" range and do not care
29803 * about the exact time of the first call of the timer, use the
29804 * g_timeout_add_seconds() function; this function allows for more
29805 * optimizations and more efficient system power usage.
29807 * This internally creates a main loop source using g_timeout_source_new()
29808 * and attaches it to the main loop context using g_source_attach(). You can
29809 * do these steps manually if you need greater control.
29811 * The interval given is in terms of monotonic time, not wall clock
29812 * time. See g_get_monotonic_time().
29814 * Returns: the ID (greater than 0) of the event source.
29819 * g_timeout_add_full: (rename-to g_timeout_add)
29820 * @priority: the priority of the timeout source. Typically this will be in
29821 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
29822 * @interval: the time between calls to the function, in milliseconds
29823 * (1/1000ths of a second)
29824 * @function: function to call
29825 * @data: data to pass to @function
29826 * @notify: (allow-none): function to call when the timeout is removed, or %NULL
29828 * Sets a function to be called at regular intervals, with the given
29829 * priority. The function is called repeatedly until it returns
29830 * %FALSE, at which point the timeout is automatically destroyed and
29831 * the function will not be called again. The @notify function is
29832 * called when the timeout is destroyed. The first call to the
29833 * function will be at the end of the first @interval.
29835 * Note that timeout functions may be delayed, due to the processing of other
29836 * event sources. Thus they should not be relied on for precise timing.
29837 * After each call to the timeout function, the time of the next
29838 * timeout is recalculated based on the current time and the given interval
29839 * (it does not try to 'catch up' time lost in delays).
29841 * This internally creates a main loop source using g_timeout_source_new()
29842 * and attaches it to the main loop context using g_source_attach(). You can
29843 * do these steps manually if you need greater control.
29845 * The interval given in terms of monotonic time, not wall clock time.
29846 * See g_get_monotonic_time().
29848 * Returns: the ID (greater than 0) of the event source.
29853 * g_timeout_add_seconds:
29854 * @interval: the time between calls to the function, in seconds
29855 * @function: function to call
29856 * @data: data to pass to @function
29858 * Sets a function to be called at regular intervals with the default
29859 * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until
29860 * it returns %FALSE, at which point the timeout is automatically destroyed
29861 * and the function will not be called again.
29863 * This internally creates a main loop source using
29864 * g_timeout_source_new_seconds() and attaches it to the main loop context
29865 * using g_source_attach(). You can do these steps manually if you need
29866 * greater control. Also see g_timeout_add_seconds_full().
29868 * Note that the first call of the timer may not be precise for timeouts
29869 * of one second. If you need finer precision and have such a timeout,
29870 * you may want to use g_timeout_add() instead.
29872 * The interval given is in terms of monotonic time, not wall clock
29873 * time. See g_get_monotonic_time().
29875 * Returns: the ID (greater than 0) of the event source.
29881 * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds)
29882 * @priority: the priority of the timeout source. Typically this will be in
29883 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
29884 * @interval: the time between calls to the function, in seconds
29885 * @function: function to call
29886 * @data: data to pass to @function
29887 * @notify: (allow-none): function to call when the timeout is removed, or %NULL
29889 * Sets a function to be called at regular intervals, with @priority.
29890 * The function is called repeatedly until it returns %FALSE, at which
29891 * point the timeout is automatically destroyed and the function will
29892 * not be called again.
29894 * Unlike g_timeout_add(), this function operates at whole second granularity.
29895 * The initial starting point of the timer is determined by the implementation
29896 * and the implementation is expected to group multiple timers together so that
29897 * they fire all at the same time.
29898 * To allow this grouping, the @interval to the first timer is rounded
29899 * and can deviate up to one second from the specified interval.
29900 * Subsequent timer iterations will generally run at the specified interval.
29902 * Note that timeout functions may be delayed, due to the processing of other
29903 * event sources. Thus they should not be relied on for precise timing.
29904 * After each call to the timeout function, the time of the next
29905 * timeout is recalculated based on the current time and the given @interval
29907 * If you want timing more precise than whole seconds, use g_timeout_add()
29910 * The grouping of timers to fire at the same time results in a more power
29911 * and CPU efficient behavior so if your timer is in multiples of seconds
29912 * and you don't require the first timer exactly one second from now, the
29913 * use of g_timeout_add_seconds() is preferred over g_timeout_add().
29915 * This internally creates a main loop source using
29916 * g_timeout_source_new_seconds() and attaches it to the main loop context
29917 * using g_source_attach(). You can do these steps manually if you need
29920 * The interval given is in terms of monotonic time, not wall clock
29921 * time. See g_get_monotonic_time().
29923 * Returns: the ID (greater than 0) of the event source.
29929 * g_timeout_source_new:
29930 * @interval: the timeout interval in milliseconds.
29932 * Creates a new timeout source.
29934 * The source will not initially be associated with any #GMainContext
29935 * and must be added to one with g_source_attach() before it will be
29938 * The interval given is in terms of monotonic time, not wall clock
29939 * time. See g_get_monotonic_time().
29941 * Returns: the newly-created timeout source
29946 * g_timeout_source_new_seconds:
29947 * @interval: the timeout interval in seconds
29949 * Creates a new timeout source.
29951 * The source will not initially be associated with any #GMainContext
29952 * and must be added to one with g_source_attach() before it will be
29955 * The scheduling granularity/accuracy of this timeout source will be
29958 * The interval given in terms of monotonic time, not wall clock time.
29959 * See g_get_monotonic_time().
29961 * Returns: the newly-created timeout source
29967 * g_timer_continue:
29968 * @timer: a #GTimer.
29970 * Resumes a timer that has previously been stopped with
29971 * g_timer_stop(). g_timer_stop() must be called before using this
29980 * @timer: a #GTimer to destroy.
29982 * Destroys a timer, freeing associated resources.
29988 * @timer: a #GTimer.
29989 * @microseconds: return location for the fractional part of seconds
29990 * elapsed, in microseconds (that is, the total number
29991 * of microseconds elapsed, modulo 1000000), or %NULL
29993 * If @timer has been started but not stopped, obtains the time since
29994 * the timer was started. If @timer has been stopped, obtains the
29995 * elapsed time between the time it was started and the time it was
29996 * stopped. The return value is the number of seconds elapsed,
29997 * including any fractional part. The @microseconds out parameter is
29998 * essentially useless.
30000 * Returns: seconds elapsed as a floating point value, including any
30008 * Creates a new timer, and starts timing (i.e. g_timer_start() is
30009 * implicitly called for you).
30011 * Returns: a new #GTimer.
30017 * @timer: a #GTimer.
30019 * This function is useless; it's fine to call g_timer_start() on an
30020 * already-started timer to reset the start time, so g_timer_reset()
30021 * serves no purpose.
30027 * @timer: a #GTimer.
30029 * Marks a start time, so that future calls to g_timer_elapsed() will
30030 * report the time since g_timer_start() was called. g_timer_new()
30031 * automatically marks the start time, so no need to call
30032 * g_timer_start() immediately after creating the timer.
30038 * @timer: a #GTimer.
30040 * Marks an end time, so calls to g_timer_elapsed() will return the
30041 * difference between this end time and the start time.
30046 * g_trash_stack_height:
30047 * @stack_p: a #GTrashStack
30049 * Returns the height of a #GTrashStack.
30051 * Note that execution of this function is of O(N) complexity
30052 * where N denotes the number of items on the stack.
30054 * Returns: the height of the stack
30059 * g_trash_stack_peek:
30060 * @stack_p: a #GTrashStack
30062 * Returns the element at the top of a #GTrashStack
30063 * which may be %NULL.
30065 * Returns: the element at the top of the stack
30070 * g_trash_stack_pop:
30071 * @stack_p: a #GTrashStack
30073 * Pops a piece of memory off a #GTrashStack.
30075 * Returns: the element at the top of the stack
30080 * g_trash_stack_push:
30081 * @stack_p: a #GTrashStack
30082 * @data_p: the piece of memory to push on the stack
30084 * Pushes a piece of memory onto a #GTrashStack.
30092 * Removes all keys and values from the #GTree and decreases its
30093 * reference count by one. If keys and/or values are dynamically
30094 * allocated, you should either free them first or create the #GTree
30095 * using g_tree_new_full(). In the latter case the destroy functions
30096 * you supplied will be called on all keys and values before destroying
30104 * @func: the function to call for each node visited.
30105 * If this function returns %TRUE, the traversal is stopped.
30106 * @user_data: user data to pass to the function
30108 * Calls the given function for each of the key/value pairs in the #GTree.
30109 * The function is passed the key and value of each pair, and the given
30110 * @data parameter. The tree is traversed in sorted order.
30112 * The tree may not be modified while iterating over it (you can't
30113 * add/remove items). To remove all items matching a predicate, you need
30114 * to add each item to a list in your #GTraverseFunc as you walk over
30115 * the tree, then walk the list and remove each item.
30123 * Gets the height of a #GTree.
30125 * If the #GTree contains no nodes, the height is 0.
30126 * If the #GTree contains only one root node the height is 1.
30127 * If the root node has children the height is 2, etc.
30129 * Returns: the height of @tree
30136 * @key: the key to insert
30137 * @value: the value corresponding to the key
30139 * Inserts a key/value pair into a #GTree.
30141 * If the given key already exists in the #GTree its corresponding value
30142 * is set to the new value. If you supplied a @value_destroy_func when
30143 * creating the #GTree, the old value is freed using that function. If
30144 * you supplied a @key_destroy_func when creating the #GTree, the passed
30145 * key is freed using that function.
30147 * The tree is automatically 'balanced' as new key/value pairs are added,
30148 * so that the distance from the root to every leaf is as small as possible.
30155 * @key: the key to look up
30157 * Gets the value corresponding to the given key. Since a #GTree is
30158 * automatically balanced as key/value pairs are added, key lookup
30159 * is O(log n) (where n is the number of key/value pairs in the tree).
30161 * Returns: the value corresponding to the key, or %NULL
30162 * if the key was not found
30167 * g_tree_lookup_extended:
30169 * @lookup_key: the key to look up
30170 * @orig_key: returns the original key
30171 * @value: returns the value associated with the key
30173 * Looks up a key in the #GTree, returning the original key and the
30174 * associated value. This is useful if you need to free the memory
30175 * allocated for the original key, for example before calling
30178 * Returns: %TRUE if the key was found in the #GTree
30184 * @key_compare_func: the function used to order the nodes in the #GTree.
30185 * It should return values similar to the standard strcmp() function -
30186 * 0 if the two arguments are equal, a negative value if the first argument
30187 * comes before the second, or a positive value if the first argument comes
30188 * after the second.
30190 * Creates a new #GTree.
30192 * Returns: a newly allocated #GTree
30198 * @key_compare_func: qsort()-style comparison function
30199 * @key_compare_data: data to pass to comparison function
30200 * @key_destroy_func: a function to free the memory allocated for the key
30201 * used when removing the entry from the #GTree or %NULL if you don't
30202 * want to supply such a function
30203 * @value_destroy_func: a function to free the memory allocated for the
30204 * value used when removing the entry from the #GTree or %NULL if you
30205 * don't want to supply such a function
30207 * Creates a new #GTree like g_tree_new() and allows to specify functions
30208 * to free the memory allocated for the key and value that get called when
30209 * removing the entry from the #GTree.
30211 * Returns: a newly allocated #GTree
30216 * g_tree_new_with_data:
30217 * @key_compare_func: qsort()-style comparison function
30218 * @key_compare_data: data to pass to comparison function
30220 * Creates a new #GTree with a comparison function that accepts user data.
30221 * See g_tree_new() for more details.
30223 * Returns: a newly allocated #GTree
30231 * Gets the number of nodes in a #GTree.
30233 * Returns: the number of nodes in @tree
30241 * Increments the reference count of @tree by one.
30243 * It is safe to call this function from any thread.
30245 * Returns: the passed in #GTree
30253 * @key: the key to remove
30255 * Removes a key/value pair from a #GTree.
30257 * If the #GTree was created using g_tree_new_full(), the key and value
30258 * are freed using the supplied destroy functions, otherwise you have to
30259 * make sure that any dynamically allocated values are freed yourself.
30260 * If the key does not exist in the #GTree, the function does nothing.
30262 * Returns: %TRUE if the key was found (prior to 2.8, this function
30263 * returned nothing)
30270 * @key: the key to insert
30271 * @value: the value corresponding to the key
30273 * Inserts a new key and value into a #GTree similar to g_tree_insert().
30274 * The difference is that if the key already exists in the #GTree, it gets
30275 * replaced by the new key. If you supplied a @value_destroy_func when
30276 * creating the #GTree, the old value is freed using that function. If you
30277 * supplied a @key_destroy_func when creating the #GTree, the old key is
30278 * freed using that function.
30280 * The tree is automatically 'balanced' as new key/value pairs are added,
30281 * so that the distance from the root to every leaf is as small as possible.
30288 * @search_func: a function used to search the #GTree
30289 * @user_data: the data passed as the second argument to @search_func
30291 * Searches a #GTree using @search_func.
30293 * The @search_func is called with a pointer to the key of a key/value
30294 * pair in the tree, and the passed in @user_data. If @search_func returns
30295 * 0 for a key/value pair, then the corresponding value is returned as
30296 * the result of g_tree_search(). If @search_func returns -1, searching
30297 * will proceed among the key/value pairs that have a smaller key; if
30298 * @search_func returns 1, searching will proceed among the key/value
30299 * pairs that have a larger key.
30301 * Returns: the value corresponding to the found key, or %NULL
30302 * if the key was not found
30309 * @key: the key to remove
30311 * Removes a key and its associated value from a #GTree without calling
30312 * the key and value destroy functions.
30314 * If the key does not exist in the #GTree, the function does nothing.
30316 * Returns: %TRUE if the key was found (prior to 2.8, this function
30317 * returned nothing)
30324 * @traverse_func: the function to call for each node visited. If this
30325 * function returns %TRUE, the traversal is stopped.
30326 * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
30327 * %G_PRE_ORDER and %G_POST_ORDER
30328 * @user_data: user data to pass to the function
30330 * Calls the given function for each node in the #GTree.
30332 * Deprecated: 2.2: The order of a balanced tree is somewhat arbitrary.
30333 * If you just want to visit all nodes in sorted order, use
30334 * g_tree_foreach() instead. If you really need to visit nodes in
30335 * a different order, consider using an [n-ary tree][glib-N-ary-Trees].
30343 * Decrements the reference count of @tree by one.
30344 * If the reference count drops to 0, all keys and values will
30345 * be destroyed (if destroy functions were specified) and all
30346 * memory allocated by @tree will be released.
30348 * It is safe to call this function from any thread.
30356 * @n_bytes: number of bytes to allocate.
30358 * Attempts to allocate @n_bytes, and returns %NULL on failure.
30359 * Contrast with g_malloc(), which aborts the program on failure.
30361 * Returns: the allocated memory, or %NULL.
30367 * @n_bytes: number of bytes to allocate
30369 * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
30370 * failure. Contrast with g_malloc0(), which aborts the program on failure.
30373 * Returns: the allocated memory, or %NULL
30379 * @n_blocks: the number of blocks to allocate
30380 * @n_block_bytes: the size of each block in bytes
30382 * This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
30383 * but care is taken to detect possible overflow during multiplication.
30386 * Returns: the allocated memory, or %NULL
30392 * @n_blocks: the number of blocks to allocate
30393 * @n_block_bytes: the size of each block in bytes
30395 * This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
30396 * but care is taken to detect possible overflow during multiplication.
30399 * Returns: the allocated memory, or %NULL.
30405 * @mem: (allow-none): previously-allocated memory, or %NULL.
30406 * @n_bytes: number of bytes to allocate.
30408 * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
30409 * on failure. Contrast with g_realloc(), which aborts the program
30410 * on failure. If @mem is %NULL, behaves the same as g_try_malloc().
30412 * Returns: the allocated memory, or %NULL.
30418 * @mem: (allow-none): previously-allocated memory, or %NULL.
30419 * @n_blocks: the number of blocks to allocate
30420 * @n_block_bytes: the size of each block in bytes
30422 * This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
30423 * but care is taken to detect possible overflow during multiplication.
30426 * Returns: the allocated memory, or %NULL.
30432 * @str: a UCS-4 encoded string
30433 * @len: the maximum length (number of characters) of @str to use.
30434 * If @len < 0, then the string is nul-terminated.
30435 * @items_read: (allow-none): location to store number of bytes read,
30436 * or %NULL. If an error occurs then the index of the invalid input
30438 * @items_written: (allow-none): location to store number of #gunichar2
30439 * written, or %NULL. The value stored here does not include the
30441 * @error: location to store the error occurring, or %NULL to ignore
30442 * errors. Any of the errors in #GConvertError other than
30443 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
30445 * Convert a string from UCS-4 to UTF-16. A 0 character will be
30446 * added to the result after the converted text.
30448 * Returns: a pointer to a newly allocated UTF-16 string.
30449 * This value must be freed with g_free(). If an error occurs,
30450 * %NULL will be returned and @error set.
30456 * @str: a UCS-4 encoded string
30457 * @len: the maximum length (number of characters) of @str to use.
30458 * If @len < 0, then the string is nul-terminated.
30459 * @items_read: (allow-none): location to store number of characters
30461 * @items_written: (allow-none): location to store number of bytes
30462 * written or %NULL. The value here stored does not include the
30464 * @error: location to store the error occurring, or %NULL to ignore
30465 * errors. Any of the errors in #GConvertError other than
30466 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
30468 * Convert a string from a 32-bit fixed width representation as UCS-4.
30469 * to UTF-8. The result will be terminated with a 0 byte.
30471 * Returns: a pointer to a newly allocated UTF-8 string.
30472 * This value must be freed with g_free(). If an error occurs,
30473 * %NULL will be returned and @error set. In that case, @items_read
30474 * will be set to the position of the first invalid input character.
30479 * g_unichar_break_type:
30480 * @c: a Unicode character
30482 * Determines the break type of @c. @c should be a Unicode character
30483 * (to derive a character from UTF-8 encoded text, use
30484 * g_utf8_get_char()). The break type is used to find word and line
30485 * breaks ("text boundaries"), Pango implements the Unicode boundary
30486 * resolution algorithms and normally you would use a function such
30487 * as pango_break() instead of caring about break types yourself.
30489 * Returns: the break type of @c
30494 * g_unichar_combining_class:
30495 * @uc: a Unicode character
30497 * Determines the canonical combining class of a Unicode character.
30499 * Returns: the combining class of the character
30505 * g_unichar_compose:
30506 * @a: a Unicode character
30507 * @b: a Unicode character
30508 * @ch: return location for the composed character
30510 * Performs a single composition step of the
30511 * Unicode canonical composition algorithm.
30513 * This function includes algorithmic Hangul Jamo composition,
30514 * but it is not exactly the inverse of g_unichar_decompose().
30515 * No composition can have either of @a or @b equal to zero.
30516 * To be precise, this function composes if and only if
30517 * there exists a Primary Composite P which is canonically
30518 * equivalent to the sequence <@a,@b>. See the Unicode
30519 * Standard for the definition of Primary Composite.
30521 * If @a and @b do not compose a new character, @ch is set to zero.
30524 * [UAX#15](http://unicode.org/reports/tr15/)
30527 * Returns: %TRUE if the characters could be composed
30533 * g_unichar_decompose:
30534 * @ch: a Unicode character
30535 * @a: return location for the first component of @ch
30536 * @b: return location for the second component of @ch
30538 * Performs a single decomposition step of the
30539 * Unicode canonical decomposition algorithm.
30541 * This function does not include compatibility
30542 * decompositions. It does, however, include algorithmic
30543 * Hangul Jamo decomposition, as well as 'singleton'
30544 * decompositions which replace a character by a single
30545 * other character. In the case of singletons *@b will
30548 * If @ch is not decomposable, *@a is set to @ch and *@b
30551 * Note that the way Unicode decomposition pairs are
30552 * defined, it is guaranteed that @b would not decompose
30553 * further, but @a may itself decompose. To get the full
30554 * canonical decomposition for @ch, one would need to
30555 * recursively call this function on @a. Or use
30556 * g_unichar_fully_decompose().
30559 * [UAX#15](http://unicode.org/reports/tr15/)
30562 * Returns: %TRUE if the character could be decomposed
30568 * g_unichar_digit_value:
30569 * @c: a Unicode character
30571 * Determines the numeric value of a character as a decimal
30574 * Returns: If @c is a decimal digit (according to
30575 * g_unichar_isdigit()), its numeric value. Otherwise, -1.
30580 * g_unichar_fully_decompose:
30581 * @ch: a Unicode character.
30582 * @compat: whether perform canonical or compatibility decomposition
30583 * @result: (allow-none): location to store decomposed result, or %NULL
30584 * @result_len: length of @result
30586 * Computes the canonical or compatibility decomposition of a
30587 * Unicode character. For compatibility decomposition,
30588 * pass %TRUE for @compat; for canonical decomposition
30589 * pass %FALSE for @compat.
30591 * The decomposed sequence is placed in @result. Only up to
30592 * @result_len characters are written into @result. The length
30593 * of the full decomposition (irrespective of @result_len) is
30594 * returned by the function. For canonical decomposition,
30595 * currently all decompositions are of length at most 4, but
30596 * this may change in the future (very unlikely though).
30597 * At any rate, Unicode does guarantee that a buffer of length
30598 * 18 is always enough for both compatibility and canonical
30599 * decompositions, so that is the size recommended. This is provided
30600 * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
30603 * [UAX#15](http://unicode.org/reports/tr15/)
30606 * Returns: the length of the full decomposition.
30612 * g_unichar_get_mirror_char:
30613 * @ch: a Unicode character
30614 * @mirrored_ch: location to store the mirrored character
30616 * In Unicode, some characters are "mirrored". This means that their
30617 * images are mirrored horizontally in text that is laid out from right
30618 * to left. For instance, "(" would become its mirror image, ")", in
30619 * right-to-left text.
30621 * If @ch has the Unicode mirrored property and there is another unicode
30622 * character that typically has a glyph that is the mirror image of @ch's
30623 * glyph and @mirrored_ch is set, it puts that character in the address
30624 * pointed to by @mirrored_ch. Otherwise the original character is put.
30626 * Returns: %TRUE if @ch has a mirrored character, %FALSE otherwise
30632 * g_unichar_get_script:
30633 * @ch: a Unicode character
30635 * Looks up the #GUnicodeScript for a particular character (as defined
30636 * by Unicode Standard Annex \#24). No check is made for @ch being a
30637 * valid Unicode character; if you pass in invalid character, the
30638 * result is undefined.
30640 * This function is equivalent to pango_script_for_unichar() and the
30641 * two are interchangeable.
30643 * Returns: the #GUnicodeScript for the character.
30649 * g_unichar_isalnum:
30650 * @c: a Unicode character
30652 * Determines whether a character is alphanumeric.
30653 * Given some UTF-8 text, obtain a character value
30654 * with g_utf8_get_char().
30656 * Returns: %TRUE if @c is an alphanumeric character
30661 * g_unichar_isalpha:
30662 * @c: a Unicode character
30664 * Determines whether a character is alphabetic (i.e. a letter).
30665 * Given some UTF-8 text, obtain a character value with
30666 * g_utf8_get_char().
30668 * Returns: %TRUE if @c is an alphabetic character
30673 * g_unichar_iscntrl:
30674 * @c: a Unicode character
30676 * Determines whether a character is a control character.
30677 * Given some UTF-8 text, obtain a character value with
30678 * g_utf8_get_char().
30680 * Returns: %TRUE if @c is a control character
30685 * g_unichar_isdefined:
30686 * @c: a Unicode character
30688 * Determines if a given character is assigned in the Unicode
30691 * Returns: %TRUE if the character has an assigned value
30696 * g_unichar_isdigit:
30697 * @c: a Unicode character
30699 * Determines whether a character is numeric (i.e. a digit). This
30700 * covers ASCII 0-9 and also digits in other languages/scripts. Given
30701 * some UTF-8 text, obtain a character value with g_utf8_get_char().
30703 * Returns: %TRUE if @c is a digit
30708 * g_unichar_isgraph:
30709 * @c: a Unicode character
30711 * Determines whether a character is printable and not a space
30712 * (returns %FALSE for control characters, format characters, and
30713 * spaces). g_unichar_isprint() is similar, but returns %TRUE for
30714 * spaces. Given some UTF-8 text, obtain a character value with
30715 * g_utf8_get_char().
30717 * Returns: %TRUE if @c is printable unless it's a space
30722 * g_unichar_islower:
30723 * @c: a Unicode character
30725 * Determines whether a character is a lowercase letter.
30726 * Given some UTF-8 text, obtain a character value with
30727 * g_utf8_get_char().
30729 * Returns: %TRUE if @c is a lowercase letter
30734 * g_unichar_ismark:
30735 * @c: a Unicode character
30737 * Determines whether a character is a mark (non-spacing mark,
30738 * combining mark, or enclosing mark in Unicode speak).
30739 * Given some UTF-8 text, obtain a character value
30740 * with g_utf8_get_char().
30742 * Note: in most cases where isalpha characters are allowed,
30743 * ismark characters should be allowed to as they are essential
30744 * for writing most European languages as well as many non-Latin
30747 * Returns: %TRUE if @c is a mark character
30753 * g_unichar_isprint:
30754 * @c: a Unicode character
30756 * Determines whether a character is printable.
30757 * Unlike g_unichar_isgraph(), returns %TRUE for spaces.
30758 * Given some UTF-8 text, obtain a character value with
30759 * g_utf8_get_char().
30761 * Returns: %TRUE if @c is printable
30766 * g_unichar_ispunct:
30767 * @c: a Unicode character
30769 * Determines whether a character is punctuation or a symbol.
30770 * Given some UTF-8 text, obtain a character value with
30771 * g_utf8_get_char().
30773 * Returns: %TRUE if @c is a punctuation or symbol character
30778 * g_unichar_isspace:
30779 * @c: a Unicode character
30781 * Determines whether a character is a space, tab, or line separator
30782 * (newline, carriage return, etc.). Given some UTF-8 text, obtain a
30783 * character value with g_utf8_get_char().
30785 * (Note: don't use this to do word breaking; you have to use
30786 * Pango or equivalent to get word breaking right, the algorithm
30787 * is fairly complex.)
30789 * Returns: %TRUE if @c is a space character
30794 * g_unichar_istitle:
30795 * @c: a Unicode character
30797 * Determines if a character is titlecase. Some characters in
30798 * Unicode which are composites, such as the DZ digraph
30799 * have three case variants instead of just two. The titlecase
30800 * form is used at the beginning of a word where only the
30801 * first letter is capitalized. The titlecase form of the DZ
30802 * digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z.
30804 * Returns: %TRUE if the character is titlecase
30809 * g_unichar_isupper:
30810 * @c: a Unicode character
30812 * Determines if a character is uppercase.
30814 * Returns: %TRUE if @c is an uppercase character
30819 * g_unichar_iswide:
30820 * @c: a Unicode character
30822 * Determines if a character is typically rendered in a double-width
30825 * Returns: %TRUE if the character is wide
30830 * g_unichar_iswide_cjk:
30831 * @c: a Unicode character
30833 * Determines if a character is typically rendered in a double-width
30834 * cell under legacy East Asian locales. If a character is wide according to
30835 * g_unichar_iswide(), then it is also reported wide with this function, but
30836 * the converse is not necessarily true. See the
30837 * [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
30840 * If a character passes the g_unichar_iswide() test then it will also pass
30841 * this test, but not the other way around. Note that some characters may
30842 * pas both this test and g_unichar_iszerowidth().
30844 * Returns: %TRUE if the character is wide in legacy East Asian locales
30850 * g_unichar_isxdigit:
30851 * @c: a Unicode character.
30853 * Determines if a character is a hexidecimal digit.
30855 * Returns: %TRUE if the character is a hexadecimal digit
30860 * g_unichar_iszerowidth:
30861 * @c: a Unicode character
30863 * Determines if a given character typically takes zero width when rendered.
30864 * The return value is %TRUE for all non-spacing and enclosing marks
30865 * (e.g., combining accents), format characters, zero-width
30866 * space, but not U+00AD SOFT HYPHEN.
30868 * A typical use of this function is with one of g_unichar_iswide() or
30869 * g_unichar_iswide_cjk() to determine the number of cells a string occupies
30870 * when displayed on a grid display (terminals). However, note that not all
30871 * terminals support zero-width rendering of zero-width marks.
30873 * Returns: %TRUE if the character has zero width
30879 * g_unichar_to_utf8:
30880 * @c: a Unicode character code
30881 * @outbuf: output buffer, must have at least 6 bytes of space.
30882 * If %NULL, the length will be computed and returned
30883 * and nothing will be written to @outbuf.
30885 * Converts a single character to UTF-8.
30887 * Returns: number of bytes written
30892 * g_unichar_tolower:
30893 * @c: a Unicode character.
30895 * Converts a character to lower case.
30897 * Returns: the result of converting @c to lower case.
30898 * If @c is not an upperlower or titlecase character,
30899 * or has no lowercase equivalent @c is returned unchanged.
30904 * g_unichar_totitle:
30905 * @c: a Unicode character
30907 * Converts a character to the titlecase.
30909 * Returns: the result of converting @c to titlecase.
30910 * If @c is not an uppercase or lowercase character,
30911 * @c is returned unchanged.
30916 * g_unichar_toupper:
30917 * @c: a Unicode character
30919 * Converts a character to uppercase.
30921 * Returns: the result of converting @c to uppercase.
30922 * If @c is not an lowercase or titlecase character,
30923 * or has no upper case equivalent @c is returned unchanged.
30929 * @c: a Unicode character
30931 * Classifies a Unicode character by type.
30933 * Returns: the type of the character.
30938 * g_unichar_validate:
30939 * @ch: a Unicode character
30941 * Checks whether @ch is a valid Unicode character. Some possible
30942 * integer values of @ch will not be valid. 0 is considered a valid
30943 * character, though it's normally a string terminator.
30945 * Returns: %TRUE if @ch is a valid Unicode character
30950 * g_unichar_xdigit_value:
30951 * @c: a Unicode character
30953 * Determines the numeric value of a character as a hexidecimal
30956 * Returns: If @c is a hex digit (according to
30957 * g_unichar_isxdigit()), its numeric value. Otherwise, -1.
30962 * g_unicode_canonical_decomposition:
30963 * @ch: a Unicode character.
30964 * @result_len: location to store the length of the return value.
30966 * Computes the canonical decomposition of a Unicode character.
30968 * Returns: a newly allocated string of Unicode characters.
30969 * @result_len is set to the resulting length of the string.
30970 * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose()
30976 * g_unicode_canonical_ordering:
30977 * @string: a UCS-4 encoded string.
30978 * @len: the maximum length of @string to use.
30980 * Computes the canonical ordering of a string in-place.
30981 * This rearranges decomposed characters in the string
30982 * according to their combining classes. See the Unicode
30983 * manual for more information.
30988 * g_unicode_script_from_iso15924:
30989 * @iso15924: a Unicode script
30991 * Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter
30992 * codes to scripts. For example, the code for Arabic is 'Arab'.
30993 * This function accepts four letter codes encoded as a @guint32 in a
30994 * big-endian fashion. That is, the code expected for Arabic is
30995 * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
30998 * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
31001 * Returns: the Unicode script for @iso15924, or
31002 * of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and
31003 * %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown.
31009 * g_unicode_script_to_iso15924:
31010 * @script: a Unicode script
31012 * Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter
31013 * codes to scripts. For example, the code for Arabic is 'Arab'. The
31014 * four letter codes are encoded as a @guint32 by this function in a
31015 * big-endian fashion. That is, the code returned for Arabic is
31016 * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
31019 * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
31022 * Returns: the ISO 15924 code for @script, encoded as an integer,
31023 * of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or
31024 * ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood.
31031 * @fd: a file descriptor
31032 * @condition: IO conditions to watch for on @fd
31033 * @function: a #GPollFDFunc
31034 * @user_data: data to pass to @function
31036 * Sets a function to be called when the IO condition, as specified by
31037 * @condition becomes true for @fd.
31039 * @function will be called when the specified IO condition becomes
31040 * %TRUE. The function is expected to clear whatever event caused the
31041 * IO condition to become true and return %TRUE in order to be notified
31042 * when it happens again. If @function returns %FALSE then the watch
31043 * will be cancelled.
31045 * The return value of this function can be passed to g_source_remove()
31046 * to cancel the watch at any time that it exists.
31048 * The source will never close the fd -- you must do it yourself.
31050 * Returns: the ID (greater than 0) of the event source
31056 * g_unix_fd_add_full:
31057 * @priority: the priority of the source
31058 * @fd: a file descriptor
31059 * @condition: IO conditions to watch for on @fd
31060 * @function: a #GUnixFDSourceFunc
31061 * @user_data: data to pass to @function
31062 * @notify: function to call when the idle is removed, or %NULL
31064 * Sets a function to be called when the IO condition, as specified by
31065 * @condition becomes true for @fd.
31067 * This is the same as g_unix_fd_add(), except that it allows you to
31068 * specify a non-default priority and a provide a #GDestroyNotify for
31071 * Returns: the ID (greater than 0) of the event source
31077 * g_unix_fd_source_new:
31078 * @fd: a file descriptor
31079 * @condition: IO conditions to watch for on @fd
31081 * Creates a #GSource to watch for a particular IO condition on a file
31084 * The source will never close the fd -- you must do it yourself.
31086 * Returns: the newly created #GSource
31092 * g_unix_open_pipe:
31093 * @fds: Array of two integers
31094 * @flags: Bitfield of file descriptor flags, as for fcntl()
31095 * @error: a #GError
31097 * Similar to the UNIX pipe() call, but on modern systems like Linux
31098 * uses the pipe2() system call, which atomically creates a pipe with
31099 * the configured flags. The only supported flag currently is
31100 * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that
31101 * must still be done separately with fcntl().
31103 * This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
31104 * for fcntl(); these are different on Linux/glibc.
31106 * Returns: %TRUE on success, %FALSE if not (and errno will be set).
31112 * g_unix_set_fd_nonblocking:
31113 * @fd: A file descriptor
31114 * @nonblock: If %TRUE, set the descriptor to be non-blocking
31115 * @error: a #GError
31117 * Control the non-blocking state of the given file descriptor,
31118 * according to @nonblock. On most systems this uses %O_NONBLOCK, but
31119 * on some older ones may use %O_NDELAY.
31121 * Returns: %TRUE if successful
31127 * g_unix_signal_add:
31128 * @signum: Signal number
31129 * @handler: Callback
31130 * @user_data: Data for @handler
31132 * A convenience function for g_unix_signal_source_new(), which
31133 * attaches to the default #GMainContext. You can remove the watch
31134 * using g_source_remove().
31136 * Returns: An ID (greater than 0) for the event source
31142 * g_unix_signal_add_full: (rename-to g_unix_signal_add)
31143 * @priority: the priority of the signal source. Typically this will be in
31144 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
31145 * @signum: Signal number
31146 * @handler: Callback
31147 * @user_data: Data for @handler
31148 * @notify: #GDestroyNotify for @handler
31150 * A convenience function for g_unix_signal_source_new(), which
31151 * attaches to the default #GMainContext. You can remove the watch
31152 * using g_source_remove().
31154 * Returns: An ID (greater than 0) for the event source
31160 * g_unix_signal_source_new:
31161 * @signum: A signal number
31163 * Create a #GSource that will be dispatched upon delivery of the UNIX
31164 * signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`,
31165 * `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2`
31168 * Note that unlike the UNIX default, all sources which have created a
31169 * watch will be dispatched, regardless of which underlying thread
31170 * invoked g_unix_signal_source_new().
31172 * For example, an effective use of this function is to handle `SIGTERM`
31173 * cleanly; flushing any outstanding files, and then calling
31174 * g_main_loop_quit (). It is not safe to do any of this a regular
31175 * UNIX signal handler; your handler may be invoked while malloc() or
31176 * another library function is running, causing reentrancy if you
31177 * attempt to use it from the handler. None of the GLib/GObject API
31178 * is safe against this kind of reentrancy.
31180 * The interaction of this source when combined with native UNIX
31181 * functions like sigprocmask() is not defined.
31183 * The source will not initially be associated with any #GMainContext
31184 * and must be added to one with g_source_attach() before it will be
31187 * Returns: A newly created #GSource
31194 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
31196 * A wrapper for the POSIX unlink() function. The unlink() function
31197 * deletes a name from the filesystem. If this was the last link to the
31198 * file and no processes have it opened, the diskspace occupied by the
31201 * See your C library manual for more details about unlink(). Note
31202 * that on Windows, it is in general not possible to delete files that
31203 * are open to some process, or mapped into memory.
31205 * Returns: 0 if the name was successfully deleted, -1 if an error
31213 * @variable: the environment variable to remove, must not contain '='
31215 * Removes an environment variable from the environment.
31217 * Note that on some systems, when variables are overwritten, the
31218 * memory used for the previous variables and its value isn't reclaimed.
31220 * You should be mindful of the fact that environment variable handling
31221 * in UNIX is not thread-safe, and your program may crash if one thread
31222 * calls g_unsetenv() while another thread is calling getenv(). (And note
31223 * that many functions, such as gettext(), call getenv() internally.) This
31224 * function is only safe to use at the very start of your program, before
31225 * creating any other threads (or creating objects that create worker
31226 * threads of their own).
31228 * If you need to set up the environment for a child process, you can
31229 * use g_get_environ() to get an environment array, modify that with
31230 * g_environ_setenv() and g_environ_unsetenv(), and then pass that
31231 * array directly to execvpe(), g_spawn_async(), or the like.
31238 * g_uri_escape_string:
31239 * @unescaped: the unescaped input string.
31240 * @reserved_chars_allowed: (allow-none): a string of reserved characters that
31241 * are allowed to be used, or %NULL.
31242 * @allow_utf8: %TRUE if the result can include UTF-8 characters.
31244 * Escapes a string for use in a URI.
31246 * Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical
31247 * characters plus dash, dot, underscore and tilde) are escaped.
31248 * But if you specify characters in @reserved_chars_allowed they are not
31249 * escaped. This is useful for the "reserved" characters in the URI
31250 * specification, since those are allowed unescaped in some portions of
31253 * Returns: an escaped version of @unescaped. The returned string should be
31254 * freed when no longer needed.
31260 * g_uri_list_extract_uris:
31261 * @uri_list: an URI list
31263 * Splits an URI list conforming to the text/uri-list
31264 * mime type defined in RFC 2483 into individual URIs,
31265 * discarding any comments. The URIs are not validated.
31267 * Returns: (transfer full): a newly allocated %NULL-terminated list
31268 * of strings holding the individual URIs. The array should be freed
31269 * with g_strfreev().
31275 * g_uri_parse_scheme:
31276 * @uri: a valid URI.
31278 * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
31280 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
31282 * Common schemes include "file", "http", "svn+ssh", etc.
31284 * Returns: The "Scheme" component of the URI, or %NULL on error.
31285 * The returned string should be freed when no longer needed.
31291 * g_uri_unescape_segment:
31292 * @escaped_string: (allow-none): A string, may be %NULL
31293 * @escaped_string_end: (allow-none): Pointer to end of @escaped_string, may be %NULL
31294 * @illegal_characters: (allow-none): An optional string of illegal characters not to be allowed, may be %NULL
31296 * Unescapes a segment of an escaped string.
31298 * If any of the characters in @illegal_characters or the character zero appears
31299 * as an escaped character in @escaped_string then that is an error and %NULL
31300 * will be returned. This is useful it you want to avoid for instance having a
31301 * slash being expanded in an escaped path element, which might confuse pathname
31304 * Returns: an unescaped version of @escaped_string or %NULL on error.
31305 * The returned string should be freed when no longer needed. As a
31306 * special case if %NULL is given for @escaped_string, this function
31307 * will return %NULL.
31313 * g_uri_unescape_string:
31314 * @escaped_string: an escaped string to be unescaped.
31315 * @illegal_characters: (allow-none): a string of illegal characters not to be
31316 * allowed, or %NULL.
31318 * Unescapes a whole escaped string.
31320 * If any of the characters in @illegal_characters or the character zero appears
31321 * as an escaped character in @escaped_string then that is an error and %NULL
31322 * will be returned. This is useful it you want to avoid for instance having a
31323 * slash being expanded in an escaped path element, which might confuse pathname
31326 * Returns: an unescaped version of @escaped_string. The returned string
31327 * should be freed when no longer needed.
31334 * @microseconds: number of microseconds to pause
31336 * Pauses the current thread for the given number of microseconds.
31338 * There are 1 million microseconds per second (represented by the
31339 * #G_USEC_PER_SEC macro). g_usleep() may have limited precision,
31340 * depending on hardware and operating system; don't rely on the exact
31341 * length of the sleep.
31347 * @str: a UTF-16 encoded string
31348 * @len: the maximum length (number of #gunichar2) of @str to use.
31349 * If @len < 0, then the string is nul-terminated.
31350 * @items_read: (allow-none): location to store number of words read,
31351 * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
31352 * returned in case @str contains a trailing partial character. If
31353 * an error occurs then the index of the invalid input is stored here.
31354 * @items_written: (allow-none): location to store number of characters
31355 * written, or %NULL. The value stored here does not include the trailing
31357 * @error: location to store the error occurring, or %NULL to ignore
31358 * errors. Any of the errors in #GConvertError other than
31359 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
31361 * Convert a string from UTF-16 to UCS-4. The result will be
31364 * Returns: a pointer to a newly allocated UCS-4 string.
31365 * This value must be freed with g_free(). If an error occurs,
31366 * %NULL will be returned and @error set.
31372 * @str: a UTF-16 encoded string
31373 * @len: the maximum length (number of #gunichar2) of @str to use.
31374 * If @len < 0, then the string is nul-terminated.
31375 * @items_read: (allow-none): location to store number of words read,
31376 * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
31377 * returned in case @str contains a trailing partial character. If
31378 * an error occurs then the index of the invalid input is stored here.
31379 * @items_written: (allow-none): location to store number of bytes written,
31380 * or %NULL. The value stored here does not include the trailing 0 byte.
31381 * @error: location to store the error occurring, or %NULL to ignore
31382 * errors. Any of the errors in #GConvertError other than
31383 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
31385 * Convert a string from UTF-16 to UTF-8. The result will be
31386 * terminated with a 0 byte.
31388 * Note that the input is expected to be already in native endianness,
31389 * an initial byte-order-mark character is not handled specially.
31390 * g_convert() can be used to convert a byte buffer of UTF-16 data of
31391 * ambiguous endianess.
31393 * Further note that this function does not validate the result
31394 * string; it may e.g. include embedded NUL characters. The only
31395 * validation done by this function is to ensure that the input can
31396 * be correctly interpreted as UTF-16, i.e. it doesn't contain
31397 * things unpaired surrogates.
31399 * Returns: a pointer to a newly allocated UTF-8 string.
31400 * This value must be freed with g_free(). If an error occurs,
31401 * %NULL will be returned and @error set.
31407 * @str: a UTF-8 encoded string
31408 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
31410 * Converts a string into a form that is independent of case. The
31411 * result will not correspond to any particular case, but can be
31412 * compared for equality or ordered with the results of calling
31413 * g_utf8_casefold() on other strings.
31415 * Note that calling g_utf8_casefold() followed by g_utf8_collate() is
31416 * only an approximation to the correct linguistic case insensitive
31417 * ordering, though it is a fairly good one. Getting this exactly
31418 * right would require a more sophisticated collation function that
31419 * takes case sensitivity into account. GLib does not currently
31420 * provide such a function.
31422 * Returns: a newly allocated string, that is a
31423 * case independent form of @str.
31429 * @str1: a UTF-8 encoded string
31430 * @str2: a UTF-8 encoded string
31432 * Compares two strings for ordering using the linguistically
31433 * correct rules for the [current locale][setlocale].
31434 * When sorting a large number of strings, it will be significantly
31435 * faster to obtain collation keys with g_utf8_collate_key() and
31436 * compare the keys with strcmp() when sorting instead of sorting
31437 * the original strings.
31439 * Returns: < 0 if @str1 compares before @str2,
31440 * 0 if they compare equal, > 0 if @str1 compares after @str2.
31445 * g_utf8_collate_key:
31446 * @str: a UTF-8 encoded string.
31447 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
31449 * Converts a string into a collation key that can be compared
31450 * with other collation keys produced by the same function using
31453 * The results of comparing the collation keys of two strings
31454 * with strcmp() will always be the same as comparing the two
31455 * original keys with g_utf8_collate().
31457 * Note that this function depends on the [current locale][setlocale].
31459 * Returns: a newly allocated string. This string should
31460 * be freed with g_free() when you are done with it.
31465 * g_utf8_collate_key_for_filename:
31466 * @str: a UTF-8 encoded string.
31467 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
31469 * Converts a string into a collation key that can be compared
31470 * with other collation keys produced by the same function using strcmp().
31472 * In order to sort filenames correctly, this function treats the dot '.'
31473 * as a special case. Most dictionary orderings seem to consider it
31474 * insignificant, thus producing the ordering "event.c" "eventgenerator.c"
31475 * "event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we
31476 * would like to treat numbers intelligently so that "file1" "file10" "file5"
31477 * is sorted as "file1" "file5" "file10".
31479 * Note that this function depends on the [current locale][setlocale].
31481 * Returns: a newly allocated string. This string should
31482 * be freed with g_free() when you are done with it.
31488 * g_utf8_find_next_char:
31489 * @p: a pointer to a position within a UTF-8 encoded string
31490 * @end: a pointer to the byte following the end of the string,
31491 * or %NULL to indicate that the string is nul-terminated
31493 * Finds the start of the next UTF-8 character in the string after @p.
31495 * @p does not have to be at the beginning of a UTF-8 character. No check
31496 * is made to see if the character found is actually valid other than
31497 * it starts with an appropriate byte.
31499 * Returns: a pointer to the found character or %NULL
31504 * g_utf8_find_prev_char:
31505 * @str: pointer to the beginning of a UTF-8 encoded string
31506 * @p: pointer to some position within @str
31508 * Given a position @p with a UTF-8 encoded string @str, find the start
31509 * of the previous UTF-8 character starting before @p. Returns %NULL if no
31510 * UTF-8 characters are present in @str before @p.
31512 * @p does not have to be at the beginning of a UTF-8 character. No check
31513 * is made to see if the character found is actually valid other than
31514 * it starts with an appropriate byte.
31516 * Returns: a pointer to the found character or %NULL.
31522 * @p: a pointer to Unicode character encoded as UTF-8
31524 * Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
31526 * If @p does not point to a valid UTF-8 encoded character, results
31527 * are undefined. If you are not sure that the bytes are complete
31528 * valid Unicode characters, you should use g_utf8_get_char_validated()
31531 * Returns: the resulting character
31536 * g_utf8_get_char_validated:
31537 * @p: a pointer to Unicode character encoded as UTF-8
31538 * @max_len: the maximum number of bytes to read, or -1, for no maximum or
31539 * if @p is nul-terminated
31541 * Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
31542 * This function checks for incomplete characters, for invalid characters
31543 * such as characters that are out of the range of Unicode, and for
31544 * overlong encodings of valid characters.
31546 * Returns: the resulting character. If @p points to a partial
31547 * sequence at the end of a string that could begin a valid
31548 * character (or if @max_len is zero), returns (gunichar)-2;
31549 * otherwise, if @p does not point to a valid UTF-8 encoded
31550 * Unicode character, returns (gunichar)-1.
31555 * g_utf8_normalize:
31556 * @str: a UTF-8 encoded string.
31557 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
31558 * @mode: the type of normalization to perform.
31560 * Converts a string into canonical form, standardizing
31561 * such issues as whether a character with an accent
31562 * is represented as a base character and combining
31563 * accent or as a single precomposed character. The
31564 * string has to be valid UTF-8, otherwise %NULL is
31565 * returned. You should generally call g_utf8_normalize()
31566 * before comparing two Unicode strings.
31568 * The normalization mode %G_NORMALIZE_DEFAULT only
31569 * standardizes differences that do not affect the
31570 * text content, such as the above-mentioned accent
31571 * representation. %G_NORMALIZE_ALL also standardizes
31572 * the "compatibility" characters in Unicode, such
31573 * as SUPERSCRIPT THREE to the standard forms
31574 * (in this case DIGIT THREE). Formatting information
31575 * may be lost but for most text operations such
31576 * characters should be considered the same.
31578 * %G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
31579 * are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL,
31580 * but returned a result with composed forms rather
31581 * than a maximally decomposed form. This is often
31582 * useful if you intend to convert the string to
31583 * a legacy encoding or pass it to a system with
31584 * less capable Unicode handling.
31586 * Returns: a newly allocated string, that is the
31587 * normalized form of @str, or %NULL if @str is not
31593 * g_utf8_offset_to_pointer:
31594 * @str: a UTF-8 encoded string
31595 * @offset: a character offset within @str
31597 * Converts from an integer character offset to a pointer to a position
31598 * within the string.
31600 * Since 2.10, this function allows to pass a negative @offset to
31601 * step backwards. It is usually worth stepping backwards from the end
31602 * instead of forwards if @offset is in the last fourth of the string,
31603 * since moving forward is about 3 times faster than moving backward.
31605 * Note that this function doesn't abort when reaching the end of @str.
31606 * Therefore you should be sure that @offset is within string boundaries
31607 * before calling that function. Call g_utf8_strlen() when unsure.
31608 * This limitation exists as this function is called frequently during
31609 * text rendering and therefore has to be as fast as possible.
31611 * Returns: the resulting pointer
31616 * g_utf8_pointer_to_offset:
31617 * @str: a UTF-8 encoded string
31618 * @pos: a pointer to a position within @str
31620 * Converts from a pointer to position within a string to a integer
31621 * character offset.
31623 * Since 2.10, this function allows @pos to be before @str, and returns
31624 * a negative offset in this case.
31626 * Returns: the resulting character offset
31631 * g_utf8_prev_char:
31632 * @p: a pointer to a position within a UTF-8 encoded string
31634 * Finds the previous UTF-8 character in the string before @p.
31636 * @p does not have to be at the beginning of a UTF-8 character. No check
31637 * is made to see if the character found is actually valid other than
31638 * it starts with an appropriate byte. If @p might be the first
31639 * character of the string, you must use g_utf8_find_prev_char() instead.
31641 * Returns: a pointer to the found character
31647 * @p: a nul-terminated UTF-8 encoded string
31648 * @len: the maximum length of @p
31649 * @c: a Unicode character
31651 * Finds the leftmost occurrence of the given Unicode character
31652 * in a UTF-8 encoded string, while limiting the search to @len bytes.
31653 * If @len is -1, allow unbounded search.
31655 * Returns: %NULL if the string does not contain the character,
31656 * otherwise, a pointer to the start of the leftmost occurrence
31657 * of the character in the string.
31663 * @str: a UTF-8 encoded string
31664 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
31666 * Converts all Unicode characters in the string that have a case
31667 * to lowercase. The exact manner that this is done depends
31668 * on the current locale, and may result in the number of
31669 * characters in the string changing.
31671 * Returns: a newly allocated string, with all characters
31672 * converted to lowercase.
31678 * @p: pointer to the start of a UTF-8 encoded string
31679 * @max: the maximum number of bytes to examine. If @max
31680 * is less than 0, then the string is assumed to be
31681 * nul-terminated. If @max is 0, @p will not be examined and
31682 * may be %NULL. If @max is greater than 0, up to @max
31683 * bytes are examined
31685 * Computes the length of the string in characters, not including
31686 * the terminating nul character. If the @max'th byte falls in the
31687 * middle of a character, the last (partial) character is not counted.
31689 * Returns: the length of the string in characters
31695 * @dest: buffer to fill with characters from @src
31696 * @src: UTF-8 encoded string
31697 * @n: character count
31699 * Like the standard C strncpy() function, but copies a given number
31700 * of characters instead of a given number of bytes. The @src string
31701 * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
31702 * text before trying to use UTF-8 utility functions with it.)
31710 * @p: a nul-terminated UTF-8 encoded string
31711 * @len: the maximum length of @p
31712 * @c: a Unicode character
31714 * Find the rightmost occurrence of the given Unicode character
31715 * in a UTF-8 encoded string, while limiting the search to @len bytes.
31716 * If @len is -1, allow unbounded search.
31718 * Returns: %NULL if the string does not contain the character,
31719 * otherwise, a pointer to the start of the rightmost occurrence
31720 * of the character in the string.
31725 * g_utf8_strreverse:
31726 * @str: a UTF-8 encoded string
31727 * @len: the maximum length of @str to use, in bytes. If @len < 0,
31728 * then the string is nul-terminated.
31730 * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text.
31731 * (Use g_utf8_validate() on all text before trying to use UTF-8
31732 * utility functions with it.)
31734 * This function is intended for programmatic uses of reversed strings.
31735 * It pays no attention to decomposed characters, combining marks, byte
31736 * order marks, directional indicators (LRM, LRO, etc) and similar
31737 * characters which might need special handling when reversing a string
31738 * for display purposes.
31740 * Note that unlike g_strreverse(), this function returns
31741 * newly-allocated memory, which should be freed with g_free() when
31742 * no longer needed.
31744 * Returns: a newly-allocated string which is the reverse of @str
31751 * @str: a UTF-8 encoded string
31752 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
31754 * Converts all Unicode characters in the string that have a case
31755 * to uppercase. The exact manner that this is done depends
31756 * on the current locale, and may result in the number of
31757 * characters in the string increasing. (For instance, the
31758 * German ess-zet will be changed to SS.)
31760 * Returns: a newly allocated string, with all characters
31761 * converted to uppercase.
31766 * g_utf8_substring:
31767 * @str: a UTF-8 encoded string
31768 * @start_pos: a character offset within @str
31769 * @end_pos: another character offset within @str
31771 * Copies a substring out of a UTF-8 encoded string.
31772 * The substring will contain @end_pos - @start_pos characters.
31774 * Returns: a newly allocated copy of the requested
31775 * substring. Free with g_free() when no longer needed.
31782 * @str: a UTF-8 encoded string
31783 * @len: the maximum length of @str to use, in bytes. If @len < 0,
31784 * then the string is nul-terminated.
31785 * @items_read: (allow-none): location to store number of bytes read, or %NULL.
31786 * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
31787 * returned in case @str contains a trailing partial
31788 * character. If an error occurs then the index of the
31789 * invalid input is stored here.
31790 * @items_written: (allow-none): location to store number of characters
31791 * written or %NULL. The value here stored does not include the
31792 * trailing 0 character.
31793 * @error: location to store the error occurring, or %NULL to ignore
31794 * errors. Any of the errors in #GConvertError other than
31795 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
31797 * Convert a string from UTF-8 to a 32-bit fixed width
31798 * representation as UCS-4. A trailing 0 character will be added to the
31799 * string after the converted text.
31801 * Returns: a pointer to a newly allocated UCS-4 string.
31802 * This value must be freed with g_free(). If an error occurs,
31803 * %NULL will be returned and @error set.
31808 * g_utf8_to_ucs4_fast:
31809 * @str: a UTF-8 encoded string
31810 * @len: the maximum length of @str to use, in bytes. If @len < 0,
31811 * then the string is nul-terminated.
31812 * @items_written: (allow-none): location to store the number of
31813 * characters in the result, or %NULL.
31815 * Convert a string from UTF-8 to a 32-bit fixed width
31816 * representation as UCS-4, assuming valid UTF-8 input.
31817 * This function is roughly twice as fast as g_utf8_to_ucs4()
31818 * but does no error checking on the input. A trailing 0 character
31819 * will be added to the string after the converted text.
31821 * Returns: a pointer to a newly allocated UCS-4 string.
31822 * This value must be freed with g_free().
31828 * @str: a UTF-8 encoded string
31829 * @len: the maximum length (number of bytes) of @str to use.
31830 * If @len < 0, then the string is nul-terminated.
31831 * @items_read: (allow-none): location to store number of bytes read,
31832 * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
31833 * returned in case @str contains a trailing partial character. If
31834 * an error occurs then the index of the invalid input is stored here.
31835 * @items_written: (allow-none): location to store number of #gunichar2
31836 * written, or %NULL. The value stored here does not include the
31838 * @error: location to store the error occurring, or %NULL to ignore
31839 * errors. Any of the errors in #GConvertError other than
31840 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
31842 * Convert a string from UTF-8 to UTF-16. A 0 character will be
31843 * added to the result after the converted text.
31845 * Returns: a pointer to a newly allocated UTF-16 string.
31846 * This value must be freed with g_free(). If an error occurs,
31847 * %NULL will be returned and @error set.
31853 * @str: (array length=max_len) (element-type guint8): a pointer to character data
31854 * @max_len: max bytes to validate, or -1 to go until NUL
31855 * @end: (allow-none) (out) (transfer none): return location for end of valid data
31857 * Validates UTF-8 encoded text. @str is the text to validate;
31858 * if @str is nul-terminated, then @max_len can be -1, otherwise
31859 * @max_len should be the number of bytes to validate.
31860 * If @end is non-%NULL, then the end of the valid range
31861 * will be stored there (i.e. the start of the first invalid
31862 * character if some bytes were invalid, or the end of the text
31863 * being validated otherwise).
31865 * Note that g_utf8_validate() returns %FALSE if @max_len is
31866 * positive and any of the @max_len bytes are nul.
31868 * Returns %TRUE if all of @str was valid. Many GLib and GTK+
31869 * routines require valid UTF-8 as input; so data read from a file
31870 * or the network should be checked with g_utf8_validate() before
31871 * doing anything else with it.
31873 * Returns: %TRUE if the text was valid UTF-8
31879 * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
31880 * @utb: a pointer to a struct utimbuf.
31882 * A wrapper for the POSIX utime() function. The utime() function
31883 * sets the access and modification timestamps of a file.
31885 * See your C library manual for more details about how utime() works
31888 * Returns: 0 if the operation was successful, -1 if an error occurred
31894 * g_variant_builder_add: (skip)
31895 * @builder: a #GVariantBuilder
31896 * @format_string: a #GVariant varargs format string
31897 * @...: arguments, as per @format_string
31899 * Adds to a #GVariantBuilder.
31901 * This call is a convenience wrapper that is exactly equivalent to
31902 * calling g_variant_new() followed by g_variant_builder_add_value().
31904 * Note that the arguments must be of the correct width for their types
31905 * specified in @format_string. This can be achieved by casting them. See
31906 * the [GVariant varargs documentation][gvariant-varargs].
31908 * This function might be used as follows:
31910 * |[<!-- language="C" -->
31912 * make_pointless_dictionary (void)
31914 * GVariantBuilder builder;
31917 * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
31918 * for (i = 0; i < 16; i++)
31922 * sprintf (buf, "%d", i);
31923 * g_variant_builder_add (&builder, "{is}", i, buf);
31926 * return g_variant_builder_end (&builder);
31935 * g_variant_builder_add_parsed:
31936 * @builder: a #GVariantBuilder
31937 * @format: a text format #GVariant
31938 * @...: arguments as per @format
31940 * Adds to a #GVariantBuilder.
31942 * This call is a convenience wrapper that is exactly equivalent to
31943 * calling g_variant_new_parsed() followed by
31944 * g_variant_builder_add_value().
31946 * Note that the arguments must be of the correct width for their types
31947 * specified in @format_string. This can be achieved by casting them. See
31948 * the [GVariant varargs documentation][gvariant-varargs].
31950 * This function might be used as follows:
31952 * |[<!-- language="C" -->
31954 * make_pointless_dictionary (void)
31956 * GVariantBuilder builder;
31959 * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
31960 * g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600);
31961 * g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo");
31962 * g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}");
31963 * return g_variant_builder_end (&builder);
31972 * g_variant_builder_add_value:
31973 * @builder: a #GVariantBuilder
31974 * @value: a #GVariant
31976 * Adds @value to @builder.
31978 * It is an error to call this function in any way that would create an
31979 * inconsistent value to be constructed. Some examples of this are
31980 * putting different types of items into an array, putting the wrong
31981 * types or number of items in a tuple, putting more than one value into
31984 * If @value is a floating reference (see g_variant_ref_sink()),
31985 * the @builder instance takes ownership of @value.
31992 * g_variant_builder_clear: (skip)
31993 * @builder: a #GVariantBuilder
31995 * Releases all memory associated with a #GVariantBuilder without
31996 * freeing the #GVariantBuilder structure itself.
31998 * It typically only makes sense to do this on a stack-allocated
31999 * #GVariantBuilder if you want to abort building the value part-way
32000 * through. This function need not be called if you call
32001 * g_variant_builder_end() and it also doesn't need to be called on
32002 * builders allocated with g_variant_builder_new (see
32003 * g_variant_builder_unref() for that).
32005 * This function leaves the #GVariantBuilder structure set to all-zeros.
32006 * It is valid to call this function on either an initialised
32007 * #GVariantBuilder or one that is set to all-zeros but it is not valid
32008 * to call this function on uninitialised memory.
32015 * g_variant_builder_close:
32016 * @builder: a #GVariantBuilder
32018 * Closes the subcontainer inside the given @builder that was opened by
32019 * the most recent call to g_variant_builder_open().
32021 * It is an error to call this function in any way that would create an
32022 * inconsistent value to be constructed (ie: too few values added to the
32030 * g_variant_builder_end:
32031 * @builder: a #GVariantBuilder
32033 * Ends the builder process and returns the constructed value.
32035 * It is not permissible to use @builder in any way after this call
32036 * except for reference counting operations (in the case of a
32037 * heap-allocated #GVariantBuilder) or by reinitialising it with
32038 * g_variant_builder_init() (in the case of stack-allocated).
32040 * It is an error to call this function in any way that would create an
32041 * inconsistent value to be constructed (ie: insufficient number of
32042 * items added to a container with a specific number of children
32043 * required). It is also an error to call this function if the builder
32044 * was created with an indefinite array or maybe type and no children
32045 * have been added; in this case it is impossible to infer the type of
32048 * Returns: (transfer none): a new, floating, #GVariant
32054 * g_variant_builder_init: (skip)
32055 * @builder: a #GVariantBuilder
32056 * @type: a container type
32058 * Initialises a #GVariantBuilder structure.
32060 * @type must be non-%NULL. It specifies the type of container to
32061 * construct. It can be an indefinite type such as
32062 * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
32063 * Maybe, array, tuple, dictionary entry and variant-typed values may be
32066 * After the builder is initialised, values are added using
32067 * g_variant_builder_add_value() or g_variant_builder_add().
32069 * After all the child values are added, g_variant_builder_end() frees
32070 * the memory associated with the builder and returns the #GVariant that
32073 * This function completely ignores the previous contents of @builder.
32074 * On one hand this means that it is valid to pass in completely
32075 * uninitialised memory. On the other hand, this means that if you are
32076 * initialising over top of an existing #GVariantBuilder you need to
32077 * first call g_variant_builder_clear() in order to avoid leaking
32080 * You must not call g_variant_builder_ref() or
32081 * g_variant_builder_unref() on a #GVariantBuilder that was initialised
32082 * with this function. If you ever pass a reference to a
32083 * #GVariantBuilder outside of the control of your own code then you
32084 * should assume that the person receiving that reference may try to use
32085 * reference counting; you should use g_variant_builder_new() instead of
32093 * g_variant_builder_new:
32094 * @type: a container type
32096 * Allocates and initialises a new #GVariantBuilder.
32098 * You should call g_variant_builder_unref() on the return value when it
32099 * is no longer needed. The memory will not be automatically freed by
32102 * In most cases it is easier to place a #GVariantBuilder directly on
32103 * the stack of the calling function and initialise it with
32104 * g_variant_builder_init().
32106 * Returns: (transfer full): a #GVariantBuilder
32112 * g_variant_builder_open:
32113 * @builder: a #GVariantBuilder
32114 * @type: a #GVariantType
32116 * Opens a subcontainer inside the given @builder. When done adding
32117 * items to the subcontainer, g_variant_builder_close() must be called.
32119 * It is an error to call this function in any way that would cause an
32120 * inconsistent value to be constructed (ie: adding too many values or
32121 * a value of an incorrect type).
32128 * g_variant_builder_ref:
32129 * @builder: a #GVariantBuilder allocated by g_variant_builder_new()
32131 * Increases the reference count on @builder.
32133 * Don't call this on stack-allocated #GVariantBuilder instances or bad
32134 * things will happen.
32136 * Returns: (transfer full): a new reference to @builder
32142 * g_variant_builder_unref:
32143 * @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new()
32145 * Decreases the reference count on @builder.
32147 * In the event that there are no more references, releases all memory
32148 * associated with the #GVariantBuilder.
32150 * Don't call this on stack-allocated #GVariantBuilder instances or bad
32151 * things will happen.
32158 * g_variant_byteswap:
32159 * @value: a #GVariant
32161 * Performs a byteswapping operation on the contents of @value. The
32162 * result is that all multi-byte numeric data contained in @value is
32163 * byteswapped. That includes 16, 32, and 64bit signed and unsigned
32164 * integers as well as file handles and double precision floating point
32167 * This function is an identity mapping on any value that does not
32168 * contain multi-byte numeric data. That include strings, booleans,
32169 * bytes and containers containing only these things (recursively).
32171 * The returned value is always in normal form and is marked as trusted.
32173 * Returns: (transfer full): the byteswapped form of @value
32179 * g_variant_check_format_string:
32180 * @value: a #GVariant
32181 * @format_string: a valid #GVariant format string
32182 * @copy_only: %TRUE to ensure the format string makes deep copies
32184 * Checks if calling g_variant_get() with @format_string on @value would
32185 * be valid from a type-compatibility standpoint. @format_string is
32186 * assumed to be a valid format string (from a syntactic standpoint).
32188 * If @copy_only is %TRUE then this function additionally checks that it
32189 * would be safe to call g_variant_unref() on @value immediately after
32190 * the call to g_variant_get() without invalidating the result. This is
32191 * only possible if deep copies are made (ie: there are no pointers to
32192 * the data inside of the soon-to-be-freed #GVariant instance). If this
32193 * check fails then a g_critical() is printed and %FALSE is returned.
32195 * This function is meant to be used by functions that wish to provide
32196 * varargs accessors to #GVariant values of uncertain values (eg:
32197 * g_variant_lookup() or g_menu_model_get_item_attribute()).
32199 * Returns: %TRUE if @format_string is safe to use
32205 * g_variant_classify:
32206 * @value: a #GVariant
32208 * Classifies @value according to its top-level type.
32210 * Returns: the #GVariantClass of @value
32216 * g_variant_compare:
32217 * @one: (type GVariant): a basic-typed #GVariant instance
32218 * @two: (type GVariant): a #GVariant instance of the same type
32220 * Compares @one and @two.
32222 * The types of @one and @two are #gconstpointer only to allow use of
32223 * this function with #GTree, #GPtrArray, etc. They must each be a
32226 * Comparison is only defined for basic types (ie: booleans, numbers,
32227 * strings). For booleans, %FALSE is less than %TRUE. Numbers are
32228 * ordered in the usual way. Strings are in ASCII lexographical order.
32230 * It is a programmer error to attempt to compare container values or
32231 * two values that have types that are not exactly equal. For example,
32232 * you cannot compare a 32-bit signed integer with a 32-bit unsigned
32233 * integer. Also note that this function is not particularly
32234 * well-behaved when it comes to comparison of doubles; in particular,
32235 * the handling of incomparable values (ie: NaN) is undefined.
32237 * If you only require an equality comparison, g_variant_equal() is more
32240 * Returns: negative value if a < b;
32242 * positive value if a > b.
32248 * g_variant_dict_clear:
32249 * @dict: a #GVariantDict
32251 * Releases all memory associated with a #GVariantDict without freeing
32252 * the #GVariantDict structure itself.
32254 * It typically only makes sense to do this on a stack-allocated
32255 * #GVariantDict if you want to abort building the value part-way
32256 * through. This function need not be called if you call
32257 * g_variant_dict_end() and it also doesn't need to be called on dicts
32258 * allocated with g_variant_dict_new (see g_variant_dict_unref() for
32261 * It is valid to call this function on either an initialised
32262 * #GVariantDict or one that was previously cleared by an earlier call
32263 * to g_variant_dict_clear() but it is not valid to call this function
32264 * on uninitialised memory.
32271 * g_variant_dict_contains:
32272 * @dict: a #GVariantDict
32273 * @key: the key to lookup in the dictionary
32275 * Checks if @key exists in @dict.
32277 * Returns: %TRUE if @key is in @dict
32283 * g_variant_dict_end:
32284 * @dict: a #GVariantDict
32286 * Returns the current value of @dict as a #GVariant of type
32287 * %G_VARIANT_TYPE_VARDICT, clearing it in the process.
32289 * It is not permissible to use @dict in any way after this call except
32290 * for reference counting operations (in the case of a heap-allocated
32291 * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in
32292 * the case of stack-allocated).
32294 * Returns: (transfer none): a new, floating, #GVariant
32300 * g_variant_dict_init: (skip)
32301 * @dict: a #GVariantDict
32302 * @from_asv: (allow-none): the initial value for @dict
32304 * Initialises a #GVariantDict structure.
32306 * If @from_asv is given, it is used to initialise the dictionary.
32308 * This function completely ignores the previous contents of @dict. On
32309 * one hand this means that it is valid to pass in completely
32310 * uninitialised memory. On the other hand, this means that if you are
32311 * initialising over top of an existing #GVariantDict you need to first
32312 * call g_variant_dict_clear() in order to avoid leaking memory.
32314 * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a
32315 * #GVariantDict that was initialised with this function. If you ever
32316 * pass a reference to a #GVariantDict outside of the control of your
32317 * own code then you should assume that the person receiving that
32318 * reference may try to use reference counting; you should use
32319 * g_variant_dict_new() instead of this function.
32326 * g_variant_dict_insert:
32327 * @dict: a #GVariantDict
32328 * @key: the key to insert a value for
32329 * @format_string: a #GVariant varargs format string
32330 * @...: arguments, as per @format_string
32332 * Inserts a value into a #GVariantDict.
32334 * This call is a convenience wrapper that is exactly equivalent to
32335 * calling g_variant_new() followed by g_variant_dict_insert_value().
32342 * g_variant_dict_insert_value:
32343 * @dict: a #GVariantDict
32344 * @key: the key to insert a value for
32345 * @value: the value to insert
32347 * Inserts (or replaces) a key in a #GVariantDict.
32349 * @value is consumed if it is floating.
32356 * g_variant_dict_lookup:
32357 * @dict: a #GVariantDict
32358 * @key: the key to lookup in the dictionary
32359 * @format_string: a GVariant format string
32360 * @...: the arguments to unpack the value into
32362 * Looks up a value in a #GVariantDict.
32364 * This function is a wrapper around g_variant_dict_lookup_value() and
32365 * g_variant_get(). In the case that %NULL would have been returned,
32366 * this function returns %FALSE. Otherwise, it unpacks the returned
32367 * value and returns %TRUE.
32369 * @format_string determines the C types that are used for unpacking the
32370 * values and also determines if the values are copied or borrowed, see the
32371 * section on [GVariant format strings][gvariant-format-strings-pointers].
32373 * Returns: %TRUE if a value was unpacked
32379 * g_variant_dict_lookup_value:
32380 * @dict: a #GVariantDict
32381 * @key: the key to lookup in the dictionary
32382 * @expected_type: (allow-none): a #GVariantType, or %NULL
32384 * Looks up a value in a #GVariantDict.
32386 * If @key is not found in @dictionary, %NULL is returned.
32388 * The @expected_type string specifies what type of value is expected.
32389 * If the value associated with @key has a different type then %NULL is
32392 * If the key is found and the value has the correct type, it is
32393 * returned. If @expected_type was specified then any non-%NULL return
32394 * value will have this type.
32396 * Returns: (transfer full): the value of the dictionary key, or %NULL
32402 * g_variant_dict_new:
32403 * @from_asv: (allow-none): the #GVariant with which to initialise the
32406 * Allocates and initialises a new #GVariantDict.
32408 * You should call g_variant_dict_unref() on the return value when it
32409 * is no longer needed. The memory will not be automatically freed by
32412 * In some cases it may be easier to place a #GVariantDict directly on
32413 * the stack of the calling function and initialise it with
32414 * g_variant_dict_init(). This is particularly useful when you are
32415 * using #GVariantDict to construct a #GVariant.
32417 * Returns: (transfer full): a #GVariantDict
32423 * g_variant_dict_ref:
32424 * @dict: a heap-allocated #GVariantDict
32426 * Increases the reference count on @dict.
32428 * Don't call this on stack-allocated #GVariantDict instances or bad
32429 * things will happen.
32431 * Returns: (transfer full): a new reference to @dict
32437 * g_variant_dict_remove:
32438 * @dict: a #GVariantDict
32439 * @key: the key to remove
32441 * Removes a key and its associated value from a #GVariantDict.
32443 * Returns: %TRUE if the key was found and removed
32449 * g_variant_dict_unref:
32450 * @dict: (transfer full): a heap-allocated #GVariantDict
32452 * Decreases the reference count on @dict.
32454 * In the event that there are no more references, releases all memory
32455 * associated with the #GVariantDict.
32457 * Don't call this on stack-allocated #GVariantDict instances or bad
32458 * things will happen.
32465 * g_variant_dup_bytestring:
32466 * @value: an array-of-bytes #GVariant instance
32467 * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store
32468 * the length (not including the nul terminator)
32470 * Similar to g_variant_get_bytestring() except that instead of
32471 * returning a constant string, the string is duplicated.
32473 * The return value must be freed using g_free().
32475 * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8):
32476 * a newly allocated string
32482 * g_variant_dup_bytestring_array:
32483 * @value: an array of array of bytes #GVariant ('aay')
32484 * @length: (out) (allow-none): the length of the result, or %NULL
32486 * Gets the contents of an array of array of bytes #GVariant. This call
32487 * makes a deep copy; the return result should be released with
32490 * If @length is non-%NULL then the number of elements in the result is
32491 * stored there. In any case, the resulting array will be
32492 * %NULL-terminated.
32494 * For an empty array, @length will be set to 0 and a pointer to a
32495 * %NULL pointer will be returned.
32497 * Returns: (array length=length) (transfer full): an array of strings
32503 * g_variant_dup_objv:
32504 * @value: an array of object paths #GVariant
32505 * @length: (out) (allow-none): the length of the result, or %NULL
32507 * Gets the contents of an array of object paths #GVariant. This call
32508 * makes a deep copy; the return result should be released with
32511 * If @length is non-%NULL then the number of elements in the result
32512 * is stored there. In any case, the resulting array will be
32513 * %NULL-terminated.
32515 * For an empty array, @length will be set to 0 and a pointer to a
32516 * %NULL pointer will be returned.
32518 * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
32524 * g_variant_dup_string:
32525 * @value: a string #GVariant instance
32526 * @length: (out): a pointer to a #gsize, to store the length
32528 * Similar to g_variant_get_string() except that instead of returning
32529 * a constant string, the string is duplicated.
32531 * The string will always be utf8 encoded.
32533 * The return value must be freed using g_free().
32535 * Returns: (transfer full): a newly allocated string, utf8 encoded
32541 * g_variant_dup_strv:
32542 * @value: an array of strings #GVariant
32543 * @length: (out) (allow-none): the length of the result, or %NULL
32545 * Gets the contents of an array of strings #GVariant. This call
32546 * makes a deep copy; the return result should be released with
32549 * If @length is non-%NULL then the number of elements in the result
32550 * is stored there. In any case, the resulting array will be
32551 * %NULL-terminated.
32553 * For an empty array, @length will be set to 0 and a pointer to a
32554 * %NULL pointer will be returned.
32556 * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
32563 * @one: (type GVariant): a #GVariant instance
32564 * @two: (type GVariant): a #GVariant instance
32566 * Checks if @one and @two have the same type and value.
32568 * The types of @one and @two are #gconstpointer only to allow use of
32569 * this function with #GHashTable. They must each be a #GVariant.
32571 * Returns: %TRUE if @one and @two are equal
32577 * g_variant_get: (skip)
32578 * @value: a #GVariant instance
32579 * @format_string: a #GVariant format string
32580 * @...: arguments, as per @format_string
32582 * Deconstructs a #GVariant instance.
32584 * Think of this function as an analogue to scanf().
32586 * The arguments that are expected by this function are entirely
32587 * determined by @format_string. @format_string also restricts the
32588 * permissible types of @value. It is an error to give a value with
32589 * an incompatible type. See the section on
32590 * [GVariant format strings][gvariant-format-strings].
32591 * Please note that the syntax of the format string is very likely to be
32592 * extended in the future.
32594 * @format_string determines the C types that are used for unpacking
32595 * the values and also determines if the values are copied or borrowed,
32596 * see the section on
32597 * [GVariant format strings][gvariant-format-strings-pointers].
32604 * g_variant_get_boolean:
32605 * @value: a boolean #GVariant instance
32607 * Returns the boolean value of @value.
32609 * It is an error to call this function with a @value of any type
32610 * other than %G_VARIANT_TYPE_BOOLEAN.
32612 * Returns: %TRUE or %FALSE
32618 * g_variant_get_byte:
32619 * @value: a byte #GVariant instance
32621 * Returns the byte value of @value.
32623 * It is an error to call this function with a @value of any type
32624 * other than %G_VARIANT_TYPE_BYTE.
32626 * Returns: a #guchar
32632 * g_variant_get_bytestring:
32633 * @value: an array-of-bytes #GVariant instance
32635 * Returns the string value of a #GVariant instance with an
32636 * array-of-bytes type. The string has no particular encoding.
32638 * If the array does not end with a nul terminator character, the empty
32639 * string is returned. For this reason, you can always trust that a
32640 * non-%NULL nul-terminated string will be returned by this function.
32642 * If the array contains a nul terminator character somewhere other than
32643 * the last byte then the returned string is the string, up to the first
32644 * such nul character.
32646 * It is an error to call this function with a @value that is not an
32649 * The return value remains valid as long as @value exists.
32651 * Returns: (transfer none) (array zero-terminated=1) (element-type guint8):
32652 * the constant string
32658 * g_variant_get_bytestring_array:
32659 * @value: an array of array of bytes #GVariant ('aay')
32660 * @length: (out) (allow-none): the length of the result, or %NULL
32662 * Gets the contents of an array of array of bytes #GVariant. This call
32663 * makes a shallow copy; the return result should be released with
32664 * g_free(), but the individual strings must not be modified.
32666 * If @length is non-%NULL then the number of elements in the result is
32667 * stored there. In any case, the resulting array will be
32668 * %NULL-terminated.
32670 * For an empty array, @length will be set to 0 and a pointer to a
32671 * %NULL pointer will be returned.
32673 * Returns: (array length=length) (transfer container): an array of constant strings
32679 * g_variant_get_child: (skip)
32680 * @value: a container #GVariant
32681 * @index_: the index of the child to deconstruct
32682 * @format_string: a #GVariant format string
32683 * @...: arguments, as per @format_string
32685 * Reads a child item out of a container #GVariant instance and
32686 * deconstructs it according to @format_string. This call is
32687 * essentially a combination of g_variant_get_child_value() and
32690 * @format_string determines the C types that are used for unpacking
32691 * the values and also determines if the values are copied or borrowed,
32692 * see the section on
32693 * [GVariant format strings][gvariant-format-strings-pointers].
32700 * g_variant_get_child_value:
32701 * @value: a container #GVariant
32702 * @index_: the index of the child to fetch
32704 * Reads a child item out of a container #GVariant instance. This
32705 * includes variants, maybes, arrays, tuples and dictionary
32706 * entries. It is an error to call this function on any other type of
32709 * It is an error if @index_ is greater than the number of child items
32710 * in the container. See g_variant_n_children().
32712 * The returned value is never floating. You should free it with
32713 * g_variant_unref() when you're done with it.
32715 * This function is O(1).
32717 * Returns: (transfer full): the child at the specified index
32723 * g_variant_get_data:
32724 * @value: a #GVariant instance
32726 * Returns a pointer to the serialised form of a #GVariant instance.
32727 * The returned data may not be in fully-normalised form if read from an
32728 * untrusted source. The returned data must not be freed; it remains
32729 * valid for as long as @value exists.
32731 * If @value is a fixed-sized value that was deserialised from a
32732 * corrupted serialised container then %NULL may be returned. In this
32733 * case, the proper thing to do is typically to use the appropriate
32734 * number of nul bytes in place of @value. If @value is not fixed-sized
32735 * then %NULL is never returned.
32737 * In the case that @value is already in serialised form, this function
32738 * is O(1). If the value is not already in serialised form,
32739 * serialisation occurs implicitly and is approximately O(n) in the size
32742 * To deserialise the data returned by this function, in addition to the
32743 * serialised data, you must know the type of the #GVariant, and (if the
32744 * machine might be different) the endianness of the machine that stored
32745 * it. As a result, file formats or network messages that incorporate
32746 * serialised #GVariant<!---->s must include this information either
32747 * implicitly (for instance "the file always contains a
32748 * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
32749 * explicitly (by storing the type and/or endianness in addition to the
32750 * serialised data).
32752 * Returns: (transfer none): the serialised form of @value, or %NULL
32758 * g_variant_get_data_as_bytes:
32759 * @value: a #GVariant
32761 * Returns a pointer to the serialised form of a #GVariant instance.
32762 * The semantics of this function are exactly the same as
32763 * g_variant_get_data(), except that the returned #GBytes holds
32764 * a reference to the variant data.
32766 * Returns: (transfer full): A new #GBytes representing the variant data
32772 * g_variant_get_double:
32773 * @value: a double #GVariant instance
32775 * Returns the double precision floating point value of @value.
32777 * It is an error to call this function with a @value of any type
32778 * other than %G_VARIANT_TYPE_DOUBLE.
32780 * Returns: a #gdouble
32786 * g_variant_get_fixed_array:
32787 * @value: a #GVariant array with fixed-sized elements
32788 * @n_elements: (out): a pointer to the location to store the number of items
32789 * @element_size: the size of each element
32791 * Provides access to the serialised data for an array of fixed-sized
32794 * @value must be an array with fixed-sized elements. Numeric types are
32795 * fixed-size, as are tuples containing only other fixed-sized types.
32797 * @element_size must be the size of a single element in the array,
32798 * as given by the section on
32799 * [serialized data memory][gvariant-serialised-data-memory].
32801 * In particular, arrays of these fixed-sized types can be interpreted
32802 * as an array of the given C type, with @element_size set to the size
32803 * the appropriate type:
32804 * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.)
32805 * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!)
32806 * - %G_VARIANT_TYPE_BYTE: #guchar
32807 * - %G_VARIANT_TYPE_HANDLE: #guint32
32808 * - %G_VARIANT_TYPE_DOUBLE: #gdouble
32810 * For example, if calling this function for an array of 32-bit integers,
32811 * you might say sizeof(gint32). This value isn't used except for the purpose
32812 * of a double-check that the form of the serialised data matches the caller's
32815 * @n_elements, which must be non-%NULL is set equal to the number of
32816 * items in the array.
32818 * Returns: (array length=n_elements) (transfer none): a pointer to
32825 * g_variant_get_handle:
32826 * @value: a handle #GVariant instance
32828 * Returns the 32-bit signed integer value of @value.
32830 * It is an error to call this function with a @value of any type other
32831 * than %G_VARIANT_TYPE_HANDLE.
32833 * By convention, handles are indexes into an array of file descriptors
32834 * that are sent alongside a D-Bus message. If you're not interacting
32835 * with D-Bus, you probably don't need them.
32837 * Returns: a #gint32
32843 * g_variant_get_int16:
32844 * @value: a int16 #GVariant instance
32846 * Returns the 16-bit signed integer value of @value.
32848 * It is an error to call this function with a @value of any type
32849 * other than %G_VARIANT_TYPE_INT16.
32851 * Returns: a #gint16
32857 * g_variant_get_int32:
32858 * @value: a int32 #GVariant instance
32860 * Returns the 32-bit signed integer value of @value.
32862 * It is an error to call this function with a @value of any type
32863 * other than %G_VARIANT_TYPE_INT32.
32865 * Returns: a #gint32
32871 * g_variant_get_int64:
32872 * @value: a int64 #GVariant instance
32874 * Returns the 64-bit signed integer value of @value.
32876 * It is an error to call this function with a @value of any type
32877 * other than %G_VARIANT_TYPE_INT64.
32879 * Returns: a #gint64
32885 * g_variant_get_maybe:
32886 * @value: a maybe-typed value
32888 * Given a maybe-typed #GVariant instance, extract its value. If the
32889 * value is Nothing, then this function returns %NULL.
32891 * Returns: (allow-none) (transfer full): the contents of @value, or %NULL
32897 * g_variant_get_normal_form:
32898 * @value: a #GVariant
32900 * Gets a #GVariant instance that has the same value as @value and is
32901 * trusted to be in normal form.
32903 * If @value is already trusted to be in normal form then a new
32904 * reference to @value is returned.
32906 * If @value is not already trusted, then it is scanned to check if it
32907 * is in normal form. If it is found to be in normal form then it is
32908 * marked as trusted and a new reference to it is returned.
32910 * If @value is found not to be in normal form then a new trusted
32911 * #GVariant is created with the same value as @value.
32913 * It makes sense to call this function if you've received #GVariant
32914 * data from untrusted sources and you want to ensure your serialised
32915 * output is definitely in normal form.
32917 * Returns: (transfer full): a trusted #GVariant
32923 * g_variant_get_objv:
32924 * @value: an array of object paths #GVariant
32925 * @length: (out) (allow-none): the length of the result, or %NULL
32927 * Gets the contents of an array of object paths #GVariant. This call
32928 * makes a shallow copy; the return result should be released with
32929 * g_free(), but the individual strings must not be modified.
32931 * If @length is non-%NULL then the number of elements in the result
32932 * is stored there. In any case, the resulting array will be
32933 * %NULL-terminated.
32935 * For an empty array, @length will be set to 0 and a pointer to a
32936 * %NULL pointer will be returned.
32938 * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
32944 * g_variant_get_size:
32945 * @value: a #GVariant instance
32947 * Determines the number of bytes that would be required to store @value
32948 * with g_variant_store().
32950 * If @value has a fixed-sized type then this function always returned
32953 * In the case that @value is already in serialised form or the size has
32954 * already been calculated (ie: this function has been called before)
32955 * then this function is O(1). Otherwise, the size is calculated, an
32956 * operation which is approximately O(n) in the number of values
32959 * Returns: the serialised size of @value
32965 * g_variant_get_string:
32966 * @value: a string #GVariant instance
32967 * @length: (allow-none) (default 0) (out): a pointer to a #gsize,
32968 * to store the length
32970 * Returns the string value of a #GVariant instance with a string
32971 * type. This includes the types %G_VARIANT_TYPE_STRING,
32972 * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
32974 * The string will always be utf8 encoded.
32976 * If @length is non-%NULL then the length of the string (in bytes) is
32977 * returned there. For trusted values, this information is already
32978 * known. For untrusted values, a strlen() will be performed.
32980 * It is an error to call this function with a @value of any type
32981 * other than those three.
32983 * The return value remains valid as long as @value exists.
32985 * Returns: (transfer none): the constant string, utf8 encoded
32991 * g_variant_get_strv:
32992 * @value: an array of strings #GVariant
32993 * @length: (out) (allow-none): the length of the result, or %NULL
32995 * Gets the contents of an array of strings #GVariant. This call
32996 * makes a shallow copy; the return result should be released with
32997 * g_free(), but the individual strings must not be modified.
32999 * If @length is non-%NULL then the number of elements in the result
33000 * is stored there. In any case, the resulting array will be
33001 * %NULL-terminated.
33003 * For an empty array, @length will be set to 0 and a pointer to a
33004 * %NULL pointer will be returned.
33006 * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
33012 * g_variant_get_type:
33013 * @value: a #GVariant
33015 * Determines the type of @value.
33017 * The return value is valid for the lifetime of @value and must not
33020 * Returns: a #GVariantType
33026 * g_variant_get_type_string:
33027 * @value: a #GVariant
33029 * Returns the type string of @value. Unlike the result of calling
33030 * g_variant_type_peek_string(), this string is nul-terminated. This
33031 * string belongs to #GVariant and must not be freed.
33033 * Returns: the type string for the type of @value
33039 * g_variant_get_uint16:
33040 * @value: a uint16 #GVariant instance
33042 * Returns the 16-bit unsigned integer value of @value.
33044 * It is an error to call this function with a @value of any type
33045 * other than %G_VARIANT_TYPE_UINT16.
33047 * Returns: a #guint16
33053 * g_variant_get_uint32:
33054 * @value: a uint32 #GVariant instance
33056 * Returns the 32-bit unsigned integer value of @value.
33058 * It is an error to call this function with a @value of any type
33059 * other than %G_VARIANT_TYPE_UINT32.
33061 * Returns: a #guint32
33067 * g_variant_get_uint64:
33068 * @value: a uint64 #GVariant instance
33070 * Returns the 64-bit unsigned integer value of @value.
33072 * It is an error to call this function with a @value of any type
33073 * other than %G_VARIANT_TYPE_UINT64.
33075 * Returns: a #guint64
33081 * g_variant_get_va: (skip)
33082 * @value: a #GVariant
33083 * @format_string: a string that is prefixed with a format string
33084 * @endptr: (allow-none) (default NULL): location to store the end pointer,
33086 * @app: a pointer to a #va_list
33088 * This function is intended to be used by libraries based on #GVariant
33089 * that want to provide g_variant_get()-like functionality to their
33092 * The API is more general than g_variant_get() to allow a wider range
33093 * of possible uses.
33095 * @format_string must still point to a valid format string, but it only
33096 * need to be nul-terminated if @endptr is %NULL. If @endptr is
33097 * non-%NULL then it is updated to point to the first character past the
33098 * end of the format string.
33100 * @app is a pointer to a #va_list. The arguments, according to
33101 * @format_string, are collected from this #va_list and the list is left
33102 * pointing to the argument following the last.
33104 * These two generalisations allow mixing of multiple calls to
33105 * g_variant_new_va() and g_variant_get_va() within a single actual
33106 * varargs call by the user.
33108 * @format_string determines the C types that are used for unpacking
33109 * the values and also determines if the values are copied or borrowed,
33110 * see the section on
33111 * [GVariant format strings][gvariant-format-strings-pointers].
33118 * g_variant_get_variant:
33119 * @value: a variant #GVariant instance
33121 * Unboxes @value. The result is the #GVariant instance that was
33122 * contained in @value.
33124 * Returns: (transfer full): the item contained in the variant
33131 * @value: (type GVariant): a basic #GVariant value as a #gconstpointer
33133 * Generates a hash value for a #GVariant instance.
33135 * The output of this function is guaranteed to be the same for a given
33136 * value only per-process. It may change between different processor
33137 * architectures or even different versions of GLib. Do not use this
33138 * function as a basis for building protocols or file formats.
33140 * The type of @value is #gconstpointer only to allow use of this
33141 * function with #GHashTable. @value must be a #GVariant.
33143 * Returns: a hash value corresponding to @value
33149 * g_variant_is_container:
33150 * @value: a #GVariant instance
33152 * Checks if @value is a container.
33154 * Returns: %TRUE if @value is a container
33160 * g_variant_is_floating:
33161 * @value: a #GVariant
33163 * Checks whether @value has a floating reference count.
33165 * This function should only ever be used to assert that a given variant
33166 * is or is not floating, or for debug purposes. To acquire a reference
33167 * to a variant that might be floating, always use g_variant_ref_sink()
33168 * or g_variant_take_ref().
33170 * See g_variant_ref_sink() for more information about floating reference
33173 * Returns: whether @value is floating
33179 * g_variant_is_normal_form:
33180 * @value: a #GVariant instance
33182 * Checks if @value is in normal form.
33184 * The main reason to do this is to detect if a given chunk of
33185 * serialised data is in normal form: load the data into a #GVariant
33186 * using g_variant_new_from_data() and then use this function to
33189 * If @value is found to be in normal form then it will be marked as
33190 * being trusted. If the value was already marked as being trusted then
33191 * this function will immediately return %TRUE.
33193 * Returns: %TRUE if @value is in normal form
33199 * g_variant_is_object_path:
33200 * @string: a normal C nul-terminated string
33202 * Determines if a given string is a valid D-Bus object path. You
33203 * should ensure that a string is a valid D-Bus object path before
33204 * passing it to g_variant_new_object_path().
33206 * A valid object path starts with '/' followed by zero or more
33207 * sequences of characters separated by '/' characters. Each sequence
33208 * must contain only the characters "[A-Z][a-z][0-9]_". No sequence
33209 * (including the one following the final '/' character) may be empty.
33211 * Returns: %TRUE if @string is a D-Bus object path
33217 * g_variant_is_of_type:
33218 * @value: a #GVariant instance
33219 * @type: a #GVariantType
33221 * Checks if a value has a type matching the provided type.
33223 * Returns: %TRUE if the type of @value matches @type
33229 * g_variant_is_signature:
33230 * @string: a normal C nul-terminated string
33232 * Determines if a given string is a valid D-Bus type signature. You
33233 * should ensure that a string is a valid D-Bus type signature before
33234 * passing it to g_variant_new_signature().
33236 * D-Bus type signatures consist of zero or more definite #GVariantType
33237 * strings in sequence.
33239 * Returns: %TRUE if @string is a D-Bus type signature
33245 * g_variant_iter_copy:
33246 * @iter: a #GVariantIter
33248 * Creates a new heap-allocated #GVariantIter to iterate over the
33249 * container that was being iterated over by @iter. Iteration begins on
33250 * the new iterator from the current position of the old iterator but
33251 * the two copies are independent past that point.
33253 * Use g_variant_iter_free() to free the return value when you no longer
33256 * A reference is taken to the container that @iter is iterating over
33257 * and will be releated only when g_variant_iter_free() is called.
33259 * Returns: (transfer full): a new heap-allocated #GVariantIter
33265 * g_variant_iter_free:
33266 * @iter: (transfer full): a heap-allocated #GVariantIter
33268 * Frees a heap-allocated #GVariantIter. Only call this function on
33269 * iterators that were returned by g_variant_iter_new() or
33270 * g_variant_iter_copy().
33277 * g_variant_iter_init: (skip)
33278 * @iter: a pointer to a #GVariantIter
33279 * @value: a container #GVariant
33281 * Initialises (without allocating) a #GVariantIter. @iter may be
33282 * completely uninitialised prior to this call; its old value is
33285 * The iterator remains valid for as long as @value exists, and need not
33286 * be freed in any way.
33288 * Returns: the number of items in @value
33294 * g_variant_iter_loop: (skip)
33295 * @iter: a #GVariantIter
33296 * @format_string: a GVariant format string
33297 * @...: the arguments to unpack the value into
33299 * Gets the next item in the container and unpacks it into the variable
33300 * argument list according to @format_string, returning %TRUE.
33302 * If no more items remain then %FALSE is returned.
33304 * On the first call to this function, the pointers appearing on the
33305 * variable argument list are assumed to point at uninitialised memory.
33306 * On the second and later calls, it is assumed that the same pointers
33307 * will be given and that they will point to the memory as set by the
33308 * previous call to this function. This allows the previous values to
33309 * be freed, as appropriate.
33311 * This function is intended to be used with a while loop as
33312 * demonstrated in the following example. This function can only be
33313 * used when iterating over an array. It is only valid to call this
33314 * function with a string constant for the format string and the same
33315 * string constant must be used each time. Mixing calls to this
33316 * function and g_variant_iter_next() or g_variant_iter_next_value() on
33317 * the same iterator causes undefined behavior.
33319 * If you break out of a such a while loop using g_variant_iter_loop() then
33320 * you must free or unreference all the unpacked values as you would with
33321 * g_variant_get(). Failure to do so will cause a memory leak.
33323 * Here is an example for memory management with g_variant_iter_loop():
33324 * |[<!-- language="C" -->
33325 * // Iterates a dictionary of type 'a{sv}'
33327 * iterate_dictionary (GVariant *dictionary)
33329 * GVariantIter iter;
33333 * g_variant_iter_init (&iter, dictionary);
33334 * while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
33336 * g_print ("Item '%s' has type '%s'\n", key,
33337 * g_variant_get_type_string (value));
33339 * // no need to free 'key' and 'value' here
33340 * // unless breaking out of this loop
33345 * For most cases you should use g_variant_iter_next().
33347 * This function is really only useful when unpacking into #GVariant or
33348 * #GVariantIter in order to allow you to skip the call to
33349 * g_variant_unref() or g_variant_iter_free().
33351 * For example, if you are only looping over simple integer and string
33352 * types, g_variant_iter_next() is definitely preferred. For string
33353 * types, use the '&' prefix to avoid allocating any memory at all (and
33354 * thereby avoiding the need to free anything as well).
33356 * @format_string determines the C types that are used for unpacking
33357 * the values and also determines if the values are copied or borrowed.
33359 * See the section on
33360 * [GVariant format strings][gvariant-format-strings-pointers].
33362 * Returns: %TRUE if a value was unpacked, or %FALSE if there was no
33369 * g_variant_iter_n_children:
33370 * @iter: a #GVariantIter
33372 * Queries the number of child items in the container that we are
33373 * iterating over. This is the total number of items -- not the number
33374 * of items remaining.
33376 * This function might be useful for preallocation of arrays.
33378 * Returns: the number of children in the container
33384 * g_variant_iter_new:
33385 * @value: a container #GVariant
33387 * Creates a heap-allocated #GVariantIter for iterating over the items
33390 * Use g_variant_iter_free() to free the return value when you no longer
33393 * A reference is taken to @value and will be released only when
33394 * g_variant_iter_free() is called.
33396 * Returns: (transfer full): a new heap-allocated #GVariantIter
33402 * g_variant_iter_next: (skip)
33403 * @iter: a #GVariantIter
33404 * @format_string: a GVariant format string
33405 * @...: the arguments to unpack the value into
33407 * Gets the next item in the container and unpacks it into the variable
33408 * argument list according to @format_string, returning %TRUE.
33410 * If no more items remain then %FALSE is returned.
33412 * All of the pointers given on the variable arguments list of this
33413 * function are assumed to point at uninitialised memory. It is the
33414 * responsibility of the caller to free all of the values returned by
33415 * the unpacking process.
33417 * Here is an example for memory management with g_variant_iter_next():
33418 * |[<!-- language="C" -->
33419 * // Iterates a dictionary of type 'a{sv}'
33421 * iterate_dictionary (GVariant *dictionary)
33423 * GVariantIter iter;
33427 * g_variant_iter_init (&iter, dictionary);
33428 * while (g_variant_iter_next (&iter, "{sv}", &key, &value))
33430 * g_print ("Item '%s' has type '%s'\n", key,
33431 * g_variant_get_type_string (value));
33433 * // must free data for ourselves
33434 * g_variant_unref (value);
33440 * For a solution that is likely to be more convenient to C programmers
33441 * when dealing with loops, see g_variant_iter_loop().
33443 * @format_string determines the C types that are used for unpacking
33444 * the values and also determines if the values are copied or borrowed.
33446 * See the section on
33447 * [GVariant format strings][gvariant-format-strings-pointers].
33449 * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
33455 * g_variant_iter_next_value:
33456 * @iter: a #GVariantIter
33458 * Gets the next item in the container. If no more items remain then
33459 * %NULL is returned.
33461 * Use g_variant_unref() to drop your reference on the return value when
33462 * you no longer need it.
33464 * Here is an example for iterating with g_variant_iter_next_value():
33465 * |[<!-- language="C" -->
33466 * // recursively iterate a container
33468 * iterate_container_recursive (GVariant *container)
33470 * GVariantIter iter;
33473 * g_variant_iter_init (&iter, container);
33474 * while ((child = g_variant_iter_next_value (&iter)))
33476 * g_print ("type '%s'\n", g_variant_get_type_string (child));
33478 * if (g_variant_is_container (child))
33479 * iterate_container_recursive (child);
33481 * g_variant_unref (child);
33486 * Returns: (allow-none) (transfer full): a #GVariant, or %NULL
33492 * g_variant_lookup: (skip)
33493 * @dictionary: a dictionary #GVariant
33494 * @key: the key to lookup in the dictionary
33495 * @format_string: a GVariant format string
33496 * @...: the arguments to unpack the value into
33498 * Looks up a value in a dictionary #GVariant.
33500 * This function is a wrapper around g_variant_lookup_value() and
33501 * g_variant_get(). In the case that %NULL would have been returned,
33502 * this function returns %FALSE. Otherwise, it unpacks the returned
33503 * value and returns %TRUE.
33505 * @format_string determines the C types that are used for unpacking
33506 * the values and also determines if the values are copied or borrowed,
33507 * see the section on
33508 * [GVariant format strings][gvariant-format-strings-pointers].
33510 * This function is currently implemented with a linear scan. If you
33511 * plan to do many lookups then #GVariantDict may be more efficient.
33513 * Returns: %TRUE if a value was unpacked
33519 * g_variant_lookup_value:
33520 * @dictionary: a dictionary #GVariant
33521 * @key: the key to lookup in the dictionary
33522 * @expected_type: (allow-none): a #GVariantType, or %NULL
33524 * Looks up a value in a dictionary #GVariant.
33526 * This function works with dictionaries of the type a{s*} (and equally
33527 * well with type a{o*}, but we only further discuss the string case
33528 * for sake of clarity).
33530 * In the event that @dictionary has the type a{sv}, the @expected_type
33531 * string specifies what type of value is expected to be inside of the
33532 * variant. If the value inside the variant has a different type then
33533 * %NULL is returned. In the event that @dictionary has a value type other
33534 * than v then @expected_type must directly match the key type and it is
33535 * used to unpack the value directly or an error occurs.
33537 * In either case, if @key is not found in @dictionary, %NULL is returned.
33539 * If the key is found and the value has the correct type, it is
33540 * returned. If @expected_type was specified then any non-%NULL return
33541 * value will have this type.
33543 * This function is currently implemented with a linear scan. If you
33544 * plan to do many lookups then #GVariantDict may be more efficient.
33546 * Returns: (transfer full): the value of the dictionary key, or %NULL
33552 * g_variant_n_children:
33553 * @value: a container #GVariant
33555 * Determines the number of children in a container #GVariant instance.
33556 * This includes variants, maybes, arrays, tuples and dictionary
33557 * entries. It is an error to call this function on any other type of
33560 * For variants, the return value is always 1. For values with maybe
33561 * types, it is always zero or one. For arrays, it is the length of the
33562 * array. For tuples it is the number of tuple items (which depends
33563 * only on the type). For dictionary entries, it is always 2
33565 * This function is O(1).
33567 * Returns: the number of children in the container
33573 * g_variant_new: (skip)
33574 * @format_string: a #GVariant format string
33575 * @...: arguments, as per @format_string
33577 * Creates a new #GVariant instance.
33579 * Think of this function as an analogue to g_strdup_printf().
33581 * The type of the created instance and the arguments that are expected
33582 * by this function are determined by @format_string. See the section on
33583 * [GVariant format strings][gvariant-format-strings]. Please note that
33584 * the syntax of the format string is very likely to be extended in the
33587 * The first character of the format string must not be '*' '?' '@' or
33588 * 'r'; in essence, a new #GVariant must always be constructed by this
33589 * function (and not merely passed through it unmodified).
33591 * Note that the arguments must be of the correct width for their types
33592 * specified in @format_string. This can be achieved by casting them. See
33593 * the [GVariant varargs documentation][gvariant-varargs].
33596 * MyFlags some_flags = FLAG_ONE | FLAG_TWO;
33597 * const gchar *some_strings[] = { "a", "b", "c", NULL };
33598 * GVariant *new_variant;
33600 * new_variant = g_variant_new ("(t^as)",
33601 * /<!-- -->* This cast is required. *<!-- -->/
33602 * (guint64) some_flags,
33606 * Returns: a new floating #GVariant instance
33612 * g_variant_new_array:
33613 * @child_type: (allow-none): the element type of the new array
33614 * @children: (allow-none) (array length=n_children): an array of
33615 * #GVariant pointers, the children
33616 * @n_children: the length of @children
33618 * Creates a new #GVariant array from @children.
33620 * @child_type must be non-%NULL if @n_children is zero. Otherwise, the
33621 * child type is determined by inspecting the first element of the
33622 * @children array. If @child_type is non-%NULL then it must be a
33625 * The items of the array are taken from the @children array. No entry
33626 * in the @children array may be %NULL.
33628 * All items in the array must have the same type, which must be the
33629 * same as @child_type, if given.
33631 * If the @children are floating references (see g_variant_ref_sink()), the
33632 * new instance takes ownership of them as if via g_variant_ref_sink().
33634 * Returns: (transfer none): a floating reference to a new #GVariant array
33640 * g_variant_new_boolean:
33641 * @value: a #gboolean value
33643 * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
33645 * Returns: (transfer none): a floating reference to a new boolean #GVariant instance
33651 * g_variant_new_byte:
33652 * @value: a #guint8 value
33654 * Creates a new byte #GVariant instance.
33656 * Returns: (transfer none): a floating reference to a new byte #GVariant instance
33662 * g_variant_new_bytestring:
33663 * @string: (array zero-terminated=1) (element-type guint8): a normal
33664 * nul-terminated string in no particular encoding
33666 * Creates an array-of-bytes #GVariant with the contents of @string.
33667 * This function is just like g_variant_new_string() except that the
33668 * string need not be valid utf8.
33670 * The nul terminator character at the end of the string is stored in
33673 * Returns: (transfer none): a floating reference to a new bytestring #GVariant instance
33679 * g_variant_new_bytestring_array:
33680 * @strv: (array length=length): an array of strings
33681 * @length: the length of @strv, or -1
33683 * Constructs an array of bytestring #GVariant from the given array of
33686 * If @length is -1 then @strv is %NULL-terminated.
33688 * Returns: (transfer none): a new floating #GVariant instance
33694 * g_variant_new_dict_entry: (constructor)
33695 * @key: a basic #GVariant, the key
33696 * @value: a #GVariant, the value
33698 * Creates a new dictionary entry #GVariant. @key and @value must be
33699 * non-%NULL. @key must be a value of a basic type (ie: not a container).
33701 * If the @key or @value are floating references (see g_variant_ref_sink()),
33702 * the new instance takes ownership of them as if via g_variant_ref_sink().
33704 * Returns: (transfer none): a floating reference to a new dictionary entry #GVariant
33710 * g_variant_new_double:
33711 * @value: a #gdouble floating point value
33713 * Creates a new double #GVariant instance.
33715 * Returns: (transfer none): a floating reference to a new double #GVariant instance
33721 * g_variant_new_fixed_array:
33722 * @element_type: the #GVariantType of each element
33723 * @elements: a pointer to the fixed array of contiguous elements
33724 * @n_elements: the number of elements
33725 * @element_size: the size of each element
33727 * Provides access to the serialised data for an array of fixed-sized
33730 * @value must be an array with fixed-sized elements. Numeric types are
33731 * fixed-size as are tuples containing only other fixed-sized types.
33733 * @element_size must be the size of a single element in the array.
33734 * For example, if calling this function for an array of 32-bit integers,
33735 * you might say sizeof(gint32). This value isn't used except for the purpose
33736 * of a double-check that the form of the serialised data matches the caller's
33739 * @n_elements, which must be non-%NULL is set equal to the number of
33740 * items in the array.
33742 * Returns: (transfer none): a floating reference to a new array #GVariant instance
33748 * g_variant_new_from_bytes:
33749 * @type: a #GVariantType
33750 * @bytes: a #GBytes
33751 * @trusted: if the contents of @bytes are trusted
33753 * Constructs a new serialised-mode #GVariant instance. This is the
33754 * inner interface for creation of new serialised values that gets
33755 * called from various functions in gvariant.c.
33757 * A reference is taken on @bytes.
33759 * Returns: (transfer none): a new #GVariant with a floating reference
33765 * g_variant_new_from_data:
33766 * @type: a definite #GVariantType
33767 * @data: (array length=size) (element-type guint8): the serialised data
33768 * @size: the size of @data
33769 * @trusted: %TRUE if @data is definitely in normal form
33770 * @notify: (scope async): function to call when @data is no longer needed
33771 * @user_data: data for @notify
33773 * Creates a new #GVariant instance from serialised data.
33775 * @type is the type of #GVariant instance that will be constructed.
33776 * The interpretation of @data depends on knowing the type.
33778 * @data is not modified by this function and must remain valid with an
33779 * unchanging value until such a time as @notify is called with
33780 * @user_data. If the contents of @data change before that time then
33781 * the result is undefined.
33783 * If @data is trusted to be serialised data in normal form then
33784 * @trusted should be %TRUE. This applies to serialised data created
33785 * within this process or read from a trusted location on the disk (such
33786 * as a file installed in /usr/lib alongside your application). You
33787 * should set trusted to %FALSE if @data is read from the network, a
33788 * file in the user's home directory, etc.
33790 * If @data was not stored in this machine's native endianness, any multi-byte
33791 * numeric values in the returned variant will also be in non-native
33792 * endianness. g_variant_byteswap() can be used to recover the original values.
33794 * @notify will be called with @user_data when @data is no longer
33795 * needed. The exact time of this call is unspecified and might even be
33796 * before this function returns.
33798 * Returns: (transfer none): a new floating #GVariant of type @type
33804 * g_variant_new_handle:
33805 * @value: a #gint32 value
33807 * Creates a new handle #GVariant instance.
33809 * By convention, handles are indexes into an array of file descriptors
33810 * that are sent alongside a D-Bus message. If you're not interacting
33811 * with D-Bus, you probably don't need them.
33813 * Returns: (transfer none): a floating reference to a new handle #GVariant instance
33819 * g_variant_new_int16:
33820 * @value: a #gint16 value
33822 * Creates a new int16 #GVariant instance.
33824 * Returns: (transfer none): a floating reference to a new int16 #GVariant instance
33830 * g_variant_new_int32:
33831 * @value: a #gint32 value
33833 * Creates a new int32 #GVariant instance.
33835 * Returns: (transfer none): a floating reference to a new int32 #GVariant instance
33841 * g_variant_new_int64:
33842 * @value: a #gint64 value
33844 * Creates a new int64 #GVariant instance.
33846 * Returns: (transfer none): a floating reference to a new int64 #GVariant instance
33852 * g_variant_new_maybe:
33853 * @child_type: (allow-none): the #GVariantType of the child, or %NULL
33854 * @child: (allow-none): the child value, or %NULL
33856 * Depending on if @child is %NULL, either wraps @child inside of a
33857 * maybe container or creates a Nothing instance for the given @type.
33859 * At least one of @child_type and @child must be non-%NULL.
33860 * If @child_type is non-%NULL then it must be a definite type.
33861 * If they are both non-%NULL then @child_type must be the type
33864 * If @child is a floating reference (see g_variant_ref_sink()), the new
33865 * instance takes ownership of @child.
33867 * Returns: (transfer none): a floating reference to a new #GVariant maybe instance
33873 * g_variant_new_object_path:
33874 * @object_path: a normal C nul-terminated string
33876 * Creates a D-Bus object path #GVariant with the contents of @string.
33877 * @string must be a valid D-Bus object path. Use
33878 * g_variant_is_object_path() if you're not sure.
33880 * Returns: (transfer none): a floating reference to a new object path #GVariant instance
33886 * g_variant_new_objv:
33887 * @strv: (array length=length) (element-type utf8): an array of strings
33888 * @length: the length of @strv, or -1
33890 * Constructs an array of object paths #GVariant from the given array of
33893 * Each string must be a valid #GVariant object path; see
33894 * g_variant_is_object_path().
33896 * If @length is -1 then @strv is %NULL-terminated.
33898 * Returns: (transfer none): a new floating #GVariant instance
33904 * g_variant_new_parsed:
33905 * @format: a text format #GVariant
33906 * @...: arguments as per @format
33908 * Parses @format and returns the result.
33910 * @format must be a text format #GVariant with one extension: at any
33911 * point that a value may appear in the text, a '%' character followed
33912 * by a GVariant format string (as per g_variant_new()) may appear. In
33913 * that case, the same arguments are collected from the argument list as
33914 * g_variant_new() would have collected.
33916 * Note that the arguments must be of the correct width for their types
33917 * specified in @format. This can be achieved by casting them. See
33918 * the [GVariant varargs documentation][gvariant-varargs].
33920 * Consider this simple example:
33921 * |[<!-- language="C" -->
33922 * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
33925 * In the example, the variable argument parameters are collected and
33926 * filled in as if they were part of the original string to produce the
33928 * |[<!-- language="C" -->
33929 * [('one', 1), ('two', 2), ('three', 3)]
33932 * This function is intended only to be used with @format as a string
33933 * literal. Any parse error is fatal to the calling process. If you
33934 * want to parse data from untrusted sources, use g_variant_parse().
33936 * You may not use this function to return, unmodified, a single
33937 * #GVariant pointer from the argument list. ie: @format may not solely
33938 * be anything along the lines of "%*", "%?", "\%r", or anything starting
33941 * Returns: a new floating #GVariant instance
33946 * g_variant_new_parsed_va:
33947 * @format: a text format #GVariant
33948 * @app: a pointer to a #va_list
33950 * Parses @format and returns the result.
33952 * This is the version of g_variant_new_parsed() intended to be used
33955 * The return value will be floating if it was a newly created GVariant
33956 * instance. In the case that @format simply specified the collection
33957 * of a #GVariant pointer (eg: @format was "%*") then the collected
33958 * #GVariant pointer will be returned unmodified, without adding any
33959 * additional references.
33961 * Note that the arguments in @app must be of the correct width for their types
33962 * specified in @format when collected into the #va_list. See
33963 * the [GVariant varargs documentation][gvariant-varargs].
33965 * In order to behave correctly in all cases it is necessary for the
33966 * calling function to g_variant_ref_sink() the return result before
33967 * returning control to the user that originally provided the pointer.
33968 * At this point, the caller will have their own full reference to the
33969 * result. This can also be done by adding the result to a container,
33970 * or by passing it to another g_variant_new() call.
33972 * Returns: a new, usually floating, #GVariant
33977 * g_variant_new_printf: (skip)
33978 * @format_string: a printf-style format string
33979 * @...: arguments for @format_string
33981 * Creates a string-type GVariant using printf formatting.
33983 * This is similar to calling g_strdup_printf() and then
33984 * g_variant_new_string() but it saves a temporary variable and an
33985 * unnecessary copy.
33987 * Returns: (transfer none): a floating reference to a new string
33988 * #GVariant instance
33994 * g_variant_new_signature:
33995 * @signature: a normal C nul-terminated string
33997 * Creates a D-Bus type signature #GVariant with the contents of
33998 * @string. @string must be a valid D-Bus type signature. Use
33999 * g_variant_is_signature() if you're not sure.
34001 * Returns: (transfer none): a floating reference to a new signature #GVariant instance
34007 * g_variant_new_string:
34008 * @string: a normal utf8 nul-terminated string
34010 * Creates a string #GVariant with the contents of @string.
34012 * @string must be valid utf8.
34014 * Returns: (transfer none): a floating reference to a new string #GVariant instance
34020 * g_variant_new_strv:
34021 * @strv: (array length=length) (element-type utf8): an array of strings
34022 * @length: the length of @strv, or -1
34024 * Constructs an array of strings #GVariant from the given array of
34027 * If @length is -1 then @strv is %NULL-terminated.
34029 * Returns: (transfer none): a new floating #GVariant instance
34035 * g_variant_new_take_string: (skip)
34036 * @string: a normal utf8 nul-terminated string
34038 * Creates a string #GVariant with the contents of @string.
34040 * @string must be valid utf8.
34042 * This function consumes @string. g_free() will be called on @string
34043 * when it is no longer required.
34045 * You must not modify or access @string in any other way after passing
34046 * it to this function. It is even possible that @string is immediately
34049 * Returns: (transfer none): a floating reference to a new string
34050 * #GVariant instance
34056 * g_variant_new_tuple:
34057 * @children: (array length=n_children): the items to make the tuple out of
34058 * @n_children: the length of @children
34060 * Creates a new tuple #GVariant out of the items in @children. The
34061 * type is determined from the types of @children. No entry in the
34062 * @children array may be %NULL.
34064 * If @n_children is 0 then the unit tuple is constructed.
34066 * If the @children are floating references (see g_variant_ref_sink()), the
34067 * new instance takes ownership of them as if via g_variant_ref_sink().
34069 * Returns: (transfer none): a floating reference to a new #GVariant tuple
34075 * g_variant_new_uint16:
34076 * @value: a #guint16 value
34078 * Creates a new uint16 #GVariant instance.
34080 * Returns: (transfer none): a floating reference to a new uint16 #GVariant instance
34086 * g_variant_new_uint32:
34087 * @value: a #guint32 value
34089 * Creates a new uint32 #GVariant instance.
34091 * Returns: (transfer none): a floating reference to a new uint32 #GVariant instance
34097 * g_variant_new_uint64:
34098 * @value: a #guint64 value
34100 * Creates a new uint64 #GVariant instance.
34102 * Returns: (transfer none): a floating reference to a new uint64 #GVariant instance
34108 * g_variant_new_va: (skip)
34109 * @format_string: a string that is prefixed with a format string
34110 * @endptr: (allow-none) (default NULL): location to store the end pointer,
34112 * @app: a pointer to a #va_list
34114 * This function is intended to be used by libraries based on
34115 * #GVariant that want to provide g_variant_new()-like functionality
34118 * The API is more general than g_variant_new() to allow a wider range
34119 * of possible uses.
34121 * @format_string must still point to a valid format string, but it only
34122 * needs to be nul-terminated if @endptr is %NULL. If @endptr is
34123 * non-%NULL then it is updated to point to the first character past the
34124 * end of the format string.
34126 * @app is a pointer to a #va_list. The arguments, according to
34127 * @format_string, are collected from this #va_list and the list is left
34128 * pointing to the argument following the last.
34130 * Note that the arguments in @app must be of the correct width for their
34131 * types specified in @format_string when collected into the #va_list.
34132 * See the [GVariant varargs documentation][gvariant-varargs.
34134 * These two generalisations allow mixing of multiple calls to
34135 * g_variant_new_va() and g_variant_get_va() within a single actual
34136 * varargs call by the user.
34138 * The return value will be floating if it was a newly created GVariant
34139 * instance (for example, if the format string was "(ii)"). In the case
34140 * that the format_string was '*', '?', 'r', or a format starting with
34141 * '@' then the collected #GVariant pointer will be returned unmodified,
34142 * without adding any additional references.
34144 * In order to behave correctly in all cases it is necessary for the
34145 * calling function to g_variant_ref_sink() the return result before
34146 * returning control to the user that originally provided the pointer.
34147 * At this point, the caller will have their own full reference to the
34148 * result. This can also be done by adding the result to a container,
34149 * or by passing it to another g_variant_new() call.
34151 * Returns: a new, usually floating, #GVariant
34157 * g_variant_new_variant: (constructor)
34158 * @value: a #GVariant instance
34160 * Boxes @value. The result is a #GVariant instance representing a
34161 * variant containing the original value.
34163 * If @child is a floating reference (see g_variant_ref_sink()), the new
34164 * instance takes ownership of @child.
34166 * Returns: (transfer none): a floating reference to a new variant #GVariant instance
34173 * @type: (allow-none): a #GVariantType, or %NULL
34174 * @text: a string containing a GVariant in text form
34175 * @limit: (allow-none): a pointer to the end of @text, or %NULL
34176 * @endptr: (allow-none): a location to store the end pointer, or %NULL
34177 * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
34179 * Parses a #GVariant from a text representation.
34181 * A single #GVariant is parsed from the content of @text.
34183 * The format is described [here][gvariant-text].
34185 * The memory at @limit will never be accessed and the parser behaves as
34186 * if the character at @limit is the nul terminator. This has the
34187 * effect of bounding @text.
34189 * If @endptr is non-%NULL then @text is permitted to contain data
34190 * following the value that this function parses and @endptr will be
34191 * updated to point to the first character past the end of the text
34192 * parsed by this function. If @endptr is %NULL and there is extra data
34193 * then an error is returned.
34195 * If @type is non-%NULL then the value will be parsed to have that
34196 * type. This may result in additional parse errors (in the case that
34197 * the parsed value doesn't fit the type) but may also result in fewer
34198 * errors (in the case that the type would have been ambiguous, such as
34199 * with empty arrays).
34201 * In the event that the parsing is successful, the resulting #GVariant
34204 * In case of any error, %NULL will be returned. If @error is non-%NULL
34205 * then it will be set to reflect the error that occurred.
34207 * Officially, the language understood by the parser is "any string
34208 * produced by g_variant_print()".
34210 * Returns: a reference to a #GVariant, or %NULL
34215 * g_variant_parse_error_print_context:
34216 * @error: a #GError from the #GVariantParseError domain
34217 * @source_str: the string that was given to the parser
34219 * Pretty-prints a message showing the context of a #GVariant parse
34220 * error within the string for which parsing was attempted.
34222 * The resulting string is suitable for output to the console or other
34223 * monospace media where newlines are treated in the usual way.
34225 * The message will typically look something like one of the following:
34228 * unterminated string constant:
34236 * unable to find a common type:
34241 * The format of the message may change in a future version.
34243 * @error must have come from a failed attempt to g_variant_parse() and
34244 * @source_str must be exactly the same string that caused the error.
34245 * If @source_str was not nul-terminated when you passed it to
34246 * g_variant_parse() then you must add nul termination before using this
34249 * Returns: (transfer full): the printed message
34255 * g_variant_parser_get_error_quark:
34257 * Deprecated: Use g_variant_parse_error_quark() instead.
34263 * @value: a #GVariant
34264 * @type_annotate: %TRUE if type information should be included in
34267 * Pretty-prints @value in the format understood by g_variant_parse().
34269 * The format is described [here][gvariant-text].
34271 * If @type_annotate is %TRUE, then type information is included in
34274 * Returns: (transfer full): a newly-allocated string holding the result.
34280 * g_variant_print_string: (skip)
34281 * @value: a #GVariant
34282 * @string: (allow-none) (default NULL): a #GString, or %NULL
34283 * @type_annotate: %TRUE if type information should be included in
34286 * Behaves as g_variant_print(), but operates on a #GString.
34288 * If @string is non-%NULL then it is appended to and returned. Else,
34289 * a new empty #GString is allocated and it is returned.
34291 * Returns: a #GString containing the string
34298 * @value: a #GVariant
34300 * Increases the reference count of @value.
34302 * Returns: the same @value
34308 * g_variant_ref_sink:
34309 * @value: a #GVariant
34311 * #GVariant uses a floating reference count system. All functions with
34312 * names starting with `g_variant_new_` return floating
34315 * Calling g_variant_ref_sink() on a #GVariant with a floating reference
34316 * will convert the floating reference into a full reference. Calling
34317 * g_variant_ref_sink() on a non-floating #GVariant results in an
34318 * additional normal reference being added.
34320 * In other words, if the @value is floating, then this call "assumes
34321 * ownership" of the floating reference, converting it to a normal
34322 * reference. If the @value is not floating, then this call adds a
34323 * new normal reference increasing the reference count by one.
34325 * All calls that result in a #GVariant instance being inserted into a
34326 * container will call g_variant_ref_sink() on the instance. This means
34327 * that if the value was just created (and has only its floating
34328 * reference) then the container will assume sole ownership of the value
34329 * at that point and the caller will not need to unreference it. This
34330 * makes certain common styles of programming much easier while still
34331 * maintaining normal refcounting semantics in situations where values
34332 * are not floating.
34334 * Returns: the same @value
34341 * @value: the #GVariant to store
34342 * @data: the location to store the serialised data at
34344 * Stores the serialised form of @value at @data. @data should be
34345 * large enough. See g_variant_get_size().
34347 * The stored data is in machine native byte order but may not be in
34348 * fully-normalised form if read from an untrusted source. See
34349 * g_variant_get_normal_form() for a solution.
34351 * As with g_variant_get_data(), to be able to deserialise the
34352 * serialised variant successfully, its type and (if the destination
34353 * machine might be different) its endianness must also be available.
34355 * This function is approximately O(n) in the size of @data.
34362 * g_variant_take_ref:
34363 * @value: a #GVariant
34365 * If @value is floating, sink it. Otherwise, do nothing.
34367 * Typically you want to use g_variant_ref_sink() in order to
34368 * automatically do the correct thing with respect to floating or
34369 * non-floating references, but there is one specific scenario where
34370 * this function is helpful.
34372 * The situation where this function is helpful is when creating an API
34373 * that allows the user to provide a callback function that returns a
34374 * #GVariant. We certainly want to allow the user the flexibility to
34375 * return a non-floating reference from this callback (for the case
34376 * where the value that is being returned already exists).
34378 * At the same time, the style of the #GVariant API makes it likely that
34379 * for newly-created #GVariant instances, the user can be saved some
34380 * typing if they are allowed to return a #GVariant with a floating
34383 * Using this function on the return value of the user's callback allows
34384 * the user to do whichever is more convenient for them. The caller
34385 * will alway receives exactly one full reference to the value: either
34386 * the one that was returned in the first place, or a floating reference
34387 * that has been converted to a full reference.
34389 * This function has an odd interaction when combined with
34390 * g_variant_ref_sink() running at the same time in another thread on
34391 * the same #GVariant instance. If g_variant_ref_sink() runs first then
34392 * the result will be that the floating reference is converted to a hard
34393 * reference. If g_variant_take_ref() runs first then the result will
34394 * be that the floating reference is converted to a hard reference and
34395 * an additional reference on top of that one is added. It is best to
34396 * avoid this situation.
34398 * Returns: the same @value
34403 * g_variant_type_copy:
34404 * @type: a #GVariantType
34406 * Makes a copy of a #GVariantType. It is appropriate to call
34407 * g_variant_type_free() on the return value. @type may not be %NULL.
34409 * Returns: (transfer full): a new #GVariantType
34416 * g_variant_type_dup_string:
34417 * @type: a #GVariantType
34419 * Returns a newly-allocated copy of the type string corresponding to
34420 * @type. The returned string is nul-terminated. It is appropriate to
34421 * call g_free() on the return value.
34423 * Returns: (transfer full): the corresponding type string
34430 * g_variant_type_element:
34431 * @type: an array or maybe #GVariantType
34433 * Determines the element type of an array or maybe type.
34435 * This function may only be used with array or maybe types.
34437 * Returns: (transfer none): the element type of @type
34444 * g_variant_type_equal:
34445 * @type1: (type GVariantType): a #GVariantType
34446 * @type2: (type GVariantType): a #GVariantType
34448 * Compares @type1 and @type2 for equality.
34450 * Only returns %TRUE if the types are exactly equal. Even if one type
34451 * is an indefinite type and the other is a subtype of it, %FALSE will
34452 * be returned if they are not exactly equal. If you want to check for
34453 * subtypes, use g_variant_type_is_subtype_of().
34455 * The argument types of @type1 and @type2 are only #gconstpointer to
34456 * allow use with #GHashTable without function pointer casting. For
34457 * both arguments, a valid #GVariantType must be provided.
34459 * Returns: %TRUE if @type1 and @type2 are exactly equal
34466 * g_variant_type_first:
34467 * @type: a tuple or dictionary entry #GVariantType
34469 * Determines the first item type of a tuple or dictionary entry
34472 * This function may only be used with tuple or dictionary entry types,
34473 * but must not be used with the generic tuple type
34474 * %G_VARIANT_TYPE_TUPLE.
34476 * In the case of a dictionary entry type, this returns the type of
34479 * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
34481 * This call, together with g_variant_type_next() provides an iterator
34482 * interface over tuple and dictionary entry types.
34484 * Returns: (transfer none): the first item type of @type, or %NULL
34491 * g_variant_type_free:
34492 * @type: (allow-none): a #GVariantType, or %NULL
34494 * Frees a #GVariantType that was allocated with
34495 * g_variant_type_copy(), g_variant_type_new() or one of the container
34496 * type constructor functions.
34498 * In the case that @type is %NULL, this function does nothing.
34505 * g_variant_type_get_string_length:
34506 * @type: a #GVariantType
34508 * Returns the length of the type string corresponding to the given
34509 * @type. This function must be used to determine the valid extent of
34510 * the memory region returned by g_variant_type_peek_string().
34512 * Returns: the length of the corresponding type string
34519 * g_variant_type_hash:
34520 * @type: (type GVariantType): a #GVariantType
34524 * The argument type of @type is only #gconstpointer to allow use with
34525 * #GHashTable without function pointer casting. A valid
34526 * #GVariantType must be provided.
34528 * Returns: the hash value
34535 * g_variant_type_is_array:
34536 * @type: a #GVariantType
34538 * Determines if the given @type is an array type. This is true if the
34539 * type string for @type starts with an 'a'.
34541 * This function returns %TRUE for any indefinite type for which every
34542 * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
34545 * Returns: %TRUE if @type is an array type
34552 * g_variant_type_is_basic:
34553 * @type: a #GVariantType
34555 * Determines if the given @type is a basic type.
34557 * Basic types are booleans, bytes, integers, doubles, strings, object
34558 * paths and signatures.
34560 * Only a basic type may be used as the key of a dictionary entry.
34562 * This function returns %FALSE for all indefinite types except
34563 * %G_VARIANT_TYPE_BASIC.
34565 * Returns: %TRUE if @type is a basic type
34572 * g_variant_type_is_container:
34573 * @type: a #GVariantType
34575 * Determines if the given @type is a container type.
34577 * Container types are any array, maybe, tuple, or dictionary
34578 * entry types plus the variant type.
34580 * This function returns %TRUE for any indefinite type for which every
34581 * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
34584 * Returns: %TRUE if @type is a container type
34591 * g_variant_type_is_definite:
34592 * @type: a #GVariantType
34594 * Determines if the given @type is definite (ie: not indefinite).
34596 * A type is definite if its type string does not contain any indefinite
34597 * type characters ('*', '?', or 'r').
34599 * A #GVariant instance may not have an indefinite type, so calling
34600 * this function on the result of g_variant_get_type() will always
34601 * result in %TRUE being returned. Calling this function on an
34602 * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
34603 * %FALSE being returned.
34605 * Returns: %TRUE if @type is definite
34612 * g_variant_type_is_dict_entry:
34613 * @type: a #GVariantType
34615 * Determines if the given @type is a dictionary entry type. This is
34616 * true if the type string for @type starts with a '{'.
34618 * This function returns %TRUE for any indefinite type for which every
34619 * definite subtype is a dictionary entry type --
34620 * %G_VARIANT_TYPE_DICT_ENTRY, for example.
34622 * Returns: %TRUE if @type is a dictionary entry type
34629 * g_variant_type_is_maybe:
34630 * @type: a #GVariantType
34632 * Determines if the given @type is a maybe type. This is true if the
34633 * type string for @type starts with an 'm'.
34635 * This function returns %TRUE for any indefinite type for which every
34636 * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
34639 * Returns: %TRUE if @type is a maybe type
34646 * g_variant_type_is_subtype_of:
34647 * @type: a #GVariantType
34648 * @supertype: a #GVariantType
34650 * Checks if @type is a subtype of @supertype.
34652 * This function returns %TRUE if @type is a subtype of @supertype. All
34653 * types are considered to be subtypes of themselves. Aside from that,
34654 * only indefinite types can have subtypes.
34656 * Returns: %TRUE if @type is a subtype of @supertype
34663 * g_variant_type_is_tuple:
34664 * @type: a #GVariantType
34666 * Determines if the given @type is a tuple type. This is true if the
34667 * type string for @type starts with a '(' or if @type is
34668 * %G_VARIANT_TYPE_TUPLE.
34670 * This function returns %TRUE for any indefinite type for which every
34671 * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
34674 * Returns: %TRUE if @type is a tuple type
34681 * g_variant_type_is_variant:
34682 * @type: a #GVariantType
34684 * Determines if the given @type is the variant type.
34686 * Returns: %TRUE if @type is the variant type
34693 * g_variant_type_key:
34694 * @type: a dictionary entry #GVariantType
34696 * Determines the key type of a dictionary entry type.
34698 * This function may only be used with a dictionary entry type. Other
34699 * than the additional restriction, this call is equivalent to
34700 * g_variant_type_first().
34702 * Returns: (transfer none): the key type of the dictionary entry
34709 * g_variant_type_n_items:
34710 * @type: a tuple or dictionary entry #GVariantType
34712 * Determines the number of items contained in a tuple or
34713 * dictionary entry type.
34715 * This function may only be used with tuple or dictionary entry types,
34716 * but must not be used with the generic tuple type
34717 * %G_VARIANT_TYPE_TUPLE.
34719 * In the case of a dictionary entry type, this function will always
34722 * Returns: the number of items in @type
34729 * g_variant_type_new:
34730 * @type_string: a valid GVariant type string
34732 * Creates a new #GVariantType corresponding to the type string given
34733 * by @type_string. It is appropriate to call g_variant_type_free() on
34734 * the return value.
34736 * It is a programmer error to call this function with an invalid type
34737 * string. Use g_variant_type_string_is_valid() if you are unsure.
34739 * Returns: (transfer full): a new #GVariantType
34745 * g_variant_type_new_array: (constructor)
34746 * @element: a #GVariantType
34748 * Constructs the type corresponding to an array of elements of the
34751 * It is appropriate to call g_variant_type_free() on the return value.
34753 * Returns: (transfer full): a new array #GVariantType
34760 * g_variant_type_new_dict_entry: (constructor)
34761 * @key: a basic #GVariantType
34762 * @value: a #GVariantType
34764 * Constructs the type corresponding to a dictionary entry with a key
34765 * of type @key and a value of type @value.
34767 * It is appropriate to call g_variant_type_free() on the return value.
34769 * Returns: (transfer full): a new dictionary entry #GVariantType
34776 * g_variant_type_new_maybe: (constructor)
34777 * @element: a #GVariantType
34779 * Constructs the type corresponding to a maybe instance containing
34780 * type @type or Nothing.
34782 * It is appropriate to call g_variant_type_free() on the return value.
34784 * Returns: (transfer full): a new maybe #GVariantType
34791 * g_variant_type_new_tuple:
34792 * @items: (array length=length): an array of #GVariantTypes, one for each item
34793 * @length: the length of @items, or -1
34795 * Constructs a new tuple type, from @items.
34797 * @length is the number of items in @items, or -1 to indicate that
34798 * @items is %NULL-terminated.
34800 * It is appropriate to call g_variant_type_free() on the return value.
34802 * Returns: (transfer full): a new tuple #GVariantType
34809 * g_variant_type_next:
34810 * @type: a #GVariantType from a previous call
34812 * Determines the next item type of a tuple or dictionary entry
34815 * @type must be the result of a previous call to
34816 * g_variant_type_first() or g_variant_type_next().
34818 * If called on the key type of a dictionary entry then this call
34819 * returns the value type. If called on the value type of a dictionary
34820 * entry then this call returns %NULL.
34822 * For tuples, %NULL is returned when @type is the last item in a tuple.
34824 * Returns: (transfer none): the next #GVariantType after @type, or %NULL
34831 * g_variant_type_peek_string: (skip)
34832 * @type: a #GVariantType
34834 * Returns the type string corresponding to the given @type. The
34835 * result is not nul-terminated; in order to determine its length you
34836 * must call g_variant_type_get_string_length().
34838 * To get a nul-terminated string, see g_variant_type_dup_string().
34840 * Returns: the corresponding type string (not nul-terminated)
34847 * g_variant_type_string_is_valid:
34848 * @type_string: a pointer to any string
34850 * Checks if @type_string is a valid GVariant type string. This call is
34851 * equivalent to calling g_variant_type_string_scan() and confirming
34852 * that the following character is a nul terminator.
34854 * Returns: %TRUE if @type_string is exactly one valid type string
34861 * g_variant_type_string_scan:
34862 * @string: a pointer to any string
34863 * @limit: (allow-none): the end of @string, or %NULL
34864 * @endptr: (out) (allow-none): location to store the end pointer, or %NULL
34866 * Scan for a single complete and valid GVariant type string in @string.
34867 * The memory pointed to by @limit (or bytes beyond it) is never
34870 * If a valid type string is found, @endptr is updated to point to the
34871 * first character past the end of the string that was found and %TRUE
34874 * If there is no valid type string starting at @string, or if the type
34875 * string does not end before @limit then %FALSE is returned.
34877 * For the simple case of checking if a string is a valid type string,
34878 * see g_variant_type_string_is_valid().
34880 * Returns: %TRUE if a valid type string was found
34886 * g_variant_type_value:
34887 * @type: a dictionary entry #GVariantType
34889 * Determines the value type of a dictionary entry type.
34891 * This function may only be used with a dictionary entry type.
34893 * Returns: (transfer none): the value type of the dictionary entry
34901 * @value: a #GVariant
34903 * Decreases the reference count of @value. When its reference count
34904 * drops to 0, the memory used by the variant is freed.
34912 * @string: the return location for the newly-allocated string.
34913 * @format: a standard printf() format string, but notice
34914 * [string precision pitfalls][string-precision]
34915 * @args: the list of arguments to insert in the output.
34917 * An implementation of the GNU vasprintf() function which supports
34918 * positional parameters, as specified in the Single Unix Specification.
34919 * This function is similar to g_vsprintf(), except that it allocates a
34920 * string to hold the output, instead of putting the output in a buffer
34921 * you allocate in advance.
34923 * Returns: the number of bytes printed.
34930 * @file: the stream to write to.
34931 * @format: a standard printf() format string, but notice
34932 * [string precision pitfalls][string-precision]
34933 * @args: the list of arguments to insert in the output.
34935 * An implementation of the standard fprintf() function which supports
34936 * positional parameters, as specified in the Single Unix Specification.
34938 * Returns: the number of bytes printed.
34945 * @format: a standard printf() format string, but notice
34946 * [string precision pitfalls][string-precision]
34947 * @args: the list of arguments to insert in the output.
34949 * An implementation of the standard vprintf() function which supports
34950 * positional parameters, as specified in the Single Unix Specification.
34952 * Returns: the number of bytes printed.
34959 * @string: the buffer to hold the output.
34960 * @n: the maximum number of bytes to produce (including the
34961 * terminating nul character).
34962 * @format: a standard printf() format string, but notice
34963 * string precision pitfalls][string-precision]
34964 * @args: the list of arguments to insert in the output.
34966 * A safer form of the standard vsprintf() function. The output is guaranteed
34967 * to not exceed @n characters (including the terminating nul character), so
34968 * it is easy to ensure that a buffer overflow cannot occur.
34970 * See also g_strdup_vprintf().
34972 * In versions of GLib prior to 1.2.3, this function may return -1 if the
34973 * output was truncated, and the truncated string may not be nul-terminated.
34974 * In versions prior to 1.3.12, this function returns the length of the output
34977 * The return value of g_vsnprintf() conforms to the vsnprintf() function
34978 * as standardized in ISO C99. Note that this is different from traditional
34979 * vsnprintf(), which returns the length of the output string.
34981 * The format string may contain positional parameters, as specified in
34982 * the Single Unix Specification.
34984 * Returns: the number of bytes which would be produced if the buffer
34985 * was large enough.
34991 * @string: the buffer to hold the output.
34992 * @format: a standard printf() format string, but notice
34993 * [string precision pitfalls][string-precision]
34994 * @args: the list of arguments to insert in the output.
34996 * An implementation of the standard vsprintf() function which supports
34997 * positional parameters, as specified in the Single Unix Specification.
34999 * Returns: the number of bytes printed.
35005 * g_wakeup_acknowledge:
35006 * @wakeup: a #GWakeup
35008 * Acknowledges receipt of a wakeup signal on @wakeup.
35010 * You must call this after @wakeup polls as ready. If not, it will
35011 * continue to poll as ready until you do so.
35013 * If you call this function and @wakeup is not signaled, nothing
35022 * @wakeup: a #GWakeup
35026 * You must not currently be polling on the #GPollFD returned by
35027 * g_wakeup_get_pollfd(), or the result is undefined.
35032 * g_wakeup_get_pollfd:
35033 * @wakeup: a #GWakeup
35034 * @poll_fd: a #GPollFD
35036 * Prepares a @poll_fd such that polling on it will succeed when
35037 * g_wakeup_signal() has been called on @wakeup.
35039 * @poll_fd is valid until @wakeup is freed.
35048 * Creates a new #GWakeup.
35050 * You should use g_wakeup_free() to free it when you are done.
35052 * Returns: a new #GWakeup
35059 * @wakeup: a #GWakeup
35063 * Any future (or present) polling on the #GPollFD returned by
35064 * g_wakeup_get_pollfd() will immediately succeed until such a time as
35065 * g_wakeup_acknowledge() is called.
35067 * This function is safe to call from a UNIX signal handler.
35075 * @...: format string, followed by parameters to insert
35076 * into the format string (as with printf())
35078 * A convenience function/macro to log a warning message.
35080 * You can make warnings fatal at runtime by setting the `G_DEBUG`
35081 * environment variable (see
35082 * [Running GLib Applications](glib-running.html)).
35084 * If g_log_default_handler() is used as the log handler function,
35085 * a newline character will automatically be appended to @..., and
35086 * need not be entered manually.
35091 * g_win32_error_message:
35092 * @error: error code.
35094 * Translate a Win32 error code (as returned by GetLastError()) into
35095 * the corresponding message. The message is either language neutral,
35096 * or in the thread's language, or the user's language, the system's
35097 * language, or US English (see docs for FormatMessage()). The
35098 * returned string is in UTF-8. It should be deallocated with
35101 * Returns: newly-allocated error message
35106 * g_win32_get_command_line:
35108 * Gets the command line arguments, on Windows, in the GLib filename
35109 * encoding (ie: UTF-8).
35111 * Normally, on Windows, the command line arguments are passed to main()
35112 * in the system codepage encoding. This prevents passing filenames as
35113 * arguments if the filenames contain characters that fall outside of
35114 * this codepage. If such filenames are passed, then substitutions
35115 * will occur (such as replacing some characters with '?').
35117 * GLib's policy of using UTF-8 as a filename encoding on Windows was
35118 * designed to localise the pain of dealing with filenames outside of
35119 * the system codepage to one area: dealing with commandline arguments
35122 * As such, most GLib programs should ignore the value of argv passed to
35123 * their main() function and call g_win32_get_command_line() instead.
35124 * This will get the "full Unicode" commandline arguments using
35125 * GetCommandLineW() and convert it to the GLib filename encoding (which
35126 * is UTF-8 on Windows).
35128 * The strings returned by this function are suitable for use with
35129 * functions such as g_open() and g_file_new_for_commandline_arg() but
35130 * are not suitable for use with g_option_context_parse(), which assumes
35131 * that its input will be in the system codepage. The return value is
35132 * suitable for use with g_option_context_parse_strv(), however, which
35133 * is a better match anyway because it won't leak memory.
35135 * Unlike argv, the returned value is a normal strv and can (and should)
35136 * be freed with g_strfreev() when no longer needed.
35138 * Returns: (transfer full): the commandline arguments in the GLib
35139 * filename encoding (ie: UTF-8)
35145 * g_win32_get_package_installation_directory:
35146 * @package: (allow-none): You should pass %NULL for this.
35147 * @dll_name: (allow-none): The name of a DLL that a package provides in UTF-8, or %NULL.
35149 * Try to determine the installation directory for a software package.
35151 * This function is deprecated. Use
35152 * g_win32_get_package_installation_directory_of_module() instead.
35154 * The use of @package is deprecated. You should always pass %NULL. A
35155 * warning is printed if non-NULL is passed as @package.
35157 * The original intended use of @package was for a short identifier of
35158 * the package, typically the same identifier as used for
35159 * `GETTEXT_PACKAGE` in software configured using GNU
35160 * autotools. The function first looks in the Windows Registry for the
35161 * value `#InstallationDirectory` in the key
35162 * `#HKLM\Software\@package`, and if that value
35163 * exists and is a string, returns that.
35165 * It is strongly recommended that packagers of GLib-using libraries
35166 * for Windows do not store installation paths in the Registry to be
35167 * used by this function as that interfers with having several
35168 * parallel installations of the library. Enabling multiple
35169 * installations of different versions of some GLib-using library, or
35170 * GLib itself, is desirable for various reasons.
35172 * For this reason it is recommeded to always pass %NULL as
35173 * @package to this function, to avoid the temptation to use the
35174 * Registry. In version 2.20 of GLib the @package parameter
35175 * will be ignored and this function won't look in the Registry at all.
35177 * If @package is %NULL, or the above value isn't found in the
35178 * Registry, but @dll_name is non-%NULL, it should name a DLL loaded
35179 * into the current process. Typically that would be the name of the
35180 * DLL calling this function, looking for its installation
35181 * directory. The function then asks Windows what directory that DLL
35182 * was loaded from. If that directory's last component is "bin" or
35183 * "lib", the parent directory is returned, otherwise the directory
35184 * itself. If that DLL isn't loaded, the function proceeds as if
35185 * @dll_name was %NULL.
35187 * If both @package and @dll_name are %NULL, the directory from where
35188 * the main executable of the process was loaded is used instead in
35189 * the same way as above.
35191 * Returns: a string containing the installation directory for
35192 * @package. The string is in the GLib file name encoding,
35193 * i.e. UTF-8. The return value should be freed with g_free() when not
35194 * needed any longer. If the function fails %NULL is returned.
35195 * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to
35196 * g_win32_get_package_installation_directory_of_module() instead.
35201 * g_win32_get_package_installation_directory_of_module:
35202 * @hmodule: (allow-none): The Win32 handle for a DLL loaded into the current process, or %NULL
35204 * This function tries to determine the installation directory of a
35205 * software package based on the location of a DLL of the software
35208 * @hmodule should be the handle of a loaded DLL or %NULL. The
35209 * function looks up the directory that DLL was loaded from. If
35210 * @hmodule is NULL, the directory the main executable of the current
35211 * process is looked up. If that directory's last component is "bin"
35212 * or "lib", its parent directory is returned, otherwise the directory
35215 * It thus makes sense to pass only the handle to a "public" DLL of a
35216 * software package to this function, as such DLLs typically are known
35217 * to be installed in a "bin" or occasionally "lib" subfolder of the
35218 * installation folder. DLLs that are of the dynamically loaded module
35219 * or plugin variety are often located in more private locations
35220 * deeper down in the tree, from which it is impossible for GLib to
35221 * deduce the root of the package installation.
35223 * The typical use case for this function is to have a DllMain() that
35224 * saves the handle for the DLL. Then when code in the DLL needs to
35225 * construct names of files in the installation tree it calls this
35226 * function passing the DLL handle.
35228 * Returns: a string containing the guessed installation directory for
35229 * the software package @hmodule is from. The string is in the GLib
35230 * file name encoding, i.e. UTF-8. The return value should be freed
35231 * with g_free() when not needed any longer. If the function fails
35232 * %NULL is returned.
35238 * g_win32_get_package_installation_subdirectory:
35239 * @package: (allow-none): You should pass %NULL for this.
35240 * @dll_name: (allow-none): The name of a DLL that a package provides, in UTF-8, or %NULL.
35241 * @subdir: A subdirectory of the package installation directory, also in UTF-8
35243 * This function is deprecated. Use
35244 * g_win32_get_package_installation_directory_of_module() and
35245 * g_build_filename() instead.
35247 * Returns a newly-allocated string containing the path of the
35248 * subdirectory @subdir in the return value from calling
35249 * g_win32_get_package_installation_directory() with the @package and
35250 * @dll_name parameters. See the documentation for
35251 * g_win32_get_package_installation_directory() for more details. In
35252 * particular, note that it is deprecated to pass anything except NULL
35255 * Returns: a string containing the complete path to @subdir inside
35256 * the installation directory of @package. The returned string is in
35257 * the GLib file name encoding, i.e. UTF-8. The return value should be
35258 * freed with g_free() when no longer needed. If something goes wrong,
35259 * %NULL is returned.
35260 * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to
35261 * g_win32_get_package_installation_directory_of_module() instead, and
35262 * then construct a subdirectory pathname with g_build_filename().
35267 * g_win32_get_windows_version:
35269 * Returns version information for the Windows operating system the
35270 * code is running on. See MSDN documentation for the GetVersion()
35271 * function. To summarize, the most significant bit is one on Win9x,
35272 * and zero on NT-based systems. Since version 2.14, GLib works only
35273 * on NT-based systems, so checking whether your are running on Win9x
35274 * in your own software is moot. The least significant byte is 4 on
35275 * Windows NT 4, and 5 on Windows XP. Software that needs really
35276 * detailed version and feature information should use Win32 API like
35277 * GetVersionEx() and VerifyVersionInfo().
35279 * Returns: The version information.
35285 * g_win32_getlocale:
35287 * The setlocale() function in the Microsoft C library uses locale
35288 * names of the form "English_United States.1252" etc. We want the
35289 * UNIXish standard form "en_US", "zh_TW" etc. This function gets the
35290 * current thread locale from Windows - without any encoding info -
35291 * and returns it as a string of the above form for use in forming
35292 * file names etc. The returned string should be deallocated with
35295 * Returns: newly-allocated locale name.
35300 * g_win32_locale_filename_from_utf8:
35301 * @utf8filename: a UTF-8 encoded filename.
35303 * Converts a filename from UTF-8 to the system codepage.
35305 * On NT-based Windows, on NTFS file systems, file names are in
35306 * Unicode. It is quite possible that Unicode file names contain
35307 * characters not representable in the system codepage. (For instance,
35308 * Greek or Cyrillic characters on Western European or US Windows
35309 * installations, or various less common CJK characters on CJK Windows
35312 * In such a case, and if the filename refers to an existing file, and
35313 * the file system stores alternate short (8.3) names for directory
35314 * entries, the short form of the filename is returned. Note that the
35315 * "short" name might in fact be longer than the Unicode name if the
35316 * Unicode name has very short pathname components containing
35317 * non-ASCII characters. If no system codepage name for the file is
35318 * possible, %NULL is returned.
35320 * The return value is dynamically allocated and should be freed with
35321 * g_free() when no longer needed.
35323 * Returns: The converted filename, or %NULL on conversion
35324 * failure and lack of short names.
35332 * A standard boolean type.
35333 * Variables of this type should only contain the value
35341 * Corresponds to the standard C char type.
35348 * An untyped pointer to constant data.
35349 * The data pointed to should not be changed.
35351 * This is typically used in function prototypes to indicate
35352 * that the data pointed to will not be altered by the function.
35359 * Corresponds to the standard C double type.
35360 * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
35367 * Corresponds to the standard C float type.
35368 * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
35375 * Corresponds to the standard C int type.
35376 * Values of this type can range from #G_MININT to #G_MAXINT.
35383 * A signed integer guaranteed to be 16 bits on all platforms.
35384 * Values of this type can range from #G_MININT16 (= -32,768) to
35385 * #G_MAXINT16 (= 32,767).
35387 * To print or scan values of this type, use
35388 * %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT.
35395 * A signed integer guaranteed to be 32 bits on all platforms.
35396 * Values of this type can range from #G_MININT32 (= -2,147,483,648)
35397 * to #G_MAXINT32 (= 2,147,483,647).
35399 * To print or scan values of this type, use
35400 * %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
35407 * A signed integer guaranteed to be 64 bits on all platforms.
35408 * Values of this type can range from #G_MININT64
35409 * (= -9,223,372,036,854,775,808) to #G_MAXINT64
35410 * (= 9,223,372,036,854,775,807).
35412 * To print or scan values of this type, use
35413 * %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
35420 * A signed integer guaranteed to be 8 bits on all platforms.
35421 * Values of this type can range from #G_MININT8 (= -128) to
35422 * #G_MAXINT8 (= 127).
35429 * Corresponds to the C99 type intptr_t,
35430 * a signed integer type that can hold any pointer.
35432 * To print or scan values of this type, use
35433 * %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
35441 * @arg: Do not use this argument
35443 * Do not call this function; it is used to share private
35444 * API between glib, gobject, and gio.
35449 * glib_check_version:
35450 * @required_major: the required major version
35451 * @required_minor: the required minor version
35452 * @required_micro: the required micro version
35454 * Checks that the GLib library in use is compatible with the
35455 * given version. Generally you would pass in the constants
35456 * #GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION
35457 * as the three arguments to this function; that produces
35458 * a check that the library in use is compatible with
35459 * the version of GLib the application or module was compiled
35462 * Compatibility is defined by two things: first the version
35463 * of the running library is newer than the version
35464 * @required_major.required_minor.@required_micro. Second
35465 * the running library must be binary compatible with the
35466 * version @required_major.required_minor.@required_micro
35467 * (same major version.)
35469 * Returns: %NULL if the GLib library is compatible with the
35470 * given version, or a string describing the version mismatch.
35471 * The returned string is owned by GLib and must not be modified
35479 * @str: The string to be translated
35481 * Returns the translated string from the glib translations.
35482 * This is an internal function and should only be used by
35483 * the internals of glib (such as libgio).
35485 * Returns: the transation of @str to the current locale
35490 * glib_mem_profiler_table:
35492 * A #GMemVTable containing profiling variants of the memory
35493 * allocation functions. Use them together with g_mem_profile()
35494 * in order to get information about the memory allocation pattern
35501 * @msgctxtid: a combined message context and message id, separated
35502 * by a \004 character
35503 * @msgidoffset: the offset of the message id in @msgctxid
35505 * This function is a variant of glib_gettext() which supports
35506 * a disambiguating message context. See g_dpgettext() for full
35509 * This is an internal function and should only be used by
35510 * the internals of glib (such as libgio).
35512 * Returns: the translation of @str to the current locale
35519 * Corresponds to the standard C long type.
35520 * Values of this type can range from #G_MINLONG to #G_MAXLONG.
35527 * A signed integer type that is used for file offsets,
35528 * corresponding to the C99 type off64_t.
35529 * Values of this type can range from #G_MINOFFSET to
35532 * To print or scan values of this type, use
35533 * %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
35542 * An untyped pointer.
35543 * #gpointer looks better and is easier to use than void*.
35550 * Corresponds to the standard C short type.
35551 * Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
35558 * An unsigned integer type of the result of the sizeof operator,
35559 * corresponding to the size_t type defined in C99.
35560 * This type is wide enough to hold the numeric value of a pointer,
35561 * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide
35562 * on a 64-bit platform. Values of this type can range from 0 to
35565 * To print or scan values of this type, use
35566 * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT.
35573 * A signed variant of #gsize, corresponding to the
35574 * ssize_t defined on most platforms.
35575 * Values of this type can range from #G_MINSSIZE
35578 * To print or scan values of this type, use
35579 * %G_GSIZE_MODIFIER and/or %G_GSSIZE_FORMAT.
35586 * Corresponds to the standard C unsigned char type.
35593 * Corresponds to the standard C unsigned int type.
35594 * Values of this type can range from 0 to #G_MAXUINT.
35601 * An unsigned integer guaranteed to be 16 bits on all platforms.
35602 * Values of this type can range from 0 to #G_MAXUINT16 (= 65,535).
35604 * To print or scan values of this type, use
35605 * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
35612 * An unsigned integer guaranteed to be 32 bits on all platforms.
35613 * Values of this type can range from 0 to #G_MAXUINT32 (= 4,294,967,295).
35615 * To print or scan values of this type, use
35616 * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
35623 * An unsigned integer guaranteed to be 64-bits on all platforms.
35624 * Values of this type can range from 0 to #G_MAXUINT64
35625 * (= 18,446,744,073,709,551,615).
35627 * To print or scan values of this type, use
35628 * %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
35635 * An unsigned integer guaranteed to be 8 bits on all platforms.
35636 * Values of this type can range from 0 to #G_MAXUINT8 (= 255).
35643 * Corresponds to the C99 type uintptr_t,
35644 * an unsigned integer type that can hold any pointer.
35646 * To print or scan values of this type, use
35647 * %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
35656 * Corresponds to the standard C unsigned long type.
35657 * Values of this type can range from 0 to #G_MAXULONG.
35664 * Corresponds to the standard C unsigned short type.
35665 * Values of this type can range from 0 to #G_MAXUSHORT.
35670 /************************************************************/
35671 /* THIS FILE IS GENERATED DO NOT EDIT */
35672 /************************************************************/