/************************************************************/ /* THIS FILE IS GENERATED DO NOT EDIT */ /************************************************************/ /** * ABS: * @a: a numeric value * * Calculates the absolute value of @a. * The absolute value is simply the number with any negative sign taken away. * * For example, * - ABS(-10) is 10. * - ABS(10) is also 10. * * Returns: the absolute value of @a. */ /** * CLAMP: * @x: the value to clamp * @low: the minimum value allowed * @high: the maximum value allowed * * Ensures that @x is between the limits set by @low and @high. If @low is * greater than @high the result is undefined. * * For example, * - CLAMP(5, 10, 15) is 10. * - CLAMP(15, 5, 10) is 10. * - CLAMP(20, 15, 25) is 20. * * Returns: the value of @x clamped to the range between @low and @high */ /** * C_: * @Context: a message context, must be a string literal * @String: a message id, must be a string literal * * Uses gettext to get the translation for @String. @Context is * used as a context. This is mainly useful for short strings which * may need different translations, depending on the context in which * they are used. * |[ * label1 = C_("Navigation", "Back"); * label2 = C_("Body part", "Back"); * ]| * * If you are using the C_() macro, you need to make sure that you pass * `--keyword=C_:1c,2` to xgettext when extracting messages. * Note that this only works with GNU gettext >= 0.15. * * Returns: the translated message * Since: 2.16 */ /** * FALSE: * * Defines the %FALSE value for the #gboolean type. */ /** * GArray: * @data: a pointer to the element data. The data may be moved as * elements are added to the #GArray. * @len: the number of elements in the #GArray not including the * possible terminating zero element. * * Contains the public fields of a GArray. */ /** * GAsyncQueue: * * The GAsyncQueue struct is an opaque data structure which represents * an asynchronous queue. It should only be accessed through the * g_async_queue_* functions. */ /** * GByteArray: * @data: a pointer to the element data. The data may be moved as * elements are added to the #GByteArray * @len: the number of elements in the #GByteArray * * Contains the public fields of a GByteArray. */ /** * GBytes: * * A simple refcounted data type representing an immutable sequence of zero or * more bytes from an unspecified origin. * * The purpose of a #GBytes is to keep the memory region that it holds * alive for as long as anyone holds a reference to the bytes. When * the last reference count is dropped, the memory is released. Multiple * unrelated callers can use byte data in the #GBytes without coordinating * their activities, resting assured that the byte data will not change or * move while they hold a reference. * * A #GBytes can come from many different origins that may have * different procedures for freeing the memory region. Examples are * memory from g_malloc(), from memory slices, from a #GMappedFile or * memory from other allocators. * * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full(). * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare() * function to g_tree_new(). * * The data pointed to by this bytes must not be modified. For a mutable * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a * mutable array for a #GBytes sequence. To create an immutable #GBytes from * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. * * Since: 2.32 */ /** * GCompareDataFunc: * @a: a value * @b: a value to compare with * @user_data: user data * * Specifies the type of a comparison function used to compare two * values. The function should return a negative integer if the first * value comes before the second, 0 if they are equal, or a positive * integer if the first value comes after the second. * * Returns: negative value if @a < @b; zero if @a = @b; positive * value if @a > @b */ /** * GCompareFunc: * @a: a value * @b: a value to compare with * * Specifies the type of a comparison function used to compare two * values. The function should return a negative integer if the first * value comes before the second, 0 if they are equal, or a positive * integer if the first value comes after the second. * * Returns: negative value if @a < @b; zero if @a = @b; positive * value if @a > @b */ /** * GCond: * * The #GCond struct is an opaque data structure that represents a * condition. Threads can block on a #GCond if they find a certain * condition to be false. If other threads change the state of this * condition they signal the #GCond, and that causes the waiting * threads to be woken up. * * Consider the following example of a shared variable. One or more * threads can wait for data to be published to the variable and when * another thread publishes the data, it can signal one of the waiting * threads to wake up to collect the data. * * Here is an example for using GCond to block a thread until a condition * is satisfied: * |[ * gpointer current_data = NULL; * GMutex data_mutex; * GCond data_cond; * * void * push_data (gpointer data) * { * g_mutex_lock (&data_mutex); * current_data = data; * g_cond_signal (&data_cond); * g_mutex_unlock (&data_mutex); * } * * gpointer * pop_data (void) * { * gpointer data; * * g_mutex_lock (&data_mutex); * while (!current_data) * g_cond_wait (&data_cond, &data_mutex); * data = current_data; * current_data = NULL; * g_mutex_unlock (&data_mutex); * * return data; * } * ]| * Whenever a thread calls pop_data() now, it will wait until * current_data is non-%NULL, i.e. until some other thread * has called push_data(). * * The example shows that use of a condition variable must always be * paired with a mutex. Without the use of a mutex, there would be a * race between the check of @current_data by the while loop in * pop_data() and waiting. Specifically, another thread could set * @current_data after the check, and signal the cond (with nobody * waiting on it) before the first thread goes to sleep. #GCond is * specifically useful for its ability to release the mutex and go * to sleep atomically. * * It is also important to use the g_cond_wait() and g_cond_wait_until() * functions only inside a loop which checks for the condition to be * true. See g_cond_wait() for an explanation of why the condition may * not be true even after it returns. * * If a #GCond is allocated in static storage then it can be used * without initialisation. Otherwise, you should call g_cond_init() * on it and g_cond_clear() when done. * * A #GCond should only be accessed via the g_cond_ functions. */ /** * GData: * * The #GData struct is an opaque data structure to represent a * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be * accessed via the following functions. */ /** * GDataForeachFunc: * @key_id: the #GQuark id to identifying the data element. * @data: the data element. * @user_data: (closure): user data passed to g_dataset_foreach(). * * Specifies the type of function passed to g_dataset_foreach(). It is * called with each #GQuark id and associated data element, together * with the @user_data parameter supplied to g_dataset_foreach(). */ /** * GDate: * @julian_days: the Julian representation of the date * @julian: this bit is set if @julian_days is valid * @dmy: this is set if @day, @month and @year are valid * @day: the day of the day-month-year representation of the date, * as a number between 1 and 31 * @month: the day of the day-month-year representation of the date, * as a number between 1 and 12 * @year: the day of the day-month-year representation of the date * * Represents a day between January 1, Year 1 and a few thousand years in * the future. None of its members should be accessed directly. * * If the #GDate-struct is obtained from g_date_new(), it will be safe * to mutate but invalid and thus not safe for calendrical computations. * * If it's declared on the stack, it will contain garbage so must be * initialized with g_date_clear(). g_date_clear() makes the date invalid * but sane. An invalid date doesn't represent a day, it's "empty." A date * becomes valid after you set it to a Julian day or you set a day, month, * and year. */ /** * GDateDMY: * @G_DATE_DAY: a day * @G_DATE_MONTH: a month * @G_DATE_YEAR: a year * * This enumeration isn't used in the API, but may be useful if you need * to mark a number as a day, month, or year. */ /** * GDateDay: * * Integer representing a day of the month; between 1 and 31. * #G_DATE_BAD_DAY represents an invalid day of the month. */ /** * GDateMonth: * @G_DATE_BAD_MONTH: invalid value * @G_DATE_JANUARY: January * @G_DATE_FEBRUARY: February * @G_DATE_MARCH: March * @G_DATE_APRIL: April * @G_DATE_MAY: May * @G_DATE_JUNE: June * @G_DATE_JULY: July * @G_DATE_AUGUST: August * @G_DATE_SEPTEMBER: September * @G_DATE_OCTOBER: October * @G_DATE_NOVEMBER: November * @G_DATE_DECEMBER: December * * Enumeration representing a month; values are #G_DATE_JANUARY, * #G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value. */ /** * GDateWeekday: * @G_DATE_BAD_WEEKDAY: invalid value * @G_DATE_MONDAY: Monday * @G_DATE_TUESDAY: Tuesday * @G_DATE_WEDNESDAY: Wednesday * @G_DATE_THURSDAY: Thursday * @G_DATE_FRIDAY: Friday * @G_DATE_SATURDAY: Saturday * @G_DATE_SUNDAY: Sunday * * Enumeration representing a day of the week; #G_DATE_MONDAY, * #G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. */ /** * GDateYear: * * Integer representing a year; #G_DATE_BAD_YEAR is the invalid * value. The year must be 1 or higher; negative (BC) years are not * allowed. The year is represented with four digits. */ /** * GDestroyNotify: * @data: the data element. * * Specifies the type of function which is called when a data element * is destroyed. It is passed the pointer to the data element and * should free any memory and resources allocated for it. */ /** * GDir: * * An opaque structure representing an opened directory. */ /** * GDoubleIEEE754: * @v_double: the double value * * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, * mantissa and exponent of IEEE floats and doubles. These unions are defined * as appropriate for a given platform. IEEE floats and doubles are supported * (used for storage) by at least Intel, PPC and Sparc. */ /** * GDuplicateFunc: * @data: the data to duplicate * @user_data: (closure): user data that was specified in * g_datalist_id_dup_data() * * The type of functions that are used to 'duplicate' an object. * What this means depends on the context, it could just be * incrementing the reference count, if @data is a ref-counted * object. * * Returns: a duplicate of data */ /** * GEqualFunc: * @a: a value * @b: a value to compare with * * Specifies the type of a function used to test two values for * equality. The function should return %TRUE if both values are equal * and %FALSE otherwise. * * Returns: %TRUE if @a = @b; %FALSE otherwise */ /** * GErrorType: * @G_ERR_UNKNOWN: unknown error * @G_ERR_UNEXP_EOF: unexpected end of file * @G_ERR_UNEXP_EOF_IN_STRING: unterminated string constant * @G_ERR_UNEXP_EOF_IN_COMMENT: unterminated comment * @G_ERR_NON_DIGIT_IN_CONST: non-digit character in a number * @G_ERR_DIGIT_RADIX: digit beyond radix in a number * @G_ERR_FLOAT_RADIX: non-decimal floating point number * @G_ERR_FLOAT_MALFORMED: malformed floating point number * * The possible errors, used in the @v_error field * of #GTokenValue, when the token is a %G_TOKEN_ERROR. */ /** * GFileError: * @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of * the file (or other resource) or processes with special privileges * can perform the operation. * @G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory * for writing, or create or remove hard links to it. * @G_FILE_ERROR_ACCES: Permission denied; the file permissions do not * allow the attempted operation. * @G_FILE_ERROR_NAMETOOLONG: Filename too long. * @G_FILE_ERROR_NOENT: No such file or directory. This is a "file * doesn't exist" error for ordinary files that are referenced in * contexts where they are expected to already exist. * @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when * a directory is required. * @G_FILE_ERROR_NXIO: No such device or address. The system tried to * use the device represented by a file you specified, and it * couldn't find the device. This can mean that the device file was * installed incorrectly, or that the physical device is missing or * not correctly attached to the computer. * @G_FILE_ERROR_NODEV: The underlying file system of the specified file * does not support memory mapping. * @G_FILE_ERROR_ROFS: The directory containing the new link can't be * modified because it's on a read-only file system. * @G_FILE_ERROR_TXTBSY: Text file busy. * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory. * (GLib won't reliably return this, don't pass in pointers to bad * memory.) * @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered * in looking up a file name. This often indicates a cycle of symbolic * links. * @G_FILE_ERROR_NOSPC: No space left on device; write operation on a * file failed because the disk is full. * @G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate * more virtual memory because its capacity is full. * @G_FILE_ERROR_MFILE: The current process has too many files open and * can't open any more. Duplicate descriptors do count toward this * limit. * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the * entire system. * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a * descriptor that has been closed or reading from a descriptor open * only for writing (or vice versa). * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate * various kinds of problems with passing the wrong argument to a * library function. * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the * other end of a pipe. Every library function that returns this * error code also generates a 'SIGPIPE' signal; this signal * terminates the program if not handled or blocked. Thus, your * program will never actually see this code unless it has handled * or blocked 'SIGPIPE'. * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might * work if you try again later. * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal * occurred and prevented completion of the call. When this * happens, you should try the call again. * @G_FILE_ERROR_IO: Input/output error; usually used for physical read * or write errors. i.e. the disk or other physical device hardware * is returning errors. * @G_FILE_ERROR_PERM: Operation not permitted; only the owner of the * file (or other resource) or processes with special privileges can * perform the operation. * @G_FILE_ERROR_NOSYS: Function not implemented; this indicates that * the system is missing some functionality. * @G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this * is the standard "failed for unspecified reason" error code present * in all #GError error code enumerations. Returned if no specific * code applies. * * Values corresponding to @errno codes returned from file operations * on UNIX. Unlike @errno codes, GFileError values are available on * all systems, even Windows. The exact meaning of each code depends * on what sort of file operation you were performing; the UNIX * documentation gives more details. The following error code descriptions * come from the GNU C Library manual, and are under the copyright * of that manual. * * It's not very portable to make detailed assumptions about exactly * which errors will be returned from a given operation. Some errors * don't occur on some systems, etc., sometimes there are subtle * differences in when a system will report a given error, etc. */ /** * GFileTest: * @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file * (not a directory). Note that this test will also return %TRUE * if the tested file is a symlink to a regular file. * @G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink. * @G_FILE_TEST_IS_DIR: %TRUE if the file is a directory. * @G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable. * @G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not * be a regular file. * * A test to perform on a file using g_file_test(). */ /** * GFloatIEEE754: * @v_float: the double value * * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, * mantissa and exponent of IEEE floats and doubles. These unions are defined * as appropriate for a given platform. IEEE floats and doubles are supported * (used for storage) by at least Intel, PPC and Sparc. */ /** * GFormatSizeFlags: * @G_FORMAT_SIZE_DEFAULT: behave the same as g_format_size() * @G_FORMAT_SIZE_LONG_FORMAT: include the exact number of bytes as part * of the returned string. For example, "45.6 kB (45,612 bytes)". * @G_FORMAT_SIZE_IEC_UNITS: use IEC (base 1024) units with "KiB"-style * suffixes. IEC units should only be used for reporting things with * a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. * Network and storage sizes should be reported in the normal SI units. * @G_FORMAT_SIZE_BITS: set the size as a quantity in bits, rather than * bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’. * * Flags to modify the format of the string returned by g_format_size_full(). */ /** * GFunc: * @data: the element's data * @user_data: user data passed to g_list_foreach() or g_slist_foreach() * * Specifies the type of functions passed to g_list_foreach() and * g_slist_foreach(). */ /** * GHFunc: * @key: a key * @value: the value corresponding to the key * @user_data: user data passed to g_hash_table_foreach() * * Specifies the type of the function passed to g_hash_table_foreach(). * It is called with each key/value pair, together with the @user_data * parameter which is passed to g_hash_table_foreach(). */ /** * GHRFunc: * @key: a key * @value: the value associated with the key * @user_data: user data passed to g_hash_table_remove() * * Specifies the type of the function passed to * g_hash_table_foreach_remove(). It is called with each key/value * pair, together with the @user_data parameter passed to * g_hash_table_foreach_remove(). It should return %TRUE if the * key/value pair should be removed from the #GHashTable. * * Returns: %TRUE if the key/value pair should be removed from the * #GHashTable */ /** * GHashFunc: * @key: a key * * Specifies the type of the hash function which is passed to * g_hash_table_new() when a #GHashTable is created. * * The function is passed a key and should return a #guint hash value. * The functions g_direct_hash(), g_int_hash() and g_str_hash() provide * hash functions which can be used when the key is a #gpointer, #gint*, * and #gchar* respectively. * * g_direct_hash() is also the appropriate hash function for keys * of the form `GINT_TO_POINTER (n)` (or similar macros). * * A good hash functions should produce * hash values that are evenly distributed over a fairly large range. * The modulus is taken with the hash table size (a prime number) to * find the 'bucket' to place each key into. The function should also * be very fast, since it is called for each key lookup. * * Note that the hash functions provided by GLib have these qualities, * but are not particularly robust against manufactured keys that * cause hash collisions. Therefore, you should consider choosing * a more secure hash function when using a GHashTable with keys * that originate in untrusted data (such as HTTP requests). * Using g_str_hash() in that situation might make your application * vulerable to * [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). * * The key to choosing a good hash is unpredictability. Even * cryptographic hashes are very easy to find collisions for when the * remainder is taken modulo a somewhat predictable prime number. There * must be an element of randomness that an attacker is unable to guess. * * Returns: the hash value corresponding to the key */ /** * GHashTable: * * The #GHashTable struct is an opaque data structure to represent a * [Hash Table][glib-Hash-Tables]. It should only be accessed via the * following functions. */ /** * GHashTableIter: * * A GHashTableIter structure represents an iterator that can be used * to iterate over the elements of a #GHashTable. GHashTableIter * structures are typically allocated on the stack and then initialized * with g_hash_table_iter_init(). */ /** * GHook: * @data: data which is passed to func when this hook is invoked * @next: pointer to the next hook in the list * @prev: pointer to the previous hook in the list * @ref_count: the reference count of this hook * @hook_id: the id of this hook, which is unique within its list * @flags: flags which are set for this hook. See #GHookFlagMask for * predefined flags * @func: the function to call when this hook is invoked. The possible * signatures for this function are #GHookFunc and #GHookCheckFunc * @destroy: the default @finalize_hook function of a #GHookList calls * this member of the hook that is being finalized * * The #GHook struct represents a single hook function in a #GHookList. */ /** * GHookCheckFunc: * @data: the data field of the #GHook is passed to the hook function here * * Defines the type of a hook function that can be invoked * by g_hook_list_invoke_check(). * * Returns: %FALSE if the #GHook should be destroyed */ /** * GHookCheckMarshaller: * @hook: a #GHook * @marshal_data: user data * * Defines the type of function used by g_hook_list_marshal_check(). * * Returns: %FALSE if @hook should be destroyed */ /** * GHookCompareFunc: * @new_hook: the #GHook being inserted * @sibling: the #GHook to compare with @new_hook * * Defines the type of function used to compare #GHook elements in * g_hook_insert_sorted(). * * Returns: a value <= 0 if @new_hook should be before @sibling */ /** * GHookFinalizeFunc: * @hook_list: a #GHookList * @hook: the hook in @hook_list that gets finalized * * Defines the type of function to be called when a hook in a * list of hooks gets finalized. */ /** * GHookFindFunc: * @hook: a #GHook * @data: user data passed to g_hook_find_func() * * Defines the type of the function passed to g_hook_find(). * * Returns: %TRUE if the required #GHook has been found */ /** * GHookFlagMask: * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for * hook flags; see %G_HOOK_FLAG_USER_SHIFT * * Flags used internally in the #GHook implementation. */ /** * GHookFunc: * @data: the data field of the #GHook is passed to the hook function here * * Defines the type of a hook function that can be invoked * by g_hook_list_invoke(). */ /** * GHookList: * @seq_id: the next free #GHook id * @hook_size: the size of the #GHookList elements, in bytes * @is_setup: 1 if the #GHookList has been initialized * @hooks: the first #GHook element in the list * @dummy3: unused * @finalize_hook: the function to call to finalize a #GHook element. * The default behaviour is to call the hooks @destroy function * @dummy: unused * * The #GHookList struct represents a list of hook functions. */ /** * GHookMarshaller: * @hook: a #GHook * @marshal_data: user data * * Defines the type of function used by g_hook_list_marshal(). */ /** * GINT16_FROM_BE: * @val: a #gint16 value in big-endian byte order * * Converts a #gint16 value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GINT16_FROM_LE: * @val: a #gint16 value in little-endian byte order * * Converts a #gint16 value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GINT16_TO_BE: * @val: a #gint16 value in host byte order * * Converts a #gint16 value from host byte order to big-endian. * * Returns: @val converted to big-endian */ /** * GINT16_TO_LE: * @val: a #gint16 value in host byte order * * Converts a #gint16 value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GINT32_FROM_BE: * @val: a #gint32 value in big-endian byte order * * Converts a #gint32 value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GINT32_FROM_LE: * @val: a #gint32 value in little-endian byte order * * Converts a #gint32 value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GINT32_TO_BE: * @val: a #gint32 value in host byte order * * Converts a #gint32 value from host byte order to big-endian. * * Returns: @val converted to big-endian */ /** * GINT32_TO_LE: * @val: a #gint32 value in host byte order * * Converts a #gint32 value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GINT64_FROM_BE: * @val: a #gint64 value in big-endian byte order * * Converts a #gint64 value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GINT64_FROM_LE: * @val: a #gint64 value in little-endian byte order * * Converts a #gint64 value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GINT64_TO_BE: * @val: a #gint64 value in host byte order * * Converts a #gint64 value from host byte order to big-endian. * * Returns: @val converted to big-endian */ /** * GINT64_TO_LE: * @val: a #gint64 value in host byte order * * Converts a #gint64 value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GINT_FROM_BE: * @val: a #gint value in big-endian byte order * * Converts a #gint value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GINT_FROM_LE: * @val: a #gint value in little-endian byte order * * Converts a #gint value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GINT_TO_BE: * @val: a #gint value in host byte order * * Converts a #gint value from host byte order to big-endian. * * Returns: @val converted to big-endian byte order */ /** * GINT_TO_LE: * @val: a #gint value in host byte order * * Converts a #gint value from host byte order to little-endian. * * Returns: @val converted to little-endian byte order */ /** * GINT_TO_POINTER: * @i: integer to stuff into a pointer * * Stuffs an integer into a pointer type. * * Remember, you may not store pointers in integers. This is not portable * in any way, shape or form. These macros only allow storing integers in * pointers, and only preserve 32 bits of the integer; values outside the * range of a 32-bit integer will be mangled. */ /** * GIOChannel: * * A data structure representing an IO Channel. The fields should be * considered private and should only be accessed with the following * functions. */ /** * GIOChannelError: * @G_IO_CHANNEL_ERROR_FBIG: File too large. * @G_IO_CHANNEL_ERROR_INVAL: Invalid argument. * @G_IO_CHANNEL_ERROR_IO: IO error. * @G_IO_CHANNEL_ERROR_ISDIR: File is a directory. * @G_IO_CHANNEL_ERROR_NOSPC: No space left on device. * @G_IO_CHANNEL_ERROR_NXIO: No such device or address. * @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype. * @G_IO_CHANNEL_ERROR_PIPE: Broken pipe. * @G_IO_CHANNEL_ERROR_FAILED: Some other error. * * Error codes returned by #GIOChannel operations. */ /** * GIOCondition: * @G_IO_IN: There is data to read. * @G_IO_OUT: Data can be written (without blocking). * @G_IO_PRI: There is urgent data to read. * @G_IO_ERR: Error condition. * @G_IO_HUP: Hung up (the connection has been broken, usually for * pipes and sockets). * @G_IO_NVAL: Invalid request. The file descriptor is not open. * * A bitwise combination representing a condition to watch for on an * event source. */ /** * GIOError: * @G_IO_ERROR_NONE: no error * @G_IO_ERROR_AGAIN: an EAGAIN error occurred * @G_IO_ERROR_INVAL: an EINVAL error occurred * @G_IO_ERROR_UNKNOWN: another error occurred * * #GIOError is only used by the deprecated functions * g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). */ /** * GIOFlags: * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND * (see the documentation of the UNIX open() syscall) * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to * %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() * syscall) * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. * This flag cannot be changed. * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable. * This flag cannot be changed. * @G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE * that existed before the spelling was fixed in GLib 2.30. It is kept * here for compatibility reasons. Deprecated since 2.30 * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, * i.e. that g_io_channel_seek_position() can be used on it. * This flag cannot be changed. * @G_IO_FLAG_MASK: the mask that specifies all the valid flags. * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from * g_io_channel_get_flags() * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify * with g_io_channel_set_flags() * * Specifies properties of a #GIOChannel. Some of the flags can only be * read with g_io_channel_get_flags(), but not changed with * g_io_channel_set_flags(). */ /** * GIOFunc: * @source: the #GIOChannel event source * @condition: the condition which has been satisfied * @data: user data set in g_io_add_watch() or g_io_add_watch_full() * * Specifies the type of function passed to g_io_add_watch() or * g_io_add_watch_full(), which is called when the requested condition * on a #GIOChannel is satisfied. * * Returns: the function should return %FALSE if the event source * should be removed */ /** * GIOFuncs: * @io_read: reads raw bytes from the channel. This is called from * various functions such as g_io_channel_read_chars() to * read raw bytes from the channel. Encoding and buffering * issues are dealt with at a higher level. * @io_write: writes raw bytes to the channel. This is called from * various functions such as g_io_channel_write_chars() to * write raw bytes to the channel. Encoding and buffering * issues are dealt with at a higher level. * @io_seek: (optional): seeks the channel. This is called from * g_io_channel_seek() on channels that support it. * @io_close: closes the channel. This is called from * g_io_channel_close() after flushing the buffers. * @io_create_watch: creates a watch on the channel. This call * corresponds directly to g_io_create_watch(). * @io_free: called from g_io_channel_unref() when the channel needs to * be freed. This function must free the memory associated * with the channel, including freeing the #GIOChannel * structure itself. The channel buffers have been flushed * and possibly @io_close has been called by the time this * function is called. * @io_set_flags: sets the #GIOFlags on the channel. This is called * from g_io_channel_set_flags() with all flags except * for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked * out. * @io_get_flags: gets the #GIOFlags for the channel. This function * need only return the %G_IO_FLAG_APPEND and * %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() * automatically adds the others as appropriate. * * A table of functions used to handle different types of #GIOChannel * in a generic way. */ /** * GIOStatus: * @G_IO_STATUS_ERROR: An error occurred. * @G_IO_STATUS_NORMAL: Success. * @G_IO_STATUS_EOF: End of file. * @G_IO_STATUS_AGAIN: Resource temporarily unavailable. * * Stati returned by most of the #GIOFuncs functions. */ /** * GKeyFile: * * The GKeyFile struct contains only private data * and should not be accessed directly. */ /** * GKeyFileError: * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in * an unknown encoding * @G_KEY_FILE_ERROR_PARSE: document was ill-formed * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found * @G_KEY_FILE_ERROR_GROUP_NOT_FOUND: a requested group was not found * @G_KEY_FILE_ERROR_INVALID_VALUE: a value could not be parsed * * Error codes returned by key file parsing. */ /** * GKeyFileFlags: * @G_KEY_FILE_NONE: No flags, default behaviour * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the * (possibly modified) contents of the key file back to a file; * otherwise all comments will be lost when the key file is * written back. * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the * (possibly modified) contents of the key file back to a file; * otherwise only the translations for the current language will be * written back. * * Flags which influence the parsing. */ /** * GLIB_CHECK_VERSION: * @major: the major version to check for * @minor: the minor version to check for * @micro: the micro version to check for * * Checks the version of the GLib library that is being compiled * against. See glib_check_version() for a runtime check. * * Returns: %TRUE if the version of the GLib header files * is the same as or newer than the passed-in version. */ /** * GLIB_DISABLE_DEPRECATION_WARNINGS: * * A macro that should be defined before including the glib.h header. * If it is defined, no compiler warnings will be produced for uses * of deprecated GLib APIs. */ /** * GLIB_MAJOR_VERSION: * * The major version number of the GLib library. * * Like #glib_major_version, but from the headers used at * application compile time, rather than from the library * linked against at application run time. */ /** * GLIB_MICRO_VERSION: * * The micro version number of the GLib library. * * Like #gtk_micro_version, but from the headers used at * application compile time, rather than from the library * linked against at application run time. */ /** * GLIB_MINOR_VERSION: * * The minor version number of the GLib library. * * Like #gtk_minor_version, but from the headers used at * application compile time, rather than from the library * linked against at application run time. */ /** * GLONG_FROM_BE: * @val: a #glong value in big-endian byte order * * Converts a #glong value from big-endian to the host byte order. * * Returns: @val converted to host byte order */ /** * GLONG_FROM_LE: * @val: a #glong value in little-endian byte order * * Converts a #glong value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GLONG_TO_BE: * @val: a #glong value in host byte order * * Converts a #glong value from host byte order to big-endian. * * Returns: @val converted to big-endian byte order */ /** * GLONG_TO_LE: * @val: a #glong value in host byte order * * Converts a #glong value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GList: * @data: holds the element's data, which can be a pointer to any kind * of data, or any integer value using the * [Type Conversion Macros][glib-Type-Conversion-Macros] * @next: contains the link to the next element in the list * @prev: contains the link to the previous element in the list * * The #GList struct is used for each element in a doubly-linked list. */ /** * GLogFunc: * @log_domain: the log domain of the message * @log_level: the log level of the message (including the * fatal and recursion flags) * @message: the message to process * @user_data: user data, set in g_log_set_handler() * * Specifies the prototype of log handler functions. * * The default log handler, g_log_default_handler(), automatically appends a * new-line character to @message when printing it. It is advised that any * custom log handler functions behave similarly, so that logging calls in user * code do not need modifying to add a new-line character to the message if the * log handler is changed. * * This is not used if structured logging is enabled; see * [Using Structured Logging][using-structured-logging]. */ /** * GLogLevelFlags: * @G_LOG_FLAG_RECURSION: internal flag * @G_LOG_FLAG_FATAL: internal flag * @G_LOG_LEVEL_ERROR: log level for errors, see g_error(). * This level is also used for messages produced by g_assert(). * @G_LOG_LEVEL_CRITICAL: log level for critical warning messages, see * g_critical(). * This level is also used for messages produced by g_return_if_fail() * and g_return_val_if_fail(). * @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning() * @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message() * @G_LOG_LEVEL_INFO: log level for informational messages, see g_info() * @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug() * @G_LOG_LEVEL_MASK: a mask including all log levels * * Flags specifying the level of log messages. * * It is possible to change how GLib treats messages of the various * levels using g_log_set_handler() and g_log_set_fatal_mask(). */ /** * GMappedFile: * * The #GMappedFile represents a file mapping created with * g_mapped_file_new(). It has only private members and should * not be accessed directly. */ /** * GMarkupCollectType: * @G_MARKUP_COLLECT_INVALID: used to terminate the list of attributes * to collect * @G_MARKUP_COLLECT_STRING: collect the string pointer directly from * the attribute_values[] array. Expects a parameter of type (const * char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the * attribute isn't present then the pointer will be set to %NULL * @G_MARKUP_COLLECT_STRDUP: as with %G_MARKUP_COLLECT_STRING, but * expects a parameter of type (char **) and g_strdup()s the * returned pointer. The pointer must be freed with g_free() * @G_MARKUP_COLLECT_BOOLEAN: expects a parameter of type (gboolean *) * and parses the attribute value as a boolean. Sets %FALSE if the * attribute isn't present. Valid boolean values consist of * (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", * "yes", "y", "1" * @G_MARKUP_COLLECT_TRISTATE: as with %G_MARKUP_COLLECT_BOOLEAN, but * in the case of a missing attribute a value is set that compares * equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is * implied * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields. * If present, allows the attribute not to appear. A default value * is set depending on what value type is used * * A mixed enumerated type and flags field. You must specify one type * (string, strdup, boolean, tristate). Additionally, you may optionally * bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL. * * It is likely that this enum will be extended in the future to * support other types. */ /** * GMutex: * * The #GMutex struct is an opaque data structure to represent a mutex * (mutual exclusion). It can be used to protect data against shared * access. * * Take for example the following function: * |[ * int * give_me_next_number (void) * { * static int current_number = 0; * * // now do a very complicated calculation to calculate the new * // number, this might for example be a random number generator * current_number = calc_next_number (current_number); * * return current_number; * } * ]| * It is easy to see that this won't work in a multi-threaded * application. There current_number must be protected against shared * access. A #GMutex can be used as a solution to this problem: * |[ * int * give_me_next_number (void) * { * static GMutex mutex; * static int current_number = 0; * int ret_val; * * g_mutex_lock (&mutex); * ret_val = current_number = calc_next_number (current_number); * g_mutex_unlock (&mutex); * * return ret_val; * } * ]| * Notice that the #GMutex is not initialised to any particular value. * Its placement in static storage ensures that it will be initialised * to all-zeros, which is appropriate. * * If a #GMutex is placed in other contexts (eg: embedded in a struct) * then it must be explicitly initialised using g_mutex_init(). * * A #GMutex should only be accessed via g_mutex_ functions. */ /** * GNode: * @data: contains the actual data of the node. * @next: points to the node's next sibling (a sibling is another * #GNode with the same parent). * @prev: points to the node's previous sibling. * @parent: points to the parent of the #GNode, or is %NULL if the * #GNode is the root of the tree. * @children: points to the first child of the #GNode. The other * children are accessed by using the @next pointer of each * child. * * The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees]. */ /** * GNodeForeachFunc: * @node: a #GNode. * @data: user data passed to g_node_children_foreach(). * * Specifies the type of function passed to g_node_children_foreach(). * The function is called with each child node, together with the user * data passed to g_node_children_foreach(). */ /** * GNodeTraverseFunc: * @node: a #GNode. * @data: user data passed to g_node_traverse(). * * Specifies the type of function passed to g_node_traverse(). The * function is called with each of the nodes visited, together with the * user data passed to g_node_traverse(). If the function returns * %TRUE, then the traversal is stopped. * * Returns: %TRUE to stop the traversal. */ /** * GOnce: * @status: the status of the #GOnce * @retval: the value returned by the call to the function, if @status * is %G_ONCE_STATUS_READY * * A #GOnce struct controls a one-time initialization function. Any * one-time initialization function must have its own unique #GOnce * struct. * * Since: 2.4 */ /** * GOnceStatus: * @G_ONCE_STATUS_NOTCALLED: the function has not been called yet. * @G_ONCE_STATUS_PROGRESS: the function call is currently in progress. * @G_ONCE_STATUS_READY: the function has been called. * * The possible statuses of a one-time initialization function * controlled by a #GOnce struct. * * Since: 2.4 */ /** * GPOINTER_TO_INT: * @p: pointer containing an integer * * Extracts an integer from a pointer. The integer must have * been stored in the pointer with GINT_TO_POINTER(). * * Remember, you may not store pointers in integers. This is not portable * in any way, shape or form. These macros only allow storing integers in * pointers, and only preserve 32 bits of the integer; values outside the * range of a 32-bit integer will be mangled. */ /** * GPOINTER_TO_SIZE: * @p: pointer to extract a #gsize from * * Extracts a #gsize from a pointer. The #gsize must have * been stored in the pointer with GSIZE_TO_POINTER(). */ /** * GPOINTER_TO_UINT: * @p: pointer to extract an unsigned integer from * * Extracts an unsigned integer from a pointer. The integer must have * been stored in the pointer with GUINT_TO_POINTER(). */ /** * GPatternSpec: * * A GPatternSpec struct is the 'compiled' form of a pattern. This * structure is opaque and its fields cannot be accessed directly. */ /** * GPrivate: * * The #GPrivate struct is an opaque data structure to represent a * thread-local data key. It is approximately equivalent to the * pthread_setspecific()/pthread_getspecific() APIs on POSIX and to * TlsSetValue()/TlsGetValue() on Windows. * * If you don't already know why you might want this functionality, * then you probably don't need it. * * #GPrivate is a very limited resource (as far as 128 per program, * shared between all libraries). It is also not possible to destroy a * #GPrivate after it has been used. As such, it is only ever acceptable * to use #GPrivate in static scope, and even then sparingly so. * * See G_PRIVATE_INIT() for a couple of examples. * * The #GPrivate structure should be considered opaque. It should only * be accessed via the g_private_ functions. */ /** * GPtrArray: * @pdata: points to the array of pointers, which may be moved when the * array grows * @len: number of pointers in the array * * Contains the public fields of a pointer array. */ /** * GQuark: * * A GQuark is a non-zero integer which uniquely identifies a * particular string. A GQuark value of zero is associated to %NULL. */ /** * GRWLock: * * The GRWLock struct is an opaque data structure to represent a * reader-writer lock. It is similar to a #GMutex in that it allows * multiple threads to coordinate access to a shared resource. * * The difference to a mutex is that a reader-writer lock discriminates * between read-only ('reader') and full ('writer') access. While only * one thread at a time is allowed write access (by holding the 'writer' * lock via g_rw_lock_writer_lock()), multiple threads can gain * simultaneous read-only access (by holding the 'reader' lock via * g_rw_lock_reader_lock()). * * Here is an example for an array with access functions: * |[ * GRWLock lock; * GPtrArray *array; * * gpointer * my_array_get (guint index) * { * gpointer retval = NULL; * * if (!array) * return NULL; * * g_rw_lock_reader_lock (&lock); * if (index < array->len) * retval = g_ptr_array_index (array, index); * g_rw_lock_reader_unlock (&lock); * * return retval; * } * * void * my_array_set (guint index, gpointer data) * { * g_rw_lock_writer_lock (&lock); * * if (!array) * array = g_ptr_array_new (); * * if (index >= array->len) * g_ptr_array_set_size (array, index+1); * g_ptr_array_index (array, index) = data; * * g_rw_lock_writer_unlock (&lock); * } * ]| * This example shows an array which can be accessed by many readers * (the my_array_get() function) simultaneously, whereas the writers * (the my_array_set() function) will only be allowed one at a time * and only if no readers currently access the array. This is because * of the potentially dangerous resizing of the array. Using these * functions is fully multi-thread safe now. * * If a #GRWLock is allocated in static storage then it can be used * without initialisation. Otherwise, you should call * g_rw_lock_init() on it and g_rw_lock_clear() when done. * * A GRWLock should only be accessed with the g_rw_lock_ functions. * * Since: 2.32 */ /** * GRand: * * The GRand struct is an opaque data structure. It should only be * accessed through the g_rand_* functions. */ /** * GRecMutex: * * The GRecMutex struct is an opaque data structure to represent a * recursive mutex. It is similar to a #GMutex with the difference * that it is possible to lock a GRecMutex multiple times in the same * thread without deadlock. When doing so, care has to be taken to * unlock the recursive mutex as often as it has been locked. * * If a #GRecMutex is allocated in static storage then it can be used * without initialisation. Otherwise, you should call * g_rec_mutex_init() on it and g_rec_mutex_clear() when done. * * A GRecMutex should only be accessed with the * g_rec_mutex_ functions. * * Since: 2.32 */ /** * GSIZE_FROM_BE: * @val: a #gsize value in big-endian byte order * * Converts a #gsize value from big-endian to the host byte order. * * Returns: @val converted to host byte order */ /** * GSIZE_FROM_LE: * @val: a #gsize value in little-endian byte order * * Converts a #gsize value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GSIZE_TO_BE: * @val: a #gsize value in host byte order * * Converts a #gsize value from host byte order to big-endian. * * Returns: @val converted to big-endian byte order */ /** * GSIZE_TO_LE: * @val: a #gsize value in host byte order * * Converts a #gsize value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GSIZE_TO_POINTER: * @s: #gsize to stuff into the pointer * * Stuffs a #gsize into a pointer type. */ /** * GSList: * @data: holds the element's data, which can be a pointer to any kind * of data, or any integer value using the * [Type Conversion Macros][glib-Type-Conversion-Macros] * @next: contains the link to the next element in the list. * * The #GSList struct is used for each element in the singly-linked * list. */ /** * GSSIZE_FROM_BE: * @val: a #gssize value in big-endian byte order * * Converts a #gssize value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GSSIZE_FROM_LE: * @val: a #gssize value in little-endian byte order * * Converts a #gssize value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GSSIZE_TO_BE: * @val: a #gssize value in host byte order * * Converts a #gssize value from host byte order to big-endian. * * Returns: @val converted to big-endian */ /** * GSSIZE_TO_LE: * @val: a #gssize value in host byte order * * Converts a #gssize value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GScanner: * @user_data: unused * @max_parse_errors: unused * @parse_errors: g_scanner_error() increments this field * @input_name: name of input stream, featured by the default message handler * @qdata: quarked data * @config: link into the scanner configuration * @token: token parsed by the last g_scanner_get_next_token() * @value: value of the last token from g_scanner_get_next_token() * @line: line number of the last token from g_scanner_get_next_token() * @position: char number of the last token from g_scanner_get_next_token() * @next_token: token parsed by the last g_scanner_peek_next_token() * @next_value: value of the last token from g_scanner_peek_next_token() * @next_line: line number of the last token from g_scanner_peek_next_token() * @next_position: char number of the last token from g_scanner_peek_next_token() * @msg_handler: handler function for _warn and _error * * The data structure representing a lexical scanner. * * You should set @input_name after creating the scanner, since * it is used by the default message handler when displaying * warnings and errors. If you are scanning a file, the filename * would be a good choice. * * The @user_data and @max_parse_errors fields are not used. * If you need to associate extra data with the scanner you * can place them here. * * If you want to use your own message handler you can set the * @msg_handler field. The type of the message handler function * is declared by #GScannerMsgFunc. */ /** * GScannerConfig: * @cset_skip_characters: specifies which characters should be skipped * by the scanner (the default is the whitespace characters: space, * tab, carriage-return and line-feed). * @cset_identifier_first: specifies the characters which can start * identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). * @cset_identifier_nth: specifies the characters which can be used * in identifiers, after the first character (the default is * #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, * #G_CSET_LATINC). * @cpair_comment_single: specifies the characters at the start and * end of single-line comments. The default is "#\n" which means * that single-line comments start with a '#' and continue until * a '\n' (end of line). * @case_sensitive: specifies if symbols are case sensitive (the * default is %FALSE). * @skip_comment_multi: specifies if multi-line comments are skipped * and not returned as tokens (the default is %TRUE). * @skip_comment_single: specifies if single-line comments are skipped * and not returned as tokens (the default is %TRUE). * @scan_comment_multi: specifies if multi-line comments are recognized * (the default is %TRUE). * @scan_identifier: specifies if identifiers are recognized (the * default is %TRUE). * @scan_identifier_1char: specifies if single-character * identifiers are recognized (the default is %FALSE). * @scan_identifier_NULL: specifies if %NULL is reported as * %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). * @scan_symbols: specifies if symbols are recognized (the default * is %TRUE). * @scan_binary: specifies if binary numbers are recognized (the * default is %FALSE). * @scan_octal: specifies if octal numbers are recognized (the * default is %TRUE). * @scan_float: specifies if floating point numbers are recognized * (the default is %TRUE). * @scan_hex: specifies if hexadecimal numbers are recognized (the * default is %TRUE). * @scan_hex_dollar: specifies if '$' is recognized as a prefix for * hexadecimal numbers (the default is %FALSE). * @scan_string_sq: specifies if strings can be enclosed in single * quotes (the default is %TRUE). * @scan_string_dq: specifies if strings can be enclosed in double * quotes (the default is %TRUE). * @numbers_2_int: specifies if binary, octal and hexadecimal numbers * are reported as #G_TOKEN_INT (the default is %TRUE). * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT * (the default is %FALSE). * @identifier_2_string: specifies if identifiers are reported as strings * (the default is %FALSE). * @char_2_token: specifies if characters are reported by setting * `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE). * @symbol_2_token: specifies if symbols are reported by setting * `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE). * @scope_0_fallback: specifies if a symbol is searched for in the * default scope in addition to the current scope (the default is %FALSE). * @store_int64: use value.v_int64 rather than v_int * * Specifies the #GScanner parser configuration. Most settings can * be changed during the parsing phase and will affect the lexical * parsing of the next unpeeked token. */ /** * GScannerMsgFunc: * @scanner: a #GScanner * @message: the message * @error: %TRUE if the message signals an error, * %FALSE if it signals a warning. * * Specifies the type of the message handler function. */ /** * GSeekType: * @G_SEEK_CUR: the current position in the file. * @G_SEEK_SET: the start of the file. * @G_SEEK_END: the end of the file. * * An enumeration specifying the base position for a * g_io_channel_seek_position() operation. */ /** * GSequence: * * The #GSequence struct is an opaque data type representing a * [sequence][glib-Sequences] data type. */ /** * GSequenceIter: * * The #GSequenceIter struct is an opaque data type representing an * iterator pointing into a #GSequence. */ /** * GSequenceIterCompareFunc: * @a: a #GSequenceIter * @b: a #GSequenceIter * @data: user data * * A #GSequenceIterCompareFunc is a function used to compare iterators. * It must return zero if the iterators compare equal, a negative value * if @a comes before @b, and a positive value if @b comes before @a. * * Returns: zero if the iterators are equal, a negative value if @a * comes before @b, and a positive value if @b comes before @a. */ /** * GShellError: * @G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting. * @G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty. * @G_SHELL_ERROR_FAILED: Some other error. * * Error codes returned by shell functions. */ /** * GStatBuf: * * A type corresponding to the appropriate struct type for the stat() * system call, depending on the platform and/or compiler being used. * * See g_stat() for more information. */ /** * GString: * @str: points to the character data. It may move as text is added. * The @str field is null-terminated and so * can be used as an ordinary C string. * @len: contains the length of the string, not including the * terminating nul byte. * @allocated_len: the number of bytes that can be stored in the * string before it needs to be reallocated. May be larger than @len. * * The GString struct contains the public fields of a GString. */ /** * GStringChunk: * * An opaque data structure representing String Chunks. * It should only be accessed by using the following functions. */ /** * GStrv: * * A typedef alias for gchar**. This is mostly useful when used together with * g_auto(). */ /** * GTestCase: * * An opaque structure representing a test case. */ /** * GTestDataFunc: * @user_data: the data provided when registering the test * * The type used for test case functions that take an extra pointer * argument. * * Since: 2.28 */ /** * GTestFileType: * @G_TEST_DIST: a file that was included in the distribution tarball * @G_TEST_BUILT: a file that was built on the compiling machine * * The type of file to return the filename for, when used with * g_test_build_filename(). * * These two options correspond rather directly to the 'dist' and * 'built' terminology that automake uses and are explicitly used to * distinguish between the 'srcdir' and 'builddir' being separate. All * files in your project should either be dist (in the * `EXTRA_DIST` or `dist_schema_DATA` * sense, in which case they will always be in the srcdir) or built (in * the `BUILT_SOURCES` sense, in which case they will * always be in the builddir). * * Note: as a general rule of automake, files that are generated only as * part of the build-from-git process (but then are distributed with the * tarball) always go in srcdir (even if doing a srcdir != builddir * build from git) and are considered as distributed files. * * Since: 2.38 */ /** * GTestFixtureFunc: * @fixture: (not nullable): the test fixture * @user_data: the data provided when registering the test * * The type used for functions that operate on test fixtures. This is * used for the fixture setup and teardown functions as well as for the * testcases themselves. * * @user_data is a pointer to the data that was given when registering * the test case. * * @fixture will be a pointer to the area of memory allocated by the * test framework, of the size requested. If the requested size was * zero then @fixture will be equal to @user_data. * * Since: 2.28 */ /** * GTestFunc: * * The type used for test case functions. * * Since: 2.28 */ /** * GTestSubprocessFlags: * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child * process will inherit the parent's stdin. Otherwise, the child's * stdin is redirected to `/dev/null`. * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child * process will inherit the parent's stdout. Otherwise, the child's * stdout will not be visible, but it will be captured to allow * later tests with g_test_trap_assert_stdout(). * @G_TEST_SUBPROCESS_INHERIT_STDERR: If this flag is given, the child * process will inherit the parent's stderr. Otherwise, the child's * stderr will not be visible, but it will be captured to allow * later tests with g_test_trap_assert_stderr(). * * Flags to pass to g_test_trap_subprocess() to control input and output. * * Note that in contrast with g_test_trap_fork(), the default is to * not show stdout and stderr. */ /** * GTestSuite: * * An opaque structure representing a test suite. */ /** * GTestTrapFlags: * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to * `/dev/null` so it cannot be observed on the console during test * runs. The actual output is still captured though to allow later * tests with g_test_trap_assert_stdout(). * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to * `/dev/null` so it cannot be observed on the console during test * runs. The actual output is still captured though to allow later * tests with g_test_trap_assert_stderr(). * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the * child process is shared with stdin of its parent process. * It is redirected to `/dev/null` otherwise. * * Test traps are guards around forked tests. * These flags determine what traps to set. * * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(), * which is deprecated. g_test_trap_subprocess() uses * #GTestSubprocessFlags. */ /** * GThread: * * The #GThread struct represents a running thread. This struct * is returned by g_thread_new() or g_thread_try_new(). You can * obtain the #GThread struct representing the current thread by * calling g_thread_self(). * * GThread is refcounted, see g_thread_ref() and g_thread_unref(). * The thread represented by it holds a reference while it is running, * and g_thread_join() consumes the reference that it is given, so * it is normally not necessary to manage GThread references * explicitly. * * The structure is opaque -- none of its fields may be directly * accessed. */ /** * GThreadError: * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource * shortage. Try again later. * * Possible errors of thread related functions. */ /** * GThreadFunc: * @data: data passed to the thread * * Specifies the type of the @func functions passed to g_thread_new() * or g_thread_try_new(). * * Returns: the return value of the thread */ /** * GThreadPool: * @func: the function to execute in the threads of this pool * @user_data: the user data for the threads of this pool * @exclusive: are all threads exclusive to this pool * * The #GThreadPool struct represents a thread pool. It has three * public read-only members, but the underlying struct is bigger, * so you must not copy this struct. */ /** * GTime: * * Simply a replacement for time_t. It has been deprecated * since it is not equivalent to time_t on 64-bit platforms * with a 64-bit time_t. Unrelated to #GTimer. * * Note that #GTime is defined to always be a 32-bit integer, * unlike time_t which may be 64-bit on some systems. Therefore, * #GTime will overflow in the year 2038, and you cannot use the * address of a #GTime variable as argument to the UNIX time() * function. * * Instead, do the following: * |[ * time_t ttime; * GTime gtime; * * time (&ttime); * gtime = (GTime)ttime; * ]| */ /** * GTimeVal: * @tv_sec: seconds * @tv_usec: microseconds * * Represents a precise time, with seconds and microseconds. * Similar to the struct timeval returned by the gettimeofday() * UNIX system call. * * GLib is attempting to unify around the use of 64bit integers to * represent microsecond-precision time. As such, this type will be * removed from a future version of GLib. */ /** * GTimeZone: * * #GTimeZone is an opaque structure whose members cannot be accessed * directly. * * Since: 2.26 */ /** * GTimer: * * Opaque datatype that records a start time. */ /** * GTokenType: * @G_TOKEN_EOF: the end of the file * @G_TOKEN_LEFT_PAREN: a '(' character * @G_TOKEN_LEFT_CURLY: a '{' character * @G_TOKEN_LEFT_BRACE: a '[' character * @G_TOKEN_RIGHT_CURLY: a '}' character * @G_TOKEN_RIGHT_PAREN: a ')' character * @G_TOKEN_RIGHT_BRACE: a ']' character * @G_TOKEN_EQUAL_SIGN: a '=' character * @G_TOKEN_COMMA: a ',' character * @G_TOKEN_NONE: not a token * @G_TOKEN_ERROR: an error occurred * @G_TOKEN_CHAR: a character * @G_TOKEN_BINARY: a binary integer * @G_TOKEN_OCTAL: an octal integer * @G_TOKEN_INT: an integer * @G_TOKEN_HEX: a hex integer * @G_TOKEN_FLOAT: a floating point number * @G_TOKEN_STRING: a string * @G_TOKEN_SYMBOL: a symbol * @G_TOKEN_IDENTIFIER: an identifier * @G_TOKEN_IDENTIFIER_NULL: a null identifier * @G_TOKEN_COMMENT_SINGLE: one line comment * @G_TOKEN_COMMENT_MULTI: multi line comment * * The possible types of token returned from each * g_scanner_get_next_token() call. */ /** * GTokenValue: * @v_symbol: token symbol value * @v_identifier: token identifier value * @v_binary: token binary integer value * @v_octal: octal integer value * @v_int: integer value * @v_int64: 64-bit integer value * @v_float: floating point value * @v_hex: hex integer value * @v_string: string value * @v_comment: comment value * @v_char: character value * @v_error: error value * * A union holding the value of the token. */ /** * GTrashStack: * @next: pointer to the previous element of the stack, * gets stored in the first `sizeof (gpointer)` * bytes of the element * * Each piece of memory that is pushed onto the stack * is cast to a GTrashStack*. * * Deprecated: 2.48: #GTrashStack is deprecated without replacement */ /** * GTraverseFlags: * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has * been introduced in 2.6, for older version use * %G_TRAVERSE_LEAFS. * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This * name has been introduced in 2.6, for older * version use %G_TRAVERSE_NON_LEAFS. * @G_TRAVERSE_ALL: all nodes should be visited. * @G_TRAVERSE_MASK: a mask of all traverse flags. * @G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES. * @G_TRAVERSE_NON_LEAFS: identical to %G_TRAVERSE_NON_LEAVES. * * Specifies which nodes are visited during several of the tree * functions, including g_node_traverse() and g_node_find(). */ /** * GTraverseFunc: * @key: a key of a #GTree node * @value: the value corresponding to the key * @data: user data passed to g_tree_traverse() * * Specifies the type of function passed to g_tree_traverse(). It is * passed the key and value of each node, together with the @user_data * parameter passed to g_tree_traverse(). If the function returns * %TRUE, the traversal is stopped. * * Returns: %TRUE to stop the traversal */ /** * GTraverseType: * @G_IN_ORDER: vists a node's left child first, then the node itself, * then its right child. This is the one to use if you * want the output sorted according to the compare * function. * @G_PRE_ORDER: visits a node, then its children. * @G_POST_ORDER: visits the node's children, then the node itself. * @G_LEVEL_ORDER: is not implemented for * [balanced binary trees][glib-Balanced-Binary-Trees]. * For [n-ary trees][glib-N-ary-Trees], it * vists the root node first, then its children, then * its grandchildren, and so on. Note that this is less * efficient than the other orders. * * Specifies the type of traveral performed by g_tree_traverse(), * g_node_traverse() and g_node_find(). The different orders are * illustrated here: * - In order: A, B, C, D, E, F, G, H, I * ![](Sorted_binary_tree_inorder.svg) * - Pre order: F, B, A, D, C, E, G, I, H * ![](Sorted_binary_tree_preorder.svg) * - Post order: A, C, E, D, B, H, I, G, F * ![](Sorted_binary_tree_postorder.svg) * - Level order: F, B, G, A, D, I, C, E, H * ![](Sorted_binary_tree_breadth-first_traversal.svg) */ /** * GTree: * * The GTree struct is an opaque data structure representing a * [balanced binary tree][glib-Balanced-Binary-Trees]. It should be * accessed only by using the following functions. */ /** * GUINT16_FROM_BE: * @val: a #guint16 value in big-endian byte order * * Converts a #guint16 value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GUINT16_FROM_LE: * @val: a #guint16 value in little-endian byte order * * Converts a #guint16 value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GUINT16_SWAP_BE_PDP: * @val: a #guint16 value in big-endian or pdp-endian byte order * * Converts a #guint16 value between big-endian and pdp-endian byte order. * The conversion is symmetric so it can be used both ways. * * Returns: @val converted to the opposite byte order */ /** * GUINT16_SWAP_LE_BE: * @val: a #guint16 value in little-endian or big-endian byte order * * Converts a #guint16 value between little-endian and big-endian byte order. * The conversion is symmetric so it can be used both ways. * * Returns: @val converted to the opposite byte order */ /** * GUINT16_SWAP_LE_PDP: * @val: a #guint16 value in little-endian or pdp-endian byte order * * Converts a #guint16 value between little-endian and pdp-endian byte order. * The conversion is symmetric so it can be used both ways. * * Returns: @val converted to the opposite byte order */ /** * GUINT16_TO_BE: * @val: a #guint16 value in host byte order * * Converts a #guint16 value from host byte order to big-endian. * * Returns: @val converted to big-endian */ /** * GUINT16_TO_LE: * @val: a #guint16 value in host byte order * * Converts a #guint16 value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GUINT32_FROM_BE: * @val: a #guint32 value in big-endian byte order * * Converts a #guint32 value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GUINT32_FROM_LE: * @val: a #guint32 value in little-endian byte order * * Converts a #guint32 value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GUINT32_SWAP_BE_PDP: * @val: a #guint32 value in big-endian or pdp-endian byte order * * Converts a #guint32 value between big-endian and pdp-endian byte order. * The conversion is symmetric so it can be used both ways. * * Returns: @val converted to the opposite byte order */ /** * GUINT32_SWAP_LE_BE: * @val: a #guint32 value in little-endian or big-endian byte order * * Converts a #guint32 value between little-endian and big-endian byte order. * The conversion is symmetric so it can be used both ways. * * Returns: @val converted to the opposite byte order */ /** * GUINT32_SWAP_LE_PDP: * @val: a #guint32 value in little-endian or pdp-endian byte order * * Converts a #guint32 value between little-endian and pdp-endian byte order. * The conversion is symmetric so it can be used both ways. * * Returns: @val converted to the opposite byte order */ /** * GUINT32_TO_BE: * @val: a #guint32 value in host byte order * * Converts a #guint32 value from host byte order to big-endian. * * Returns: @val converted to big-endian */ /** * GUINT32_TO_LE: * @val: a #guint32 value in host byte order * * Converts a #guint32 value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GUINT64_FROM_BE: * @val: a #guint64 value in big-endian byte order * * Converts a #guint64 value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GUINT64_FROM_LE: * @val: a #guint64 value in little-endian byte order * * Converts a #guint64 value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GUINT64_SWAP_LE_BE: * @val: a #guint64 value in little-endian or big-endian byte order * * Converts a #guint64 value between little-endian and big-endian byte order. * The conversion is symmetric so it can be used both ways. * * Returns: @val converted to the opposite byte order */ /** * GUINT64_TO_BE: * @val: a #guint64 value in host byte order * * Converts a #guint64 value from host byte order to big-endian. * * Returns: @val converted to big-endian */ /** * GUINT64_TO_LE: * @val: a #guint64 value in host byte order * * Converts a #guint64 value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GUINT_FROM_BE: * @val: a #guint value in big-endian byte order * * Converts a #guint value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GUINT_FROM_LE: * @val: a #guint value in little-endian byte order * * Converts a #guint value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GUINT_TO_BE: * @val: a #guint value in host byte order * * Converts a #guint value from host byte order to big-endian. * * Returns: @val converted to big-endian byte order */ /** * GUINT_TO_LE: * @val: a #guint value in host byte order * * Converts a #guint value from host byte order to little-endian. * * Returns: @val converted to little-endian byte order. */ /** * GUINT_TO_POINTER: * @u: unsigned integer to stuff into the pointer * * Stuffs an unsigned integer into a pointer type. */ /** * GULONG_FROM_BE: * @val: a #gulong value in big-endian byte order * * Converts a #gulong value from big-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GULONG_FROM_LE: * @val: a #gulong value in little-endian byte order * * Converts a #gulong value from little-endian to host byte order. * * Returns: @val converted to host byte order */ /** * GULONG_TO_BE: * @val: a #gulong value in host byte order * * Converts a #gulong value from host byte order to big-endian. * * Returns: @val converted to big-endian */ /** * GULONG_TO_LE: * @val: a #gulong value in host byte order * * Converts a #gulong value from host byte order to little-endian. * * Returns: @val converted to little-endian */ /** * GVariant: * * #GVariant is an opaque data structure and can only be accessed * using the following functions. * * Since: 2.24 */ /** * GVariantBuilder: * * A utility type for constructing container-type #GVariant instances. * * This is an opaque structure and may only be accessed using the * following functions. * * #GVariantBuilder is not threadsafe in any way. Do not attempt to * access it from more than one thread. */ /** * GVariantClass: * @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean. * @G_VARIANT_CLASS_BYTE: The #GVariant is a byte. * @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer. * @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer. * @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer. * @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer. * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer. * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer. * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index. * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating * point value. * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string. * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path * string. * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string. * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant. * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value. * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array. * @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple. * @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry. * * The range of possible top-level types of #GVariant instances. * * Since: 2.24 */ /** * GVariantDict: * * #GVariantDict is a mutable interface to #GVariant dictionaries. * * It can be used for doing a sequence of dictionary lookups in an * efficient way on an existing #GVariant dictionary or it can be used * to construct new dictionaries with a hashtable-like interface. It * can also be used for taking existing dictionaries and modifying them * in order to create new ones. * * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT * dictionaries. * * It is possible to use #GVariantDict allocated on the stack or on the * heap. When using a stack-allocated #GVariantDict, you begin with a * call to g_variant_dict_init() and free the resources with a call to * g_variant_dict_clear(). * * Heap-allocated #GVariantDict follows normal refcounting rules: you * allocate it with g_variant_dict_new() and use g_variant_dict_ref() * and g_variant_dict_unref(). * * g_variant_dict_end() is used to convert the #GVariantDict back into a * dictionary-type #GVariant. When used with stack-allocated instances, * this also implicitly frees all associated memory, but for * heap-allocated instances, you must still call g_variant_dict_unref() * afterwards. * * You will typically want to use a heap-allocated #GVariantDict when * you expose it as part of an API. For most other uses, the * stack-allocated form will be more convenient. * * Consider the following two examples that do the same thing in each * style: take an existing dictionary and look up the "count" uint32 * key, adding 1 to it if it is found, or returning an error if the * key is not found. Each returns the new dictionary as a floating * #GVariant. * * ## Using a stack-allocated GVariantDict * * |[ * GVariant * * add_to_count (GVariant *orig, * GError **error) * { * GVariantDict dict; * guint32 count; * * g_variant_dict_init (&dict, orig); * if (!g_variant_dict_lookup (&dict, "count", "u", &count)) * { * g_set_error (...); * g_variant_dict_clear (&dict); * return NULL; * } * * g_variant_dict_insert (&dict, "count", "u", count + 1); * * return g_variant_dict_end (&dict); * } * ]| * * ## Using heap-allocated GVariantDict * * |[ * GVariant * * add_to_count (GVariant *orig, * GError **error) * { * GVariantDict *dict; * GVariant *result; * guint32 count; * * dict = g_variant_dict_new (orig); * * if (g_variant_dict_lookup (dict, "count", "u", &count)) * { * g_variant_dict_insert (dict, "count", "u", count + 1); * result = g_variant_dict_end (dict); * } * else * { * g_set_error (...); * result = NULL; * } * * g_variant_dict_unref (dict); * * return result; * } * ]| * * Since: 2.40 */ /** * GVariantIter: (skip) * * #GVariantIter is an opaque data structure and can only be accessed * using the following functions. */ /** * GVariantParseError: * @G_VARIANT_PARSE_ERROR_FAILED: generic error (unused) * @G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED: a non-basic #GVariantType was given where a basic type was expected * @G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE: cannot infer the #GVariantType * @G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED: an indefinite #GVariantType was given where a definite type was expected * @G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END: extra data after parsing finished * @G_VARIANT_PARSE_ERROR_INVALID_CHARACTER: invalid character in number or unicode escape * @G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING: not a valid #GVariant format string * @G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH: not a valid object path * @G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE: not a valid type signature * @G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING: not a valid #GVariant type string * @G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE: could not find a common type for array entries * @G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE: the numerical value is out of range of the given type * @G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG: the numerical value is out of range for any type * @G_VARIANT_PARSE_ERROR_TYPE_ERROR: cannot parse as variant of the specified type * @G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN: an unexpected token was encountered * @G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD: an unknown keyword was encountered * @G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT: unterminated string constant * @G_VARIANT_PARSE_ERROR_VALUE_EXPECTED: no value given * * Error codes returned by parsing text-format GVariants. */ /** * G_ASCII_DTOSTR_BUF_SIZE: * * A good size for a buffer to be passed into g_ascii_dtostr(). * It is guaranteed to be enough for all output of that function * on systems with 64bit IEEE-compatible doubles. * * The typical usage would be something like: * |[ * char buf[G_ASCII_DTOSTR_BUF_SIZE]; * * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); * ]| */ /** * G_ATOMIC_LOCK_FREE: * * This macro is defined if the atomic operations of GLib are * implemented using real hardware atomic operations. This means that * the GLib atomic API can be used between processes and safely mixed * with other (hardware) atomic APIs. * * If this macro is not defined, the atomic operations may be * emulated using a mutex. In that case, the GLib atomic operations are * only atomic relative to themselves and within a single process. */ /** * G_BEGIN_DECLS: * * Used (along with #G_END_DECLS) to bracket header files. If the * compiler in use is a C++ compiler, adds extern "C" * around the header. */ /** * G_BIG_ENDIAN: * * Specifies one of the possible types of byte order. * See #G_BYTE_ORDER. */ /** * G_BYTE_ORDER: * * The host byte order. * This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for * #G_PDP_ENDIAN may be added in future.) */ /** * G_CONST_RETURN: * * If %G_DISABLE_CONST_RETURNS is defined, this macro expands * to nothing. By default, the macro expands to const. The macro * can be used in place of const for functions that return a value * that should not be modified. The purpose of this macro is to allow * us to turn on const for returned constant strings by default, while * allowing programmers who find that annoying to turn it off. This macro * should only be used for return values and for "out" parameters, it * doesn't make sense for "in" parameters. * * Deprecated: 2.30: API providers should replace all existing uses with * const and API consumers should adjust their code accordingly */ /** * G_CSET_A_2_Z: * * The set of uppercase ASCII alphabet characters. * Used for specifying valid identifier characters * in #GScannerConfig. */ /** * G_CSET_DIGITS: * * The set of ASCII digits. * Used for specifying valid identifier characters * in #GScannerConfig. */ /** * G_CSET_LATINC: * * The set of uppercase ISO 8859-1 alphabet characters * which are not ASCII characters. * Used for specifying valid identifier characters * in #GScannerConfig. */ /** * G_CSET_LATINS: * * The set of lowercase ISO 8859-1 alphabet characters * which are not ASCII characters. * Used for specifying valid identifier characters * in #GScannerConfig. */ /** * G_CSET_a_2_z: * * The set of lowercase ASCII alphabet characters. * Used for specifying valid identifier characters * in #GScannerConfig. */ /** * G_DATE_BAD_DAY: * * Represents an invalid #GDateDay. */ /** * G_DATE_BAD_JULIAN: * * Represents an invalid Julian day number. */ /** * G_DATE_BAD_YEAR: * * Represents an invalid year. */ /** * G_DEFINE_AUTOPTR_CLEANUP_FUNC: * @TypeName: a type name to define a g_autoptr() cleanup function for * @func: the cleanup function * * Defines the appropriate cleanup function for a pointer type. * * The function will not be called if the variable to be cleaned up * contains %NULL. * * This will typically be the _free() or _unref() function for the given * type. * * With this definition, it will be possible to use g_autoptr() with * @TypeName. * * |[ * G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref) * ]| * * This macro should be used unconditionally; it is a no-op on compilers * where cleanup is not supported. * * Since: 2.44 */ /** * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC: * @TypeName: a type name to define a g_auto() cleanup function for * @func: the clear function * * Defines the appropriate cleanup function for a type. * * This will typically be the _clear() function for the given type. * * With this definition, it will be possible to use g_auto() with * @TypeName. * * |[ * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear) * ]| * * This macro should be used unconditionally; it is a no-op on compilers * where cleanup is not supported. * * Since: 2.44 */ /** * G_DEFINE_AUTO_CLEANUP_FREE_FUNC: * @TypeName: a type name to define a g_auto() cleanup function for * @func: the free function * @none: the "none" value for the type * * Defines the appropriate cleanup function for a type. * * With this definition, it will be possible to use g_auto() with * @TypeName. * * This function will be rarely used. It is used with pointer-based * typedefs and non-pointer types where the value of the variable * represents a resource that must be freed. Two examples are #GStrv * and file descriptors. * * @none specifies the "none" value for the type in question. It is * probably something like %NULL or -1. If the variable is found to * contain this value then the free function will not be called. * * |[ * G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL) * ]| * * This macro should be used unconditionally; it is a no-op on compilers * where cleanup is not supported. * * Since: 2.44 */ /** * G_DEFINE_QUARK: * @QN: the name to return a #GQuark for * @q_n: prefix for the function name * * A convenience macro which defines a function returning the * #GQuark for the name @QN. The function will be named * @q_n_quark(). * * Note that the quark name will be stringified automatically * in the macro, so you shouldn't use double quotes. * * Since: 2.34 */ /** * G_DEPRECATED: * * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is * meant to be portable across different compilers and must be placed * before the function declaration. * * Since: 2.32 */ /** * G_DEPRECATED_FOR: * @f: the name of the function that this function was deprecated for * * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it * is meant to be portable across different compilers and must be placed * before the function declaration. * * Since: 2.32 */ /** * G_DIR_SEPARATOR: * * The directory separator character. * This is '/' on UNIX machines and '\' under Windows. */ /** * G_DIR_SEPARATOR_S: * * The directory separator as a string. * This is "/" on UNIX machines and "\" under Windows. */ /** * G_E: * * The base of natural logarithms. */ /** * G_END_DECLS: * * Used (along with #G_BEGIN_DECLS) to bracket header files. If the * compiler in use is a C++ compiler, adds extern "C" * around the header. */ /** * G_FILE_ERROR: * * Error domain for file operations. Errors in this domain will * be from the #GFileError enumeration. See #GError for information * on error domains. */ /** * G_GINT16_FORMAT: * * This is the platform dependent conversion specifier for scanning and * printing values of type #gint16. It is a string literal, but doesn't * include the percent-sign, such that you can add precision and length * modifiers between percent-sign and conversion specifier. * * |[ * gint16 in; * gint32 out; * sscanf ("42", "%" G_GINT16_FORMAT, &in) * out = in * 1000; * g_print ("%" G_GINT32_FORMAT, out); * ]| */ /** * G_GINT16_MODIFIER: * * The platform dependent length modifier for conversion specifiers * for scanning and printing values of type #gint16 or #guint16. It * is a string literal, but doesn't include the percent-sign, such * that you can add precision and length modifiers between percent-sign * and conversion specifier and append a conversion specifier. * * The following example prints "0x7b"; * |[ * gint16 value = 123; * g_print ("%#" G_GINT16_MODIFIER "x", value); * ]| * * Since: 2.4 */ /** * G_GINT32_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #gint32. See also #G_GINT16_FORMAT. */ /** * G_GINT32_MODIFIER: * * The platform dependent length modifier for conversion specifiers * for scanning and printing values of type #gint32 or #guint32. It * is a string literal. See also #G_GINT16_MODIFIER. * * Since: 2.4 */ /** * G_GINT64_CONSTANT: * @val: a literal integer value, e.g. 0x1d636b02300a7aa7 * * This macro is used to insert 64-bit integer literals * into the source code. */ /** * G_GINT64_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #gint64. See also #G_GINT16_FORMAT. * * Some platforms do not support scanning and printing 64-bit integers, * even though the types are supported. On such platforms %G_GINT64_FORMAT * is not defined. Note that scanf() may not support 64-bit integers, even * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() * is not recommended for parsing anyway; consider using g_ascii_strtoull() * instead. */ /** * G_GINT64_MODIFIER: * * The platform dependent length modifier for conversion specifiers * for scanning and printing values of type #gint64 or #guint64. * It is a string literal. * * Some platforms do not support printing 64-bit integers, even * though the types are supported. On such platforms %G_GINT64_MODIFIER * is not defined. * * Since: 2.4 */ /** * G_GINTPTR_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #gintptr. * * Since: 2.22 */ /** * G_GINTPTR_MODIFIER: * * The platform dependent length modifier for conversion specifiers * for scanning and printing values of type #gintptr or #guintptr. * It is a string literal. * * Since: 2.22 */ /** * G_GNUC_ALLOC_SIZE: * @x: the index of the argument specifying the allocation size * * Expands to the GNU C alloc_size function attribute if the compiler * is a new enough gcc. This attribute tells the compiler that the * function returns a pointer to memory of a size that is specified * by the @xth function parameter. * * Place the attribute after the function declaration, just before the * semicolon. * * See the GNU C documentation for more details. * * Since: 2.18 */ /** * G_GNUC_ALLOC_SIZE2: * @x: the index of the argument specifying one factor of the allocation size * @y: the index of the argument specifying the second factor of the allocation size * * Expands to the GNU C alloc_size function attribute if the compiler is a * new enough gcc. This attribute tells the compiler that the function returns * a pointer to memory of a size that is specified by the product of two * function parameters. * * Place the attribute after the function declaration, just before the * semicolon. * * See the GNU C documentation for more details. * * Since: 2.18 */ /** * G_GNUC_BEGIN_IGNORE_DEPRECATIONS: * * Tells gcc (if it is a new enough version) to temporarily stop emitting * warnings when functions marked with %G_GNUC_DEPRECATED or * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have * one deprecated function calling another one, or when you still have * regression tests for deprecated functions. * * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you * are not compiling with `-Wdeprecated-declarations` then neither macro * has any effect.) * * This macro can be used either inside or outside of a function body, * but must appear on a line by itself. * * Since: 2.32 */ /** * G_GNUC_CHECK_VERSION: * @major: major version to check against * @minor: minor version to check against * * Expands to a a check for a compiler with __GNUC__ defined and a version * greater than or equal to the major and minor numbers provided. For example, * the following would only match on compilers such as GCC 4.8 or newer. * * |[ * #if G_GNUC_CHECK_VERSION(4, 8) * #endif * ]| * * Since: 2.42 */ /** * G_GNUC_CONST: * * Expands to the GNU C const function attribute if the compiler is gcc. * Declaring a function as const enables better optimization of calls to * the function. A const function doesn't examine any values except its * parameters, and has no effects except its return value. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. * * A function that has pointer arguments and examines the data pointed to * must not be declared const. Likewise, a function that calls a non-const * function usually must not be const. It doesn't make sense for a const * function to return void. */ /** * G_GNUC_DEPRECATED: * * Expands to the GNU C deprecated attribute if the compiler is gcc. * It can be used to mark typedefs, variables and functions as deprecated. * When called with the `-Wdeprecated-declarations` option, * gcc will generate warnings when deprecated interfaces are used. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. * * Since: 2.2 */ /** * G_GNUC_DEPRECATED_FOR: * @f: the intended replacement for the deprecated symbol, * such as the name of a function * * Like %G_GNUC_DEPRECATED, but names the intended replacement for the * deprecated symbol if the version of gcc in use is new enough to support * custom deprecation messages. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. * * Note that if @f is a macro, it will be expanded in the warning message. * You can enclose it in quotes to prevent this. (The quotes will show up * in the warning, but it's better than showing the macro expansion.) * * Since: 2.26 */ /** * G_GNUC_END_IGNORE_DEPRECATIONS: * * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling * gcc to begin outputting warnings again (assuming those warnings * had been enabled to begin with). * * This macro can be used either inside or outside of a function body, * but must appear on a line by itself. * * Since: 2.32 */ /** * G_GNUC_EXTENSION: * * Expands to __extension__ when gcc is used as the compiler. This simply * tells gcc not to warn about the following non-standard code when compiling * with the `-pedantic` option. */ /** * G_GNUC_FORMAT: * @arg_idx: the index of the argument * * Expands to the GNU C format_arg function attribute if the compiler * is gcc. This function attribute specifies that a function takes a * format string for a printf(), scanf(), strftime() or strfmon() style * function and modifies it, so that the result can be passed to a printf(), * scanf(), strftime() or strfmon() style function (with the remaining * arguments to the format function the same as they would have been * for the unmodified string). * * Place the attribute after the function declaration, just before the * semicolon. * * See the GNU C documentation for more details. * * |[ * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); * ]| */ /** * G_GNUC_FUNCTION: * * Expands to "" on all modern compilers, and to __FUNCTION__ on gcc * version 2.x. Don't use it. * * Deprecated: 2.16: Use G_STRFUNC() instead */ /** * G_GNUC_INTERNAL: * * This attribute can be used for marking library functions as being used * internally to the library only, which may allow the compiler to handle * function calls more efficiently. Note that static functions do not need * to be marked as internal in this way. See the GNU C documentation for * details. * * When using a compiler that supports the GNU C hidden visibility attribute, * this macro expands to __attribute__((visibility("hidden"))). * When using the Sun Studio compiler, it expands to __hidden. * * Note that for portability, the attribute should be placed before the * function declaration. While GCC allows the macro after the declaration, * Sun Studio does not. * * |[ * G_GNUC_INTERNAL * void _g_log_fallback_handler (const gchar *log_domain, * GLogLevelFlags log_level, * const gchar *message, * gpointer unused_data); * ]| * * Since: 2.6 */ /** * G_GNUC_MALLOC: * * Expands to the GNU C malloc function attribute if the compiler is gcc. * Declaring a function as malloc enables better optimization of the function. * A function can have the malloc attribute if it returns a pointer which is * guaranteed to not alias with any other pointer when the function returns * (in practice, this means newly allocated memory). * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. * * Since: 2.6 */ /** * G_GNUC_MAY_ALIAS: * * Expands to the GNU C may_alias type attribute if the compiler is gcc. * Types with this attribute will not be subjected to type-based alias * analysis, but are assumed to alias with any other type, just like char. * * See the GNU C documentation for details. * * Since: 2.14 */ /** * G_GNUC_NORETURN: * * Expands to the GNU C noreturn function attribute if the compiler is gcc. * It is used for declaring functions which never return. It enables * optimization of the function, and avoids possible compiler warnings. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. */ /** * G_GNUC_NO_INSTRUMENT: * * Expands to the GNU C no_instrument_function function attribute if the * compiler is gcc. Functions with this attribute will not be instrumented * for profiling, when the compiler is called with the * `-finstrument-functions` option. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. */ /** * G_GNUC_NULL_TERMINATED: * * Expands to the GNU C sentinel function attribute if the compiler is gcc. * This function attribute only applies to variadic functions and instructs * the compiler to check that the argument list is terminated with an * explicit %NULL. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. * * Since: 2.8 */ /** * G_GNUC_PRETTY_FUNCTION: * * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ * on gcc version 2.x. Don't use it. * * Deprecated: 2.16: Use G_STRFUNC() instead */ /** * G_GNUC_PRINTF: * @format_idx: the index of the argument corresponding to the * format string (the arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments, or 0 if * there are no format arguments * * Expands to the GNU C format function attribute if the compiler is gcc. * This is used for declaring functions which take a variable number of * arguments, with the same syntax as printf(). It allows the compiler * to type-check the arguments passed to the function. * * Place the attribute after the function declaration, just before the * semicolon. * * See the * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) * for more details. * * |[ * gint g_snprintf (gchar *string, * gulong n, * gchar const *format, * ...) G_GNUC_PRINTF (3, 4); * ]| */ /** * G_GNUC_PURE: * * Expands to the GNU C pure function attribute if the compiler is gcc. * Declaring a function as pure enables better optimization of calls to * the function. A pure function has no effects except its return value * and the return value depends only on the parameters and/or global * variables. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. */ /** * G_GNUC_SCANF: * @format_idx: the index of the argument corresponding to * the format string (the arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments, or 0 if * there are no format arguments * * Expands to the GNU C format function attribute if the compiler is gcc. * This is used for declaring functions which take a variable number of * arguments, with the same syntax as scanf(). It allows the compiler * to type-check the arguments passed to the function. * * See the * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) * for details. */ /** * G_GNUC_UNUSED: * * Expands to the GNU C unused function attribute if the compiler is gcc. * It is used for declaring functions and arguments which may never be used. * It avoids possible compiler warnings. * * For functions, place the attribute after the declaration, just before the * semicolon. For arguments, place the attribute at the beginning of the * argument declaration. * * |[ * void my_unused_function (G_GNUC_UNUSED gint unused_argument, * gint other_argument) G_GNUC_UNUSED; * ]| * * See the GNU C documentation for more details. */ /** * G_GNUC_WARN_UNUSED_RESULT: * * Expands to the GNU C warn_unused_result function attribute if the compiler * is gcc. This function attribute makes the compiler emit a warning if the * result of a function call is ignored. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. * * Since: 2.10 */ /** * G_GOFFSET_CONSTANT: * @val: a literal integer value, e.g. 0x1d636b02300a7aa7 * * This macro is used to insert #goffset 64-bit integer literals * into the source code. * * See also #G_GINT64_CONSTANT. * * Since: 2.20 */ /** * G_GOFFSET_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #goffset. See also #G_GINT64_FORMAT. * * Since: 2.20 */ /** * G_GOFFSET_MODIFIER: * * The platform dependent length modifier for conversion specifiers * for scanning and printing values of type #goffset. It is a string * literal. See also #G_GINT64_MODIFIER. * * Since: 2.20 */ /** * G_GSIZE_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #gsize. See also #G_GINT16_FORMAT. * * Since: 2.6 */ /** * G_GSIZE_MODIFIER: * * The platform dependent length modifier for conversion specifiers * for scanning and printing values of type #gsize. It * is a string literal. * * Since: 2.6 */ /** * G_GSSIZE_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #gssize. See also #G_GINT16_FORMAT. * * Since: 2.6 */ /** * G_GSSIZE_MODIFIER: * * The platform dependent length modifier for conversion specifiers * for scanning and printing values of type #gssize. It * is a string literal. * * Since: 2.6 */ /** * G_GUINT16_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #guint16. See also #G_GINT16_FORMAT */ /** * G_GUINT32_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #guint32. See also #G_GINT16_FORMAT. */ /** * G_GUINT64_CONSTANT: * @val: a literal integer value, e.g. 0x1d636b02300a7aa7U * * This macro is used to insert 64-bit unsigned integer * literals into the source code. * * Since: 2.10 */ /** * G_GUINT64_FORMAT: * * This is the platform dependent conversion specifier for scanning * and printing values of type #guint64. See also #G_GINT16_FORMAT. * * Some platforms do not support scanning and printing 64-bit integers, * even though the types are supported. On such platforms %G_GUINT64_FORMAT * is not defined. Note that scanf() may not support 64-bit integers, even * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() * is not recommended for parsing anyway; consider using g_ascii_strtoull() * instead. */ /** * G_GUINTPTR_FORMAT: * * This is the platform dependent conversion specifier * for scanning and printing values of type #guintptr. * * Since: 2.22 */ /** * G_HAVE_GNUC_VISIBILITY: * * Defined to 1 if gcc-style visibility handling is supported. */ /** * G_HOOK: * @hook: a pointer * * Casts a pointer to a `GHook*`. */ /** * G_HOOK_ACTIVE: * @hook: a #GHook * * Returns %TRUE if the #GHook is active, which is normally the case * until the #GHook is destroyed. * * Returns: %TRUE if the #GHook is active */ /** * G_HOOK_FLAGS: * @hook: a #GHook * * Gets the flags of a hook. */ /** * G_HOOK_FLAG_USER_SHIFT: * * The position of the first bit which is not reserved for internal * use be the #GHook implementation, i.e. * `1 << G_HOOK_FLAG_USER_SHIFT` is the first * bit which can be used for application-defined flags. */ /** * G_HOOK_IN_CALL: * @hook: a #GHook * * Returns %TRUE if the #GHook function is currently executing. * * Returns: %TRUE if the #GHook function is currently executing */ /** * G_HOOK_IS_UNLINKED: * @hook: a #GHook * * Returns %TRUE if the #GHook is not in a #GHookList. * * Returns: %TRUE if the #GHook is not in a #GHookList */ /** * G_HOOK_IS_VALID: * @hook: a #GHook * * Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, * it is active and it has not been destroyed. * * Returns: %TRUE if the #GHook is valid */ /** * G_IEEE754_DOUBLE_BIAS: * * The bias by which exponents in double-precision floats are offset. */ /** * G_IEEE754_FLOAT_BIAS: * * The bias by which exponents in single-precision floats are offset. */ /** * G_INLINE_FUNC: * * This macro used to be used to conditionally define inline functions * in a compatible way before this feature was supported in all * compilers. These days, GLib requires inlining support from the * compiler, so your GLib-using programs can safely assume that the * "inline" keywork works properly. * * Never use this macro anymore. Just say "static inline". * * Deprecated: 2.48: Use "static inline" instead */ /** * G_IO_CHANNEL_ERROR: * * Error domain for #GIOChannel operations. Errors in this domain will * be from the #GIOChannelError enumeration. See #GError for * information on error domains. */ /** * G_IS_DIR_SEPARATOR: * @c: a character * * Checks whether a character is a directory * separator. It returns %TRUE for '/' on UNIX * machines and for '\' or '/' under Windows. * * Since: 2.6 */ /** * G_KEY_FILE_DESKTOP_GROUP: * * The name of the main group of a desktop entry file, as defined in the * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec). * Consult the specification for more * details about the meanings of the keys below. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_ACTIONS: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list * giving the available application actions. * * Since: 2.38 */ /** * G_KEY_FILE_DESKTOP_KEY_CATEGORIES: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list * of strings giving the categories in which the desktop entry * should be shown in a menu. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_COMMENT: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the tooltip for the desktop entry. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true * if the application is D-Bus activatable. * * Since: 2.38 */ /** * G_KEY_FILE_DESKTOP_KEY_EXEC: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the command line to execute. It is only valid for desktop * entries with the `Application` type. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the generic name of the desktop entry. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_HIDDEN: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the desktop entry has been deleted by the user. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_ICON: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the name of the icon to be displayed for the desktop * entry. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list * of strings giving the MIME types supported by this desktop entry. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_NAME: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the specific name of the desktop entry. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of * strings identifying the environments that should not display the * desktop entry. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the desktop entry should be shown in menus. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of * strings identifying the environments that should display the * desktop entry. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_PATH: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * containing the working directory to run the program in. It is only * valid for desktop entries with the `Application` type. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the application supports the * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string * identifying the WM class or name hint of a window that the application * will create, which can be used to emulate Startup Notification with * older applications. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_TERMINAL: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the program should be run in a terminal window. * It is only valid for desktop entries with the * `Application` type. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the file name of a binary on disk used to determine if the * program is actually installed. It is only valid for desktop entries * with the `Application` type. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_TYPE: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the type of the desktop entry. Usually * #G_KEY_FILE_DESKTOP_TYPE_APPLICATION, * #G_KEY_FILE_DESKTOP_TYPE_LINK, or * #G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_URL: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the URL to access. It is only valid for desktop entries * with the `Link` type. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_KEY_VERSION: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the version of the Desktop Entry Specification used for * the desktop entry file. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_TYPE_APPLICATION: * * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing applications. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY: * * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing directories. * * Since: 2.14 */ /** * G_KEY_FILE_DESKTOP_TYPE_LINK: * * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing links to documents. * * Since: 2.14 */ /** * G_KEY_FILE_ERROR: * * Error domain for key file parsing. Errors in this domain will * be from the #GKeyFileError enumeration. * * See #GError for information on error domains. */ /** * G_LIKELY: * @expr: the expression * * Hints the compiler that the expression is likely to evaluate to * a true value. The compiler may use this information for optimizations. * * |[ * if (G_LIKELY (random () != 1)) * g_print ("not one"); * ]| * * Returns: the value of @expr * Since: 2.2 */ /** * G_LITTLE_ENDIAN: * * Specifies one of the possible types of byte order. * See #G_BYTE_ORDER. */ /** * G_LN10: * * The natural logarithm of 10. */ /** * G_LN2: * * The natural logarithm of 2. */ /** * G_LOCK: * @name: the name of the lock * * Works like g_mutex_lock(), but for a lock defined with * #G_LOCK_DEFINE. */ /** * G_LOCK_DEFINE: * @name: the name of the lock * * The #G_LOCK_ macros provide a convenient interface to #GMutex. * #G_LOCK_DEFINE defines a lock. It can appear in any place where * variable definitions may appear in programs, i.e. in the first block * of a function or outside of functions. The @name parameter will be * mangled to get the name of the #GMutex. This means that you * can use names of existing variables as the parameter - e.g. the name * of the variable you intend to protect with the lock. Look at our * give_me_next_number() example using the #G_LOCK macros: * * Here is an example for using the #G_LOCK convenience macros: * |[ * G_LOCK_DEFINE (current_number); * * int * give_me_next_number (void) * { * static int current_number = 0; * int ret_val; * * G_LOCK (current_number); * ret_val = current_number = calc_next_number (current_number); * G_UNLOCK (current_number); * * return ret_val; * } * ]| */ /** * G_LOCK_DEFINE_STATIC: * @name: the name of the lock * * This works like #G_LOCK_DEFINE, but it creates a static object. */ /** * G_LOCK_EXTERN: * @name: the name of the lock * * This declares a lock, that is defined with #G_LOCK_DEFINE in another * module. */ /** * G_LOG_2_BASE_10: * * Multiplying the base 2 exponent by this number yields the base 10 exponent. */ /** * G_LOG_DOMAIN: * * Defines the log domain. See [Log Domains](#log-domains). * * Libraries should define this so that any messages * which they log can be differentiated from messages from other * libraries and application code. But be careful not to define * it in any public header files. * * Log domains must be unique, and it is recommended that they are the * application or library name, optionally followed by a hyphen and a sub-domain * name. For example, `bloatpad` or `bloatpad-io`. * * If undefined, it defaults to the default %NULL (or `""`) log domain; this is * not advisable, as it cannot be filtered against using the `G_MESSAGES_DEBUG` * environment variable. * * For example, GTK+ uses this in its `Makefile.am`: * |[ * AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\" * ]| * * Applications can choose to leave it as the default %NULL (or `""`) * domain. However, defining the domain offers the same advantages as * above. */ /** * G_LOG_FATAL_MASK: * * GLib log levels that are considered fatal by default. * * This is not used if structured logging is enabled; see * [Using Structured Logging][using-structured-logging]. */ /** * G_LOG_LEVEL_USER_SHIFT: * * Log levels below 1< * GOnce my_once = G_ONCE_INIT; * ]| * * Since: 2.4 */ /** * G_OS_UNIX: * * This macro is defined only on UNIX. So you can bracket * UNIX-specific code in "\#ifdef G_OS_UNIX". */ /** * G_OS_WIN32: * * This macro is defined only on Windows. So you can bracket * Windows-specific code in "\#ifdef G_OS_WIN32". */ /** * G_PASTE: * @identifier1: an identifier * @identifier2: an identifier * * Yields a new preprocessor pasted identifier * @identifier1identifier2 from its expanded * arguments @identifier1 and @identifier2. For example, * the following code: * |[ * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller) * const gchar *name = GET (traveller, name); * const gchar *quest = GET (traveller, quest); * GdkColor *favourite = GET (traveller, favourite_colour); * ]| * * is transformed by the preprocessor into: * |[ * const gchar *name = traveller_get_name (traveller); * const gchar *quest = traveller_get_quest (traveller); * GdkColor *favourite = traveller_get_favourite_colour (traveller); * ]| * * Since: 2.20 */ /** * G_PDP_ENDIAN: * * Specifies one of the possible types of byte order * (currently unused). See #G_BYTE_ORDER. */ /** * G_PI: * * The value of pi (ratio of circle's circumference to its diameter). */ /** * G_PI_2: * * Pi divided by 2. */ /** * G_PI_4: * * Pi divided by 4. */ /** * G_PRIVATE_INIT: * @notify: a #GDestroyNotify * * A macro to assist with the static initialisation of a #GPrivate. * * This macro is useful for the case that a #GDestroyNotify function * should be associated with the key. This is needed when the key will be * used to point at memory that should be deallocated when the thread * exits. * * Additionally, the #GDestroyNotify will also be called on the previous * value stored in the key when g_private_replace() is used. * * If no #GDestroyNotify is needed, then use of this macro is not * required -- if the #GPrivate is declared in static scope then it will * be properly initialised by default (ie: to all zeros). See the * examples below. * * |[ * static GPrivate name_key = G_PRIVATE_INIT (g_free); * * // return value should not be freed * const gchar * * get_local_name (void) * { * return g_private_get (&name_key); * } * * void * set_local_name (const gchar *name) * { * g_private_replace (&name_key, g_strdup (name)); * } * * * static GPrivate count_key; // no free function * * gint * get_local_count (void) * { * return GPOINTER_TO_INT (g_private_get (&count_key)); * } * * void * set_local_count (gint count) * { * g_private_set (&count_key, GINT_TO_POINTER (count)); * } * ]| * * Since: 2.32 */ /** * G_SEARCHPATH_SEPARATOR: * * The search path separator character. * This is ':' on UNIX machines and ';' under Windows. */ /** * G_SEARCHPATH_SEPARATOR_S: * * The search path separator as a string. * This is ":" on UNIX machines and ";" under Windows. */ /** * G_SHELL_ERROR: * * Error domain for shell functions. Errors in this domain will be from * the #GShellError enumeration. See #GError for information on error * domains. */ /** * G_SQRT2: * * The square root of two. */ /** * G_STATIC_ASSERT: * @expr: a constant expression * * The G_STATIC_ASSERT() macro lets the programmer check * a condition at compile time, the condition needs to * be compile time computable. The macro can be used in * any place where a typedef is valid. * * A typedef is generally allowed in exactly the same places that * a variable declaration is allowed. For this reason, you should * not use G_STATIC_ASSERT() in the middle of blocks of code. * * The macro should only be used once per source code line. * * Since: 2.20 */ /** * G_STATIC_ASSERT_EXPR: * @expr: a constant expression * * The G_STATIC_ASSERT_EXPR() macro lets the programmer check * a condition at compile time. The condition needs to be * compile time computable. * * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression * and, as such, can be used in the middle of other expressions. * Its value should be ignored. This can be accomplished by placing * it as the first argument of a comma expression. * * |[ * #define ADD_ONE_TO_INT(x) \ * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1)) * ]| * * Since: 2.30 */ /** * G_STMT_END: * * Used within multi-statement macros so that they can be used in places * where only one statement is expected by the compiler. */ /** * G_STMT_START: * * Used within multi-statement macros so that they can be used in places * where only one statement is expected by the compiler. */ /** * G_STRFUNC: * * Expands to a string identifying the current function. * * Since: 2.4 */ /** * G_STRINGIFY: * @macro_or_string: a macro or a string * * Accepts a macro or a string and converts it into a string after * preprocessor argument expansion. For example, the following code: * * |[ * #define AGE 27 * const gchar *greeting = G_STRINGIFY (AGE) " today!"; * ]| * * is transformed by the preprocessor into (code equivalent to): * * |[ * const gchar *greeting = "27 today!"; * ]| */ /** * G_STRLOC: * * Expands to a string identifying the current code position. */ /** * G_STRUCT_MEMBER: * @member_type: the type of the struct field * @struct_p: a pointer to a struct * @struct_offset: the offset of the field from the start of the struct, * in bytes * * Returns a member of a structure at a given offset, using the given type. * * Returns: the struct member */ /** * G_STRUCT_MEMBER_P: * @struct_p: a pointer to a struct * @struct_offset: the offset from the start of the struct, in bytes * * Returns an untyped pointer to a given offset of a struct. * * Returns: an untyped pointer to @struct_p plus @struct_offset bytes */ /** * G_STRUCT_OFFSET: * @struct_type: a structure type, e.g. #GtkWidget * @member: a field in the structure, e.g. @window * * Returns the offset, in bytes, of a member of a struct. * * Returns: the offset of @member from the start of @struct_type */ /** * G_STR_DELIMITERS: * * The standard delimiters, used in g_strdelimit(). */ /** * G_THREAD_ERROR: * * The error domain of the GLib thread subsystem. */ /** * G_TRYLOCK: * @name: the name of the lock * * Works like g_mutex_trylock(), but for a lock defined with * #G_LOCK_DEFINE. * * Returns: %TRUE, if the lock could be locked. */ /** * G_UNAVAILABLE: * @maj: the major version that introduced the symbol * @min: the minor version that introduced the symbol * * This macro can be used to mark a function declaration as unavailable. * It must be placed before the function declaration. Use of a function * that has been annotated with this macros will produce a compiler warning. * * Since: 2.32 */ /** * G_UNLIKELY: * @expr: the expression * * Hints the compiler that the expression is unlikely to evaluate to * a true value. The compiler may use this information for optimizations. * * |[ * if (G_UNLIKELY (random () == 1)) * g_print ("a random one"); * ]| * * Returns: the value of @expr * Since: 2.2 */ /** * G_UNLOCK: * @name: the name of the lock * * Works like g_mutex_unlock(), but for a lock defined with * #G_LOCK_DEFINE. */ /** * G_USEC_PER_SEC: * * Number of microseconds in one second (1 million). * This macro is provided for code readability. */ /** * G_VARIANT_PARSE_ERROR: * * Error domain for GVariant text format parsing. Specific error codes * are not currently defined for this domain. See #GError for * information on error domains. */ /** * G_VA_COPY: * @ap1: the va_list variable to place a copy of @ap2 in * @ap2: a va_list * * Portable way to copy va_list variables. * * In order to use this function, you must include string.h yourself, * because this macro may use memmove() and GLib does not include * string.h for you. */ /** * G_WIN32_DLLMAIN_FOR_DLL_NAME: * @static: empty or "static" * @dll_name: the name of the (pointer to the) char array where * the DLL name will be stored. If this is used, you must also * include `windows.h`. If you need a more complex DLL entry * point function, you cannot use this * * On Windows, this macro defines a DllMain() function that stores * the actual DLL name that the code being compiled will be included in. * * On non-Windows platforms, expands to nothing. */ /** * G_WIN32_HAVE_WIDECHAR_API: * * On Windows, this macro defines an expression which evaluates to * %TRUE if the code is running on a version of Windows where the wide * character versions of the Win32 API functions, and the wide character * versions of the C library functions work. (They are always present in * the DLLs, but don't work on Windows 9x and Me.) * * On non-Windows platforms, it is not defined. * * Since: 2.6 */ /** * G_WIN32_IS_NT_BASED: * * On Windows, this macro defines an expression which evaluates to * %TRUE if the code is running on an NT-based Windows operating system. * * On non-Windows platforms, it is not defined. * * Since: 2.6 */ /** * MAX: * @a: a numeric value * @b: a numeric value * * Calculates the maximum of @a and @b. * * Returns: the maximum of @a and @b. */ /** * MAXPATHLEN: * * Provided for UNIX emulation on Windows; equivalent to UNIX * macro %MAXPATHLEN, which is the maximum length of a filename * (including full path). */ /** * MIN: * @a: a numeric value * @b: a numeric value * * Calculates the minimum of @a and @b. * * Returns: the minimum of @a and @b. */ /** * NC_: * @Context: a message context, must be a string literal * @String: a message id, must be a string literal * * Only marks a string for translation, with context. * This is useful in situations where the translated strings can't * be directly used, e.g. in string array initializers. To get the * translated string, you should call g_dpgettext2() at runtime. * * |[ * { * static const char *messages[] = { * NC_("some context", "some very meaningful message"), * NC_("some context", "and another one") * }; * const char *string; * ... * string * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message") * : g_dpgettext2 (NULL, "some context", messages[index]); * * fputs (string); * ... * } * ]| * * If you are using the NC_() macro, you need to make sure that you pass * `--keyword=NC_:1c,2` to xgettext when extracting messages. * Note that this only works with GNU gettext >= 0.15. Intltool has support * for the NC_() macro since version 0.40.1. * * Since: 2.18 */ /** * NULL: * * Defines the standard %NULL pointer. */ /** * N_: * @String: the string to be translated * * Only marks a string for translation. This is useful in situations * where the translated strings can't be directly used, e.g. in string * array initializers. To get the translated string, call gettext() * at runtime. * |[ * { * static const char *messages[] = { * N_("some very meaningful message"), * N_("and another one") * }; * const char *string; * ... * string * = index > 1 ? _("a default message") : gettext (messages[index]); * * fputs (string); * ... * } * ]| * * Since: 2.4 */ /** * Q_: * @String: the string to be translated, with a '|'-separated prefix * which must not be translated * * Like _(), but handles context in message ids. This has the advantage * that the string can be adorned with a prefix to guarantee uniqueness * and provide context to the translator. * * One use case given in the gettext manual is GUI translation, where one * could e.g. disambiguate two "Open" menu entries as "File|Open" and * "Printer|Open". Another use case is the string "Russian" which may * have to be translated differently depending on whether it's the name * of a character set or a language. This could be solved by using * "charset|Russian" and "language|Russian". * * See the C_() macro for a different way to mark up translatable strings * with context. * * If you are using the Q_() macro, you need to make sure that you pass * `--keyword=Q_` to xgettext when extracting messages. * If you are using GNU gettext >= 0.15, you can also use * `--keyword=Q_:1g` to let xgettext split the context * string off into a msgctxt line in the po file. * * Returns: the translated message * Since: 2.4 */ /** * SECTION:arrays * @title: Arrays * @short_description: arrays of arbitrary elements which grow * automatically as elements are added * * Arrays are similar to standard C arrays, except that they grow * automatically as elements are added. * * Array elements can be of any size (though all elements of one array * are the same size), and the array can be automatically cleared to * '0's and zero-terminated. * * To create a new array use g_array_new(). * * To add elements to an array, use g_array_append_val(), * g_array_append_vals(), g_array_prepend_val(), and * g_array_prepend_vals(). * * To access an element of an array, use g_array_index(). * * To set the size of an array, use g_array_set_size(). * * To free an array, use g_array_free(). * * Here is an example that stores integers in a #GArray: * |[ * GArray *garray; * gint i; * // We create a new array to store gint values. * // We don't want it zero-terminated or cleared to 0's. * garray = g_array_new (FALSE, FALSE, sizeof (gint)); * for (i = 0; i < 10000; i++) * g_array_append_val (garray, i); * for (i = 0; i < 10000; i++) * if (g_array_index (garray, gint, i) != i) * g_print ("ERROR: got %d instead of %d\n", * g_array_index (garray, gint, i), i); * g_array_free (garray, TRUE); * ]| */ /** * SECTION:arrays_byte * @title: Byte Arrays * @short_description: arrays of bytes * * #GByteArray is a mutable array of bytes based on #GArray, to provide arrays * of bytes which grow automatically as elements are added. * * To create a new #GByteArray use g_byte_array_new(). To add elements to a * #GByteArray, use g_byte_array_append(), and g_byte_array_prepend(). * * To set the size of a #GByteArray, use g_byte_array_set_size(). * * To free a #GByteArray, use g_byte_array_free(). * * An example for using a #GByteArray: * |[ * GByteArray *gbarray; * gint i; * * gbarray = g_byte_array_new (); * for (i = 0; i < 10000; i++) * g_byte_array_append (gbarray, (guint8*) "abcd", 4); * * for (i = 0; i < 10000; i++) * { * g_assert (gbarray->data[4*i] == 'a'); * g_assert (gbarray->data[4*i+1] == 'b'); * g_assert (gbarray->data[4*i+2] == 'c'); * g_assert (gbarray->data[4*i+3] == 'd'); * } * * g_byte_array_free (gbarray, TRUE); * ]| * * See #GBytes if you are interested in an immutable object representing a * sequence of bytes. */ /** * SECTION:arrays_pointer * @title: Pointer Arrays * @short_description: arrays of pointers to any type of data, which * grow automatically as new elements are added * * Pointer Arrays are similar to Arrays but are used only for storing * pointers. * * If you remove elements from the array, elements at the end of the * array are moved into the space previously occupied by the removed * element. This means that you should not rely on the index of particular * elements remaining the same. You should also be careful when deleting * elements while iterating over the array. * * To create a pointer array, use g_ptr_array_new(). * * To add elements to a pointer array, use g_ptr_array_add(). * * To remove elements from a pointer array, use g_ptr_array_remove(), * g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). * * To access an element of a pointer array, use g_ptr_array_index(). * * To set the size of a pointer array, use g_ptr_array_set_size(). * * To free a pointer array, use g_ptr_array_free(). * * An example using a #GPtrArray: * |[ * GPtrArray *array; * gchar *string1 = "one"; * gchar *string2 = "two"; * gchar *string3 = "three"; * * array = g_ptr_array_new (); * g_ptr_array_add (array, (gpointer) string1); * g_ptr_array_add (array, (gpointer) string2); * g_ptr_array_add (array, (gpointer) string3); * * if (g_ptr_array_index (array, 0) != (gpointer) string1) * g_print ("ERROR: got %p instead of %p\n", * g_ptr_array_index (array, 0), string1); * * g_ptr_array_free (array, TRUE); * ]| */ /** * SECTION:async_queues * @title: Asynchronous Queues * @short_description: asynchronous communication between threads * @see_also: #GThreadPool * * Often you need to communicate between different threads. In general * it's safer not to do this by shared memory, but by explicit message * passing. These messages only make sense asynchronously for * multi-threaded applications though, as a synchronous operation could * as well be done in the same thread. * * Asynchronous queues are an exception from most other GLib data * structures, as they can be used simultaneously from multiple threads * without explicit locking and they bring their own builtin reference * counting. This is because the nature of an asynchronous queue is that * it will always be used by at least 2 concurrent threads. * * For using an asynchronous queue you first have to create one with * g_async_queue_new(). #GAsyncQueue structs are reference counted, * use g_async_queue_ref() and g_async_queue_unref() to manage your * references. * * A thread which wants to send a message to that queue simply calls * g_async_queue_push() to push the message to the queue. * * A thread which is expecting messages from an asynchronous queue * simply calls g_async_queue_pop() for that queue. If no message is * available in the queue at that point, the thread is now put to sleep * until a message arrives. The message will be removed from the queue * and returned. The functions g_async_queue_try_pop() and * g_async_queue_timeout_pop() can be used to only check for the presence * of messages or to only wait a certain time for messages respectively. * * For almost every function there exist two variants, one that locks * the queue and one that doesn't. That way you can hold the queue lock * (acquire it with g_async_queue_lock() and release it with * g_async_queue_unlock()) over multiple queue accessing instructions. * This can be necessary to ensure the integrity of the queue, but should * only be used when really necessary, as it can make your life harder * if used unwisely. Normally you should only use the locking function * variants (those without the _unlocked suffix). * * In many cases, it may be more convenient to use #GThreadPool when * you need to distribute work to a set of worker threads instead of * using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue * internally. */ /** * SECTION:atomic_operations * @title: Atomic Operations * @short_description: basic atomic integer and pointer operations * @see_also: #GMutex * * The following is a collection of compiler macros to provide atomic * access to integer and pointer-sized values. * * The macros that have 'int' in the name will operate on pointers to * #gint and #guint. The macros with 'pointer' in the name will operate * on pointers to any pointer-sized value, including #gsize. There is * no support for 64bit operations on platforms with 32bit pointers * because it is not generally possible to perform these operations * atomically. * * The get, set and exchange operations for integers and pointers * nominally operate on #gint and #gpointer, respectively. Of the * arithmetic operations, the 'add' operation operates on (and returns) * signed integer values (#gint and #gssize) and the 'and', 'or', and * 'xor' operations operate on (and return) unsigned integer values * (#guint and #gsize). * * All of the operations act as a full compiler and (where appropriate) * hardware memory barrier. Acquire and release or producer and * consumer barrier semantics are not available through this API. * * It is very important that all accesses to a particular integer or * pointer be performed using only this API and that different sizes of * operation are not mixed or used on overlapping memory regions. Never * read or assign directly from or to a value -- always use this API. * * For simple reference counting purposes you should use * g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that * fall outside of simple reference counting patterns are prone to * subtle bugs and occasionally undefined behaviour. It is also worth * noting that since all of these operations require global * synchronisation of the entire machine, they can be quite slow. In * the case of performing multiple atomic operations it can often be * faster to simply acquire a mutex lock around the critical area, * perform the operations normally and then release the lock. */ /** * SECTION:base64 * @title: Base64 Encoding * @short_description: encodes and decodes data in Base64 format * * Base64 is an encoding that allows a sequence of arbitrary bytes to be * encoded as a sequence of printable ASCII characters. For the definition * of Base64, see * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) * or * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt). * Base64 is most commonly used as a MIME transfer encoding * for email. * * GLib supports incremental encoding using g_base64_encode_step() and * g_base64_encode_close(). Incremental decoding can be done with * g_base64_decode_step(). To encode or decode data in one go, use * g_base64_encode() or g_base64_decode(). To avoid memory allocation when * decoding, you can use g_base64_decode_inplace(). * * Support for Base64 encoding has been added in GLib 2.12. */ /** * SECTION:bookmarkfile * @title: Bookmark file parser * @short_description: parses files containing bookmarks * * GBookmarkFile lets you parse, edit or create files containing bookmarks * to URI, along with some meta-data about the resource pointed by the URI * like its MIME type, the application that is registering the bookmark and * the icon that should be used to represent the bookmark. The data is stored * using the * [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec). * * The syntax of the bookmark files is described in detail inside the * Desktop Bookmark Specification, here is a quick summary: bookmark * files use a sub-class of the XML Bookmark Exchange Language * specification, consisting of valid UTF-8 encoded XML, under the * root element; each bookmark is stored inside a * element, using its URI: no relative paths can * be used inside a bookmark file. The bookmark may have a user defined * title and description, to be used instead of the URI. Under the * element, with its owner attribute set to * `http://freedesktop.org`, is stored the meta-data about a resource * pointed by its URI. The meta-data consists of the resource's MIME * type; the applications that have registered a bookmark; the groups * to which a bookmark belongs to; a visibility flag, used to set the * bookmark as "private" to the applications and groups that has it * registered; the URI and MIME type of an icon, to be used when * displaying the bookmark inside a GUI. * * Here is an example of a bookmark file: * [bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel) * * A bookmark file might contain more than one bookmark; each bookmark * is accessed through its URI. * * The important caveat of bookmark files is that when you add a new * bookmark you must also add the application that is registering it, using * g_bookmark_file_add_application() or g_bookmark_file_set_app_info(). * If a bookmark has no applications then it won't be dumped when creating * the on disk representation, using g_bookmark_file_to_data() or * g_bookmark_file_to_file(). * * The #GBookmarkFile parser was added in GLib 2.12. */ /** * SECTION:byte_order * @title: Byte Order Macros * @short_description: a portable way to convert between different byte orders * * These macros provide a portable way to determine the host byte order * and to convert values between different byte orders. * * The byte order is the order in which bytes are stored to create larger * data types such as the #gint and #glong values. * The host byte order is the byte order used on the current machine. * * Some processors store the most significant bytes (i.e. the bytes that * hold the largest part of the value) first. These are known as big-endian * processors. Other processors (notably the x86 family) store the most * significant byte last. These are known as little-endian processors. * * Finally, to complicate matters, some other processors store the bytes in * a rather curious order known as PDP-endian. For a 4-byte word, the 3rd * most significant byte is stored first, then the 4th, then the 1st and * finally the 2nd. * * Obviously there is a problem when these different processors communicate * with each other, for example over networks or by using binary file formats. * This is where these macros come in. They are typically used to convert * values into a byte order which has been agreed on for use when * communicating between different processors. The Internet uses what is * known as 'network byte order' as the standard byte order (which is in * fact the big-endian byte order). * * Note that the byte order conversion macros may evaluate their arguments * multiple times, thus you should not use them with arguments which have * side-effects. */ /** * SECTION:checkedmath * @title: Bounds-checking integer arithmetic * @short_description: a set of helpers for performing checked integer arithmetic * * GLib offers a set of macros for doing additions and multiplications * of unsigned integers, with checks for overflows. * * The helpers all have three arguments. A pointer to the destination * is always the first argument and the operands to the operation are * the other two. * * Following standard GLib convention, the helpers return %TRUE in case * of success (ie: no overflow). * * The helpers may be macros, normal functions or inlines. They may be * implemented with inline assembly or compiler intrinsics where * available. * * Since: 2.48 */ /** * SECTION:checksum * @title: Data Checksums * @short_description: computes the checksum for data * * GLib provides a generic API for computing checksums (or "digests") * for a sequence of arbitrary bytes, using various hashing algorithms * like MD5, SHA-1 and SHA-256. Checksums are commonly used in various * environments and specifications. * * GLib supports incremental checksums using the GChecksum data * structure, by calling g_checksum_update() as long as there's data * available and then using g_checksum_get_string() or * g_checksum_get_digest() to compute the checksum and return it either * as a string in hexadecimal form, or as a raw sequence of bytes. To * compute the checksum for binary blobs and NUL-terminated strings in * one go, use the convenience functions g_compute_checksum_for_data() * and g_compute_checksum_for_string(), respectively. * * Support for checksums has been added in GLib 2.16 */ /** * SECTION:conversions * @title: Character Set Conversion * @short_description: convert strings between different character sets * * The g_convert() family of function wraps the functionality of iconv(). * In addition to pure character set conversions, GLib has functions to * deal with the extra complications of encodings for file names. * * ## File Name Encodings * * Historically, UNIX has not had a defined encoding for file names: * a file name is valid as long as it does not have path separators * in it ("/"). However, displaying file names may require conversion: * from the character set in which they were created, to the character * set in which the application operates. Consider the Spanish file name * "Presentación.sxi". If the application which created it uses * ISO-8859-1 for its encoding, * |[ * Character: P r e s e n t a c i ó n . s x i * Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69 * ]| * However, if the application use UTF-8, the actual file name on * disk would look like this: * |[ * Character: P r e s e n t a c i ó n . s x i * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69 * ]| * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use * GLib do the same thing. If you get a file name from the file system, * for example, from readdir() or from g_dir_read_name(), and you wish * to display the file name to the user, you will need to convert it * into UTF-8. The opposite case is when the user types the name of a * file they wish to save: the toolkit will give you that string in * UTF-8 encoding, and you will need to convert it to the character * set used for file names before you can create the file with open() * or fopen(). * * By default, GLib assumes that file names on disk are in UTF-8 * encoding. This is a valid assumption for file systems which * were created relatively recently: most applications use UTF-8 * encoding for their strings, and that is also what they use for * the file names they create. However, older file systems may * still contain file names created in "older" encodings, such as * ISO-8859-1. In this case, for compatibility reasons, you may want * to instruct GLib to use that particular encoding for file names * rather than UTF-8. You can do this by specifying the encoding for * file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING] * environment variable. For example, if your installation uses * ISO-8859-1 for file names, you can put this in your `~/.profile`: * |[ * export G_FILENAME_ENCODING=ISO-8859-1 * ]| * GLib provides the functions g_filename_to_utf8() and * g_filename_from_utf8() to perform the necessary conversions. * These functions convert file names from the encoding specified * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This * [diagram][file-name-encodings-diagram] illustrates how * these functions are used to convert between UTF-8 and the * encoding for file names in the file system. * * ## Conversion between file name encodings # {#file-name-encodings-diagram) * * ![](file-name-encodings.png) * * ## Checklist for Application Writers * * This section is a practical summary of the detailed * things to do to make sure your applications process file * name encodings correctly. * * 1. If you get a file name from the file system from a function * such as readdir() or gtk_file_chooser_get_filename(), you do * not need to do any conversion to pass that file name to * functions like open(), rename(), or fopen() -- those are "raw" * file names which the file system understands. * * 2. If you need to display a file name, convert it to UTF-8 first * by using g_filename_to_utf8(). If conversion fails, display a * string like "Unknown file name". Do not convert this string back * into the encoding used for file names if you wish to pass it to * the file system; use the original file name instead. * * For example, the document window of a word processor could display * "Unknown file name" in its title bar but still let the user save * the file, as it would keep the raw file name internally. This * can happen if the user has not set the `G_FILENAME_ENCODING` * environment variable even though he has files whose names are * not encoded in UTF-8. * * 3. If your user interface lets the user type a file name for saving * or renaming, convert it to the encoding used for file names in * the file system by using g_filename_from_utf8(). Pass the converted * file name to functions like fopen(). If conversion fails, ask the * user to enter a different file name. This can happen if the user * types Japanese characters when `G_FILENAME_ENCODING` is set to * `ISO-8859-1`, for example. */ /** * SECTION:datalist * @title: Keyed Data Lists * @short_description: lists of data elements which are accessible by a * string or GQuark identifier * * Keyed data lists provide lists of arbitrary data elements which can * be accessed either with a string or with a #GQuark corresponding to * the string. * * The #GQuark methods are quicker, since the strings have to be * converted to #GQuarks anyway. * * Data lists are used for associating arbitrary data with #GObjects, * using g_object_set_data() and related functions. * * To create a datalist, use g_datalist_init(). * * To add data elements to a datalist use g_datalist_id_set_data(), * g_datalist_id_set_data_full(), g_datalist_set_data() and * g_datalist_set_data_full(). * * To get data elements from a datalist use g_datalist_id_get_data() * and g_datalist_get_data(). * * To iterate over all data elements in a datalist use * g_datalist_foreach() (not thread-safe). * * To remove data elements from a datalist use * g_datalist_id_remove_data() and g_datalist_remove_data(). * * To remove all data elements from a datalist, use g_datalist_clear(). */ /** * SECTION:datasets * @title: Datasets * @short_description: associate groups of data elements with * particular memory locations * * Datasets associate groups of data elements with particular memory * locations. These are useful if you need to associate data with a * structure returned from an external library. Since you cannot modify * the structure, you use its location in memory as the key into a * dataset, where you can associate any number of data elements with it. * * There are two forms of most of the dataset functions. The first form * uses strings to identify the data elements associated with a * location. The second form uses #GQuark identifiers, which are * created with a call to g_quark_from_string() or * g_quark_from_static_string(). The second form is quicker, since it * does not require looking up the string in the hash table of #GQuark * identifiers. * * There is no function to create a dataset. It is automatically * created as soon as you add elements to it. * * To add data elements to a dataset use g_dataset_id_set_data(), * g_dataset_id_set_data_full(), g_dataset_set_data() and * g_dataset_set_data_full(). * * To get data elements from a dataset use g_dataset_id_get_data() and * g_dataset_get_data(). * * To iterate over all data elements in a dataset use * g_dataset_foreach() (not thread-safe). * * To remove data elements from a dataset use * g_dataset_id_remove_data() and g_dataset_remove_data(). * * To destroy a dataset, use g_dataset_destroy(). */ /** * SECTION:date * @title: Date and Time Functions * @short_description: calendrical calculations and miscellaneous time stuff * * The #GDate data structure represents a day between January 1, Year 1, * and sometime a few thousand years in the future (right now it will go * to the year 65535 or so, but g_date_set_parse() only parses up to the * year 8000 or so - just count on "a few thousand"). #GDate is meant to * represent everyday dates, not astronomical dates or historical dates * or ISO timestamps or the like. It extrapolates the current Gregorian * calendar forward and backward in time; there is no attempt to change * the calendar to match time periods or locations. #GDate does not store * time information; it represents a day. * * The #GDate implementation has several nice features; it is only a * 64-bit struct, so storing large numbers of dates is very efficient. It * can keep both a Julian and day-month-year representation of the date, * since some calculations are much easier with one representation or the * other. A Julian representation is simply a count of days since some * fixed day in the past; for #GDate the fixed day is January 1, 1 AD. * ("Julian" dates in the #GDate API aren't really Julian dates in the * technical sense; technically, Julian dates count from the start of the * Julian period, Jan 1, 4713 BC). * * #GDate is simple to use. First you need a "blank" date; you can get a * dynamically allocated date from g_date_new(), or you can declare an * automatic variable or array and initialize it to a sane state by * calling g_date_clear(). A cleared date is sane; it's safe to call * g_date_set_dmy() and the other mutator functions to initialize the * value of a cleared date. However, a cleared date is initially * invalid, meaning that it doesn't represent a day that exists. * It is undefined to call any of the date calculation routines on an * invalid date. If you obtain a date from a user or other * unpredictable source, you should check its validity with the * g_date_valid() predicate. g_date_valid() is also used to check for * errors with g_date_set_parse() and other functions that can * fail. Dates can be invalidated by calling g_date_clear() again. * * It is very important to use the API to access the #GDate * struct. Often only the day-month-year or only the Julian * representation is valid. Sometimes neither is valid. Use the API. * * GLib also features #GDateTime which represents a precise time. */ /** * SECTION:date-time * @title: GDateTime * @short_description: a structure representing Date and Time * @see_also: #GTimeZone * * #GDateTime is a structure that combines a Gregorian date and time * into a single structure. It provides many conversion and methods to * manipulate dates and times. Time precision is provided down to * microseconds and the time can range (proleptically) from 0001-01-01 * 00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX * time in the sense that it is oblivious to leap seconds. * * #GDateTime is an immutable object; once it has been created it cannot * be modified further. All modifiers will create a new #GDateTime. * Nearly all such functions can fail due to the date or time going out * of range, in which case %NULL will be returned. * * #GDateTime is reference counted: the reference count is increased by calling * g_date_time_ref() and decreased by calling g_date_time_unref(). When the * reference count drops to 0, the resources allocated by the #GDateTime * structure are released. * * Many parts of the API may produce non-obvious results. As an * example, adding two months to January 31st will yield March 31st * whereas adding one month and then one month again will yield either * March 28th or March 29th. Also note that adding 24 hours is not * always the same as adding one day (since days containing daylight * savings time transitions are either 23 or 25 hours in length). * * #GDateTime is available since GLib 2.26. */ /** * SECTION:error_reporting * @Title: Error Reporting * @Short_description: a system for reporting errors * * GLib provides a standard method of reporting errors from a called * function to the calling code. (This is the same problem solved by * exceptions in other languages.) It's important to understand that * this method is both a data type (the #GError struct) and a [set of * rules][gerror-rules]. If you use #GError incorrectly, then your code will not * properly interoperate with other code that uses #GError, and users * of your API will probably get confused. In most cases, [using #GError is * preferred over numeric error codes][gerror-comparison], but there are * situations where numeric error codes are useful for performance. * * First and foremost: #GError should only be used to report recoverable * runtime errors, never to report programming errors. If the programmer * has screwed up, then you should use g_warning(), g_return_if_fail(), * g_assert(), g_error(), or some similar facility. (Incidentally, * remember that the g_error() function should only be used for * programming errors, it should not be used to print any error * reportable via #GError.) * * Examples of recoverable runtime errors are "file not found" or * "failed to parse input." Examples of programming errors are "NULL * passed to strcmp()" or "attempted to free the same pointer twice." * These two kinds of errors are fundamentally different: runtime errors * should be handled or reported to the user, programming errors should * be eliminated by fixing the bug in the program. This is why most * functions in GLib and GTK+ do not use the #GError facility. * * Functions that can fail take a return location for a #GError as their * last argument. On error, a new #GError instance will be allocated and * returned to the caller via this argument. For example: * |[ * gboolean g_file_get_contents (const gchar *filename, * gchar **contents, * gsize *length, * GError **error); * ]| * If you pass a non-%NULL value for the `error` argument, it should * point to a location where an error can be placed. For example: * |[ * gchar *contents; * GError *err = NULL; * * g_file_get_contents ("foo.txt", &contents, NULL, &err); * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); * if (err != NULL) * { * // Report error to user, and free error * g_assert (contents == NULL); * fprintf (stderr, "Unable to read file: %s\n", err->message); * g_error_free (err); * } * else * { * // Use file contents * g_assert (contents != NULL); * } * ]| * Note that `err != NULL` in this example is a reliable indicator * of whether g_file_get_contents() failed. Additionally, * g_file_get_contents() returns a boolean which * indicates whether it was successful. * * Because g_file_get_contents() returns %FALSE on failure, if you * are only interested in whether it failed and don't need to display * an error message, you can pass %NULL for the @error argument: * |[ * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors * // no error occurred * ; * else * // error * ; * ]| * * The #GError object contains three fields: @domain indicates the module * the error-reporting function is located in, @code indicates the specific * error that occurred, and @message is a user-readable error message with * as many details as possible. Several functions are provided to deal * with an error received from a called function: g_error_matches() * returns %TRUE if the error matches a given domain and code, * g_propagate_error() copies an error into an error location (so the * calling function will receive it), and g_clear_error() clears an * error location by freeing the error and resetting the location to * %NULL. To display an error to the user, simply display the @message, * perhaps along with additional context known only to the calling * function (the file being opened, or whatever - though in the * g_file_get_contents() case, the @message already contains a filename). * * When implementing a function that can report errors, the basic * tool is g_set_error(). Typically, if a fatal error occurs you * want to g_set_error(), then return immediately. g_set_error() * does nothing if the error location passed to it is %NULL. * Here's an example: * |[ * gint * foo_open_file (GError **error) * { * gint fd; * int saved_errno; * * fd = open ("file.txt", O_RDONLY); * saved_errno = errno; * * if (fd < 0) * { * g_set_error (error, * FOO_ERROR, // error domain * FOO_ERROR_BLAH, // error code * "Failed to open file: %s", // error message format string * g_strerror (saved_errno)); * return -1; * } * else * return fd; * } * ]| * * Things are somewhat more complicated if you yourself call another * function that can report a #GError. If the sub-function indicates * fatal errors in some way other than reporting a #GError, such as * by returning %TRUE on success, you can simply do the following: * |[ * gboolean * my_function_that_can_fail (GError **err) * { * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * * if (!sub_function_that_can_fail (err)) * { * // assert that error was set by the sub-function * g_assert (err == NULL || *err != NULL); * return FALSE; * } * * // otherwise continue, no error occurred * g_assert (err == NULL || *err == NULL); * } * ]| * * If the sub-function does not indicate errors other than by * reporting a #GError (or if its return value does not reliably indicate * errors) you need to create a temporary #GError * since the passed-in one may be %NULL. g_propagate_error() is * intended for use in this case. * |[ * gboolean * my_function_that_can_fail (GError **err) * { * GError *tmp_error; * * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * * tmp_error = NULL; * sub_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { * // store tmp_error in err, if err != NULL, * // otherwise call g_error_free() on tmp_error * g_propagate_error (err, tmp_error); * return FALSE; * } * * // otherwise continue, no error occurred * } * ]| * * Error pileups are always a bug. For example, this code is incorrect: * |[ * gboolean * my_function_that_can_fail (GError **err) * { * GError *tmp_error; * * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * * tmp_error = NULL; * sub_function_that_can_fail (&tmp_error); * other_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { * g_propagate_error (err, tmp_error); * return FALSE; * } * } * ]| * @tmp_error should be checked immediately after sub_function_that_can_fail(), * and either cleared or propagated upward. The rule is: after each error, * you must either handle the error, or return it to the calling function. * * Note that passing %NULL for the error location is the equivalent * of handling an error by always doing nothing about it. So the * following code is fine, assuming errors in sub_function_that_can_fail() * are not fatal to my_function_that_can_fail(): * |[ * gboolean * my_function_that_can_fail (GError **err) * { * GError *tmp_error; * * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * * sub_function_that_can_fail (NULL); // ignore errors * * tmp_error = NULL; * other_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { * g_propagate_error (err, tmp_error); * return FALSE; * } * } * ]| * * Note that passing %NULL for the error location ignores errors; * it's equivalent to * `try { sub_function_that_can_fail (); } catch (...) {}` * in C++. It does not mean to leave errors unhandled; it means * to handle them by doing nothing. * * Error domains and codes are conventionally named as follows: * * - The error domain is called __ERROR, * for example %G_SPAWN_ERROR or %G_THREAD_ERROR: * |[ * #define G_SPAWN_ERROR g_spawn_error_quark () * * GQuark * g_spawn_error_quark (void) * { * return g_quark_from_static_string ("g-spawn-error-quark"); * } * ]| * * - The quark function for the error domain is called * __error_quark, * for example g_spawn_error_quark() or g_thread_error_quark(). * * - The error codes are in an enumeration called * Error; * for example, #GThreadError or #GSpawnError. * * - Members of the error code enumeration are called * __ERROR_, * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. * * - If there's a "generic" or "unknown" error code for unrecoverable * errors it doesn't make sense to distinguish with specific codes, * it should be called __ERROR_FAILED, * for example %G_SPAWN_ERROR_FAILED. In the case of error code * enumerations that may be extended in future releases, you should * generally not handle this error code explicitly, but should * instead treat any unrecognized error code as equivalent to * FAILED. * * ## Comparison of #GError and traditional error handling # {#gerror-comparison} * * #GError has several advantages over traditional numeric error codes: * importantly, tools like * [gobject-introspection](https://developer.gnome.org/gi/stable/) understand * #GErrors and convert them to exceptions in bindings; the message includes * more information than just a code; and use of a domain helps prevent * misinterpretation of error codes. * * #GError has disadvantages though: it requires a memory allocation, and * formatting the error message string has a performance overhead. This makes it * unsuitable for use in retry loops where errors are a common case, rather than * being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these * overheads in the normal control flow. String formatting overhead can be * eliminated by using g_set_error_literal() in some cases. * * These performance issues can be compounded if a function wraps the #GErrors * returned by the functions it calls: this multiplies the number of allocations * and string formatting operations. This can be partially mitigated by using * g_prefix_error(). * * ## Rules for use of #GError # {#gerror-rules} * * Summary of rules for use of #GError: * * - Do not report programming errors via #GError. * * - The last argument of a function that returns an error should * be a location where a #GError can be placed (i.e. "#GError** error"). * If #GError is used with varargs, the #GError** should be the last * argument before the "...". * * - The caller may pass %NULL for the #GError** if they are not interested * in details of the exact error that occurred. * * - If %NULL is passed for the #GError** argument, then errors should * not be returned to the caller, but your function should still * abort and return if an error occurs. That is, control flow should * not be affected by whether the caller wants to get a #GError. * * - If a #GError is reported, then your function by definition had a * fatal failure and did not complete whatever it was supposed to do. * If the failure was not fatal, then you handled it and you should not * report it. If it was fatal, then you must report it and discontinue * whatever you were doing immediately. * * - If a #GError is reported, out parameters are not guaranteed to * be set to any defined value. * * - A #GError* must be initialized to %NULL before passing its address * to a function that can report errors. * * - "Piling up" errors is always a bug. That is, if you assign a * new #GError to a #GError* that is non-%NULL, thus overwriting * the previous error, it indicates that you should have aborted * the operation instead of continuing. If you were able to continue, * you should have cleared the previous error with g_clear_error(). * g_set_error() will complain if you pile up errors. * * - By convention, if you return a boolean value indicating success * then %TRUE means success and %FALSE means failure. Avoid creating * functions which have a boolean return value and a GError parameter, * but where the boolean does something other than signal whether the * GError is set. Among other problems, it requires C callers to allocate * a temporary error. Instead, provide a "gboolean *" out parameter. * There are functions in GLib itself such as g_key_file_has_key() that * are deprecated because of this. If %FALSE is returned, the error must * be set to a non-%NULL value. One exception to this is that in situations * that are already considered to be undefined behaviour (such as when a * g_return_val_if_fail() check fails), the error need not be set. * Instead of checking separately whether the error is set, callers * should ensure that they do not provoke undefined behaviour, then * assume that the error will be set on failure. * * - A %NULL return value is also frequently used to mean that an error * occurred. You should make clear in your documentation whether %NULL * is a valid return value in non-error cases; if %NULL is a valid value, * then users must check whether an error was returned to see if the * function succeeded. * * - When implementing a function that can report errors, you may want * to add a check at the top of your function that the error return * location is either %NULL or contains a %NULL error (e.g. * `g_return_if_fail (error == NULL || *error == NULL);`). */ /** * SECTION:fileutils * @title: File Utilities * @short_description: various file-related functions * * Do not use these APIs unless you are porting a POSIX application to Windows. * A more high-level file access API is provided as GIO — see the documentation * for #GFile. * * There is a group of functions which wrap the common POSIX functions * dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(), * g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these * wrappers is to make it possible to handle file names with any Unicode * characters in them on Windows without having to use ifdefs and the * wide character API in the application code. * * On some Unix systems, these APIs may be defined as identical to their POSIX * counterparts. For this reason, you must check for and include the necessary * header files (such as `fcntl.h`) before using functions like g_creat(). You * must also define the relevant feature test macros. * * The pathname argument should be in the GLib file name encoding. * On POSIX this is the actual on-disk encoding which might correspond * to the locale settings of the process (or the `G_FILENAME_ENCODING` * environment variable), or not. * * On Windows the GLib file name encoding is UTF-8. Note that the * Microsoft C library does not use UTF-8, but has separate APIs for * current system code page and wide characters (UTF-16). The GLib * wrappers call the wide character API if present (on modern Windows * systems), otherwise convert to/from the system code page. * * Another group of functions allows to open and read directories * in the GLib file name encoding. These are g_dir_open(), * g_dir_read_name(), g_dir_rewind(), g_dir_close(). */ /** * SECTION:ghostutils * @short_description: Internet hostname utilities * * Functions for manipulating internet hostnames; in particular, for * converting between Unicode and ASCII-encoded forms of * Internationalized Domain Names (IDNs). * * The * [Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt) * standards allow for the use * of Unicode domain names in applications, while providing * backward-compatibility with the old ASCII-only DNS, by defining an * ASCII-Compatible Encoding of any given Unicode name, which can be * used with non-IDN-aware applications and protocols. (For example, * "Παν語.org" maps to "xn--4wa8awb4637h.org".) */ /** * SECTION:gregex * @title: Perl-compatible regular expressions * @short_description: matches strings against regular expressions * @see_also: [Regular expression syntax][glib-regex-syntax] * * The g_regex_*() functions implement regular * expression pattern matching using syntax and semantics similar to * Perl regular expression. * * Some functions accept a @start_position argument, setting it differs * from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL * in the case of a pattern that begins with any kind of lookbehind assertion. * For example, consider the pattern "\Biss\B" which finds occurrences of "iss" * in the middle of words. ("\B" matches only if the current position in the * subject is not a word boundary.) When applied to the string "Mississipi" * from the fourth byte, namely "issipi", it does not match, because "\B" is * always false at the start of the subject, which is deemed to be a word * boundary. However, if the entire string is passed , but with * @start_position set to 4, it finds the second occurrence of "iss" because * it is able to look behind the starting point to discover that it is * preceded by a letter. * * Note that, unless you set the #G_REGEX_RAW flag, all the strings passed * to these functions must be encoded in UTF-8. The lengths and the positions * inside the strings are in bytes and not in characters, so, for instance, * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a * single character. If you set #G_REGEX_RAW the strings can be non-valid * UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two * bytes and two characters long. * * When matching a pattern, "\n" matches only against a "\n" character in * the string, and "\r" matches only a "\r" character. To match any newline * sequence use "\R". This particular group matches either the two-character * sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed, * U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"), * CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line * separator, U+2028), or PS (paragraph separator, U+2029). * * The behaviour of the dot, circumflex, and dollar metacharacters are * affected by newline characters, the default is to recognize any newline * character (the same characters recognized by "\R"). This can be changed * with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF * compile options, and with #G_REGEX_MATCH_NEWLINE_ANY, * #G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and * #G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also * relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an * unescaped "#" outside a character class is encountered. This indicates * a comment that lasts until after the next newline. * * When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern * matching is changed to be compatible with the way that regular expressions * work in JavaScript. More precisely, a lonely ']' character in the pattern * is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and * you must use the '\u' escape sequence with 4 hex digits to specify a unicode * codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by * the specified number of hex digits, they match 'x' and 'u' literally; also * '\U' always matches 'U' instead of being an error in the pattern. Finally, * pattern matching is modified so that back references to an unset subpattern * group produces a match with the empty string instead of an error. See * pcreapi(3) for more information. * * Creating and manipulating the same #GRegex structure from different * threads is not a problem as #GRegex does not modify its internal * state between creation and destruction, on the other hand #GMatchInfo * is not threadsafe. * * The regular expressions low-level functionalities are obtained through * the excellent * [PCRE](http://www.pcre.org/) * library written by Philip Hazel. */ /** * SECTION:gunix * @title: UNIX-specific utilities and integration * @short_description: pipes, signal handling * @include: glib-unix.h * * Most of GLib is intended to be portable; in contrast, this set of * functions is designed for programs which explicitly target UNIX, * or are using it to build higher level abstractions which would be * conditionally compiled if the platform matches G_OS_UNIX. * * To use these functions, you must explicitly include the * "glib-unix.h" header. */ /** * SECTION:gurifuncs * @title: URI Functions * @short_description: manipulating URIs * * Functions for manipulating Universal Resource Identifiers (URIs) as * defined by * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt). * It is highly recommended that you have read and * understand RFC 3986 for understanding this API. */ /** * SECTION:gvariant * @title: GVariant * @short_description: strongly typed value datatype * @see_also: GVariantType * * #GVariant is a variant datatype; it can contain one or more values * along with information about the type of the values. * * A #GVariant may contain simple types, like an integer, or a boolean value; * or complex types, like an array of two strings, or a dictionary of key * value pairs. A #GVariant is also immutable: once it's been created neither * its type nor its content can be modified further. * * GVariant is useful whenever data needs to be serialized, for example when * sending method parameters in DBus, or when saving settings using GSettings. * * When creating a new #GVariant, you pass the data you want to store in it * along with a string representing the type of data you wish to pass to it. * * For instance, if you want to create a #GVariant holding an integer value you * can use: * * |[ * GVariant *v = g_variant_new ("u", 40); * ]| * * The string "u" in the first argument tells #GVariant that the data passed to * the constructor (40) is going to be an unsigned integer. * * More advanced examples of #GVariant in use can be found in documentation for * [GVariant format strings][gvariant-format-strings-pointers]. * * The range of possible values is determined by the type. * * The type system used by #GVariant is #GVariantType. * * #GVariant instances always have a type and a value (which are given * at construction time). The type and value of a #GVariant instance * can never change other than by the #GVariant itself being * destroyed. A #GVariant cannot contain a pointer. * * #GVariant is reference counted using g_variant_ref() and * g_variant_unref(). #GVariant also has floating reference counts -- * see g_variant_ref_sink(). * * #GVariant is completely threadsafe. A #GVariant instance can be * concurrently accessed in any way from any number of threads without * problems. * * #GVariant is heavily optimised for dealing with data in serialised * form. It works particularly well with data located in memory-mapped * files. It can perform nearly all deserialisation operations in a * small constant time, usually touching only a single memory page. * Serialised #GVariant data can also be sent over the network. * * #GVariant is largely compatible with D-Bus. Almost all types of * #GVariant instances can be sent over D-Bus. See #GVariantType for * exceptions. (However, #GVariant's serialisation format is not the same * as the serialisation format of a D-Bus message body: use #GDBusMessage, * in the gio library, for those.) * * For space-efficiency, the #GVariant serialisation format does not * automatically include the variant's length, type or endianness, * which must either be implied from context (such as knowledge that a * particular file format always contains a little-endian * %G_VARIANT_TYPE_VARIANT which occupies the whole length of the file) * or supplied out-of-band (for instance, a length, type and/or endianness * indicator could be placed at the beginning of a file, network message * or network stream). * * A #GVariant's size is limited mainly by any lower level operating * system constraints, such as the number of bits in #gsize. For * example, it is reasonable to have a 2GB file mapped into memory * with #GMappedFile, and call g_variant_new_from_data() on it. * * For convenience to C programmers, #GVariant features powerful * varargs-based value construction and destruction. This feature is * designed to be embedded in other libraries. * * There is a Python-inspired text language for describing #GVariant * values. #GVariant includes a printer for this language and a parser * with type inferencing. * * ## Memory Use * * #GVariant tries to be quite efficient with respect to memory use. * This section gives a rough idea of how much memory is used by the * current implementation. The information here is subject to change * in the future. * * The memory allocated by #GVariant can be grouped into 4 broad * purposes: memory for serialised data, memory for the type * information cache, buffer management memory and memory for the * #GVariant structure itself. * * ## Serialised Data Memory * * This is the memory that is used for storing GVariant data in * serialised form. This is what would be sent over the network or * what would end up on disk, not counting any indicator of the * endianness, or of the length or type of the top-level variant. * * The amount of memory required to store a boolean is 1 byte. 16, * 32 and 64 bit integers and double precision floating point numbers * use their "natural" size. Strings (including object path and * signature strings) are stored with a nul terminator, and as such * use the length of the string plus 1 byte. * * Maybe types use no space at all to represent the null value and * use the same amount of space (sometimes plus one byte) as the * equivalent non-maybe-typed value to represent the non-null case. * * Arrays use the amount of space required to store each of their * members, concatenated. Additionally, if the items stored in an * array are not of a fixed-size (ie: strings, other arrays, etc) * then an additional framing offset is stored for each item. The * size of this offset is either 1, 2 or 4 bytes depending on the * overall size of the container. Additionally, extra padding bytes * are added as required for alignment of child values. * * Tuples (including dictionary entries) use the amount of space * required to store each of their members, concatenated, plus one * framing offset (as per arrays) for each non-fixed-sized item in * the tuple, except for the last one. Additionally, extra padding * bytes are added as required for alignment of child values. * * Variants use the same amount of space as the item inside of the * variant, plus 1 byte, plus the length of the type string for the * item inside the variant. * * As an example, consider a dictionary mapping strings to variants. * In the case that the dictionary is empty, 0 bytes are required for * the serialisation. * * If we add an item "width" that maps to the int32 value of 500 then * we will use 4 byte to store the int32 (so 6 for the variant * containing it) and 6 bytes for the string. The variant must be * aligned to 8 after the 6 bytes of the string, so that's 2 extra * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used * for the dictionary entry. An additional 1 byte is added to the * array as a framing offset making a total of 15 bytes. * * If we add another entry, "title" that maps to a nullable string * that happens to have a value of null, then we use 0 bytes for the * null value (and 3 bytes for the variant to contain it along with * its type string) plus 6 bytes for the string. Again, we need 2 * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. * * We now require extra padding between the two items in the array. * After the 14 bytes of the first item, that's 2 bytes required. * We now require 2 framing offsets for an extra two * bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item * dictionary. * * ## Type Information Cache * * For each GVariant type that currently exists in the program a type * information structure is kept in the type information cache. The * type information structure is required for rapid deserialisation. * * Continuing with the above example, if a #GVariant exists with the * type "a{sv}" then a type information struct will exist for * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type * will share the same type information. Additionally, all * single-digit types are stored in read-only static memory and do * not contribute to the writable memory footprint of a program using * #GVariant. * * Aside from the type information structures stored in read-only * memory, there are two forms of type information. One is used for * container types where there is a single element type: arrays and * maybe types. The other is used for container types where there * are multiple element types: tuples and dictionary entries. * * Array type info structures are 6 * sizeof (void *), plus the * memory required to store the type string itself. This means that * on 32-bit systems, the cache entry for "a{sv}" would require 30 * bytes of memory (plus malloc overhead). * * Tuple type info structures are 6 * sizeof (void *), plus 4 * * sizeof (void *) for each item in the tuple, plus the memory * required to store the type string itself. A 2-item tuple, for * example, would have a type information structure that consumed * writable memory in the size of 14 * sizeof (void *) (plus type * string) This means that on 32-bit systems, the cache entry for * "{sv}" would require 61 bytes of memory (plus malloc overhead). * * This means that in total, for our "a{sv}" example, 91 bytes of * type information would be allocated. * * The type information cache, additionally, uses a #GHashTable to * store and lookup the cached items and stores a pointer to this * hash table in static storage. The hash table is freed when there * are zero items in the type cache. * * Although these sizes may seem large it is important to remember * that a program will probably only have a very small number of * different types of values in it and that only one type information * structure is required for many different values of the same type. * * ## Buffer Management Memory * * #GVariant uses an internal buffer management structure to deal * with the various different possible sources of serialised data * that it uses. The buffer is responsible for ensuring that the * correct call is made when the data is no longer in use by * #GVariant. This may involve a g_free() or a g_slice_free() or * even g_mapped_file_unref(). * * One buffer management structure is used for each chunk of * serialised data. The size of the buffer management structure * is 4 * (void *). On 32-bit systems, that's 16 bytes. * * ## GVariant structure * * The size of a #GVariant structure is 6 * (void *). On 32-bit * systems, that's 24 bytes. * * #GVariant structures only exist if they are explicitly created * with API calls. For example, if a #GVariant is constructed out of * serialised data for the example given above (with the dictionary) * then although there are 9 individual values that comprise the * entire dictionary (two keys, two values, two variants containing * the values, two dictionary entries, plus the dictionary itself), * only 1 #GVariant instance exists -- the one referring to the * dictionary. * * If calls are made to start accessing the other values then * #GVariant instances will exist for those values only for as long * as they are in use (ie: until you call g_variant_unref()). The * type information is shared. The serialised data and the buffer * management structure for that serialised data is shared by the * child. * * ## Summary * * To put the entire example together, for our dictionary mapping * strings to variants (with two entries, as given above), we are * using 91 bytes of memory for type information, 29 bytes of memory * for the serialised data, 16 bytes for buffer management and 24 * bytes for the #GVariant instance, or a total of 160 bytes, plus * malloc overhead. If we were to use g_variant_get_child_value() to * access the two dictionary entries, we would use an additional 48 * bytes. If we were to have other dictionaries of the same type, we * would use more memory for the serialised data and buffer * management for those dictionaries, but the type information would * be shared. */ /** * SECTION:gvarianttype * @title: GVariantType * @short_description: introduction to the GVariant type system * @see_also: #GVariantType, #GVariant * * This section introduces the GVariant type system. It is based, in * large part, on the D-Bus type system, with two major changes and * some minor lifting of restrictions. The * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), * therefore, provides a significant amount of * information that is useful when working with GVariant. * * The first major change with respect to the D-Bus type system is the * introduction of maybe (or "nullable") types. Any type in GVariant can be * converted to a maybe type, in which case, "nothing" (or "null") becomes a * valid value. Maybe types have been added by introducing the * character "m" to type strings. * * The second major change is that the GVariant type system supports the * concept of "indefinite types" -- types that are less specific than * the normal types found in D-Bus. For example, it is possible to speak * of "an array of any type" in GVariant, where the D-Bus type system * would require you to speak of "an array of integers" or "an array of * strings". Indefinite types have been added by introducing the * characters "*", "?" and "r" to type strings. * * Finally, all arbitrary restrictions relating to the complexity of * types are lifted along with the restriction that dictionary entries * may only appear nested inside of arrays. * * Just as in D-Bus, GVariant types are described with strings ("type * strings"). Subject to the differences mentioned above, these strings * are of the same form as those found in DBus. Note, however: D-Bus * always works in terms of messages and therefore individual type * strings appear nowhere in its interface. Instead, "signatures" * are a concatenation of the strings of the type of each argument in a * message. GVariant deals with single values directly so GVariant type * strings always describe the type of exactly one value. This means * that a D-Bus signature string is generally not a valid GVariant type * string -- except in the case that it is the signature of a message * containing exactly one argument. * * An indefinite type is similar in spirit to what may be called an * abstract type in other type systems. No value can exist that has an * indefinite type as its type, but values can exist that have types * that are subtypes of indefinite types. That is to say, * g_variant_get_type() will never return an indefinite type, but * calling g_variant_is_of_type() with an indefinite type may return * %TRUE. For example, you cannot have a value that represents "an * array of no particular type", but you can have an "array of integers" * which certainly matches the type of "an array of no particular type", * since "array of integers" is a subtype of "array of no particular * type". * * This is similar to how instances of abstract classes may not * directly exist in other type systems, but instances of their * non-abstract subtypes may. For example, in GTK, no object that has * the type of #GtkBin can exist (since #GtkBin is an abstract class), * but a #GtkWindow can certainly be instantiated, and you would say * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of * #GtkBin). * * ## GVariant Type Strings * * A GVariant type string can be any of the following: * * - any basic type string (listed below) * * - "v", "r" or "*" * * - one of the characters 'a' or 'm', followed by another type string * * - the character '(', followed by a concatenation of zero or more other * type strings, followed by the character ')' * * - the character '{', followed by a basic type string (see below), * followed by another type string, followed by the character '}' * * A basic type string describes a basic type (as per * g_variant_type_is_basic()) and is always a single character in length. * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", * "h", "d", "s", "o", "g" and "?". * * The above definition is recursive to arbitrary depth. "aaaaai" and * "(ui(nq((y)))s)" are both valid type strings, as is * "a(aa(ui)(qna{ya(yd)}))". * * The meaning of each of the characters is as follows: * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value * that, by convention, is used as an index into an array of file * descriptors that are sent alongside a D-Bus message. * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision * floating point value. * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string. * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form * of a D-Bus object path. * - `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of * a D-Bus type signature. * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that * is a supertype of any of the basic types. * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that * contain any other type of value. * - `a`: used as a prefix on another type string to mean an array of that * type; the type string "ai", for example, is the type of an array of * signed 32-bit integers. * - `m`: used as a prefix on another type string to mean a "maybe", or * "nullable", version of that type; the type string "ms", for example, * is the type of a value that maybe contains a string, or maybe contains * nothing. * - `()`: used to enclose zero or more other concatenated type strings to * create a tuple type; the type string "(is)", for example, is the type of * a pair of an integer and a string. * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is * a supertype of any tuple type, regardless of the number of items. * - `{}`: used to enclose a basic type string concatenated with another type * string to create a dictionary entry type, which usually appears inside of * an array to form a dictionary; the type string "a{sd}", for example, is * the type of a dictionary that maps strings to double precision floating * point values. * * The first type (the basic type) is the key type and the second type is * the value type. The reason that the first type is restricted to being a * basic type is so that it can easily be hashed. * - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is * a supertype of all types. Note that, as with all type strings, this * character represents exactly one type. It cannot be used inside of tuples * to mean "any number of items". * * Any type string of a container that contains an indefinite type is, * itself, an indefinite type. For example, the type string "a*" * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type * that is a supertype of every array type. "(*s)" is a supertype * of all tuples that contain exactly two items where the second * item is a string. * * "a{?*}" is an indefinite type that is a supertype of all arrays * containing dictionary entries where the key is any basic type and * the value is any type at all. This is, by definition, a dictionary, * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note * that, due to the restriction that the key of a dictionary entry must * be a basic type, "{**}" is not a valid type string. */ /** * SECTION:hash_tables * @title: Hash Tables * @short_description: associations between keys and values so that * given a key the value can be found quickly * * A #GHashTable provides associations between keys and values which is * optimized so that given a key, the associated value can be found * very quickly. * * Note that neither keys nor values are copied when inserted into the * #GHashTable, so they must exist for the lifetime of the #GHashTable. * This means that the use of static strings is OK, but temporary * strings (i.e. those created in buffers and those returned by GTK+ * widgets) should be copied with g_strdup() before being inserted. * * If keys or values are dynamically allocated, you must be careful to * ensure that they are freed when they are removed from the * #GHashTable, and also when they are overwritten by new insertions * into the #GHashTable. It is also not advisable to mix static strings * and dynamically-allocated strings in a #GHashTable, because it then * becomes difficult to determine whether the string should be freed. * * To create a #GHashTable, use g_hash_table_new(). * * To insert a key and value into a #GHashTable, use * g_hash_table_insert(). * * To lookup a value corresponding to a given key, use * g_hash_table_lookup() and g_hash_table_lookup_extended(). * * g_hash_table_lookup_extended() can also be used to simply * check if a key is present in the hash table. * * To remove a key and value, use g_hash_table_remove(). * * To call a function for each key and value pair use * g_hash_table_foreach() or use a iterator to iterate over the * key/value pairs in the hash table, see #GHashTableIter. * * To destroy a #GHashTable use g_hash_table_destroy(). * * A common use-case for hash tables is to store information about a * set of keys, without associating any particular value with each * key. GHashTable optimizes one way of doing so: If you store only * key-value pairs where key == value, then GHashTable does not * allocate memory to store the values, which can be a considerable * space saving, if your set is large. The functions * g_hash_table_add() and g_hash_table_contains() are designed to be * used when using #GHashTable this way. * * #GHashTable is not designed to be statically initialised with keys and * values known at compile time. To build a static hash table, use a tool such * as [gperf](https://www.gnu.org/software/gperf/). */ /** * SECTION:hmac * @title: Secure HMAC Digests * @short_description: computes the HMAC for data * * HMACs should be used when producing a cookie or hash based on data * and a key. Simple mechanisms for using SHA1 and other algorithms to * digest a key and data together are vulnerable to various security * issues. * [HMAC](http://en.wikipedia.org/wiki/HMAC) * uses algorithms like SHA1 in a secure way to produce a digest of a * key and data. * * Both the key and data are arbitrary byte arrays of bytes or characters. * * Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 * in GLib 2.42. Support for SHA-384 was added in GLib 2.52. */ /** * SECTION:hooks * @title: Hook Functions * @short_description: support for manipulating lists of hook functions * * The #GHookList, #GHook and their related functions provide support for * lists of hook functions. Functions can be added and removed from the lists, * and the list of hook functions can be invoked. */ /** * SECTION:i18n * @title: Internationalization * @short_description: gettext support macros * @see_also: the gettext manual * * GLib doesn't force any particular localization method upon its users. * But since GLib itself is localized using the gettext() mechanism, it seems * natural to offer the de-facto standard gettext() support macros in an * easy-to-use form. * * In order to use these macros in an application, you must include * ``. For use in a library, you must include * `` * after defining the %GETTEXT_PACKAGE macro suitably for your library: * |[ * #define GETTEXT_PACKAGE "gtk20" * #include * ]| * For an application, note that you also have to call bindtextdomain(), * bind_textdomain_codeset(), textdomain() and setlocale() early on in your * main() to make gettext() work. For example: * |[ * #include * #include * * int * main (int argc, char **argv) * { * setlocale (LC_ALL, ""); * bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale"); * bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8"); * textdomain (GETTEXT_PACKAGE); * * // Rest of your application. * } * ]| * where `DATADIR` is as typically provided by automake. * * For a library, you only have to call bindtextdomain() and * bind_textdomain_codeset() in your initialization function. If your library * doesn't have an initialization function, you can call the functions before * the first translated message. * * The * [gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers) * covers details of how to integrate gettext into a project’s build system and * workflow. */ /** * SECTION:iochannels * @title: IO Channels * @short_description: portable support for using files, pipes and sockets * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(), * #GMainLoop * * The #GIOChannel data type aims to provide a portable method for * using file descriptors, pipes, and sockets, and integrating them * into the [main event loop][glib-The-Main-Event-Loop]. Currently, * full support is available on UNIX platforms, support for Windows * is only partially complete. * * To create a new #GIOChannel on UNIX systems use * g_io_channel_unix_new(). This works for plain file descriptors, * pipes and sockets. Alternatively, a channel can be created for a * file in a system independent manner using g_io_channel_new_file(). * * Once a #GIOChannel has been created, it can be used in a generic * manner with the functions g_io_channel_read_chars(), * g_io_channel_write_chars(), g_io_channel_seek_position(), and * g_io_channel_shutdown(). * * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which * events you are interested in on the #GIOChannel, and provide a * function to be called whenever these events occur. * * #GIOChannel instances are created with an initial reference count of 1. * g_io_channel_ref() and g_io_channel_unref() can be used to * increment or decrement the reference count respectively. When the * reference count falls to 0, the #GIOChannel is freed. (Though it * isn't closed automatically, unless it was created using * g_io_channel_new_file().) Using g_io_add_watch() or * g_io_add_watch_full() increments a channel's reference count. * * The new functions g_io_channel_read_chars(), * g_io_channel_read_line(), g_io_channel_read_line_string(), * g_io_channel_read_to_end(), g_io_channel_write_chars(), * g_io_channel_seek_position(), and g_io_channel_flush() should not be * mixed with the deprecated functions g_io_channel_read(), * g_io_channel_write(), and g_io_channel_seek() on the same channel. */ /** * SECTION:keyfile * @title: Key-value file parser * @short_description: parses .ini-like config files * * #GKeyFile lets you parse, edit or create files containing groups of * key-value pairs, which we call "key files" for lack of a better name. * Several freedesktop.org specifications use key files now, e.g the * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) * and the * [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). * * The syntax of key files is described in detail in the * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), * here is a quick summary: Key files * consists of groups of key-value pairs, interspersed with comments. * * |[ * # this is just an example * # there can be comments before the first group * * [First Group] * * Name=Key File Example\tthis value shows\nescaping * * # localized strings are stored in multiple key-value pairs * Welcome=Hello * Welcome[de]=Hallo * Welcome[fr_FR]=Bonjour * Welcome[it]=Ciao * Welcome[be@latin]=Hello * * [Another Group] * * Numbers=2;20;-200;0 * * Booleans=true;false;true;true * ]| * * Lines beginning with a '#' and blank lines are considered comments. * * Groups are started by a header line containing the group name enclosed * in '[' and ']', and ended implicitly by the start of the next group or * the end of the file. Each key-value pair must be contained in a group. * * Key-value pairs generally have the form `key=value`, with the * exception of localized strings, which have the form * `key[locale]=value`, with a locale identifier of the * form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER` * are optional. * Space before and after the '=' character are ignored. Newline, tab, * carriage return and backslash characters in value are escaped as \n, * \t, \r, and \\\\, respectively. To preserve leading spaces in values, * these can also be escaped as \s. * * Key files can store strings (possibly with localized variants), integers, * booleans and lists of these. Lists are separated by a separator character, * typically ';' or ','. To use the list separator character in a value in * a list, it has to be escaped by prefixing it with a backslash. * * This syntax is obviously inspired by the .ini files commonly met * on Windows, but there are some important differences: * * - .ini files use the ';' character to begin comments, * key files use the '#' character. * * - Key files do not allow for ungrouped keys meaning only * comments can precede the first group. * * - Key files are always encoded in UTF-8. * * - Key and Group names are case-sensitive. For example, a group called * [GROUP] is a different from [group]. * * - .ini files don't have a strongly typed boolean entry type, * they only have GetProfileInt(). In key files, only * true and false (in lower case) are allowed. * * Note that in contrast to the * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), * groups in key files may contain the same * key multiple times; the last entry wins. Key files may also contain * multiple groups with the same name; they are merged together. * Another difference is that keys and group names in key files are not * restricted to ASCII characters. * * Here is an example of loading a key file and reading a value: * |[ * g_autoptr(GError) error = NULL; * g_autoptr(GKeyFile) key_file = g_key_file_new (); * * if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error)) * { * if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT)) * g_warning ("Error loading key file: %s", error->message); * return; * } * * g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error); * if (val == NULL && * !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND)) * { * g_warning ("Error finding key in key file: %s", error->message); * return; * } * else if (val == NULL) * { * // Fall back to a default value. * val = g_strdup ("default-value"); * } * ]| * * Here is an example of creating and saving a key file: * |[ * g_autoptr(GKeyFile) key_file = g_key_file_new (); * const gchar *val = …; * g_autoptr(GError) error = NULL; * * g_key_file_set_string (key_file, "Group Name", "SomeKey", val); * * // Save as a file. * if (!g_key_file_save_to_file (key_file, "key-file.ini", &error)) * { * g_warning ("Error saving key file: %s", error->message); * return; * } * * // Or store to a GBytes for use elsewhere. * gsize data_len; * g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error); * if (data == NULL) * { * g_warning ("Error saving key file: %s", error->message); * return; * } * g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); * ]| */ /** * SECTION:linked_lists_double * @title: Doubly-Linked Lists * @short_description: linked lists that can be iterated over in both directions * * The #GList structure and its associated functions provide a standard * doubly-linked list data structure. * * Each element in the list contains a piece of data, together with * pointers which link to the previous and next elements in the list. * Using these pointers it is possible to move through the list in both * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], * which only allows movement through the list in the forward direction). * * The double linked list does not keep track of the number of items * and does not keep track of both the start and end of the list. If * you want fast access to both the start and the end of the list, * and/or the number of items in the list, use a * [GQueue][glib-Double-ended-Queues] instead. * * The data contained in each element can be either integer values, by * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], * or simply pointers to any type of data. * * List elements are allocated from the [slice allocator][glib-Memory-Slices], * which is more efficient than allocating elements individually. * * Note that most of the #GList functions expect to be passed a pointer * to the first element in the list. The functions which insert * elements return the new start of the list, which may have changed. * * There is no function to create a #GList. %NULL is considered to be * a valid, empty list so you simply set a #GList* to %NULL to initialize * it. * * To add elements, use g_list_append(), g_list_prepend(), * g_list_insert() and g_list_insert_sorted(). * * To visit all elements in the list, use a loop over the list: * |[ * GList *l; * for (l = list; l != NULL; l = l->next) * { * // do something with l->data * } * ]| * * To call a function for each element in the list, use g_list_foreach(). * * To loop over the list and modify it (e.g. remove a certain element) * a while loop is more appropriate, for example: * |[ * GList *l = list; * while (l != NULL) * { * GList *next = l->next; * if (should_be_removed (l)) * { * // possibly free l->data * list = g_list_delete_link (list, l); * } * l = next; * } * ]| * * To remove elements, use g_list_remove(). * * To navigate in a list, use g_list_first(), g_list_last(), * g_list_next(), g_list_previous(). * * To find elements in the list use g_list_nth(), g_list_nth_data(), * g_list_find() and g_list_find_custom(). * * To find the index of an element use g_list_position() and * g_list_index(). * * To free the entire list, use g_list_free() or g_list_free_full(). */ /** * SECTION:linked_lists_single * @title: Singly-Linked Lists * @short_description: linked lists that can be iterated in one direction * * The #GSList structure and its associated functions provide a * standard singly-linked list data structure. * * Each element in the list contains a piece of data, together with a * pointer which links to the next element in the list. Using this * pointer it is possible to move through the list in one direction * only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], * which allow movement in both directions). * * The data contained in each element can be either integer values, by * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], * or simply pointers to any type of data. * * List elements are allocated from the [slice allocator][glib-Memory-Slices], * which is more efficient than allocating elements individually. * * Note that most of the #GSList functions expect to be passed a * pointer to the first element in the list. The functions which insert * elements return the new start of the list, which may have changed. * * There is no function to create a #GSList. %NULL is considered to be * the empty list so you simply set a #GSList* to %NULL. * * To add elements, use g_slist_append(), g_slist_prepend(), * g_slist_insert() and g_slist_insert_sorted(). * * To remove elements, use g_slist_remove(). * * To find elements in the list use g_slist_last(), g_slist_next(), * g_slist_nth(), g_slist_nth_data(), g_slist_find() and * g_slist_find_custom(). * * To find the index of an element use g_slist_position() and * g_slist_index(). * * To call a function for each element in the list use * g_slist_foreach(). * * To free the entire list, use g_slist_free(). */ /** * SECTION:macros * @title: Standard Macros * @short_description: commonly-used macros * * These macros provide a few commonly-used features. */ /** * SECTION:macros_misc * @title: Miscellaneous Macros * @short_description: specialized macros which are not used often * * These macros provide more specialized features which are not * needed so often by application programmers. */ /** * SECTION:main * @title: The Main Event Loop * @short_description: manages all available sources of events * * The main event loop manages all the available sources of events for * GLib and GTK+ applications. These events can come from any number of * different types of sources such as file descriptors (plain files, * pipes or sockets) and timeouts. New types of event sources can also * be added using g_source_attach(). * * To allow multiple independent sets of sources to be handled in * different threads, each source is associated with a #GMainContext. * A GMainContext can only be running in a single thread, but * sources can be added to it and removed from it from other threads. * * Each event source is assigned a priority. The default priority, * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. * Values greater than 0 denote lower priorities. Events from high priority * sources are always processed before events from lower priority sources. * * Idle functions can also be added, and assigned a priority. These will * be run whenever no events with a higher priority are ready to be processed. * * The #GMainLoop data type represents a main event loop. A GMainLoop is * created with g_main_loop_new(). After adding the initial event sources, * g_main_loop_run() is called. This continuously checks for new events from * each of the event sources and dispatches them. Finally, the processing of * an event from one of the sources leads to a call to g_main_loop_quit() to * exit the main loop, and g_main_loop_run() returns. * * It is possible to create new instances of #GMainLoop recursively. * This is often used in GTK+ applications when showing modal dialog * boxes. Note that event sources are associated with a particular * #GMainContext, and will be checked and dispatched for all main * loops associated with that GMainContext. * * GTK+ contains wrappers of some of these functions, e.g. gtk_main(), * gtk_main_quit() and gtk_events_pending(). * * ## Creating new source types * * One of the unusual features of the #GMainLoop functionality * is that new types of event source can be created and used in * addition to the builtin type of event source. A new event source * type is used for handling GDK events. A new source type is created * by "deriving" from the #GSource structure. The derived type of * source is represented by a structure that has the #GSource structure * as a first element, and other elements specific to the new source * type. To create an instance of the new source type, call * g_source_new() passing in the size of the derived structure and * a table of functions. These #GSourceFuncs determine the behavior of * the new source type. * * New source types basically interact with the main context * in two ways. Their prepare function in #GSourceFuncs can set a timeout * to determine the maximum amount of time that the main loop will sleep * before checking the source again. In addition, or as well, the source * can add file descriptors to the set that the main context checks using * g_source_add_poll(). * * ## Customizing the main loop iteration * * Single iterations of a #GMainContext can be run with * g_main_context_iteration(). In some cases, more detailed control * of exactly how the details of the main loop work is desired, for * instance, when integrating the #GMainLoop with an external main loop. * In such cases, you can call the component functions of * g_main_context_iteration() directly. These functions are * g_main_context_prepare(), g_main_context_query(), * g_main_context_check() and g_main_context_dispatch(). * * ## State of a Main Context # {#mainloop-states} * * The operation of these functions can best be seen in terms * of a state diagram, as shown in this image. * * ![](mainloop-states.gif) * * On UNIX, the GLib mainloop is incompatible with fork(). Any program * using the mainloop must either exec() or exit() from the child * without returning to the mainloop. * * ## Memory management of sources # {#mainloop-memory-management} * * There are two options for memory management of the user data passed to a * #GSource to be passed to its callback on invocation. This data is provided * in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and * more generally, using g_source_set_callback(). This data is typically an * object which ‘owns’ the timeout or idle callback, such as a widget or a * network protocol implementation. In many cases, it is an error for the * callback to be invoked after this owning object has been destroyed, as that * results in use of freed memory. * * The first, and preferred, option is to store the source ID returned by * functions such as g_timeout_add() or g_source_attach(), and explicitly * remove that source from the main context using g_source_remove() when the * owning object is finalized. This ensures that the callback can only be * invoked while the object is still alive. * * The second option is to hold a strong reference to the object in the * callback, and to release it in the callback’s #GDestroyNotify. This ensures * that the object is kept alive until after the source is finalized, which is * guaranteed to be after it is invoked for the final time. The #GDestroyNotify * is another callback passed to the ‘full’ variants of #GSource functions (for * example, g_timeout_add_full()). It is called when the source is finalized, * and is designed for releasing references like this. * * One important caveat of this second approach is that it will keep the object * alive indefinitely if the main loop is stopped before the #GSource is * invoked, which may be undesirable. */ /** * SECTION:markup * @Title: Simple XML Subset Parser * @Short_description: parses a subset of XML * @See_also: [XML Specification](http://www.w3.org/TR/REC-xml/) * * The "GMarkup" parser is intended to parse a simple markup format * that's a subset of XML. This is a small, efficient, easy-to-use * parser. It should not be used if you expect to interoperate with * other applications generating full-scale XML. However, it's very * useful for application data files, config files, etc. where you * know your application will be the only one writing the file. * Full-scale XML parsers should be able to parse the subset used by * GMarkup, so you can easily migrate to full-scale XML at a later * time if the need arises. * * GMarkup is not guaranteed to signal an error on all invalid XML; * the parser may accept documents that an XML parser would not. * However, XML documents which are not well-formed (which is a * weaker condition than being valid. See the * [XML specification](http://www.w3.org/TR/REC-xml/) * for definitions of these terms.) are not considered valid GMarkup * documents. * * Simplifications to XML include: * * - Only UTF-8 encoding is allowed * * - No user-defined entities * * - Processing instructions, comments and the doctype declaration * are "passed through" but are not interpreted in any way * * - No DTD or validation * * The markup format does support: * * - Elements * * - Attributes * * - 5 standard entities: & < > " ' * * - Character references * * - Sections marked as CDATA */ /** * SECTION:memory * @Short_Description: general memory-handling * @Title: Memory Allocation * * These functions provide support for allocating and freeing memory. * * If any call to allocate memory using functions g_new(), g_new0(), g_renew(), * g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n() * fails, the application is terminated. This also means that there is no * need to check if the call succeeded. On the other hand, g_try_...() family * of functions returns %NULL on failure that can be used as a check * for unsuccessful memory allocation. The application is not terminated * in this case. * * It's important to match g_malloc() (and wrappers such as g_new()) with * g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with * g_slice_free(), plain malloc() with free(), and (if you're using C++) * new with delete and new[] with delete[]. Otherwise bad things can happen, * since these allocators may use different memory pools (and new/delete call * constructors and destructors). */ /** * SECTION:memory_slices * @title: Memory Slices * @short_description: efficient way to allocate groups of equal-sized * chunks of memory * * Memory slices provide a space-efficient and multi-processing scalable * way to allocate equal-sized pieces of memory, just like the original * #GMemChunks (from GLib 2.8), while avoiding their excessive * memory-waste, scalability and performance problems. * * To achieve these goals, the slice allocator uses a sophisticated, * layered design that has been inspired by Bonwick's slab allocator * ([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html) * Jeff Bonwick, The slab allocator: An object-caching kernel * memory allocator. USENIX 1994, and * [Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html) * Bonwick and Jonathan Adams, Magazines and vmem: Extending the * slab allocator to many cpu's and arbitrary resources. USENIX 2001) * * It uses posix_memalign() to optimize allocations of many equally-sized * chunks, and has per-thread free lists (the so-called magazine layer) * to quickly satisfy allocation requests of already known structure sizes. * This is accompanied by extra caching logic to keep freed memory around * for some time before returning it to the system. Memory that is unused * due to alignment constraints is used for cache colorization (random * distribution of chunk addresses) to improve CPU cache utilization. The * caching layer of the slice allocator adapts itself to high lock contention * to improve scalability. * * The slice allocator can allocate blocks as small as two pointers, and * unlike malloc(), it does not reserve extra space per block. For large block * sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the * system malloc() implementation. For newly written code it is recommended * to use the new `g_slice` API instead of g_malloc() and * friends, as long as objects are not resized during their lifetime and the * object size used at allocation time is still available when freeing. * * Here is an example for using the slice allocator: * |[ * gchar *mem[10000]; * gint i; * * // Allocate 10000 blocks. * for (i = 0; i < 10000; i++) * { * mem[i] = g_slice_alloc (50); * * // Fill in the memory with some junk. * for (j = 0; j < 50; j++) * mem[i][j] = i * j; * } * * // Now free all of the blocks. * for (i = 0; i < 10000; i++) * g_slice_free1 (50, mem[i]); * ]| * * And here is an example for using the using the slice allocator * with data structures: * |[ * GRealArray *array; * * // Allocate one block, using the g_slice_new() macro. * array = g_slice_new (GRealArray); * * // We can now use array just like a normal pointer to a structure. * array->data = NULL; * array->len = 0; * array->alloc = 0; * array->zero_terminated = (zero_terminated ? 1 : 0); * array->clear = (clear ? 1 : 0); * array->elt_size = elt_size; * * // We can free the block, so it can be reused. * g_slice_free (GRealArray, array); * ]| */ /** * SECTION:messages * @Title: Message Output and Debugging Functions * @Short_description: functions to output messages and help debug applications * * These functions provide support for outputting messages. * * The g_return family of macros (g_return_if_fail(), * g_return_val_if_fail(), g_return_if_reached(), * g_return_val_if_reached()) should only be used for programming * errors, a typical use case is checking for invalid parameters at * the beginning of a public function. They should not be used if * you just mean "if (error) return", they should only be used if * you mean "if (bug in program) return". The program behavior is * generally considered undefined after one of these checks fails. * They are not intended for normal control flow, only to give a * perhaps-helpful warning before giving up. * * Structured logging output is supported using g_log_structured(). This differs * from the traditional g_log() API in that log messages are handled as a * collection of key–value pairs representing individual pieces of information, * rather than as a single string containing all the information in an arbitrary * format. * * The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error() * will use the traditional g_log() API unless you define the symbol * %G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages * logged through the traditional g_log() API are ultimatively passed to * g_log_structured(), so that all log messages end up in same destination. * If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become * ineffective for the wrapper macros g_warning() and friends (see * [Testing for Messages][testing-for-messages]). * * The support for structured logging was motivated by the following needs (some * of which were supported previously; others weren’t): * * Support for multiple logging levels. * * Structured log support with the ability to add `MESSAGE_ID`s (see * g_log_structured()). * * Moving the responsibility for filtering log messages from the program to * the log viewer — instead of libraries and programs installing log handlers * (with g_log_set_handler()) which filter messages before output, all log * messages are outputted, and the log viewer program (such as `journalctl`) * must filter them. This is based on the idea that bugs are sometimes hard * to reproduce, so it is better to log everything possible and then use * tools to analyse the logs than it is to not be able to reproduce a bug to * get additional log data. Code which uses logging in performance-critical * sections should compile out the g_log_structured() calls in * release builds, and compile them in in debugging builds. * * A single writer function which handles all log messages in a process, from * all libraries and program code; rather than multiple log handlers with * poorly defined interactions between them. This allows a program to easily * change its logging policy by changing the writer function, for example to * log to an additional location or to change what logging output fallbacks * are used. The log writer functions provided by GLib are exposed publicly * so they can be used from programs’ log writers. This allows log writer * policy and implementation to be kept separate. * * If a library wants to add standard information to all of its log messages * (such as library state) or to redact private data (such as passwords or * network credentials), it should use a wrapper function around its * g_log_structured() calls or implement that in the single log writer * function. * * If a program wants to pass context data from a g_log_structured() call to * its log writer function so that, for example, it can use the correct * server connection to submit logs to, that user data can be passed as a * zero-length #GLogField to g_log_structured_array(). * * Color output needed to be supported on the terminal, to make reading * through logs easier. * * ## Using Structured Logging ## {#using-structured-logging} * * To use structured logging (rather than the old-style logging), either use * the g_log_structured() and g_log_structured_array() functions; or define * `G_LOG_USE_STRUCTURED` before including any GLib header, and use the * g_message(), g_debug(), g_error() (etc.) macros. * * You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(), * but it is a good idea to avoid confusion. * * ## Log Domains ## {#log-domains} * * Log domains may be used to broadly split up the origins of log messages. * Typically, there are one or a few log domains per application or library. * %G_LOG_DOMAIN should be used to define the default log domain for the current * compilation unit — it is typically defined at the top of a source file, or in * the preprocessor flags for a group of source files. * * Log domains must be unique, and it is recommended that they are the * application or library name, optionally followed by a hyphen and a sub-domain * name. For example, `bloatpad` or `bloatpad-io`. * * ## Debug Message Output ## {#debug-message-output} * * The default log functions (g_log_default_handler() for the old-style API and * g_log_writer_default() for the structured API) both drop debug and * informational messages by default, unless the log domains of those messages * are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to * `all`). * * It is recommended that custom log writer functions re-use the * `G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one, * so that developers can re-use the same debugging techniques and tools across * projects. * * ## Testing for Messages ## {#testing-for-messages} * * With the old g_log() API, g_test_expect_message() and * g_test_assert_expected_messages() could be used in simple cases to check * whether some code under test had emitted a given log message. These * functions have been deprecated with the structured logging API, for several * reasons: * * They relied on an internal queue which was too inflexible for many use * cases, where messages might be emitted in several orders, some * messages might not be emitted deterministically, or messages might be * emitted by unrelated log domains. * * They do not support structured log fields. * * Examining the log output of code is a bad approach to testing it, and * while it might be necessary for legacy code which uses g_log(), it should * be avoided for new code using g_log_structured(). * * They will continue to work as before if g_log() is in use (and * %G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the * structured logging API. * * Examining the log output of code is discouraged: libraries should not emit to * `stderr` during defined behaviour, and hence this should not be tested. If * the log emissions of a library during undefined behaviour need to be tested, * they should be limited to asserting that the library aborts and prints a * suitable error message before aborting. This should be done with * g_test_trap_assert_stderr(). * * If it is really necessary to test the structured log messages emitted by a * particular piece of code – and the code cannot be restructured to be more * suitable to more conventional unit testing – you should write a custom log * writer function (see g_log_set_writer_func()) which appends all log messages * to a queue. When you want to check the log messages, examine and clear the * queue, ignoring irrelevant log messages (for example, from log domains other * than the one under test). */ /** * SECTION:misc_utils * @title: Miscellaneous Utility Functions * @short_description: a selection of portable utility functions * * These are portable utility functions. */ /** * SECTION:numerical * @title: Numerical Definitions * @short_description: mathematical constants, and floating point decomposition * * GLib offers mathematical constants such as #G_PI for the value of pi; * many platforms have these in the C library, but some don't, the GLib * versions always exist. * * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the * sign, mantissa and exponent of IEEE floats and doubles. These unions are * defined as appropriate for a given platform. IEEE floats and doubles are * supported (used for storage) by at least Intel, PPC and Sparc. See * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) * for more information about IEEE number formats. */ /** * SECTION:option * @Short_description: parses commandline options * @Title: Commandline option parser * * The GOption commandline parser is intended to be a simpler replacement * for the popt library. It supports short and long commandline options, * as shown in the following example: * * `testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2` * * The example demonstrates a number of features of the GOption * commandline parser: * * - Options can be single letters, prefixed by a single dash. * * - Multiple short options can be grouped behind a single dash. * * - Long options are prefixed by two consecutive dashes. * * - Options can have an extra argument, which can be a number, a string or * a filename. For long options, the extra argument can be appended with * an equals sign after the option name, which is useful if the extra * argument starts with a dash, which would otherwise cause it to be * interpreted as another option. * * - Non-option arguments are returned to the application as rest arguments. * * - An argument consisting solely of two dashes turns off further parsing, * any remaining arguments (even those starting with a dash) are returned * to the application as rest arguments. * * Another important feature of GOption is that it can automatically * generate nicely formatted help output. Unless it is explicitly turned * off with g_option_context_set_help_enabled(), GOption will recognize * the `--help`, `-?`, `--help-all` and `--help-groupname` options * (where `groupname` is the name of a #GOptionGroup) and write a text * similar to the one shown in the following example to stdout. * * |[ * Usage: * testtreemodel [OPTION...] - test tree model performance * * Help Options: * -h, --help Show help options * --help-all Show all help options * --help-gtk Show GTK+ Options * * Application Options: * -r, --repeats=N Average over N repetitions * -m, --max-size=M Test up to 2^M items * --display=DISPLAY X display to use * -v, --verbose Be verbose * -b, --beep Beep when done * --rand Randomize the data * ]| * * GOption groups options in #GOptionGroups, which makes it easy to * incorporate options from multiple sources. The intended use for this is * to let applications collect option groups from the libraries it uses, * add them to their #GOptionContext, and parse all options by a single call * to g_option_context_parse(). See gtk_get_option_group() for an example. * * If an option is declared to be of type string or filename, GOption takes * care of converting it to the right encoding; strings are returned in * UTF-8, filenames are returned in the GLib filename encoding. Note that * this only works if setlocale() has been called before * g_option_context_parse(). * * Here is a complete example of setting up GOption to parse the example * commandline above and produce the example help output. * |[ * static gint repeats = 2; * static gint max_size = 8; * static gboolean verbose = FALSE; * static gboolean beep = FALSE; * static gboolean randomize = FALSE; * * static GOptionEntry entries[] = * { * { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" }, * { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" }, * { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL }, * { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL }, * { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL }, * { NULL } * }; * * int * main (int argc, char *argv[]) * { * GError *error = NULL; * GOptionContext *context; * * context = g_option_context_new ("- test tree model performance"); * g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE); * g_option_context_add_group (context, gtk_get_option_group (TRUE)); * if (!g_option_context_parse (context, &argc, &argv, &error)) * { * g_print ("option parsing failed: %s\n", error->message); * exit (1); * } * * ... * * } * ]| * * On UNIX systems, the argv that is passed to main() has no particular * encoding, even to the extent that different parts of it may have * different encodings. In general, normal arguments and flags will be * in the current locale and filenames should be considered to be opaque * byte strings. Proper use of %G_OPTION_ARG_FILENAME vs * %G_OPTION_ARG_STRING is therefore important. * * Note that on Windows, filenames do have an encoding, but using * #GOptionContext with the argv as passed to main() will result in a * program that can only accept commandline arguments with characters * from the system codepage. This can cause problems when attempting to * deal with filenames containing Unicode characters that fall outside * of the codepage. * * A solution to this is to use g_win32_get_command_line() and * g_option_context_parse_strv() which will properly handle full Unicode * filenames. If you are using #GApplication, this is done * automatically for you. * * The following example shows how you can use #GOptionContext directly * in order to correctly deal with Unicode filenames on Windows: * * |[ * int * main (int argc, char **argv) * { * GError *error = NULL; * GOptionContext *context; * gchar **args; * * #ifdef G_OS_WIN32 * args = g_win32_get_command_line (); * #else * args = g_strdupv (argv); * #endif * * // set up context * * if (!g_option_context_parse_strv (context, &args, &error)) * { * // error happened * } * * ... * * g_strfreev (args); * * ... * } * ]| */ /** * SECTION:patterns * @title: Glob-style pattern matching * @short_description: matches strings against patterns containing '*' * (wildcard) and '?' (joker) * * The g_pattern_match* functions match a string * against a pattern containing '*' and '?' wildcards with similar * semantics as the standard glob() function: '*' matches an arbitrary, * possibly empty, string, '?' matches an arbitrary character. * * Note that in contrast to glob(), the '/' character can be matched by * the wildcards, there are no '[...]' character ranges and '*' and '?' * can not be escaped to include them literally in a pattern. * * When multiple strings must be matched against the same pattern, it * is better to compile the pattern to a #GPatternSpec using * g_pattern_spec_new() and use g_pattern_match_string() instead of * g_pattern_match_simple(). This avoids the overhead of repeated * pattern compilation. */ /** * SECTION:quarks * @title: Quarks * @short_description: a 2-way association between a string and a * unique integer identifier * * Quarks are associations between strings and integer identifiers. * Given either the string or the #GQuark identifier it is possible to * retrieve the other. * * Quarks are used for both [datasets][glib-Datasets] and * [keyed data lists][glib-Keyed-Data-Lists]. * * To create a new quark from a string, use g_quark_from_string() or * g_quark_from_static_string(). * * To find the string corresponding to a given #GQuark, use * g_quark_to_string(). * * To find the #GQuark corresponding to a given string, use * g_quark_try_string(). * * Another use for the string pool maintained for the quark functions * is string interning, using g_intern_string() or * g_intern_static_string(). An interned string is a canonical * representation for a string. One important advantage of interned * strings is that they can be compared for equality by a simple * pointer comparison, rather than using strcmp(). */ /** * SECTION:queue * @Title: Double-ended Queues * @Short_description: double-ended queue data structure * * The #GQueue structure and its associated functions provide a standard * queue data structure. Internally, GQueue uses the same data structure * as #GList to store elements. * * The data contained in each element can be either integer values, by * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], * or simply pointers to any type of data. * * To create a new GQueue, use g_queue_new(). * * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or * g_queue_init(). * * To add elements, use g_queue_push_head(), g_queue_push_head_link(), * g_queue_push_tail() and g_queue_push_tail_link(). * * To remove elements, use g_queue_pop_head() and g_queue_pop_tail(). * * To free the entire queue, use g_queue_free(). */ /** * SECTION:random_numbers * @title: Random Numbers * @short_description: pseudo-random number generator * * The following functions allow you to use a portable, fast and good * pseudo-random number generator (PRNG). * * Do not use this API for cryptographic purposes such as key * generation, nonces, salts or one-time pads. * * This PRNG is suitable for non-cryptographic use such as in games * (shuffling a card deck, generating levels), generating data for * a test suite, etc. If you need random data for cryptographic * purposes, it is recommended to use platform-specific APIs such * as `/dev/random` on UNIX, or CryptGenRandom() on Windows. * * GRand uses the Mersenne Twister PRNG, which was originally * developed by Makoto Matsumoto and Takuji Nishimura. Further * information can be found at * [this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html). * * If you just need a random number, you simply call the g_random_* * functions, which will create a globally used #GRand and use the * according g_rand_* functions internally. Whenever you need a * stream of reproducible random numbers, you better create a * #GRand yourself and use the g_rand_* functions directly, which * will also be slightly faster. Initializing a #GRand with a * certain seed will produce exactly the same series of random * numbers on all platforms. This can thus be used as a seed for * e.g. games. * * The g_rand*_range functions will return high quality equally * distributed random numbers, whereas for example the * `(g_random_int()%max)` approach often * doesn't yield equally distributed numbers. * * GLib changed the seeding algorithm for the pseudo-random number * generator Mersenne Twister, as used by #GRand. This was necessary, * because some seeds would yield very bad pseudo-random streams. * Also the pseudo-random integers generated by g_rand*_int_range() * will have a slightly better equal distribution with the new * version of GLib. * * The original seeding and generation algorithms, as found in * GLib 2.0.x, can be used instead of the new ones by setting the * environment variable `G_RANDOM_VERSION` to the value of '2.0'. * Use the GLib-2.0 algorithms only if you have sequences of numbers * generated with Glib-2.0 that you need to reproduce exactly. */ /** * SECTION:scanner * @title: Lexical Scanner * @short_description: a general purpose lexical scanner * * The #GScanner and its associated functions provide a * general purpose lexical scanner. */ /** * SECTION:sequence * @title: Sequences * @short_description: scalable lists * * The #GSequence data structure has the API of a list, but is * implemented internally with a balanced binary tree. This means that * it is possible to maintain a sorted list of n elements in time O(n log n). * The data contained in each element can be either integer values, by using * of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply * pointers to any type of data. * * A #GSequence is accessed through "iterators", represented by a * #GSequenceIter. An iterator represents a position between two * elements of the sequence. For example, the "begin" iterator * represents the gap immediately before the first element of the * sequence, and the "end" iterator represents the gap immediately * after the last element. In an empty sequence, the begin and end * iterators are the same. * * Some methods on #GSequence operate on ranges of items. For example * g_sequence_foreach_range() will call a user-specified function on * each element with the given range. The range is delimited by the * gaps represented by the passed-in iterators, so if you pass in the * begin and end iterators, the range in question is the entire * sequence. * * The function g_sequence_get() is used with an iterator to access the * element immediately following the gap that the iterator represents. * The iterator is said to "point" to that element. * * Iterators are stable across most operations on a #GSequence. For * example an iterator pointing to some element of a sequence will * continue to point to that element even after the sequence is sorted. * Even moving an element to another sequence using for example * g_sequence_move_range() will not invalidate the iterators pointing * to it. The only operation that will invalidate an iterator is when * the element it points to is removed from any sequence. * * To sort the data, either use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to the #GSequence or, if * you want to add a large amount of data, it is more efficient to call * g_sequence_sort() or g_sequence_sort_iter() after doing unsorted * insertions. */ /** * SECTION:shell * @title: Shell-related Utilities * @short_description: shell-like commandline handling * * GLib provides the functions g_shell_quote() and g_shell_unquote() * to handle shell-like quoting in strings. The function g_shell_parse_argv() * parses a string similar to the way a POSIX shell (/bin/sh) would. * * Note that string handling in shells has many obscure and historical * corner-cases which these functions do not necessarily reproduce. They * are good enough in practice, though. */ /** * SECTION:spawn * @Short_description: process launching * @Title: Spawning Processes * * GLib supports spawning of processes with an API that is more * convenient than the bare UNIX fork() and exec(). * * The g_spawn family of functions has synchronous (g_spawn_sync()) * and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()), * as well as convenience variants that take a complete shell-like * commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()). * * See #GSubprocess in GIO for a higher-level API that provides * stream interfaces for communication with child processes. * * An example of using g_spawn_async_with_pipes(): * |[ * const gchar * const argv[] = { "my-favourite-program", "--args", NULL }; * gint child_stdout, child_stderr; * GPid child_pid; * g_autoptr(GError) error = NULL; * * // Spawn child process. * g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL, * NULL, &child_pid, NULL, &child_stdout, * &child_stderr, &error); * if (error != NULL) * { * g_error ("Spawning child failed: %s", error->message); * return; * } * * // Add a child watch function which will be called when the child process * // exits. * g_child_watch_add (child_pid, child_watch_cb, NULL); * * // You could watch for output on @child_stdout and @child_stderr using * // #GUnixInputStream or #GIOChannel here. * * static void * child_watch_cb (GPid pid, * gint status, * gpointer user_data) * { * g_message ("Child %" G_PID_FORMAT " exited %s", pid, * g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally"); * * // Free any resources associated with the child here, such as I/O channels * // on its stdout and stderr FDs. If you have no code to put in the * // child_watch_cb() callback, you can remove it and the g_child_watch_add() * // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag, * // otherwise the child process will stay around as a zombie until this * // process exits. * * g_spawn_close_pid (pid); * } * ]| */ /** * SECTION:string_chunks * @title: String Chunks * @short_description: efficient storage of groups of strings * * String chunks are used to store groups of strings. Memory is * allocated in blocks, and as strings are added to the #GStringChunk * they are copied into the next free position in a block. When a block * is full a new block is allocated. * * When storing a large number of strings, string chunks are more * efficient than using g_strdup() since fewer calls to malloc() are * needed, and less memory is wasted in memory allocation overheads. * * By adding strings with g_string_chunk_insert_const() it is also * possible to remove duplicates. * * To create a new #GStringChunk use g_string_chunk_new(). * * To add strings to a #GStringChunk use g_string_chunk_insert(). * * To add strings to a #GStringChunk, but without duplicating strings * which are already in the #GStringChunk, use * g_string_chunk_insert_const(). * * To free the entire #GStringChunk use g_string_chunk_free(). It is * not possible to free individual strings. */ /** * SECTION:string_utils * @title: String Utility Functions * @short_description: various string-related functions * * This section describes a number of utility functions for creating, * duplicating, and manipulating strings. * * Note that the functions g_printf(), g_fprintf(), g_sprintf(), * g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf() * are declared in the header `gprintf.h` which is not included in `glib.h` * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to * explicitly include `` in order to use the GLib * printf() functions. * * ## String precision pitfalls # {#string-precision} * * While you may use the printf() functions to format UTF-8 strings, * notice that the precision of a \%Ns parameter is interpreted * as the number of bytes, not characters to print. On top of that, * the GNU libc implementation of the printf() functions has the * "feature" that it checks that the string given for the \%Ns * parameter consists of a whole number of characters in the current * encoding. So, unless you are sure you are always going to be in an * UTF-8 locale or your know your text is restricted to ASCII, avoid * using \%Ns. If your intention is to format strings for a * certain number of columns, then \%Ns is not a correct solution * anyway, since it fails to take wide characters (see g_unichar_iswide()) * into account. * * Note also that there are various printf() parameters which are platform * dependent. GLib provides platform independent macros for these parameters * which should be used instead. A common example is %G_GUINT64_FORMAT, which * should be used instead of `%llu` or similar parameters for formatting * 64-bit integers. These macros are all named `G_*_FORMAT`; see * [Basic Types][glib-Basic-Types]. */ /** * SECTION:strings * @title: Strings * @short_description: text buffers which grow automatically * as text is added * * A #GString is an object that handles the memory management of a C * string for you. The emphasis of #GString is on text, typically * UTF-8. Crucially, the "str" member of a #GString is guaranteed to * have a trailing nul character, and it is therefore always safe to * call functions such as strchr() or g_strdup() on it. * * However, a #GString can also hold arbitrary binary data, because it * has a "len" member, which includes any possible embedded nul * characters in the data. Conceptually then, #GString is like a * #GByteArray with the addition of many convenience methods for text, * and a guaranteed nul terminator. */ /** * SECTION:testing * @title: Testing * @short_description: a test framework * @see_also: [gtester][gtester], [gtester-report][gtester-report] * * GLib provides a framework for writing and maintaining unit tests * in parallel to the code they are testing. The API is designed according * to established concepts found in the other test frameworks (JUnit, NUnit, * RUnit), which in turn is based on smalltalk unit testing concepts. * * - Test case: Tests (test methods) are grouped together with their * fixture into test cases. * * - Fixture: A test fixture consists of fixture data and setup and * teardown methods to establish the environment for the test * functions. We use fresh fixtures, i.e. fixtures are newly set * up and torn down around each test invocation to avoid dependencies * between tests. * * - Test suite: Test cases can be grouped into test suites, to allow * subsets of the available tests to be run. Test suites can be * grouped into other test suites as well. * * The API is designed to handle creation and registration of test suites * and test cases implicitly. A simple call like * |[ * g_test_add_func ("/misc/assertions", test_assertions); * ]| * creates a test suite called "misc" with a single test case named * "assertions", which consists of running the test_assertions function. * * In addition to the traditional g_assert(), the test framework provides * an extended set of assertions for comparisons: g_assert_cmpfloat(), * g_assert_cmpint(), g_assert_cmpuint(), g_assert_cmphex(), * g_assert_cmpstr(), and g_assert_cmpmem(). The advantage of these * variants over plain g_assert() is that the assertion messages can be * more elaborate, and include the values of the compared entities. * * A full example of creating a test suite with two tests using fixtures: * |[ * #include * #include * * typedef struct { * MyObject *obj; * OtherObject *helper; * } MyObjectFixture; * * static void * my_object_fixture_set_up (MyObjectFixture *fixture, * gconstpointer user_data) * { * fixture->obj = my_object_new (); * my_object_set_prop1 (fixture->obj, "some-value"); * my_object_do_some_complex_setup (fixture->obj, user_data); * * fixture->helper = other_object_new (); * } * * static void * my_object_fixture_tear_down (MyObjectFixture *fixture, * gconstpointer user_data) * { * g_clear_object (&fixture->helper); * g_clear_object (&fixture->obj); * } * * static void * test_my_object_test1 (MyObjectFixture *fixture, * gconstpointer user_data) * { * g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value"); * } * * static void * test_my_object_test2 (MyObjectFixture *fixture, * gconstpointer user_data) * { * my_object_do_some_work_using_helper (fixture->obj, fixture->helper); * g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value"); * } * * int * main (int argc, char *argv[]) * { * setlocale (LC_ALL, ""); * * g_test_init (&argc, &argv, NULL); * g_test_bug_base ("http://bugzilla.gnome.org/show_bug.cgi?id="); * * // Define the tests. * g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data", * my_object_fixture_set_up, test_my_object_test1, * my_object_fixture_tear_down); * g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data", * my_object_fixture_set_up, test_my_object_test2, * my_object_fixture_tear_down); * * return g_test_run (); * } * ]| * * ### Integrating GTest in your project * * If you are using the [Meson](http://mesonbuild.com) build system, you will * typically use the provided `test()` primitive to call the test binaries, * e.g.: * * |[ * test( * 'foo', * executable('foo', 'foo.c', dependencies: deps), * env: [ * 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), * 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), * ], * ) * * test( * 'bar', * executable('bar', 'bar.c', dependencies: deps), * env: [ * 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), * 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), * ], * ) * ]| * * If you are using Autotools, you're strongly encouraged to use the Automake * [TAP](https://testanything.org/) harness; GLib provides template files for * easily integrating with it: * * - [glib-tap.mk](https://git.gnome.org/browse/glib/tree/glib-tap.mk) * - [tap-test](https://git.gnome.org/browse/glib/tree/tap-test) * - [tap-driver.sh](https://git.gnome.org/browse/glib/tree/tap-driver.sh) * * You can copy these files in your own project's root directory, and then * set up your `Makefile.am` file to reference them, for instance: * * |[ * include $(top_srcdir)/glib-tap.mk * * # test binaries * test_programs = \ * foo \ * bar * * # data distributed in the tarball * dist_test_data = \ * foo.data.txt \ * bar.data.txt * * # data not distributed in the tarball * test_data = \ * blah.data.txt * ]| * * Make sure to distribute the TAP files, using something like the following * in your top-level `Makefile.am`: * * |[ * EXTRA_DIST += \ * tap-driver.sh \ * tap-test * ]| * * `glib-tap.mk` will be distributed implicitly due to being included in a * `Makefile.am`. All three files should be added to version control. * * If you don't have access to the Autotools TAP harness, you can use the * [gtester][gtester] and [gtester-report][gtester-report] tools, and use * the [glib.mk](https://git.gnome.org/browse/glib/tree/glib.mk) Automake * template provided by GLib. */ /** * SECTION:thread_pools * @title: Thread Pools * @short_description: pools of threads to execute work concurrently * @see_also: #GThread * * Sometimes you wish to asynchronously fork out the execution of work * and continue working in your own thread. If that will happen often, * the overhead of starting and destroying a thread each time might be * too high. In such cases reusing already started threads seems like a * good idea. And it indeed is, but implementing this can be tedious * and error-prone. * * Therefore GLib provides thread pools for your convenience. An added * advantage is, that the threads can be shared between the different * subsystems of your program, when they are using GLib. * * To create a new thread pool, you use g_thread_pool_new(). * It is destroyed by g_thread_pool_free(). * * If you want to execute a certain task within a thread pool, * you call g_thread_pool_push(). * * To get the current number of running threads you call * g_thread_pool_get_num_threads(). To get the number of still * unprocessed tasks you call g_thread_pool_unprocessed(). To control * the maximal number of threads for a thread pool, you use * g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads(). * * Finally you can control the number of unused threads, that are kept * alive by GLib for future use. The current number can be fetched with * g_thread_pool_get_num_unused_threads(). The maximal number can be * controlled by g_thread_pool_get_max_unused_threads() and * g_thread_pool_set_max_unused_threads(). All currently unused threads * can be stopped by calling g_thread_pool_stop_unused_threads(). */ /** * SECTION:threads * @title: Threads * @short_description: portable support for threads, mutexes, locks, * conditions and thread private data * @see_also: #GThreadPool, #GAsyncQueue * * Threads act almost like processes, but unlike processes all threads * of one process share the same memory. This is good, as it provides * easy communication between the involved threads via this shared * memory, and it is bad, because strange things (so called * "Heisenbugs") might happen if the program is not carefully designed. * In particular, due to the concurrent nature of threads, no * assumptions on the order of execution of code running in different * threads can be made, unless order is explicitly forced by the * programmer through synchronization primitives. * * The aim of the thread-related functions in GLib is to provide a * portable means for writing multi-threaded software. There are * primitives for mutexes to protect the access to portions of memory * (#GMutex, #GRecMutex and #GRWLock). There is a facility to use * individual bits for locks (g_bit_lock()). There are primitives * for condition variables to allow synchronization of threads (#GCond). * There are primitives for thread-private data - data that every * thread has a private instance of (#GPrivate). There are facilities * for one-time initialization (#GOnce, g_once_init_enter()). Finally, * there are primitives to create and manage threads (#GThread). * * The GLib threading system used to be initialized with g_thread_init(). * This is no longer necessary. Since version 2.32, the GLib threading * system is automatically initialized at the start of your program, * and all thread-creation functions and synchronization primitives * are available right away. * * Note that it is not safe to assume that your program has no threads * even if you don't call g_thread_new() yourself. GLib and GIO can * and will create threads for their own purposes in some cases, such * as when using g_unix_signal_source_new() or when using GDBus. * * Originally, UNIX did not have threads, and therefore some traditional * UNIX APIs are problematic in threaded programs. Some notable examples * are * * - C library functions that return data in statically allocated * buffers, such as strtok() or strerror(). For many of these, * there are thread-safe variants with a _r suffix, or you can * look at corresponding GLib APIs (like g_strsplit() or g_strerror()). * * - The functions setenv() and unsetenv() manipulate the process * environment in a not thread-safe way, and may interfere with getenv() * calls in other threads. Note that getenv() calls may be hidden behind * other APIs. For example, GNU gettext() calls getenv() under the * covers. In general, it is best to treat the environment as readonly. * If you absolutely have to modify the environment, do it early in * main(), when no other threads are around yet. * * - The setlocale() function changes the locale for the entire process, * affecting all threads. Temporary changes to the locale are often made * to change the behavior of string scanning or formatting functions * like scanf() or printf(). GLib offers a number of string APIs * (like g_ascii_formatd() or g_ascii_strtod()) that can often be * used as an alternative. Or you can use the uselocale() function * to change the locale only for the current thread. * * - The fork() function only takes the calling thread into the child's * copy of the process image. If other threads were executing in critical * sections they could have left mutexes locked which could easily * cause deadlocks in the new child. For this reason, you should * call exit() or exec() as soon as possible in the child and only * make signal-safe library calls before that. * * - The daemon() function uses fork() in a way contrary to what is * described above. It should not be used with GLib programs. * * GLib itself is internally completely thread-safe (all global data is * automatically locked), but individual data structure instances are * not automatically locked for performance reasons. For example, * you must coordinate accesses to the same #GHashTable from multiple * threads. The two notable exceptions from this rule are #GMainLoop * and #GAsyncQueue, which are thread-safe and need no further * application-level locking to be accessed from multiple threads. * Most refcounting functions such as g_object_ref() are also thread-safe. * * A common use for #GThreads is to move a long-running blocking operation out * of the main thread and into a worker thread. For GLib functions, such as * single GIO operations, this is not necessary, and complicates the code. * Instead, the `…_async()` version of the function should be used from the main * thread, eliminating the need for locking and synchronisation between multiple * threads. If an operation does need to be moved to a worker thread, consider * using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a * better choice than #GThread, as it handles thread reuse and task queueing; * #GTask uses this internally. * * However, if multiple blocking operations need to be performed in sequence, * and it is not possible to use #GTask for them, moving them to a worker thread * can clarify the code. */ /** * SECTION:timers * @title: Timers * @short_description: keep track of elapsed time * * #GTimer records a start time, and counts microseconds elapsed since * that time. This is done somewhat differently on different platforms, * and can be tricky to get exactly right, so #GTimer provides a * portable/convenient interface. */ /** * SECTION:timezone * @title: GTimeZone * @short_description: a structure representing a time zone * @see_also: #GDateTime * * #GTimeZone is a structure that represents a time zone, at no * particular point in time. It is refcounted and immutable. * * A time zone contains a number of intervals. Each interval has * an abbreviation to describe it, an offet to UTC and a flag indicating * if the daylight savings time is in effect during that interval. A * time zone always has at least one interval -- interval 0. * * Every UTC time is contained within exactly one interval, but a given * local time may be contained within zero, one or two intervals (due to * incontinuities associated with daylight savings time). * * An interval may refer to a specific period of time (eg: the duration * of daylight savings time during 2010) or it may refer to many periods * of time that share the same properties (eg: all periods of daylight * savings time). It is also possible (usually for political reasons) * that some properties (like the abbreviation) change between intervals * without other properties changing. * * #GTimeZone is available since GLib 2.26. */ /** * SECTION:trash_stack * @title: Trash Stacks * @short_description: maintain a stack of unused allocated memory chunks * * A #GTrashStack is an efficient way to keep a stack of unused allocated * memory chunks. Each memory chunk is required to be large enough to hold * a #gpointer. This allows the stack to be maintained without any space * overhead, since the stack pointers can be stored inside the memory chunks. * * There is no function to create a #GTrashStack. A %NULL #GTrashStack* * is a perfectly valid empty stack. * * There is no longer any good reason to use #GTrashStack. If you have * extra pieces of memory, free() them and allocate them again later. * * Deprecated: 2.48: #GTrashStack is deprecated without replacement */ /** * SECTION:trees-binary * @title: Balanced Binary Trees * @short_description: a sorted collection of key/value pairs optimized * for searching and traversing in order * * The #GTree structure and its associated functions provide a sorted * collection of key/value pairs optimized for searching and traversing * in order. * * To create a new #GTree use g_tree_new(). * * To insert a key/value pair into a #GTree use g_tree_insert(). * * To lookup the value corresponding to a given key, use * g_tree_lookup() and g_tree_lookup_extended(). * * To find out the number of nodes in a #GTree, use g_tree_nnodes(). To * get the height of a #GTree, use g_tree_height(). * * To traverse a #GTree, calling a function for each node visited in * the traversal, use g_tree_foreach(). * * To remove a key/value pair use g_tree_remove(). * * To destroy a #GTree, use g_tree_destroy(). */ /** * SECTION:trees-nary * @title: N-ary Trees * @short_description: trees of data with any number of branches * * The #GNode struct and its associated functions provide a N-ary tree * data structure, where nodes in the tree can contain arbitrary data. * * To create a new tree use g_node_new(). * * To insert a node into a tree use g_node_insert(), * g_node_insert_before(), g_node_append() and g_node_prepend(). * * To create a new node and insert it into a tree use * g_node_insert_data(), g_node_insert_data_after(), * g_node_insert_data_before(), g_node_append_data() * and g_node_prepend_data(). * * To reverse the children of a node use g_node_reverse_children(). * * To find a node use g_node_get_root(), g_node_find(), * g_node_find_child(), g_node_child_index(), g_node_child_position(), * g_node_first_child(), g_node_last_child(), g_node_nth_child(), * g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() * or g_node_last_sibling(). * * To get information about a node or tree use G_NODE_IS_LEAF(), * G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), * g_node_n_children(), g_node_is_ancestor() or g_node_max_height(). * * To traverse a tree, calling a function for each node visited in the * traversal, use g_node_traverse() or g_node_children_foreach(). * * To remove a node or subtree from a tree use g_node_unlink() or * g_node_destroy(). */ /** * SECTION:type_conversion * @title: Type Conversion Macros * @short_description: portably storing integers in pointer variables * * Many times GLib, GTK+, and other libraries allow you to pass "user * data" to a callback, in the form of a void pointer. From time to time * you want to pass an integer instead of a pointer. You could allocate * an integer, with something like: * |[ * int *ip = g_new (int, 1); * *ip = 42; * ]| * But this is inconvenient, and it's annoying to have to free the * memory at some later time. * * Pointers are always at least 32 bits in size (on all platforms GLib * intends to support). Thus you can store at least 32-bit integer values * in a pointer value. Naively, you might try this, but it's incorrect: * |[ * gpointer p; * int i; * p = (void*) 42; * i = (int) p; * ]| * Again, that example was not correct, don't copy it. * The problem is that on some systems you need to do this: * |[ * gpointer p; * int i; * p = (void*) (long) 42; * i = (int) (long) p; * ]| * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care * to do the right thing on the every platform. * * Warning: You may not store pointers in integers. This is not * portable in any way, shape or form. These macros only allow storing * integers in pointers, and only preserve 32 bits of the integer; values * outside the range of a 32-bit integer will be mangled. */ /** * SECTION:types * @title: Basic Types * @short_description: standard GLib types, defined for ease-of-use * and portability * * GLib defines a number of commonly used types, which can be divided * into several groups: * - New types which are not part of standard C (but are defined in * various C standard library header files) — #gboolean, #gssize. * - Integer types which are guaranteed to be the same size across * all platforms — #gint8, #guint8, #gint16, #guint16, #gint32, * #guint32, #gint64, #guint64. * - Types which are easier to use than their standard C counterparts - * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. * - Types which correspond exactly to standard C types, but are * included for completeness — #gchar, #gint, #gshort, #glong, * #gfloat, #gdouble. * - Types which correspond exactly to standard C99 types, but are available * to use even if your compiler does not support C99 — #gsize, #goffset, * #gintptr, #guintptr. * * GLib also defines macros for the limits of some of the standard * integer and floating point types, as well as macros for suitable * printf() formats for these types. */ /** * SECTION:unicode * @Title: Unicode Manipulation * @Short_description: functions operating on Unicode characters and * UTF-8 strings * @See_also: g_locale_to_utf8(), g_locale_from_utf8() * * This section describes a number of functions for dealing with * Unicode characters and strings. There are analogues of the * traditional `ctype.h` character classification and case conversion * functions, UTF-8 analogues of some string utility functions, * functions to perform normalization, case conversion and collation * on UTF-8 strings and finally functions to convert between the UTF-8, * UTF-16 and UCS-4 encodings of Unicode. * * The implementations of the Unicode functions in GLib are based * on the Unicode Character Data tables, which are available from * [www.unicode.org](http://www.unicode.org/). * GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1, * GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1, * GLib 2.30 supports Unicode 6.0. */ /** * SECTION:uuid * @title: GUuid * @short_description: a universally unique identifier * * A UUID, or Universally unique identifier, is intended to uniquely * identify information in a distributed environment. For the * definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html). * * The creation of UUIDs does not require a centralized authority. * * UUIDs are of relatively small size (128 bits, or 16 bytes). The * common string representation (ex: * 1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes. * * The UUID specification defines 5 versions, and calling * g_uuid_string_random() will generate a unique (or rather random) * UUID of the most common version, version 4. * * Since: 2.52 */ /** * SECTION:version * @Title: Version Information * @Short_description: variables and functions to check the GLib version * * GLib provides version information, primarily useful in configure * checks for builds that have a configure script. Applications will * not typically use the features described here. * * The GLib headers annotate deprecated APIs in a way that produces * compiler warnings if these deprecated APIs are used. The warnings * can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS * before including the glib.h header. * * GLib also provides support for building applications against * defined subsets of deprecated or new GLib APIs. Define the macro * %GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib * you want to receive warnings about deprecated APIs. Define the * macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of * GLib whose API you want to use. */ /** * SECTION:windows * @title: Windows Compatibility Functions * @short_description: UNIX emulation on Windows * * These functions provide some level of UNIX emulation on the * Windows platform. If your application really needs the POSIX * APIs, we suggest you try the Cygwin project. */ /** * TRUE: * * Defines the %TRUE value for the #gboolean type. */ /** * _: * @String: the string to be translated * * Marks a string for translation, gets replaced with the translated string * at runtime. * * Since: 2.4 */ /** * _glib_get_locale_dir: * * Return the path to the share\locale or lib\locale subfolder of the * GLib installation folder. The path is in the system codepage. We * have to use system codepage as bindtextdomain() doesn't have a * UTF-8 interface. */ /** * g_abort: * * A wrapper for the POSIX abort() function. * * On Windows it is a function that makes extra effort (including a call * to abort()) to ensure that a debugger-catchable exception is thrown * before the program terminates. * * See your C library manual for more details about abort(). * * Since: 2.50 */ /** * g_access: * @filename: (type filename): a pathname in the GLib file name encoding * (UTF-8 on Windows) * @mode: as in access() * * A wrapper for the POSIX access() function. This function is used to * test a pathname for one or several of read, write or execute * permissions, or just existence. * * On Windows, the file protection mechanism is not at all POSIX-like, * and the underlying function in the C library only checks the * FAT-style READONLY attribute, and does not look at the ACL of a * file at all. This function is this in practise almost useless on * Windows. Software that needs to handle file permissions on Windows * more exactly should use the Win32 API. * * See your C library manual for more details about access(). * * Returns: zero if the pathname refers to an existing file system * object that has all the tested permissions, or -1 otherwise * or on error. * Since: 2.8 */ /** * g_array_append_val: * @a: a #GArray * @v: the value to append to the #GArray * * Adds the value on to the end of the array. The array will grow in * size automatically if necessary. * * g_array_append_val() is a macro which uses a reference to the value * parameter @v. This means that you cannot use it with literal values * such as "27". You must use variables. * * Returns: the #GArray */ /** * g_array_append_vals: * @array: a #GArray * @data: (not nullable): a pointer to the elements to append to the end of the array * @len: the number of elements to append * * Adds @len elements onto the end of the array. * * Returns: the #GArray */ /** * g_array_free: * @array: a #GArray * @free_segment: if %TRUE the actual element data is freed as well * * Frees the memory allocated for the #GArray. If @free_segment is * %TRUE it frees the memory block holding the elements as well and * also each element if @array has a @element_free_func set. Pass * %FALSE if you want to free the #GArray wrapper but preserve the * underlying array for use elsewhere. If the reference count of @array * is greater than one, the #GArray wrapper is preserved but the size * of @array will be set to zero. * * If array elements contain dynamically-allocated memory, they should * be freed separately. * * This function is not thread-safe. If using a #GArray from multiple * threads, use only the atomic g_array_ref() and g_array_unref() * functions. * * Returns: the element data if @free_segment is %FALSE, otherwise * %NULL. The element data should be freed using g_free(). */ /** * g_array_get_element_size: * @array: A #GArray * * Gets the size of the elements in @array. * * Returns: Size of each element, in bytes * Since: 2.22 */ /** * g_array_index: * @a: a #GArray * @t: the type of the elements * @i: the index of the element to return * * Returns the element of a #GArray at the given index. The return * value is cast to the given type. * * This example gets a pointer to an element in a #GArray: * |[ * EDayViewEvent *event; * // This gets a pointer to the 4th element in the array of * // EDayViewEvent structs. * event = &g_array_index (events, EDayViewEvent, 3); * ]| * * Returns: the element of the #GArray at the index given by @i */ /** * g_array_insert_val: * @a: a #GArray * @i: the index to place the element at * @v: the value to insert into the array * * Inserts an element into an array at the given index. * * g_array_insert_val() is a macro which uses a reference to the value * parameter @v. This means that you cannot use it with literal values * such as "27". You must use variables. * * Returns: the #GArray */ /** * g_array_insert_vals: * @array: a #GArray * @index_: the index to place the elements at * @data: (not nullable): a pointer to the elements to insert * @len: the number of elements to insert * * Inserts @len elements into a #GArray at the given index. * * Returns: the #GArray */ /** * g_array_new: * @zero_terminated: %TRUE if the array should have an extra element at * the end which is set to 0 * @clear_: %TRUE if #GArray elements should be automatically cleared * to 0 when they are allocated * @element_size: the size of each element in bytes * * Creates a new #GArray with a reference count of 1. * * Returns: the new #GArray */ /** * g_array_prepend_val: * @a: a #GArray * @v: the value to prepend to the #GArray * * Adds the value on to the start of the array. The array will grow in * size automatically if necessary. * * This operation is slower than g_array_append_val() since the * existing elements in the array have to be moved to make space for * the new element. * * g_array_prepend_val() is a macro which uses a reference to the value * parameter @v. This means that you cannot use it with literal values * such as "27". You must use variables. * * Returns: the #GArray */ /** * g_array_prepend_vals: * @array: a #GArray * @data: (not nullable): a pointer to the elements to prepend to the start of the array * @len: the number of elements to prepend * * Adds @len elements onto the start of the array. * * This operation is slower than g_array_append_vals() since the * existing elements in the array have to be moved to make space for * the new elements. * * Returns: the #GArray */ /** * g_array_ref: * @array: A #GArray * * Atomically increments the reference count of @array by one. * This function is thread-safe and may be called from any thread. * * Returns: The passed in #GArray * Since: 2.22 */ /** * g_array_remove_index: * @array: a #GArray * @index_: the index of the element to remove * * Removes the element at the given index from a #GArray. The following * elements are moved down one place. * * Returns: the #GArray */ /** * g_array_remove_index_fast: * @array: a @GArray * @index_: the index of the element to remove * * Removes the element at the given index from a #GArray. The last * element in the array is used to fill in the space, so this function * does not preserve the order of the #GArray. But it is faster than * g_array_remove_index(). * * Returns: the #GArray */ /** * g_array_remove_range: * @array: a @GArray * @index_: the index of the first element to remove * @length: the number of elements to remove * * Removes the given number of elements starting at the given index * from a #GArray. The following elements are moved to close the gap. * * Returns: the #GArray * Since: 2.4 */ /** * g_array_set_clear_func: * @array: A #GArray * @clear_func: a function to clear an element of @array * * Sets a function to clear an element of @array. * * The @clear_func will be called when an element in the array * data segment is removed and when the array is freed and data * segment is deallocated as well. * * Note that in contrast with other uses of #GDestroyNotify * functions, @clear_func is expected to clear the contents of * the array element it is given, but not free the element itself. * * Since: 2.32 */ /** * g_array_set_size: * @array: a #GArray * @length: the new size of the #GArray * * Sets the size of the array, expanding it if necessary. If the array * was created with @clear_ set to %TRUE, the new elements are set to 0. * * Returns: the #GArray */ /** * g_array_sized_new: * @zero_terminated: %TRUE if the array should have an extra element at * the end with all bits cleared * @clear_: %TRUE if all bits in the array should be cleared to 0 on * allocation * @element_size: size of each element in the array * @reserved_size: number of elements preallocated * * Creates a new #GArray with @reserved_size elements preallocated and * a reference count of 1. This avoids frequent reallocation, if you * are going to add many elements to the array. Note however that the * size of the array is still 0. * * Returns: the new #GArray */ /** * g_array_sort: * @array: a #GArray * @compare_func: comparison function * * Sorts a #GArray using @compare_func which should be a qsort()-style * comparison function (returns less than zero for first arg is less * than second arg, zero for equal, greater zero if first arg is * greater than second arg). * * This is guaranteed to be a stable sort since version 2.32. */ /** * g_array_sort_with_data: * @array: a #GArray * @compare_func: comparison function * @user_data: data to pass to @compare_func * * Like g_array_sort(), but the comparison function receives an extra * user data argument. * * This is guaranteed to be a stable sort since version 2.32. * * There used to be a comment here about making the sort stable by * using the addresses of the elements in the comparison function. * This did not actually work, so any such code should be removed. */ /** * g_array_unref: * @array: A #GArray * * Atomically decrements the reference count of @array by one. If the * reference count drops to 0, all memory allocated by the array is * released. This function is thread-safe and may be called from any * thread. * * Since: 2.22 */ /** * g_ascii_digit_value: * @c: an ASCII character * * Determines the numeric value of a character as a decimal digit. * Differs from g_unichar_digit_value() because it takes a char, so * there's no worry about sign extension if characters are signed. * * Returns: If @c is a decimal digit (according to g_ascii_isdigit()), * its numeric value. Otherwise, -1. */ /** * g_ascii_dtostr: * @buffer: A buffer to place the resulting string in * @buf_len: The length of the buffer. * @d: The #gdouble to convert * * Converts a #gdouble to a string, using the '.' as * decimal point. * * This function generates enough precision that converting * the string back using g_ascii_strtod() gives the same machine-number * (on machines with IEEE compatible 64bit doubles). It is * guaranteed that the size of the resulting string will never * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating * nul character, which is always added. * * Returns: The pointer to the buffer with the converted string. */ /** * g_ascii_formatd: * @buffer: A buffer to place the resulting string in * @buf_len: The length of the buffer. * @format: The printf()-style format to use for the * code to use for converting. * @d: The #gdouble to convert * * Converts a #gdouble to a string, using the '.' as * decimal point. To format the number you pass in * a printf()-style format string. Allowed conversion * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. * * The returned buffer is guaranteed to be nul-terminated. * * If you just want to want to serialize the value into a * string, use g_ascii_dtostr(). * * Returns: The pointer to the buffer with the converted string. */ /** * g_ascii_isalnum: * @c: any character * * Determines whether a character is alphanumeric. * * Unlike the standard C library isalnum() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike * the standard library function, this takes a char, not an int, * so don't call it on %EOF, but no need to cast to #guchar before * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII alphanumeric character */ /** * g_ascii_isalpha: * @c: any character * * Determines whether a character is alphabetic (i.e. a letter). * * Unlike the standard C library isalpha() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike * the standard library function, this takes a char, not an int, * so don't call it on %EOF, but no need to cast to #guchar before * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII alphabetic character */ /** * g_ascii_iscntrl: * @c: any character * * Determines whether a character is a control character. * * Unlike the standard C library iscntrl() function, this only * recognizes standard ASCII control characters and ignores the * locale, returning %FALSE for all non-ASCII characters. Also, * unlike the standard library function, this takes a char, not * an int, so don't call it on %EOF, but no need to cast to #guchar * before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII control character. */ /** * g_ascii_isdigit: * @c: any character * * Determines whether a character is digit (0-9). * * Unlike the standard C library isdigit() function, this takes * a char, not an int, so don't call it on %EOF, but no need to * cast to #guchar before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII digit. */ /** * g_ascii_isgraph: * @c: any character * * Determines whether a character is a printing character and not a space. * * Unlike the standard C library isgraph() function, this only * recognizes standard ASCII characters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike * the standard library function, this takes a char, not an int, * so don't call it on %EOF, but no need to cast to #guchar before * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII printing character other than space. */ /** * g_ascii_islower: * @c: any character * * Determines whether a character is an ASCII lower case letter. * * Unlike the standard C library islower() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike * the standard library function, this takes a char, not an int, * so don't call it on %EOF, but no need to worry about casting * to #guchar before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII lower case letter */ /** * g_ascii_isprint: * @c: any character * * Determines whether a character is a printing character. * * Unlike the standard C library isprint() function, this only * recognizes standard ASCII characters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike * the standard library function, this takes a char, not an int, * so don't call it on %EOF, but no need to cast to #guchar before * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII printing character. */ /** * g_ascii_ispunct: * @c: any character * * Determines whether a character is a punctuation character. * * Unlike the standard C library ispunct() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike * the standard library function, this takes a char, not an int, * so don't call it on %EOF, but no need to cast to #guchar before * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII punctuation character. */ /** * g_ascii_isspace: * @c: any character * * Determines whether a character is a white-space character. * * Unlike the standard C library isspace() function, this only * recognizes standard ASCII white-space and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike * the standard library function, this takes a char, not an int, * so don't call it on %EOF, but no need to cast to #guchar before * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII white-space character */ /** * g_ascii_isupper: * @c: any character * * Determines whether a character is an ASCII upper case letter. * * Unlike the standard C library isupper() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike * the standard library function, this takes a char, not an int, * so don't call it on %EOF, but no need to worry about casting * to #guchar before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII upper case letter */ /** * g_ascii_isxdigit: * @c: any character * * Determines whether a character is a hexadecimal-digit character. * * Unlike the standard C library isxdigit() function, this takes * a char, not an int, so don't call it on %EOF, but no need to * cast to #guchar before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII hexadecimal-digit character. */ /** * g_ascii_strcasecmp: * @s1: string to compare with @s2 * @s2: string to compare with @s1 * * Compare two strings, ignoring the case of ASCII characters. * * Unlike the BSD strcasecmp() function, this only recognizes standard * ASCII letters and ignores the locale, treating all non-ASCII * bytes as if they are not letters. * * This function should be used only on strings that are known to be * in encodings where the bytes corresponding to ASCII letters always * represent themselves. This includes UTF-8 and the ISO-8859-* * charsets, but not for instance double-byte encodings like the * Windows Codepage 932, where the trailing bytes of double-byte * characters include all ASCII letters. If you compare two CP932 * strings using this function, you will get false matches. * * Both @s1 and @s2 must be non-%NULL. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, * or a positive value if @s1 > @s2. */ /** * g_ascii_strdown: * @str: a string * @len: length of @str in bytes, or -1 if @str is nul-terminated * * Converts all upper case ASCII letters to lower case ASCII letters. * * Returns: a newly-allocated string, with all the upper case * characters in @str converted to lower case, with semantics that * exactly match g_ascii_tolower(). (Note that this is unlike the * old g_strdown(), which modified the string in place.) */ /** * g_ascii_string_to_signed: * @str: a string * @base: base of a parsed number * @min: a lower bound (inclusive) * @max: an upper bound (inclusive) * @out_num: (out) (optional): a return location for a number * @error: a return location for #GError * * A convenience function for converting a string to a signed number. * * This function assumes that @str contains only a number of the given * @base that is within inclusive bounds limited by @min and @max. If * this is true, then the converted number is stored in @out_num. An * empty string is not a valid input. A string with leading or * trailing whitespace is also an invalid input. * * @base can be between 2 and 36 inclusive. Hexadecimal numbers must * not be prefixed with "0x" or "0X". Such a problem does not exist * for octal numbers, since they were usually prefixed with a zero * which does not change the value of the parsed number. * * Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR * domain. If the input is invalid, the error code will be * %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of * bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. * * See g_ascii_strtoll() if you have more complex needs such as * parsing a string which starts with a number, but then has other * characters. * * Returns: %TRUE if @str was a number, otherwise %FALSE. * Since: 2.54 */ /** * g_ascii_string_to_unsigned: * @str: a string * @base: base of a parsed number * @min: a lower bound (inclusive) * @max: an upper bound (inclusive) * @out_num: (out) (optional): a return location for a number * @error: a return location for #GError * * A convenience function for converting a string to an unsigned number. * * This function assumes that @str contains only a number of the given * @base that is within inclusive bounds limited by @min and @max. If * this is true, then the converted number is stored in @out_num. An * empty string is not a valid input. A string with leading or * trailing whitespace is also an invalid input. * * @base can be between 2 and 36 inclusive. Hexadecimal numbers must * not be prefixed with "0x" or "0X". Such a problem does not exist * for octal numbers, since they were usually prefixed with a zero * which does not change the value of the parsed number. * * Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR * domain. If the input is invalid, the error code will be * %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of * bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. * * See g_ascii_strtoull() if you have more complex needs such as * parsing a string which starts with a number, but then has other * characters. * * Returns: %TRUE if @str was a number, otherwise %FALSE. * Since: 2.54 */ /** * g_ascii_strncasecmp: * @s1: string to compare with @s2 * @s2: string to compare with @s1 * @n: number of characters to compare * * Compare @s1 and @s2, ignoring the case of ASCII characters and any * characters after the first @n in each string. * * Unlike the BSD strcasecmp() function, this only recognizes standard * ASCII letters and ignores the locale, treating all non-ASCII * characters as if they are not letters. * * The same warning as in g_ascii_strcasecmp() applies: Use this * function only on strings known to be in encodings where bytes * corresponding to ASCII letters always represent themselves. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, * or a positive value if @s1 > @s2. */ /** * g_ascii_strtod: * @nptr: the string to convert to a numeric value. * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the * character after the last character used in the conversion. * * Converts a string to a #gdouble value. * * This function behaves like the standard strtod() function * does in the C locale. It does this without actually changing * the current locale, since that would not be thread-safe. * A limitation of the implementation is that this function * will still accept localized versions of infinities and NANs. * * This function is typically used when reading configuration * files or other non-user input that should be locale independent. * To handle input from the user you should normally use the * locale-sensitive system strtod() function. * * To convert from a #gdouble to a string in a locale-insensitive * way, use g_ascii_dtostr(). * * If the correct value would cause overflow, plus or minus %HUGE_VAL * is returned (according to the sign of the value), and %ERANGE is * stored in %errno. If the correct value would cause underflow, * zero is returned and %ERANGE is stored in %errno. * * This function resets %errno before calling strtod() so that * you can reliably detect overflow and underflow. * * Returns: the #gdouble value. */ /** * g_ascii_strtoll: * @nptr: the string to convert to a numeric value. * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the * character after the last character used in the conversion. * @base: to be used for the conversion, 2..36 or 0 * * Converts a string to a #gint64 value. * This function behaves like the standard strtoll() function * does in the C locale. It does this without actually * changing the current locale, since that would not be * thread-safe. * * This function is typically used when reading configuration * files or other non-user input that should be locale independent. * To handle input from the user you should normally use the * locale-sensitive system strtoll() function. * * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64 * is returned, and `ERANGE` is stored in `errno`. * If the base is outside the valid range, zero is returned, and * `EINVAL` is stored in `errno`. If the * string conversion fails, zero is returned, and @endptr returns @nptr * (if @endptr is non-%NULL). * * Returns: the #gint64 value or zero on error. * Since: 2.12 */ /** * g_ascii_strtoull: * @nptr: the string to convert to a numeric value. * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the * character after the last character used in the conversion. * @base: to be used for the conversion, 2..36 or 0 * * Converts a string to a #guint64 value. * This function behaves like the standard strtoull() function * does in the C locale. It does this without actually * changing the current locale, since that would not be * thread-safe. * * This function is typically used when reading configuration * files or other non-user input that should be locale independent. * To handle input from the user you should normally use the * locale-sensitive system strtoull() function. * * If the correct value would cause overflow, %G_MAXUINT64 * is returned, and `ERANGE` is stored in `errno`. * If the base is outside the valid range, zero is returned, and * `EINVAL` is stored in `errno`. * If the string conversion fails, zero is returned, and @endptr returns * @nptr (if @endptr is non-%NULL). * * Returns: the #guint64 value or zero on error. * Since: 2.2 */ /** * g_ascii_strup: * @str: a string * @len: length of @str in bytes, or -1 if @str is nul-terminated * * Converts all lower case ASCII letters to upper case ASCII letters. * * Returns: a newly allocated string, with all the lower case * characters in @str converted to upper case, with semantics that * exactly match g_ascii_toupper(). (Note that this is unlike the * old g_strup(), which modified the string in place.) */ /** * g_ascii_tolower: * @c: any character * * Convert a character to ASCII lower case. * * Unlike the standard C library tolower() function, this only * recognizes standard ASCII letters and ignores the locale, returning * all non-ASCII characters unchanged, even if they are lower case * letters in a particular character set. Also unlike the standard * library function, this takes and returns a char, not an int, so * don't call it on %EOF but no need to worry about casting to #guchar * before passing a possibly non-ASCII character in. * * Returns: the result of converting @c to lower case. If @c is * not an ASCII upper case letter, @c is returned unchanged. */ /** * g_ascii_toupper: * @c: any character * * Convert a character to ASCII upper case. * * Unlike the standard C library toupper() function, this only * recognizes standard ASCII letters and ignores the locale, returning * all non-ASCII characters unchanged, even if they are upper case * letters in a particular character set. Also unlike the standard * library function, this takes and returns a char, not an int, so * don't call it on %EOF but no need to worry about casting to #guchar * before passing a possibly non-ASCII character in. * * Returns: the result of converting @c to upper case. If @c is not * an ASCII lower case letter, @c is returned unchanged. */ /** * g_ascii_xdigit_value: * @c: an ASCII character. * * Determines the numeric value of a character as a hexidecimal * digit. Differs from g_unichar_xdigit_value() because it takes * a char, so there's no worry about sign extension if characters * are signed. * * Returns: If @c is a hex digit (according to g_ascii_isxdigit()), * its numeric value. Otherwise, -1. */ /** * g_assert: * @expr: the expression to check * * Debugging macro to terminate the application if the assertion * fails. If the assertion fails (i.e. the expression is not true), * an error message is logged and the application is terminated. * * The macro can be turned off in final releases of code by defining * `G_DISABLE_ASSERT` when compiling the application, so code must * not depend on any side effects from @expr. */ /** * g_assert_cmpfloat: * @n1: an floating point number * @cmp: The comparison operator to use. * One of ==, !=, <, >, <=, >=. * @n2: another floating point number * * Debugging macro to compare two floating point numbers. * * The effect of `g_assert_cmpfloat (n1, op, n2)` is * the same as `g_assert_true (n1 op n2)`. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * * Since: 2.16 */ /** * g_assert_cmphex: * @n1: an unsigned integer * @cmp: The comparison operator to use. * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * * Debugging macro to compare to unsigned integers. * * This is a variant of g_assert_cmpuint() that displays the numbers * in hexadecimal notation in the message. * * Since: 2.16 */ /** * g_assert_cmpint: * @n1: an integer * @cmp: The comparison operator to use. * One of ==, !=, <, >, <=, >=. * @n2: another integer * * Debugging macro to compare two integers. * * The effect of `g_assert_cmpint (n1, op, n2)` is * the same as `g_assert_true (n1 op n2)`. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * * Since: 2.16 */ /** * g_assert_cmpmem: * @m1: pointer to a buffer * @l1: length of @m1 * @m2: pointer to another buffer * @l2: length of @m2 * * Debugging macro to compare memory regions. If the comparison fails, * an error message is logged and the application is either terminated * or the testcase marked as failed. * * The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is * the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`. * The advantage of this macro is that it can produce a message that * includes the actual values of @l1 and @l2. * * |[ * g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected)); * ]| * * Since: 2.46 */ /** * g_assert_cmpstr: * @s1: a string (may be %NULL) * @cmp: The comparison operator to use. * One of ==, !=, <, >, <=, >=. * @s2: another string (may be %NULL) * * Debugging macro to compare two strings. If the comparison fails, * an error message is logged and the application is either terminated * or the testcase marked as failed. * The strings are compared using g_strcmp0(). * * The effect of `g_assert_cmpstr (s1, op, s2)` is * the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`. * The advantage of this macro is that it can produce a message that * includes the actual values of @s1 and @s2. * * |[ * g_assert_cmpstr (mystring, ==, "fubar"); * ]| * * Since: 2.16 */ /** * g_assert_cmpuint: * @n1: an unsigned integer * @cmp: The comparison operator to use. * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * * Debugging macro to compare two unsigned integers. * * The effect of `g_assert_cmpuint (n1, op, n2)` is * the same as `g_assert_true (n1 op n2)`. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * * Since: 2.16 */ /** * g_assert_error: * @err: a #GError, possibly %NULL * @dom: the expected error domain (a #GQuark) * @c: the expected error code * * Debugging macro to check that a method has returned * the correct #GError. * * The effect of `g_assert_error (err, dom, c)` is * the same as `g_assert_true (err != NULL && err->domain * == dom && err->code == c)`. The advantage of this * macro is that it can produce a message that includes the incorrect * error message and code. * * This can only be used to test for a specific error. If you want to * test that @err is set, but don't care what it's set to, just use * `g_assert (err != NULL)` * * Since: 2.20 */ /** * g_assert_false: * @expr: the expression to check * * Debugging macro to check an expression is false. * * If the assertion fails (i.e. the expression is not false), * an error message is logged and the application is either * terminated or the testcase marked as failed. * * See g_test_set_nonfatal_assertions(). * * Since: 2.38 */ /** * g_assert_no_error: * @err: a #GError, possibly %NULL * * Debugging macro to check that a #GError is not set. * * The effect of `g_assert_no_error (err)` is * the same as `g_assert_true (err == NULL)`. The advantage * of this macro is that it can produce a message that includes * the error message and code. * * Since: 2.20 */ /** * g_assert_nonnull: * @expr: the expression to check * * Debugging macro to check an expression is not %NULL. * * If the assertion fails (i.e. the expression is %NULL), * an error message is logged and the application is either * terminated or the testcase marked as failed. * * See g_test_set_nonfatal_assertions(). * * Since: 2.40 */ /** * g_assert_not_reached: * * Debugging macro to terminate the application if it is ever * reached. If it is reached, an error message is logged and the * application is terminated. * * The macro can be turned off in final releases of code by defining * `G_DISABLE_ASSERT` when compiling the application. */ /** * g_assert_null: * @expr: the expression to check * * Debugging macro to check an expression is %NULL. * * If the assertion fails (i.e. the expression is not %NULL), * an error message is logged and the application is either * terminated or the testcase marked as failed. * * See g_test_set_nonfatal_assertions(). * * Since: 2.38 */ /** * g_assert_true: * @expr: the expression to check * * Debugging macro to check that an expression is true. * * If the assertion fails (i.e. the expression is not true), * an error message is logged and the application is either * terminated or the testcase marked as failed. * * See g_test_set_nonfatal_assertions(). * * Since: 2.38 */ /** * g_assertion_message_expr: (skip) * @domain: (nullable): * @file: * @line: * @func: * @expr: (nullable): */ /** * g_async_queue_length: * @queue: a #GAsyncQueue. * * Returns the length of the queue. * * Actually this function returns the number of data items in * the queue minus the number of waiting threads, so a negative * value means waiting threads, and a positive value means available * entries in the @queue. A return value of 0 could mean n entries * in the queue and n threads waiting. This can happen due to locking * of the queue or due to scheduling. * * Returns: the length of the @queue */ /** * g_async_queue_length_unlocked: * @queue: a #GAsyncQueue * * Returns the length of the queue. * * Actually this function returns the number of data items in * the queue minus the number of waiting threads, so a negative * value means waiting threads, and a positive value means available * entries in the @queue. A return value of 0 could mean n entries * in the queue and n threads waiting. This can happen due to locking * of the queue or due to scheduling. * * This function must be called while holding the @queue's lock. * * Returns: the length of the @queue. */ /** * g_async_queue_lock: * @queue: a #GAsyncQueue * * Acquires the @queue's lock. If another thread is already * holding the lock, this call will block until the lock * becomes available. * * Call g_async_queue_unlock() to drop the lock again. * * While holding the lock, you can only call the * g_async_queue_*_unlocked() functions on @queue. Otherwise, * deadlock may occur. */ /** * g_async_queue_new: * * Creates a new asynchronous queue. * * Returns: a new #GAsyncQueue. Free with g_async_queue_unref() */ /** * g_async_queue_new_full: * @item_free_func: function to free queue elements * * Creates a new asynchronous queue and sets up a destroy notify * function that is used to free any remaining queue items when * the queue is destroyed after the final unref. * * Returns: a new #GAsyncQueue. Free with g_async_queue_unref() * Since: 2.16 */ /** * g_async_queue_pop: * @queue: a #GAsyncQueue * * Pops data from the @queue. If @queue is empty, this function * blocks until data becomes available. * * Returns: data from the queue */ /** * g_async_queue_pop_unlocked: * @queue: a #GAsyncQueue * * Pops data from the @queue. If @queue is empty, this function * blocks until data becomes available. * * This function must be called while holding the @queue's lock. * * Returns: data from the queue. */ /** * g_async_queue_push: * @queue: a #GAsyncQueue * @data: @data to push into the @queue * * Pushes the @data into the @queue. @data must not be %NULL. */ /** * g_async_queue_push_front: * @queue: a #GAsyncQueue * @item: data to push into the @queue * * Pushes the @item into the @queue. @item must not be %NULL. * In contrast to g_async_queue_push(), this function * pushes the new item ahead of the items already in the queue, * so that it will be the next one to be popped off the queue. * * Since: 2.46 */ /** * g_async_queue_push_front_unlocked: * @queue: a #GAsyncQueue * @item: data to push into the @queue * * Pushes the @item into the @queue. @item must not be %NULL. * In contrast to g_async_queue_push_unlocked(), this function * pushes the new item ahead of the items already in the queue, * so that it will be the next one to be popped off the queue. * * This function must be called while holding the @queue's lock. * * Since: 2.46 */ /** * g_async_queue_push_sorted: * @queue: a #GAsyncQueue * @data: the @data to push into the @queue * @func: the #GCompareDataFunc is used to sort @queue * @user_data: user data passed to @func. * * Inserts @data into @queue using @func to determine the new * position. * * This function requires that the @queue is sorted before pushing on * new elements, see g_async_queue_sort(). * * This function will lock @queue before it sorts the queue and unlock * it when it is finished. * * For an example of @func see g_async_queue_sort(). * * Since: 2.10 */ /** * g_async_queue_push_sorted_unlocked: * @queue: a #GAsyncQueue * @data: the @data to push into the @queue * @func: the #GCompareDataFunc is used to sort @queue * @user_data: user data passed to @func. * * Inserts @data into @queue using @func to determine the new * position. * * The sort function @func is passed two elements of the @queue. * It should return 0 if they are equal, a negative value if the * first element should be higher in the @queue or a positive value * if the first element should be lower in the @queue than the second * element. * * This function requires that the @queue is sorted before pushing on * new elements, see g_async_queue_sort(). * * This function must be called while holding the @queue's lock. * * For an example of @func see g_async_queue_sort(). * * Since: 2.10 */ /** * g_async_queue_push_unlocked: * @queue: a #GAsyncQueue * @data: @data to push into the @queue * * Pushes the @data into the @queue. @data must not be %NULL. * * This function must be called while holding the @queue's lock. */ /** * g_async_queue_ref: * @queue: a #GAsyncQueue * * Increases the reference count of the asynchronous @queue by 1. * You do not need to hold the lock to call this function. * * Returns: the @queue that was passed in (since 2.6) */ /** * g_async_queue_ref_unlocked: * @queue: a #GAsyncQueue * * Increases the reference count of the asynchronous @queue by 1. * * Deprecated: 2.8: Reference counting is done atomically. * so g_async_queue_ref() can be used regardless of the @queue's * lock. */ /** * g_async_queue_remove: * @queue: a #GAsyncQueue * @item: the data to remove from the @queue * * Remove an item from the queue. * * Returns: %TRUE if the item was removed * Since: 2.46 */ /** * g_async_queue_remove_unlocked: * @queue: a #GAsyncQueue * @item: the data to remove from the @queue * * Remove an item from the queue. * * This function must be called while holding the @queue's lock. * * Returns: %TRUE if the item was removed * Since: 2.46 */ /** * g_async_queue_sort: * @queue: a #GAsyncQueue * @func: the #GCompareDataFunc is used to sort @queue * @user_data: user data passed to @func * * Sorts @queue using @func. * * The sort function @func is passed two elements of the @queue. * It should return 0 if they are equal, a negative value if the * first element should be higher in the @queue or a positive value * if the first element should be lower in the @queue than the second * element. * * This function will lock @queue before it sorts the queue and unlock * it when it is finished. * * If you were sorting a list of priority numbers to make sure the * lowest priority would be at the top of the queue, you could use: * |[ * gint32 id1; * gint32 id2; * * id1 = GPOINTER_TO_INT (element1); * id2 = GPOINTER_TO_INT (element2); * * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1); * ]| * * Since: 2.10 */ /** * g_async_queue_sort_unlocked: * @queue: a #GAsyncQueue * @func: the #GCompareDataFunc is used to sort @queue * @user_data: user data passed to @func * * Sorts @queue using @func. * * The sort function @func is passed two elements of the @queue. * It should return 0 if they are equal, a negative value if the * first element should be higher in the @queue or a positive value * if the first element should be lower in the @queue than the second * element. * * This function must be called while holding the @queue's lock. * * Since: 2.10 */ /** * g_async_queue_timed_pop: * @queue: a #GAsyncQueue * @end_time: a #GTimeVal, determining the final time * * Pops data from the @queue. If the queue is empty, blocks until * @end_time or until data becomes available. * * If no data is received before @end_time, %NULL is returned. * * To easily calculate @end_time, a combination of g_get_current_time() * and g_time_val_add() can be used. * * Returns: data from the queue or %NULL, when no data is * received before @end_time. * Deprecated: use g_async_queue_timeout_pop(). */ /** * g_async_queue_timed_pop_unlocked: * @queue: a #GAsyncQueue * @end_time: a #GTimeVal, determining the final time * * Pops data from the @queue. If the queue is empty, blocks until * @end_time or until data becomes available. * * If no data is received before @end_time, %NULL is returned. * * To easily calculate @end_time, a combination of g_get_current_time() * and g_time_val_add() can be used. * * This function must be called while holding the @queue's lock. * * Returns: data from the queue or %NULL, when no data is * received before @end_time. * Deprecated: use g_async_queue_timeout_pop_unlocked(). */ /** * g_async_queue_timeout_pop: * @queue: a #GAsyncQueue * @timeout: the number of microseconds to wait * * Pops data from the @queue. If the queue is empty, blocks for * @timeout microseconds, or until data becomes available. * * If no data is received before the timeout, %NULL is returned. * * Returns: data from the queue or %NULL, when no data is * received before the timeout. */ /** * g_async_queue_timeout_pop_unlocked: * @queue: a #GAsyncQueue * @timeout: the number of microseconds to wait * * Pops data from the @queue. If the queue is empty, blocks for * @timeout microseconds, or until data becomes available. * * If no data is received before the timeout, %NULL is returned. * * This function must be called while holding the @queue's lock. * * Returns: data from the queue or %NULL, when no data is * received before the timeout. */ /** * g_async_queue_try_pop: * @queue: a #GAsyncQueue * * Tries to pop data from the @queue. If no data is available, * %NULL is returned. * * Returns: data from the queue or %NULL, when no data is * available immediately. */ /** * g_async_queue_try_pop_unlocked: * @queue: a #GAsyncQueue * * Tries to pop data from the @queue. If no data is available, * %NULL is returned. * * This function must be called while holding the @queue's lock. * * Returns: data from the queue or %NULL, when no data is * available immediately. */ /** * g_async_queue_unlock: * @queue: a #GAsyncQueue * * Releases the queue's lock. * * Calling this function when you have not acquired * the with g_async_queue_lock() leads to undefined * behaviour. */ /** * g_async_queue_unref: * @queue: a #GAsyncQueue. * * Decreases the reference count of the asynchronous @queue by 1. * * If the reference count went to 0, the @queue will be destroyed * and the memory allocated will be freed. So you are not allowed * to use the @queue afterwards, as it might have disappeared. * You do not need to hold the lock to call this function. */ /** * g_async_queue_unref_and_unlock: * @queue: a #GAsyncQueue * * Decreases the reference count of the asynchronous @queue by 1 * and releases the lock. This function must be called while holding * the @queue's lock. If the reference count went to 0, the @queue * will be destroyed and the memory allocated will be freed. * * Deprecated: 2.8: Reference counting is done atomically. * so g_async_queue_unref() can be used regardless of the @queue's * lock. */ /** * g_atexit: * @func: (scope async): the function to call on normal program termination. * * Specifies a function to be called at normal program termination. * * Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor * macro that maps to a call to the atexit() function in the C * library. This means that in case the code that calls g_atexit(), * i.e. atexit(), is in a DLL, the function will be called when the * DLL is detached from the program. This typically makes more sense * than that the function is called when the GLib DLL is detached, * which happened earlier when g_atexit() was a function in the GLib * DLL. * * The behaviour of atexit() in the context of dynamically loaded * modules is not formally specified and varies wildly. * * On POSIX systems, calling g_atexit() (or atexit()) in a dynamically * loaded module which is unloaded before the program terminates might * well cause a crash at program exit. * * Some POSIX systems implement atexit() like Windows, and have each * dynamically loaded module maintain an own atexit chain that is * called when the module is unloaded. * * On other POSIX systems, before a dynamically loaded module is * unloaded, the registered atexit functions (if any) residing in that * module are called, regardless where the code that registered them * resided. This is presumably the most robust approach. * * As can be seen from the above, for portability it's best to avoid * calling g_atexit() (or atexit()) except in the main executable of a * program. * * Deprecated: 2.32: It is best to avoid g_atexit(). */ /** * g_atomic_int_add: * @atomic: a pointer to a #gint or #guint * @val: the value to add * * Atomically adds @val to the value of @atomic. * * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic += val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * * Before version 2.30, this function did not return a value * (but g_atomic_int_exchange_and_add() did, and had the same meaning). * * Returns: the value of @atomic before the add, signed * Since: 2.4 */ /** * g_atomic_int_and: * @atomic: a pointer to a #gint or #guint * @val: the value to 'and' * * Performs an atomic bitwise 'and' of the value of @atomic and @val, * storing the result back in @atomic. * * This call acts as a full compiler and hardware memory barrier. * * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic &= val; return tmp; }`. * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ /** * g_atomic_int_compare_and_exchange: * @atomic: a pointer to a #gint or #guint * @oldval: the value to compare with * @newval: the value to conditionally replace with * * Compares @atomic to @oldval and, if equal, sets it to @newval. * If @atomic was not equal to @oldval then no change occurs. * * This compare and exchange is done atomically. * * Think of this operation as an atomic version of * `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: %TRUE if the exchange took place * Since: 2.4 */ /** * g_atomic_int_dec_and_test: * @atomic: a pointer to a #gint or #guint * * Decrements the value of @atomic by 1. * * Think of this operation as an atomic version of * `{ *atomic -= 1; return (*atomic == 0); }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: %TRUE if the resultant value is zero * Since: 2.4 */ /** * g_atomic_int_exchange_and_add: * @atomic: a pointer to a #gint * @val: the value to add * * This function existed before g_atomic_int_add() returned the prior * value of the integer (which it now does). It is retained only for * compatibility reasons. Don't use this function in new code. * * Returns: the value of @atomic before the add, signed * Since: 2.4 * Deprecated: 2.30: Use g_atomic_int_add() instead. */ /** * g_atomic_int_get: * @atomic: a pointer to a #gint or #guint * * Gets the current value of @atomic. * * This call acts as a full compiler and hardware * memory barrier (before the get). * * Returns: the value of the integer * Since: 2.4 */ /** * g_atomic_int_inc: * @atomic: a pointer to a #gint or #guint * * Increments the value of @atomic by 1. * * Think of this operation as an atomic version of `{ *atomic += 1; }`. * * This call acts as a full compiler and hardware memory barrier. * * Since: 2.4 */ /** * g_atomic_int_or: * @atomic: a pointer to a #gint or #guint * @val: the value to 'or' * * Performs an atomic bitwise 'or' of the value of @atomic and @val, * storing the result back in @atomic. * * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic |= val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ /** * g_atomic_int_set: * @atomic: a pointer to a #gint or #guint * @newval: a new value to store * * Sets the value of @atomic to @newval. * * This call acts as a full compiler and hardware * memory barrier (after the set). * * Since: 2.4 */ /** * g_atomic_int_xor: * @atomic: a pointer to a #gint or #guint * @val: the value to 'xor' * * Performs an atomic bitwise 'xor' of the value of @atomic and @val, * storing the result back in @atomic. * * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic ^= val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ /** * g_atomic_pointer_add: * @atomic: (not nullable): a pointer to a #gpointer-sized value * @val: the value to add * * Atomically adds @val to the value of @atomic. * * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic += val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: the value of @atomic before the add, signed * Since: 2.30 */ /** * g_atomic_pointer_and: * @atomic: (not nullable): a pointer to a #gpointer-sized value * @val: the value to 'and' * * Performs an atomic bitwise 'and' of the value of @atomic and @val, * storing the result back in @atomic. * * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic &= val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ /** * g_atomic_pointer_compare_and_exchange: * @atomic: (not nullable): a pointer to a #gpointer-sized value * @oldval: the value to compare with * @newval: the value to conditionally replace with * * Compares @atomic to @oldval and, if equal, sets it to @newval. * If @atomic was not equal to @oldval then no change occurs. * * This compare and exchange is done atomically. * * Think of this operation as an atomic version of * `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: %TRUE if the exchange took place * Since: 2.4 */ /** * g_atomic_pointer_get: * @atomic: (not nullable): a pointer to a #gpointer-sized value * * Gets the current value of @atomic. * * This call acts as a full compiler and hardware * memory barrier (before the get). * * Returns: the value of the pointer * Since: 2.4 */ /** * g_atomic_pointer_or: * @atomic: (not nullable): a pointer to a #gpointer-sized value * @val: the value to 'or' * * Performs an atomic bitwise 'or' of the value of @atomic and @val, * storing the result back in @atomic. * * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic |= val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ /** * g_atomic_pointer_set: * @atomic: (not nullable): a pointer to a #gpointer-sized value * @newval: a new value to store * * Sets the value of @atomic to @newval. * * This call acts as a full compiler and hardware * memory barrier (after the set). * * Since: 2.4 */ /** * g_atomic_pointer_xor: * @atomic: (not nullable): a pointer to a #gpointer-sized value * @val: the value to 'xor' * * Performs an atomic bitwise 'xor' of the value of @atomic and @val, * storing the result back in @atomic. * * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic ^= val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ /** * g_auto: * @TypeName: a supported variable type * * Helper to declare a variable with automatic cleanup. * * The variable is cleaned up in a way appropriate to its type when the * variable goes out of scope. The type must support this. * * This feature is only supported on GCC and clang. This macro is not * defined on other compilers and should not be used in programs that * are intended to be portable to those compilers. * * This is meant to be used with stack-allocated structures and * non-pointer types. For the (more commonly used) pointer version, see * g_autoptr(). * * This macro can be used to avoid having to do explicit cleanups of * local variables when exiting functions. It often vastly simplifies * handling of error conditions, removing the need for various tricks * such as 'goto out' or repeating of cleanup code. It is also helpful * for non-error cases. * * Consider the following example: * * |[ * GVariant * * my_func(void) * { * g_auto(GQueue) queue = G_QUEUE_INIT; * g_auto(GVariantBuilder) builder; * g_auto(GStrv) strv; * * g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT); * strv = g_strsplit("a:b:c", ":", -1); * * ... * * if (error_condition) * return NULL; * * ... * * return g_variant_builder_end (&builder); * } * ]| * * You must initialize the variable in some way -- either by use of an * initialiser or by ensuring that an _init function will be called on * it unconditionally before it goes out of scope. * * Since: 2.44 */ /** * g_autofree: * * Macro to add an attribute to pointer variable to ensure automatic * cleanup using g_free(). * * This macro differs from g_autoptr() in that it is an attribute supplied * before the type name, rather than wrapping the type definition. Instead * of using a type-specific lookup, this macro always calls g_free() directly. * * This means it's useful for any type that is returned from * g_malloc(). * * Otherwise, this macro has similar constraints as g_autoptr() - only * supported on GCC and clang, the variable must be initialized, etc. * * |[ * gboolean * operate_on_malloc_buf (void) * { * g_autofree guint8* membuf = NULL; * * membuf = g_malloc (8192); * * // Some computation on membuf * * // membuf will be automatically freed here * return TRUE; * } * ]| * * Since: 2.44 */ /** * g_autolist: * @TypeName: a supported variable type * * Helper to declare a list variable with automatic deep cleanup. * * The list is deeply freed, in a way appropriate to the specified type, when the * variable goes out of scope. The type must support this. * * This feature is only supported on GCC and clang. This macro is not * defined on other compilers and should not be used in programs that * are intended to be portable to those compilers. * * This is meant to be used to declare lists of a type with a cleanup * function. The type of the variable is a GList *. You * must not add your own '*'. * * This macro can be used to avoid having to do explicit cleanups of * local variables when exiting functions. It often vastly simplifies * handling of error conditions, removing the need for various tricks * such as 'goto out' or repeating of cleanup code. It is also helpful * for non-error cases. * * See also g_autoslist(), g_autoptr() and g_steal_pointer(). * * Since: 2.56 */ /** * g_autoptr: * @TypeName: a supported variable type * * Helper to declare a pointer variable with automatic cleanup. * * The variable is cleaned up in a way appropriate to its type when the * variable goes out of scope. The type must support this. * * This feature is only supported on GCC and clang. This macro is not * defined on other compilers and should not be used in programs that * are intended to be portable to those compilers. * * This is meant to be used to declare pointers to types with cleanup * functions. The type of the variable is a pointer to @TypeName. You * must not add your own '*'. * * This macro can be used to avoid having to do explicit cleanups of * local variables when exiting functions. It often vastly simplifies * handling of error conditions, removing the need for various tricks * such as 'goto out' or repeating of cleanup code. It is also helpful * for non-error cases. * * Consider the following example: * * |[ * gboolean * check_exists(GVariant *dict) * { * g_autoptr(GVariant) dirname, basename = NULL; * g_autofree gchar *path = NULL; * * dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING); * * if (dirname == NULL) * return FALSE; * * basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING); * * if (basename == NULL) * return FALSE; * * path = g_build_filename (g_variant_get_string (dirname, NULL), * g_variant_get_string (basename, NULL), * NULL); * * return g_access (path, R_OK) == 0; * } * ]| * * You must initialise the variable in some way -- either by use of an * initialiser or by ensuring that it is assigned to unconditionally * before it goes out of scope. * * See also g_auto(), g_autofree() and g_steal_pointer(). * * Since: 2.44 */ /** * g_autoslist: * @TypeName: a supported variable type * * Helper to declare a singly linked list variable with automatic deep cleanup. * * The list is deeply freed, in a way appropriate to the specified type, when the * variable goes out of scope. The type must support this. * * This feature is only supported on GCC and clang. This macro is not * defined on other compilers and should not be used in programs that * are intended to be portable to those compilers. * * This is meant to be used to declare lists of a type with a cleanup * function. The type of the variable is a GSList *. You * must not add your own '*'. * * This macro can be used to avoid having to do explicit cleanups of * local variables when exiting functions. It often vastly simplifies * handling of error conditions, removing the need for various tricks * such as 'goto out' or repeating of cleanup code. It is also helpful * for non-error cases. * * See also g_autolist(), g_autoptr() and g_steal_pointer(). * * Since: 2.56 */ /** * g_base64_decode: * @text: zero-terminated string with base64 text to decode * @out_len: (out): The length of the decoded data is written here * * Decode a sequence of Base-64 encoded text into binary data. Note * that the returned binary data is not necessarily zero-terminated, * so it should not be used as a character string. * * Returns: (transfer full) (array length=out_len) (element-type guint8): * newly allocated buffer containing the binary data * that @text represents. The returned buffer must * be freed with g_free(). * Since: 2.12 */ /** * g_base64_decode_inplace: * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated * string with base64 text to decode * @out_len: (inout): The length of the decoded data is written here * * Decode a sequence of Base-64 encoded text into binary data * by overwriting the input data. * * Returns: (transfer none): The binary data that @text responds. This pointer * is the same as the input @text. * Since: 2.20 */ /** * g_base64_decode_step: (skip) * @in: (array length=len) (element-type guint8): binary input data * @len: max length of @in data to decode * @out: (out caller-allocates) (array) (element-type guint8): output buffer * @state: (inout): Saved state between steps, initialize to 0 * @save: (inout): Saved state between steps, initialize to 0 * * Incrementally decode a sequence of binary data from its Base-64 stringified * representation. By calling this function multiple times you can convert * data in chunks to avoid having to have the full encoded data in memory. * * The output buffer must be large enough to fit all the data that will * be written to it. Since base64 encodes 3 bytes in 4 chars you need * at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero * state). * * Returns: The number of bytes of output that was written * Since: 2.12 */ /** * g_base64_encode: * @data: (array length=len) (element-type guint8): the binary data to encode * @len: the length of @data * * Encode a sequence of binary data into its Base-64 stringified * representation. * * Returns: (transfer full): a newly allocated, zero-terminated Base-64 * encoded string representing @data. The returned string must * be freed with g_free(). * Since: 2.12 */ /** * g_base64_encode_close: * @break_lines: whether to break long lines * @out: (out) (array) (element-type guint8): pointer to destination buffer * @state: (inout): Saved state from g_base64_encode_step() * @save: (inout): Saved state from g_base64_encode_step() * * Flush the status from a sequence of calls to g_base64_encode_step(). * * The output buffer must be large enough to fit all the data that will * be written to it. It will need up to 4 bytes, or up to 5 bytes if * line-breaking is enabled. * * The @out array will not be automatically nul-terminated. * * Returns: The number of bytes of output that was written * Since: 2.12 */ /** * g_base64_encode_step: * @in: (array length=len) (element-type guint8): the binary data to encode * @len: the length of @in * @break_lines: whether to break long lines * @out: (out) (array) (element-type guint8): pointer to destination buffer * @state: (inout): Saved state between steps, initialize to 0 * @save: (inout): Saved state between steps, initialize to 0 * * Incrementally encode a sequence of binary data into its Base-64 stringified * representation. By calling this function multiple times you can convert * data in chunks to avoid having to have the full encoded data in memory. * * When all of the data has been converted you must call * g_base64_encode_close() to flush the saved state. * * The output buffer must be large enough to fit all the data that will * be written to it. Due to the way base64 encodes you will need * at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of * non-zero state). If you enable line-breaking you will need at least: * ((@len / 3 + 1) * 4 + 4) / 72 + 1 bytes of extra space. * * @break_lines is typically used when putting base64-encoded data in emails. * It breaks the lines at 72 columns instead of putting all of the text on * the same line. This avoids problems with long lines in the email system. * Note however that it breaks the lines with `LF` characters, not * `CR LF` sequences, so the result cannot be passed directly to SMTP * or certain other protocols. * * Returns: The number of bytes of output that was written * Since: 2.12 */ /** * g_basename: * @file_name: (type filename): the name of the file * * Gets the name of the file without any leading directory * components. It returns a pointer into the given file name * string. * * Returns: (type filename): the name of the file without any leading * directory components * Deprecated: 2.2: Use g_path_get_basename() instead, but notice * that g_path_get_basename() allocates new memory for the * returned string, unlike this function which returns a pointer * into the argument. */ /** * g_bit_lock: * @address: a pointer to an integer * @lock_bit: a bit value between 0 and 31 * * Sets the indicated @lock_bit in @address. If the bit is already * set, this call will block until g_bit_unlock() unsets the * corresponding bit. * * Attempting to lock on two different bits within the same integer is * not supported and will very probably cause deadlocks. * * The value of the bit that is set is (1u << @bit). If @bit is not * between 0 and 31 then the result is undefined. * * This function accesses @address atomically. All other accesses to * @address must be atomic in order for this function to work * reliably. * * Since: 2.24 */ /** * g_bit_nth_lsf: * @mask: a #gulong containing flags * @nth_bit: the index of the bit to start the search from * * Find the position of the first bit set in @mask, searching * from (but not including) @nth_bit upwards. Bits are numbered * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, * usually). To start searching from the 0th bit, set @nth_bit to -1. * * Returns: the index of the first bit set which is higher than @nth_bit, or -1 * if no higher bits are set */ /** * g_bit_nth_msf: * @mask: a #gulong containing flags * @nth_bit: the index of the bit to start the search from * * Find the position of the first bit set in @mask, searching * from (but not including) @nth_bit downwards. Bits are numbered * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, * usually). To start searching from the last bit, set @nth_bit to * -1 or GLIB_SIZEOF_LONG * 8. * * Returns: the index of the first bit set which is lower than @nth_bit, or -1 * if no lower bits are set */ /** * g_bit_storage: * @number: a #guint * * Gets the number of bits used to hold @number, * e.g. if @number is 4, 3 bits are needed. * * Returns: the number of bits used to hold @number */ /** * g_bit_trylock: * @address: a pointer to an integer * @lock_bit: a bit value between 0 and 31 * * Sets the indicated @lock_bit in @address, returning %TRUE if * successful. If the bit is already set, returns %FALSE immediately. * * Attempting to lock on two different bits within the same integer is * not supported. * * The value of the bit that is set is (1u << @bit). If @bit is not * between 0 and 31 then the result is undefined. * * This function accesses @address atomically. All other accesses to * @address must be atomic in order for this function to work * reliably. * * Returns: %TRUE if the lock was acquired * Since: 2.24 */ /** * g_bit_unlock: * @address: a pointer to an integer * @lock_bit: a bit value between 0 and 31 * * Clears the indicated @lock_bit in @address. If another thread is * currently blocked in g_bit_lock() on this same bit then it will be * woken up. * * This function accesses @address atomically. All other accesses to * @address must be atomic in order for this function to work * reliably. * * Since: 2.24 */ /** * g_bookmark_file_add_application: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @name: (nullable): the name of the application registering the bookmark * or %NULL * @exec: (nullable): command line to be used to launch the bookmark or %NULL * * Adds the application with @name and @exec to the list of * applications that have registered a bookmark for @uri into * @bookmark. * * Every bookmark inside a #GBookmarkFile must have at least an * application registered. Each application must provide a name, a * command line useful for launching the bookmark, the number of times * the bookmark has been registered by the application and the last * time the application registered this bookmark. * * If @name is %NULL, the name of the application will be the * same returned by g_get_application_name(); if @exec is %NULL, the * command line will be a composition of the program name as * returned by g_get_prgname() and the "\%u" modifier, which will be * expanded to the bookmark's URI. * * This function will automatically take care of updating the * registrations count and timestamping in case an application * with the same @name had already registered a bookmark for * @uri inside @bookmark. * * If no bookmark for @uri is found, one is created. * * Since: 2.12 */ /** * g_bookmark_file_add_group: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @group: the group name to be added * * Adds @group to the list of groups to which the bookmark for @uri * belongs to. * * If no bookmark for @uri is found then it is created. * * Since: 2.12 */ /** * g_bookmark_file_free: * @bookmark: a #GBookmarkFile * * Frees a #GBookmarkFile. * * Since: 2.12 */ /** * g_bookmark_file_get_added: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @error: return location for a #GError, or %NULL * * Gets the time the bookmark for @uri was added to @bookmark * * In the event the URI cannot be found, -1 is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: a timestamp * Since: 2.12 */ /** * g_bookmark_file_get_app_info: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @name: an application's name * @exec: (out) (optional): return location for the command line of the application, or %NULL * @count: (out) (optional): return location for the registration count, or %NULL * @stamp: (out) (optional): return location for the last registration time, or %NULL * @error: return location for a #GError, or %NULL * * Gets the registration informations of @app_name for the bookmark for * @uri. See g_bookmark_file_set_app_info() for more informations about * the returned data. * * The string returned in @app_exec must be freed. * * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the * event that no application with name @app_name has registered a bookmark * for @uri, %FALSE is returned and error is set to * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting * the command line fails, an error of the #G_SHELL_ERROR domain is * set and %FALSE is returned. * * Returns: %TRUE on success. * Since: 2.12 */ /** * g_bookmark_file_get_applications: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @length: (out) (optional): return location of the length of the returned list, or %NULL * @error: return location for a #GError, or %NULL * * Retrieves the names of the applications that have registered the * bookmark for @uri. * * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. * Use g_strfreev() to free it. * Since: 2.12 */ /** * g_bookmark_file_get_description: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @error: return location for a #GError, or %NULL * * Retrieves the description of the bookmark for @uri. * * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: a newly allocated string or %NULL if the specified * URI cannot be found. * Since: 2.12 */ /** * g_bookmark_file_get_groups: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @length: (out) (optional): return location for the length of the returned string, or %NULL * @error: return location for a #GError, or %NULL * * Retrieves the list of group names of the bookmark for @uri. * * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * The returned array is %NULL terminated, so @length may optionally * be %NULL. * * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names. * Use g_strfreev() to free it. * Since: 2.12 */ /** * g_bookmark_file_get_icon: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @href: (out) (optional): return location for the icon's location or %NULL * @mime_type: (out) (optional): return location for the icon's MIME type or %NULL * @error: return location for a #GError or %NULL * * Gets the icon of the bookmark for @uri. * * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: %TRUE if the icon for the bookmark for the URI was found. * You should free the returned strings. * Since: 2.12 */ /** * g_bookmark_file_get_is_private: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @error: return location for a #GError, or %NULL * * Gets whether the private flag of the bookmark for @uri is set. * * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the * event that the private flag cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. * * Returns: %TRUE if the private flag is set, %FALSE otherwise. * Since: 2.12 */ /** * g_bookmark_file_get_mime_type: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @error: return location for a #GError, or %NULL * * Retrieves the MIME type of the resource pointed by @uri. * * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the * event that the MIME type cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. * * Returns: a newly allocated string or %NULL if the specified * URI cannot be found. * Since: 2.12 */ /** * g_bookmark_file_get_modified: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @error: return location for a #GError, or %NULL * * Gets the time when the bookmark for @uri was last modified. * * In the event the URI cannot be found, -1 is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: a timestamp * Since: 2.12 */ /** * g_bookmark_file_get_size: * @bookmark: a #GBookmarkFile * * Gets the number of bookmarks inside @bookmark. * * Returns: the number of bookmarks * Since: 2.12 */ /** * g_bookmark_file_get_title: * @bookmark: a #GBookmarkFile * @uri: (nullable): a valid URI or %NULL * @error: return location for a #GError, or %NULL * * Returns the title of the bookmark for @uri. * * If @uri is %NULL, the title of @bookmark is returned. * * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: a newly allocated string or %NULL if the specified * URI cannot be found. * Since: 2.12 */ /** * g_bookmark_file_get_uris: * @bookmark: a #GBookmarkFile * @length: (out) (optional): return location for the number of returned URIs, or %NULL * * Returns all URIs of the bookmarks in the bookmark file @bookmark. * The array of returned URIs will be %NULL-terminated, so @length may * optionally be %NULL. * * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. * Use g_strfreev() to free it. * Since: 2.12 */ /** * g_bookmark_file_get_visited: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @error: return location for a #GError, or %NULL * * Gets the time the bookmark for @uri was last visited. * * In the event the URI cannot be found, -1 is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: a timestamp. * Since: 2.12 */ /** * g_bookmark_file_has_application: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @name: the name of the application * @error: return location for a #GError or %NULL * * Checks whether the bookmark for @uri inside @bookmark has been * registered by application @name. * * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: %TRUE if the application @name was found * Since: 2.12 */ /** * g_bookmark_file_has_group: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @group: the group name to be searched * @error: return location for a #GError, or %NULL * * Checks whether @group appears in the list of groups to which * the bookmark for @uri belongs to. * * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: %TRUE if @group was found. * Since: 2.12 */ /** * g_bookmark_file_has_item: * @bookmark: a #GBookmarkFile * @uri: a valid URI * * Looks whether the desktop bookmark has an item with its URI set to @uri. * * Returns: %TRUE if @uri is inside @bookmark, %FALSE otherwise * Since: 2.12 */ /** * g_bookmark_file_load_from_data: * @bookmark: an empty #GBookmarkFile struct * @data: (array length=length) (element-type guint8): desktop bookmarks * loaded in memory * @length: the length of @data in bytes * @error: return location for a #GError, or %NULL * * Loads a bookmark file from memory into an empty #GBookmarkFile * structure. If the object cannot be created then @error is set to a * #GBookmarkFileError. * * Returns: %TRUE if a desktop bookmark could be loaded. * Since: 2.12 */ /** * g_bookmark_file_load_from_data_dirs: * @bookmark: a #GBookmarkFile * @file: (type filename): a relative path to a filename to open and parse * @full_path: (out) (optional) (type filename): return location for a string * containing the full path of the file, or %NULL * @error: return location for a #GError, or %NULL * * This function looks for a desktop bookmark file named @file in the * paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), * loads the file into @bookmark and returns the file's full path in * @full_path. If the file could not be loaded then an %error is * set to either a #GFileError or #GBookmarkFileError. * * Returns: %TRUE if a key file could be loaded, %FALSE otherwise * Since: 2.12 */ /** * g_bookmark_file_load_from_file: * @bookmark: an empty #GBookmarkFile struct * @filename: (type filename): the path of a filename to load, in the * GLib file name encoding * @error: return location for a #GError, or %NULL * * Loads a desktop bookmark file into an empty #GBookmarkFile structure. * If the file could not be loaded then @error is set to either a #GFileError * or #GBookmarkFileError. * * Returns: %TRUE if a desktop bookmark file could be loaded * Since: 2.12 */ /** * g_bookmark_file_move_item: * @bookmark: a #GBookmarkFile * @old_uri: a valid URI * @new_uri: (nullable): a valid URI, or %NULL * @error: return location for a #GError or %NULL * * Changes the URI of a bookmark item from @old_uri to @new_uri. Any * existing bookmark for @new_uri will be overwritten. If @new_uri is * %NULL, then the bookmark is removed. * * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * * Returns: %TRUE if the URI was successfully changed * Since: 2.12 */ /** * g_bookmark_file_new: (constructor) * * Creates a new empty #GBookmarkFile object. * * Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data() * or g_bookmark_file_load_from_data_dirs() to read an existing bookmark * file. * * Returns: an empty #GBookmarkFile * Since: 2.12 */ /** * g_bookmark_file_remove_application: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @name: the name of the application * @error: return location for a #GError or %NULL * * Removes application registered with @name from the list of applications * that have registered a bookmark for @uri inside @bookmark. * * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * In the event that no application with name @app_name has registered * a bookmark for @uri, %FALSE is returned and error is set to * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. * * Returns: %TRUE if the application was successfully removed. * Since: 2.12 */ /** * g_bookmark_file_remove_group: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @group: the group name to be removed * @error: return location for a #GError, or %NULL * * Removes @group from the list of groups to which the bookmark * for @uri belongs to. * * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * In the event no group was defined, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. * * Returns: %TRUE if @group was successfully removed. * Since: 2.12 */ /** * g_bookmark_file_remove_item: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @error: return location for a #GError, or %NULL * * Removes the bookmark for @uri from the bookmark file @bookmark. * * Returns: %TRUE if the bookmark was removed successfully. * Since: 2.12 */ /** * g_bookmark_file_set_added: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @added: a timestamp or -1 to use the current time * * Sets the time the bookmark for @uri was added into @bookmark. * * If no bookmark for @uri is found then it is created. * * Since: 2.12 */ /** * g_bookmark_file_set_app_info: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @name: an application's name * @exec: an application's command line * @count: the number of registrations done for this application * @stamp: the time of the last registration for this application * @error: return location for a #GError or %NULL * * Sets the meta-data of application @name inside the list of * applications that have registered a bookmark for @uri inside * @bookmark. * * You should rarely use this function; use g_bookmark_file_add_application() * and g_bookmark_file_remove_application() instead. * * @name can be any UTF-8 encoded string used to identify an * application. * @exec can have one of these two modifiers: "\%f", which will * be expanded as the local file name retrieved from the bookmark's * URI; "\%u", which will be expanded as the bookmark's URI. * The expansion is done automatically when retrieving the stored * command line using the g_bookmark_file_get_app_info() function. * @count is the number of times the application has registered the * bookmark; if is < 0, the current registration count will be increased * by one, if is 0, the application with @name will be removed from * the list of registered applications. * @stamp is the Unix time of the last registration; if it is -1, the * current time will be used. * * If you try to remove an application by setting its registration count to * zero, and no bookmark for @uri is found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly, * in the event that no application @name has registered a bookmark * for @uri, %FALSE is returned and error is set to * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark * for @uri is found, one is created. * * Returns: %TRUE if the application's meta-data was successfully * changed. * Since: 2.12 */ /** * g_bookmark_file_set_description: * @bookmark: a #GBookmarkFile * @uri: (nullable): a valid URI or %NULL * @description: a string * * Sets @description as the description of the bookmark for @uri. * * If @uri is %NULL, the description of @bookmark is set. * * If a bookmark for @uri cannot be found then it is created. * * Since: 2.12 */ /** * g_bookmark_file_set_groups: * @bookmark: a #GBookmarkFile * @uri: an item's URI * @groups: (nullable) (array length=length) (element-type utf8): an array of * group names, or %NULL to remove all groups * @length: number of group name values in @groups * * Sets a list of group names for the item with URI @uri. Each previously * set group name list is removed. * * If @uri cannot be found then an item for it is created. * * Since: 2.12 */ /** * g_bookmark_file_set_icon: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @href: (nullable): the URI of the icon for the bookmark, or %NULL * @mime_type: the MIME type of the icon for the bookmark * * Sets the icon for the bookmark for @uri. If @href is %NULL, unsets * the currently set icon. @href can either be a full URL for the icon * file or the icon name following the Icon Naming specification. * * If no bookmark for @uri is found one is created. * * Since: 2.12 */ /** * g_bookmark_file_set_is_private: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @is_private: %TRUE if the bookmark should be marked as private * * Sets the private flag of the bookmark for @uri. * * If a bookmark for @uri cannot be found then it is created. * * Since: 2.12 */ /** * g_bookmark_file_set_mime_type: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @mime_type: a MIME type * * Sets @mime_type as the MIME type of the bookmark for @uri. * * If a bookmark for @uri cannot be found then it is created. * * Since: 2.12 */ /** * g_bookmark_file_set_modified: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @modified: a timestamp or -1 to use the current time * * Sets the last time the bookmark for @uri was last modified. * * If no bookmark for @uri is found then it is created. * * The "modified" time should only be set when the bookmark's meta-data * was actually changed. Every function of #GBookmarkFile that * modifies a bookmark also changes the modification time, except for * g_bookmark_file_set_visited(). * * Since: 2.12 */ /** * g_bookmark_file_set_title: * @bookmark: a #GBookmarkFile * @uri: (nullable): a valid URI or %NULL * @title: a UTF-8 encoded string * * Sets @title as the title of the bookmark for @uri inside the * bookmark file @bookmark. * * If @uri is %NULL, the title of @bookmark is set. * * If a bookmark for @uri cannot be found then it is created. * * Since: 2.12 */ /** * g_bookmark_file_set_visited: * @bookmark: a #GBookmarkFile * @uri: a valid URI * @visited: a timestamp or -1 to use the current time * * Sets the time the bookmark for @uri was last visited. * * If no bookmark for @uri is found then it is created. * * The "visited" time should only be set if the bookmark was launched, * either using the command line retrieved by g_bookmark_file_get_app_info() * or by the default application for the bookmark's MIME type, retrieved * using g_bookmark_file_get_mime_type(). Changing the "visited" time * does not affect the "modified" time. * * Since: 2.12 */ /** * g_bookmark_file_to_data: * @bookmark: a #GBookmarkFile * @length: (out) (optional): return location for the length of the returned string, or %NULL * @error: return location for a #GError, or %NULL * * This function outputs @bookmark as a string. * * Returns: (array length=length) (element-type guint8): * a newly allocated string holding the contents of the #GBookmarkFile * Since: 2.12 */ /** * g_bookmark_file_to_file: * @bookmark: a #GBookmarkFile * @filename: (type filename): path of the output file * @error: return location for a #GError, or %NULL * * This function outputs @bookmark into a file. The write process is * guaranteed to be atomic by using g_file_set_contents() internally. * * Returns: %TRUE if the file was successfully written. * Since: 2.12 */ /** * g_build_filename: * @first_element: (type filename): the first element in the path * @...: remaining elements in path, terminated by %NULL * * Creates a filename from a series of elements using the correct * separator for filenames. * * On Unix, this function behaves identically to `g_build_path * (G_DIR_SEPARATOR_S, first_element, ....)`. * * On Windows, it takes into account that either the backslash * (`\` or slash (`/`) can be used as separator in filenames, but * otherwise behaves as on UNIX. When file pathname separators need * to be inserted, the one that last previously occurred in the * parameters (reading from left to right) is used. * * No attempt is made to force the resulting filename to be an absolute * path. If the first element is a relative path, the result will * be a relative path. * * Returns: (type filename): a newly-allocated string that must be freed with * g_free(). */ /** * g_build_filename_valist: * @first_element: (type filename): the first element in the path * @args: va_list of remaining elements in path * * Behaves exactly like g_build_filename(), but takes the path elements * as a va_list. This function is mainly meant for language bindings. * * Returns: (type filename): a newly-allocated string that must be freed * with g_free(). * Since: 2.56 */ /** * g_build_filenamev: * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated * array of strings containing the path elements. * * Behaves exactly like g_build_filename(), but takes the path elements * as a string array, instead of varargs. This function is mainly * meant for language bindings. * * Returns: (type filename): a newly-allocated string that must be freed * with g_free(). * Since: 2.8 */ /** * g_build_path: * @separator: (type filename): a string used to separator the elements of the path. * @first_element: (type filename): the first element in the path * @...: remaining elements in path, terminated by %NULL * * Creates a path from a series of elements using @separator as the * separator between elements. At the boundary between two elements, * any trailing occurrences of separator in the first element, or * leading occurrences of separator in the second element are removed * and exactly one copy of the separator is inserted. * * Empty elements are ignored. * * The number of leading copies of the separator on the result is * the same as the number of leading copies of the separator on * the first non-empty element. * * The number of trailing copies of the separator on the result is * the same as the number of trailing copies of the separator on * the last non-empty element. (Determination of the number of * trailing copies is done without stripping leading copies, so * if the separator is `ABA`, then `ABABA` has 1 trailing copy.) * * However, if there is only a single non-empty element, and there * are no characters in that element not part of the leading or * trailing separators, then the result is exactly the original value * of that element. * * Other than for determination of the number of leading and trailing * copies of the separator, elements consisting only of copies * of the separator are ignored. * * Returns: (type filename): a newly-allocated string that must be freed with * g_free(). */ /** * g_build_pathv: * @separator: a string used to separator the elements of the path. * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated * array of strings containing the path elements. * * Behaves exactly like g_build_path(), but takes the path elements * as a string array, instead of varargs. This function is mainly * meant for language bindings. * * Returns: (type filename): a newly-allocated string that must be freed * with g_free(). * Since: 2.8 */ /** * g_byte_array_append: * @array: a #GByteArray * @data: the byte data to be added * @len: the number of bytes to add * * Adds the given bytes to the end of the #GByteArray. * The array will grow in size automatically if necessary. * * Returns: the #GByteArray */ /** * g_byte_array_free: * @array: a #GByteArray * @free_segment: if %TRUE the actual byte data is freed as well * * Frees the memory allocated by the #GByteArray. If @free_segment is * %TRUE it frees the actual byte data. If the reference count of * @array is greater than one, the #GByteArray wrapper is preserved but * the size of @array will be set to zero. * * Returns: the element data if @free_segment is %FALSE, otherwise * %NULL. The element data should be freed using g_free(). */ /** * g_byte_array_free_to_bytes: * @array: (transfer full): a #GByteArray * * Transfers the data from the #GByteArray into a new immutable #GBytes. * * The #GByteArray is freed unless the reference count of @array is greater * than one, the #GByteArray wrapper is preserved but the size of @array * will be set to zero. * * This is identical to using g_bytes_new_take() and g_byte_array_free() * together. * * Since: 2.32 * Returns: (transfer full): a new immutable #GBytes representing same * byte data that was in the array */ /** * g_byte_array_new: * * Creates a new #GByteArray with a reference count of 1. * * Returns: (transfer full): the new #GByteArray */ /** * g_byte_array_new_take: * @data: (transfer full) (array length=len): byte data for the array * @len: length of @data * * Create byte array containing the data. The data will be owned by the array * and will be freed with g_free(), i.e. it could be allocated using g_strdup(). * * Since: 2.32 * Returns: (transfer full): a new #GByteArray */ /** * g_byte_array_prepend: * @array: a #GByteArray * @data: the byte data to be added * @len: the number of bytes to add * * Adds the given data to the start of the #GByteArray. * The array will grow in size automatically if necessary. * * Returns: the #GByteArray */ /** * g_byte_array_ref: * @array: A #GByteArray * * Atomically increments the reference count of @array by one. * This function is thread-safe and may be called from any thread. * * Returns: The passed in #GByteArray * Since: 2.22 */ /** * g_byte_array_remove_index: * @array: a #GByteArray * @index_: the index of the byte to remove * * Removes the byte at the given index from a #GByteArray. * The following bytes are moved down one place. * * Returns: the #GByteArray */ /** * g_byte_array_remove_index_fast: * @array: a #GByteArray * @index_: the index of the byte to remove * * Removes the byte at the given index from a #GByteArray. The last * element in the array is used to fill in the space, so this function * does not preserve the order of the #GByteArray. But it is faster * than g_byte_array_remove_index(). * * Returns: the #GByteArray */ /** * g_byte_array_remove_range: * @array: a @GByteArray * @index_: the index of the first byte to remove * @length: the number of bytes to remove * * Removes the given number of bytes starting at the given index from a * #GByteArray. The following elements are moved to close the gap. * * Returns: the #GByteArray * Since: 2.4 */ /** * g_byte_array_set_size: * @array: a #GByteArray * @length: the new size of the #GByteArray * * Sets the size of the #GByteArray, expanding it if necessary. * * Returns: the #GByteArray */ /** * g_byte_array_sized_new: * @reserved_size: number of bytes preallocated * * Creates a new #GByteArray with @reserved_size bytes preallocated. * This avoids frequent reallocation, if you are going to add many * bytes to the array. Note however that the size of the array is still * 0. * * Returns: the new #GByteArray */ /** * g_byte_array_sort: * @array: a #GByteArray * @compare_func: comparison function * * Sorts a byte array, using @compare_func which should be a * qsort()-style comparison function (returns less than zero for first * arg is less than second arg, zero for equal, greater than zero if * first arg is greater than second arg). * * If two array elements compare equal, their order in the sorted array * is undefined. If you want equal elements to keep their order (i.e. * you want a stable sort) you can write a comparison function that, * if two elements would otherwise compare equal, compares them by * their addresses. */ /** * g_byte_array_sort_with_data: * @array: a #GByteArray * @compare_func: comparison function * @user_data: data to pass to @compare_func * * Like g_byte_array_sort(), but the comparison function takes an extra * user data argument. */ /** * g_byte_array_unref: * @array: A #GByteArray * * Atomically decrements the reference count of @array by one. If the * reference count drops to 0, all memory allocated by the array is * released. This function is thread-safe and may be called from any * thread. * * Since: 2.22 */ /** * g_bytes_compare: * @bytes1: (type GLib.Bytes): a pointer to a #GBytes * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1 * * Compares the two #GBytes values. * * This function can be used to sort GBytes instances in lexographical order. * * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is * greater, and zero if bytes2 is equal to bytes1 * Since: 2.32 */ /** * g_bytes_equal: * @bytes1: (type GLib.Bytes): a pointer to a #GBytes * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1 * * Compares the two #GBytes values being pointed to and returns * %TRUE if they are equal. * * This function can be passed to g_hash_table_new() as the @key_equal_func * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. * * Returns: %TRUE if the two keys match. * Since: 2.32 */ /** * g_bytes_get_data: * @bytes: a #GBytes * @size: (out) (optional): location to return size of byte data * * Get the byte data in the #GBytes. This data should not be modified. * * This function will always return the same pointer for a given #GBytes. * * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes * may represent an empty string with @data non-%NULL and @size as 0. %NULL will * not be returned if @size is non-zero. * * Returns: (transfer none) (array length=size) (element-type guint8) (nullable): * a pointer to the byte data, or %NULL * Since: 2.32 */ /** * g_bytes_get_size: * @bytes: a #GBytes * * Get the size of the byte data in the #GBytes. * * This function will always return the same value for a given #GBytes. * * Returns: the size * Since: 2.32 */ /** * g_bytes_hash: * @bytes: (type GLib.Bytes): a pointer to a #GBytes key * * Creates an integer hash code for the byte data in the #GBytes. * * This function can be passed to g_hash_table_new() as the @key_hash_func * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. * * Returns: a hash value corresponding to the key. * Since: 2.32 */ /** * g_bytes_new: * @data: (transfer none) (array length=size) (element-type guint8) (nullable): * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from @data. * * @data is copied. If @size is 0, @data may be %NULL. * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ /** * g_bytes_new_from_bytes: * @bytes: a #GBytes * @offset: offset which subsection starts at * @length: length of subsection * * Creates a #GBytes which is a subsection of another #GBytes. The @offset + * @length may not be longer than the size of @bytes. * * A reference to @bytes will be held by the newly created #GBytes until * the byte data is no longer needed. * * Since 2.56, if @offset is 0 and @length matches the size of @bytes, then * @bytes will be returned with the reference count incremented by 1. If @bytes * is a slice of another #GBytes, then the resulting #GBytes will reference * the same #GBytes instead of @bytes. This allows consumers to simplify the * usage of #GBytes when asynchronously writing to streams. * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ /** * g_bytes_new_static: (skip) * @data: (transfer full) (array length=size) (element-type guint8) (nullable): * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from static data. * * @data must be static (ie: never modified or freed). It may be %NULL if @size * is 0. * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ /** * g_bytes_new_take: * @data: (transfer full) (array length=size) (element-type guint8) (nullable): * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from @data. * * After this call, @data belongs to the bytes and may no longer be * modified by the caller. g_free() will be called on @data when the * bytes is no longer in use. Because of this @data must have been created by * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many * functions that wrap these calls (such as g_new(), g_strdup(), etc). * * For creating #GBytes with memory from other allocators, see * g_bytes_new_with_free_func(). * * @data may be %NULL if @size is 0. * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ /** * g_bytes_new_with_free_func: (skip) * @data: (array length=size) (element-type guint8) (nullable): * the data to be used for the bytes * @size: the size of @data * @free_func: the function to call to release the data * @user_data: data to pass to @free_func * * Creates a #GBytes from @data. * * When the last reference is dropped, @free_func will be called with the * @user_data argument. * * @data must not be modified after this call is made until @free_func has * been called to indicate that the bytes is no longer in use. * * @data may be %NULL if @size is 0. * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ /** * g_bytes_ref: * @bytes: a #GBytes * * Increase the reference count on @bytes. * * Returns: the #GBytes * Since: 2.32 */ /** * g_bytes_unref: * @bytes: (nullable): a #GBytes * * Releases a reference on @bytes. This may result in the bytes being * freed. If @bytes is %NULL, it will return immediately. * * Since: 2.32 */ /** * g_bytes_unref_to_array: * @bytes: (transfer full): a #GBytes * * Unreferences the bytes, and returns a new mutable #GByteArray containing * the same byte data. * * As an optimization, the byte data is transferred to the array without copying * if this was the last reference to bytes and bytes was created with * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all * other cases the data is copied. * * Returns: (transfer full): a new mutable #GByteArray containing the same byte data * Since: 2.32 */ /** * g_bytes_unref_to_data: * @bytes: (transfer full): a #GBytes * @size: (out): location to place the length of the returned data * * Unreferences the bytes, and returns a pointer the same byte data * contents. * * As an optimization, the byte data is returned without copying if this was * the last reference to bytes and bytes was created with g_bytes_new(), * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the * data is copied. * * Returns: (transfer full) (array length=size) (element-type guint8) (not nullable): a pointer to the same byte data, which should be * freed with g_free() * Since: 2.32 */ /** * g_chdir: * @path: (type filename): a pathname in the GLib file name encoding * (UTF-8 on Windows) * * A wrapper for the POSIX chdir() function. The function changes the * current directory of the process to @path. * * See your C library manual for more details about chdir(). * * Returns: 0 on success, -1 if an error occurred. * Since: 2.8 */ /** * g_checksum_copy: * @checksum: the #GChecksum to copy * * Copies a #GChecksum. If @checksum has been closed, by calling * g_checksum_get_string() or g_checksum_get_digest(), the copied * checksum will be closed as well. * * Returns: the copy of the passed #GChecksum. Use g_checksum_free() * when finished using it. * Since: 2.16 */ /** * g_checksum_free: * @checksum: a #GChecksum * * Frees the memory allocated for @checksum. * * Since: 2.16 */ /** * g_checksum_get_digest: (skip) * @checksum: a #GChecksum * @buffer: output buffer * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. * After the call it contains the length of the digest. * * Gets the digest from @checksum as a raw binary vector and places it * into @buffer. The size of the digest depends on the type of checksum. * * Once this function has been called, the #GChecksum is closed and can * no longer be updated with g_checksum_update(). * * Since: 2.16 */ /** * g_checksum_get_string: * @checksum: a #GChecksum * * Gets the digest as an hexadecimal string. * * Once this function has been called the #GChecksum can no longer be * updated with g_checksum_update(). * * The hexadecimal characters will be lower case. * * Returns: the hexadecimal representation of the checksum. The * returned string is owned by the checksum and should not be modified * or freed. * Since: 2.16 */ /** * g_checksum_new: * @checksum_type: the desired type of checksum * * Creates a new #GChecksum, using the checksum algorithm @checksum_type. * If the @checksum_type is not known, %NULL is returned. * A #GChecksum can be used to compute the checksum, or digest, of an * arbitrary binary blob, using different hashing algorithms. * * A #GChecksum works by feeding a binary blob through g_checksum_update() * until there is data to be checked; the digest can then be extracted * using g_checksum_get_string(), which will return the checksum as a * hexadecimal string; or g_checksum_get_digest(), which will return a * vector of raw bytes. Once either g_checksum_get_string() or * g_checksum_get_digest() have been called on a #GChecksum, the checksum * will be closed and it won't be possible to call g_checksum_update() * on it anymore. * * Returns: (transfer full): the newly created #GChecksum, or %NULL. * Use g_checksum_free() to free the memory allocated by it. * Since: 2.16 */ /** * g_checksum_reset: * @checksum: the #GChecksum to reset * * Resets the state of the @checksum back to its initial state. * * Since: 2.18 */ /** * g_checksum_type_get_length: * @checksum_type: a #GChecksumType * * Gets the length in bytes of digests of type @checksum_type * * Returns: the checksum length, or -1 if @checksum_type is * not supported. * Since: 2.16 */ /** * g_checksum_update: * @checksum: a #GChecksum * @data: (array length=length) (element-type guint8): buffer used to compute the checksum * @length: size of the buffer, or -1 if it is a null-terminated string. * * Feeds @data into an existing #GChecksum. The checksum must still be * open, that is g_checksum_get_string() or g_checksum_get_digest() must * not have been called on @checksum. * * Since: 2.16 */ /** * g_child_watch_add: * @pid: process id to watch. On POSIX the positive pid of a child * process. On Windows a handle for a process (which doesn't have to be * a child). * @function: function to call * @data: data to pass to @function * * Sets a function to be called when the child indicated by @pid * exits, at a default priority, #G_PRIORITY_DEFAULT. * * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to * the spawn function for the child watching to work. * * Note that on platforms where #GPid must be explicitly closed * (see g_spawn_close_pid()) @pid must not be closed while the * source is still active. Typically, you will want to call * g_spawn_close_pid() in the callback function for the source. * * GLib supports only a single callback per process id. * On POSIX platforms, the same restrictions mentioned for * g_child_watch_source_new() apply to this function. * * This internally creates a main loop source using * g_child_watch_source_new() and attaches it to the main loop context * using g_source_attach(). You can do these steps manually if you * need greater control. * * Returns: the ID (greater than 0) of the event source. * Since: 2.4 */ /** * g_child_watch_add_full: (rename-to g_child_watch_add) * @priority: the priority of the idle source. Typically this will be in the * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. * @pid: process to watch. On POSIX the positive pid of a child process. On * Windows a handle for a process (which doesn't have to be a child). * @function: function to call * @data: data to pass to @function * @notify: (nullable): function to call when the idle is removed, or %NULL * * Sets a function to be called when the child indicated by @pid * exits, at the priority @priority. * * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to * the spawn function for the child watching to work. * * In many programs, you will want to call g_spawn_check_exit_status() * in the callback to determine whether or not the child exited * successfully. * * Also, note that on platforms where #GPid must be explicitly closed * (see g_spawn_close_pid()) @pid must not be closed while the source * is still active. Typically, you should invoke g_spawn_close_pid() * in the callback function for the source. * * GLib supports only a single callback per process id. * On POSIX platforms, the same restrictions mentioned for * g_child_watch_source_new() apply to this function. * * This internally creates a main loop source using * g_child_watch_source_new() and attaches it to the main loop context * using g_source_attach(). You can do these steps manually if you * need greater control. * * Returns: the ID (greater than 0) of the event source. * Since: 2.4 */ /** * g_child_watch_source_new: * @pid: process to watch. On POSIX the positive pid of a child process. On * Windows a handle for a process (which doesn't have to be a child). * * Creates a new child_watch source. * * The source will not initially be associated with any #GMainContext * and must be added to one with g_source_attach() before it will be * executed. * * Note that child watch sources can only be used in conjunction with * `g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used. * * Note that on platforms where #GPid must be explicitly closed * (see g_spawn_close_pid()) @pid must not be closed while the * source is still active. Typically, you will want to call * g_spawn_close_pid() in the callback function for the source. * * On POSIX platforms, the following restrictions apply to this API * due to limitations in POSIX process interfaces: * * * @pid must be a child of this process * * @pid must be positive * * the application must not call `waitpid` with a non-positive * first argument, for instance in another thread * * the application must not wait for @pid to exit by any other * mechanism, including `waitpid(pid, ...)` or a second child-watch * source for the same @pid * * the application must not ignore SIGCHILD * * If any of those conditions are not met, this and related APIs will * not work correctly. This can often be diagnosed via a GLib warning * stating that `ECHILD` was received by `waitpid`. * * Calling `waitpid` for specific processes other than @pid remains a * valid thing to do. * * Returns: the newly-created child watch source * Since: 2.4 */ /** * g_chmod: * @filename: (type filename): a pathname in the GLib file name encoding * (UTF-8 on Windows) * @mode: as in chmod() * * A wrapper for the POSIX chmod() function. The chmod() function is * used to set the permissions of a file system object. * * On Windows the file protection mechanism is not at all POSIX-like, * and the underlying chmod() function in the C library just sets or * clears the FAT-style READONLY attribute. It does not touch any * ACL. Software that needs to manage file permissions on Windows * exactly should use the Win32 API. * * See your C library manual for more details about chmod(). * * Returns: 0 if the operation succeeded, -1 on error * Since: 2.8 */ /** * g_clear_error: * @err: a #GError return location * * If @err or *@err is %NULL, does nothing. Otherwise, * calls g_error_free() on *@err and sets *@err to %NULL. */ /** * g_clear_handle_id: (skip) * @tag_ptr: (not nullable): a pointer to the handler ID * @clear_func: (not nullable): the function to call to clear the handler * * Clears a numeric handler, such as a #GSource ID. * * @tag_ptr must be a valid pointer to the variable holding the handler. * * If the ID is zero then this function does nothing. * Otherwise, clear_func() is called with the ID as a parameter, and the tag is * set to zero. * * A macro is also included that allows this function to be used without * pointer casts. * * Since: 2.56 */ /** * g_clear_pointer: (skip) * @pp: (not nullable): a pointer to a variable, struct member etc. holding a * pointer * @destroy: a function to which a gpointer can be passed, to destroy *@pp * * Clears a reference to a variable. * * @pp must not be %NULL. * * If the reference is %NULL then this function does nothing. * Otherwise, the variable is destroyed using @destroy and the * pointer is set to %NULL. * * A macro is also included that allows this function to be used without * pointer casts. * * Since: 2.34 */ /** * g_close: * @fd: A file descriptor * @error: a #GError * * This wraps the close() call; in case of error, %errno will be * preserved, but the error will also be stored as a #GError in @error. * * Besides using #GError, there is another major reason to prefer this * function over the call provided by the system; on Unix, it will * attempt to correctly handle %EINTR, which has platform-specific * semantics. * * Returns: %TRUE on success, %FALSE if there was an error. * Since: 2.36 */ /** * g_compute_checksum_for_bytes: * @checksum_type: a #GChecksumType * @data: binary blob to compute the digest of * * Computes the checksum for a binary @data. This is a * convenience wrapper for g_checksum_new(), g_checksum_get_string() * and g_checksum_free(). * * The hexadecimal string returned will be in lower case. * * Returns: the digest of the binary data as a string in hexadecimal. * The returned string should be freed with g_free() when done using it. * Since: 2.34 */ /** * g_compute_checksum_for_data: * @checksum_type: a #GChecksumType * @data: (array length=length) (element-type guint8): binary blob to compute the digest of * @length: length of @data * * Computes the checksum for a binary @data of @length. This is a * convenience wrapper for g_checksum_new(), g_checksum_get_string() * and g_checksum_free(). * * The hexadecimal string returned will be in lower case. * * Returns: the digest of the binary data as a string in hexadecimal. * The returned string should be freed with g_free() when done using it. * Since: 2.16 */ /** * g_compute_checksum_for_string: * @checksum_type: a #GChecksumType * @str: the string to compute the checksum of * @length: the length of the string, or -1 if the string is null-terminated. * * Computes the checksum of a string. * * The hexadecimal string returned will be in lower case. * * Returns: the checksum as a hexadecimal string. The returned string * should be freed with g_free() when done using it. * Since: 2.16 */ /** * g_compute_hmac_for_bytes: * @digest_type: a #GChecksumType to use for the HMAC * @key: the key to use in the HMAC * @data: binary blob to compute the HMAC of * * Computes the HMAC for a binary @data. This is a * convenience wrapper for g_hmac_new(), g_hmac_get_string() * and g_hmac_unref(). * * The hexadecimal string returned will be in lower case. * * Returns: the HMAC of the binary data as a string in hexadecimal. * The returned string should be freed with g_free() when done using it. * Since: 2.50 */ /** * g_compute_hmac_for_data: * @digest_type: a #GChecksumType to use for the HMAC * @key: (array length=key_len): the key to use in the HMAC * @key_len: the length of the key * @data: (array length=length): binary blob to compute the HMAC of * @length: length of @data * * Computes the HMAC for a binary @data of @length. This is a * convenience wrapper for g_hmac_new(), g_hmac_get_string() * and g_hmac_unref(). * * The hexadecimal string returned will be in lower case. * * Returns: the HMAC of the binary data as a string in hexadecimal. * The returned string should be freed with g_free() when done using it. * Since: 2.30 */ /** * g_compute_hmac_for_string: * @digest_type: a #GChecksumType to use for the HMAC * @key: (array length=key_len): the key to use in the HMAC * @key_len: the length of the key * @str: the string to compute the HMAC for * @length: the length of the string, or -1 if the string is nul-terminated * * Computes the HMAC for a string. * * The hexadecimal string returned will be in lower case. * * Returns: the HMAC as a hexadecimal string. * The returned string should be freed with g_free() * when done using it. * Since: 2.30 */ /** * g_cond_broadcast: * @cond: a #GCond * * If threads are waiting for @cond, all of them are unblocked. * If no threads are waiting for @cond, this function has no effect. * It is good practice to lock the same mutex as the waiting threads * while calling this function, though not required. */ /** * g_cond_clear: * @cond: an initialised #GCond * * Frees the resources allocated to a #GCond with g_cond_init(). * * This function should not be used with a #GCond that has been * statically allocated. * * Calling g_cond_clear() for a #GCond on which threads are * blocking leads to undefined behaviour. * * Since: 2.32 */ /** * g_cond_init: * @cond: an uninitialized #GCond * * Initialises a #GCond so that it can be used. * * This function is useful to initialise a #GCond that has been * allocated as part of a larger structure. It is not necessary to * initialise a #GCond that has been statically allocated. * * To undo the effect of g_cond_init() when a #GCond is no longer * needed, use g_cond_clear(). * * Calling g_cond_init() on an already-initialised #GCond leads * to undefined behaviour. * * Since: 2.32 */ /** * g_cond_signal: * @cond: a #GCond * * If threads are waiting for @cond, at least one of them is unblocked. * If no threads are waiting for @cond, this function has no effect. * It is good practice to hold the same lock as the waiting thread * while calling this function, though not required. */ /** * g_cond_wait: * @cond: a #GCond * @mutex: a #GMutex that is currently locked * * Atomically releases @mutex and waits until @cond is signalled. * When this function returns, @mutex is locked again and owned by the * calling thread. * * When using condition variables, it is possible that a spurious wakeup * may occur (ie: g_cond_wait() returns even though g_cond_signal() was * not called). It's also possible that a stolen wakeup may occur. * This is when g_cond_signal() is called, but another thread acquires * @mutex before this thread and modifies the state of the program in * such a way that when g_cond_wait() is able to return, the expected * condition is no longer met. * * For this reason, g_cond_wait() must always be used in a loop. See * the documentation for #GCond for a complete example. */ /** * g_cond_wait_until: * @cond: a #GCond * @mutex: a #GMutex that is currently locked * @end_time: the monotonic time to wait until * * Waits until either @cond is signalled or @end_time has passed. * * As with g_cond_wait() it is possible that a spurious or stolen wakeup * could occur. For that reason, waiting on a condition variable should * always be in a loop, based on an explicitly-checked predicate. * * %TRUE is returned if the condition variable was signalled (or in the * case of a spurious wakeup). %FALSE is returned if @end_time has * passed. * * The following code shows how to correctly perform a timed wait on a * condition variable (extending the example presented in the * documentation for #GCond): * * |[ * gpointer * pop_data_timed (void) * { * gint64 end_time; * gpointer data; * * g_mutex_lock (&data_mutex); * * end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND; * while (!current_data) * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time)) * { * // timeout has passed. * g_mutex_unlock (&data_mutex); * return NULL; * } * * // there is data for us * data = current_data; * current_data = NULL; * * g_mutex_unlock (&data_mutex); * * return data; * } * ]| * * Notice that the end time is calculated once, before entering the * loop and reused. This is the motivation behind the use of absolute * time on this API -- if a relative time of 5 seconds were passed * directly to the call and a spurious wakeup occurred, the program would * have to start over waiting again (which would lead to a total wait * time of more than 5 seconds). * * Returns: %TRUE on a signal, %FALSE on a timeout * Since: 2.32 */ /** * g_convert: * @str: (array length=len) (element-type guint8): * the string to convert. * @len: the length of the string in bytes, or -1 if the string is * nul-terminated (Note that some encodings may allow nul * bytes to occur inside strings. In that case, using -1 * for the @len parameter is unsafe) * @to_codeset: name of character set into which to convert @str * @from_codeset: character set of @str. * @bytes_read: (out) (optional): location to store the number of bytes in * the input string that were successfully converted, or %NULL. * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: (out) (optional): the number of bytes stored in * the output buffer (not including the terminating nul). * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * * Converts a string from one character set to another. * * Note that you should use g_iconv() for streaming conversions. * Despite the fact that @bytes_read can return information about partial * characters, the g_convert_... functions are not generally suitable * for streaming. If the underlying converter maintains internal state, * then this won't be preserved across successive calls to g_convert(), * g_convert_with_iconv() or g_convert_with_fallback(). (An example of * this is the GNU C converter for CP1255 which does not emit a base * character until it knows that the next character is not a mark that * could combine with the base character.) * * Using extensions such as "//TRANSLIT" may not work (or may not work * well) on many platforms. Consider using g_str_to_ascii() instead. * * Returns: (array length=bytes_written) (element-type guint8) (transfer full): * If the conversion was successful, a newly allocated buffer * containing the converted string, which must be freed with g_free(). * Otherwise %NULL and @error will be set. */ /** * g_convert_with_fallback: * @str: (array length=len) (element-type guint8): * the string to convert. * @len: the length of the string in bytes, or -1 if the string is * nul-terminated (Note that some encodings may allow nul * bytes to occur inside strings. In that case, using -1 * for the @len parameter is unsafe) * @to_codeset: name of character set into which to convert @str * @from_codeset: character set of @str. * @fallback: UTF-8 string to use in place of characters not * present in the target encoding. (The string must be * representable in the target encoding). * If %NULL, characters not in the target encoding will * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. * @bytes_read: (out) (optional): location to store the number of bytes in * the input string that were successfully converted, or %NULL. * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. * @bytes_written: (out) (optional): the number of bytes stored in * the output buffer (not including the terminating nul). * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * * Converts a string from one character set to another, possibly * including fallback sequences for characters not representable * in the output. Note that it is not guaranteed that the specification * for the fallback sequences in @fallback will be honored. Some * systems may do an approximate conversion from @from_codeset * to @to_codeset in their iconv() functions, * in which case GLib will simply return that approximate conversion. * * Note that you should use g_iconv() for streaming conversions. * Despite the fact that @bytes_read can return information about partial * characters, the g_convert_... functions are not generally suitable * for streaming. If the underlying converter maintains internal state, * then this won't be preserved across successive calls to g_convert(), * g_convert_with_iconv() or g_convert_with_fallback(). (An example of * this is the GNU C converter for CP1255 which does not emit a base * character until it knows that the next character is not a mark that * could combine with the base character.) * * Returns: (array length=bytes_written) (element-type guint8) (transfer full): * If the conversion was successful, a newly allocated buffer * containing the converted string, which must be freed with g_free(). * Otherwise %NULL and @error will be set. */ /** * g_convert_with_iconv: (skip) * @str: (array length=len) (element-type guint8): * the string to convert. * @len: the length of the string in bytes, or -1 if the string is * nul-terminated (Note that some encodings may allow nul * bytes to occur inside strings. In that case, using -1 * for the @len parameter is unsafe) * @converter: conversion descriptor from g_iconv_open() * @bytes_read: (out) (optional): location to store the number of bytes in * the input string that were successfully converted, or %NULL. * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: (out) (optional): the number of bytes stored in * the output buffer (not including the terminating nul). * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * * Converts a string from one character set to another. * * Note that you should use g_iconv() for streaming conversions. * Despite the fact that @bytes_read can return information about partial * characters, the g_convert_... functions are not generally suitable * for streaming. If the underlying converter maintains internal state, * then this won't be preserved across successive calls to g_convert(), * g_convert_with_iconv() or g_convert_with_fallback(). (An example of * this is the GNU C converter for CP1255 which does not emit a base * character until it knows that the next character is not a mark that * could combine with the base character.) * * Characters which are valid in the input character set, but which have no * representation in the output character set will result in a * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv() * specification, which leaves this behaviour implementation defined. Note that * this is the same error code as is returned for an invalid byte sequence in * the input character set. To get defined behaviour for conversion of * unrepresentable characters, use g_convert_with_fallback(). * * Returns: (array length=bytes_written) (element-type guint8) (transfer full): * If the conversion was successful, a newly allocated buffer * containing the converted string, which must be freed with * g_free(). Otherwise %NULL and @error will be set. */ /** * g_creat: * @filename: (type filename): a pathname in the GLib file name encoding * (UTF-8 on Windows) * @mode: as in creat() * * A wrapper for the POSIX creat() function. The creat() function is * used to convert a pathname into a file descriptor, creating a file * if necessary. * * On POSIX systems file descriptors are implemented by the operating * system. On Windows, it's the C library that implements creat() and * file descriptors. The actual Windows API for opening files is * different, see MSDN documentation for CreateFile(). The Win32 API * uses file handles, which are more randomish integers, not small * integers like file descriptors. * * Because file descriptors are specific to the C library on Windows, * the file descriptor returned by this function makes sense only to * functions in the same C library. Thus if the GLib-using code uses a * different C library than GLib does, the file descriptor returned by * this function cannot be passed to C library functions like write() * or read(). * * See your C library manual for more details about creat(). * * Returns: a new file descriptor, or -1 if an error occurred. * The return value can be used exactly like the return value * from creat(). * Since: 2.8 */ /** * g_critical: * @...: format string, followed by parameters to insert * into the format string (as with printf()) * * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). * It's more or less application-defined what constitutes * a critical vs. a regular warning. You could call * g_log_set_always_fatal() to make critical warnings exit * the program, then use g_critical() for fatal errors, for * example. * * You can also make critical warnings fatal at runtime by * setting the `G_DEBUG` environment variable (see * [Running GLib Applications](glib-running.html)): * * |[ * G_DEBUG=fatal-warnings gdb ./my-program * ]| * * Any unrelated failures can be skipped over in * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. * * The message should typically *not* be translated to the * user's language. * * If g_log_default_handler() is used as the log handler function, a new-line * character will automatically be appended to @..., and need not be entered * manually. * * If structured logging is enabled, this will use g_log_structured(); * otherwise it will use g_log(). See * [Using Structured Logging][using-structured-logging]. */ /** * g_datalist_clear: (skip) * @datalist: a datalist. * * Frees all the data elements of the datalist. * The data elements' destroy functions are called * if they have been set. */ /** * g_datalist_foreach: * @datalist: a datalist. * @func: (scope call): the function to call for each data element. * @user_data: (closure): user data to pass to the function. * * Calls the given function for each data element of the datalist. The * function is called with each data element's #GQuark id and data, * together with the given @user_data parameter. Note that this * function is NOT thread-safe. So unless @datalist can be protected * from any modifications during invocation of this function, it should * not be called. * * @func can make changes to @datalist, but the iteration will not * reflect changes made during the g_datalist_foreach() call, other * than skipping over elements that are removed. */ /** * g_datalist_get_data: * @datalist: a datalist. * @key: the string identifying a data element. * * Gets a data element, using its string identifier. This is slower than * g_datalist_id_get_data() because it compares strings. * * Returns: (transfer none) (nullable): the data element, or %NULL if it * is not found. */ /** * g_datalist_get_flags: * @datalist: pointer to the location that holds a list * * Gets flags values packed in together with the datalist. * See g_datalist_set_flags(). * * Returns: the flags of the datalist * Since: 2.8 */ /** * g_datalist_id_dup_data: (skip) * @datalist: location of a datalist * @key_id: the #GQuark identifying a data element * @dup_func: (nullable) (scope call): function to duplicate the old value * @user_data: (closure): passed as user_data to @dup_func * * This is a variant of g_datalist_id_get_data() which * returns a 'duplicate' of the value. @dup_func defines the * meaning of 'duplicate' in this context, it could e.g. * take a reference on a ref-counted object. * * If the @key_id is not set in the datalist then @dup_func * will be called with a %NULL argument. * * Note that @dup_func is called while the datalist is locked, so it * is not allowed to read or modify the datalist. * * This function can be useful to avoid races when multiple * threads are using the same datalist and the same key. * * Returns: (nullable): the result of calling @dup_func on the value * associated with @key_id in @datalist, or %NULL if not set. * If @dup_func is %NULL, the value is returned unmodified. * Since: 2.34 */ /** * g_datalist_id_get_data: * @datalist: a datalist. * @key_id: the #GQuark identifying a data element. * * Retrieves the data element corresponding to @key_id. * * Returns: (transfer none) (nullable): the data element, or %NULL if * it is not found. */ /** * g_datalist_id_remove_data: * @dl: a datalist. * @q: the #GQuark identifying the data element. * * Removes an element, using its #GQuark identifier. */ /** * g_datalist_id_remove_no_notify: (skip) * @datalist: a datalist. * @key_id: the #GQuark identifying a data element. * * Removes an element, without calling its destroy notification * function. * * Returns: (nullable): the data previously stored at @key_id, * or %NULL if none. */ /** * g_datalist_id_replace_data: (skip) * @datalist: location of a datalist * @key_id: the #GQuark identifying a data element * @oldval: (nullable): the old value to compare against * @newval: (nullable): the new value to replace it with * @destroy: (nullable): destroy notify for the new value * @old_destroy: (out) (optional): destroy notify for the existing value * * Compares the member that is associated with @key_id in * @datalist to @oldval, and if they are the same, replace * @oldval with @newval. * * This is like a typical atomic compare-and-exchange * operation, for a member of @datalist. * * If the previous value was replaced then ownership of the * old value (@oldval) is passed to the caller, including * the registered destroy notify for it (passed out in @old_destroy). * Its up to the caller to free this as he wishes, which may * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * * Returns: %TRUE if the existing value for @key_id was replaced * by @newval, %FALSE otherwise. * Since: 2.34 */ /** * g_datalist_id_set_data: * @dl: a datalist. * @q: the #GQuark to identify the data element. * @d: (nullable): the data element, or %NULL to remove any previous element * corresponding to @q. * * Sets the data corresponding to the given #GQuark id. Any previous * data with the same key is removed, and its destroy function is * called. */ /** * g_datalist_id_set_data_full: (skip) * @datalist: a datalist. * @key_id: the #GQuark to identify the data element. * @data: (nullable): the data element or %NULL to remove any previous element * corresponding to @key_id. * @destroy_func: (nullable): the function to call when the data element is * removed. This function will be called with the data * element and can be used to free any memory allocated * for it. If @data is %NULL, then @destroy_func must * also be %NULL. * * Sets the data corresponding to the given #GQuark id, and the * function to be called when the element is removed from the datalist. * Any previous data with the same key is removed, and its destroy * function is called. */ /** * g_datalist_init: (skip) * @datalist: a pointer to a pointer to a datalist. * * Resets the datalist to %NULL. It does not free any memory or call * any destroy functions. */ /** * g_datalist_remove_data: * @dl: a datalist. * @k: the string identifying the data element. * * Removes an element using its string identifier. The data element's * destroy function is called if it has been set. */ /** * g_datalist_remove_no_notify: (skip) * @dl: a datalist. * @k: the string identifying the data element. * * Removes an element, without calling its destroy notifier. */ /** * g_datalist_set_data: * @dl: a datalist. * @k: the string to identify the data element. * @d: (nullable): the data element, or %NULL to remove any previous element * corresponding to @k. * * Sets the data element corresponding to the given string identifier. */ /** * g_datalist_set_data_full: (skip) * @dl: a datalist. * @k: the string to identify the data element. * @d: (nullable): the data element, or %NULL to remove any previous element * corresponding to @k. * @f: (nullable): the function to call when the data element is removed. * This function will be called with the data element and can be used to * free any memory allocated for it. If @d is %NULL, then @f must * also be %NULL. * * Sets the data element corresponding to the given string identifier, * and the function to be called when the data element is removed. */ /** * g_datalist_set_flags: * @datalist: pointer to the location that holds a list * @flags: the flags to turn on. The values of the flags are * restricted by %G_DATALIST_FLAGS_MASK (currently * 3; giving two possible boolean flags). * A value for @flags that doesn't fit within the mask is * an error. * * Turns on flag values for a data list. This function is used * to keep a small number of boolean flags in an object with * a data list without using any additional space. It is * not generally useful except in circumstances where space * is very tight. (It is used in the base #GObject type, for * example.) * * Since: 2.8 */ /** * g_datalist_unset_flags: * @datalist: pointer to the location that holds a list * @flags: the flags to turn off. The values of the flags are * restricted by %G_DATALIST_FLAGS_MASK (currently * 3: giving two possible boolean flags). * A value for @flags that doesn't fit within the mask is * an error. * * Turns off flag values for a data list. See g_datalist_unset_flags() * * Since: 2.8 */ /** * g_dataset_destroy: * @dataset_location: (not nullable): the location identifying the dataset. * * Destroys the dataset, freeing all memory allocated, and calling any * destroy functions set for data elements. */ /** * g_dataset_foreach: * @dataset_location: (not nullable): the location identifying the dataset. * @func: (scope call): the function to call for each data element. * @user_data: (closure): user data to pass to the function. * * Calls the given function for each data element which is associated * with the given location. Note that this function is NOT thread-safe. * So unless @dataset_location can be protected from any modifications * during invocation of this function, it should not be called. * * @func can make changes to the dataset, but the iteration will not * reflect changes made during the g_dataset_foreach() call, other * than skipping over elements that are removed. */ /** * g_dataset_get_data: * @l: the location identifying the dataset. * @k: the string identifying the data element. * * Gets the data element corresponding to a string. * * Returns: (transfer none) (nullable): the data element corresponding to * the string, or %NULL if it is not found. */ /** * g_dataset_id_get_data: * @dataset_location: (not nullable): the location identifying the dataset. * @key_id: the #GQuark id to identify the data element. * * Gets the data element corresponding to a #GQuark. * * Returns: (transfer none) (nullable): the data element corresponding to * the #GQuark, or %NULL if it is not found. */ /** * g_dataset_id_remove_data: * @l: the location identifying the dataset. * @k: the #GQuark id identifying the data element. * * Removes a data element from a dataset. The data element's destroy * function is called if it has been set. */ /** * g_dataset_id_remove_no_notify: (skip) * @dataset_location: (not nullable): the location identifying the dataset. * @key_id: the #GQuark ID identifying the data element. * * Removes an element, without calling its destroy notification * function. * * Returns: (nullable): the data previously stored at @key_id, * or %NULL if none. */ /** * g_dataset_id_set_data: * @l: the location identifying the dataset. * @k: the #GQuark id to identify the data element. * @d: the data element. * * Sets the data element associated with the given #GQuark id. Any * previous data with the same key is removed, and its destroy function * is called. */ /** * g_dataset_id_set_data_full: (skip) * @dataset_location: (not nullable): the location identifying the dataset. * @key_id: the #GQuark id to identify the data element. * @data: the data element. * @destroy_func: the function to call when the data element is * removed. This function will be called with the data * element and can be used to free any memory allocated * for it. * * Sets the data element associated with the given #GQuark id, and also * the function to call when the data element is destroyed. Any * previous data with the same key is removed, and its destroy function * is called. */ /** * g_dataset_remove_data: * @l: the location identifying the dataset. * @k: the string identifying the data element. * * Removes a data element corresponding to a string. Its destroy * function is called if it has been set. */ /** * g_dataset_remove_no_notify: (skip) * @l: the location identifying the dataset. * @k: the string identifying the data element. * * Removes an element, without calling its destroy notifier. */ /** * g_dataset_set_data: * @l: the location identifying the dataset. * @k: the string to identify the data element. * @d: the data element. * * Sets the data corresponding to the given string identifier. */ /** * g_dataset_set_data_full: (skip) * @l: the location identifying the dataset. * @k: the string to identify the data element. * @d: the data element. * @f: the function to call when the data element is removed. This * function will be called with the data element and can be used to * free any memory allocated for it. * * Sets the data corresponding to the given string identifier, and the * function to call when the data element is destroyed. */ /** * g_date_add_days: * @date: a #GDate to increment * @n_days: number of days to move the date forward * * Increments a date some number of days. * To move forward by weeks, add weeks*7 days. * The date must be valid. */ /** * g_date_add_months: * @date: a #GDate to increment * @n_months: number of months to move forward * * Increments a date by some number of months. * If the day of the month is greater than 28, * this routine may change the day of the month * (because the destination month may not have * the current day in it). The date must be valid. */ /** * g_date_add_years: * @date: a #GDate to increment * @n_years: number of years to move forward * * Increments a date by some number of years. * If the date is February 29, and the destination * year is not a leap year, the date will be changed * to February 28. The date must be valid. */ /** * g_date_clamp: * @date: a #GDate to clamp * @min_date: minimum accepted value for @date * @max_date: maximum accepted value for @date * * If @date is prior to @min_date, sets @date equal to @min_date. * If @date falls after @max_date, sets @date equal to @max_date. * Otherwise, @date is unchanged. * Either of @min_date and @max_date may be %NULL. * All non-%NULL dates must be valid. */ /** * g_date_clear: * @date: pointer to one or more dates to clear * @n_dates: number of dates to clear * * Initializes one or more #GDate structs to a sane but invalid * state. The cleared dates will not represent an existing date, but will * not contain garbage. Useful to init a date declared on the stack. * Validity can be tested with g_date_valid(). */ /** * g_date_compare: * @lhs: first date to compare * @rhs: second date to compare * * qsort()-style comparison function for dates. * Both dates must be valid. * * Returns: 0 for equal, less than zero if @lhs is less than @rhs, * greater than zero if @lhs is greater than @rhs */ /** * g_date_copy: * @date: a #GDate to copy * * Copies a GDate to a newly-allocated GDate. If the input was invalid * (as determined by g_date_valid()), the invalid state will be copied * as is into the new object. * * Returns: (transfer full): a newly-allocated #GDate initialized from @date * Since: 2.56 */ /** * g_date_days_between: * @date1: the first date * @date2: the second date * * Computes the number of days between two dates. * If @date2 is prior to @date1, the returned value is negative. * Both dates must be valid. * * Returns: the number of days between @date1 and @date2 */ /** * g_date_free: * @date: a #GDate to free * * Frees a #GDate returned from g_date_new(). */ /** * g_date_get_day: * @date: a #GDate to extract the day of the month from * * Returns the day of the month. The date must be valid. * * Returns: day of the month */ /** * g_date_get_day_of_year: * @date: a #GDate to extract day of year from * * Returns the day of the year, where Jan 1 is the first day of the * year. The date must be valid. * * Returns: day of the year */ /** * g_date_get_days_in_month: * @month: month * @year: year * * Returns the number of days in a month, taking leap * years into account. * * Returns: number of days in @month during the @year */ /** * g_date_get_iso8601_week_of_year: * @date: a valid #GDate * * Returns the week of the year, where weeks are interpreted according * to ISO 8601. * * Returns: ISO 8601 week number of the year. * Since: 2.6 */ /** * g_date_get_julian: * @date: a #GDate to extract the Julian day from * * Returns the Julian day or "serial number" of the #GDate. The * Julian day is simply the number of days since January 1, Year 1; i.e., * January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, * etc. The date must be valid. * * Returns: Julian day */ /** * g_date_get_monday_week_of_year: * @date: a #GDate * * Returns the week of the year, where weeks are understood to start on * Monday. If the date is before the first Monday of the year, return 0. * The date must be valid. * * Returns: week of the year */ /** * g_date_get_monday_weeks_in_year: * @year: a year * * Returns the number of weeks in the year, where weeks * are taken to start on Monday. Will be 52 or 53. The * date must be valid. (Years always have 52 7-day periods, * plus 1 or 2 extra days depending on whether it's a leap * year. This function is basically telling you how many * Mondays are in the year, i.e. there are 53 Mondays if * one of the extra days happens to be a Monday.) * * Returns: number of Mondays in the year */ /** * g_date_get_month: * @date: a #GDate to get the month from * * Returns the month of the year. The date must be valid. * * Returns: month of the year as a #GDateMonth */ /** * g_date_get_sunday_week_of_year: * @date: a #GDate * * Returns the week of the year during which this date falls, if * weeks are understood to begin on Sunday. The date must be valid. * Can return 0 if the day is before the first Sunday of the year. * * Returns: week number */ /** * g_date_get_sunday_weeks_in_year: * @year: year to count weeks in * * Returns the number of weeks in the year, where weeks * are taken to start on Sunday. Will be 52 or 53. The * date must be valid. (Years always have 52 7-day periods, * plus 1 or 2 extra days depending on whether it's a leap * year. This function is basically telling you how many * Sundays are in the year, i.e. there are 53 Sundays if * one of the extra days happens to be a Sunday.) * * Returns: the number of weeks in @year */ /** * g_date_get_weekday: * @date: a #GDate * * Returns the day of the week for a #GDate. The date must be valid. * * Returns: day of the week as a #GDateWeekday. */ /** * g_date_get_year: * @date: a #GDate * * Returns the year of a #GDate. The date must be valid. * * Returns: year in which the date falls */ /** * g_date_is_first_of_month: * @date: a #GDate to check * * Returns %TRUE if the date is on the first of a month. * The date must be valid. * * Returns: %TRUE if the date is the first of the month */ /** * g_date_is_last_of_month: * @date: a #GDate to check * * Returns %TRUE if the date is the last day of the month. * The date must be valid. * * Returns: %TRUE if the date is the last day of the month */ /** * g_date_is_leap_year: * @year: year to check * * Returns %TRUE if the year is a leap year. * * For the purposes of this function, leap year is every year * divisible by 4 unless that year is divisible by 100. If it * is divisible by 100 it would be a leap year only if that year * is also divisible by 400. * * Returns: %TRUE if the year is a leap year */ /** * g_date_new: * * Allocates a #GDate and initializes * it to a sane state. The new date will * be cleared (as if you'd called g_date_clear()) but invalid (it won't * represent an existing day). Free the return value with g_date_free(). * * Returns: a newly-allocated #GDate */ /** * g_date_new_dmy: * @day: day of the month * @month: month of the year * @year: year * * Like g_date_new(), but also sets the value of the date. Assuming the * day-month-year triplet you pass in represents an existing day, the * returned date will be valid. * * Returns: a newly-allocated #GDate initialized with @day, @month, and @year */ /** * g_date_new_julian: * @julian_day: days since January 1, Year 1 * * Like g_date_new(), but also sets the value of the date. Assuming the * Julian day number you pass in is valid (greater than 0, less than an * unreasonably large number), the returned date will be valid. * * Returns: a newly-allocated #GDate initialized with @julian_day */ /** * g_date_order: * @date1: the first date * @date2: the second date * * Checks if @date1 is less than or equal to @date2, * and swap the values if this is not the case. */ /** * g_date_set_day: * @date: a #GDate * @day: day to set * * Sets the day of the month for a #GDate. If the resulting * day-month-year triplet is invalid, the date will be invalid. */ /** * g_date_set_dmy: * @date: a #GDate * @day: day * @month: month * @y: year * * Sets the value of a #GDate from a day, month, and year. * The day-month-year triplet must be valid; if you aren't * sure it is, call g_date_valid_dmy() to check before you * set it. */ /** * g_date_set_julian: * @date: a #GDate * @julian_date: Julian day number (days since January 1, Year 1) * * Sets the value of a #GDate from a Julian day number. */ /** * g_date_set_month: * @date: a #GDate * @month: month to set * * Sets the month of the year for a #GDate. If the resulting * day-month-year triplet is invalid, the date will be invalid. */ /** * g_date_set_parse: * @date: a #GDate to fill in * @str: string to parse * * Parses a user-inputted string @str, and try to figure out what date it * represents, taking the [current locale][setlocale] into account. If the * string is successfully parsed, the date will be valid after the call. * Otherwise, it will be invalid. You should check using g_date_valid() * to see whether the parsing succeeded. * * This function is not appropriate for file formats and the like; it * isn't very precise, and its exact behavior varies with the locale. * It's intended to be a heuristic routine that guesses what the user * means by a given string (and it does work pretty well in that * capacity). */ /** * g_date_set_time: * @date: a #GDate. * @time_: #GTime value to set. * * Sets the value of a date from a #GTime value. * The time to date conversion is done using the user's current timezone. * * Deprecated: 2.10: Use g_date_set_time_t() instead. */ /** * g_date_set_time_t: * @date: a #GDate * @timet: time_t value to set * * Sets the value of a date to the date corresponding to a time * specified as a time_t. The time to date conversion is done using * the user's current timezone. * * To set the value of a date to the current day, you could write: * |[ * g_date_set_time_t (date, time (NULL)); * ]| * * Since: 2.10 */ /** * g_date_set_time_val: * @date: a #GDate * @timeval: #GTimeVal value to set * * Sets the value of a date from a #GTimeVal value. Note that the * @tv_usec member is ignored, because #GDate can't make use of the * additional precision. * * The time to date conversion is done using the user's current timezone. * * Since: 2.10 */ /** * g_date_set_year: * @date: a #GDate * @year: year to set * * Sets the year for a #GDate. If the resulting day-month-year * triplet is invalid, the date will be invalid. */ /** * g_date_strftime: * @s: destination buffer * @slen: buffer size * @format: format string * @date: valid #GDate * * Generates a printed representation of the date, in a * [locale][setlocale]-specific way. * Works just like the platform's C library strftime() function, * but only accepts date-related formats; time-related formats * give undefined results. Date must be valid. Unlike strftime() * (which uses the locale encoding), works on a UTF-8 format * string and stores a UTF-8 result. * * This function does not provide any conversion specifiers in * addition to those implemented by the platform's C library. * For example, don't expect that using g_date_strftime() would * make the \%F provided by the C99 strftime() work on Windows * where the C library only complies to C89. * * Returns: number of characters written to the buffer, or 0 the buffer was too small */ /** * g_date_subtract_days: * @date: a #GDate to decrement * @n_days: number of days to move * * Moves a date some number of days into the past. * To move by weeks, just move by weeks*7 days. * The date must be valid. */ /** * g_date_subtract_months: * @date: a #GDate to decrement * @n_months: number of months to move * * Moves a date some number of months into the past. * If the current day of the month doesn't exist in * the destination month, the day of the month * may change. The date must be valid. */ /** * g_date_subtract_years: * @date: a #GDate to decrement * @n_years: number of years to move * * Moves a date some number of years into the past. * If the current day doesn't exist in the destination * year (i.e. it's February 29 and you move to a non-leap-year) * then the day is changed to February 29. The date * must be valid. */ /** * g_date_time_add: * @datetime: a #GDateTime * @timespan: a #GTimeSpan * * Creates a copy of @datetime and adds the specified timespan to the copy. * * Returns: the newly created #GDateTime which should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_add_days: * @datetime: a #GDateTime * @days: the number of days * * Creates a copy of @datetime and adds the specified number of days to the * copy. Add negative values to subtract days. * * Returns: the newly created #GDateTime which should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_add_full: * @datetime: a #GDateTime * @years: the number of years to add * @months: the number of months to add * @days: the number of days to add * @hours: the number of hours to add * @minutes: the number of minutes to add * @seconds: the number of seconds to add * * Creates a new #GDateTime adding the specified values to the current date and * time in @datetime. Add negative values to subtract. * * Returns: the newly created #GDateTime that should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_add_hours: * @datetime: a #GDateTime * @hours: the number of hours to add * * Creates a copy of @datetime and adds the specified number of hours. * Add negative values to subtract hours. * * Returns: the newly created #GDateTime which should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_add_minutes: * @datetime: a #GDateTime * @minutes: the number of minutes to add * * Creates a copy of @datetime adding the specified number of minutes. * Add negative values to subtract minutes. * * Returns: the newly created #GDateTime which should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_add_months: * @datetime: a #GDateTime * @months: the number of months * * Creates a copy of @datetime and adds the specified number of months to the * copy. Add negative values to subtract months. * * Returns: the newly created #GDateTime which should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_add_seconds: * @datetime: a #GDateTime * @seconds: the number of seconds to add * * Creates a copy of @datetime and adds the specified number of seconds. * Add negative values to subtract seconds. * * Returns: the newly created #GDateTime which should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_add_weeks: * @datetime: a #GDateTime * @weeks: the number of weeks * * Creates a copy of @datetime and adds the specified number of weeks to the * copy. Add negative values to subtract weeks. * * Returns: the newly created #GDateTime which should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_add_years: * @datetime: a #GDateTime * @years: the number of years * * Creates a copy of @datetime and adds the specified number of years to the * copy. Add negative values to subtract years. * * Returns: the newly created #GDateTime which should be freed with * g_date_time_unref(). * Since: 2.26 */ /** * g_date_time_compare: * @dt1: (not nullable): first #GDateTime to compare * @dt2: (not nullable): second #GDateTime to compare * * A comparison function for #GDateTimes that is suitable * as a #GCompareFunc. Both #GDateTimes must be non-%NULL. * * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater * than @dt2. * Since: 2.26 */ /** * g_date_time_difference: * @end: a #GDateTime * @begin: a #GDateTime * * Calculates the difference in time between @end and @begin. The * #GTimeSpan that is returned is effectively @end - @begin (ie: * positive if the first parameter is larger). * * Returns: the difference between the two #GDateTime, as a time * span expressed in microseconds. * Since: 2.26 */ /** * g_date_time_equal: * @dt1: (not nullable): a #GDateTime * @dt2: (not nullable): a #GDateTime * * Checks to see if @dt1 and @dt2 are equal. * * Equal here means that they represent the same moment after converting * them to the same time zone. * * Returns: %TRUE if @dt1 and @dt2 are equal * Since: 2.26 */ /** * g_date_time_format: * @datetime: A #GDateTime * @format: a valid UTF-8 string, containing the format for the * #GDateTime * * Creates a newly allocated string representing the requested @format. * * The format strings understood by this function are a subset of the * strftime() format language as specified by C99. The \%D, \%U and \%W * conversions are not supported, nor is the 'E' modifier. The GNU * extensions \%k, \%l, \%s and \%P are supported, however, as are the * '0', '_' and '-' modifiers. * * In contrast to strftime(), this function always produces a UTF-8 * string, regardless of the current locale. Note that the rendering of * many formats is locale-dependent and may not match the strftime() * output exactly. * * The following format specifiers are supported: * * - \%a: the abbreviated weekday name according to the current locale * - \%A: the full weekday name according to the current locale * - \%b: the abbreviated month name according to the current locale * - \%B: the full month name according to the current locale * - \%c: the preferred date and time representation for the current locale * - \%C: the century number (year/100) as a 2-digit integer (00-99) * - \%d: the day of the month as a decimal number (range 01 to 31) * - \%e: the day of the month as a decimal number (range 1 to 31) * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format) * - \%g: the last two digits of the ISO 8601 week-based year as a * decimal number (00-99). This works well with \%V and \%u. * - \%G: the ISO 8601 week-based year as a decimal number. This works * well with \%V and \%u. * - \%h: equivalent to \%b * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23) * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12) * - \%j: the day of the year as a decimal number (range 001 to 366) * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23); * single digits are preceded by a blank * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); * single digits are preceded by a blank * - \%m: the month as a decimal number (range 01 to 12) * - \%M: the minute as a decimal number (range 00 to 59) * - \%p: either "AM" or "PM" according to the given time value, or the * corresponding strings for the current locale. Noon is treated as * "PM" and midnight as "AM". * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for * the current locale * - \%r: the time in a.m. or p.m. notation * - \%R: the time in 24-hour notation (\%H:\%M) * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01 * 00:00:00 UTC * - \%S: the second as a decimal number (range 00 to 60) * - \%t: a tab character * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S) * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7, * Monday being 1. This works well with \%G and \%V. * - \%V: the ISO 8601 standard week number of the current year as a decimal * number, range 01 to 53, where week 1 is the first week that has at * least 4 days in the new year. See g_date_time_get_week_of_year(). * This works well with \%G and \%u. * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0. * This is not the ISO 8601 standard format -- use \%u instead. * - \%x: the preferred date representation for the current locale without * the time * - \%X: the preferred time representation for the current locale without * the date * - \%y: the year as a decimal number without the century * - \%Y: the year as a decimal number including the century * - \%z: the time zone as an offset from UTC (+hhmm) * - \%:z: the time zone as an offset from UTC (+hh:mm). * This is a gnulib strftime() extension. Since: 2.38 * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a * gnulib strftime() extension. Since: 2.38 * - \%:::z: the time zone as an offset from UTC, with : to necessary * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38 * - \%Z: the time zone or name or abbreviation * - \%\%: a literal \% character * * Some conversion specifications can be modified by preceding the * conversion specifier by one or more modifier characters. The * following modifiers are supported for many of the numeric * conversions: * * - O: Use alternative numeric symbols, if the current locale supports those. * - _: Pad a numeric result with spaces. This overrides the default padding * for the specifier. * - -: Do not pad a numeric result. This overrides the default padding * for the specifier. * - 0: Pad a numeric result with zeros. This overrides the default padding * for the specifier. * * Returns: a newly allocated string formatted to the requested format * or %NULL in the case that there was an error (such as a format specifier * not being supported in the current locale). The string * should be freed with g_free(). * Since: 2.26 */ /** * g_date_time_get_day_of_month: * @datetime: a #GDateTime * * Retrieves the day of the month represented by @datetime in the gregorian * calendar. * * Returns: the day of the month * Since: 2.26 */ /** * g_date_time_get_day_of_week: * @datetime: a #GDateTime * * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is * Monday, 2 is Tuesday... 7 is Sunday). * * Returns: the day of the week * Since: 2.26 */ /** * g_date_time_get_day_of_year: * @datetime: a #GDateTime * * Retrieves the day of the year represented by @datetime in the Gregorian * calendar. * * Returns: the day of the year * Since: 2.26 */ /** * g_date_time_get_hour: * @datetime: a #GDateTime * * Retrieves the hour of the day represented by @datetime * * Returns: the hour of the day * Since: 2.26 */ /** * g_date_time_get_microsecond: * @datetime: a #GDateTime * * Retrieves the microsecond of the date represented by @datetime * * Returns: the microsecond of the second * Since: 2.26 */ /** * g_date_time_get_minute: * @datetime: a #GDateTime * * Retrieves the minute of the hour represented by @datetime * * Returns: the minute of the hour * Since: 2.26 */ /** * g_date_time_get_month: * @datetime: a #GDateTime * * Retrieves the month of the year represented by @datetime in the Gregorian * calendar. * * Returns: the month represented by @datetime * Since: 2.26 */ /** * g_date_time_get_second: * @datetime: a #GDateTime * * Retrieves the second of the minute represented by @datetime * * Returns: the second represented by @datetime * Since: 2.26 */ /** * g_date_time_get_seconds: * @datetime: a #GDateTime * * Retrieves the number of seconds since the start of the last minute, * including the fractional part. * * Returns: the number of seconds * Since: 2.26 */ /** * g_date_time_get_timezone_abbreviation: * @datetime: a #GDateTime * * Determines the time zone abbreviation to be used at the time and in * the time zone of @datetime. * * For example, in Toronto this is currently "EST" during the winter * months and "EDT" during the summer months when daylight savings * time is in effect. * * Returns: (transfer none): the time zone abbreviation. The returned * string is owned by the #GDateTime and it should not be * modified or freed * Since: 2.26 */ /** * g_date_time_get_utc_offset: * @datetime: a #GDateTime * * Determines the offset to UTC in effect at the time and in the time * zone of @datetime. * * The offset is the number of microseconds that you add to UTC time to * arrive at local time for the time zone (ie: negative numbers for time * zones west of GMT, positive numbers for east). * * If @datetime represents UTC time, then the offset is always zero. * * Returns: the number of microseconds that should be added to UTC to * get the local time * Since: 2.26 */ /** * g_date_time_get_week_numbering_year: * @datetime: a #GDateTime * * Returns the ISO 8601 week-numbering year in which the week containing * @datetime falls. * * This function, taken together with g_date_time_get_week_of_year() and * g_date_time_get_day_of_week() can be used to determine the full ISO * week date on which @datetime falls. * * This is usually equal to the normal Gregorian year (as returned by * g_date_time_get_year()), except as detailed below: * * For Thursday, the week-numbering year is always equal to the usual * calendar year. For other days, the number is such that every day * within a complete week (Monday to Sunday) is contained within the * same week-numbering year. * * For Monday, Tuesday and Wednesday occurring near the end of the year, * this may mean that the week-numbering year is one greater than the * calendar year (so that these days have the same week-numbering year * as the Thursday occurring early in the next year). * * For Friday, Saturday and Sunday occurring near the start of the year, * this may mean that the week-numbering year is one less than the * calendar year (so that these days have the same week-numbering year * as the Thursday occurring late in the previous year). * * An equivalent description is that the week-numbering year is equal to * the calendar year containing the majority of the days in the current * week (Monday to Sunday). * * Note that January 1 0001 in the proleptic Gregorian calendar is a * Monday, so this function never returns 0. * * Returns: the ISO 8601 week-numbering year for @datetime * Since: 2.26 */ /** * g_date_time_get_week_of_year: * @datetime: a #GDateTime * * Returns the ISO 8601 week number for the week containing @datetime. * The ISO 8601 week number is the same for every day of the week (from * Moday through Sunday). That can produce some unusual results * (described below). * * The first week of the year is week 1. This is the week that contains * the first Thursday of the year. Equivalently, this is the first week * that has more than 4 of its days falling within the calendar year. * * The value 0 is never returned by this function. Days contained * within a year but occurring before the first ISO 8601 week of that * year are considered as being contained in the last week of the * previous year. Similarly, the final days of a calendar year may be * considered as being part of the first ISO 8601 week of the next year * if 4 or more days of that week are contained within the new year. * * Returns: the ISO 8601 week number for @datetime. * Since: 2.26 */ /** * g_date_time_get_year: * @datetime: A #GDateTime * * Retrieves the year represented by @datetime in the Gregorian calendar. * * Returns: the year represented by @datetime * Since: 2.26 */ /** * g_date_time_get_ymd: * @datetime: a #GDateTime. * @year: (out) (optional): the return location for the gregorian year, or %NULL. * @month: (out) (optional): the return location for the month of the year, or %NULL. * @day: (out) (optional): the return location for the day of the month, or %NULL. * * Retrieves the Gregorian day, month, and year of a given #GDateTime. * * Since: 2.26 */ /** * g_date_time_hash: * @datetime: (not nullable): a #GDateTime * * Hashes @datetime into a #guint, suitable for use within #GHashTable. * * Returns: a #guint containing the hash * Since: 2.26 */ /** * g_date_time_is_daylight_savings: * @datetime: a #GDateTime * * Determines if daylight savings time is in effect at the time and in * the time zone of @datetime. * * Returns: %TRUE if daylight savings time is in effect * Since: 2.26 */ /** * g_date_time_new: * @tz: a #GTimeZone * @year: the year component of the date * @month: the month component of the date * @day: the day component of the date * @hour: the hour component of the date * @minute: the minute component of the date * @seconds: the number of seconds past the minute * * Creates a new #GDateTime corresponding to the given date and time in * the time zone @tz. * * The @year must be between 1 and 9999, @month between 1 and 12 and @day * between 1 and 28, 29, 30 or 31 depending on the month and the year. * * @hour must be between 0 and 23 and @minute must be between 0 and 59. * * @seconds must be at least 0.0 and must be strictly less than 60.0. * It will be rounded down to the nearest microsecond. * * If the given time is not representable in the given time zone (for * example, 02:30 on March 14th 2010 in Toronto, due to daylight savings * time) then the time will be rounded up to the nearest existing time * (in this case, 03:00). If this matters to you then you should verify * the return value for containing the same as the numbers you gave. * * In the case that the given time is ambiguous in the given time zone * (for example, 01:30 on November 7th 2010 in Toronto, due to daylight * savings time) then the time falling within standard (ie: * non-daylight) time is taken. * * It not considered a programmer error for the values to this function * to be out of range, but in the case that they are, the function will * return %NULL. * * You should release the return value by calling g_date_time_unref() * when you are done with it. * * Returns: a new #GDateTime, or %NULL * Since: 2.26 */ /** * g_date_time_new_from_iso8601: * @text: an ISO 8601 formatted time string. * @default_tz: (nullable): a #GTimeZone to use if the text doesn't contain a * timezone, or %NULL. * * Creates a #GDateTime corresponding to the given * [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601) * @text. ISO 8601 strings of the form