/************************************************************/ /* 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: 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: 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. * * 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. */ /** * 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 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. */ /** * 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 * `DIST_EXTRA` 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: 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 * #GTestTrapSubprocessFlags. */ /** * 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*. */ /** * 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_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_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 * * 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 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 * * 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 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 or #gssize. 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_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 is used to export function prototypes so they can be linked * with an external version when no inlining is performed. The file which * implements the functions should define %G_IMPLEMENTS_INLINES * before including the headers which contain %G_INLINE_FUNC declarations. * Since inlining is very compiler-dependent using these macros correctly * is very difficult. Their use is strongly discouraged. * * This macro is often mistaken for a replacement for the inline keyword; * inline is already declared in a portable manner in the GLib headers * and can be used normally. */ /** * 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_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_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. * * For applications, this is typically left as the default %NULL * (or "") domain. 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. * * For example, GTK+ uses this in its Makefile.am: * |[ * INCLUDES = -DG_LOG_DOMAIN=\"Gtk\" * ]| */ /** * G_LOG_FATAL_MASK: * * GLib log levels that are considered fatal by default. */ /** * 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 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", *string2 = "two", *string3 = "three"; * * gparray = 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: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 he wishes 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. 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. * * 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. 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; * * fd = open ("file.txt", O_RDONLY); * * 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 (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, 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. * * 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 * * 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. * * 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 stores a value along with * information about the type of that value. 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 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) * or supplied out-of-band (for instance, a 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. * * 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 byes 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_STRING; 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. */ /** * 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. */ /** * 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 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 covers details of how to set up message extraction * with xgettext. */ /** * 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. */ /** * 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. */ /** * 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 fails, the application is terminated. * This also means that there is no need to check if the call succeeded. * * 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). See also g_mem_set_vtable(). */ /** * 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 Logging * @short_description: versatile support for logging messages * with different levels of importance * * These functions provide support for logging error messages * or messages used for debugging. * * There are several built-in levels of messages, defined in * #GLogLevelFlags. These can be extended with user-defined levels. */ /** * 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. */ /** * 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. */ /** * 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_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() * 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. */ /** * 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 string and numerical comparisons: * g_assert_cmpfloat(), g_assert_cmpint(), g_assert_cmpuint(), * g_assert_cmphex(), g_assert_cmpstr(). 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. * * GLib ships with two utilities called gtester and gtester-report to * facilitate running tests and producing nicely formatted test reports. */ /** * 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. */ /** * 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. */ /** * 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 4 groups: * - New types which are not part of standard C (but are defined in * various C standard library header files) - #gboolean, #gsize, * #gssize, #goffset, #gintptr, #guintptr. * - 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. * * 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: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:warnings * @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. */ /** * 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_access: * @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: 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. * * 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: 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: 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 MT-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 MT-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. * * 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'. * * 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_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: 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: 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: 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. */ /** * 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_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_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_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_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: 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: 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: 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: 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: 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: 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: 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_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: * @in: (array length=len) (element-type guint8): binary input data * @len: max length of @in data to decode * @out: (out) (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. * * 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: 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: 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 */ /** * 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 */ /** * 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: (allow-none): the name of the application registering the bookmark * or %NULL * @exec: (allow-none): 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: (allow-none) (out): return location for the command line of the application, or %NULL * @count: (allow-none) (out): return location for the registration count, or %NULL * @stamp: (allow-none) (out): 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: (allow-none) (out): 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: (allow-none) (out): 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: (allow-none) (out): return location for the icon's location or %NULL * @mime_type: (allow-none) (out): 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: (allow-none): 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: (allow-none) (out): 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: 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: a relative path to a filename to open and parse * @full_path: (allow-none): 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: 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: (allow-none): 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: * * 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: (allow-none): 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: (allow-none): 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: (allow-none): 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: (allow-none): 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: (allow-none) (out): 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: a newly allocated string holding * the contents of the #GBookmarkFile * Since: 2.12 */ /** * g_bookmark_file_to_file: * @bookmark: a #GBookmarkFile * @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: 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: a newly-allocated string that must be freed with g_free(). */ /** * g_build_filenamev: * @args: (array zero-terminated=1): %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: a newly-allocated string that must be freed with g_free(). * Since: 2.8 */ /** * g_build_path: * @separator: a string used to separator the elements of the path. * @first_element: 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: 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): %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: 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) (allow-none): 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) (type guint8) (allow-none): 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) (allow-none): * 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. * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ /** * g_bytes_new_static: (skip) * @data: (transfer full) (array length=size) (element-type guint8) (allow-none): * 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) (allow-none): * 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: * @data: (array length=size) (allow-none): 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: (allow-none): a #GBytes * * Releases a reference on @bytes. This may result in the bytes being * freed. * * 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: 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): a pointer to the same byte data, which should * be freed with g_free() * Since: 2.32 */ /** * g_chdir: * @path: 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. * * 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: (allow-none): 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. * * 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. * * Note further that using g_child_watch_source_new() is not * compatible with calling `waitpid` with a nonpositive first * argument in the application. Calling waitpid() for individual * pids will still work fine. * * Similarly, on POSIX platforms, the @pid passed to this function must * be greater than 0 (i.e. this function must wait for a specific child, * and cannot wait for one of many children by using a nonpositive argument). * * Returns: the newly-created child watch source * Since: 2.4 */ /** * g_chmod: * @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 is %NULL, does nothing. If @err is non-%NULL, * calls g_error_free() on *@err and sets *@err to %NULL. */ /** * g_clear_pointer: (skip) * @pp: 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. * * This function is threadsafe and modifies the pointer atomically, * using memory barriers where needed. * * 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. * * 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_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: 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: 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): 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): 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 @byes_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: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with * g_free(). Otherwise %NULL and @error will be set. */ /** * g_convert_with_fallback: * @str: 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 character 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: 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: 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 @byes_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: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with * g_free(). Otherwise %NULL and @error will be set. */ /** * g_convert_with_iconv: * @str: 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: 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: 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 @byes_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: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with * g_free(). Otherwise %NULL and @error will be set. */ /** * g_creat: * @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)). * * 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. */ /** * g_datalist_clear: * @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: the function to call for each data element. * @user_data: 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. */ /** * 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: 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: * @datalist: location of a datalist * @key_id: the #GQuark identifying a data element * @dup_func: (allow-none): function to duplicate the old value * @user_data: (allow-none): 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: 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: 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: * @datalist: a datalist. * @key_id: the #GQuark identifying a data element. * * Removes an element, without calling its destroy notification * function. * * Returns: the data previously stored at @key_id, or %NULL if none. */ /** * g_datalist_id_replace_data: * @datalist: location of a datalist * @key_id: the #GQuark identifying a data element * @oldval: (allow-none): the old value to compare against * @newval: (allow-none): the new value to replace it with * @destroy: (allow-none): destroy notify for the new value * @old_destroy: (allow-none): 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 registred 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: (allow-none): 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: * @datalist: a datalist. * @key_id: the #GQuark to identify the data element. * @data: (allow-none): the data element or %NULL to remove any previous element * corresponding to @key_id. * @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. 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: * @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: * @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: (allow-none): 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: * @dl: a datalist. * @k: the string to identify the data element. * @d: (allow-none): the data element, or %NULL to remove any previous element * corresponding to @k. * @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. 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: 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: the location identifying the dataset. * @func: the function to call for each data element. * @user_data: 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 @datalist can be protected from any modifications during * invocation of this function, it should not be called. */ /** * 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: the data element corresponding to the string, or %NULL if * it is not found. */ /** * g_dataset_id_get_data: * @dataset_location: the location identifying the dataset. * @key_id: the #GQuark id to identify the data element. * * Gets the data element corresponding to a #GQuark. * * Returns: 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: * @dataset_location: the location identifying the dataset. * @key_id: the #GQuark ID identifying the data element. * * Removes an element, without calling its destroy notification * function. * * Returns: 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: * @dataset_location: 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: * @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: * @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_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 being 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: first #GDateTime to compare * @dt2: 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: a #GDateTime * @dt2: 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 rpresentation 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. 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, Saturaday 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) (allow-none): the return location for the gregorian year, or %NULL. * @month: (out) (allow-none): the return location for the month of the year, or %NULL. * @day: (out) (allow-none): 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: 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_timeval_local: * @tv: a #GTimeVal * * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the * local time zone. * * The time contained in a #GTimeVal is always stored in the form of * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the * local time offset. * * This call can fail (returning %NULL) if @tv represents a time outside * of the supported range of #GDateTime. * * 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_timeval_utc: * @tv: a #GTimeVal * * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC. * * The time contained in a #GTimeVal is always stored in the form of * seconds elapsed since 1970-01-01 00:00:00 UTC. * * This call can fail (returning %NULL) if @tv represents a time outside * of the supported range of #GDateTime. * * 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_unix_local: * @t: the Unix time * * Creates a #GDateTime corresponding to the given Unix time @t in the * local time zone. * * Unix time is the number of seconds that have elapsed since 1970-01-01 * 00:00:00 UTC, regardless of the local time offset. * * This call can fail (returning %NULL) if @t represents a time outside * of the supported range of #GDateTime. * * 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_unix_utc: * @t: the Unix time * * Creates a #GDateTime corresponding to the given Unix time @t in UTC. * * Unix time is the number of seconds that have elapsed since 1970-01-01 * 00:00:00 UTC. * * This call can fail (returning %NULL) if @t represents a time outside * of the supported range of #GDateTime. * * 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_local: * @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 local time zone. * * This call is equivalent to calling g_date_time_new() with the time * zone returned by g_time_zone_new_local(). * * Returns: a #GDateTime, or %NULL * Since: 2.26 */ /** * g_date_time_new_now: * @tz: a #GTimeZone * * Creates a #GDateTime corresponding to this exact instant in the given * time zone @tz. The time is as accurate as the system allows, to a * maximum accuracy of 1 microsecond. * * This function will always succeed unless the system clock is set to * truly insane values (or unless GLib is still being used after the * year 9999). * * 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_now_local: * * Creates a #GDateTime corresponding to this exact instant in the local * time zone. * * This is equivalent to calling g_date_time_new_now() with the time * zone returned by g_time_zone_new_local(). * * Returns: a new #GDateTime, or %NULL * Since: 2.26 */ /** * g_date_time_new_now_utc: * * Creates a #GDateTime corresponding to this exact instant in UTC. * * This is equivalent to calling g_date_time_new_now() with the time * zone returned by g_time_zone_new_utc(). * * Returns: a new #GDateTime, or %NULL * Since: 2.26 */ /** * g_date_time_new_utc: * @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 * UTC. * * This call is equivalent to calling g_date_time_new() with the time * zone returned by g_time_zone_new_utc(). * * Returns: a #GDateTime, or %NULL * Since: 2.26 */ /** * g_date_time_ref: * @datetime: a #GDateTime * * Atomically increments the reference count of @datetime by one. * * Returns: the #GDateTime with the reference count increased * Since: 2.26 */ /** * g_date_time_to_local: * @datetime: a #GDateTime * * Creates a new #GDateTime corresponding to the same instant in time as * @datetime, but in the local time zone. * * This call is equivalent to calling g_date_time_to_timezone() with the * time zone returned by g_time_zone_new_local(). * * Returns: the newly created #GDateTime * Since: 2.26 */ /** * g_date_time_to_timeval: * @datetime: a #GDateTime * @tv: a #GTimeVal to modify * * Stores the instant in time that @datetime represents into @tv. * * The time contained in a #GTimeVal is always stored in the form of * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time * zone associated with @datetime. * * On systems where 'long' is 32bit (ie: all 32bit systems and all * Windows systems), a #GTimeVal is incapable of storing the entire * range of values that #GDateTime is capable of expressing. On those * systems, this function returns %FALSE to indicate that the time is * out of range. * * On systems where 'long' is 64bit, this function never fails. * * Returns: %TRUE if successful, else %FALSE * Since: 2.26 */ /** * g_date_time_to_timezone: * @datetime: a #GDateTime * @tz: the new #GTimeZone * * Create a new #GDateTime corresponding to the same instant in time as * @datetime, but in the time zone @tz. * * This call can fail in the case that the time goes out of bounds. For * example, converting 0001-01-01 00:00:00 UTC to a time zone west of * Greenwich will fail (due to the year 0 being out of range). * * 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_to_unix: * @datetime: a #GDateTime * * Gives the Unix time corresponding to @datetime, rounding down to the * nearest second. * * Unix time is the number of seconds that have elapsed since 1970-01-01 * 00:00:00 UTC, regardless of the time zone associated with @datetime. * * Returns: the Unix time corresponding to @datetime * Since: 2.26 */ /** * g_date_time_to_utc: * @datetime: a #GDateTime * * Creates a new #GDateTime corresponding to the same instant in time as * @datetime, but in UTC. * * This call is equivalent to calling g_date_time_to_timezone() with the * time zone returned by g_time_zone_new_utc(). * * Returns: the newly created #GDateTime * Since: 2.26 */ /** * g_date_time_unref: * @datetime: a #GDateTime * * Atomically decrements the reference count of @datetime by one. * * When the reference count reaches zero, the resources allocated by * @datetime are freed * * Since: 2.26 */ /** * g_date_to_struct_tm: * @date: a #GDate to set the struct tm from * @tm: struct tm to fill * * Fills in the date-related bits of a struct tm using the @date value. * Initializes the non-date parts with something sane but meaningless. */ /** * g_date_valid: * @date: a #GDate to check * * Returns %TRUE if the #GDate represents an existing day. The date must not * contain garbage; it should have been initialized with g_date_clear() * if it wasn't allocated by one of the g_date_new() variants. * * Returns: Whether the date is valid */ /** * g_date_valid_day: * @day: day to check * * Returns %TRUE if the day of the month is valid (a day is valid if it's * between 1 and 31 inclusive). * * Returns: %TRUE if the day is valid */ /** * g_date_valid_dmy: * @day: day * @month: month * @year: year * * Returns %TRUE if the day-month-year triplet forms a valid, existing day * in the range of days #GDate understands (Year 1 or later, no more than * a few thousand years in the future). * * Returns: %TRUE if the date is a valid one */ /** * g_date_valid_julian: * @julian_date: Julian day to check * * Returns %TRUE if the Julian day is valid. Anything greater than zero * is basically a valid Julian, though there is a 32-bit limit. * * Returns: %TRUE if the Julian day is valid */ /** * g_date_valid_month: * @month: month * * Returns %TRUE if the month value is valid. The 12 #GDateMonth * enumeration values are the only valid months. * * Returns: %TRUE if the month is valid */ /** * g_date_valid_weekday: * @weekday: weekday * * Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration * values are the only valid weekdays. * * Returns: %TRUE if the weekday is valid */ /** * g_date_valid_year: * @year: year * * Returns %TRUE if the year is valid. Any year greater than 0 is valid, * though there is a 16-bit limit to what #GDate will understand. * * Returns: %TRUE if the year is valid */ /** * g_dcgettext: * @domain: (allow-none): the translation domain to use, or %NULL to use * the domain set with textdomain() * @msgid: message to translate * @category: a locale category * * This is a variant of g_dgettext() that allows specifying a locale * category instead of always using `LC_MESSAGES`. See g_dgettext() for * more information about how this functions differs from calling * dcgettext() directly. * * Returns: the translated string for the given locale category * Since: 2.26 */ /** * g_debug: * @...: format string, followed by parameters to insert * into the format string (as with printf()) * * A convenience function/macro to log a debug message. * * 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. * * Such messages are suppressed by the g_log_default_handler() unless * the G_MESSAGES_DEBUG environment variable is set appropriately. * * Since: 2.6 */ /** * g_dgettext: * @domain: (allow-none): the translation domain to use, or %NULL to use * the domain set with textdomain() * @msgid: message to translate * * This function is a wrapper of dgettext() which does not translate * the message if the default domain as set with textdomain() has no * translations for the current locale. * * The advantage of using this function over dgettext() proper is that * libraries using this function (like GTK+) will not use translations * if the application using the library does not have translations for * the current locale. This results in a consistent English-only * interface instead of one having partial translations. For this * feature to work, the call to textdomain() and setlocale() should * precede any g_dgettext() invocations. For GTK+, it means calling * textdomain() before gtk_init or its variants. * * This function disables translations if and only if upon its first * call all the following conditions hold: * * - @domain is not %NULL * * - textdomain() has been called to set a default text domain * * - there is no translations available for the default text domain * and the current locale * * - current locale is not "C" or any English locales (those * starting with "en_") * * Note that this behavior may not be desired for example if an application * has its untranslated messages in a language other than English. In those * cases the application should call textdomain() after initializing GTK+. * * Applications should normally not use this function directly, * but use the _() macro for translations. * * Returns: The translated string * Since: 2.18 */ /** * g_dir_close: * @dir: a #GDir* created by g_dir_open() * * Closes the directory and deallocates all related resources. */ /** * g_dir_make_tmp: * @tmpl: (type filename) (allow-none): Template for directory name, * as in g_mkdtemp(), basename only, or %NULL for a default template * @error: return location for a #GError * * Creates a subdirectory in the preferred directory for temporary * files (as returned by g_get_tmp_dir()). * * @tmpl should be a string in the GLib file name encoding containing * a sequence of six 'X' characters, as the parameter to g_mkstemp(). * However, unlike these functions, the template should only be a * basename, no directory components are allowed. If template is * %NULL, a default template is used. * * Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not * modified, and might thus be a read-only literal string. * * Returns: (type filename): The actual name used. This string * should be freed with g_free() when not needed any longer and is * is in the GLib file name encoding. In case of errors, %NULL is * returned and @error will be set. * Since: 2.30 */ /** * g_dir_open: * @path: the path to the directory you are interested in. On Unix * in the on-disk encoding. On Windows in UTF-8 * @flags: Currently must be set to 0. Reserved for future use. * @error: return location for a #GError, or %NULL. * If non-%NULL, an error will be set if and only if * g_dir_open() fails. * * Opens a directory for reading. The names of the files in the * directory can then be retrieved using g_dir_read_name(). Note * that the ordering is not defined. * * Returns: a newly allocated #GDir on success, %NULL on failure. * If non-%NULL, you must free the result with g_dir_close() * when you are finished with it. */ /** * g_dir_read_name: * @dir: a #GDir* created by g_dir_open() * * Retrieves the name of another entry in the directory, or %NULL. * The order of entries returned from this function is not defined, * and may vary by file system or other operating-system dependent * factors. * * %NULL may also be returned in case of errors. On Unix, you can * check `errno` to find out if %NULL was returned because of an error. * * On Unix, the '.' and '..' entries are omitted, and the returned * name is in the on-disk encoding. * * On Windows, as is true of all GLib functions which operate on * filenames, the returned name is in UTF-8. * * Returns: The entry's name or %NULL if there are no * more entries. The return value is owned by GLib and * must not be modified or freed. */ /** * g_dir_rewind: * @dir: a #GDir* created by g_dir_open() * * Resets the given directory. The next call to g_dir_read_name() * will return the first entry again. */ /** * g_direct_equal: * @v1: (allow-none): a key * @v2: (allow-none): a key to compare with @v1 * * Compares two #gpointer arguments and returns %TRUE if they are equal. * It can be passed to g_hash_table_new() as the @key_equal_func * parameter, when using opaque pointers compared by pointer value as * keys in a #GHashTable. * * This equality function is also appropriate for keys that are integers * stored in pointers, such as `GINT_TO_POINTER (n)`. * * Returns: %TRUE if the two keys match. */ /** * g_direct_hash: * @v: (allow-none): a #gpointer key * * Converts a gpointer to a hash value. * It can be passed to g_hash_table_new() as the @hash_func parameter, * when using opaque pointers compared by pointer value as keys in a * #GHashTable. * * This hash function is also appropriate for keys that are integers * stored in pointers, such as `GINT_TO_POINTER (n)`. * * Returns: a hash value corresponding to the key. */ /** * g_dirname: * @file_name: the name of the file * * Gets the directory components of a file name. * * If the file name has no directory components "." is returned. * The returned string should be freed when no longer needed. * * Returns: the directory components of the file * Deprecated: use g_path_get_dirname() instead */ /** * g_dngettext: * @domain: (allow-none): the translation domain to use, or %NULL to use * the domain set with textdomain() * @msgid: message to translate * @msgid_plural: plural form of the message * @n: the quantity for which translation is needed * * This function is a wrapper of dngettext() which does not translate * the message if the default domain as set with textdomain() has no * translations for the current locale. * * See g_dgettext() for details of how this differs from dngettext() * proper. * * Returns: The translated string * Since: 2.18 */ /** * g_double_equal: * @v1: a pointer to a #gdouble key * @v2: a pointer to a #gdouble key to compare with @v1 * * Compares the two #gdouble values being pointed to and returns * %TRUE if they are equal. * It can be passed to g_hash_table_new() as the @key_equal_func * parameter, when using non-%NULL pointers to doubles as keys in a * #GHashTable. * * Returns: %TRUE if the two keys match. * Since: 2.22 */ /** * g_double_hash: * @v: a pointer to a #gdouble key * * Converts a pointer to a #gdouble to a hash value. * It can be passed to g_hash_table_new() as the @hash_func parameter, * It can be passed to g_hash_table_new() as the @hash_func parameter, * when using non-%NULL pointers to doubles as keys in a #GHashTable. * * Returns: a hash value corresponding to the key. * Since: 2.22 */ /** * g_dpgettext: * @domain: (allow-none): the translation domain to use, or %NULL to use * the domain set with textdomain() * @msgctxtid: a combined message context and message id, separated * by a \004 character * @msgidoffset: the offset of the message id in @msgctxid * * This function is a variant of g_dgettext() which supports * a disambiguating message context. GNU gettext uses the * '\004' character to separate the message context and * message id in @msgctxtid. * If 0 is passed as @msgidoffset, this function will fall back to * trying to use the deprecated convention of using "|" as a separation * character. * * This uses g_dgettext() internally. See that functions for differences * with dgettext() proper. * * Applications should normally not use this function directly, * but use the C_() macro for translations with context. * * Returns: The translated string * Since: 2.16 */ /** * g_dpgettext2: * @domain: (allow-none): the translation domain to use, or %NULL to use * the domain set with textdomain() * @context: the message context * @msgid: the message * * This function is a variant of g_dgettext() which supports * a disambiguating message context. GNU gettext uses the * '\004' character to separate the message context and * message id in @msgctxtid. * * This uses g_dgettext() internally. See that functions for differences * with dgettext() proper. * * This function differs from C_() in that it is not a macro and * thus you may use non-string-literals as context and msgid arguments. * * Returns: The translated string * Since: 2.18 */ /** * g_environ_getenv: * @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment * list (eg, as returned from g_get_environ()), or %NULL * for an empty environment list * @variable: the environment variable to get, in the GLib file name * encoding * * Returns the value of the environment variable @variable in the * provided list @envp. * * Returns: the value of the environment variable, or %NULL if * the environment variable is not set in @envp. The returned * string is owned by @envp, and will be freed if @variable is * set or unset again. * Since: 2.32 */ /** * g_environ_setenv: * @envp: (allow-none) (array zero-terminated=1) (transfer full): an * environment list that can be freed using g_strfreev() (e.g., as * returned from g_get_environ()), or %NULL for an empty * environment list * @variable: the environment variable to set, must not contain '=' * @value: the value for to set the variable to * @overwrite: whether to change the variable if it already exists * * Sets the environment variable @variable in the provided list * @envp to @value. * * Returns: (array zero-terminated=1) (transfer full): the * updated environment list. Free it using g_strfreev(). * Since: 2.32 */ /** * g_environ_unsetenv: * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), * or %NULL for an empty environment list * @variable: the environment variable to remove, must not contain '=' * * Removes the environment variable @variable from the provided * environment @envp. * * Returns: (array zero-terminated=1) (transfer full): the * updated environment list. Free it using g_strfreev(). * Since: 2.32 */ /** * g_error: * @...: format string, followed by parameters to insert * into the format string (as with printf()) * * A convenience function/macro to log an error message. * * Error messages are always fatal, resulting in a call to * abort() to terminate the application. This function will * result in a core dump; don't use it for errors you expect. * Using this function indicates a bug in your program, i.e. * an assertion failure. * * 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. */ /** * g_error_copy: * @error: a #GError * * Makes a copy of @error. * * Returns: a new #GError */ /** * g_error_free: * @error: a #GError * * Frees a #GError and associated resources. */ /** * g_error_matches: * @error: (allow-none): a #GError or %NULL * @domain: an error domain * @code: an error code * * Returns %TRUE if @error matches @domain and @code, %FALSE * otherwise. In particular, when @error is %NULL, %FALSE will * be returned. * * If @domain contains a `FAILED` (or otherwise generic) error code, * you should generally not check for it explicitly, but should * instead treat any not-explicitly-recognized error code as being * equilalent to the `FAILED` code. This way, if the domain is * extended in the future to provide a more specific error code for * a certain case, your code will still work. * * Returns: whether @error has @domain and @code */ /** * g_error_new: * @domain: error domain * @code: error code * @format: printf()-style format for error message * @...: parameters for message format * * Creates a new #GError with the given @domain and @code, * and a message formatted with @format. * * Returns: a new #GError */ /** * g_error_new_literal: * @domain: error domain * @code: error code * @message: error message * * Creates a new #GError; unlike g_error_new(), @message is * not a printf()-style format string. Use this function if * @message contains text you don't have control over, * that could include printf() escape sequences. * * Returns: a new #GError */ /** * g_error_new_valist: * @domain: error domain * @code: error code * @format: printf()-style format for error message * @args: #va_list of parameters for the message format * * Creates a new #GError with the given @domain and @code, * and a message formatted with @format. * * Returns: a new #GError * Since: 2.22 */ /** * g_file_error_from_errno: * @err_no: an "errno" value * * Gets a #GFileError constant based on the passed-in @err_no. * For example, if you pass in `EEXIST` this function returns * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably * assume that all #GFileError values will exist. * * Normally a #GFileError value goes into a #GError returned * from a function that manipulates files. So you would use * g_file_error_from_errno() when constructing a #GError. * * Returns: #GFileError corresponding to the given @errno */ /** * g_file_get_contents: * @filename: (type filename): name of a file to read contents from, in the GLib file name encoding * @contents: (out) (array length=length) (element-type guint8): location to store an allocated string, use g_free() to free * the returned string * @length: (allow-none): location to store length in bytes of the contents, or %NULL * @error: return location for a #GError, or %NULL * * Reads an entire file into allocated memory, with good error * checking. * * If the call was successful, it returns %TRUE and sets @contents to the file * contents and @length to the length of the file contents in bytes. The string * stored in @contents will be nul-terminated, so for text files you can pass * %NULL for the @length argument. If the call was not successful, it returns * %FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error * codes are those in the #GFileError enumeration. In the error case, * @contents is set to %NULL and @length is set to zero. * * Returns: %TRUE on success, %FALSE if an error occurred */ /** * g_file_open_tmp: * @tmpl: (type filename) (allow-none): Template for file name, as in * g_mkstemp(), basename only, or %NULL for a default template * @name_used: (out) (type filename): location to store actual name used, * or %NULL * @error: return location for a #GError * * Opens a file for writing in the preferred directory for temporary * files (as returned by g_get_tmp_dir()). * * @tmpl should be a string in the GLib file name encoding containing * a sequence of six 'X' characters, as the parameter to g_mkstemp(). * However, unlike these functions, the template should only be a * basename, no directory components are allowed. If template is * %NULL, a default template is used. * * Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not * modified, and might thus be a read-only literal string. * * Upon success, and if @name_used is non-%NULL, the actual name used * is returned in @name_used. This string should be freed with g_free() * when not needed any longer. The returned name is in the GLib file * name encoding. * * Returns: A file handle (as from open()) to the file opened for * reading and writing. The file is opened in binary mode on platforms * where there is a difference. The file handle should be closed with * close(). In case of errors, -1 is returned and @error will be set. */ /** * g_file_read_link: * @filename: the symbolic link * @error: return location for a #GError * * Reads the contents of the symbolic link @filename like the POSIX * readlink() function. The returned string is in the encoding used * for filenames. Use g_filename_to_utf8() to convert it to UTF-8. * * Returns: A newly-allocated string with the contents of the symbolic link, * or %NULL if an error occurred. * Since: 2.4 */ /** * g_file_set_contents: * @filename: (type filename): name of a file to write @contents to, in the GLib file name * encoding * @contents: (array length=length) (element-type guint8): string to write to the file * @length: length of @contents, or -1 if @contents is a nul-terminated string * @error: return location for a #GError, or %NULL * * Writes all of @contents to a file named @filename, with good error checking. * If a file called @filename already exists it will be overwritten. * * This write is atomic in the sense that it is first written to a temporary * file which is then renamed to the final name. Notes: * * - On UNIX, if @filename already exists hard links to @filename will break. * Also since the file is recreated, existing permissions, access control * lists, metadata etc. may be lost. If @filename is a symbolic link, * the link itself will be replaced, not the linked file. * * - On Windows renaming a file will not remove an existing file with the * new name, so on Windows there is a race condition between the existing * file being removed and the temporary file being renamed. * * - On Windows there is no way to remove a file that is open to some * process, or mapped into memory. Thus, this function will fail if * @filename already exists and is open. * * If the call was successful, it returns %TRUE. If the call was not successful, * it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR. * Possible error codes are those in the #GFileError enumeration. * * Note that the name for the temporary file is constructed by appending up * to 7 characters to @filename. * * Returns: %TRUE on success, %FALSE if an error occurred * Since: 2.8 */ /** * g_file_test: * @filename: a filename to test in the GLib file name encoding * @test: bitfield of #GFileTest flags * * Returns %TRUE if any of the tests in the bitfield @test are * %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` * will return %TRUE if the file exists; the check whether it's a * directory doesn't matter since the existence test is %TRUE. With * the current set of available tests, there's no point passing in * more than one test at a time. * * Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links, * so for a symbolic link to a regular file g_file_test() will return * %TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR. * * Note, that for a dangling symbolic link g_file_test() will return * %TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags. * * You should never use g_file_test() to test whether it is safe * to perform an operation, because there is always the possibility * of the condition changing before you actually perform the operation. * For example, you might think you could use %G_FILE_TEST_IS_SYMLINK * to know whether it is safe to write to a file without being * tricked into writing into a different location. It doesn't work! * |[ * // DON'T DO THIS * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) * { * fd = g_open (filename, O_WRONLY); * // write to fd * } * ]| * * Another thing to note is that %G_FILE_TEST_EXISTS and * %G_FILE_TEST_IS_EXECUTABLE are implemented using the access() * system call. This usually doesn't matter, but if your program * is setuid or setgid it means that these tests will give you * the answer for the real user ID and group ID, rather than the * effective user ID and group ID. * * On Windows, there are no symlinks, so testing for * %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for * %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and * its name indicates that it is executable, checking for well-known * extensions and those listed in the `PATHEXT` environment variable. * * Returns: whether a test was %TRUE */ /** * g_filename_display_basename: * @filename: an absolute pathname in the GLib file name encoding * * Returns the display basename for the particular filename, guaranteed * to be valid UTF-8. The display name might not be identical to the filename, * for instance there might be problems converting it to UTF-8, and some files * can be translated in the display. * * If GLib cannot make sense of the encoding of @filename, as a last resort it * replaces unknown characters with U+FFFD, the Unicode replacement character. * You can search the result for the UTF-8 encoding of this character (which is * "\357\277\275" in octal notation) to find out if @filename was in an invalid * encoding. * * You must pass the whole absolute pathname to this functions so that * translation of well known locations can be done. * * This function is preferred over g_filename_display_name() if you know the * whole path, as it allows translation. * * Returns: a newly allocated string containing * a rendition of the basename of the filename in valid UTF-8 * Since: 2.6 */ /** * g_filename_display_name: * @filename: a pathname hopefully in the GLib file name encoding * * Converts a filename into a valid UTF-8 string. The conversion is * not necessarily reversible, so you should keep the original around * and use the return value of this function only for display purposes. * Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL * even if the filename actually isn't in the GLib file name encoding. * * If GLib cannot make sense of the encoding of @filename, as a last resort it * replaces unknown characters with U+FFFD, the Unicode replacement character. * You can search the result for the UTF-8 encoding of this character (which is * "\357\277\275" in octal notation) to find out if @filename was in an invalid * encoding. * * If you know the whole pathname of the file you should use * g_filename_display_basename(), since that allows location-based * translation of filenames. * * Returns: a newly allocated string containing * a rendition of the filename in valid UTF-8 * Since: 2.6 */ /** * g_filename_from_uri: * @uri: a uri describing a filename (escaped, encoded in ASCII). * @hostname: (out) (allow-none): Location to store hostname for the URI, or %NULL. * If there is no hostname in the URI, %NULL will be * stored in this location. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * * Converts an escaped ASCII-encoded URI to a local filename in the * encoding used for filenames. * * Returns: (type filename): a newly-allocated string holding * the resulting filename, or %NULL on an error. */ /** * g_filename_from_utf8: * @utf8string: a UTF-8 encoded string. * @len: the length of the string, or -1 if the string is * nul-terminated. * @bytes_read: (out) (allow-none): 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): 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 UTF-8 to the encoding GLib uses for * filenames. Note that on Windows GLib uses UTF-8 for filenames; * on other platforms, this function indirectly depends on the * [current locale][setlocale]. * * Returns: (array length=bytes_written) (element-type guint8) (transfer full): * The converted string, or %NULL on an error. */ /** * g_filename_to_uri: * @filename: an absolute filename specified in the GLib file name encoding, * which is the on-disk file name bytes on Unix, and UTF-8 on * Windows * @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * * Converts an absolute filename to an escaped ASCII-encoded URI, with the path * component following Section 3.3. of RFC 2396. * * Returns: a newly-allocated string holding the resulting * URI, or %NULL on an error. */ /** * g_filename_to_utf8: * @opsysstring: a string in the encoding for filenames * @len: the length of the string, 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) * @bytes_read: 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: 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 which is in the encoding used by GLib for * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 * for filenames; on other platforms, this function indirectly depends on * the [current locale][setlocale]. * * Returns: The converted string, or %NULL on an error. */ /** * g_find_program_in_path: * @program: a program name in the GLib file name encoding * * Locates the first executable named @program in the user's path, in the * same way that execvp() would locate it. Returns an allocated string * with the absolute path name, or %NULL if the program is not found in * the path. If @program is already an absolute path, returns a copy of * @program if @program exists and is executable, and %NULL otherwise. * * On Windows, if @program does not have a file type suffix, tries * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in * the `PATHEXT` environment variable. * * On Windows, it looks for the file in the same way as CreateProcess() * would. This means first in the directory where the executing * program was loaded from, then in the current directory, then in the * Windows 32-bit system directory, then in the Windows directory, and * finally in the directories in the `PATH` environment variable. If * the program is found, the return value contains the full name * including the type suffix. * * Returns: a newly-allocated string with the absolute path, or %NULL */ /** * g_fopen: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * @mode: a string describing the mode in which the file should be opened * * A wrapper for the stdio fopen() function. The fopen() function * opens a file and associates a new stream with it. * * Because file descriptors are specific to the C library on Windows, * and a file descriptor is part of the FILE struct, the FILE* 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* returned by this function cannot be passed to C library * functions like fprintf() or fread(). * * See your C library manual for more details about fopen(). * * Returns: A FILE* if the file was successfully opened, or %NULL if * an error occurred * Since: 2.6 */ /** * g_format_size: * @size: a size in bytes * * Formats a size (for example the size of a file) into a human readable * string. Sizes are rounded to the nearest size prefix (kB, MB, GB) * and are displayed rounded to the nearest tenth. E.g. the file size * 3292528 bytes will be converted into the string "3.2 MB". * * The prefix units base is 1000 (i.e. 1 kB is 1000 bytes). * * This string should be freed with g_free() when not needed any longer. * * See g_format_size_full() for more options about how the size might be * formatted. * * Returns: a newly-allocated formatted string containing a human readable * file size * Since: 2.30 */ /** * g_format_size_for_display: * @size: a size in bytes * * Formats a size (for example the size of a file) into a human * readable string. Sizes are rounded to the nearest size prefix * (KB, MB, GB) and are displayed rounded to the nearest tenth. * E.g. the file size 3292528 bytes will be converted into the * string "3.1 MB". * * The prefix units base is 1024 (i.e. 1 KB is 1024 bytes). * * This string should be freed with g_free() when not needed any longer. * * Returns: a newly-allocated formatted string containing a human * readable file size * Since: 2.16 * Deprecated: 2.30: This function is broken due to its use of SI * suffixes to denote IEC units. Use g_format_size() instead. */ /** * g_format_size_full: * @size: a size in bytes * @flags: #GFormatSizeFlags to modify the output * * Formats a size. * * This function is similar to g_format_size() but allows for flags * that modify the output. See #GFormatSizeFlags. * * Returns: a newly-allocated formatted string containing a human * readable file size * Since: 2.30 */ /** * g_fprintf: * @file: the stream to write to. * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard fprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * * Returns: the number of bytes printed. * Since: 2.2 */ /** * g_free: * @mem: (allow-none): the memory to free * * Frees the memory pointed to by @mem. * If @mem is %NULL it simply returns. */ /** * g_freopen: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * @mode: a string describing the mode in which the file should be opened * @stream: (allow-none): an existing stream which will be reused, or %NULL * * A wrapper for the POSIX freopen() function. The freopen() function * opens a file and associates it with an existing stream. * * See your C library manual for more details about freopen(). * * Returns: A FILE* if the file was successfully opened, or %NULL if * an error occurred. * Since: 2.6 */ /** * g_get_application_name: * * Gets a human-readable name for the application, as set by * g_set_application_name(). This name should be localized if * possible, and is intended for display to the user. Contrast with * g_get_prgname(), which gets a non-localized name. If * g_set_application_name() has not been called, returns the result of * g_get_prgname() (which may be %NULL if g_set_prgname() has also not * been called). * * Returns: human-readable application name. may return %NULL * Since: 2.2 */ /** * g_get_charset: * @charset: return location for character set name * * Obtains the character set for the [current locale][setlocale]; you * might use this character set as an argument to g_convert(), to convert * from the current locale's encoding to some other encoding. (Frequently * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.) * * On Windows the character set returned by this function is the * so-called system default ANSI code-page. That is the character set * used by the "narrow" versions of C library and Win32 functions that * handle file names. It might be different from the character set * used by the C library's current locale. * * The return value is %TRUE if the locale's encoding is UTF-8, in that * case you can perhaps avoid calling g_convert(). * * The string returned in @charset is not allocated, and should not be * freed. * * Returns: %TRUE if the returned charset is UTF-8 */ /** * g_get_codeset: * * Gets the character set for the current locale. * * Returns: a newly allocated string containing the name * of the character set. This string must be freed with g_free(). */ /** * g_get_current_dir: * * Gets the current directory. * * The returned string should be freed when no longer needed. * The encoding of the returned string is system defined. * On Windows, it is always UTF-8. * * Since GLib 2.40, this function will return the value of the "PWD" * environment variable if it is set and it happens to be the same as * the current directory. This can make a difference in the case that * the current directory is the target of a symbolic link. * * Returns: the current directory */ /** * g_get_current_time: * @result: #GTimeVal structure in which to store current time. * * Equivalent to the UNIX gettimeofday() function, but portable. * * You may find g_get_real_time() to be more convenient. */ /** * g_get_environ: * * Gets the list of environment variables for the current process. * * The list is %NULL terminated and each item in the list is of the * form 'NAME=VALUE'. * * This is equivalent to direct access to the 'environ' global variable, * except portable. * * The return value is freshly allocated and it should be freed with * g_strfreev() when it is no longer needed. * * Returns: (array zero-terminated=1) (transfer full): the list of * environment variables * Since: 2.28 */ /** * g_get_filename_charsets: * @charsets: return location for the %NULL-terminated list of encoding names * * Determines the preferred character sets used for filenames. * The first character set from the @charsets is the filename encoding, the * subsequent character sets are used when trying to generate a displayable * representation of a filename, see g_filename_display_name(). * * On Unix, the character sets are determined by consulting the * environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`. * On Windows, the character set used in the GLib API is always UTF-8 * and said environment variables have no effect. * * `G_FILENAME_ENCODING` may be set to a comma-separated list of * character set names. The special token "@locale" is taken * to mean the character set for the [current locale][setlocale]. * If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is, * the character set of the current locale is taken as the filename * encoding. If neither environment variable is set, UTF-8 is taken * as the filename encoding, but the character set of the current locale * is also put in the list of encodings. * * The returned @charsets belong to GLib and must not be freed. * * Note that on Unix, regardless of the locale character set or * `G_FILENAME_ENCODING` value, the actual file names present * on a system might be in any random encoding or just gibberish. * * Returns: %TRUE if the filename encoding is UTF-8. * Since: 2.6 */ /** * g_get_home_dir: * * Gets the current user's home directory. * * As with most UNIX tools, this function will return the value of the * `HOME` environment variable if it is set to an existing absolute path * name, falling back to the `passwd` file in the case that it is unset. * * If the path given in `HOME` is non-absolute, does not exist, or is * not a directory, the result is undefined. * * Before version 2.36 this function would ignore the `HOME` environment * variable, taking the value from the `passwd` database instead. This was * changed to increase the compatibility of GLib with other programs (and * the XDG basedir specification) and to increase testability of programs * based on GLib (by making it easier to run them from test frameworks). * * If your program has a strong requirement for either the new or the * old behaviour (and if you don't wish to increase your GLib * dependency to ensure that the new behaviour is in effect) then you * should either directly check the `HOME` environment variable yourself * or unset it before calling any functions in GLib. * * Returns: the current user's home directory */ /** * g_get_host_name: * * Return a name for the machine. * * The returned name is not necessarily a fully-qualified domain name, * or even present in DNS or some other name service at all. It need * not even be unique on your local network or site, but usually it * is. Callers should not rely on the return value having any specific * properties like uniqueness for security purposes. Even if the name * of the machine is changed while an application is running, the * return value from this function does not change. The returned * string is owned by GLib and should not be modified or freed. If no * name can be determined, a default fixed string "localhost" is * returned. * * Returns: the host name of the machine. * Since: 2.8 */ /** * g_get_language_names: * * Computes a list of applicable locale names, which can be used to * e.g. construct locale-dependent filenames or search paths. The returned * list is sorted from most desirable to least desirable and always contains * the default locale "C". * * For example, if LANGUAGE=de:en_US, then the returned list is * "de", "en_US", "en", "C". * * This function consults the environment variables `LANGUAGE`, `LC_ALL`, * `LC_MESSAGES` and `LANG` to find the list of locales specified by the * user. * * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib * that must not be modified or freed. * Since: 2.6 */ /** * g_get_locale_variants: * @locale: a locale identifier * * Returns a list of derived variants of @locale, which can be used to * e.g. construct locale-dependent filenames or search paths. The returned * list is sorted from most desirable to least desirable. * This function handles territory, charset and extra locale modifiers. * * For example, if @locale is "fr_BE", then the returned list * is "fr_BE", "fr". * * If you need the list of variants for the current locale, * use g_get_language_names(). * * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly * allocated array of newly allocated strings with the locale variants. Free with * g_strfreev(). * Since: 2.28 */ /** * g_get_monotonic_time: * * Queries the system monotonic time. * * The monotonic clock will always increase and doesn't suffer * discontinuities when the user (or NTP) changes the system time. It * may or may not continue to tick during times where the machine is * suspended. * * We try to use the clock that corresponds as closely as possible to * the passage of time as measured by system calls such as poll() but it * may not always be possible to do this. * * Returns: the monotonic time, in microseconds * Since: 2.28 */ /** * g_get_num_processors: * * Determine the approximate number of threads that the system will * schedule simultaneously for this process. This is intended to be * used as a parameter to g_thread_pool_new() for CPU bound tasks and * similar cases. * * Returns: Number of schedulable threads, always greater than 0 * Since: 2.36 */ /** * g_get_prgname: * * Gets the name of the program. This name should not be localized, * in contrast to g_get_application_name(). * * If you are using GDK or GTK+ the program name is set in gdk_init(), * which is called by gtk_init(). The program name is found by taking * the last component of @argv[0]. * * Returns: the name of the program. The returned string belongs * to GLib and must not be modified or freed. */ /** * g_get_real_name: * * Gets the real name of the user. This usually comes from the user's * entry in the `passwd` file. The encoding of the returned string is * system-defined. (On Windows, it is, however, always UTF-8.) If the * real user name cannot be determined, the string "Unknown" is * returned. * * Returns: the user's real name. */ /** * g_get_real_time: * * Queries the system wall-clock time. * * This call is functionally equivalent to g_get_current_time() except * that the return value is often more convenient than dealing with a * #GTimeVal. * * You should only use this call if you are actually interested in the real * wall-clock time. g_get_monotonic_time() is probably more useful for * measuring intervals. * * Returns: the number of microseconds since January 1, 1970 UTC. * Since: 2.28 */ /** * g_get_system_config_dirs: * * Returns an ordered list of base directories in which to access * system-wide configuration information. * * On UNIX platforms this is determined using the mechanisms described * in the * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). * In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`. * * On Windows is the directory that contains application data for all users. * A typical path is C:\Documents and Settings\All Users\Application Data. * This folder is used for application data that is not user specific. * For example, an application can store a spell-check dictionary, a database * of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. * This information will not roam and is available to anyone using the computer. * * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must * not be modified or freed. * Since: 2.6 */ /** * g_get_system_data_dirs: * * Returns an ordered list of base directories in which to access * system-wide application data. * * On UNIX platforms this is determined using the mechanisms described * in the * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec) * In this case the list of directories retrieved will be XDG_DATA_DIRS. * * On Windows the first elements in the list are the Application Data * and Documents folders for All Users. (These can be determined only * on Windows 2000 or later and are not present in the list on other * Windows versions.) See documentation for CSIDL_COMMON_APPDATA and * CSIDL_COMMON_DOCUMENTS. * * Then follows the "share" subfolder in the installation folder for * the package containing the DLL that calls this function, if it can * be determined. * * Finally the list contains the "share" subfolder in the installation * folder for GLib, and in the installation folder for the package the * application's .exe file belongs to. * * The installation folders above are determined by looking up the * folder where the module (DLL or EXE) in question is located. If the * folder's name is "bin", its parent is used, otherwise the folder * itself. * * Note that on Windows the returned list can vary depending on where * this function is called. * * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must * not be modified or freed. * Since: 2.6 */ /** * g_get_tmp_dir: * * Gets the directory to use for temporary files. * * On UNIX, this is taken from the `TMPDIR` environment variable. * If the variable is not set, `P_tmpdir` is * used, as defined by the system C library. Failing that, a * hard-coded default of "/tmp" is returned. * * On Windows, the `TEMP` environment variable is used, with the * root directory of the Windows installation (eg: "C:\") used * as a default. * * The encoding of the returned string is system-defined. On Windows, * it is always UTF-8. The return value is never %NULL or the empty * string. * * Returns: the directory to use for temporary files. */ /** * g_get_user_cache_dir: * * Returns a base directory in which to store non-essential, cached * data specific to particular user. * * On UNIX platforms this is determined using the mechanisms described * in the * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). * In this case the directory retrieved will be XDG_CACHE_HOME. * * On Windows is the directory that serves as a common repository for * temporary Internet files. A typical path is * C:\Documents and Settings\username\Local Settings\Temporary Internet Files. * See documentation for CSIDL_INTERNET_CACHE. * * Returns: a string owned by GLib that must not be modified * or freed. * Since: 2.6 */ /** * g_get_user_config_dir: * * Returns a base directory in which to store user-specific application * configuration information such as user preferences and settings. * * On UNIX platforms this is determined using the mechanisms described * in the * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). * In this case the directory retrieved will be `XDG_CONFIG_HOME`. * * On Windows this is the folder to use for local (as opposed to * roaming) application data. See documentation for * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as * what g_get_user_data_dir() returns. * * Returns: a string owned by GLib that must not be modified * or freed. * Since: 2.6 */ /** * g_get_user_data_dir: * * Returns a base directory in which to access application data such * as icons that is customized for a particular user. * * On UNIX platforms this is determined using the mechanisms described * in the * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). * In this case the directory retrieved will be `XDG_DATA_HOME`. * * On Windows this is the folder to use for local (as opposed to * roaming) application data. See documentation for * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as * what g_get_user_config_dir() returns. * * Returns: a string owned by GLib that must not be modified * or freed. * Since: 2.6 */ /** * g_get_user_name: * * Gets the user name of the current user. The encoding of the returned * string is system-defined. On UNIX, it might be the preferred file name * encoding, or something else, and there is no guarantee that it is even * consistent on a machine. On Windows, it is always UTF-8. * * Returns: the user name of the current user. */ /** * g_get_user_runtime_dir: * * Returns a directory that is unique to the current user on the local * system. * * On UNIX platforms this is determined using the mechanisms described * in the * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). * This is the directory * specified in the `XDG_RUNTIME_DIR` environment variable. * In the case that this variable is not set, GLib will issue a warning * message to stderr and return the value of g_get_user_cache_dir(). * * On Windows this is the folder to use for local (as opposed to * roaming) application data. See documentation for * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as * what g_get_user_config_dir() returns. * * Returns: a string owned by GLib that must not be modified or freed. * Since: 2.28 */ /** * g_get_user_special_dir: * @directory: the logical id of special directory * * Returns the full path of a special directory using its logical id. * * On UNIX this is done using the XDG special user directories. * For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP * falls back to `$HOME/Desktop` when XDG special user directories have * not been set up. * * Depending on the platform, the user might be able to change the path * of the special directory without requiring the session to restart; GLib * will not reflect any change once the special directories are loaded. * * Returns: the path to the specified special directory, or %NULL * if the logical id was not found. The returned string is owned by * GLib and should not be modified or freed. * Since: 2.14 */ /** * g_getenv: * @variable: the environment variable to get, in the GLib file name * encoding * * Returns the value of an environment variable. * * The name and value are in the GLib file name encoding. On UNIX, * this means the actual bytes which might or might not be in some * consistent character set and encoding. On Windows, it is in UTF-8. * On Windows, in case the environment variable's value contains * references to other environment variables, they are expanded. * * Returns: the value of the environment variable, or %NULL if * the environment variable is not found. The returned string * may be overwritten by the next call to g_getenv(), g_setenv() * or g_unsetenv(). */ /** * g_hash_table_add: * @hash_table: a #GHashTable * @key: a key to insert * * This is a convenience function for using a #GHashTable as a set. It * is equivalent to calling g_hash_table_replace() with @key as both the * key and the value. * * When a hash table only ever contains keys that have themselves as the * corresponding value it is able to be stored more efficiently. See * the discussion in the section description. * * Returns: %TRUE if the key did not exist yet * Since: 2.32 */ /** * g_hash_table_contains: * @hash_table: a #GHashTable * @key: a key to check * * Checks if @key is in @hash_table. * * Since: 2.32 */ /** * g_hash_table_destroy: * @hash_table: a #GHashTable * * Destroys all keys and values in the #GHashTable and decrements its * reference count by 1. If keys and/or values are dynamically allocated, * you should either free them first or create the #GHashTable with destroy * notifiers using g_hash_table_new_full(). In the latter case the destroy * functions you supplied will be called on all keys and values during the * destruction phase. */ /** * g_hash_table_find: * @hash_table: a #GHashTable * @predicate: function to test the key/value pairs for a certain property * @user_data: user data to pass to the function * * Calls the given function for key/value pairs in the #GHashTable * until @predicate returns %TRUE. The function is passed the key * and value of each pair, and the given @user_data parameter. The * hash table may not be modified while iterating over it (you can't * add/remove items). * * Note, that hash tables are really only optimized for forward * lookups, i.e. g_hash_table_lookup(). So code that frequently issues * g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of * once per every entry in a hash table) should probably be reworked * to use additional or different data structures for reverse lookups * (keep in mind that an O(n) find/foreach operation issued for all n * values in a hash table ends up needing O(n*n) operations). * * Returns: (allow-none): The value of the first key/value pair is returned, * for which @predicate evaluates to %TRUE. If no pair with the * requested property is found, %NULL is returned. * Since: 2.4 */ /** * g_hash_table_foreach: * @hash_table: a #GHashTable * @func: the function to call for each key/value pair * @user_data: user data to pass to the function * * Calls the given function for each of the key/value pairs in the * #GHashTable. The function is passed the key and value of each * pair, and the given @user_data parameter. The hash table may not * be modified while iterating over it (you can't add/remove * items). To remove all items matching a predicate, use * g_hash_table_foreach_remove(). * * See g_hash_table_find() for performance caveats for linear * order searches in contrast to g_hash_table_lookup(). */ /** * g_hash_table_foreach_remove: * @hash_table: a #GHashTable * @func: the function to call for each key/value pair * @user_data: user data to pass to the function * * Calls the given function for each key/value pair in the * #GHashTable. If the function returns %TRUE, then the key/value * pair is removed from the #GHashTable. If you supplied key or * value destroy functions when creating the #GHashTable, they are * used to free the memory allocated for the removed keys and values. * * See #GHashTableIter for an alternative way to loop over the * key/value pairs in the hash table. * * Returns: the number of key/value pairs removed */ /** * g_hash_table_foreach_steal: * @hash_table: a #GHashTable * @func: the function to call for each key/value pair * @user_data: user data to pass to the function * * Calls the given function for each key/value pair in the * #GHashTable. If the function returns %TRUE, then the key/value * pair is removed from the #GHashTable, but no key or value * destroy functions are called. * * See #GHashTableIter for an alternative way to loop over the * key/value pairs in the hash table. * * Returns: the number of key/value pairs removed. */ /** * g_hash_table_freeze: * @hash_table: a #GHashTable * * This function is deprecated and will be removed in the next major * release of GLib. It does nothing. */ /** * g_hash_table_get_keys: * @hash_table: a #GHashTable * * Retrieves every key inside @hash_table. The returned data is valid * until changes to the hash release those keys. * * Returns: a #GList containing all the keys inside the hash * table. The content of the list is owned by the hash table and * should not be modified or freed. Use g_list_free() when done * using the list. * Since: 2.14 */ /** * g_hash_table_get_keys_as_array: * @hash_table: a #GHashTable * @length: (out): the length of the returned array * * Retrieves every key inside @hash_table, as an array. * * The returned array is %NULL-terminated but may contain %NULL as a * key. Use @length to determine the true length if it's possible that * %NULL was used as the value for a key. * * Note: in the common case of a string-keyed #GHashTable, the return * value of this function can be conveniently cast to (gchar **). * * You should always free the return result with g_free(). In the * above-mentioned case of a string-keyed hash table, it may be * appropriate to use g_strfreev() if you call g_hash_table_steal_all() * first to transfer ownership of the keys. * * Returns: (array length=length) (transfer container): a * %NULL-terminated array containing each key from the table. * Since: 2.40 */ /** * g_hash_table_get_values: * @hash_table: a #GHashTable * * Retrieves every value inside @hash_table. The returned data * is valid until @hash_table is modified. * * Returns: a #GList containing all the values inside the hash * table. The content of the list is owned by the hash table and * should not be modified or freed. Use g_list_free() when done * using the list. * Since: 2.14 */ /** * g_hash_table_insert: * @hash_table: a #GHashTable * @key: a key to insert * @value: the value to associate with the key * * Inserts a new key and value into a #GHashTable. * * If the key already exists in the #GHashTable its current * value is replaced with the new value. If you supplied a * @value_destroy_func when creating the #GHashTable, the old * value is freed using that function. If you supplied a * @key_destroy_func when creating the #GHashTable, the passed * key is freed using that function. * * Returns: %TRUE if the key did not exist yet */ /** * g_hash_table_iter_get_hash_table: * @iter: an initialized #GHashTableIter * * Returns the #GHashTable associated with @iter. * * Returns: the #GHashTable associated with @iter. * Since: 2.16 */ /** * g_hash_table_iter_init: * @iter: an uninitialized #GHashTableIter * @hash_table: a #GHashTable * * Initializes a key/value pair iterator and associates it with * @hash_table. Modifying the hash table after calling this function * invalidates the returned iterator. * |[ * GHashTableIter iter; * gpointer key, value; * * g_hash_table_iter_init (&iter, hash_table); * while (g_hash_table_iter_next (&iter, &key, &value)) * { * // do something with key and value * } * ]| * * Since: 2.16 */ /** * g_hash_table_iter_next: * @iter: an initialized #GHashTableIter * @key: (allow-none): a location to store the key, or %NULL * @value: (allow-none): a location to store the value, or %NULL * * Advances @iter and retrieves the key and/or value that are now * pointed to as a result of this advancement. If %FALSE is returned, * @key and @value are not set, and the iterator becomes invalid. * * Returns: %FALSE if the end of the #GHashTable has been reached. * Since: 2.16 */ /** * g_hash_table_iter_remove: * @iter: an initialized #GHashTableIter * * Removes the key/value pair currently pointed to by the iterator * from its associated #GHashTable. Can only be called after * g_hash_table_iter_next() returned %TRUE, and cannot be called * more than once for the same key/value pair. * * If the #GHashTable was created using g_hash_table_new_full(), * the key and value are freed using the supplied destroy functions, * otherwise you have to make sure that any dynamically allocated * values are freed yourself. * * It is safe to continue iterating the #GHashTable afterward: * |[ * while (g_hash_table_iter_next (&iter, &key, &value)) * { * if (condition) * g_hash_table_iter_remove (&iter); * } * ]| * * Since: 2.16 */ /** * g_hash_table_iter_replace: * @iter: an initialized #GHashTableIter * @value: the value to replace with * * Replaces the value currently pointed to by the iterator * from its associated #GHashTable. Can only be called after * g_hash_table_iter_next() returned %TRUE. * * If you supplied a @value_destroy_func when creating the * #GHashTable, the old value is freed using that function. * * Since: 2.30 */ /** * g_hash_table_iter_steal: * @iter: an initialized #GHashTableIter * * Removes the key/value pair currently pointed to by the * iterator from its associated #GHashTable, without calling * the key and value destroy functions. Can only be called * after g_hash_table_iter_next() returned %TRUE, and cannot * be called more than once for the same key/value pair. * * Since: 2.16 */ /** * g_hash_table_lookup: * @hash_table: a #GHashTable * @key: the key to look up * * Looks up a key in a #GHashTable. Note that this function cannot * distinguish between a key that is not present and one which is present * and has the value %NULL. If you need this distinction, use * g_hash_table_lookup_extended(). * * Returns: (allow-none): the associated value, or %NULL if the key is not found */ /** * g_hash_table_lookup_extended: * @hash_table: a #GHashTable * @lookup_key: the key to look up * @orig_key: (allow-none): return location for the original key, or %NULL * @value: (allow-none): return location for the value associated with the key, or %NULL * * Looks up a key in the #GHashTable, returning the original key and the * associated value and a #gboolean which is %TRUE if the key was found. This * is useful if you need to free the memory allocated for the original key, * for example before calling g_hash_table_remove(). * * You can actually pass %NULL for @lookup_key to test * whether the %NULL key exists, provided the hash and equal functions * of @hash_table are %NULL-safe. * * Returns: %TRUE if the key was found in the #GHashTable */ /** * g_hash_table_new: * @hash_func: a function to create a hash value from a key * @key_equal_func: a function to check two keys for equality * * Creates a new #GHashTable with a reference count of 1. * * Hash values returned by @hash_func are used to determine where keys * are stored within the #GHashTable data structure. The g_direct_hash(), * g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash() * functions are provided for some common types of keys. * If @hash_func is %NULL, g_direct_hash() is used. * * @key_equal_func is used when looking up keys in the #GHashTable. * The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal() * and g_str_equal() functions are provided for the most common types * of keys. If @key_equal_func is %NULL, keys are compared directly in * a similar fashion to g_direct_equal(), but without the overhead of * a function call. * * Returns: a new #GHashTable */ /** * g_hash_table_new_full: * @hash_func: a function to create a hash value from a key * @key_equal_func: a function to check two keys for equality * @key_destroy_func: (allow-none): a function to free the memory allocated for the key * used when removing the entry from the #GHashTable, or %NULL * if you don't want to supply such a function. * @value_destroy_func: (allow-none): a function to free the memory allocated for the * value used when removing the entry from the #GHashTable, or %NULL * if you don't want to supply such a function. * * Creates a new #GHashTable like g_hash_table_new() with a reference * count of 1 and allows to specify functions to free the memory * allocated for the key and value that get called when removing the * entry from the #GHashTable. * * Returns: a new #GHashTable */ /** * g_hash_table_ref: * @hash_table: a valid #GHashTable * * Atomically increments the reference count of @hash_table by one. * This function is MT-safe and may be called from any thread. * * Returns: the passed in #GHashTable * Since: 2.10 */ /** * g_hash_table_remove: * @hash_table: a #GHashTable * @key: the key to remove * * Removes a key and its associated value from a #GHashTable. * * If the #GHashTable was created using g_hash_table_new_full(), the * key and value are freed using the supplied destroy functions, otherwise * you have to make sure that any dynamically allocated values are freed * yourself. * * Returns: %TRUE if the key was found and removed from the #GHashTable */ /** * g_hash_table_remove_all: * @hash_table: a #GHashTable * * Removes all keys and their associated values from a #GHashTable. * * If the #GHashTable was created using g_hash_table_new_full(), * the keys and values are freed using the supplied destroy functions, * otherwise you have to make sure that any dynamically allocated * values are freed yourself. * * Since: 2.12 */ /** * g_hash_table_replace: * @hash_table: a #GHashTable * @key: a key to insert * @value: the value to associate with the key * * Inserts a new key and value into a #GHashTable similar to * g_hash_table_insert(). The difference is that if the key * already exists in the #GHashTable, it gets replaced by the * new key. If you supplied a @value_destroy_func when creating * the #GHashTable, the old value is freed using that function. * If you supplied a @key_destroy_func when creating the * #GHashTable, the old key is freed using that function. * * Returns: %TRUE of the key did not exist yet */ /** * g_hash_table_size: * @hash_table: a #GHashTable * * Returns the number of elements contained in the #GHashTable. * * Returns: the number of key/value pairs in the #GHashTable. */ /** * g_hash_table_steal: * @hash_table: a #GHashTable * @key: the key to remove * * Removes a key and its associated value from a #GHashTable without * calling the key and value destroy functions. * * Returns: %TRUE if the key was found and removed from the #GHashTable */ /** * g_hash_table_steal_all: * @hash_table: a #GHashTable * * Removes all keys and their associated values from a #GHashTable * without calling the key and value destroy functions. * * Since: 2.12 */ /** * g_hash_table_thaw: * @hash_table: a #GHashTable * * This function is deprecated and will be removed in the next major * release of GLib. It does nothing. */ /** * g_hash_table_unref: * @hash_table: a valid #GHashTable * * Atomically decrements the reference count of @hash_table by one. * If the reference count drops to 0, all keys and values will be * destroyed, and all memory allocated by the hash table is released. * This function is MT-safe and may be called from any thread. * * Since: 2.10 */ /** * g_hmac_copy: * @hmac: the #GHmac to copy * * Copies a #GHmac. If @hmac has been closed, by calling * g_hmac_get_string() or g_hmac_get_digest(), the copied * HMAC will be closed as well. * * Returns: the copy of the passed #GHmac. Use g_hmac_unref() * when finished using it. * Since: 2.30 */ /** * g_hmac_get_digest: * @hmac: a #GHmac * @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 array and places it * into @buffer. The size of the digest depends on the type of checksum. * * Once this function has been called, the #GHmac is closed and can * no longer be updated with g_checksum_update(). * * Since: 2.30 */ /** * g_hmac_get_string: * @hmac: a #GHmac * * Gets the HMAC as an hexadecimal string. * * Once this function has been called the #GHmac can no longer be * updated with g_hmac_update(). * * The hexadecimal characters will be lower case. * * Returns: the hexadecimal representation of the HMAC. The * returned string is owned by the HMAC and should not be modified * or freed. * Since: 2.30 */ /** * g_hmac_new: * @digest_type: the desired type of digest * @key: (array length=key_len): the key for the HMAC * @key_len: the length of the keys * * Creates a new #GHmac, using the digest algorithm @digest_type. * If the @digest_type is not known, %NULL is returned. * A #GHmac can be used to compute the HMAC of a key and an * arbitrary binary blob, using different hashing algorithms. * * A #GHmac works by feeding a binary blob through g_hmac_update() * until the data is complete; the digest can then be extracted * using g_hmac_get_string(), which will return the checksum as a * hexadecimal string; or g_hmac_get_digest(), which will return a * array of raw bytes. Once either g_hmac_get_string() or * g_hmac_get_digest() have been called on a #GHmac, the HMAC * will be closed and it won't be possible to call g_hmac_update() * on it anymore. * * Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. * * Returns: the newly created #GHmac, or %NULL. * Use g_hmac_unref() to free the memory allocated by it. * Since: 2.30 */ /** * g_hmac_ref: * @hmac: a valid #GHmac * * Atomically increments the reference count of @hmac by one. * * This function is MT-safe and may be called from any thread. * * Returns: the passed in #GHmac. * Since: 2.30 */ /** * g_hmac_unref: * @hmac: a #GHmac * * Atomically decrements the reference count of @hmac by one. * * If the reference count drops to 0, all keys and values will be * destroyed, and all memory allocated by the hash table is released. * This function is MT-safe and may be called from any thread. * Frees the memory allocated for @hmac. * * Since: 2.30 */ /** * g_hmac_update: * @hmac: a #GHmac * @data: (array length=length): buffer used to compute the checksum * @length: size of the buffer, or -1 if it is a nul-terminated string * * Feeds @data into an existing #GHmac. * * The HMAC must still be open, that is g_hmac_get_string() or * g_hmac_get_digest() must not have been called on @hmac. * * Since: 2.30 */ /** * g_hook_alloc: * @hook_list: a #GHookList * * Allocates space for a #GHook and initializes it. * * Returns: a new #GHook */ /** * g_hook_append: * @hook_list: a #GHookList * @hook: the #GHook to add to the end of @hook_list * * Appends a #GHook onto the end of a #GHookList. */ /** * g_hook_compare_ids: * @new_hook: a #GHook * @sibling: a #GHook to compare with @new_hook * * Compares the ids of two #GHook elements, returning a negative value * if the second id is greater than the first. * * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook */ /** * g_hook_destroy: * @hook_list: a #GHookList * @hook_id: a hook ID * * Destroys a #GHook, given its ID. * * Returns: %TRUE if the #GHook was found in the #GHookList and destroyed */ /** * g_hook_destroy_link: * @hook_list: a #GHookList * @hook: the #GHook to remove * * Removes one #GHook from a #GHookList, marking it * inactive and calling g_hook_unref() on it. */ /** * g_hook_find: * @hook_list: a #GHookList * @need_valids: %TRUE if #GHook elements which have been destroyed * should be skipped * @func: the function to call for each #GHook, which should return * %TRUE when the #GHook has been found * @data: the data to pass to @func * * Finds a #GHook in a #GHookList using the given function to * test for a match. * * Returns: the found #GHook or %NULL if no matching #GHook is found */ /** * g_hook_find_data: * @hook_list: a #GHookList * @need_valids: %TRUE if #GHook elements which have been destroyed * should be skipped * @data: the data to find * * Finds a #GHook in a #GHookList with the given data. * * Returns: the #GHook with the given @data or %NULL if no matching * #GHook is found */ /** * g_hook_find_func: * @hook_list: a #GHookList * @need_valids: %TRUE if #GHook elements which have been destroyed * should be skipped * @func: the function to find * * Finds a #GHook in a #GHookList with the given function. * * Returns: the #GHook with the given @func or %NULL if no matching * #GHook is found */ /** * g_hook_find_func_data: * @hook_list: a #GHookList * @need_valids: %TRUE if #GHook elements which have been destroyed * should be skipped * @func: the function to find * @data: the data to find * * Finds a #GHook in a #GHookList with the given function and data. * * Returns: the #GHook with the given @func and @data or %NULL if * no matching #GHook is found */ /** * g_hook_first_valid: * @hook_list: a #GHookList * @may_be_in_call: %TRUE if hooks which are currently running * (e.g. in another thread) are considered valid. If set to %FALSE, * these are skipped * * Returns the first #GHook in a #GHookList which has not been destroyed. * The reference count for the #GHook is incremented, so you must call * g_hook_unref() to restore it when no longer needed. (Or call * g_hook_next_valid() if you are stepping through the #GHookList.) * * Returns: the first valid #GHook, or %NULL if none are valid */ /** * g_hook_free: * @hook_list: a #GHookList * @hook: the #GHook to free * * Calls the #GHookList @finalize_hook function if it exists, * and frees the memory allocated for the #GHook. */ /** * g_hook_get: * @hook_list: a #GHookList * @hook_id: a hook id * * Returns the #GHook with the given id, or %NULL if it is not found. * * Returns: the #GHook with the given id, or %NULL if it is not found */ /** * g_hook_insert_before: * @hook_list: a #GHookList * @sibling: the #GHook to insert the new #GHook before * @hook: the #GHook to insert * * Inserts a #GHook into a #GHookList, before a given #GHook. */ /** * g_hook_insert_sorted: * @hook_list: a #GHookList * @hook: the #GHook to insert * @func: the comparison function used to sort the #GHook elements * * Inserts a #GHook into a #GHookList, sorted by the given function. */ /** * g_hook_list_clear: * @hook_list: a #GHookList * * Removes all the #GHook elements from a #GHookList. */ /** * g_hook_list_init: * @hook_list: a #GHookList * @hook_size: the size of each element in the #GHookList, * typically `sizeof (GHook)`. * * Initializes a #GHookList. * This must be called before the #GHookList is used. */ /** * g_hook_list_invoke: * @hook_list: a #GHookList * @may_recurse: %TRUE if functions which are already running * (e.g. in another thread) can be called. If set to %FALSE, * these are skipped * * Calls all of the #GHook functions in a #GHookList. */ /** * g_hook_list_invoke_check: * @hook_list: a #GHookList * @may_recurse: %TRUE if functions which are already running * (e.g. in another thread) can be called. If set to %FALSE, * these are skipped * * Calls all of the #GHook functions in a #GHookList. * Any function which returns %FALSE is removed from the #GHookList. */ /** * g_hook_list_marshal: * @hook_list: a #GHookList * @may_recurse: %TRUE if hooks which are currently running * (e.g. in another thread) are considered valid. If set to %FALSE, * these are skipped * @marshaller: the function to call for each #GHook * @marshal_data: data to pass to @marshaller * * Calls a function on each valid #GHook. */ /** * g_hook_list_marshal_check: * @hook_list: a #GHookList * @may_recurse: %TRUE if hooks which are currently running * (e.g. in another thread) are considered valid. If set to %FALSE, * these are skipped * @marshaller: the function to call for each #GHook * @marshal_data: data to pass to @marshaller * * Calls a function on each valid #GHook and destroys it if the * function returns %FALSE. */ /** * g_hook_next_valid: * @hook_list: a #GHookList * @hook: the current #GHook * @may_be_in_call: %TRUE if hooks which are currently running * (e.g. in another thread) are considered valid. If set to %FALSE, * these are skipped * * Returns the next #GHook in a #GHookList which has not been destroyed. * The reference count for the #GHook is incremented, so you must call * g_hook_unref() to restore it when no longer needed. (Or continue to call * g_hook_next_valid() until %NULL is returned.) * * Returns: the next valid #GHook, or %NULL if none are valid */ /** * g_hook_prepend: * @hook_list: a #GHookList * @hook: the #GHook to add to the start of @hook_list * * Prepends a #GHook on the start of a #GHookList. */ /** * g_hook_ref: * @hook_list: a #GHookList * @hook: the #GHook to increment the reference count of * * Increments the reference count for a #GHook. * * Returns: the @hook that was passed in (since 2.6) */ /** * g_hook_unref: * @hook_list: a #GHookList * @hook: the #GHook to unref * * Decrements the reference count of a #GHook. * If the reference count falls to 0, the #GHook is removed * from the #GHookList and g_hook_free() is called to free it. */ /** * g_hostname_is_ascii_encoded: * @hostname: a hostname * * Tests if @hostname contains segments with an ASCII-compatible * encoding of an Internationalized Domain Name. If this returns * %TRUE, you should decode the hostname with g_hostname_to_unicode() * before displaying it to the user. * * Note that a hostname might contain a mix of encoded and unencoded * segments, and so it is possible for g_hostname_is_non_ascii() and * g_hostname_is_ascii_encoded() to both return %TRUE for a name. * * Returns: %TRUE if @hostname contains any ASCII-encoded * segments. * Since: 2.22 */ /** * g_hostname_is_ip_address: * @hostname: a hostname (or IP address in string form) * * Tests if @hostname is the string form of an IPv4 or IPv6 address. * (Eg, "192.168.0.1".) * * Returns: %TRUE if @hostname is an IP address * Since: 2.22 */ /** * g_hostname_is_non_ascii: * @hostname: a hostname * * Tests if @hostname contains Unicode characters. If this returns * %TRUE, you need to encode the hostname with g_hostname_to_ascii() * before using it in non-IDN-aware contexts. * * Note that a hostname might contain a mix of encoded and unencoded * segments, and so it is possible for g_hostname_is_non_ascii() and * g_hostname_is_ascii_encoded() to both return %TRUE for a name. * * Returns: %TRUE if @hostname contains any non-ASCII characters * Since: 2.22 */ /** * g_hostname_to_ascii: * @hostname: a valid UTF-8 or ASCII hostname * * Converts @hostname to its canonical ASCII form; an ASCII-only * string containing no uppercase letters and not ending with a * trailing dot. * * Returns: an ASCII hostname, which must be freed, or %NULL if * @hostname is in some way invalid. * Since: 2.22 */ /** * g_hostname_to_unicode: * @hostname: a valid UTF-8 or ASCII hostname * * Converts @hostname to its canonical presentation form; a UTF-8 * string in Unicode normalization form C, containing no uppercase * letters, no forbidden characters, and no ASCII-encoded segments, * and not ending with a trailing dot. * * Of course if @hostname is not an internationalized hostname, then * the canonical presentation form will be entirely ASCII. * * Returns: a UTF-8 hostname, which must be freed, or %NULL if * @hostname is in some way invalid. * Since: 2.22 */ /** * g_htonl: * @val: a 32-bit integer value in host byte order * * Converts a 32-bit integer value from host to network byte order. * * Returns: @val converted to network byte order */ /** * g_htons: * @val: a 16-bit integer value in host byte order * * Converts a 16-bit integer value from host to network byte order. * * Returns: @val converted to network byte order */ /** * g_iconv: * @converter: conversion descriptor from g_iconv_open() * @inbuf: bytes to convert * @inbytes_left: inout parameter, bytes remaining to convert in @inbuf * @outbuf: converted output bytes * @outbytes_left: inout parameter, bytes available to fill in @outbuf * * Same as the standard UNIX routine iconv(), but * may be implemented via libiconv on UNIX flavors that lack * a native implementation. * * GLib provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * * Returns: count of non-reversible conversions, or -1 on error */ /** * g_iconv_close: * @converter: a conversion descriptor from g_iconv_open() * * Same as the standard UNIX routine iconv_close(), but * may be implemented via libiconv on UNIX flavors that lack * a native implementation. Should be called to clean up * the conversion descriptor from g_iconv_open() when * you are done converting things. * * GLib provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * * Returns: -1 on error, 0 on success */ /** * g_iconv_open: * @to_codeset: destination codeset * @from_codeset: source codeset * * Same as the standard UNIX routine iconv_open(), but * may be implemented via libiconv on UNIX flavors that lack * a native implementation. * * GLib provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * * Returns: a "conversion descriptor", or (GIConv)-1 if * opening the converter failed. */ /** * g_idle_add: * @function: function to call * @data: data to pass to @function. * * Adds a function to be called whenever there are no higher priority * events pending to the default main loop. The function is given the * default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function * returns %FALSE it is automatically removed from the list of event * sources and will not be called again. * * This internally creates a main loop source using g_idle_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. */ /** * g_idle_add_full: (rename-to g_idle_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. * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the idle is removed, or %NULL * * Adds a function to be called whenever there are no higher priority * events pending. If the function returns %FALSE it is automatically * removed from the list of event sources and will not be called again. * * This internally creates a main loop source using g_idle_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. */ /** * g_idle_remove_by_data: * @data: the data for the idle source's callback. * * Removes the idle function with the given data. * * Returns: %TRUE if an idle source was found and removed. */ /** * g_idle_source_new: * * Creates a new idle 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 the default priority for idle sources is * %G_PRIORITY_DEFAULT_IDLE, as compared to other sources which * have a default priority of %G_PRIORITY_DEFAULT. * * Returns: the newly-created idle source */ /** * g_info: * @...: format string, followed by parameters to insert * into the format string (as with printf()) * * A convenience function/macro to log an informational message. Seldom used. * * 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. * * Such messages are suppressed by the g_log_default_handler() unless * the G_MESSAGES_DEBUG environment variable is set appropriately. * * Since: 2.40 */ /** * g_int64_equal: * @v1: a pointer to a #gint64 key * @v2: a pointer to a #gint64 key to compare with @v1 * * Compares the two #gint64 values being pointed to and returns * %TRUE if they are equal. * It can be passed to g_hash_table_new() as the @key_equal_func * parameter, when using non-%NULL pointers to 64-bit integers as keys in a * #GHashTable. * * Returns: %TRUE if the two keys match. * Since: 2.22 */ /** * g_int64_hash: * @v: a pointer to a #gint64 key * * Converts a pointer to a #gint64 to a hash value. * * It can be passed to g_hash_table_new() as the @hash_func parameter, * when using non-%NULL pointers to 64-bit integer values as keys in a * #GHashTable. * * Returns: a hash value corresponding to the key. * Since: 2.22 */ /** * g_int_equal: * @v1: a pointer to a #gint key * @v2: a pointer to a #gint key to compare with @v1 * * Compares the two #gint values being pointed to and returns * %TRUE if they are equal. * It can be passed to g_hash_table_new() as the @key_equal_func * parameter, when using non-%NULL pointers to integers as keys in a * #GHashTable. * * Note that this function acts on pointers to #gint, not on #gint * directly: if your hash table's keys are of the form * `GINT_TO_POINTER (n)`, use g_direct_equal() instead. * * Returns: %TRUE if the two keys match. */ /** * g_int_hash: * @v: a pointer to a #gint key * * Converts a pointer to a #gint to a hash value. * It can be passed to g_hash_table_new() as the @hash_func parameter, * when using non-%NULL pointers to integer values as keys in a #GHashTable. * * Note that this function acts on pointers to #gint, not on #gint * directly: if your hash table's keys are of the form * `GINT_TO_POINTER (n)`, use g_direct_hash() instead. * * Returns: a hash value corresponding to the key. */ /** * g_intern_static_string: * @string: (allow-none): a static string * * Returns a canonical representation for @string. Interned strings * can be compared for equality by comparing the pointers, instead of * using strcmp(). g_intern_static_string() does not copy the string, * therefore @string must not be freed or modified. * * Returns: a canonical representation for the string * Since: 2.10 */ /** * g_intern_string: * @string: (allow-none): a string * * Returns a canonical representation for @string. Interned strings * can be compared for equality by comparing the pointers, instead of * using strcmp(). * * Returns: a canonical representation for the string * Since: 2.10 */ /** * g_io_add_watch: * @channel: a #GIOChannel * @condition: the condition to watch for * @func: the function to call when the condition is satisfied * @user_data: user data to pass to @func * * Adds the #GIOChannel into the default main loop context * with the default priority. * * Returns: the event source id */ /** * g_io_add_watch_full: (rename-to g_io_add_watch) * @channel: a #GIOChannel * @priority: the priority of the #GIOChannel source * @condition: the condition to watch for * @func: the function to call when the condition is satisfied * @user_data: user data to pass to @func * @notify: the function to call when the source is removed * * Adds the #GIOChannel into the default main loop context * with the given priority. * * This internally creates a main loop source using g_io_create_watch() * and attaches it to the main loop context with g_source_attach(). * You can do these steps manually if you need greater control. * * Returns: the event source id */ /** * g_io_channel_close: * @channel: A #GIOChannel * * Close an IO channel. Any pending data to be written will be * flushed, ignoring errors. The channel will not be freed until the * last reference is dropped using g_io_channel_unref(). * * Deprecated: 2.2: Use g_io_channel_shutdown() instead. */ /** * g_io_channel_error_from_errno: * @en: an `errno` error number, e.g. `EINVAL` * * Converts an `errno` error number to a #GIOChannelError. * * Returns: a #GIOChannelError error number, e.g. * %G_IO_CHANNEL_ERROR_INVAL. */ /** * g_io_channel_flush: * @channel: a #GIOChannel * @error: location to store an error of type #GIOChannelError * * Flushes the write buffer for the GIOChannel. * * Returns: the status of the operation: One of * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or * #G_IO_STATUS_ERROR. */ /** * g_io_channel_get_buffer_condition: * @channel: A #GIOChannel * * This function returns a #GIOCondition depending on whether there * is data to be read/space to write data in the internal buffers in * the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. * * Returns: A #GIOCondition */ /** * g_io_channel_get_buffer_size: * @channel: a #GIOChannel * * Gets the buffer size. * * Returns: the size of the buffer. */ /** * g_io_channel_get_buffered: * @channel: a #GIOChannel * * Returns whether @channel is buffered. * * Returns: %TRUE if the @channel is buffered. */ /** * g_io_channel_get_close_on_unref: * @channel: a #GIOChannel. * * Returns whether the file/socket/whatever associated with @channel * will be closed when @channel receives its final unref and is * destroyed. The default value of this is %TRUE for channels created * by g_io_channel_new_file (), and %FALSE for all other channels. * * Returns: Whether the channel will be closed on the final unref of * the GIOChannel data structure. */ /** * g_io_channel_get_encoding: * @channel: a #GIOChannel * * Gets the encoding for the input/output of the channel. * The internal encoding is always UTF-8. The encoding %NULL * makes the channel safe for binary data. * * Returns: A string containing the encoding, this string is * owned by GLib and must not be freed. */ /** * g_io_channel_get_flags: * @channel: a #GIOChannel * * Gets the current flags for a #GIOChannel, including read-only * flags such as %G_IO_FLAG_IS_READABLE. * * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE * are cached for internal use by the channel when it is created. * If they should change at some later point (e.g. partial shutdown * of a socket with the UNIX shutdown() function), the user * should immediately call g_io_channel_get_flags() to update * the internal values of these flags. * * Returns: the flags which are set on the channel */ /** * g_io_channel_get_line_term: * @channel: a #GIOChannel * @length: a location to return the length of the line terminator * * This returns the string that #GIOChannel uses to determine * where in the file a line break occurs. A value of %NULL * indicates autodetection. * * Returns: The line termination string. This value * is owned by GLib and must not be freed. */ /** * g_io_channel_init: * @channel: a #GIOChannel * * Initializes a #GIOChannel struct. * * This is called by each of the above functions when creating a * #GIOChannel, and so is not often needed by the application * programmer (unless you are creating a new type of #GIOChannel). */ /** * g_io_channel_new_file: * @filename: A string containing the name of a file * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have * the same meaning as in fopen() * @error: A location to return an error of type %G_FILE_ERROR * * Open a file @filename as a #GIOChannel using mode @mode. This * channel will be closed when the last reference to it is dropped, * so there is no need to call g_io_channel_close() (though doing * so will not cause problems, as long as no attempt is made to * access the channel after it is closed). * * Returns: A #GIOChannel on success, %NULL on failure. */ /** * g_io_channel_read: * @channel: a #GIOChannel * @buf: a buffer to read the data into (which should be at least * count bytes long) * @count: the number of bytes to read from the #GIOChannel * @bytes_read: returns the number of bytes actually read * * Reads data from a #GIOChannel. * * Returns: %G_IO_ERROR_NONE if the operation was successful. * Deprecated: 2.2: Use g_io_channel_read_chars() instead. */ /** * g_io_channel_read_chars: * @channel: a #GIOChannel * @buf: (out caller-allocates) (array length=count) (element-type guint8): * a buffer to read data into * @count: (in): the size of the buffer. Note that the buffer may not be * complelely filled even if there is data in the buffer if the * remaining data is not a complete character. * @bytes_read: (allow-none) (out): The number of bytes read. This may be * zero even on success if count < 6 and the channel's encoding * is non-%NULL. This indicates that the next UTF-8 character is * too wide for the buffer. * @error: a location to return an error of type #GConvertError * or #GIOChannelError. * * Replacement for g_io_channel_read() with the new API. * * Returns: the status of the operation. */ /** * g_io_channel_read_line: * @channel: a #GIOChannel * @str_return: (out): The line read from the #GIOChannel, including the * line terminator. This data should be freed with g_free() * when no longer needed. This is a nul-terminated string. * If a @length of zero is returned, this will be %NULL instead. * @length: (allow-none) (out): location to store length of the read data, or %NULL * @terminator_pos: (allow-none) (out): location to store position of line terminator, or %NULL * @error: A location to return an error of type #GConvertError * or #GIOChannelError * * Reads a line, including the terminating character(s), * from a #GIOChannel into a newly-allocated string. * @str_return will contain allocated memory if the return * is %G_IO_STATUS_NORMAL. * * Returns: the status of the operation. */ /** * g_io_channel_read_line_string: * @channel: a #GIOChannel * @buffer: a #GString into which the line will be written. * If @buffer already contains data, the old data will * be overwritten. * @terminator_pos: (allow-none): location to store position of line terminator, or %NULL * @error: a location to store an error of type #GConvertError * or #GIOChannelError * * Reads a line from a #GIOChannel, using a #GString as a buffer. * * Returns: the status of the operation. */ /** * g_io_channel_read_to_end: * @channel: a #GIOChannel * @str_return: (out) (array length=length) (element-type guint8): Location to * store a pointer to a string holding the remaining data in the * #GIOChannel. This data should be freed with g_free() when no * longer needed. This data is terminated by an extra nul * character, but there may be other nuls in the intervening data. * @length: (out): location to store length of the data * @error: location to return an error of type #GConvertError * or #GIOChannelError * * Reads all the remaining data from the file. * * Returns: %G_IO_STATUS_NORMAL on success. * This function never returns %G_IO_STATUS_EOF. */ /** * g_io_channel_read_unichar: * @channel: a #GIOChannel * @thechar: (out): a location to return a character * @error: a location to return an error of type #GConvertError * or #GIOChannelError * * Reads a Unicode character from @channel. * This function cannot be called on a channel with %NULL encoding. * * Returns: a #GIOStatus */ /** * g_io_channel_ref: * @channel: a #GIOChannel * * Increments the reference count of a #GIOChannel. * * Returns: the @channel that was passed in (since 2.6) */ /** * g_io_channel_seek: * @channel: a #GIOChannel * @offset: an offset, in bytes, which is added to the position specified * by @type * @type: the position in the file, which can be %G_SEEK_CUR (the current * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END * (the end of the file) * * Sets the current position in the #GIOChannel, similar to the standard * library function fseek(). * * Returns: %G_IO_ERROR_NONE if the operation was successful. * Deprecated: 2.2: Use g_io_channel_seek_position() instead. */ /** * g_io_channel_seek_position: * @channel: a #GIOChannel * @offset: The offset in bytes from the position specified by @type * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those * cases where a call to g_io_channel_set_encoding () * is allowed. See the documentation for * g_io_channel_set_encoding () for details. * @error: A location to return an error of type #GIOChannelError * * Replacement for g_io_channel_seek() with the new API. * * Returns: the status of the operation. */ /** * g_io_channel_set_buffer_size: * @channel: a #GIOChannel * @size: the size of the buffer, or 0 to let GLib pick a good size * * Sets the buffer size. */ /** * g_io_channel_set_buffered: * @channel: a #GIOChannel * @buffered: whether to set the channel buffered or unbuffered * * The buffering state can only be set if the channel's encoding * is %NULL. For any other encoding, the channel must be buffered. * * A buffered channel can only be set unbuffered if the channel's * internal buffers have been flushed. Newly created channels or * channels which have returned %G_IO_STATUS_EOF * not require such a flush. For write-only channels, a call to * g_io_channel_flush () is sufficient. For all other channels, * the buffers may be flushed by a call to g_io_channel_seek_position (). * This includes the possibility of seeking with seek type %G_SEEK_CUR * and an offset of zero. Note that this means that socket-based * channels cannot be set unbuffered once they have had data * read from them. * * On unbuffered channels, it is safe to mix read and write * calls from the new and old APIs, if this is necessary for * maintaining old code. * * The default state of the channel is buffered. */ /** * g_io_channel_set_close_on_unref: * @channel: a #GIOChannel * @do_close: Whether to close the channel on the final unref of * the GIOChannel data structure. The default value of * this is %TRUE for channels created by g_io_channel_new_file (), * and %FALSE for all other channels. * * Setting this flag to %TRUE for a channel you have already closed * can cause problems. */ /** * g_io_channel_set_encoding: * @channel: a #GIOChannel * @encoding: (allow-none): the encoding type * @error: location to store an error of type #GConvertError * * Sets the encoding for the input/output of the channel. * The internal encoding is always UTF-8. The default encoding * for the external file is UTF-8. * * The encoding %NULL is safe to use with binary data. * * The encoding can only be set if one of the following conditions * is true: * * - The channel was just created, and has not been written to or read from yet. * * - The channel is write-only. * * - The channel is a file, and the file pointer was just repositioned * by a call to g_io_channel_seek_position(). (This flushes all the * internal buffers.) * * - The current encoding is %NULL or UTF-8. * * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL). * * - One of the functions g_io_channel_read_chars() or * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or * %G_IO_STATUS_ERROR. This may be useful in the case of * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. * Returning one of these statuses from g_io_channel_read_line(), * g_io_channel_read_line_string(), or g_io_channel_read_to_end() * does not guarantee that the encoding can be changed. * * Channels which do not meet one of the above conditions cannot call * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if * they are "seekable", cannot call g_io_channel_write_chars() after * calling one of the API "read" functions. * * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set */ /** * g_io_channel_set_flags: * @channel: a #GIOChannel * @flags: the flags to set on the IO channel * @error: A location to return an error of type #GIOChannelError * * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK). * * Returns: the status of the operation. */ /** * g_io_channel_set_line_term: * @channel: a #GIOChannel * @line_term: (allow-none): The line termination string. Use %NULL for * autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", * and the Unicode paragraph separator. Autodetection should not be * used for anything other than file-based channels. * @length: The length of the termination string. If -1 is passed, the * string is assumed to be nul-terminated. This option allows * termination strings with embedded nuls. * * This sets the string that #GIOChannel uses to determine * where in the file a line break occurs. */ /** * g_io_channel_shutdown: * @channel: a #GIOChannel * @flush: if %TRUE, flush pending * @err: location to store a #GIOChannelError * * Close an IO channel. Any pending data to be written will be * flushed if @flush is %TRUE. The channel will not be freed until the * last reference is dropped using g_io_channel_unref(). * * Returns: the status of the operation. */ /** * g_io_channel_unix_get_fd: * @channel: a #GIOChannel, created with g_io_channel_unix_new(). * * Returns the file descriptor of the #GIOChannel. * * On Windows this function returns the file descriptor or socket of * the #GIOChannel. * * Returns: the file descriptor of the #GIOChannel. */ /** * g_io_channel_unix_new: * @fd: a file descriptor. * * Creates a new #GIOChannel given a file descriptor. On UNIX systems * this works for plain files, pipes, and sockets. * * The returned #GIOChannel has a reference count of 1. * * The default encoding for #GIOChannel is UTF-8. If your application * is reading output from a command using via pipe, you may need to set * the encoding to the encoding of the current locale (see * g_get_charset()) with the g_io_channel_set_encoding() function. * * If you want to read raw binary data without interpretation, then * call the g_io_channel_set_encoding() function with %NULL for the * encoding argument. * * This function is available in GLib on Windows, too, but you should * avoid using it on Windows. The domain of file descriptors and * sockets overlap. There is no way for GLib to know which one you mean * in case the argument you pass to this function happens to be both a * valid file descriptor and socket. If that happens a warning is * issued, and GLib assumes that it is the file descriptor you mean. * * Returns: a new #GIOChannel. */ /** * g_io_channel_unref: * @channel: a #GIOChannel * * Decrements the reference count of a #GIOChannel. */ /** * g_io_channel_win32_new_fd: * @fd: a C library file descriptor. * * Creates a new #GIOChannel given a file descriptor on Windows. This * works for file descriptors from the C runtime. * * This function works for file descriptors as returned by the open(), * creat(), pipe() and fileno() calls in the Microsoft C runtime. In * order to meaningfully use this function your code should use the * same C runtime as GLib uses, which is msvcrt.dll. Note that in * current Microsoft compilers it is near impossible to convince it to * build code that would use msvcrt.dll. The last Microsoft compiler * version that supported using msvcrt.dll as the C runtime was version * 6. The GNU compiler and toolchain for Windows, also known as Mingw, * fully supports msvcrt.dll. * * If you have created a #GIOChannel for a file descriptor and started * watching (polling) it, you shouldn't call read() on the file * descriptor. This is because adding polling for a file descriptor is * implemented in GLib on Windows by starting a thread that sits * blocked in a read() from the file descriptor most of the time. All * reads from the file descriptor should be done by this internal GLib * thread. Your code should call only g_io_channel_read(). * * This function is available only in GLib on Windows. * * Returns: a new #GIOChannel. */ /** * g_io_channel_win32_new_messages: * @hwnd: a window handle. * * Creates a new #GIOChannel given a window handle on Windows. * * This function creates a #GIOChannel that can be used to poll for * Windows messages for the window in question. * * Returns: a new #GIOChannel. */ /** * g_io_channel_win32_new_socket: * @socket: a Winsock socket * * Creates a new #GIOChannel given a socket on Windows. * * This function works for sockets created by Winsock. It's available * only in GLib on Windows. * * Polling a #GSource created to watch a channel for a socket puts the * socket in non-blocking mode. This is a side-effect of the * implementation and unavoidable. * * Returns: a new #GIOChannel */ /** * g_io_channel_write: * @channel: a #GIOChannel * @buf: the buffer containing the data to write * @count: the number of bytes to write * @bytes_written: the number of bytes actually written * * Writes data to a #GIOChannel. * * Returns: %G_IO_ERROR_NONE if the operation was successful. * Deprecated: 2.2: Use g_io_channel_write_chars() instead. */ /** * g_io_channel_write_chars: * @channel: a #GIOChannel * @buf: (array) (element-type guint8): a buffer to write data from * @count: the size of the buffer. If -1, the buffer * is taken to be a nul-terminated string. * @bytes_written: (out): The number of bytes written. This can be nonzero * even if the return value is not %G_IO_STATUS_NORMAL. * If the return value is %G_IO_STATUS_NORMAL and the * channel is blocking, this will always be equal * to @count if @count >= 0. * @error: a location to return an error of type #GConvertError * or #GIOChannelError * * Replacement for g_io_channel_write() with the new API. * * On seekable channels with encodings other than %NULL or UTF-8, generic * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars () * may only be made on a channel from which data has been read in the * cases described in the documentation for g_io_channel_set_encoding (). * * Returns: the status of the operation. */ /** * g_io_channel_write_unichar: * @channel: a #GIOChannel * @thechar: a character * @error: location to return an error of type #GConvertError * or #GIOChannelError * * Writes a Unicode character to @channel. * This function cannot be called on a channel with %NULL encoding. * * Returns: a #GIOStatus */ /** * g_io_create_watch: * @channel: a #GIOChannel to watch * @condition: conditions to watch for * * Creates a #GSource that's dispatched when @condition is met for the * given @channel. For example, if condition is #G_IO_IN, the source will * be dispatched when there's data available for reading. * * g_io_add_watch() is a simpler interface to this same functionality, for * the case where you want to add the source to the default main loop context * at the default priority. * * On Windows, polling a #GSource created to watch a channel for a socket * puts the socket in non-blocking mode. This is a side-effect of the * implementation and unavoidable. * * Returns: a new #GSource */ /** * g_key_file_free: (skip) * @key_file: a #GKeyFile * * Clears all keys and groups from @key_file, and decreases the * reference count by 1. If the reference count reaches zero, * frees the key file and all its allocated memory. * * Since: 2.6 */ /** * g_key_file_get_boolean: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @error: return location for a #GError * * Returns the value associated with @key under @group_name as a * boolean. * * If @key cannot be found then %FALSE is returned and @error is set * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value * associated with @key cannot be interpreted as a boolean then %FALSE * is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * * Returns: the value associated with the key as a boolean, * or %FALSE if the key was not found or could not be parsed. * Since: 2.6 */ /** * g_key_file_get_boolean_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @length: (out): the number of booleans returned * @error: return location for a #GError * * Returns the values associated with @key under @group_name as * booleans. * * If @key cannot be found then %NULL is returned and @error is set to * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated * with @key cannot be interpreted as booleans then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * * Returns: (array length=length) (element-type gboolean) (transfer container): * the values associated with the key as a list of booleans, or %NULL if the * key was not found or could not be parsed. The returned list of booleans * should be freed with g_free() when no longer needed. * Since: 2.6 */ /** * g_key_file_get_comment: * @key_file: a #GKeyFile * @group_name: (allow-none): a group name, or %NULL * @key: a key * @error: return location for a #GError * * Retrieves a comment above @key from @group_name. * If @key is %NULL then @comment will be read from above * @group_name. If both @key and @group_name are %NULL, then * @comment will be read from above the first group in the file. * * Returns: a comment that should be freed with g_free() * Since: 2.6 */ /** * g_key_file_get_double: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @error: return location for a #GError * * Returns the value associated with @key under @group_name as a * double. If @group_name is %NULL, the start_group is used. * * If @key cannot be found then 0.0 is returned and @error is set to * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated * with @key cannot be interpreted as a double then 0.0 is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * * Returns: the value associated with the key as a double, or * 0.0 if the key was not found or could not be parsed. * Since: 2.12 */ /** * g_key_file_get_double_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @length: (out): the number of doubles returned * @error: return location for a #GError * * Returns the values associated with @key under @group_name as * doubles. * * If @key cannot be found then %NULL is returned and @error is set to * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated * with @key cannot be interpreted as doubles then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * * Returns: (array length=length) (element-type gdouble) (transfer container): * the values associated with the key as a list of doubles, or %NULL if the * key was not found or could not be parsed. The returned list of doubles * should be freed with g_free() when no longer needed. * Since: 2.12 */ /** * g_key_file_get_groups: * @key_file: a #GKeyFile * @length: (out) (allow-none): return location for the number of returned groups, or %NULL * * Returns all groups in the key file loaded with @key_file. * The array of returned groups will be %NULL-terminated, so * @length may optionally be %NULL. * * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. * Use g_strfreev() to free it. * Since: 2.6 */ /** * g_key_file_get_int64: * @key_file: a non-%NULL #GKeyFile * @group_name: a non-%NULL group name * @key: a non-%NULL key * @error: return location for a #GError * * Returns the value associated with @key under @group_name as a signed * 64-bit integer. This is similar to g_key_file_get_integer() but can return * 64-bit results without truncation. * * Returns: the value associated with the key as a signed 64-bit integer, or * 0 if the key was not found or could not be parsed. * Since: 2.26 */ /** * g_key_file_get_integer: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @error: return location for a #GError * * Returns the value associated with @key under @group_name as an * integer. * * If @key cannot be found then 0 is returned and @error is set to * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated * with @key cannot be interpreted as an integer then 0 is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * * Returns: the value associated with the key as an integer, or * 0 if the key was not found or could not be parsed. * Since: 2.6 */ /** * g_key_file_get_integer_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @length: (out): the number of integers returned * @error: return location for a #GError * * Returns the values associated with @key under @group_name as * integers. * * If @key cannot be found then %NULL is returned and @error is set to * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated * with @key cannot be interpreted as integers then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * * Returns: (array length=length) (element-type gint) (transfer container): * the values associated with the key as a list of integers, or %NULL if * the key was not found or could not be parsed. The returned list of * integers should be freed with g_free() when no longer needed. * Since: 2.6 */ /** * g_key_file_get_keys: * @key_file: a #GKeyFile * @group_name: a group name * @length: (out) (allow-none): return location for the number of keys returned, or %NULL * @error: return location for a #GError, or %NULL * * Returns all keys for the group name @group_name. The array of * returned keys will be %NULL-terminated, so @length may * optionally be %NULL. In the event that the @group_name cannot * be found, %NULL is returned and @error is set to * #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. * Use g_strfreev() to free it. * Since: 2.6 */ /** * g_key_file_get_locale_string: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @locale: (allow-none): a locale identifier or %NULL * @error: return location for a #GError, or %NULL * * Returns the value associated with @key under @group_name * translated in the given @locale if available. If @locale is * %NULL then the current locale is assumed. * * If @key cannot be found then %NULL is returned and @error is set * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated * with @key cannot be interpreted or no suitable translation can * be found then the untranslated value is returned. * * Returns: a newly allocated string or %NULL if the specified * key cannot be found. * Since: 2.6 */ /** * g_key_file_get_locale_string_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @locale: (allow-none): a locale identifier or %NULL * @length: (out) (allow-none): return location for the number of returned strings or %NULL * @error: return location for a #GError or %NULL * * Returns the values associated with @key under @group_name * translated in the given @locale if available. If @locale is * %NULL then the current locale is assumed. * * If @key cannot be found then %NULL is returned and @error is set * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated * with @key cannot be interpreted or no suitable translations * can be found then the untranslated values are returned. The * returned array is %NULL-terminated, so @length may optionally * be %NULL. * * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array * or %NULL if the key isn't found. The string array should be freed * with g_strfreev(). * Since: 2.6 */ /** * g_key_file_get_start_group: * @key_file: a #GKeyFile * * Returns the name of the start group of the file. * * Returns: The start group of the key file. * Since: 2.6 */ /** * g_key_file_get_string: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @error: return location for a #GError, or %NULL * * Returns the string value associated with @key under @group_name. * Unlike g_key_file_get_value(), this function handles escape sequences * like \s. * * In the event the key cannot be found, %NULL is returned and * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * * Returns: a newly allocated string or %NULL if the specified * key cannot be found. * Since: 2.6 */ /** * g_key_file_get_string_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @length: (out) (allow-none): return location for the number of returned strings, or %NULL * @error: return location for a #GError, or %NULL * * Returns the values associated with @key under @group_name. * * In the event the key cannot be found, %NULL is returned and * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): * a %NULL-terminated string array or %NULL if the specified * key cannot be found. The array should be freed with g_strfreev(). * Since: 2.6 */ /** * g_key_file_get_uint64: * @key_file: a non-%NULL #GKeyFile * @group_name: a non-%NULL group name * @key: a non-%NULL key * @error: return location for a #GError * * Returns the value associated with @key under @group_name as an unsigned * 64-bit integer. This is similar to g_key_file_get_integer() but can return * large positive results without truncation. * * Returns: the value associated with the key as an unsigned 64-bit integer, * or 0 if the key was not found or could not be parsed. * Since: 2.26 */ /** * g_key_file_get_value: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @error: return location for a #GError, or %NULL * * Returns the raw value associated with @key under @group_name. * Use g_key_file_get_string() to retrieve an unescaped UTF-8 string. * * In the event the key cannot be found, %NULL is returned and * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * * Returns: a newly allocated string or %NULL if the specified * key cannot be found. * Since: 2.6 */ /** * g_key_file_has_group: * @key_file: a #GKeyFile * @group_name: a group name * * Looks whether the key file has the group @group_name. * * Returns: %TRUE if @group_name is a part of @key_file, %FALSE * otherwise. * Since: 2.6 */ /** * g_key_file_has_key: (skip) * @key_file: a #GKeyFile * @group_name: a group name * @key: a key name * @error: return location for a #GError * * Looks whether the key file has the key @key in the group * @group_name. * * Note that this function does not follow the rules for #GError strictly; * the return value both carries meaning and signals an error. To use * this function, you must pass a #GError pointer in @error, and check * whether it is not %NULL to see if an error occurred. * * Language bindings should use g_key_file_get_value() to test whether * or not a key exists. * * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise * Since: 2.6 */ /** * g_key_file_load_from_data: * @key_file: an empty #GKeyFile struct * @data: key file loaded in memory * @length: the length of @data in bytes (or (gsize)-1 if data is nul-terminated) * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * * Loads a key file from memory into an empty #GKeyFile structure. * If the object cannot be created then %error is set to a #GKeyFileError. * * Returns: %TRUE if a key file could be loaded, %FALSE otherwise * Since: 2.6 */ /** * g_key_file_load_from_data_dirs: * @key_file: an empty #GKeyFile struct * @file: (type filename): a relative path to a filename to open and parse * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path * of the file, or %NULL * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * * This function looks for a key file named @file in the paths * returned from g_get_user_data_dir() and g_get_system_data_dirs(), * loads the file into @key_file 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 #GKeyFileError. * * Returns: %TRUE if a key file could be loaded, %FALSE othewise * Since: 2.6 */ /** * g_key_file_load_from_dirs: * @key_file: an empty #GKeyFile struct * @file: (type filename): a relative path to a filename to open and parse * @search_dirs: (array zero-terminated=1) (element-type filename): %NULL-terminated array of directories to search * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path * of the file, or %NULL * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * * This function looks for a key file named @file in the paths * specified in @search_dirs, loads the file into @key_file 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 * #GKeyFileError. * * Returns: %TRUE if a key file could be loaded, %FALSE otherwise * Since: 2.14 */ /** * g_key_file_load_from_file: * @key_file: an empty #GKeyFile struct * @file: (type filename): the path of a filename to load, in the GLib filename encoding * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * * Loads a key file into an empty #GKeyFile structure. * If the file could not be loaded then @error is set to * either a #GFileError or #GKeyFileError. * * Returns: %TRUE if a key file could be loaded, %FALSE otherwise * Since: 2.6 */ /** * g_key_file_new: * * Creates a new empty #GKeyFile object. Use * g_key_file_load_from_file(), g_key_file_load_from_data(), * g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to * read an existing key file. * * Returns: (transfer full): an empty #GKeyFile. * Since: 2.6 */ /** * g_key_file_ref: (skip) * @key_file: a #GKeyFile * * Increases the reference count of @key_file. * * Returns: the same @key_file. * Since: 2.32 */ /** * g_key_file_remove_comment: * @key_file: a #GKeyFile * @group_name: (allow-none): a group name, or %NULL * @key: (allow-none): a key * @error: return location for a #GError * * Removes a comment above @key from @group_name. * If @key is %NULL then @comment will be removed above @group_name. * If both @key and @group_name are %NULL, then @comment will * be removed above the first group in the file. * * Returns: %TRUE if the comment was removed, %FALSE otherwise * Since: 2.6 */ /** * g_key_file_remove_group: * @key_file: a #GKeyFile * @group_name: a group name * @error: return location for a #GError or %NULL * * Removes the specified group, @group_name, * from the key file. * * Returns: %TRUE if the group was removed, %FALSE otherwise * Since: 2.6 */ /** * g_key_file_remove_key: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key name to remove * @error: return location for a #GError or %NULL * * Removes @key in @group_name from the key file. * * Returns: %TRUE if the key was removed, %FALSE otherwise * Since: 2.6 */ /** * g_key_file_save_to_file: * @key_file: a #GKeyFile * @filename: the name of the file to write to * @error: a pointer to a %NULL #GError, or %NULL * * Writes the contents of @key_file to @filename using * g_file_set_contents(). * * This function can fail for any of the reasons that * g_file_set_contents() may fail. * * Returns: %TRUE if successful, else %FALSE with @error set * Since: 2.40 */ /** * g_key_file_set_boolean: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @value: %TRUE or %FALSE * * Associates a new boolean value with @key under @group_name. * If @key cannot be found then it is created. * * Since: 2.6 */ /** * g_key_file_set_boolean_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @list: (array length=length): an array of boolean values * @length: length of @list * * Associates a list of boolean values with @key under @group_name. * If @key cannot be found then it is created. * If @group_name is %NULL, the start_group is used. * * Since: 2.6 */ /** * g_key_file_set_comment: * @key_file: a #GKeyFile * @group_name: (allow-none): a group name, or %NULL * @key: (allow-none): a key * @comment: a comment * @error: return location for a #GError * * Places a comment above @key from @group_name. * If @key is %NULL then @comment will be written above @group_name. * If both @key and @group_name are %NULL, then @comment will be * written above the first group in the file. * * Returns: %TRUE if the comment was written, %FALSE otherwise * Since: 2.6 */ /** * g_key_file_set_double: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @value: an double value * * Associates a new double value with @key under @group_name. * If @key cannot be found then it is created. * * Since: 2.12 */ /** * g_key_file_set_double_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @list: (array length=length): an array of double values * @length: number of double values in @list * * Associates a list of double values with @key under * @group_name. If @key cannot be found then it is created. * * Since: 2.12 */ /** * g_key_file_set_int64: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @value: an integer value * * Associates a new integer value with @key under @group_name. * If @key cannot be found then it is created. * * Since: 2.26 */ /** * g_key_file_set_integer: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @value: an integer value * * Associates a new integer value with @key under @group_name. * If @key cannot be found then it is created. * * Since: 2.6 */ /** * g_key_file_set_integer_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @list: (array length=length): an array of integer values * @length: number of integer values in @list * * Associates a list of integer values with @key under @group_name. * If @key cannot be found then it is created. * * Since: 2.6 */ /** * g_key_file_set_list_separator: * @key_file: a #GKeyFile * @separator: the separator * * Sets the character which is used to separate * values in lists. Typically ';' or ',' are used * as separators. The default list separator is ';'. * * Since: 2.6 */ /** * g_key_file_set_locale_string: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @locale: a locale identifier * @string: a string * * Associates a string value for @key and @locale under @group_name. * If the translation for @key cannot be found then it is created. * * Since: 2.6 */ /** * g_key_file_set_locale_string_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @locale: a locale identifier * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values * @length: the length of @list * * Associates a list of string values for @key and @locale under * @group_name. If the translation for @key cannot be found then * it is created. * * Since: 2.6 */ /** * g_key_file_set_string: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @string: a string * * Associates a new string value with @key under @group_name. * If @key cannot be found then it is created. * If @group_name cannot be found then it is created. * Unlike g_key_file_set_value(), this function handles characters * that need escaping, such as newlines. * * Since: 2.6 */ /** * g_key_file_set_string_list: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values * @length: number of string values in @list * * Associates a list of string values for @key under @group_name. * If @key cannot be found then it is created. * If @group_name cannot be found then it is created. * * Since: 2.6 */ /** * g_key_file_set_uint64: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @value: an integer value * * Associates a new integer value with @key under @group_name. * If @key cannot be found then it is created. * * Since: 2.26 */ /** * g_key_file_set_value: * @key_file: a #GKeyFile * @group_name: a group name * @key: a key * @value: a string * * Associates a new value with @key under @group_name. * * If @key cannot be found then it is created. If @group_name cannot * be found then it is created. To set an UTF-8 string which may contain * characters that need escaping (such as newlines or spaces), use * g_key_file_set_string(). * * Since: 2.6 */ /** * g_key_file_to_data: * @key_file: a #GKeyFile * @length: (out) (allow-none): return location for the length of the * returned string, or %NULL * @error: return location for a #GError, or %NULL * * This function outputs @key_file as a string. * * Note that this function never reports an error, * so it is safe to pass %NULL as @error. * * Returns: a newly allocated string holding * the contents of the #GKeyFile * Since: 2.6 */ /** * g_key_file_unref: * @key_file: a #GKeyFile * * Decreases the reference count of @key_file by 1. If the reference count * reaches zero, frees the key file and all its allocated memory. * * Since: 2.32 */ /** * g_list_alloc: * * Allocates space for one #GList element. It is called by * g_list_append(), g_list_prepend(), g_list_insert() and * g_list_insert_sorted() and so is rarely used on its own. * * Returns: a pointer to the newly-allocated #GList element */ /** * g_list_append: * @list: a pointer to a #GList * @data: the data for the new element * * Adds a new element on to the end of the list. * * Note that the return value is the new start of the list, * if @list was empty; make sure you store the new value. * * g_list_append() has to traverse the entire list to find the end, * which is inefficient when adding multiple elements. A common idiom * to avoid the inefficiency is to use g_list_prepend() and reverse * the list with g_list_reverse() when all elements have been added. * * |[ * // Notice that these are initialized to the empty list. * GList *string_list = NULL, *number_list = NULL; * * // This is a list of strings. * string_list = g_list_append (string_list, "first"); * string_list = g_list_append (string_list, "second"); * * // This is a list of integers. * number_list = g_list_append (number_list, GINT_TO_POINTER (27)); * number_list = g_list_append (number_list, GINT_TO_POINTER (14)); * ]| * * Returns: either @list or the new start of the #GList if @list was %NULL */ /** * g_list_concat: * @list1: a #GList, this must point to the top of the list * @list2: the #GList to add to the end of the first #GList, * this must point to the top of the list * * Adds the second #GList onto the end of the first #GList. * Note that the elements of the second #GList are not copied. * They are used directly. * * This function is for example used to move an element in the list. * The following example moves an element to the top of the list: * |[ * list = g_list_remove_link (list, llink); * list = g_list_concat (llink, list); * ]| * * Returns: the start of the new #GList, which equals @list1 if not %NULL */ /** * g_list_copy: * @list: a #GList, this must point to the top of the list * * Copies a #GList. * * Note that this is a "shallow" copy. If the list elements * consist of pointers to data, the pointers are copied but * the actual data is not. See g_list_copy_deep() if you need * to copy the data as well. * * Returns: the start of the new list that holds the same data as @list */ /** * g_list_copy_deep: * @list: a #GList, this must point to the top of the list * @func: a copy function used to copy every element in the list * @user_data: user data passed to the copy function @func, or %NULL * * Makes a full (deep) copy of a #GList. * * In contrast with g_list_copy(), this function uses @func to make * a copy of each list element, in addition to copying the list * container itself. * * @func, as a #GCopyFunc, takes two arguments, the data to be copied * and a @user_data pointer. It's safe to pass %NULL as user_data, * if the copy function takes only one argument. * * For instance, if @list holds a list of GObjects, you can do: * |[ * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); * ]| * * And, to entirely free the new list, you could do: * |[ * g_list_free_full (another_list, g_object_unref); * ]| * * Returns: the start of the new list that holds a full copy of @list, * use g_list_free_full() to free it * Since: 2.34 */ /** * g_list_delete_link: * @list: a #GList, this must point to the top of the list * @link_: node to delete from @list * * Removes the node link_ from the list and frees it. * Compare this to g_list_remove_link() which removes the node * without freeing it. * * Returns: the (possibly changed) start of the #GList */ /** * g_list_find: * @list: a #GList, this must point to the top of the list * @data: the element data to find * * Finds the element in a #GList which contains the given data. * * Returns: the found #GList element, or %NULL if it is not found */ /** * g_list_find_custom: * @list: a #GList, this must point to the top of the list * @data: user data passed to the function * @func: the function to call for each element. * It should return 0 when the desired element is found * * Finds an element in a #GList, using a supplied function to * find the desired element. It iterates over the list, calling * the given function which should return 0 when the desired * element is found. The function takes two #gconstpointer arguments, * the #GList element's data as the first argument and the * given user data. * * Returns: the found #GList element, or %NULL if it is not found */ /** * g_list_first: * @list: any #GList element * * Gets the first element in a #GList. * * Returns: the first element in the #GList, * or %NULL if the #GList has no elements */ /** * g_list_foreach: * @list: a #GList, this must point to the top of the list * @func: the function to call with each element's data * @user_data: user data to pass to the function * * Calls a function for each element of a #GList. */ /** * g_list_free: * @list: a #GList * * Frees all of the memory used by a #GList. * The freed elements are returned to the slice allocator. * * If list elements contain dynamically-allocated memory, you should * either use g_list_free_full() or free them manually first. */ /** * g_list_free1: * * Another name for g_list_free_1(). */ /** * g_list_free_1: * @list: a #GList element * * Frees one #GList element. * It is usually used after g_list_remove_link(). */ /** * g_list_free_full: * @list: a pointer to a #GList * @free_func: the function to be called to free each element's data * * Convenience method, which frees all the memory used by a #GList, * and calls @free_func on every element's data. * * Since: 2.28 */ /** * g_list_index: * @list: a #GList, this must point to the top of the list * @data: the data to find * * Gets the position of the element containing * the given data (starting from 0). * * Returns: the index of the element containing the data, * or -1 if the data is not found */ /** * g_list_insert: * @list: a pointer to a #GList, this must point to the top of the list * @data: the data for the new element * @position: the position to insert the element. If this is * negative, or is larger than the number of elements in the * list, the new element is added on to the end of the list. * * Inserts a new element into the list at the given position. * * Returns: the (possibly changed) start of the #GList */ /** * g_list_insert_before: * @list: a pointer to a #GList, this must point to the top of the list * @sibling: the list element before which the new element * is inserted or %NULL to insert at the end of the list * @data: the data for the new element * * Inserts a new element into the list before the given position. * * Returns: the (possibly changed) start of the #GList */ /** * g_list_insert_sorted: * @list: a pointer to a #GList, this must point to the top of the * already sorted list * @data: the data for the new element * @func: the function to compare elements in the list. It should * return a number > 0 if the first parameter comes after the * second parameter in the sort order. * * Inserts a new element into the list, using the given comparison * function to determine its position. * * If you are adding many new elements to a list, and the number of * new elements is much larger than the length of the list, use * g_list_prepend() to add the new items and sort the list afterwards * with g_list_sort(). * * Returns: the (possibly changed) start of the #GList */ /** * g_list_insert_sorted_with_data: * @list: a pointer to a #GList, this must point to the top of the * already sorted list * @data: the data for the new element * @func: the function to compare elements in the list. It should * return a number > 0 if the first parameter comes after the * second parameter in the sort order. * @user_data: user data to pass to comparison function * * Inserts a new element into the list, using the given comparison * function to determine its position. * * If you are adding many new elements to a list, and the number of * new elements is much larger than the length of the list, use * g_list_prepend() to add the new items and sort the list afterwards * with g_list_sort(). * * Returns: the (possibly changed) start of the #GList * Since: 2.10 */ /** * g_list_last: * @list: any #GList element * * Gets the last element in a #GList. * * Returns: the last element in the #GList, * or %NULL if the #GList has no elements */ /** * g_list_length: * @list: a #GList, this must point to the top of the list * * Gets the number of elements in a #GList. * * This function iterates over the whole list to count its elements. * Use a #GQueue instead of a GList if you regularly need the number * of items. * * Returns: the number of elements in the #GList */ /** * g_list_next: * @list: an element in a #GList * * A convenience macro to get the next element in a #GList. * Note that it is considered perfectly acceptable to access * @list->next directly. * * Returns: the next element, or %NULL if there are no more elements */ /** * g_list_nth: * @list: a #GList, this must point to the top of the list * @n: the position of the element, counting from 0 * * Gets the element at the given position in a #GList. * * Returns: the element, or %NULL if the position is off * the end of the #GList */ /** * g_list_nth_data: * @list: a #GList, this must point to the top of the list * @n: the position of the element * * Gets the data of the element at the given position. * * Returns: the element's data, or %NULL if the position * is off the end of the #GList */ /** * g_list_nth_prev: * @list: a #GList * @n: the position of the element, counting from 0 * * Gets the element @n places before @list. * * Returns: the element, or %NULL if the position is * off the end of the #GList */ /** * g_list_position: * @list: a #GList, this must point to the top of the list * @llink: an element in the #GList * * Gets the position of the given element * in the #GList (starting from 0). * * Returns: the position of the element in the #GList, * or -1 if the element is not found */ /** * g_list_prepend: * @list: a pointer to a #GList, this must point to the top of the list * @data: the data for the new element * * Prepends a new element on to the start of the list. * * Note that the return value is the new start of the list, * which will have changed, so make sure you store the new value. * * |[ * // Notice that it is initialized to the empty list. * GList *list = NULL; * * list = g_list_prepend (list, "last"); * list = g_list_prepend (list, "first"); * ]| * * Do not use this function to prepend a new element to a different * element than the start of the list. Use g_list_insert_before() instead. * * Returns: a pointer to the newly prepended element, which is the new * start of the #GList */ /** * g_list_previous: * @list: an element in a #GList * * A convenience macro to get the previous element in a #GList. * Note that it is considered perfectly acceptable to access * @list->previous directly. * * Returns: the previous element, or %NULL if there are no previous * elements */ /** * g_list_remove: * @list: a #GList, this must point to the top of the list * @data: the data of the element to remove * * Removes an element from a #GList. * If two elements contain the same data, only the first is removed. * If none of the elements contain the data, the #GList is unchanged. * * Returns: the (possibly changed) start of the #GList */ /** * g_list_remove_all: * @list: a #GList, this must point to the top of the list * @data: data to remove * * Removes all list nodes with data equal to @data. * Returns the new head of the list. Contrast with * g_list_remove() which removes only the first node * matching the given data. * * Returns: the (possibly changed) start of the #GList */ /** * g_list_remove_link: * @list: a #GList, this must point to the top of the list * @llink: an element in the #GList * * Removes an element from a #GList, without freeing the element. * The removed element's prev and next links are set to %NULL, so * that it becomes a self-contained list with one element. * * This function is for example used to move an element in the list * (see the example for g_list_concat()) or to remove an element in * the list before freeing its data: * |[ * list = g_list_remove_link (list, llink); * free_some_data_that_may_access_the_list_again (llink->data); * g_list_free (llink); * ]| * * Returns: the (possibly changed) start of the #GList */ /** * g_list_reverse: * @list: a #GList, this must point to the top of the list * * Reverses a #GList. * It simply switches the next and prev pointers of each element. * * Returns: the start of the reversed #GList */ /** * g_list_sort: * @list: a #GList, this must point to the top of the list * @compare_func: the comparison function used to sort the #GList. * This function is passed the data from 2 elements of the #GList * and should return 0 if they are equal, a negative value if the * first element comes before the second, or a positive value if * the first element comes after the second. * * Sorts a #GList using the given comparison function. The algorithm * used is a stable sort. * * Returns: the (possibly changed) start of the #GList */ /** * g_list_sort_with_data: * @list: a #GList, this must point to the top of the list * @compare_func: comparison function * @user_data: user data to pass to comparison function * * Like g_list_sort(), but the comparison function accepts * a user data argument. * * Returns: the (possibly changed) start of the #GList */ /** * g_listenv: * * Gets the names of all variables set in the environment. * * Programs that want to be portable to Windows should typically use * this function and g_getenv() instead of using the environ array * from the C library directly. On Windows, the strings in the environ * array are in system codepage encoding, while in most of the typical * use cases for environment variables in GLib-using programs you want * the UTF-8 encoding that this function and g_getenv() provide. * * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated * list of strings which must be freed with g_strfreev(). * Since: 2.8 */ /** * g_locale_from_utf8: * @utf8string: a UTF-8 encoded string * @len: the length of the string, 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) * @bytes_read: 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: 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 UTF-8 to the encoding used for strings by * the C runtime (usually the same as that used by the operating * system) in the [current locale][setlocale]. On Windows this means * the system codepage. * * Returns: A newly-allocated buffer containing the converted string, * or %NULL on an error, and error will be set. */ /** * g_locale_to_utf8: * @opsysstring: a string in the encoding of the current locale. On Windows * this means the system codepage. * @len: the length of the string, 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) * @bytes_read: 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: 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 which is in the encoding used for strings by * the C runtime (usually the same as that used by the operating * system) in the [current locale][setlocale] into a UTF-8 string. * * Returns: A newly-allocated buffer containing the converted string, * or %NULL on an error, and error will be set. */ /** * g_log: * @log_domain: the log domain, usually #G_LOG_DOMAIN * @log_level: the log level, either from #GLogLevelFlags * or a user-defined level * @format: the message format. See the printf() documentation * @...: the parameters to insert into the format string * * Logs an error or debugging message. * * If the log level has been set as fatal, the abort() * function is called to terminate the program. * * 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. */ /** * g_log_default_handler: * @log_domain: the log domain of the message * @log_level: the level of the message * @message: the message * @unused_data: data passed from g_log() which is unused * * The default log handler set up by GLib; g_log_set_default_handler() * allows to install an alternate default log handler. * This is used if no log handler has been set for the particular log * domain and log level combination. It outputs the message to stderr * or stdout and if the log level is fatal it calls abort(). It automatically * prints a new-line character after the message, so one does not need to be * manually included in @message. * * The behavior of this log handler can be influenced by a number of * environment variables: * * - `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which * messages should be prefixed by the program name and PID of the * aplication. * * - `G_MESSAGES_DEBUG`: A space-separated list of log domains for * which debug and informational messages are printed. By default * these messages are not printed. * * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for * the rest. */ /** * g_log_remove_handler: * @log_domain: the log domain * @handler_id: the id of the handler, which was returned * in g_log_set_handler() * * Removes the log handler. */ /** * g_log_set_always_fatal: * @fatal_mask: the mask containing bits set for each level * of error which is to be fatal * * Sets the message levels which are always fatal, in any log domain. * When a message with any of these levels is logged the program terminates. * You can only set the levels defined by GLib to be fatal. * %G_LOG_LEVEL_ERROR is always fatal. * * You can also make some message levels fatal at runtime by setting * the `G_DEBUG` environment variable (see * [Running GLib Applications](glib-running.html)). * * Returns: the old fatal mask */ /** * g_log_set_default_handler: * @log_func: the log handler function * @user_data: data passed to the log handler * * Installs a default log handler which is used if no * log handler has been set for the particular log domain * and log level combination. By default, GLib uses * g_log_default_handler() as default log handler. * * Returns: the previous default log handler * Since: 2.6 */ /** * g_log_set_fatal_mask: * @log_domain: the log domain * @fatal_mask: the new fatal mask * * Sets the log levels which are fatal in the given domain. * %G_LOG_LEVEL_ERROR is always fatal. * * Returns: the old fatal mask for the log domain */ /** * g_log_set_handler: * @log_domain: (allow-none): the log domain, or %NULL for the default "" * application domain * @log_levels: the log levels to apply the log handler for. * To handle fatal and recursive messages as well, combine * the log levels with the #G_LOG_FLAG_FATAL and * #G_LOG_FLAG_RECURSION bit flags. * @log_func: the log handler function * @user_data: data passed to the log handler * * Sets the log handler for a domain and a set of log levels. * To handle fatal and recursive messages the @log_levels parameter * must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION * bit flags. * * Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if * you want to set a handler for this log level you must combine it with * #G_LOG_FLAG_FATAL. * * Here is an example for adding a log handler for all warning messages * in the default domain: * |[ * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * ]| * * This example adds a log handler for all critical messages from GTK+: * |[ * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * ]| * * This example adds a log handler for all messages from GLib: * |[ * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * ]| * * Returns: the id of the new handler */ /** * g_logv: * @log_domain: the log domain * @log_level: the log level * @format: the message format. See the printf() documentation * @args: the parameters to insert into the format string * * Logs an error or debugging message. * * If the log level has been set as fatal, the abort() * function is called to terminate the program. * * 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. */ /** * g_lstat: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * @buf: a pointer to a stat struct, which will be filled with the file * information * * A wrapper for the POSIX lstat() function. The lstat() function is * like stat() except that in the case of symbolic links, it returns * information about the symbolic link itself and not the file that it * refers to. If the system does not support symbolic links g_lstat() * is identical to g_stat(). * * See your C library manual for more details about lstat(). * * Returns: 0 if the information was successfully retrieved, * -1 if an error occurred * Since: 2.6 */ /** * g_main_context_acquire: * @context: a #GMainContext * * Tries to become the owner of the specified context. * If some other thread is the owner of the context, * returns %FALSE immediately. Ownership is properly * recursive: the owner can require ownership again * and will release ownership when g_main_context_release() * is called as many times as g_main_context_acquire(). * * You must be the owner of a context before you * can call g_main_context_prepare(), g_main_context_query(), * g_main_context_check(), g_main_context_dispatch(). * * Returns: %TRUE if the operation succeeded, and * this thread is now the owner of @context. */ /** * g_main_context_add_poll: * @context: (allow-none): a #GMainContext (or %NULL for the default context) * @fd: a #GPollFD structure holding information about a file * descriptor to watch. * @priority: the priority for this file descriptor which should be * the same as the priority used for g_source_attach() to ensure that the * file descriptor is polled whenever the results may be needed. * * Adds a file descriptor to the set of file descriptors polled for * this context. This will very seldom be used directly. Instead * a typical event source will use g_source_add_unix_fd() instead. */ /** * g_main_context_check: * @context: a #GMainContext * @max_priority: the maximum numerical priority of sources to check * @fds: (array length=n_fds): array of #GPollFD's that was passed to * the last call to g_main_context_query() * @n_fds: return value of g_main_context_query() * * Passes the results of polling back to the main loop. * * You must have successfully acquired the context with * g_main_context_acquire() before you may call this function. * * Returns: %TRUE if some sources are ready to be dispatched. */ /** * g_main_context_default: * * Returns the global default main context. This is the main context * used for main loop functions when a main loop is not explicitly * specified, and corresponds to the "main" main loop. See also * g_main_context_get_thread_default(). * * Returns: (transfer none): the global default main context. */ /** * g_main_context_dispatch: * @context: a #GMainContext * * Dispatches all pending sources. * * You must have successfully acquired the context with * g_main_context_acquire() before you may call this function. */ /** * g_main_context_find_source_by_funcs_user_data: * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used). * @funcs: the @source_funcs passed to g_source_new(). * @user_data: the user data from the callback. * * Finds a source with the given source functions and user data. If * multiple sources exist with the same source function and user data, * the first one found will be returned. * * Returns: (transfer none): the source, if one was found, otherwise %NULL */ /** * g_main_context_find_source_by_id: * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used) * @source_id: the source ID, as returned by g_source_get_id(). * * Finds a #GSource given a pair of context and ID. * * Returns: (transfer none): the #GSource if found, otherwise, %NULL */ /** * g_main_context_find_source_by_user_data: * @context: a #GMainContext * @user_data: the user_data for the callback. * * Finds a source with the given user data for the callback. If * multiple sources exist with the same user data, the first * one found will be returned. * * Returns: (transfer none): the source, if one was found, otherwise %NULL */ /** * g_main_context_get_poll_func: * @context: a #GMainContext * * Gets the poll function set by g_main_context_set_poll_func(). * * Returns: the poll function */ /** * g_main_context_get_thread_default: * * Gets the thread-default #GMainContext for this thread. Asynchronous * operations that want to be able to be run in contexts other than * the default one should call this method or * g_main_context_ref_thread_default() to get a #GMainContext to add * their #GSources to. (Note that even in single-threaded * programs applications may sometimes want to temporarily push a * non-default context, so it is not safe to assume that this will * always return %NULL if you are running in the default thread.) * * If you need to hold a reference on the context, use * g_main_context_ref_thread_default() instead. * * Returns: (transfer none): the thread-default #GMainContext, or * %NULL if the thread-default context is the global default context. * Since: 2.22 */ /** * g_main_context_invoke: * @context: (allow-none): a #GMainContext, or %NULL * @function: function to call * @data: data to pass to @function * * Invokes a function in such a way that @context is owned during the * invocation of @function. * * If @context is %NULL then the global default main context — as * returned by g_main_context_default() — is used. * * If @context is owned by the current thread, @function is called * directly. Otherwise, if @context is the thread-default main context * of the current thread and g_main_context_acquire() succeeds, then * @function is called and g_main_context_release() is called * afterwards. * * In any other case, an idle source is created to call @function and * that source is attached to @context (presumably to be run in another * thread). The idle source is attached with #G_PRIORITY_DEFAULT * priority. If you want a different priority, use * g_main_context_invoke_full(). * * Note that, as with normal idle functions, @function should probably * return %FALSE. If it returns %TRUE, it will be continuously run in a * loop (and may prevent this call from returning). * * Since: 2.28 */ /** * g_main_context_invoke_full: * @context: (allow-none): a #GMainContext, or %NULL * @priority: the priority at which to run @function * @function: function to call * @data: data to pass to @function * @notify: (allow-none): a function to call when @data is no longer in use, or %NULL. * * Invokes a function in such a way that @context is owned during the * invocation of @function. * * This function is the same as g_main_context_invoke() except that it * lets you specify the priority incase @function ends up being * scheduled as an idle and also lets you give a #GDestroyNotify for @data. * * @notify should not assume that it is called from any particular * thread or with any particular context acquired. * * Since: 2.28 */ /** * g_main_context_is_owner: * @context: a #GMainContext * * Determines whether this thread holds the (recursive) * ownership of this #GMainContext. This is useful to * know before waiting on another thread that may be * blocking to get ownership of @context. * * Returns: %TRUE if current thread is owner of @context. * Since: 2.10 */ /** * g_main_context_iteration: * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used) * @may_block: whether the call may block. * * Runs a single iteration for the given main loop. This involves * checking to see if any event sources are ready to be processed, * then if no events sources are ready and @may_block is %TRUE, waiting * for a source to become ready, then dispatching the highest priority * events sources that are ready. Otherwise, if @may_block is %FALSE * sources are not waited to become ready, only those highest priority * events sources will be dispatched (if any), that are ready at this * given moment without further waiting. * * Note that even when @may_block is %TRUE, it is still possible for * g_main_context_iteration() to return %FALSE, since the wait may * be interrupted for other reasons than an event source becoming ready. * * Returns: %TRUE if events were dispatched. */ /** * g_main_context_new: * * Creates a new #GMainContext structure. * * Returns: the new #GMainContext */ /** * g_main_context_pending: * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used) * * Checks if any sources have pending events for the given context. * * Returns: %TRUE if events are pending. */ /** * g_main_context_pop_thread_default: * @context: (allow-none): a #GMainContext object, or %NULL * * Pops @context off the thread-default context stack (verifying that * it was on the top of the stack). * * Since: 2.22 */ /** * g_main_context_prepare: * @context: a #GMainContext * @priority: location to store priority of highest priority * source already ready. * * Prepares to poll sources within a main loop. The resulting information * for polling is determined by calling g_main_context_query (). * * You must have successfully acquired the context with * g_main_context_acquire() before you may call this function. * * Returns: %TRUE if some source is ready to be dispatched * prior to polling. */ /** * g_main_context_push_thread_default: * @context: (allow-none): a #GMainContext, or %NULL for the global default context * * Acquires @context and sets it as the thread-default context for the * current thread. This will cause certain asynchronous operations * (such as most [gio][gio]-based I/O) which are * started in this thread to run under @context and deliver their * results to its main loop, rather than running under the global * default context in the main thread. Note that calling this function * changes the context returned by g_main_context_get_thread_default(), * not the one returned by g_main_context_default(), so it does not affect * the context used by functions like g_idle_add(). * * Normally you would call this function shortly after creating a new * thread, passing it a #GMainContext which will be run by a * #GMainLoop in that thread, to set a new default context for all * async operations in that thread. (In this case, you don't need to * ever call g_main_context_pop_thread_default().) In some cases * however, you may want to schedule a single operation in a * non-default context, or temporarily use a non-default context in * the main thread. In that case, you can wrap the call to the * asynchronous operation inside a * g_main_context_push_thread_default() / * g_main_context_pop_thread_default() pair, but it is up to you to * ensure that no other asynchronous operations accidentally get * started while the non-default context is active. * * Beware that libraries that predate this function may not correctly * handle being used from a thread with a thread-default context. Eg, * see g_file_supports_thread_contexts(). * * Since: 2.22 */ /** * g_main_context_query: * @context: a #GMainContext * @max_priority: maximum priority source to check * @timeout_: (out): location to store timeout to be used in polling * @fds: (out caller-allocates) (array length=n_fds): location to * store #GPollFD records that need to be polled. * @n_fds: length of @fds. * * Determines information necessary to poll this main loop. * * You must have successfully acquired the context with * g_main_context_acquire() before you may call this function. * * Returns: the number of records actually stored in @fds, * or, if more than @n_fds records need to be stored, the number * of records that need to be stored. */ /** * g_main_context_ref: * @context: a #GMainContext * * Increases the reference count on a #GMainContext object by one. * * Returns: the @context that was passed in (since 2.6) */ /** * g_main_context_ref_thread_default: * * Gets the thread-default #GMainContext for this thread, as with * g_main_context_get_thread_default(), but also adds a reference to * it with g_main_context_ref(). In addition, unlike * g_main_context_get_thread_default(), if the thread-default context * is the global default context, this will return that #GMainContext * (with a ref added to it) rather than returning %NULL. * * Returns: (transfer full): the thread-default #GMainContext. Unref * with g_main_context_unref() when you are done with it. * Since: 2.32 */ /** * g_main_context_release: * @context: a #GMainContext * * Releases ownership of a context previously acquired by this thread * with g_main_context_acquire(). If the context was acquired multiple * times, the ownership will be released only when g_main_context_release() * is called as many times as it was acquired. */ /** * g_main_context_remove_poll: * @context: a #GMainContext * @fd: a #GPollFD descriptor previously added with g_main_context_add_poll() * * Removes file descriptor from the set of file descriptors to be * polled for a particular context. */ /** * g_main_context_set_poll_func: * @context: a #GMainContext * @func: the function to call to poll all file descriptors * * Sets the function to use to handle polling of file descriptors. It * will be used instead of the poll() system call * (or GLib's replacement function, which is used where * poll() isn't available). * * This function could possibly be used to integrate the GLib event * loop with an external event loop. */ /** * g_main_context_unref: * @context: a #GMainContext * * Decreases the reference count on a #GMainContext object by one. If * the result is zero, free the context and free all associated memory. */ /** * g_main_context_wait: * @context: a #GMainContext * @cond: a condition variable * @mutex: a mutex, currently held * * Tries to become the owner of the specified context, * as with g_main_context_acquire(). But if another thread * is the owner, atomically drop @mutex and wait on @cond until * that owner releases ownership or until @cond is signaled, then * try again (once) to become the owner. * * Returns: %TRUE if the operation succeeded, and * this thread is now the owner of @context. */ /** * g_main_context_wakeup: * @context: a #GMainContext * * If @context is currently blocking in g_main_context_iteration() * waiting for a source to become ready, cause it to stop blocking * and return. Otherwise, cause the next invocation of * g_main_context_iteration() to return without blocking. * * This API is useful for low-level control over #GMainContext; for * example, integrating it with main loop implementations such as * #GMainLoop. * * Another related use for this function is when implementing a main * loop with a termination condition, computed from multiple threads: * * |[ * #define NUM_TASKS 10 * static volatile gint tasks_remaining = NUM_TASKS; * ... * * while (g_atomic_int_get (&tasks_remaining) != 0) * g_main_context_iteration (NULL, TRUE); * ]| * * Then in a thread: * |[ * perform_work(); * * if (g_atomic_int_dec_and_test (&tasks_remaining)) * g_main_context_wakeup (NULL); * ]| */ /** * g_main_current_source: * * Returns the currently firing source for this thread. * * Returns: (transfer none): The currently firing source or %NULL. * Since: 2.12 */ /** * g_main_depth: * * Returns the depth of the stack of calls to * g_main_context_dispatch() on any #GMainContext in the current thread. * That is, when called from the toplevel, it gives 0. When * called from within a callback from g_main_context_iteration() * (or g_main_loop_run(), etc.) it returns 1. When called from within * a callback to a recursive call to g_main_context_iteration(), * it returns 2. And so forth. * * This function is useful in a situation like the following: * Imagine an extremely simple "garbage collected" system. * * |[ * static GList *free_list; * * gpointer * allocate_memory (gsize size) * { * gpointer result = g_malloc (size); * free_list = g_list_prepend (free_list, result); * return result; * } * * void * free_allocated_memory (void) * { * GList *l; * for (l = free_list; l; l = l->next); * g_free (l->data); * g_list_free (free_list); * free_list = NULL; * } * * [...] * * while (TRUE); * { * g_main_context_iteration (NULL, TRUE); * free_allocated_memory(); * } * ]| * * This works from an application, however, if you want to do the same * thing from a library, it gets more difficult, since you no longer * control the main loop. You might think you can simply use an idle * function to make the call to free_allocated_memory(), but that * doesn't work, since the idle function could be called from a * recursive callback. This can be fixed by using g_main_depth() * * |[ * gpointer * allocate_memory (gsize size) * { * FreeListBlock *block = g_new (FreeListBlock, 1); * block->mem = g_malloc (size); * block->depth = g_main_depth (); * free_list = g_list_prepend (free_list, block); * return block->mem; * } * * void * free_allocated_memory (void) * { * GList *l; * * int depth = g_main_depth (); * for (l = free_list; l; ); * { * GList *next = l->next; * FreeListBlock *block = l->data; * if (block->depth > depth) * { * g_free (block->mem); * g_free (block); * free_list = g_list_delete_link (free_list, l); * } * * l = next; * } * } * ]| * * There is a temptation to use g_main_depth() to solve * problems with reentrancy. For instance, while waiting for data * to be received from the network in response to a menu item, * the menu item might be selected again. It might seem that * one could make the menu item's callback return immediately * and do nothing if g_main_depth() returns a value greater than 1. * However, this should be avoided since the user then sees selecting * the menu item do nothing. Furthermore, you'll find yourself adding * these checks all over your code, since there are doubtless many, * many things that the user could do. Instead, you can use the * following techniques: * * 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent * the user from interacting with elements while the main * loop is recursing. * * 2. Avoid main loop recursion in situations where you can't handle * arbitrary callbacks. Instead, structure your code so that you * simply return to the main loop and then get called again when * there is more work to do. * * Returns: The main loop recursion level in the current thread */ /** * g_main_loop_get_context: * @loop: a #GMainLoop. * * Returns the #GMainContext of @loop. * * Returns: (transfer none): the #GMainContext of @loop */ /** * g_main_loop_is_running: * @loop: a #GMainLoop. * * Checks to see if the main loop is currently being run via g_main_loop_run(). * * Returns: %TRUE if the mainloop is currently being run. */ /** * g_main_loop_new: * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used). * @is_running: set to %TRUE to indicate that the loop is running. This * is not very important since calling g_main_loop_run() will set this to * %TRUE anyway. * * Creates a new #GMainLoop structure. * * Returns: a new #GMainLoop. */ /** * g_main_loop_quit: * @loop: a #GMainLoop * * Stops a #GMainLoop from running. Any calls to g_main_loop_run() * for the loop will return. * * Note that sources that have already been dispatched when * g_main_loop_quit() is called will still be executed. */ /** * g_main_loop_ref: * @loop: a #GMainLoop * * Increases the reference count on a #GMainLoop object by one. * * Returns: @loop */ /** * g_main_loop_run: * @loop: a #GMainLoop * * Runs a main loop until g_main_loop_quit() is called on the loop. * If this is called for the thread of the loop's #GMainContext, * it will process events from the loop, otherwise it will * simply wait. */ /** * g_main_loop_unref: * @loop: a #GMainLoop * * Decreases the reference count on a #GMainLoop object by one. If * the result is zero, free the loop and free all associated memory. */ /** * g_malloc: * @n_bytes: the number of bytes to allocate * * Allocates @n_bytes bytes of memory. * If @n_bytes is 0 it returns %NULL. * * Returns: a pointer to the allocated memory */ /** * g_malloc0: * @n_bytes: the number of bytes to allocate * * Allocates @n_bytes bytes of memory, initialized to 0's. * If @n_bytes is 0 it returns %NULL. * * Returns: a pointer to the allocated memory */ /** * g_malloc0_n: * @n_blocks: the number of blocks to allocate * @n_block_bytes: the size of each block in bytes * * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, * but care is taken to detect possible overflow during multiplication. * * Since: 2.24 * Returns: a pointer to the allocated memory */ /** * g_malloc_n: * @n_blocks: the number of blocks to allocate * @n_block_bytes: the size of each block in bytes * * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, * but care is taken to detect possible overflow during multiplication. * * Since: 2.24 * Returns: a pointer to the allocated memory */ /** * g_mapped_file_free: * @file: a #GMappedFile * * This call existed before #GMappedFile had refcounting and is currently * exactly the same as g_mapped_file_unref(). * * Since: 2.8 * Deprecated: 2.22: Use g_mapped_file_unref() instead. */ /** * g_mapped_file_get_bytes: * @file: a #GMappedFile * * Creates a new #GBytes which references the data mapped from @file. * The mapped contents of the file must not be modified after creating this * bytes object, because a #GBytes should be immutable. * * Returns: (transfer full): A newly allocated #GBytes referencing data * from @file * Since: 2.34 */ /** * g_mapped_file_get_contents: * @file: a #GMappedFile * * Returns the contents of a #GMappedFile. * * Note that the contents may not be zero-terminated, * even if the #GMappedFile is backed by a text file. * * If the file is empty then %NULL is returned. * * Returns: the contents of @file, or %NULL. * Since: 2.8 */ /** * g_mapped_file_get_length: * @file: a #GMappedFile * * Returns the length of the contents of a #GMappedFile. * * Returns: the length of the contents of @file. * Since: 2.8 */ /** * g_mapped_file_new: * @filename: The path of the file to load, in the GLib filename encoding * @writable: whether the mapping should be writable * @error: return location for a #GError, or %NULL * * Maps a file into memory. On UNIX, this is using the mmap() function. * * If @writable is %TRUE, the mapped buffer may be modified, otherwise * it is an error to modify the mapped buffer. Modifications to the buffer * are not visible to other processes mapping the same file, and are not * written back to the file. * * Note that modifications of the underlying file might affect the contents * of the #GMappedFile. Therefore, mapping should only be used if the file * will not be modified, or if all modifications of the file are done * atomically (e.g. using g_file_set_contents()). * * If @filename is the name of an empty, regular file, the function * will successfully return an empty #GMappedFile. In other cases of * size 0 (e.g. device files such as /dev/null), @error will be set * to the #GFileError value #G_FILE_ERROR_INVAL. * * Returns: a newly allocated #GMappedFile which must be unref'd * with g_mapped_file_unref(), or %NULL if the mapping failed. * Since: 2.8 */ /** * g_mapped_file_new_from_fd: * @fd: The file descriptor of the file to load * @writable: whether the mapping should be writable * @error: return location for a #GError, or %NULL * * Maps a file into memory. On UNIX, this is using the mmap() function. * * If @writable is %TRUE, the mapped buffer may be modified, otherwise * it is an error to modify the mapped buffer. Modifications to the buffer * are not visible to other processes mapping the same file, and are not * written back to the file. * * Note that modifications of the underlying file might affect the contents * of the #GMappedFile. Therefore, mapping should only be used if the file * will not be modified, or if all modifications of the file are done * atomically (e.g. using g_file_set_contents()). * * Returns: a newly allocated #GMappedFile which must be unref'd * with g_mapped_file_unref(), or %NULL if the mapping failed. * Since: 2.32 */ /** * g_mapped_file_ref: * @file: a #GMappedFile * * Increments the reference count of @file by one. It is safe to call * this function from any thread. * * Returns: the passed in #GMappedFile. * Since: 2.22 */ /** * g_mapped_file_unref: * @file: a #GMappedFile * * Decrements the reference count of @file by one. If the reference count * drops to 0, unmaps the buffer of @file and frees it. * * It is safe to call this function from any thread. * * Since 2.22 */ /** * g_markup_collect_attributes: * @element_name: the current tag name * @attribute_names: the attribute names * @attribute_values: the attribute values * @error: a pointer to a #GError or %NULL * @first_type: the #GMarkupCollectType of the first attribute * @first_attr: the name of the first attribute * @...: a pointer to the storage location of the first attribute * (or %NULL), followed by more types names and pointers, ending * with %G_MARKUP_COLLECT_INVALID * * Collects the attributes of the element from the data passed to the * #GMarkupParser start_element function, dealing with common error * conditions and supporting boolean values. * * This utility function is not required to write a parser but can save * a lot of typing. * * The @element_name, @attribute_names, @attribute_values and @error * parameters passed to the start_element callback should be passed * unmodified to this function. * * Following these arguments is a list of "supported" attributes to collect. * It is an error to specify multiple attributes with the same name. If any * attribute not in the list appears in the @attribute_names array then an * unknown attribute error will result. * * The #GMarkupCollectType field allows specifying the type of collection * to perform and if a given attribute must appear or is optional. * * The attribute name is simply the name of the attribute to collect. * * The pointer should be of the appropriate type (see the descriptions * under #GMarkupCollectType) and may be %NULL in case a particular * attribute is to be allowed but ignored. * * This function deals with issuing errors for missing attributes * (of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes * (of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate * attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well * as parse errors for boolean-valued attributes (again of type * %G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE * will be returned and @error will be set as appropriate. * * Returns: %TRUE if successful * Since: 2.16 */ /** * g_markup_escape_text: * @text: some valid UTF-8 text * @length: length of @text in bytes, or -1 if the text is nul-terminated * * Escapes text so that the markup parser will parse it verbatim. * Less than, greater than, ampersand, etc. are replaced with the * corresponding entities. This function would typically be used * when writing out a file to be parsed with the markup parser. * * Note that this function doesn't protect whitespace and line endings * from being processed according to the XML rules for normalization * of line endings and attribute values. * * Note also that this function will produce character references in * the range of  ...  for all control sequences * except for tabstop, newline and carriage return. The character * references in this range are not valid XML 1.0, but they are * valid XML 1.1 and will be accepted by the GMarkup parser. * * Returns: a newly allocated string with the escaped text */ /** * g_markup_parse_context_end_parse: * @context: a #GMarkupParseContext * @error: return location for a #GError * * Signals to the #GMarkupParseContext that all data has been * fed into the parse context with g_markup_parse_context_parse(). * * This function reports an error if the document isn't complete, * for example if elements are still open. * * Returns: %TRUE on success, %FALSE if an error was set */ /** * g_markup_parse_context_free: * @context: a #GMarkupParseContext * * Frees a #GMarkupParseContext. * * This function can't be called from inside one of the * #GMarkupParser functions or while a subparser is pushed. */ /** * g_markup_parse_context_get_element: * @context: a #GMarkupParseContext * * Retrieves the name of the currently open element. * * If called from the start_element or end_element handlers this will * give the element_name as passed to those functions. For the parent * elements, see g_markup_parse_context_get_element_stack(). * * Returns: the name of the currently open element, or %NULL * Since: 2.2 */ /** * g_markup_parse_context_get_element_stack: * @context: a #GMarkupParseContext * * Retrieves the element stack from the internal state of the parser. * * The returned #GSList is a list of strings where the first item is * the currently open tag (as would be returned by * g_markup_parse_context_get_element()) and the next item is its * immediate parent. * * This function is intended to be used in the start_element and * end_element handlers where g_markup_parse_context_get_element() * would merely return the name of the element that is being * processed. * * Returns: the element stack, which must not be modified * Since: 2.16 */ /** * g_markup_parse_context_get_position: * @context: a #GMarkupParseContext * @line_number: (allow-none): return location for a line number, or %NULL * @char_number: (allow-none): return location for a char-on-line number, or %NULL * * Retrieves the current line number and the number of the character on * that line. Intended for use in error messages; there are no strict * semantics for what constitutes the "current" line number other than * "the best number we could come up with for error messages." */ /** * g_markup_parse_context_get_user_data: * @context: a #GMarkupParseContext * * Returns the user_data associated with @context. * * This will either be the user_data that was provided to * g_markup_parse_context_new() or to the most recent call * of g_markup_parse_context_push(). * * Returns: the provided user_data. The returned data belongs to * the markup context and will be freed when * g_markup_parse_context_free() is called. * Since: 2.18 */ /** * g_markup_parse_context_new: * @parser: a #GMarkupParser * @flags: one or more #GMarkupParseFlags * @user_data: user data to pass to #GMarkupParser functions * @user_data_dnotify: user data destroy notifier called when * the parse context is freed * * Creates a new parse context. A parse context is used to parse * marked-up documents. You can feed any number of documents into * a context, as long as no errors occur; once an error occurs, * the parse context can't continue to parse text (you have to * free it and create a new parse context). * * Returns: a new #GMarkupParseContext */ /** * g_markup_parse_context_parse: * @context: a #GMarkupParseContext * @text: chunk of text to parse * @text_len: length of @text in bytes * @error: return location for a #GError * * Feed some data to the #GMarkupParseContext. * * The data need not be valid UTF-8; an error will be signaled if * it's invalid. The data need not be an entire document; you can * feed a document into the parser incrementally, via multiple calls * to this function. Typically, as you receive data from a network * connection or file, you feed each received chunk of data into this * function, aborting the process if an error occurs. Once an error * is reported, no further data may be fed to the #GMarkupParseContext; * all errors are fatal. * * Returns: %FALSE if an error occurred, %TRUE on success */ /** * g_markup_parse_context_pop: * @context: a #GMarkupParseContext * * Completes the process of a temporary sub-parser redirection. * * This function exists to collect the user_data allocated by a * matching call to g_markup_parse_context_push(). It must be called * in the end_element handler corresponding to the start_element * handler during which g_markup_parse_context_push() was called. * You must not call this function from the error callback -- the * @user_data is provided directly to the callback in that case. * * This function is not intended to be directly called by users * interested in invoking subparsers. Instead, it is intended to * be used by the subparsers themselves to implement a higher-level * interface. * * Returns: the user data passed to g_markup_parse_context_push() * Since: 2.18 */ /** * g_markup_parse_context_push: * @context: a #GMarkupParseContext * @parser: a #GMarkupParser * @user_data: user data to pass to #GMarkupParser functions * * Temporarily redirects markup data to a sub-parser. * * This function may only be called from the start_element handler of * a #GMarkupParser. It must be matched with a corresponding call to * g_markup_parse_context_pop() in the matching end_element handler * (except in the case that the parser aborts due to an error). * * All tags, text and other data between the matching tags is * redirected to the subparser given by @parser. @user_data is used * as the user_data for that parser. @user_data is also passed to the * error callback in the event that an error occurs. This includes * errors that occur in subparsers of the subparser. * * The end tag matching the start tag for which this call was made is * handled by the previous parser (which is given its own user_data) * which is why g_markup_parse_context_pop() is provided to allow "one * last access" to the @user_data provided to this function. In the * case of error, the @user_data provided here is passed directly to * the error callback of the subparser and g_markup_parse_context_pop() * should not be called. In either case, if @user_data was allocated * then it ought to be freed from both of these locations. * * This function is not intended to be directly called by users * interested in invoking subparsers. Instead, it is intended to be * used by the subparsers themselves to implement a higher-level * interface. * * As an example, see the following implementation of a simple * parser that counts the number of tags encountered. * * |[ * typedef struct * { * gint tag_count; * } CounterData; * * static void * counter_start_element (GMarkupParseContext *context, * const gchar *element_name, * const gchar **attribute_names, * const gchar **attribute_values, * gpointer user_data, * GError **error) * { * CounterData *data = user_data; * * data->tag_count++; * } * * static void * counter_error (GMarkupParseContext *context, * GError *error, * gpointer user_data) * { * CounterData *data = user_data; * * g_slice_free (CounterData, data); * } * * static GMarkupParser counter_subparser = * { * counter_start_element, * NULL, * NULL, * NULL, * counter_error * }; * ]| * * In order to allow this parser to be easily used as a subparser, the * following interface is provided: * * |[ * void * start_counting (GMarkupParseContext *context) * { * CounterData *data = g_slice_new (CounterData); * * data->tag_count = 0; * g_markup_parse_context_push (context, &counter_subparser, data); * } * * gint * end_counting (GMarkupParseContext *context) * { * CounterData *data = g_markup_parse_context_pop (context); * int result; * * result = data->tag_count; * g_slice_free (CounterData, data); * * return result; * } * ]| * * The subparser would then be used as follows: * * |[ * static void start_element (context, element_name, ...) * { * if (strcmp (element_name, "count-these") == 0) * start_counting (context); * * // else, handle other tags... * } * * static void end_element (context, element_name, ...) * { * if (strcmp (element_name, "count-these") == 0) * g_print ("Counted %d tags\n", end_counting (context)); * * // else, handle other tags... * } * ]| * * Since: 2.18 */ /** * g_markup_parse_context_ref: * @context: a #GMarkupParseContext * * Increases the reference count of @context. * * Returns: the same @context * Since: 2.36 */ /** * g_markup_parse_context_unref: * @context: a #GMarkupParseContext * * Decreases the reference count of @context. When its reference count * drops to 0, it is freed. * * Since: 2.36 */ /** * g_markup_printf_escaped: * @format: printf() style format string * @...: the arguments to insert in the format string * * Formats arguments according to @format, escaping * all string and character arguments in the fashion * of g_markup_escape_text(). This is useful when you * want to insert literal strings into XML-style markup * output, without having to worry that the strings * might themselves contain markup. * * |[ * const char *store = "Fortnum & Mason"; * const char *item = "Tea"; * char *output; * * output = g_markup_printf_escaped ("" * "%s" * "%s" * "", * store, item); * ]| * * Returns: newly allocated result from formatting * operation. Free with g_free(). * Since: 2.4 */ /** * g_markup_vprintf_escaped: * @format: printf() style format string * @args: variable argument list, similar to vprintf() * * Formats the data in @args according to @format, escaping * all string and character arguments in the fashion * of g_markup_escape_text(). See g_markup_printf_escaped(). * * Returns: newly allocated result from formatting * operation. Free with g_free(). * Since: 2.4 */ /** * g_match_info_expand_references: * @match_info: (allow-none): a #GMatchInfo or %NULL * @string_to_expand: the string to expand * @error: location to store the error occurring, or %NULL to ignore errors * * Returns a new string containing the text in @string_to_expand with * references and escape sequences expanded. References refer to the last * match done with @string against @regex and have the same syntax used by * g_regex_replace(). * * The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was * passed to g_regex_new(). * * The backreferences are extracted from the string passed to the match * function, so you cannot call this function after freeing the string. * * @match_info may be %NULL in which case @string_to_expand must not * contain references. For instance "foo\n" does not refer to an actual * pattern and '\n' merely will be replaced with \n character, * while to expand "\0" (whole match) one needs the result of a match. * Use g_regex_check_replacement() to find out whether @string_to_expand * contains references. * * Returns: (allow-none): the expanded string, or %NULL if an error occurred * Since: 2.14 */ /** * g_match_info_fetch: * @match_info: #GMatchInfo structure * @match_num: number of the sub expression * * Retrieves the text matching the @match_num'th capturing * parentheses. 0 is the full text of the match, 1 is the first paren * set, 2 the second, and so on. * * If @match_num is a valid sub pattern but it didn't match anything * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty * string is returned. * * If the match was obtained using the DFA algorithm, that is using * g_regex_match_all() or g_regex_match_all_full(), the retrieved * string is not that of a set of parentheses but that of a matched * substring. Substrings are matched in reverse order of length, so * 0 is the longest match. * * The string is fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * * Returns: (allow-none): The matched substring, or %NULL if an error * occurred. You have to free the string yourself * Since: 2.14 */ /** * g_match_info_fetch_all: * @match_info: a #GMatchInfo structure * * Bundles up pointers to each of the matching substrings from a match * and stores them in an array of gchar pointers. The first element in * the returned array is the match number 0, i.e. the entire matched * text. * * If a sub pattern didn't match anything (e.g. sub pattern 1, matching * "b" against "(a)?b") then an empty string is inserted. * * If the last match was obtained using the DFA algorithm, that is using * g_regex_match_all() or g_regex_match_all_full(), the retrieved * strings are not that matched by sets of parentheses but that of the * matched substring. Substrings are matched in reverse order of length, * so the first one is the longest match. * * The strings are fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * * Returns: (transfer full): a %NULL-terminated array of gchar * * pointers. It must be freed using g_strfreev(). If the previous * match failed %NULL is returned * Since: 2.14 */ /** * g_match_info_fetch_named: * @match_info: #GMatchInfo structure * @name: name of the subexpression * * Retrieves the text matching the capturing parentheses named @name. * * If @name is a valid sub pattern name but it didn't match anything * (e.g. sub pattern "X", matching "b" against "(?Pa)?b") * then an empty string is returned. * * The string is fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * * Returns: (allow-none): The matched substring, or %NULL if an error * occurred. You have to free the string yourself * Since: 2.14 */ /** * g_match_info_fetch_named_pos: * @match_info: #GMatchInfo structure * @name: name of the subexpression * @start_pos: (out) (allow-none): pointer to location where to store * the start position, or %NULL * @end_pos: (out) (allow-none): pointer to location where to store * the end position, or %NULL * * Retrieves the position in bytes of the capturing parentheses named @name. * * If @name is a valid sub pattern name but it didn't match anything * (e.g. sub pattern "X", matching "b" against "(?Pa)?b") * then @start_pos and @end_pos are set to -1 and %TRUE is returned. * * Returns: %TRUE if the position was fetched, %FALSE otherwise. * If the position cannot be fetched, @start_pos and @end_pos * are left unchanged. * Since: 2.14 */ /** * g_match_info_fetch_pos: * @match_info: #GMatchInfo structure * @match_num: number of the sub expression * @start_pos: (out) (allow-none): pointer to location where to store * the start position, or %NULL * @end_pos: (out) (allow-none): pointer to location where to store * the end position, or %NULL * * Retrieves the position in bytes of the @match_num'th capturing * parentheses. 0 is the full text of the match, 1 is the first * paren set, 2 the second, and so on. * * If @match_num is a valid sub pattern but it didn't match anything * (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos * and @end_pos are set to -1 and %TRUE is returned. * * If the match was obtained using the DFA algorithm, that is using * g_regex_match_all() or g_regex_match_all_full(), the retrieved * position is not that of a set of parentheses but that of a matched * substring. Substrings are matched in reverse order of length, so * 0 is the longest match. * * Returns: %TRUE if the position was fetched, %FALSE otherwise. If * the position cannot be fetched, @start_pos and @end_pos are left * unchanged * Since: 2.14 */ /** * g_match_info_free: * @match_info: (allow-none): a #GMatchInfo, or %NULL * * If @match_info is not %NULL, calls g_match_info_unref(); otherwise does * nothing. * * Since: 2.14 */ /** * g_match_info_get_match_count: * @match_info: a #GMatchInfo structure * * Retrieves the number of matched substrings (including substring 0, * that is the whole matched text), so 1 is returned if the pattern * has no substrings in it and 0 is returned if the match failed. * * If the last match was obtained using the DFA algorithm, that is * using g_regex_match_all() or g_regex_match_all_full(), the retrieved * count is not that of the number of capturing parentheses but that of * the number of matched substrings. * * Returns: Number of matched substrings, or -1 if an error occurred * Since: 2.14 */ /** * g_match_info_get_regex: * @match_info: a #GMatchInfo * * Returns #GRegex object used in @match_info. It belongs to Glib * and must not be freed. Use g_regex_ref() if you need to keep it * after you free @match_info object. * * Returns: #GRegex object used in @match_info * Since: 2.14 */ /** * g_match_info_get_string: * @match_info: a #GMatchInfo * * Returns the string searched with @match_info. This is the * string passed to g_regex_match() or g_regex_replace() so * you may not free it before calling this function. * * Returns: the string searched with @match_info * Since: 2.14 */ /** * g_match_info_is_partial_match: * @match_info: a #GMatchInfo structure * * Usually if the string passed to g_regex_match*() matches as far as * it goes, but is too short to match the entire pattern, %FALSE is * returned. There are circumstances where it might be helpful to * distinguish this case from other cases in which there is no match. * * Consider, for example, an application where a human is required to * type in data for a field with specific formatting requirements. An * example might be a date in the form ddmmmyy, defined by the pattern * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$". * If the application sees the user’s keystrokes one by one, and can * check that what has been typed so far is potentially valid, it is * able to raise an error as soon as a mistake is made. * * GRegex supports the concept of partial matching by means of the * #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags. * When they are used, the return code for * g_regex_match() or g_regex_match_full() is, as usual, %TRUE * for a complete match, %FALSE otherwise. But, when these functions * return %FALSE, you can check if the match was partial calling * g_match_info_is_partial_match(). * * The difference between #G_REGEX_MATCH_PARTIAL_SOFT and * #G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered * with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a * possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching * stops at the partial match. * When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD * are set, the latter takes precedence. * * There were formerly some restrictions on the pattern for partial matching. * The restrictions no longer apply. * * See pcrepartial(3) for more information on partial matching. * * Returns: %TRUE if the match was partial, %FALSE otherwise * Since: 2.14 */ /** * g_match_info_matches: * @match_info: a #GMatchInfo structure * * Returns whether the previous match operation succeeded. * * Returns: %TRUE if the previous match operation succeeded, * %FALSE otherwise * Since: 2.14 */ /** * g_match_info_next: * @match_info: a #GMatchInfo structure * @error: location to store the error occurring, or %NULL to ignore errors * * Scans for the next match using the same parameters of the previous * call to g_regex_match_full() or g_regex_match() that returned * @match_info. * * The match is done on the string passed to the match function, so you * cannot free it before calling this function. * * Returns: %TRUE is the string matched, %FALSE otherwise * Since: 2.14 */ /** * g_match_info_ref: * @match_info: a #GMatchInfo * * Increases reference count of @match_info by 1. * * Returns: @match_info * Since: 2.30 */ /** * g_match_info_unref: * @match_info: a #GMatchInfo * * Decreases reference count of @match_info by 1. When reference count drops * to zero, it frees all the memory associated with the match_info structure. * * Since: 2.30 */ /** * g_mem_gc_friendly: * * This variable is %TRUE if the `G_DEBUG` environment variable * includes the key `gc-friendly`. */ /** * g_mem_is_system_malloc: * * Checks whether the allocator used by g_malloc() is the system's * malloc implementation. If it returns %TRUE memory allocated with * malloc() can be used interchangeable with memory allocated using g_malloc(). * This function is useful for avoiding an extra copy of allocated memory returned * by a non-GLib-based API. * * A different allocator can be set using g_mem_set_vtable(). * * Returns: if %TRUE, malloc() and g_malloc() can be mixed. */ /** * g_mem_profile: * * Outputs a summary of memory usage. * * It outputs the frequency of allocations of different sizes, * the total number of bytes which have been allocated, * the total number of bytes which have been freed, * and the difference between the previous two values, i.e. the number of bytes * still in use. * * Note that this function will not output anything unless you have * previously installed the #glib_mem_profiler_table with g_mem_set_vtable(). */ /** * g_mem_set_vtable: * @vtable: table of memory allocation routines. * * Sets the #GMemVTable to use for memory allocation. You can use this * to provide custom memory allocation routines. * * The @vtable only needs to provide malloc(), realloc(), and free() * functions; GLib can provide default implementations of the others. * The malloc() and realloc() implementations should return %NULL on * failure, GLib will handle error-checking for you. @vtable is copied, * so need not persist after this function has been called. * * Note that this function must be called before using any other GLib * functions. */ /** * g_memdup: * @mem: the memory to copy. * @byte_size: the number of bytes to copy. * * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it * from @mem. If @mem is %NULL it returns %NULL. * * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem * is %NULL. */ /** * g_memmove: * @dest: the destination address to copy the bytes to. * @src: the source address to copy the bytes from. * @len: the number of bytes to copy. * * Copies a block of memory @len bytes long, from @src to @dest. * The source and destination areas may overlap. * * Deprecated: 2.40: Just use memmove(). */ /** * g_message: * @...: format string, followed by parameters to insert * into the format string (as with printf()) * * A convenience function/macro to log a normal message. * * 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. */ /** * g_mkdir: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * @mode: permissions to use for the newly created directory * * A wrapper for the POSIX mkdir() function. The mkdir() function * attempts to create a directory with the given name and permissions. * The mode argument is ignored on Windows. * * See your C library manual for more details about mkdir(). * * Returns: 0 if the directory was successfully created, -1 if an error * occurred * Since: 2.6 */ /** * g_mkdir_with_parents: * @pathname: a pathname in the GLib file name encoding * @mode: permissions to use for newly created directories * * Create a directory if it doesn't already exist. Create intermediate * parent directories as needed, too. * * Returns: 0 if the directory already exists, or was successfully * created. Returns -1 if an error occurred, with errno set. * Since: 2.8 */ /** * g_mkdtemp: * @tmpl: (type filename): template directory name * * Creates a temporary directory. See the mkdtemp() documentation * on most UNIX-like systems. * * The parameter is a string that should follow the rules for * mkdtemp() templates, i.e. contain the string "XXXXXX". * g_mkdtemp() is slightly more flexible than mkdtemp() in that the * sequence does not have to occur at the very end of the template * and you can pass a @mode and additional @flags. The X string will * be modified to form the name of a directory that didn't exist. * The string should be in the GLib file name encoding. Most importantly, * on Windows it should be in UTF-8. * * Returns: A pointer to @tmpl, which has been modified * to hold the directory name. In case of errors, %NULL is * returned and %errno will be set. * Since: 2.30 */ /** * g_mkdtemp_full: * @tmpl: (type filename): template directory name * @mode: permissions to create the temporary directory with * * Creates a temporary directory. See the mkdtemp() documentation * on most UNIX-like systems. * * The parameter is a string that should follow the rules for * mkdtemp() templates, i.e. contain the string "XXXXXX". * g_mkdtemp() is slightly more flexible than mkdtemp() in that the * sequence does not have to occur at the very end of the template * and you can pass a @mode. The X string will be modified to form * the name of a directory that didn't exist. The string should be * in the GLib file name encoding. Most importantly, on Windows it * should be in UTF-8. * * Returns: A pointer to @tmpl, which has been modified * to hold the directory name. In case of errors, %NULL is * returned, and %errno will be set. * Since: 2.30 */ /** * g_mkstemp: * @tmpl: (type filename): template filename * * Opens a temporary file. See the mkstemp() documentation * on most UNIX-like systems. * * The parameter is a string that should follow the rules for * mkstemp() templates, i.e. contain the string "XXXXXX". * g_mkstemp() is slightly more flexible than mkstemp() in that the * sequence does not have to occur at the very end of the template. * The X string will be modified to form the name of a file that * didn't exist. The string should be in the GLib file name encoding. * Most importantly, on Windows it should be in UTF-8. * * Returns: A file handle (as from open()) to the file * opened for reading and writing. The file is opened in binary * mode on platforms where there is a difference. The file handle * should be closed with close(). In case of errors, -1 is * returned and %errno will be set. */ /** * g_mkstemp_full: * @tmpl: (type filename): template filename * @flags: flags to pass to an open() call in addition to O_EXCL * and O_CREAT, which are passed automatically * @mode: permissions to create the temporary file with * * Opens a temporary file. See the mkstemp() documentation * on most UNIX-like systems. * * The parameter is a string that should follow the rules for * mkstemp() templates, i.e. contain the string "XXXXXX". * g_mkstemp_full() is slightly more flexible than mkstemp() * in that the sequence does not have to occur at the very end of the * template and you can pass a @mode and additional @flags. The X * string will be modified to form the name of a file that didn't exist. * The string should be in the GLib file name encoding. Most importantly, * on Windows it should be in UTF-8. * * Returns: A file handle (as from open()) to the file * opened for reading and writing. The file handle should be * closed with close(). In case of errors, -1 is returned * and %errno will be set. * Since: 2.22 */ /** * g_mutex_clear: * @mutex: an initialized #GMutex * * Frees the resources allocated to a mutex with g_mutex_init(). * * This function should not be used with a #GMutex that has been * statically allocated. * * Calling g_mutex_clear() on a locked mutex leads to undefined * behaviour. * * Sine: 2.32 */ /** * g_mutex_init: * @mutex: an uninitialized #GMutex * * Initializes a #GMutex so that it can be used. * * This function is useful to initialize a mutex that has been * allocated on the stack, or as part of a larger structure. * It is not necessary to initialize a mutex that has been * statically allocated. * * |[ * typedef struct { * GMutex m; * ... * } Blob; * * Blob *b; * * b = g_new (Blob, 1); * g_mutex_init (&b->m); * ]| * * To undo the effect of g_mutex_init() when a mutex is no longer * needed, use g_mutex_clear(). * * Calling g_mutex_init() on an already initialized #GMutex leads * to undefined behaviour. * * Since: 2.32 */ /** * g_mutex_lock: * @mutex: a #GMutex * * Locks @mutex. If @mutex is already locked by another thread, the * current thread will block until @mutex is unlocked by the other * thread. * * #GMutex is neither guaranteed to be recursive nor to be * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has * already been locked by the same thread results in undefined behaviour * (including but not limited to deadlocks). */ /** * g_mutex_trylock: * @mutex: a #GMutex * * Tries to lock @mutex. If @mutex is already locked by another thread, * it immediately returns %FALSE. Otherwise it locks @mutex and returns * %TRUE. * * #GMutex is neither guaranteed to be recursive nor to be * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has * already been locked by the same thread results in undefined behaviour * (including but not limited to deadlocks or arbitrary return values). * * Returns: %TRUE if @mutex could be locked */ /** * g_mutex_unlock: * @mutex: a #GMutex * * Unlocks @mutex. If another thread is blocked in a g_mutex_lock() * call for @mutex, it will become unblocked and can lock @mutex itself. * * Calling g_mutex_unlock() on a mutex that is not locked by the * current thread leads to undefined behaviour. */ /** * g_node_child_index: * @node: a #GNode * @data: the data to find * * Gets the position of the first child of a #GNode * which contains the given data. * * Returns: the index of the child of @node which contains * @data, or -1 if the data is not found */ /** * g_node_child_position: * @node: a #GNode * @child: a child of @node * * Gets the position of a #GNode with respect to its siblings. * @child must be a child of @node. The first child is numbered 0, * the second 1, and so on. * * Returns: the position of @child with respect to its siblings */ /** * g_node_children_foreach: * @node: a #GNode * @flags: which types of children are to be visited, one of * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @func: the function to call for each visited node * @data: user data to pass to the function * * Calls a function for each of the children of a #GNode. * Note that it doesn't descend beneath the child nodes. */ /** * g_node_copy: * @node: a #GNode * * Recursively copies a #GNode (but does not deep-copy the data inside the * nodes, see g_node_copy_deep() if you need that). * * Returns: a new #GNode containing the same data pointers */ /** * g_node_copy_deep: * @node: a #GNode * @copy_func: the function which is called to copy the data inside each node, * or %NULL to use the original data. * @data: data to pass to @copy_func * * Recursively copies a #GNode and its data. * * Returns: a new #GNode containing copies of the data in @node. * Since: 2.4 */ /** * g_node_depth: * @node: a #GNode * * Gets the depth of a #GNode. * * If @node is %NULL the depth is 0. The root node has a depth of 1. * For the children of the root node the depth is 2. And so on. * * Returns: the depth of the #GNode */ /** * g_node_destroy: * @root: the root of the tree/subtree to destroy * * Removes @root and its children from the tree, freeing any memory * allocated. */ /** * g_node_find: * @root: the root #GNode of the tree to search * @order: the order in which nodes are visited - %G_IN_ORDER, * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER * @flags: which types of children are to be searched, one of * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @data: the data to find * * Finds a #GNode in a tree. * * Returns: the found #GNode, or %NULL if the data is not found */ /** * g_node_find_child: * @node: a #GNode * @flags: which types of children are to be searched, one of * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @data: the data to find * * Finds the first child of a #GNode with the given data. * * Returns: the found child #GNode, or %NULL if the data is not found */ /** * g_node_first_sibling: * @node: a #GNode * * Gets the first sibling of a #GNode. * This could possibly be the node itself. * * Returns: the first sibling of @node */ /** * g_node_get_root: * @node: a #GNode * * Gets the root of a tree. * * Returns: the root of the tree */ /** * g_node_insert: * @parent: the #GNode to place @node under * @position: the position to place @node at, with respect to its siblings * If position is -1, @node is inserted as the last child of @parent * @node: the #GNode to insert * * Inserts a #GNode beneath the parent at the given position. * * Returns: the inserted #GNode */ /** * g_node_insert_after: * @parent: the #GNode to place @node under * @sibling: the sibling #GNode to place @node after. * If sibling is %NULL, the node is inserted as the first child of @parent. * @node: the #GNode to insert * * Inserts a #GNode beneath the parent after the given sibling. * * Returns: the inserted #GNode */ /** * g_node_insert_before: * @parent: the #GNode to place @node under * @sibling: the sibling #GNode to place @node before. * If sibling is %NULL, the node is inserted as the last child of @parent. * @node: the #GNode to insert * * Inserts a #GNode beneath the parent before the given sibling. * * Returns: the inserted #GNode */ /** * g_node_is_ancestor: * @node: a #GNode * @descendant: a #GNode * * Returns %TRUE if @node is an ancestor of @descendant. * This is true if node is the parent of @descendant, * or if node is the grandparent of @descendant etc. * * Returns: %TRUE if @node is an ancestor of @descendant */ /** * g_node_last_child: * @node: a #GNode (must not be %NULL) * * Gets the last child of a #GNode. * * Returns: the last child of @node, or %NULL if @node has no children */ /** * g_node_last_sibling: * @node: a #GNode * * Gets the last sibling of a #GNode. * This could possibly be the node itself. * * Returns: the last sibling of @node */ /** * g_node_max_height: * @root: a #GNode * * Gets the maximum height of all branches beneath a #GNode. * This is the maximum distance from the #GNode to all leaf nodes. * * If @root is %NULL, 0 is returned. If @root has no children, * 1 is returned. If @root has children, 2 is returned. And so on. * * Returns: the maximum height of the tree beneath @root */ /** * g_node_n_children: * @node: a #GNode * * Gets the number of children of a #GNode. * * Returns: the number of children of @node */ /** * g_node_n_nodes: * @root: a #GNode * @flags: which types of children are to be counted, one of * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * * Gets the number of nodes in a tree. * * Returns: the number of nodes in the tree */ /** * g_node_new: * @data: the data of the new node * * Creates a new #GNode containing the given data. * Used to create the first node in a tree. * * Returns: a new #GNode */ /** * g_node_nth_child: * @node: a #GNode * @n: the index of the desired child * * Gets a child of a #GNode, using the given index. * The first child is at index 0. If the index is * too big, %NULL is returned. * * Returns: the child of @node at index @n */ /** * g_node_prepend: * @parent: the #GNode to place the new #GNode under * @node: the #GNode to insert * * Inserts a #GNode as the first child of the given parent. * * Returns: the inserted #GNode */ /** * g_node_reverse_children: * @node: a #GNode. * * Reverses the order of the children of a #GNode. * (It doesn't change the order of the grandchildren.) */ /** * g_node_traverse: * @root: the root #GNode of the tree to traverse * @order: the order in which nodes are visited - %G_IN_ORDER, * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. * @flags: which types of children are to be visited, one of * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @max_depth: the maximum depth of the traversal. Nodes below this * depth will not be visited. If max_depth is -1 all nodes in * the tree are visited. If depth is 1, only the root is visited. * If depth is 2, the root and its children are visited. And so on. * @func: the function to call for each visited #GNode * @data: user data to pass to the function * * Traverses a tree starting at the given root #GNode. * It calls the given function for each node visited. * The traversal can be halted at any point by returning %TRUE from @func. */ /** * g_node_unlink: * @node: the #GNode to unlink, which becomes the root of a new tree * * Unlinks a #GNode from a tree, resulting in two separate trees. */ /** * g_ntohl: * @val: a 32-bit integer value in network byte order * * Converts a 32-bit integer value from network to host byte order. * * Returns: @val converted to host byte order. */ /** * g_ntohs: * @val: a 16-bit integer value in network byte order * * Converts a 16-bit integer value from network to host byte order. * * Returns: @val converted to host byte order */ /** * g_nullify_pointer: * @nullify_location: the memory address of the pointer. * * Set the pointer at the specified location to %NULL. */ /** * g_on_error_query: * @prg_name: the program name, needed by gdb for the "[S]tack trace" * option. If @prg_name is %NULL, g_get_prgname() is called to get * the program name (which will work correctly if gdk_init() or * gtk_init() has been called) * * Prompts the user with * `[E]xit, [H]alt, show [S]tack trace or [P]roceed`. * This function is intended to be used for debugging use only. * The following example shows how it can be used together with * the g_log() functions. * * |[ * #include * * static void * log_handler (const gchar *log_domain, * GLogLevelFlags log_level, * const gchar *message, * gpointer user_data) * { * g_log_default_handler (log_domain, log_level, message, user_data); * * g_on_error_query (MY_PROGRAM_NAME); * } * * int * main (int argc, char *argv[]) * { * g_log_set_handler (MY_LOG_DOMAIN, * G_LOG_LEVEL_WARNING | * G_LOG_LEVEL_ERROR | * G_LOG_LEVEL_CRITICAL, * log_handler, * NULL); * ... * ]| * * If "[E]xit" is selected, the application terminates with a call * to _exit(0). * * If "[S]tack" trace is selected, g_on_error_stack_trace() is called. * This invokes gdb, which attaches to the current process and shows * a stack trace. The prompt is then shown again. * * If "[P]roceed" is selected, the function returns. * * This function may cause different actions on non-UNIX platforms. */ /** * g_on_error_stack_trace: * @prg_name: the program name, needed by gdb for the "[S]tack trace" * option * * Invokes gdb, which attaches to the current process and shows a * stack trace. Called by g_on_error_query() when the "[S]tack trace" * option is selected. You can get the current process's program name * with g_get_prgname(), assuming that you have called gtk_init() or * gdk_init(). * * This function may cause different actions on non-UNIX platforms. */ /** * g_once: * @once: a #GOnce structure * @func: the #GThreadFunc function associated to @once. This function * is called only once, regardless of the number of times it and * its associated #GOnce struct are passed to g_once(). * @arg: data to be passed to @func * * The first call to this routine by a process with a given #GOnce * struct calls @func with the given argument. Thereafter, subsequent * calls to g_once() with the same #GOnce struct do not call @func * again, but return the stored result of the first call. On return * from g_once(), the status of @once will be %G_ONCE_STATUS_READY. * * For example, a mutex or a thread-specific data key must be created * exactly once. In a threaded environment, calling g_once() ensures * that the initialization is serialized across multiple threads. * * Calling g_once() recursively on the same #GOnce struct in * @func will lead to a deadlock. * * |[ * gpointer * get_debug_flags (void) * { * static GOnce my_once = G_ONCE_INIT; * * g_once (&my_once, parse_debug_flags, NULL); * * return my_once.retval; * } * ]| * * Since: 2.4 */ /** * g_once_init_enter: * @location: location of a static initializable variable containing 0 * * Function to be called when starting a critical initialization * section. The argument @location must point to a static * 0-initialized variable that will be set to a value other than 0 at * the end of the initialization section. In combination with * g_once_init_leave() and the unique address @value_location, it can * be ensured that an initialization section will be executed only once * during a program's life time, and that concurrent threads are * blocked until initialization completed. To be used in constructs * like this: * * |[ * static gsize initialization_value = 0; * * if (g_once_init_enter (&initialization_value)) * { * gsize setup_value = 42; // initialization code here * * g_once_init_leave (&initialization_value, setup_value); * } * * // use initialization_value here * ]| * * Returns: %TRUE if the initialization section should be entered, * %FALSE and blocks otherwise * Since: 2.14 */ /** * g_once_init_leave: * @location: location of a static initializable variable containing 0 * @result: new non-0 value for *@value_location * * Counterpart to g_once_init_enter(). Expects a location of a static * 0-initialized initialization variable, and an initialization value * other than 0. Sets the variable to the initialization value, and * releases concurrent threads blocking in g_once_init_enter() on this * initialization variable. * * Since: 2.14 */ /** * g_open: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * @flags: as in open() * @mode: as in open() * * A wrapper for the POSIX open() function. The open() function is * used to convert a pathname into a file descriptor. * * On POSIX systems file descriptors are implemented by the operating * system. On Windows, it's the C library that implements open() and * file descriptors. The actual Win32 API for opening files is quite * 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 open(). * * Returns: a new file descriptor, or -1 if an error occurred. * The return value can be used exactly like the return value * from open(). * Since: 2.6 */ /** * g_option_context_add_group: * @context: a #GOptionContext * @group: the group to add * * Adds a #GOptionGroup to the @context, so that parsing with @context * will recognize the options in the group. Note that the group will * be freed together with the context when g_option_context_free() is * called, so you must not free the group yourself after adding it * to a context. * * Since: 2.6 */ /** * g_option_context_add_main_entries: * @context: a #GOptionContext * @entries: a %NULL-terminated array of #GOptionEntrys * @translation_domain: (allow-none): a translation domain to use for translating * the `--help` output for the options in @entries * with gettext(), or %NULL * * A convenience function which creates a main group if it doesn't * exist, adds the @entries to it and sets the translation domain. * * Since: 2.6 */ /** * g_option_context_free: * @context: a #GOptionContext * * Frees context and all the groups which have been * added to it. * * Please note that parsed arguments need to be freed separately (see * #GOptionEntry). * * Since: 2.6 */ /** * g_option_context_get_description: * @context: a #GOptionContext * * Returns the description. See g_option_context_set_description(). * * Returns: the description * Since: 2.12 */ /** * g_option_context_get_help: * @context: a #GOptionContext * @main_help: if %TRUE, only include the main group * @group: (allow-none): the #GOptionGroup to create help for, or %NULL * * Returns a formatted, translated help text for the given context. * To obtain the text produced by `--help`, call * `g_option_context_get_help (context, TRUE, NULL)`. * To obtain the text produced by `--help-all`, call * `g_option_context_get_help (context, FALSE, NULL)`. * To obtain the help text for an option group, call * `g_option_context_get_help (context, FALSE, group)`. * * Returns: A newly allocated string containing the help text * Since: 2.14 */ /** * g_option_context_get_help_enabled: * @context: a #GOptionContext * * Returns whether automatic `--help` generation * is turned on for @context. See g_option_context_set_help_enabled(). * * Returns: %TRUE if automatic help generation is turned on. * Since: 2.6 */ /** * g_option_context_get_ignore_unknown_options: * @context: a #GOptionContext * * Returns whether unknown options are ignored or not. See * g_option_context_set_ignore_unknown_options(). * * Returns: %TRUE if unknown options are ignored. * Since: 2.6 */ /** * g_option_context_get_main_group: * @context: a #GOptionContext * * Returns a pointer to the main group of @context. * * Returns: the main group of @context, or %NULL if @context doesn't * have a main group. Note that group belongs to @context and should * not be modified or freed. * Since: 2.6 */ /** * g_option_context_get_summary: * @context: a #GOptionContext * * Returns the summary. See g_option_context_set_summary(). * * Returns: the summary * Since: 2.12 */ /** * g_option_context_new: * @parameter_string: (allow-none): a string which is displayed in * the first line of `--help` output, after the usage summary * `programname [OPTION...]` * * Creates a new option context. * * The @parameter_string can serve multiple purposes. It can be used * to add descriptions for "rest" arguments, which are not parsed by * the #GOptionContext, typically something like "FILES" or * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for * collecting "rest" arguments, GLib handles this automatically by * using the @arg_description of the corresponding #GOptionEntry in * the usage summary. * * Another usage is to give a short summary of the program * functionality, like " - frob the strings", which will be displayed * in the same line as the usage. For a longer description of the * program functionality that should be displayed as a paragraph * below the usage line, use g_option_context_set_summary(). * * Note that the @parameter_string is translated using the * function set with g_option_context_set_translate_func(), so * it should normally be passed untranslated. * * Returns: a newly created #GOptionContext, which must be * freed with g_option_context_free() after use. * Since: 2.6 */ /** * g_option_context_parse: * @context: a #GOptionContext * @argc: (inout) (allow-none): a pointer to the number of command line arguments * @argv: (inout) (array length=argc) (allow-none): a pointer to the array of command line arguments * @error: a return location for errors * * Parses the command line arguments, recognizing options * which have been added to @context. A side-effect of * calling this function is that g_set_prgname() will be * called. * * If the parsing is successful, any parsed arguments are * removed from the array and @argc and @argv are updated * accordingly. A '--' option is stripped from @argv * unless there are unparsed options before and after it, * or some of the options after it start with '-'. In case * of an error, @argc and @argv are left unmodified. * * If automatic `--help` support is enabled * (see g_option_context_set_help_enabled()), and the * @argv array contains one of the recognized help options, * this function will produce help output to stdout and * call `exit (0)`. * * Note that function depends on the [current locale][setlocale] for * automatic character set conversion of string and filename * arguments. * * Returns: %TRUE if the parsing was successful, * %FALSE if an error occurred * Since: 2.6 */ /** * g_option_context_parse_strv: * @context: a #GOptionContext * @arguments: (inout) (array null-terminated=1): a pointer to the * command line arguments (which must be in UTF-8 on Windows) * @error: a return location for errors * * Parses the command line arguments. * * This function is similar to g_option_context_parse() except that it * respects the normal memory rules when dealing with a strv instead of * assuming that the passed-in array is the argv of the main function. * * In particular, strings that are removed from the arguments list will * be freed using g_free(). * * On Windows, the strings are expected to be in UTF-8. This is in * contrast to g_option_context_parse() which expects them to be in the * system codepage, which is how they are passed as @argv to main(). * See g_win32_get_command_line() for a solution. * * This function is useful if you are trying to use #GOptionContext with * #GApplication. * * Returns: %TRUE if the parsing was successful, * %FALSE if an error occurred * Since: 2.40 */ /** * g_option_context_set_description: * @context: a #GOptionContext * @description: (allow-none): a string to be shown in `--help` output * after the list of options, or %NULL * * Adds a string to be displayed in `--help` output after the list * of options. This text often includes a bug reporting address. * * Note that the summary is translated (see * g_option_context_set_translate_func()). * * Since: 2.12 */ /** * g_option_context_set_help_enabled: * @context: a #GOptionContext * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it * * Enables or disables automatic generation of `--help` output. * By default, g_option_context_parse() recognizes `--help`, `-h`, * `-?`, `--help-all` and `--help-groupname` and creates suitable * output to stdout. * * Since: 2.6 */ /** * g_option_context_set_ignore_unknown_options: * @context: a #GOptionContext * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce * an error when unknown options are met * * Sets whether to ignore unknown options or not. If an argument is * ignored, it is left in the @argv array after parsing. By default, * g_option_context_parse() treats unknown options as error. * * This setting does not affect non-option arguments (i.e. arguments * which don't start with a dash). But note that GOption cannot reliably * determine whether a non-option belongs to a preceding unknown option. * * Since: 2.6 */ /** * g_option_context_set_main_group: * @context: a #GOptionContext * @group: the group to set as main group * * Sets a #GOptionGroup as main group of the @context. * This has the same effect as calling g_option_context_add_group(), * the only difference is that the options in the main group are * treated differently when generating `--help` output. * * Since: 2.6 */ /** * g_option_context_set_summary: * @context: a #GOptionContext * @summary: (allow-none): a string to be shown in `--help` output * before the list of options, or %NULL * * Adds a string to be displayed in `--help` output before the list * of options. This is typically a summary of the program functionality. * * Note that the summary is translated (see * g_option_context_set_translate_func() and * g_option_context_set_translation_domain()). * * Since: 2.12 */ /** * g_option_context_set_translate_func: * @context: a #GOptionContext * @func: (allow-none): the #GTranslateFunc, or %NULL * @data: (allow-none): user data to pass to @func, or %NULL * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL * * Sets the function which is used to translate the contexts * user-visible strings, for `--help` output. If @func is %NULL, * strings are not translated. * * Note that option groups have their own translation functions, * this function only affects the @parameter_string (see g_option_context_new()), * the summary (see g_option_context_set_summary()) and the description * (see g_option_context_set_description()). * * If you are using gettext(), you only need to set the translation * domain, see g_option_context_set_translation_domain(). * * Since: 2.12 */ /** * g_option_context_set_translation_domain: * @context: a #GOptionContext * @domain: the domain to use * * A convenience function to use gettext() for translating * user-visible strings. * * Since: 2.12 */ /** * g_option_group_add_entries: * @group: a #GOptionGroup * @entries: a %NULL-terminated array of #GOptionEntrys * * Adds the options specified in @entries to @group. * * Since: 2.6 */ /** * g_option_group_free: * @group: a #GOptionGroup * * Frees a #GOptionGroup. Note that you must not free groups * which have been added to a #GOptionContext. * * Since: 2.6 */ /** * g_option_group_new: * @name: the name for the option group, this is used to provide * help for the options in this group with `--help-`@name * @description: a description for this group to be shown in * `--help`. This string is translated using the translation * domain or translation function of the group * @help_description: a description for the `--help-`@name option. * This string is translated using the translation domain or translation function * of the group * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks, * the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL * @destroy: (allow-none): a function that will be called to free @user_data, or %NULL * * Creates a new #GOptionGroup. * * Returns: a newly created option group. It should be added * to a #GOptionContext or freed with g_option_group_free(). * Since: 2.6 */ /** * g_option_group_set_error_hook: * @group: a #GOptionGroup * @error_func: a function to call when an error occurs * * Associates a function with @group which will be called * from g_option_context_parse() when an error occurs. * * Note that the user data to be passed to @error_func can be * specified when constructing the group with g_option_group_new(). * * Since: 2.6 */ /** * g_option_group_set_parse_hooks: * @group: a #GOptionGroup * @pre_parse_func: (allow-none): a function to call before parsing, or %NULL * @post_parse_func: (allow-none): a function to call after parsing, or %NULL * * Associates two functions with @group which will be called * from g_option_context_parse() before the first option is parsed * and after the last option has been parsed, respectively. * * Note that the user data to be passed to @pre_parse_func and * @post_parse_func can be specified when constructing the group * with g_option_group_new(). * * Since: 2.6 */ /** * g_option_group_set_translate_func: * @group: a #GOptionGroup * @func: (allow-none): the #GTranslateFunc, or %NULL * @data: (allow-none): user data to pass to @func, or %NULL * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL * * Sets the function which is used to translate user-visible strings, * for `--help` output. Different groups can use different * #GTranslateFuncs. If @func is %NULL, strings are not translated. * * If you are using gettext(), you only need to set the translation * domain, see g_option_group_set_translation_domain(). * * Since: 2.6 */ /** * g_option_group_set_translation_domain: * @group: a #GOptionGroup * @domain: the domain to use * * A convenience function to use gettext() for translating * user-visible strings. * * Since: 2.6 */ /** * g_parse_debug_string: * @string: (allow-none): a list of debug options separated by colons, spaces, or * commas, or %NULL. * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate * strings with bit flags. * @nkeys: the number of #GDebugKeys in the array. * * Parses a string containing debugging options * into a %guint containing bit flags. This is used * within GDK and GTK+ to parse the debug options passed on the * command line or through environment variables. * * If @string is equal to "all", all flags are set. Any flags * specified along with "all" in @string are inverted; thus, * "all,foo,bar" or "foo,bar,all" sets all flags except those * corresponding to "foo" and "bar". * * If @string is equal to "help", all the available keys in @keys * are printed out to standard error. * * Returns: the combined set of bit flags. */ /** * g_path_get_basename: * @file_name: the name of the file * * Gets the last component of the filename. * * If @file_name ends with a directory separator it gets the component * before the last slash. If @file_name consists only of directory * separators (and on Windows, possibly a drive letter), a single * separator is returned. If @file_name is empty, it gets ".". * * Returns: a newly allocated string containing the last * component of the filename */ /** * g_path_get_dirname: * @file_name: the name of the file * * Gets the directory components of a file name. * * If the file name has no directory components "." is returned. * The returned string should be freed when no longer needed. * * Returns: the directory components of the file */ /** * g_path_is_absolute: * @file_name: a file name * * Returns %TRUE if the given @file_name is an absolute file name. * Note that this is a somewhat vague concept on Windows. * * On POSIX systems, an absolute file name is well-defined. It always * starts from the single root directory. For example "/usr/local". * * On Windows, the concepts of current drive and drive-specific * current directory introduce vagueness. This function interprets as * an absolute file name one that either begins with a directory * separator such as "\Users\tml" or begins with the root on a drive, * for example "C:\Windows". The first case also includes UNC paths * such as "\\myserver\docs\foo". In all cases, either slashes or * backslashes are accepted. * * Note that a file name relative to the current drive root does not * truly specify a file uniquely over time and across processes, as * the current drive is a per-process value and can be changed. * * File names relative the current directory on some specific drive, * such as "D:foo/bar", are not interpreted as absolute by this * function, but they obviously are not relative to the normal current * directory as returned by getcwd() or g_get_current_dir() * either. Such paths should be avoided, or need to be handled using * Windows-specific code. * * Returns: %TRUE if @file_name is absolute */ /** * g_path_skip_root: * @file_name: a file name * * Returns a pointer into @file_name after the root component, * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name * is not an absolute path it returns %NULL. * * Returns: a pointer into @file_name after the root component */ /** * g_pattern_match: * @pspec: a #GPatternSpec * @string_length: the length of @string (in bytes, i.e. strlen(), * not g_utf8_strlen()) * @string: the UTF-8 encoded string to match * @string_reversed: (allow-none): the reverse of @string or %NULL * * Matches a string against a compiled pattern. Passing the correct * length of the string given is mandatory. The reversed string can be * omitted by passing %NULL, this is more efficient if the reversed * version of the string to be matched is not at hand, as * g_pattern_match() will only construct it if the compiled pattern * requires reverse matches. * * Note that, if the user code will (possibly) match a string against a * multitude of patterns containing wildcards, chances are high that * some patterns will require a reversed string. In this case, it's * more efficient to provide the reversed string to avoid multiple * constructions thereof in the various calls to g_pattern_match(). * * Note also that the reverse of a UTF-8 encoded string can in general * not be obtained by g_strreverse(). This works only if the string * does not contain any multibyte characters. GLib offers the * g_utf8_strreverse() function to reverse UTF-8 encoded strings. * * Returns: %TRUE if @string matches @pspec */ /** * g_pattern_match_simple: * @pattern: the UTF-8 encoded pattern * @string: the UTF-8 encoded string to match * * Matches a string against a pattern given as a string. If this * function is to be called in a loop, it's more efficient to compile * the pattern once with g_pattern_spec_new() and call * g_pattern_match_string() repeatedly. * * Returns: %TRUE if @string matches @pspec */ /** * g_pattern_match_string: * @pspec: a #GPatternSpec * @string: the UTF-8 encoded string to match * * Matches a string against a compiled pattern. If the string is to be * matched against more than one pattern, consider using * g_pattern_match() instead while supplying the reversed string. * * Returns: %TRUE if @string matches @pspec */ /** * g_pattern_spec_equal: * @pspec1: a #GPatternSpec * @pspec2: another #GPatternSpec * * Compares two compiled pattern specs and returns whether they will * match the same set of strings. * * Returns: Whether the compiled patterns are equal */ /** * g_pattern_spec_free: * @pspec: a #GPatternSpec * * Frees the memory allocated for the #GPatternSpec. */ /** * g_pattern_spec_new: * @pattern: a zero-terminated UTF-8 encoded string * * Compiles a pattern to a #GPatternSpec. * * Returns: a newly-allocated #GPatternSpec */ /** * g_pointer_bit_lock: * @address: a pointer to a #gpointer-sized value * @lock_bit: a bit value between 0 and 31 * * This is equivalent to g_bit_lock, but working on pointers (or other * pointer-sized values). * * For portability reasons, you may only lock on the bottom 32 bits of * the pointer. * * Since: 2.30 */ /** * g_pointer_bit_trylock: * @address: a pointer to a #gpointer-sized value * @lock_bit: a bit value between 0 and 31 * * This is equivalent to g_bit_trylock, but working on pointers (or * other pointer-sized values). * * For portability reasons, you may only lock on the bottom 32 bits of * the pointer. * * Returns: %TRUE if the lock was acquired * Since: 2.30 */ /** * g_pointer_bit_unlock: * @address: a pointer to a #gpointer-sized value * @lock_bit: a bit value between 0 and 31 * * This is equivalent to g_bit_unlock, but working on pointers (or other * pointer-sized values). * * For portability reasons, you may only lock on the bottom 32 bits of * the pointer. * * Since: 2.30 */ /** * g_poll: * @fds: file descriptors to poll * @nfds: the number of file descriptors in @fds * @timeout: amount of time to wait, in milliseconds, or -1 to wait forever * * Polls @fds, as with the poll() system call, but portably. (On * systems that don't have poll(), it is emulated using select().) * This is used internally by #GMainContext, but it can be called * directly if you need to block until a file descriptor is ready, but * don't want to run the full main loop. * * Each element of @fds is a #GPollFD describing a single file * descriptor to poll. The %fd field indicates the file descriptor, * and the %events field indicates the events to poll for. On return, * the %revents fields will be filled with the events that actually * occurred. * * On POSIX systems, the file descriptors in @fds can be any sort of * file descriptor, but the situation is much more complicated on * Windows. If you need to use g_poll() in code that has to run on * Windows, the easiest solution is to construct all of your * #GPollFDs with g_io_channel_win32_make_pollfd(). * * Returns: the number of entries in @fds whose %revents fields * were filled in, or 0 if the operation timed out, or -1 on error or * if the call was interrupted. * Since: 2.20 */ /** * g_prefix_error: * @err: (allow-none): a return location for a #GError, or %NULL * @format: printf()-style format string * @...: arguments to @format * * Formats a string according to @format and prefix it to an existing * error message. If @err is %NULL (ie: no error variable) then do * nothing. * * If *@err is %NULL (ie: an error variable is present but there is no * error condition) then also do nothing. Whether or not it makes sense * to take advantage of this feature is up to you. * * Since: 2.16 */ /** * g_print: * @format: the message format. See the printf() documentation * @...: the parameters to insert into the format string * * Outputs a formatted message via the print handler. * The default print handler simply outputs the message to stdout, without * appending a trailing new-line character. Typically, @format should end with * its own new-line character. * * g_print() should not be used from within libraries for debugging * messages, since it may be redirected by applications to special * purpose message windows or even files. Instead, libraries should * use g_log(), or the convenience functions g_message(), g_warning() * and g_error(). */ /** * g_printerr: * @format: the message format. See the printf() documentation * @...: the parameters to insert into the format string * * Outputs a formatted message via the error message handler. * The default handler simply outputs the message to stderr, without appending * a trailing new-line character. Typically, @format should end with its own * new-line character. * * g_printerr() should not be used from within libraries. * Instead g_log() should be used, or the convenience functions * g_message(), g_warning() and g_error(). */ /** * g_printf: * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard printf() function which supports * positional parameters, as specified in the Single Unix Specification. * * As with the standard printf(), this does not automatically append a trailing * new-line character to the message, so typically @format should end with its * own new-line character. * * Returns: the number of bytes printed. * Since: 2.2 */ /** * g_printf_string_upper_bound: * @format: the format string. See the printf() documentation * @args: the parameters to be inserted into the format string * * Calculates the maximum space needed to store the output * of the sprintf() function. * * Returns: the maximum space needed to store the formatted string */ /** * g_private_get: * @key: a #GPrivate * * Returns the current value of the thread local variable @key. * * If the value has not yet been set in this thread, %NULL is returned. * Values are never copied between threads (when a new thread is * created, for example). * * Returns: the thread-local value */ /** * g_private_replace: * @key: a #GPrivate * @value: the new value * * Sets the thread local variable @key to have the value @value in the * current thread. * * This function differs from g_private_set() in the following way: if * the previous value was non-%NULL then the #GDestroyNotify handler for * @key is run on it. * * Since: 2.32 */ /** * g_private_set: * @key: a #GPrivate * @value: the new value * * Sets the thread local variable @key to have the value @value in the * current thread. * * This function differs from g_private_replace() in the following way: * the #GDestroyNotify for @key is not called on the old value. */ /** * g_propagate_error: * @dest: error return location * @src: error to move into the return location * * If @dest is %NULL, free @src; otherwise, moves @src into *@dest. * The error variable @dest points to must be %NULL. */ /** * g_propagate_prefixed_error: * @dest: error return location * @src: error to move into the return location * @format: printf()-style format string * @...: arguments to @format * * If @dest is %NULL, free @src; otherwise, moves @src into *@dest. * *@dest must be %NULL. After the move, add a prefix as with * g_prefix_error(). * * Since: 2.16 */ /** * g_ptr_array_add: * @array: a #GPtrArray * @data: the pointer to add * * Adds a pointer to the end of the pointer array. The array will grow * in size automatically if necessary. */ /** * g_ptr_array_foreach: * @array: a #GPtrArray * @func: the function to call for each array element * @user_data: user data to pass to the function * * Calls a function for each element of a #GPtrArray. * * Since: 2.4 */ /** * g_ptr_array_free: * @array: a #GPtrArray * @free_seg: if %TRUE the actual pointer array is freed as well * * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE * it frees the memory block holding the elements as well. Pass %FALSE * if you want to free the #GPtrArray wrapper but preserve the * underlying array for use elsewhere. If the reference count of @array * is greater than one, the #GPtrArray wrapper is preserved but the * size of @array will be set to zero. * * If array contents point to dynamically-allocated memory, they should * be freed separately if @free_seg is %TRUE and no #GDestroyNotify * function has been set for @array. * * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. * The pointer array should be freed using g_free(). */ /** * g_ptr_array_index: * @array: a #GPtrArray * @index_: the index of the pointer to return * * Returns the pointer at the given index of the pointer array. * * This does not perform bounds checking on the given @index_, * so you are responsible for checking it against the array length. * * Returns: the pointer at the given index */ /** * g_ptr_array_insert: * @array: a #GPtrArray * @index_: the index to place the new element at, or -1 to append * @data: the pointer to add. * * Inserts an element into the pointer array at the given index. The * array will grow in size automatically if necessary. * * Since: 2.40 */ /** * g_ptr_array_new: * * Creates a new #GPtrArray with a reference count of 1. * * Returns: the new #GPtrArray */ /** * g_ptr_array_new_full: * @reserved_size: number of pointers preallocated * @element_free_func: (allow-none): A function to free elements with * destroy @array or %NULL * * Creates a new #GPtrArray with @reserved_size pointers preallocated * and a reference count of 1. This avoids frequent reallocation, if * you are going to add many pointers to the array. Note however that * the size of the array is still 0. It also set @element_free_func * for freeing each element when the array is destroyed either via * g_ptr_array_unref(), when g_ptr_array_free() is called with * @free_segment set to %TRUE or when removing elements. * * Returns: A new #GPtrArray * Since: 2.30 */ /** * g_ptr_array_new_with_free_func: * @element_free_func: (allow-none): A function to free elements with * destroy @array or %NULL * * Creates a new #GPtrArray with a reference count of 1 and use * @element_free_func for freeing each element when the array is destroyed * either via g_ptr_array_unref(), when g_ptr_array_free() is called with * @free_segment set to %TRUE or when removing elements. * * Returns: A new #GPtrArray * Since: 2.22 */ /** * g_ptr_array_ref: * @array: a #GPtrArray * * 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 #GPtrArray * Since: 2.22 */ /** * g_ptr_array_remove: * @array: a #GPtrArray * @data: the pointer to remove * * Removes the first occurrence of the given pointer from the pointer * array. The following elements are moved down one place. If @array * has a non-%NULL #GDestroyNotify function it is called for the * removed element. * * It returns %TRUE if the pointer was removed, or %FALSE if the * pointer was not found. * * Returns: %TRUE if the pointer is removed, %FALSE if the pointer * is not found in the array */ /** * g_ptr_array_remove_fast: * @array: a #GPtrArray * @data: the pointer to remove * * Removes the first occurrence of the given pointer from the pointer * array. The last element in the array is used to fill in the space, * so this function does not preserve the order of the array. But it * is faster than g_ptr_array_remove(). If @array has a non-%NULL * #GDestroyNotify function it is called for the removed element. * * It returns %TRUE if the pointer was removed, or %FALSE if the * pointer was not found. * * Returns: %TRUE if the pointer was found in the array */ /** * g_ptr_array_remove_index: * @array: a #GPtrArray * @index_: the index of the pointer to remove * * Removes the pointer at the given index from the pointer array. * The following elements are moved down one place. If @array has * a non-%NULL #GDestroyNotify function it is called for the removed * element. * * Returns: the pointer which was removed */ /** * g_ptr_array_remove_index_fast: * @array: a #GPtrArray * @index_: the index of the pointer to remove * * Removes the pointer at the given index from the pointer array. * The last element in the array is used to fill in the space, so * this function does not preserve the order of the array. But it * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL * #GDestroyNotify function it is called for the removed element. * * Returns: the pointer which was removed */ /** * g_ptr_array_remove_range: * @array: a @GPtrArray * @index_: the index of the first pointer to remove * @length: the number of pointers to remove * * Removes the given number of pointers starting at the given index * from a #GPtrArray. The following elements are moved to close the * gap. If @array has a non-%NULL #GDestroyNotify function it is * called for the removed elements. * * Returns: the @array * Since: 2.4 */ /** * g_ptr_array_set_free_func: * @array: A #GPtrArray * @element_free_func: (allow-none): A function to free elements with * destroy @array or %NULL * * Sets a function for freeing each element when @array is destroyed * either via g_ptr_array_unref(), when g_ptr_array_free() is called * with @free_segment set to %TRUE or when removing elements. * * Since: 2.22 */ /** * g_ptr_array_set_size: * @array: a #GPtrArray * @length: the new length of the pointer array * * Sets the size of the array. When making the array larger, * newly-added elements will be set to %NULL. When making it smaller, * if @array has a non-%NULL #GDestroyNotify function then it will be * called for the removed elements. */ /** * g_ptr_array_sized_new: * @reserved_size: number of pointers preallocated * * Creates a new #GPtrArray with @reserved_size pointers preallocated * and a reference count of 1. This avoids frequent reallocation, if * you are going to add many pointers to the array. Note however that * the size of the array is still 0. * * Returns: the new #GPtrArray */ /** * g_ptr_array_sort: * @array: a #GPtrArray * @compare_func: comparison function * * Sorts the 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 irst arg is * greater than second arg). * * Note that the comparison function for g_ptr_array_sort() doesn't * take the pointers from the array as arguments, it takes pointers to * the pointers in the array. * * This is guaranteed to be a stable sort since version 2.32. */ /** * g_ptr_array_sort_with_data: * @array: a #GPtrArray * @compare_func: comparison function * @user_data: data to pass to @compare_func * * Like g_ptr_array_sort(), but the comparison function has an extra * user data argument. * * Note that the comparison function for g_ptr_array_sort_with_data() * doesn't take the pointers from the array as arguments, it takes * pointers to the pointers in the array. * * This is guaranteed to be a stable sort since version 2.32. */ /** * g_ptr_array_unref: * @array: A #GPtrArray * * Atomically decrements the reference count of @array by one. If the * reference count drops to 0, the effect is the same as calling * g_ptr_array_free() with @free_segment set to %TRUE. This function * is MT-safe and may be called from any thread. * * Since: 2.22 */ /** * g_qsort_with_data: * @pbase: start of array to sort * @total_elems: elements in the array * @size: size of each element * @compare_func: function to compare elements * @user_data: data to pass to @compare_func * * This is just like the standard C qsort() function, but * the comparison routine accepts a user data argument. * * This is guaranteed to be a stable sort since version 2.32. */ /** * g_quark_from_static_string: * @string: (allow-none): a string * * Gets the #GQuark identifying the given (static) string. If the * string does not currently have an associated #GQuark, a new #GQuark * is created, linked to the given string. * * Note that this function is identical to g_quark_from_string() except * that if a new #GQuark is created the string itself is used rather * than a copy. This saves memory, but can only be used if the string * will continue to exist until the program terminates. It can be used * with statically allocated strings in the main program, but not with * statically allocated memory in dynamically loaded modules, if you * expect to ever unload the module again (e.g. do not use this * function in GTK+ theme engines). * * Returns: the #GQuark identifying the string, or 0 if @string is %NULL */ /** * g_quark_from_string: * @string: (allow-none): a string * * Gets the #GQuark identifying the given string. If the string does * not currently have an associated #GQuark, a new #GQuark is created, * using a copy of the string. * * Returns: the #GQuark identifying the string, or 0 if @string is %NULL */ /** * g_quark_to_string: * @quark: a #GQuark. * * Gets the string associated with the given #GQuark. * * Returns: the string associated with the #GQuark */ /** * g_quark_try_string: * @string: (allow-none): a string * * Gets the #GQuark associated with the given string, or 0 if string is * %NULL or it has no associated #GQuark. * * If you want the GQuark to be created if it doesn't already exist, * use g_quark_from_string() or g_quark_from_static_string(). * * Returns: the #GQuark associated with the string, or 0 if @string is * %NULL or there is no #GQuark associated with it */ /** * g_queue_clear: * @queue: a #GQueue * * Removes all the elements in @queue. If queue elements contain * dynamically-allocated memory, they should be freed first. * * Since: 2.14 */ /** * g_queue_copy: * @queue: a #GQueue * * Copies a @queue. Note that is a shallow copy. If the elements in the * queue consist of pointers to data, the pointers are copied, but the * actual data is not. * * Returns: a copy of @queue * Since: 2.4 */ /** * g_queue_delete_link: * @queue: a #GQueue * @link_: a #GList link that must be part of @queue * * Removes @link_ from @queue and frees it. * * @link_ must be part of @queue. * * Since: 2.4 */ /** * g_queue_find: * @queue: a #GQueue * @data: data to find * * Finds the first link in @queue which contains @data. * * Returns: the first link in @queue which contains @data * Since: 2.4 */ /** * g_queue_find_custom: * @queue: a #GQueue * @data: user data passed to @func * @func: a #GCompareFunc to call for each element. It should return 0 * when the desired element is found * * Finds an element in a #GQueue, using a supplied function to find the * desired element. It iterates over the queue, calling the given function * which should return 0 when the desired element is found. The function * takes two gconstpointer arguments, the #GQueue element's data as the * first argument and the given user data as the second argument. * * Returns: the found link, or %NULL if it wasn't found * Since: 2.4 */ /** * g_queue_foreach: * @queue: a #GQueue * @func: the function to call for each element's data * @user_data: user data to pass to @func * * Calls @func for each element in the queue passing @user_data to the * function. * * Since: 2.4 */ /** * g_queue_free: * @queue: a #GQueue * * Frees the memory allocated for the #GQueue. Only call this function * if @queue was created with g_queue_new(). If queue elements contain * dynamically-allocated memory, they should be freed first. * * If queue elements contain dynamically-allocated memory, you should * either use g_queue_free_full() or free them manually first. */ /** * g_queue_free_full: * @queue: a pointer to a #GQueue * @free_func: the function to be called to free each element's data * * Convenience method, which frees all the memory used by a #GQueue, * and calls the specified destroy function on every element's data. * * Since: 2.32 */ /** * g_queue_get_length: * @queue: a #GQueue * * Returns the number of items in @queue. * * Returns: the number of items in @queue * Since: 2.4 */ /** * g_queue_index: * @queue: a #GQueue * @data: the data to find * * Returns the position of the first element in @queue which contains @data. * * Returns: the position of the first element in @queue which * contains @data, or -1 if no element in @queue contains @data * Since: 2.4 */ /** * g_queue_init: * @queue: an uninitialized #GQueue * * A statically-allocated #GQueue must be initialized with this function * before it can be used. Alternatively you can initialize it with * #G_QUEUE_INIT. It is not necessary to initialize queues created with * g_queue_new(). * * Since: 2.14 */ /** * g_queue_insert_after: * @queue: a #GQueue * @sibling: a #GList link that must be part of @queue * @data: the data to insert * * Inserts @data into @queue after @sibling * * @sibling must be part of @queue * * Since: 2.4 */ /** * g_queue_insert_before: * @queue: a #GQueue * @sibling: a #GList link that must be part of @queue * @data: the data to insert * * Inserts @data into @queue before @sibling. * * @sibling must be part of @queue. * * Since: 2.4 */ /** * g_queue_insert_sorted: * @queue: a #GQueue * @data: the data to insert * @func: the #GCompareDataFunc used to compare elements in the queue. It is * called with two elements of the @queue and @user_data. It should * return 0 if the elements are equal, a negative value if the first * element comes before the second, and a positive value if the second * element comes before the first. * @user_data: user data passed to @func * * Inserts @data into @queue using @func to determine the new position. * * Since: 2.4 */ /** * g_queue_is_empty: * @queue: a #GQueue. * * Returns %TRUE if the queue is empty. * * Returns: %TRUE if the queue is empty */ /** * g_queue_link_index: * @queue: a #GQueue * @link_: a #GList link * * Returns the position of @link_ in @queue. * * Returns: the position of @link_, or -1 if the link is * not part of @queue * Since: 2.4 */ /** * g_queue_new: * * Creates a new #GQueue. * * Returns: a newly allocated #GQueue */ /** * g_queue_peek_head: * @queue: a #GQueue * * Returns the first element of the queue. * * Returns: the data of the first element in the queue, or %NULL * if the queue is empty */ /** * g_queue_peek_head_link: * @queue: a #GQueue * * Returns the first link in @queue. * * Returns: the first link in @queue, or %NULL if @queue is empty * Since: 2.4 */ /** * g_queue_peek_nth: * @queue: a #GQueue * @n: the position of the element * * Returns the @n'th element of @queue. * * Returns: the data for the @n'th element of @queue, * or %NULL if @n is off the end of @queue * Since: 2.4 */ /** * g_queue_peek_nth_link: * @queue: a #GQueue * @n: the position of the link * * Returns the link at the given position * * Returns: the link at the @n'th position, or %NULL * if @n is off the end of the list * Since: 2.4 */ /** * g_queue_peek_tail: * @queue: a #GQueue * * Returns the last element of the queue. * * Returns: the data of the last element in the queue, or %NULL * if the queue is empty */ /** * g_queue_peek_tail_link: * @queue: a #GQueue * * Returns the last link in @queue. * * Returns: the last link in @queue, or %NULL if @queue is empty * Since: 2.4 */ /** * g_queue_pop_head: * @queue: a #GQueue * * Removes the first element of the queue and returns its data. * * Returns: the data of the first element in the queue, or %NULL * if the queue is empty */ /** * g_queue_pop_head_link: * @queue: a #GQueue * * Removes and returns the first element of the queue. * * Returns: the #GList element at the head of the queue, or %NULL * if the queue is empty */ /** * g_queue_pop_nth: * @queue: a #GQueue * @n: the position of the element * * Removes the @n'th element of @queue and returns its data. * * Returns: the element's data, or %NULL if @n is off the end of @queue * Since: 2.4 */ /** * g_queue_pop_nth_link: * @queue: a #GQueue * @n: the link's position * * Removes and returns the link at the given position. * * Returns: the @n'th link, or %NULL if @n is off the end of @queue * Since: 2.4 */ /** * g_queue_pop_tail: * @queue: a #GQueue * * Removes the last element of the queue and returns its data. * * Returns: the data of the last element in the queue, or %NULL * if the queue is empty */ /** * g_queue_pop_tail_link: * @queue: a #GQueue * * Removes and returns the last element of the queue. * * Returns: the #GList element at the tail of the queue, or %NULL * if the queue is empty */ /** * g_queue_push_head: * @queue: a #GQueue. * @data: the data for the new element. * * Adds a new element at the head of the queue. */ /** * g_queue_push_head_link: * @queue: a #GQueue * @link_: a single #GList element, not a list with more than one element * * Adds a new element at the head of the queue. */ /** * g_queue_push_nth: * @queue: a #GQueue * @data: the data for the new element * @n: the position to insert the new element. If @n is negative or * larger than the number of elements in the @queue, the element is * added to the end of the queue. * * Inserts a new element into @queue at the given position. * * Since: 2.4 */ /** * g_queue_push_nth_link: * @queue: a #GQueue * @n: the position to insert the link. If this is negative or larger than * the number of elements in @queue, the link is added to the end of * @queue. * @link_: the link to add to @queue * * Inserts @link into @queue at the given position. * * Since: 2.4 */ /** * g_queue_push_tail: * @queue: a #GQueue * @data: the data for the new element * * Adds a new element at the tail of the queue. */ /** * g_queue_push_tail_link: * @queue: a #GQueue * @link_: a single #GList element, not a list with more than one element * * Adds a new element at the tail of the queue. */ /** * g_queue_remove: * @queue: a #GQueue * @data: the data to remove * * Removes the first element in @queue that contains @data. * * Returns: %TRUE if @data was found and removed from @queue * Since: 2.4 */ /** * g_queue_remove_all: * @queue: a #GQueue * @data: the data to remove * * Remove all elements whose data equals @data from @queue. * * Returns: the number of elements removed from @queue * Since: 2.4 */ /** * g_queue_reverse: * @queue: a #GQueue * * Reverses the order of the items in @queue. * * Since: 2.4 */ /** * g_queue_sort: * @queue: a #GQueue * @compare_func: the #GCompareDataFunc used to sort @queue. This function * is passed two elements of the queue and should return 0 if they are * equal, a negative value if the first comes before the second, and * a positive value if the second comes before the first. * @user_data: user data passed to @compare_func * * Sorts @queue using @compare_func. * * Since: 2.4 */ /** * g_queue_unlink: * @queue: a #GQueue * @link_: a #GList link that must be part of @queue * * Unlinks @link_ so that it will no longer be part of @queue. * The link is not freed. * * @link_ must be part of @queue. * * Since: 2.4 */ /** * g_rand_boolean: * @rand_: a #GRand * * Returns a random #gboolean from @rand_. * This corresponds to a unbiased coin toss. * * Returns: a random #gboolean */ /** * g_rand_copy: * @rand_: a #GRand * * Copies a #GRand into a new one with the same exact state as before. * This way you can take a snapshot of the random number generator for * replaying later. * * Returns: the new #GRand * Since: 2.4 */ /** * g_rand_double: * @rand_: a #GRand * * Returns the next random #gdouble from @rand_ equally distributed over * the range [0..1). * * Returns: a random number */ /** * g_rand_double_range: * @rand_: a #GRand * @begin: lower closed bound of the interval * @end: upper open bound of the interval * * Returns the next random #gdouble from @rand_ equally distributed over * the range [@begin..@end). * * Returns: a random number */ /** * g_rand_free: * @rand_: a #GRand * * Frees the memory allocated for the #GRand. */ /** * g_rand_int: * @rand_: a #GRand * * Returns the next random #guint32 from @rand_ equally distributed over * the range [0..2^32-1]. * * Returns: a random number */ /** * g_rand_int_range: * @rand_: a #GRand * @begin: lower closed bound of the interval * @end: upper open bound of the interval * * Returns the next random #gint32 from @rand_ equally distributed over * the range [@begin..@end-1]. * * Returns: a random number */ /** * g_rand_new: * * Creates a new random number generator initialized with a seed taken * either from `/dev/urandom` (if existing) or from the current time * (as a fallback). * * On Windows, the seed is taken from rand_s(). * * Returns: the new #GRand */ /** * g_rand_new_with_seed: * @seed: a value to initialize the random number generator * * Creates a new random number generator initialized with @seed. * * Returns: the new #GRand */ /** * g_rand_new_with_seed_array: * @seed: an array of seeds to initialize the random number generator * @seed_length: an array of seeds to initialize the random number * generator * * Creates a new random number generator initialized with @seed. * * Returns: the new #GRand * Since: 2.4 */ /** * g_rand_set_seed: * @rand_: a #GRand * @seed: a value to reinitialize the random number generator * * Sets the seed for the random number generator #GRand to @seed. */ /** * g_rand_set_seed_array: * @rand_: a #GRand * @seed: array to initialize with * @seed_length: length of array * * Initializes the random number generator by an array of longs. * Array can be of arbitrary size, though only the first 624 values * are taken. This function is useful if you have many low entropy * seeds, or if you require more then 32 bits of actual entropy for * your application. * * Since: 2.4 */ /** * g_random_boolean: * * Returns a random #gboolean. * This corresponds to a unbiased coin toss. * * Returns: a random #gboolean */ /** * g_random_double: * * Returns a random #gdouble equally distributed over the range [0..1). * * Returns: a random number */ /** * g_random_double_range: * @begin: lower closed bound of the interval * @end: upper open bound of the interval * * Returns a random #gdouble equally distributed over the range * [@begin..@end). * * Returns: a random number */ /** * g_random_int: * * Return a random #guint32 equally distributed over the range * [0..2^32-1]. * * Returns: a random number */ /** * g_random_int_range: * @begin: lower closed bound of the interval * @end: upper open bound of the interval * * Returns a random #gint32 equally distributed over the range * [@begin..@end-1]. * * Returns: a random number */ /** * g_random_set_seed: * @seed: a value to reinitialize the global random number generator * * Sets the seed for the global random number generator, which is used * by the g_random_* functions, to @seed. */ /** * g_realloc: * @mem: (allow-none): the memory to reallocate * @n_bytes: new size of the memory in bytes * * Reallocates the memory pointed to by @mem, so that it now has space for * @n_bytes bytes of memory. It returns the new address of the memory, which may * have been moved. @mem may be %NULL, in which case it's considered to * have zero-length. @n_bytes may be 0, in which case %NULL will be returned * and @mem will be freed unless it is %NULL. * * Returns: the new address of the allocated memory */ /** * g_realloc_n: * @mem: (allow-none): the memory to reallocate * @n_blocks: the number of blocks to allocate * @n_block_bytes: the size of each block in bytes * * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, * but care is taken to detect possible overflow during multiplication. * * Since: 2.24 * Returns: the new address of the allocated memory */ /** * g_rec_mutex_clear: * @rec_mutex: an initialized #GRecMutex * * Frees the resources allocated to a recursive mutex with * g_rec_mutex_init(). * * This function should not be used with a #GRecMutex that has been * statically allocated. * * Calling g_rec_mutex_clear() on a locked recursive mutex leads * to undefined behaviour. * * Sine: 2.32 */ /** * g_rec_mutex_init: * @rec_mutex: an uninitialized #GRecMutex * * Initializes a #GRecMutex so that it can be used. * * This function is useful to initialize a recursive mutex * that has been allocated on the stack, or as part of a larger * structure. * * It is not necessary to initialise a recursive mutex that has been * statically allocated. * * |[ * typedef struct { * GRecMutex m; * ... * } Blob; * * Blob *b; * * b = g_new (Blob, 1); * g_rec_mutex_init (&b->m); * ]| * * Calling g_rec_mutex_init() on an already initialized #GRecMutex * leads to undefined behaviour. * * To undo the effect of g_rec_mutex_init() when a recursive mutex * is no longer needed, use g_rec_mutex_clear(). * * Since: 2.32 */ /** * g_rec_mutex_lock: * @rec_mutex: a #GRecMutex * * Locks @rec_mutex. If @rec_mutex is already locked by another * thread, the current thread will block until @rec_mutex is * unlocked by the other thread. If @rec_mutex is already locked * by the current thread, the 'lock count' of @rec_mutex is increased. * The mutex will only become available again when it is unlocked * as many times as it has been locked. * * Since: 2.32 */ /** * g_rec_mutex_trylock: * @rec_mutex: a #GRecMutex * * Tries to lock @rec_mutex. If @rec_mutex is already locked * by another thread, it immediately returns %FALSE. Otherwise * it locks @rec_mutex and returns %TRUE. * * Returns: %TRUE if @rec_mutex could be locked * Since: 2.32 */ /** * g_rec_mutex_unlock: * @rec_mutex: a #GRecMutex * * Unlocks @rec_mutex. If another thread is blocked in a * g_rec_mutex_lock() call for @rec_mutex, it will become unblocked * and can lock @rec_mutex itself. * * Calling g_rec_mutex_unlock() on a recursive mutex that is not * locked by the current thread leads to undefined behaviour. * * Since: 2.32 */ /** * g_regex_check_replacement: * @replacement: the replacement string * @has_references: (out) (allow-none): location to store information about * references in @replacement or %NULL * @error: location to store error * * Checks whether @replacement is a valid replacement string * (see g_regex_replace()), i.e. that all escape sequences in * it are valid. * * If @has_references is not %NULL then @replacement is checked * for pattern references. For instance, replacement text 'foo\n' * does not contain references and may be evaluated without information * about actual match, but '\0\1' (whole match followed by first * subpattern) requires valid #GMatchInfo object. * * Returns: whether @replacement is a valid replacement string * Since: 2.14 */ /** * g_regex_escape_nul: * @string: the string to escape * @length: the length of @string * * Escapes the nul characters in @string to "\x00". It can be used * to compile a regex with embedded nul characters. * * For completeness, @length can be -1 for a nul-terminated string. * In this case the output string will be of course equal to @string. * * Returns: a newly-allocated escaped string * Since: 2.30 */ /** * g_regex_escape_string: * @string: (array length=length): the string to escape * @length: the length of @string, or -1 if @string is nul-terminated * * Escapes the special characters used for regular expressions * in @string, for instance "a.b*c" becomes "a\.b\*c". This * function is useful to dynamically generate regular expressions. * * @string can contain nul characters that are replaced with "\0", * in this case remember to specify the correct length of @string * in @length. * * Returns: a newly-allocated escaped string * Since: 2.14 */ /** * g_regex_get_capture_count: * @regex: a #GRegex * * Returns the number of capturing subpatterns in the pattern. * * Returns: the number of capturing subpatterns * Since: 2.14 */ /** * g_regex_get_compile_flags: * @regex: a #GRegex * * Returns the compile options that @regex was created with. * * Returns: flags from #GRegexCompileFlags * Since: 2.26 */ /** * g_regex_get_has_cr_or_lf: * @regex: a #GRegex structure * * Checks whether the pattern contains explicit CR or LF references. * * Returns: %TRUE if the pattern contains explicit CR or LF references * Since: 2.34 */ /** * g_regex_get_match_flags: * @regex: a #GRegex * * Returns the match options that @regex was created with. * * Returns: flags from #GRegexMatchFlags * Since: 2.26 */ /** * g_regex_get_max_backref: * @regex: a #GRegex * * Returns the number of the highest back reference * in the pattern, or 0 if the pattern does not contain * back references. * * Returns: the number of the highest back reference * Since: 2.14 */ /** * g_regex_get_max_lookbehind: * @regex: a #GRegex structure * * Gets the number of characters in the longest lookbehind assertion in the * pattern. This information is useful when doing multi-segment matching using * the partial matching facilities. * * Returns: the number of characters in the longest lookbehind assertion. * Since: 2.38 */ /** * g_regex_get_pattern: * @regex: a #GRegex structure * * Gets the pattern string associated with @regex, i.e. a copy of * the string passed to g_regex_new(). * * Returns: the pattern of @regex * Since: 2.14 */ /** * g_regex_get_string_number: * @regex: #GRegex structure * @name: name of the subexpression * * Retrieves the number of the subexpression named @name. * * Returns: The number of the subexpression or -1 if @name * does not exists * Since: 2.14 */ /** * g_regex_match: * @regex: a #GRegex structure from g_regex_new() * @string: the string to scan for matches * @match_options: match options * @match_info: (out) (allow-none): pointer to location where to store * the #GMatchInfo, or %NULL if you do not need it * * Scans for a match in string for the pattern in @regex. * The @match_options are combined with the match options specified * when the @regex structure was created, letting you have more * flexibility in reusing #GRegex structures. * * A #GMatchInfo structure, used to get information on the match, * is stored in @match_info if not %NULL. Note that if @match_info * is not %NULL then it is created even if the function returns %FALSE, * i.e. you must free it regardless if regular expression actually matched. * * To retrieve all the non-overlapping matches of the pattern in * string you can use g_match_info_next(). * * |[ * static void * print_uppercase_words (const gchar *string) * { * // Print all uppercase-only words. * GRegex *regex; * GMatchInfo *match_info; * * regex = g_regex_new ("[A-Z]+", 0, 0, NULL); * g_regex_match (regex, string, 0, &match_info); * while (g_match_info_matches (match_info)) * { * gchar *word = g_match_info_fetch (match_info, 0); * g_print ("Found: %s\n", word); * g_free (word); * g_match_info_next (match_info, NULL); * } * g_match_info_free (match_info); * g_regex_unref (regex); * } * ]| * * @string is not copied and is used in #GMatchInfo internally. If * you use any #GMatchInfo method (except g_match_info_free()) after * freeing or modifying @string then the behaviour is undefined. * * Returns: %TRUE is the string matched, %FALSE otherwise * Since: 2.14 */ /** * g_regex_match_all: * @regex: a #GRegex structure from g_regex_new() * @string: the string to scan for matches * @match_options: match options * @match_info: (out) (allow-none): pointer to location where to store * the #GMatchInfo, or %NULL if you do not need it * * Using the standard algorithm for regular expression matching only * the longest match in the string is retrieved. This function uses * a different algorithm so it can retrieve all the possible matches. * For more documentation see g_regex_match_all_full(). * * A #GMatchInfo structure, used to get information on the match, is * stored in @match_info if not %NULL. Note that if @match_info is * not %NULL then it is created even if the function returns %FALSE, * i.e. you must free it regardless if regular expression actually * matched. * * @string is not copied and is used in #GMatchInfo internally. If * you use any #GMatchInfo method (except g_match_info_free()) after * freeing or modifying @string then the behaviour is undefined. * * Returns: %TRUE is the string matched, %FALSE otherwise * Since: 2.14 */ /** * g_regex_match_all_full: * @regex: a #GRegex structure from g_regex_new() * @string: (array length=string_len): the string to scan for matches * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match options * @match_info: (out) (allow-none): pointer to location where to store * the #GMatchInfo, or %NULL if you do not need it * @error: location to store the error occurring, or %NULL to ignore errors * * Using the standard algorithm for regular expression matching only * the longest match in the string is retrieved, it is not possible * to obtain all the available matches. For instance matching * " " against the pattern "<.*>" * you get " ". * * This function uses a different algorithm (called DFA, i.e. deterministic * finite automaton), so it can retrieve all the possible matches, all * starting at the same point in the string. For instance matching * " " against the pattern "<.*>;" * you would obtain three matches: " ", * " " and "". * * The number of matched strings is retrieved using * g_match_info_get_match_count(). To obtain the matched strings and * their position you can use, respectively, g_match_info_fetch() and * g_match_info_fetch_pos(). Note that the strings are returned in * reverse order of length; that is, the longest matching string is * given first. * * Note that the DFA algorithm is slower than the standard one and it * is not able to capture substrings, so backreferences do not work. * * Setting @start_position 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, such as "\b". * * A #GMatchInfo structure, used to get information on the match, is * stored in @match_info if not %NULL. Note that if @match_info is * not %NULL then it is created even if the function returns %FALSE, * i.e. you must free it regardless if regular expression actually * matched. * * @string is not copied and is used in #GMatchInfo internally. If * you use any #GMatchInfo method (except g_match_info_free()) after * freeing or modifying @string then the behaviour is undefined. * * Returns: %TRUE is the string matched, %FALSE otherwise * Since: 2.14 */ /** * g_regex_match_full: * @regex: a #GRegex structure from g_regex_new() * @string: (array length=string_len): the string to scan for matches * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match options * @match_info: (out) (allow-none): pointer to location where to store * the #GMatchInfo, or %NULL if you do not need it * @error: location to store the error occurring, or %NULL to ignore errors * * Scans for a match in string for the pattern in @regex. * The @match_options are combined with the match options specified * when the @regex structure was created, letting you have more * flexibility in reusing #GRegex structures. * * Setting @start_position 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, such as "\b". * * A #GMatchInfo structure, used to get information on the match, is * stored in @match_info if not %NULL. Note that if @match_info is * not %NULL then it is created even if the function returns %FALSE, * i.e. you must free it regardless if regular expression actually * matched. * * @string is not copied and is used in #GMatchInfo internally. If * you use any #GMatchInfo method (except g_match_info_free()) after * freeing or modifying @string then the behaviour is undefined. * * To retrieve all the non-overlapping matches of the pattern in * string you can use g_match_info_next(). * * |[ * static void * print_uppercase_words (const gchar *string) * { * // Print all uppercase-only words. * GRegex *regex; * GMatchInfo *match_info; * GError *error = NULL; * * regex = g_regex_new ("[A-Z]+", 0, 0, NULL); * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); * while (g_match_info_matches (match_info)) * { * gchar *word = g_match_info_fetch (match_info, 0); * g_print ("Found: %s\n", word); * g_free (word); * g_match_info_next (match_info, &error); * } * g_match_info_free (match_info); * g_regex_unref (regex); * if (error != NULL) * { * g_printerr ("Error while matching: %s\n", error->message); * g_error_free (error); * } * } * ]| * * Returns: %TRUE is the string matched, %FALSE otherwise * Since: 2.14 */ /** * g_regex_match_simple: * @pattern: the regular expression * @string: the string to scan for matches * @compile_options: compile options for the regular expression, or 0 * @match_options: match options, or 0 * * Scans for a match in @string for @pattern. * * This function is equivalent to g_regex_match() but it does not * require to compile the pattern with g_regex_new(), avoiding some * lines of code when you need just to do a match without extracting * substrings, capture counts, and so on. * * If this function is to be called on the same @pattern more than * once, it's more efficient to compile the pattern once with * g_regex_new() and then use g_regex_match(). * * Returns: %TRUE if the string matched, %FALSE otherwise * Since: 2.14 */ /** * g_regex_new: * @pattern: the regular expression * @compile_options: compile options for the regular expression, or 0 * @match_options: match options for the regular expression, or 0 * @error: return location for a #GError * * Compiles the regular expression to an internal form, and does * the initial setup of the #GRegex structure. * * Returns: a #GRegex structure. Call g_regex_unref() when you * are done with it * Since: 2.14 */ /** * g_regex_ref: * @regex: a #GRegex * * Increases reference count of @regex by 1. * * Returns: @regex * Since: 2.14 */ /** * g_regex_replace: * @regex: a #GRegex structure * @string: (array length=string_len): the string to perform matches against * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @replacement: text to replace each match with * @match_options: options for the match * @error: location to store the error occurring, or %NULL to ignore errors * * Replaces all occurrences of the pattern in @regex with the * replacement text. Backreferences of the form '\number' or * '\g' in the replacement text are interpolated by the * number-th captured subexpression of the match, '\g' refers * to the captured subexpression with the given name. '\0' refers * to the complete match, but '\0' followed by a number is the octal * representation of a character. To include a literal '\' in the * replacement, write '\\'. * * There are also escapes that changes the case of the following text: * * - \l: Convert to lower case the next character * - \u: Convert to upper case the next character * - \L: Convert to lower case till \E * - \U: Convert to upper case till \E * - \E: End case modification * * If you do not need to use backreferences use g_regex_replace_literal(). * * The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was * passed to g_regex_new(). If you want to use not UTF-8 encoded stings * you can use g_regex_replace_literal(). * * Setting @start_position 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, such as "\b". * * Returns: a newly allocated string containing the replacements * Since: 2.14 */ /** * g_regex_replace_eval: * @regex: a #GRegex structure from g_regex_new() * @string: (array length=string_len): string to perform matches against * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: options for the match * @eval: a function to call for each match * @user_data: user data to pass to the function * @error: location to store the error occurring, or %NULL to ignore errors * * Replaces occurrences of the pattern in regex with the output of * @eval for that occurrence. * * Setting @start_position 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, such as "\b". * * The following example uses g_regex_replace_eval() to replace multiple * strings at once: * |[ * static gboolean * eval_cb (const GMatchInfo *info, * GString *res, * gpointer data) * { * gchar *match; * gchar *r; * * match = g_match_info_fetch (info, 0); * r = g_hash_table_lookup ((GHashTable *)data, match); * g_string_append (res, r); * g_free (match); * * return FALSE; * } * * ... * * GRegex *reg; * GHashTable *h; * gchar *res; * * h = g_hash_table_new (g_str_hash, g_str_equal); * * g_hash_table_insert (h, "1", "ONE"); * g_hash_table_insert (h, "2", "TWO"); * g_hash_table_insert (h, "3", "THREE"); * g_hash_table_insert (h, "4", "FOUR"); * * reg = g_regex_new ("1|2|3|4", 0, 0, NULL); * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL); * g_hash_table_destroy (h); * * ... * ]| * * Returns: a newly allocated string containing the replacements * Since: 2.14 */ /** * g_regex_replace_literal: * @regex: a #GRegex structure * @string: (array length=string_len): the string to perform matches against * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @replacement: text to replace each match with * @match_options: options for the match * @error: location to store the error occurring, or %NULL to ignore errors * * Replaces all occurrences of the pattern in @regex with the * replacement text. @replacement is replaced literally, to * include backreferences use g_regex_replace(). * * Setting @start_position 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, such as "\b". * * Returns: a newly allocated string containing the replacements * Since: 2.14 */ /** * g_regex_split: * @regex: a #GRegex structure * @string: the string to split with the pattern * @match_options: match time option flags * * Breaks the string on the pattern, and returns an array of the tokens. * If the pattern contains capturing parentheses, then the text for each * of the substrings will also be returned. If the pattern does not match * anywhere in the string, then the whole string is returned as the first * token. * * As a special case, the result of splitting the empty string "" is an * empty vector, not a vector containing a single string. The reason for * this special case is that being able to represent a empty vector is * typically more useful than consistent handling of empty elements. If * you do need to represent empty elements, you'll need to check for the * empty string before calling this function. * * A pattern that can match empty strings splits @string into separate * characters wherever it matches the empty string between characters. * For example splitting "ab c" using as a separator "\s*", you will get * "a", "b" and "c". * * Returns: (transfer full): a %NULL-terminated gchar ** array. Free * it using g_strfreev() * Since: 2.14 */ /** * g_regex_split_full: * @regex: a #GRegex structure * @string: (array length=string_len): the string to split with the pattern * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match time option flags * @max_tokens: the maximum number of tokens to split @string into. * If this is less than 1, the string is split completely * @error: return location for a #GError * * Breaks the string on the pattern, and returns an array of the tokens. * If the pattern contains capturing parentheses, then the text for each * of the substrings will also be returned. If the pattern does not match * anywhere in the string, then the whole string is returned as the first * token. * * As a special case, the result of splitting the empty string "" is an * empty vector, not a vector containing a single string. The reason for * this special case is that being able to represent a empty vector is * typically more useful than consistent handling of empty elements. If * you do need to represent empty elements, you'll need to check for the * empty string before calling this function. * * A pattern that can match empty strings splits @string into separate * characters wherever it matches the empty string between characters. * For example splitting "ab c" using as a separator "\s*", you will get * "a", "b" and "c". * * Setting @start_position 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, such as "\b". * * Returns: (transfer full): a %NULL-terminated gchar ** array. Free * it using g_strfreev() * Since: 2.14 */ /** * g_regex_split_simple: * @pattern: the regular expression * @string: the string to scan for matches * @compile_options: compile options for the regular expression, or 0 * @match_options: match options, or 0 * * Breaks the string on the pattern, and returns an array of * the tokens. If the pattern contains capturing parentheses, * then the text for each of the substrings will also be returned. * If the pattern does not match anywhere in the string, then the * whole string is returned as the first token. * * This function is equivalent to g_regex_split() but it does * not require to compile the pattern with g_regex_new(), avoiding * some lines of code when you need just to do a split without * extracting substrings, capture counts, and so on. * * If this function is to be called on the same @pattern more than * once, it's more efficient to compile the pattern once with * g_regex_new() and then use g_regex_split(). * * As a special case, the result of splitting the empty string "" * is an empty vector, not a vector containing a single string. * The reason for this special case is that being able to represent * a empty vector is typically more useful than consistent handling * of empty elements. If you do need to represent empty elements, * you'll need to check for the empty string before calling this * function. * * A pattern that can match empty strings splits @string into * separate characters wherever it matches the empty string between * characters. For example splitting "ab c" using as a separator * "\s*", you will get "a", "b" and "c". * * Returns: (transfer full): a %NULL-terminated array of strings. Free * it using g_strfreev() * Since: 2.14 */ /** * g_regex_unref: * @regex: a #GRegex * * Decreases reference count of @regex by 1. When reference count drops * to zero, it frees all the memory associated with the regex structure. * * Since: 2.14 */ /** * g_reload_user_special_dirs_cache: * * Resets the cache used for g_get_user_special_dir(), so * that the latest on-disk version is used. Call this only * if you just changed the data on disk yourself. * * Due to threadsafety issues this may cause leaking of strings * that were previously returned from g_get_user_special_dir() * that can't be freed. We ensure to only leak the data for * the directories that actually changed value though. * * Since: 2.22 */ /** * g_remove: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * * A wrapper for the POSIX remove() function. The remove() function * deletes a name from the filesystem. * * See your C library manual for more details about how remove() works * on your system. On Unix, remove() removes also directories, as it * calls unlink() for files and rmdir() for directories. On Windows, * although remove() in the C library only works for files, this * function tries first remove() and then if that fails rmdir(), and * thus works for both files and directories. Note however, that on * Windows, it is in general not possible to remove a file that is * open to some process, or mapped into memory. * * If this function fails on Windows you can't infer too much from the * errno value. rmdir() is tried regardless of what caused remove() to * fail. Any errno value set by remove() will be overwritten by that * set by rmdir(). * * Returns: 0 if the file was successfully removed, -1 if an error * occurred * Since: 2.6 */ /** * g_rename: * @oldfilename: a pathname in the GLib file name encoding (UTF-8 on Windows) * @newfilename: a pathname in the GLib file name encoding * * A wrapper for the POSIX rename() function. The rename() function * renames a file, moving it between directories if required. * * See your C library manual for more details about how rename() works * on your system. It is not possible in general on Windows to rename * a file that is open to some process. * * Returns: 0 if the renaming succeeded, -1 if an error occurred * Since: 2.6 */ /** * g_rmdir: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * * A wrapper for the POSIX rmdir() function. The rmdir() function * deletes a directory from the filesystem. * * See your C library manual for more details about how rmdir() works * on your system. * * Returns: 0 if the directory was successfully removed, -1 if an error * occurred * Since: 2.6 */ /** * g_rw_lock_clear: * @rw_lock: an initialized #GRWLock * * Frees the resources allocated to a lock with g_rw_lock_init(). * * This function should not be used with a #GRWLock that has been * statically allocated. * * Calling g_rw_lock_clear() when any thread holds the lock * leads to undefined behaviour. * * Sine: 2.32 */ /** * g_rw_lock_init: * @rw_lock: an uninitialized #GRWLock * * Initializes a #GRWLock so that it can be used. * * This function is useful to initialize a lock that has been * allocated on the stack, or as part of a larger structure. It is not * necessary to initialise a reader-writer lock that has been statically * allocated. * * |[ * typedef struct { * GRWLock l; * ... * } Blob; * * Blob *b; * * b = g_new (Blob, 1); * g_rw_lock_init (&b->l); * ]| * * To undo the effect of g_rw_lock_init() when a lock is no longer * needed, use g_rw_lock_clear(). * * Calling g_rw_lock_init() on an already initialized #GRWLock leads * to undefined behaviour. * * Since: 2.32 */ /** * g_rw_lock_reader_lock: * @rw_lock: a #GRWLock * * Obtain a read lock on @rw_lock. If another thread currently holds * the write lock on @rw_lock or blocks waiting for it, the current * thread will block. Read locks can be taken recursively. * * It is implementation-defined how many threads are allowed to * hold read locks on the same lock simultaneously. * * Since: 2.32 */ /** * g_rw_lock_reader_trylock: * @rw_lock: a #GRWLock * * Tries to obtain a read lock on @rw_lock and returns %TRUE if * the read lock was successfully obtained. Otherwise it * returns %FALSE. * * Returns: %TRUE if @rw_lock could be locked * Since: 2.32 */ /** * g_rw_lock_reader_unlock: * @rw_lock: a #GRWLock * * Release a read lock on @rw_lock. * * Calling g_rw_lock_reader_unlock() on a lock that is not held * by the current thread leads to undefined behaviour. * * Since: 2.32 */ /** * g_rw_lock_writer_lock: * @rw_lock: a #GRWLock * * Obtain a write lock on @rw_lock. If any thread already holds * a read or write lock on @rw_lock, the current thread will block * until all other threads have dropped their locks on @rw_lock. * * Since: 2.32 */ /** * g_rw_lock_writer_trylock: * @rw_lock: a #GRWLock * * Tries to obtain a write lock on @rw_lock. If any other thread holds * a read or write lock on @rw_lock, it immediately returns %FALSE. * Otherwise it locks @rw_lock and returns %TRUE. * * Returns: %TRUE if @rw_lock could be locked * Since: 2.32 */ /** * g_rw_lock_writer_unlock: * @rw_lock: a #GRWLock * * Release a write lock on @rw_lock. * * Calling g_rw_lock_writer_unlock() on a lock that is not held * by the current thread leads to undefined behaviour. * * Since: 2.32 */ /** * g_scanner_add_symbol: * @scanner: a #GScanner * @symbol: the symbol to add * @value: the value of the symbol * * Adds a symbol to the default scope. * * Deprecated: 2.2: Use g_scanner_scope_add_symbol() instead. */ /** * g_scanner_cur_line: * @scanner: a #GScanner * * Returns the current line in the input stream (counting * from 1). This is the line of the last token parsed via * g_scanner_get_next_token(). * * Returns: the current line */ /** * g_scanner_cur_position: * @scanner: a #GScanner * * Returns the current position in the current line (counting * from 0). This is the position of the last token parsed via * g_scanner_get_next_token(). * * Returns: the current position on the line */ /** * g_scanner_cur_token: * @scanner: a #GScanner * * Gets the current token type. This is simply the @token * field in the #GScanner structure. * * Returns: the current token type */ /** * g_scanner_cur_value: * @scanner: a #GScanner * * Gets the current token value. This is simply the @value * field in the #GScanner structure. * * Returns: the current token value */ /** * g_scanner_destroy: * @scanner: a #GScanner * * Frees all memory used by the #GScanner. */ /** * g_scanner_eof: * @scanner: a #GScanner * * Returns %TRUE if the scanner has reached the end of * the file or text buffer. * * Returns: %TRUE if the scanner has reached the end of * the file or text buffer */ /** * g_scanner_error: * @scanner: a #GScanner * @format: the message format. See the printf() documentation * @...: the parameters to insert into the format string * * Outputs an error message, via the #GScanner message handler. */ /** * g_scanner_foreach_symbol: * @scanner: a #GScanner * @func: the function to call with each symbol * @data: data to pass to the function * * Calls a function for each symbol in the default scope. * * Deprecated: 2.2: Use g_scanner_scope_foreach_symbol() instead. */ /** * g_scanner_freeze_symbol_table: * @scanner: a #GScanner * * There is no reason to use this macro, since it does nothing. * * Deprecated: 2.2: This macro does nothing. */ /** * g_scanner_get_next_token: * @scanner: a #GScanner * * Parses the next token just like g_scanner_peek_next_token() * and also removes it from the input stream. The token data is * placed in the @token, @value, @line, and @position fields of * the #GScanner structure. * * Returns: the type of the token */ /** * g_scanner_input_file: * @scanner: a #GScanner * @input_fd: a file descriptor * * Prepares to scan a file. */ /** * g_scanner_input_text: * @scanner: a #GScanner * @text: the text buffer to scan * @text_len: the length of the text buffer * * Prepares to scan a text buffer. */ /** * g_scanner_lookup_symbol: * @scanner: a #GScanner * @symbol: the symbol to look up * * Looks up a symbol in the current scope and return its value. * If the symbol is not bound in the current scope, %NULL is * returned. * * Returns: the value of @symbol in the current scope, or %NULL * if @symbol is not bound in the current scope */ /** * g_scanner_new: * @config_templ: the initial scanner settings * * Creates a new #GScanner. * * The @config_templ structure specifies the initial settings * of the scanner, which are copied into the #GScanner * @config field. If you pass %NULL then the default settings * are used. * * Returns: the new #GScanner */ /** * g_scanner_peek_next_token: * @scanner: a #GScanner * * Parses the next token, without removing it from the input stream. * The token data is placed in the @next_token, @next_value, @next_line, * and @next_position fields of the #GScanner structure. * * Note that, while the token is not removed from the input stream * (i.e. the next call to g_scanner_get_next_token() will return the * same token), it will not be reevaluated. This can lead to surprising * results when changing scope or the scanner configuration after peeking * the next token. Getting the next token after switching the scope or * configuration will return whatever was peeked before, regardless of * any symbols that may have been added or removed in the new scope. * * Returns: the type of the token */ /** * g_scanner_remove_symbol: * @scanner: a #GScanner * @symbol: the symbol to remove * * Removes a symbol from the default scope. * * Deprecated: 2.2: Use g_scanner_scope_remove_symbol() instead. */ /** * g_scanner_scope_add_symbol: * @scanner: a #GScanner * @scope_id: the scope id * @symbol: the symbol to add * @value: the value of the symbol * * Adds a symbol to the given scope. */ /** * g_scanner_scope_foreach_symbol: * @scanner: a #GScanner * @scope_id: the scope id * @func: the function to call for each symbol/value pair * @user_data: user data to pass to the function * * Calls the given function for each of the symbol/value pairs * in the given scope of the #GScanner. The function is passed * the symbol and value of each pair, and the given @user_data * parameter. */ /** * g_scanner_scope_lookup_symbol: * @scanner: a #GScanner * @scope_id: the scope id * @symbol: the symbol to look up * * Looks up a symbol in a scope and return its value. If the * symbol is not bound in the scope, %NULL is returned. * * Returns: the value of @symbol in the given scope, or %NULL * if @symbol is not bound in the given scope. */ /** * g_scanner_scope_remove_symbol: * @scanner: a #GScanner * @scope_id: the scope id * @symbol: the symbol to remove * * Removes a symbol from a scope. */ /** * g_scanner_set_scope: * @scanner: a #GScanner * @scope_id: the new scope id * * Sets the current scope. * * Returns: the old scope id */ /** * g_scanner_sync_file_offset: * @scanner: a #GScanner * * Rewinds the filedescriptor to the current buffer position * and blows the file read ahead buffer. This is useful for * third party uses of the scanners filedescriptor, which hooks * onto the current scanning position. */ /** * g_scanner_thaw_symbol_table: * @scanner: a #GScanner * * There is no reason to use this macro, since it does nothing. * * Deprecated: 2.2: This macro does nothing. */ /** * g_scanner_unexp_token: * @scanner: a #GScanner * @expected_token: the expected token * @identifier_spec: a string describing how the scanner's user * refers to identifiers (%NULL defaults to "identifier"). * This is used if @expected_token is %G_TOKEN_IDENTIFIER or * %G_TOKEN_IDENTIFIER_NULL. * @symbol_spec: a string describing how the scanner's user refers * to symbols (%NULL defaults to "symbol"). This is used if * @expected_token is %G_TOKEN_SYMBOL or any token value greater * than %G_TOKEN_LAST. * @symbol_name: the name of the symbol, if the scanner's current * token is a symbol. * @message: a message string to output at the end of the * warning/error, or %NULL. * @is_error: if %TRUE it is output as an error. If %FALSE it is * output as a warning. * * Outputs a message through the scanner's msg_handler, * resulting from an unexpected token in the input stream. * Note that you should not call g_scanner_peek_next_token() * followed by g_scanner_unexp_token() without an intermediate * call to g_scanner_get_next_token(), as g_scanner_unexp_token() * evaluates the scanner's current token (not the peeked token) * to construct part of the message. */ /** * g_scanner_warn: * @scanner: a #GScanner * @format: the message format. See the printf() documentation * @...: the parameters to insert into the format string * * Outputs a warning message, via the #GScanner message handler. */ /** * g_sequence_append: * @seq: a #GSequence * @data: the data for the new item * * Adds a new item to the end of @seq. * * Returns: an iterator pointing to the new item * Since: 2.14 */ /** * g_sequence_foreach: * @seq: a #GSequence * @func: the function to call for each item in @seq * @user_data: user data passed to @func * * Calls @func for each item in the sequence passing @user_data * to the function. * * Since: 2.14 */ /** * g_sequence_foreach_range: * @begin: a #GSequenceIter * @end: a #GSequenceIter * @func: a #GFunc * @user_data: user data passed to @func * * Calls @func for each item in the range (@begin, @end) passing * @user_data to the function. * * Since: 2.14 */ /** * g_sequence_free: * @seq: a #GSequence * * Frees the memory allocated for @seq. If @seq has a data destroy * function associated with it, that function is called on all items * in @seq. * * Since: 2.14 */ /** * g_sequence_get: * @iter: a #GSequenceIter * * Returns the data that @iter points to. * * Returns: the data that @iter points to * Since: 2.14 */ /** * g_sequence_get_begin_iter: * @seq: a #GSequence * * Returns the begin iterator for @seq. * * Returns: the begin iterator for @seq. * Since: 2.14 */ /** * g_sequence_get_end_iter: * @seq: a #GSequence * * Returns the end iterator for @seg * * Returns: the end iterator for @seq * Since: 2.14 */ /** * g_sequence_get_iter_at_pos: * @seq: a #GSequence * @pos: a position in @seq, or -1 for the end * * Returns the iterator at position @pos. If @pos is negative or larger * than the number of items in @seq, the end iterator is returned. * * Returns: The #GSequenceIter at position @pos * Since: 2.14 */ /** * g_sequence_get_length: * @seq: a #GSequence * * Returns the length of @seq * * Returns: the length of @seq * Since: 2.14 */ /** * g_sequence_insert_before: * @iter: a #GSequenceIter * @data: the data for the new item * * Inserts a new item just before the item pointed to by @iter. * * Returns: an iterator pointing to the new item * Since: 2.14 */ /** * g_sequence_insert_sorted: * @seq: a #GSequence * @data: the data to insert * @cmp_func: the function used to compare items in the sequence * @cmp_data: user data passed to @cmp_func. * * Inserts @data into @sequence using @func to determine the new * position. The sequence must already be sorted according to @cmp_func; * otherwise the new position of @data is undefined. * * @cmp_func is called with two items of the @seq and @user_data. * It should return 0 if the items are equal, a negative value * if the first item comes before the second, and a positive value * if the second item comes before the first. * * Returns: a #GSequenceIter pointing to the new item. * Since: 2.14 */ /** * g_sequence_insert_sorted_iter: * @seq: a #GSequence * @data: data for the new item * @iter_cmp: the function used to compare iterators in the sequence * @cmp_data: user data passed to @cmp_func * * Like g_sequence_insert_sorted(), but uses * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as * the compare function. * * @iter_cmp is called with two iterators pointing into @seq. * It should return 0 if the iterators are equal, a negative * value if the first iterator comes before the second, and a * positive value if the second iterator comes before the first. * * It is called with two iterators pointing into @seq. It should * return 0 if the iterators are equal, a negative value if the * first iterator comes before the second, and a positive value * if the second iterator comes before the first. * * Returns: a #GSequenceIter pointing to the new item * Since: 2.14 */ /** * g_sequence_iter_compare: * @a: a #GSequenceIter * @b: a #GSequenceIter * * Returns a negative number if @a comes before @b, 0 if they are equal, * and a positive number if @a comes after @b. * * The @a and @b iterators must point into the same sequence. * * Returns: a negative number if @a comes before @b, 0 if they are * equal, and a positive number if @a comes after @b * Since: 2.14 */ /** * g_sequence_iter_get_position: * @iter: a #GSequenceIter * * Returns the position of @iter * * Returns: the position of @iter * Since: 2.14 */ /** * g_sequence_iter_get_sequence: * @iter: a #GSequenceIter * * Returns the #GSequence that @iter points into. * * Returns: the #GSequence that @iter points into * Since: 2.14 */ /** * g_sequence_iter_is_begin: * @iter: a #GSequenceIter * * Returns whether @iter is the begin iterator * * Returns: whether @iter is the begin iterator * Since: 2.14 */ /** * g_sequence_iter_is_end: * @iter: a #GSequenceIter * * Returns whether @iter is the end iterator * * Returns: Whether @iter is the end iterator * Since: 2.14 */ /** * g_sequence_iter_move: * @iter: a #GSequenceIter * @delta: A positive or negative number indicating how many positions away * from @iter the returned #GSequenceIter will be * * Returns the #GSequenceIter which is @delta positions away from @iter. * If @iter is closer than -@delta positions to the beginning of the sequence, * the begin iterator is returned. If @iter is closer than @delta positions * to the end of the sequence, the end iterator is returned. * * Returns: a #GSequenceIter which is @delta positions away from @iter * Since: 2.14 */ /** * g_sequence_iter_next: * @iter: a #GSequenceIter * * Returns an iterator pointing to the next position after @iter. * If @iter is the end iterator, the end iterator is returned. * * Returns: a #GSequenceIter pointing to the next position after @iter * Since: 2.14 */ /** * g_sequence_iter_prev: * @iter: a #GSequenceIter * * Returns an iterator pointing to the previous position before @iter. * If @iter is the begin iterator, the begin iterator is returned. * * Returns: a #GSequenceIter pointing to the previous position * before @iter * Since: 2.14 */ /** * g_sequence_lookup: * @seq: a #GSequence * @data: data to lookup * @cmp_func: the function used to compare items in the sequence * @cmp_data: user data passed to @cmp_func * * Returns an iterator pointing to the position of the first item found * equal to @data according to @cmp_func and @cmp_data. If more than one * item is equal, it is not guaranteed that it is the first which is * returned. In that case, you can use g_sequence_iter_next() and * g_sequence_iter_prev() to get others. * * @cmp_func is called with two items of the @seq and @user_data. * It should return 0 if the items are equal, a negative value if * the first item comes before the second, and a positive value if * the second item comes before the first. * * This function will fail if the data contained in the sequence is * unsorted. Use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to your sequence or, if * you want to add a large amount of data, call g_sequence_sort() after * doing unsorted insertions. * * Returns: an #GSequenceIter pointing to the position of the * first item found equal to @data according to @cmp_func and * @cmp_data, or %NULL if no such item exists * Since: 2.28 */ /** * g_sequence_lookup_iter: * @seq: a #GSequence * @data: data to lookup * @iter_cmp: the function used to compare iterators in the sequence * @cmp_data: user data passed to @iter_cmp * * Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc * instead of a #GCompareDataFunc as the compare function. * * @iter_cmp is called with two iterators pointing into @seq. * It should return 0 if the iterators are equal, a negative value * if the first iterator comes before the second, and a positive * value if the second iterator comes before the first. * * This function will fail if the data contained in the sequence is * unsorted. Use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to your sequence or, if * you want to add a large amount of data, call g_sequence_sort() after * doing unsorted insertions. * * Returns: an #GSequenceIter pointing to the position of * the first item found equal to @data according to @cmp_func * and @cmp_data, or %NULL if no such item exists * Since: 2.28 */ /** * g_sequence_move: * @src: a #GSequenceIter pointing to the item to move * @dest: a #GSequenceIter pointing to the position to which * the item is moved * * Moves the item pointed to by @src to the position indicated by @dest. * After calling this function @dest will point to the position immediately * after @src. It is allowed for @src and @dest to point into different * sequences. * * Since: 2.14 */ /** * g_sequence_move_range: * @dest: a #GSequenceIter * @begin: a #GSequenceIter * @end: a #GSequenceIter * * Inserts the (@begin, @end) range at the destination pointed to by ptr. * The @begin and @end iters must point into the same sequence. It is * allowed for @dest to point to a different sequence than the one pointed * into by @begin and @end. * * If @dest is NULL, the range indicated by @begin and @end is * removed from the sequence. If @dest iter points to a place within * the (@begin, @end) range, the range does not move. * * Since: 2.14 */ /** * g_sequence_new: * @data_destroy: (allow-none): a #GDestroyNotify function, or %NULL * * Creates a new GSequence. The @data_destroy function, if non-%NULL will * be called on all items when the sequence is destroyed and on items that * are removed from the sequence. * * Returns: a new #GSequence * Since: 2.14 */ /** * g_sequence_prepend: * @seq: a #GSequence * @data: the data for the new item * * Adds a new item to the front of @seq * * Returns: an iterator pointing to the new item * Since: 2.14 */ /** * g_sequence_range_get_midpoint: * @begin: a #GSequenceIter * @end: a #GSequenceIter * * Finds an iterator somewhere in the range (@begin, @end). This * iterator will be close to the middle of the range, but is not * guaranteed to be exactly in the middle. * * The @begin and @end iterators must both point to the same sequence * and @begin must come before or be equal to @end in the sequence. * * Returns: a #GSequenceIter pointing somewhere in the * (@begin, @end) range * Since: 2.14 */ /** * g_sequence_remove: * @iter: a #GSequenceIter * * Removes the item pointed to by @iter. It is an error to pass the * end iterator to this function. * * If the sequence has a data destroy function associated with it, this * function is called on the data for the removed item. * * Since: 2.14 */ /** * g_sequence_remove_range: * @begin: a #GSequenceIter * @end: a #GSequenceIter * * Removes all items in the (@begin, @end) range. * * If the sequence has a data destroy function associated with it, this * function is called on the data for the removed items. * * Since: 2.14 */ /** * g_sequence_search: * @seq: a #GSequence * @data: data for the new item * @cmp_func: the function used to compare items in the sequence * @cmp_data: user data passed to @cmp_func * * Returns an iterator pointing to the position where @data would * be inserted according to @cmp_func and @cmp_data. * * @cmp_func is called with two items of the @seq and @user_data. * It should return 0 if the items are equal, a negative value if * the first item comes before the second, and a positive value if * the second item comes before the first. * * If you are simply searching for an existing element of the sequence, * consider using g_sequence_lookup(). * * This function will fail if the data contained in the sequence is * unsorted. Use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to your sequence or, if * you want to add a large amount of data, call g_sequence_sort() after * doing unsorted insertions. * * Returns: an #GSequenceIter pointing to the position where @data * would have been inserted according to @cmp_func and @cmp_data * Since: 2.14 */ /** * g_sequence_search_iter: * @seq: a #GSequence * @data: data for the new item * @iter_cmp: the function used to compare iterators in the sequence * @cmp_data: user data passed to @iter_cmp * * Like g_sequence_search(), but uses a #GSequenceIterCompareFunc * instead of a #GCompareDataFunc as the compare function. * * @iter_cmp is called with two iterators pointing into @seq. * It should return 0 if the iterators are equal, a negative value * if the first iterator comes before the second, and a positive * value if the second iterator comes before the first. * * If you are simply searching for an existing element of the sequence, * consider using g_sequence_lookup_iter(). * * This function will fail if the data contained in the sequence is * unsorted. Use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to your sequence or, if * you want to add a large amount of data, call g_sequence_sort() after * doing unsorted insertions. * * Returns: a #GSequenceIter pointing to the position in @seq * where @data would have been inserted according to @iter_cmp * and @cmp_data * Since: 2.14 */ /** * g_sequence_set: * @iter: a #GSequenceIter * @data: new data for the item * * Changes the data for the item pointed to by @iter to be @data. If * the sequence has a data destroy function associated with it, that * function is called on the existing data that @iter pointed to. * * Since: 2.14 */ /** * g_sequence_sort: * @seq: a #GSequence * @cmp_func: the function used to sort the sequence * @cmp_data: user data passed to @cmp_func * * Sorts @seq using @cmp_func. * * @cmp_func is passed two items of @seq and should * return 0 if they are equal, a negative value if the * first comes before the second, and a positive value * if the second comes before the first. * * Since: 2.14 */ /** * g_sequence_sort_changed: * @iter: A #GSequenceIter * @cmp_func: the function used to compare items in the sequence * @cmp_data: user data passed to @cmp_func. * * Moves the data pointed to a new position as indicated by @cmp_func. This * function should be called for items in a sequence already sorted according * to @cmp_func whenever some aspect of an item changes so that @cmp_func * may return different values for that item. * * @cmp_func is called with two items of the @seq and @user_data. * It should return 0 if the items are equal, a negative value if * the first item comes before the second, and a positive value if * the second item comes before the first. * * Since: 2.14 */ /** * g_sequence_sort_changed_iter: * @iter: a #GSequenceIter * @iter_cmp: the function used to compare iterators in the sequence * @cmp_data: user data passed to @cmp_func * * Like g_sequence_sort_changed(), but uses * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as * the compare function. * * @iter_cmp is called with two iterators pointing into @seq. It should * return 0 if the iterators are equal, a negative value if the first * iterator comes before the second, and a positive value if the second * iterator comes before the first. * * Since: 2.14 */ /** * g_sequence_sort_iter: * @seq: a #GSequence * @cmp_func: the function used to compare iterators in the sequence * @cmp_data: user data passed to @cmp_func * * Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead * of a GCompareDataFunc as the compare function * * @cmp_func is called with two iterators pointing into @seq. It should * return 0 if the iterators are equal, a negative value if the first * iterator comes before the second, and a positive value if the second * iterator comes before the first. * * Since: 2.14 */ /** * g_sequence_swap: * @a: a #GSequenceIter * @b: a #GSequenceIter * * Swaps the items pointed to by @a and @b. It is allowed for @a and @b * to point into difference sequences. * * Since: 2.14 */ /** * g_set_application_name: * @application_name: localized name of the application * * Sets a human-readable name for the application. This name should be * localized if possible, and is intended for display to the user. * Contrast with g_set_prgname(), which sets a non-localized name. * g_set_prgname() will be called automatically by gtk_init(), * but g_set_application_name() will not. * * Note that for thread safety reasons, this function can only * be called once. * * The application name will be used in contexts such as error messages, * or when displaying an application's name in the task list. * * Since: 2.2 */ /** * g_set_error: * @err: (allow-none): a return location for a #GError, or %NULL * @domain: error domain * @code: error code * @format: printf()-style format * @...: args for @format * * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err * must be %NULL. A new #GError is created and assigned to *@err. */ /** * g_set_error_literal: * @err: (allow-none): a return location for a #GError, or %NULL * @domain: error domain * @code: error code * @message: error message * * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err * must be %NULL. A new #GError is created and assigned to *@err. * Unlike g_set_error(), @message is not a printf()-style format string. * Use this function if @message contains text you don't have control over, * that could include printf() escape sequences. * * Since: 2.18 */ /** * g_set_prgname: * @prgname: the name of the program. * * Sets the name of the program. This name should not be localized, * in contrast to g_set_application_name(). * * Note that for thread-safety reasons this function can only be called once. */ /** * g_set_print_handler: * @func: the new print handler * * Sets the print handler. * * Any messages passed to g_print() will be output via * the new handler. The default handler simply outputs * the message to stdout. By providing your own handler * you can redirect the output, to a GTK+ widget or a * log file for example. * * Returns: the old print handler */ /** * g_set_printerr_handler: * @func: the new error message handler * * Sets the handler for printing error messages. * * Any messages passed to g_printerr() will be output via * the new handler. The default handler simply outputs the * message to stderr. By providing your own handler you can * redirect the output, to a GTK+ widget or a log file for * example. * * Returns: the old error message handler */ /** * g_setenv: * @variable: the environment variable to set, must not contain '='. * @value: the value for to set the variable to. * @overwrite: whether to change the variable if it already exists. * * Sets an environment variable. Both the variable's name and value * should be in the GLib file name encoding. On UNIX, this means that * they can be arbitrary byte strings. On Windows, they should be in * UTF-8. * * Note that on some systems, when variables are overwritten, the memory * used for the previous variables and its value isn't reclaimed. * * You should be mindful of the fact that environment variable handling * in UNIX is not thread-safe, and your program may crash if one thread * calls g_setenv() while another thread is calling getenv(). (And note * that many functions, such as gettext(), call getenv() internally.) * This function is only safe to use at the very start of your program, * before creating any other threads (or creating objects that create * worker threads of their own). * * If you need to set up the environment for a child process, you can * use g_get_environ() to get an environment array, modify that with * g_environ_setenv() and g_environ_unsetenv(), and then pass that * array directly to execvpe(), g_spawn_async(), or the like. * * Returns: %FALSE if the environment variable couldn't be set. * Since: 2.4 */ /** * g_shell_parse_argv: * @command_line: command line to parse * @argcp: (out) (optional): return location for number of args, or %NULL * @argvp: (out) (optional) (array length=argcp zero-terminated=1): return * location for array of args, or %NULL * @error: (optional): return location for error, or %NULL * * Parses a command line into an argument vector, in much the same way * the shell would, but without many of the expansions the shell would * perform (variable expansion, globs, operators, filename expansion, * etc. are not supported). The results are defined to be the same as * those you would get from a UNIX98 /bin/sh, as long as the input * contains none of the unsupported shell expansions. If the input * does contain such expansions, they are passed through * literally. Possible errors are those from the #G_SHELL_ERROR * domain. Free the returned vector with g_strfreev(). * * Returns: %TRUE on success, %FALSE if error set */ /** * g_shell_quote: * @unquoted_string: a literal string * * Quotes a string so that the shell (/bin/sh) will interpret the * quoted string to mean @unquoted_string. If you pass a filename to * the shell, for example, you should first quote it with this * function. The return value must be freed with g_free(). The * quoting style used is undefined (single or double quotes may be * used). * * Returns: quoted string */ /** * g_shell_unquote: * @quoted_string: shell-quoted string * @error: error return location or NULL * * Unquotes a string as the shell (/bin/sh) would. Only handles * quotes; if a string contains file globs, arithmetic operators, * variables, backticks, redirections, or other special-to-the-shell * features, the result will be different from the result a real shell * would produce (the variables, backticks, etc. will be passed * through literally instead of being expanded). This function is * guaranteed to succeed if applied to the result of * g_shell_quote(). If it fails, it returns %NULL and sets the * error. The @quoted_string need not actually contain quoted or * escaped text; g_shell_unquote() simply goes through the string and * unquotes/unescapes anything that the shell would. Both single and * double quotes are handled, as are escapes including escaped * newlines. The return value must be freed with g_free(). Possible * errors are in the #G_SHELL_ERROR domain. * * Shell quoting rules are a bit strange. Single quotes preserve the * literal string exactly. escape sequences are not allowed; not even * \' - if you want a ' in the quoted text, you have to do something * like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to * be escaped with backslash. Otherwise double quotes preserve things * literally. * * Returns: an unquoted string */ /** * g_slice_alloc: * @block_size: the number of bytes to allocate * * Allocates a block of memory from the slice allocator. * The block adress handed out can be expected to be aligned * to at least 1 * sizeof (void*), * though in general slices are 2 * sizeof (void*) bytes aligned, * if a malloc() fallback implementation is used instead, * the alignment may be reduced in a libc dependent fashion. * Note that the underlying slice allocation mechanism can * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated memory block * Since: 2.10 */ /** * g_slice_alloc0: * @block_size: the number of bytes to allocate * * Allocates a block of memory via g_slice_alloc() and initializes * the returned memory to 0. Note that the underlying slice allocation * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block * Since: 2.10 */ /** * g_slice_copy: * @block_size: the number of bytes to allocate * @mem_block: the memory to copy * * Allocates a block of memory from the slice allocator * and copies @block_size bytes into it from @mem_block. * * Returns: a pointer to the allocated memory block * Since: 2.14 */ /** * g_slice_dup: * @type: the type to duplicate, typically a structure name * @mem: the memory to copy into the allocated block * * A convenience macro to duplicate a block of memory using * the slice allocator. * * It calls g_slice_copy() with `sizeof (@type)` * and casts the returned pointer to a pointer of the given type, * avoiding a type cast in the source code. * Note that the underlying slice allocation mechanism can * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block, cast to a pointer to @type * Since: 2.14 */ /** * g_slice_free: * @type: the type of the block to free, typically a structure name * @mem: a pointer to the block to free * * A convenience macro to free a block of memory that has * been allocated from the slice allocator. * * It calls g_slice_free1() using `sizeof (type)` * as the block size. * Note that the exact release behaviour can be changed with the * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ /** * g_slice_free1: * @block_size: the size of the block * @mem_block: a pointer to the block to free * * Frees a block of memory. * * The memory must have been allocated via g_slice_alloc() or * g_slice_alloc0() and the @block_size has to match the size * specified upon allocation. Note that the exact release behaviour * can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment * variable, also see [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ /** * g_slice_free_chain: * @type: the type of the @mem_chain blocks * @mem_chain: a pointer to the first block of the chain * @next: the field name of the next pointer in @type * * Frees a linked list of memory blocks of structure type @type. * The memory blocks must be equal-sized, allocated via * g_slice_alloc() or g_slice_alloc0() and linked together by * a @next pointer (similar to #GSList). The name of the * @next field in @type is passed as third argument. * Note that the exact release behaviour can be changed with the * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ /** * g_slice_free_chain_with_offset: * @block_size: the size of the blocks * @mem_chain: a pointer to the first block of the chain * @next_offset: the offset of the @next field in the blocks * * Frees a linked list of memory blocks of structure type @type. * * The memory blocks must be equal-sized, allocated via * g_slice_alloc() or g_slice_alloc0() and linked together by a * @next pointer (similar to #GSList). The offset of the @next * field in each block is passed as third argument. * Note that the exact release behaviour can be changed with the * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ /** * g_slice_new: * @type: the type to allocate, typically a structure name * * A convenience macro to allocate a block of memory from the * slice allocator. * * It calls g_slice_alloc() with `sizeof (@type)` and casts the * returned pointer to a pointer of the given type, avoiding a type * cast in the source code. Note that the underlying slice allocation * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block, cast to a pointer to @type * Since: 2.10 */ /** * g_slice_new0: * @type: the type to allocate, typically a structure name * * A convenience macro to allocate a block of memory from the * slice allocator and set the memory to 0. * * It calls g_slice_alloc0() with `sizeof (@type)` * and casts the returned pointer to a pointer of the given type, * avoiding a type cast in the source code. * Note that the underlying slice allocation mechanism can * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Since: 2.10 */ /** * g_slist_alloc: * * Allocates space for one #GSList element. It is called by the * g_slist_append(), g_slist_prepend(), g_slist_insert() and * g_slist_insert_sorted() functions and so is rarely used on its own. * * Returns: a pointer to the newly-allocated #GSList element. */ /** * g_slist_append: * @list: a #GSList * @data: the data for the new element * * Adds a new element on to the end of the list. * * The return value is the new start of the list, which may * have changed, so make sure you store the new value. * * Note that g_slist_append() has to traverse the entire list * to find the end, which is inefficient when adding multiple * elements. A common idiom to avoid the inefficiency is to prepend * the elements and reverse the list when all elements have been added. * * |[ * // Notice that these are initialized to the empty list. * GSList *list = NULL, *number_list = NULL; * * // This is a list of strings. * list = g_slist_append (list, "first"); * list = g_slist_append (list, "second"); * * // This is a list of integers. * number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); * number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); * ]| * * Returns: the new start of the #GSList */ /** * g_slist_concat: * @list1: a #GSList * @list2: the #GSList to add to the end of the first #GSList * * Adds the second #GSList onto the end of the first #GSList. * Note that the elements of the second #GSList are not copied. * They are used directly. * * Returns: the start of the new #GSList */ /** * g_slist_copy: * @list: a #GSList * * Copies a #GSList. * * Note that this is a "shallow" copy. If the list elements * consist of pointers to data, the pointers are copied but * the actual data isn't. See g_slist_copy_deep() if you need * to copy the data as well. * * Returns: a copy of @list */ /** * g_slist_copy_deep: * @list: a #GSList * @func: a copy function used to copy every element in the list * @user_data: user data passed to the copy function @func, or #NULL * * Makes a full (deep) copy of a #GSList. * * In contrast with g_slist_copy(), this function uses @func to make a copy of * each list element, in addition to copying the list container itself. * * @func, as a #GCopyFunc, takes two arguments, the data to be copied and a user * pointer. It's safe to pass #NULL as user_data, if the copy function takes only * one argument. * * For instance, if @list holds a list of GObjects, you can do: * |[ * another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL); * ]| * * And, to entirely free the new list, you could do: * |[ * g_slist_free_full (another_list, g_object_unref); * ]| * * Returns: a full copy of @list, use #g_slist_free_full to free it * Since: 2.34 */ /** * g_slist_delete_link: * @list: a #GSList * @link_: node to delete * * Removes the node link_ from the list and frees it. * Compare this to g_slist_remove_link() which removes the node * without freeing it. * * Removing arbitrary nodes from a singly-linked list requires time * that is proportional to the length of the list (ie. O(n)). If you * find yourself using g_slist_delete_link() frequently, you should * consider a different data structure, such as the doubly-linked * #GList. * * Returns: the new head of @list */ /** * g_slist_find: * @list: a #GSList * @data: the element data to find * * Finds the element in a #GSList which * contains the given data. * * Returns: the found #GSList element, * or %NULL if it is not found */ /** * g_slist_find_custom: * @list: a #GSList * @data: user data passed to the function * @func: the function to call for each element. * It should return 0 when the desired element is found * * Finds an element in a #GSList, using a supplied function to * find the desired element. It iterates over the list, calling * the given function which should return 0 when the desired * element is found. The function takes two #gconstpointer arguments, * the #GSList element's data as the first argument and the * given user data. * * Returns: the found #GSList element, or %NULL if it is not found */ /** * g_slist_foreach: * @list: a #GSList * @func: the function to call with each element's data * @user_data: user data to pass to the function * * Calls a function for each element of a #GSList. */ /** * g_slist_free: * @list: a #GSList * * Frees all of the memory used by a #GSList. * The freed elements are returned to the slice allocator. * * If list elements contain dynamically-allocated memory, * you should either use g_slist_free_full() or free them manually * first. */ /** * g_slist_free1: * * A macro which does the same as g_slist_free_1(). * * Since: 2.10 */ /** * g_slist_free_1: * @list: a #GSList element * * Frees one #GSList element. * It is usually used after g_slist_remove_link(). */ /** * g_slist_free_full: * @list: a pointer to a #GSList * @free_func: the function to be called to free each element's data * * Convenience method, which frees all the memory used by a #GSList, and * calls the specified destroy function on every element's data. * * Since: 2.28 */ /** * g_slist_index: * @list: a #GSList * @data: the data to find * * Gets the position of the element containing * the given data (starting from 0). * * Returns: the index of the element containing the data, * or -1 if the data is not found */ /** * g_slist_insert: * @list: a #GSList * @data: the data for the new element * @position: the position to insert the element. * If this is negative, or is larger than the number * of elements in the list, the new element is added on * to the end of the list. * * Inserts a new element into the list at the given position. * * Returns: the new start of the #GSList */ /** * g_slist_insert_before: * @slist: a #GSList * @sibling: node to insert @data before * @data: data to put in the newly-inserted node * * Inserts a node before @sibling containing @data. * * Returns: the new head of the list. */ /** * g_slist_insert_sorted: * @list: a #GSList * @data: the data for the new element * @func: the function to compare elements in the list. * It should return a number > 0 if the first parameter * comes after the second parameter in the sort order. * * Inserts a new element into the list, using the given * comparison function to determine its position. * * Returns: the new start of the #GSList */ /** * g_slist_insert_sorted_with_data: * @list: a #GSList * @data: the data for the new element * @func: the function to compare elements in the list. * It should return a number > 0 if the first parameter * comes after the second parameter in the sort order. * @user_data: data to pass to comparison function * * Inserts a new element into the list, using the given * comparison function to determine its position. * * Returns: the new start of the #GSList * Since: 2.10 */ /** * g_slist_last: * @list: a #GSList * * Gets the last element in a #GSList. * * This function iterates over the whole list. * * Returns: the last element in the #GSList, * or %NULL if the #GSList has no elements */ /** * g_slist_length: * @list: a #GSList * * Gets the number of elements in a #GSList. * * This function iterates over the whole list to * count its elements. * * Returns: the number of elements in the #GSList */ /** * g_slist_next: * @slist: an element in a #GSList. * * A convenience macro to get the next element in a #GSList. * * Returns: the next element, or %NULL if there are no more elements. */ /** * g_slist_nth: * @list: a #GSList * @n: the position of the element, counting from 0 * * Gets the element at the given position in a #GSList. * * Returns: the element, or %NULL if the position is off * the end of the #GSList */ /** * g_slist_nth_data: * @list: a #GSList * @n: the position of the element * * Gets the data of the element at the given position. * * Returns: the element's data, or %NULL if the position * is off the end of the #GSList */ /** * g_slist_position: * @list: a #GSList * @llink: an element in the #GSList * * Gets the position of the given element * in the #GSList (starting from 0). * * Returns: the position of the element in the #GSList, * or -1 if the element is not found */ /** * g_slist_prepend: * @list: a #GSList * @data: the data for the new element * * Adds a new element on to the start of the list. * * The return value is the new start of the list, which * may have changed, so make sure you store the new value. * * |[ * // Notice that it is initialized to the empty list. * GSList *list = NULL; * list = g_slist_prepend (list, "last"); * list = g_slist_prepend (list, "first"); * ]| * * Returns: the new start of the #GSList */ /** * g_slist_remove: * @list: a #GSList * @data: the data of the element to remove * * Removes an element from a #GSList. * If two elements contain the same data, only the first is removed. * If none of the elements contain the data, the #GSList is unchanged. * * Returns: the new start of the #GSList */ /** * g_slist_remove_all: * @list: a #GSList * @data: data to remove * * Removes all list nodes with data equal to @data. * Returns the new head of the list. Contrast with * g_slist_remove() which removes only the first node * matching the given data. * * Returns: new head of @list */ /** * g_slist_remove_link: * @list: a #GSList * @link_: an element in the #GSList * * Removes an element from a #GSList, without * freeing the element. The removed element's next * link is set to %NULL, so that it becomes a * self-contained list with one element. * * Removing arbitrary nodes from a singly-linked list * requires time that is proportional to the length of the list * (ie. O(n)). If you find yourself using g_slist_remove_link() * frequently, you should consider a different data structure, * such as the doubly-linked #GList. * * Returns: the new start of the #GSList, without the element */ /** * g_slist_reverse: * @list: a #GSList * * Reverses a #GSList. * * Returns: the start of the reversed #GSList */ /** * g_slist_sort: * @list: a #GSList * @compare_func: the comparison function used to sort the #GSList. * This function is passed the data from 2 elements of the #GSList * and should return 0 if they are equal, a negative value if the * first element comes before the second, or a positive value if * the first element comes after the second. * * Sorts a #GSList using the given comparison function. * * Returns: the start of the sorted #GSList */ /** * g_slist_sort_with_data: * @list: a #GSList * @compare_func: comparison function * @user_data: data to pass to comparison function * * Like g_slist_sort(), but the sort function accepts a user data argument. * * Returns: new head of the list */ /** * g_snprintf: * @string: the buffer to hold the output. * @n: the maximum number of bytes to produce (including the * terminating nul character). * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * A safer form of the standard sprintf() function. The output is guaranteed * to not exceed @n characters (including the terminating nul character), so * it is easy to ensure that a buffer overflow cannot occur. * * See also g_strdup_printf(). * * In versions of GLib prior to 1.2.3, this function may return -1 if the * output was truncated, and the truncated string may not be nul-terminated. * In versions prior to 1.3.12, this function returns the length of the output * string. * * The return value of g_snprintf() conforms to the snprintf() * function as standardized in ISO C99. Note that this is different from * traditional snprintf(), which returns the length of the output string. * * The format string may contain positional parameters, as specified in * the Single Unix Specification. * * Returns: the number of bytes which would be produced if the buffer * was large enough. */ /** * g_source_add_child_source: * @source: a #GSource * @child_source: a second #GSource that @source should "poll" * * Adds @child_source to @source as a "polled" source; when @source is * added to a #GMainContext, @child_source will be automatically added * with the same priority, when @child_source is triggered, it will * cause @source to dispatch (in addition to calling its own * callback), and when @source is destroyed, it will destroy * @child_source as well. (@source will also still be dispatched if * its own prepare/check functions indicate that it is ready.) * * If you don't need @child_source to do anything on its own when it * triggers, you can call g_source_set_dummy_callback() on it to set a * callback that does nothing (except return %TRUE if appropriate). * * @source will hold a reference on @child_source while @child_source * is attached to it. * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * * Since: 2.28 */ /** * g_source_add_poll: * @source: a #GSource * @fd: a #GPollFD structure holding information about a file * descriptor to watch. * * Adds a file descriptor to the set of file descriptors polled for * this source. This is usually combined with g_source_new() to add an * event source. The event source's check function will typically test * the @revents field in the #GPollFD struct and return %TRUE if events need * to be processed. * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * * Using this API forces the linear scanning of event sources on each * main loop iteration. Newly-written event sources should try to use * g_source_add_unix_fd() instead of this API. */ /** * g_source_add_unix_fd: * @source: a #GSource * @fd: the fd to monitor * @events: an event mask * * Monitors @fd for the IO events in @events. * * The tag returned by this function can be used to remove or modify the * monitoring of the fd using g_source_remove_unix_fd() or * g_source_modify_unix_fd(). * * It is not necessary to remove the fd before destroying the source; it * will be cleaned up automatically. * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * * As the name suggests, this function is not available on Windows. * * Returns: an opaque tag * Since: 2.36 */ /** * g_source_attach: * @source: a #GSource * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used) * * Adds a #GSource to a @context so that it will be executed within * that context. Remove it by calling g_source_destroy(). * * Returns: the ID (greater than 0) for the source within the * #GMainContext. */ /** * g_source_destroy: * @source: a #GSource * * Removes a source from its #GMainContext, if any, and mark it as * destroyed. The source cannot be subsequently added to another * context. It is safe to call this on sources which have already been * removed from their context. */ /** * g_source_get_can_recurse: * @source: a #GSource * * Checks whether a source is allowed to be called recursively. * see g_source_set_can_recurse(). * * Returns: whether recursion is allowed. */ /** * g_source_get_context: * @source: a #GSource * * Gets the #GMainContext with which the source is associated. * * You can call this on a source that has been destroyed, provided * that the #GMainContext it was attached to still exists (in which * case it will return that #GMainContext). In particular, you can * always call this function on the source returned from * g_main_current_source(). But calling this function on a source * whose #GMainContext has been destroyed is an error. * * Returns: (transfer none) (allow-none): the #GMainContext with which the * source is associated, or %NULL if the context has not * yet been added to a source. */ /** * g_source_get_current_time: * @source: a #GSource * @timeval: #GTimeVal structure in which to store current time. * * This function ignores @source and is otherwise the same as * g_get_current_time(). * * Deprecated: 2.28: use g_source_get_time() instead */ /** * g_source_get_id: * @source: a #GSource * * Returns the numeric ID for a particular source. The ID of a source * is a positive integer which is unique within a particular main loop * context. The reverse * mapping from ID to source is done by g_main_context_find_source_by_id(). * * Returns: the ID (greater than 0) for the source */ /** * g_source_get_name: * @source: a #GSource * * Gets a name for the source, used in debugging and profiling. * The name may be #NULL if it has never been set with * g_source_set_name(). * * Returns: the name of the source * Since: 2.26 */ /** * g_source_get_priority: * @source: a #GSource * * Gets the priority of a source. * * Returns: the priority of the source */ /** * g_source_get_ready_time: * @source: a #GSource * * Gets the "ready time" of @source, as set by * g_source_set_ready_time(). * * Any time before the current monotonic time (including 0) is an * indication that the source will fire immediately. * * Returns: the monotonic ready time, -1 for "never" */ /** * g_source_get_time: * @source: a #GSource * * Gets the time to be used when checking this source. The advantage of * calling this function over calling g_get_monotonic_time() directly is * that when checking multiple sources, GLib can cache a single value * instead of having to repeatedly get the system monotonic time. * * The time here is the system monotonic time, if available, or some * other reasonable alternative otherwise. See g_get_monotonic_time(). * * Returns: the monotonic time in microseconds * Since: 2.28 */ /** * g_source_is_destroyed: * @source: a #GSource * * Returns whether @source has been destroyed. * * This is important when you operate upon your objects * from within idle handlers, but may have freed the object * before the dispatch of your idle handler. * * |[ * static gboolean * idle_callback (gpointer data) * { * SomeWidget *self = data; * * GDK_THREADS_ENTER (); * // do stuff with self * self->idle_id = 0; * GDK_THREADS_LEAVE (); * * return G_SOURCE_REMOVE; * } * * static void * some_widget_do_stuff_later (SomeWidget *self) * { * self->idle_id = g_idle_add (idle_callback, self); * } * * static void * some_widget_finalize (GObject *object) * { * SomeWidget *self = SOME_WIDGET (object); * * if (self->idle_id) * g_source_remove (self->idle_id); * * G_OBJECT_CLASS (parent_class)->finalize (object); * } * ]| * * This will fail in a multi-threaded application if the * widget is destroyed before the idle handler fires due * to the use after free in the callback. A solution, to * this particular problem, is to check to if the source * has already been destroy within the callback. * * |[ * static gboolean * idle_callback (gpointer data) * { * SomeWidget *self = data; * * GDK_THREADS_ENTER (); * if (!g_source_is_destroyed (g_main_current_source ())) * { * // do stuff with self * } * GDK_THREADS_LEAVE (); * * return FALSE; * } * ]| * * Returns: %TRUE if the source has been destroyed * Since: 2.12 */ /** * g_source_modify_unix_fd: * @source: a #GSource * @tag: the tag from g_source_add_unix_fd() * @new_events: the new event mask to watch * * Updates the event mask to watch for the fd identified by @tag. * * @tag is the tag returned from g_source_add_unix_fd(). * * If you want to remove a fd, don't set its event mask to zero. * Instead, call g_source_remove_unix_fd(). * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * * As the name suggests, this function is not available on Windows. * * Since: 2.36 */ /** * g_source_new: * @source_funcs: structure containing functions that implement * the sources behavior. * @struct_size: size of the #GSource structure to create. * * Creates a new #GSource structure. The size is specified to * allow creating structures derived from #GSource that contain * additional data. The size passed in must be at least * `sizeof (GSource)`. * * 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. * * Returns: the newly-created #GSource. */ /** * g_source_query_unix_fd: * @source: a #GSource * @tag: the tag from g_source_add_unix_fd() * * Queries the events reported for the fd corresponding to @tag on * @source during the last poll. * * The return value of this function is only defined when the function * is called from the check or dispatch functions for @source. * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * * As the name suggests, this function is not available on Windows. * * Returns: the conditions reported on the fd * Since: 2.36 */ /** * g_source_ref: * @source: a #GSource * * Increases the reference count on a source by one. * * Returns: @source */ /** * g_source_remove: * @tag: the ID of the source to remove. * * Removes the source with the given id from the default main context. * * The id of a #GSource is given by g_source_get_id(), or will be * returned by the functions g_source_attach(), g_idle_add(), * g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), * g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and * g_io_add_watch_full(). * * See also g_source_destroy(). You must use g_source_destroy() for sources * added to a non-default main context. * * It is a programmer error to attempt to remove a non-existent source. * * Returns: For historical reasons, this function always returns %TRUE */ /** * g_source_remove_by_funcs_user_data: * @funcs: The @source_funcs passed to g_source_new() * @user_data: the user data for the callback * * Removes a source from the default main loop context given the * source functions and user data. If multiple sources exist with the * same source functions and user data, only one will be destroyed. * * Returns: %TRUE if a source was found and removed. */ /** * g_source_remove_by_user_data: * @user_data: the user_data for the callback. * * Removes a source from the default main loop context given the user * data for the callback. If multiple sources exist with the same user * data, only one will be destroyed. * * Returns: %TRUE if a source was found and removed. */ /** * g_source_remove_child_source: * @source: a #GSource * @child_source: a #GSource previously passed to * g_source_add_child_source(). * * Detaches @child_source from @source and destroys it. * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * * Since: 2.28 */ /** * g_source_remove_poll: * @source: a #GSource * @fd: a #GPollFD structure previously passed to g_source_add_poll(). * * Removes a file descriptor from the set of file descriptors polled for * this source. * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. */ /** * g_source_remove_unix_fd: * @source: a #GSource * @tag: the tag from g_source_add_unix_fd() * * Reverses the effect of a previous call to g_source_add_unix_fd(). * * You only need to call this if you want to remove an fd from being * watched while keeping the same source around. In the normal case you * will just want to destroy the source. * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * * As the name suggests, this function is not available on Windows. * * Since: 2.36 */ /** * g_source_set_callback: * @source: the source * @func: a callback function * @data: the data to pass to callback function * @notify: (allow-none): a function to call when @data is no longer in use, or %NULL. * * Sets the callback function for a source. The callback for a source is * called from the source's dispatch function. * * The exact type of @func depends on the type of source; ie. you * should not count on @func being called with @data as its first * parameter. * * Typically, you won't use this function. Instead use functions specific * to the type of source you are using. */ /** * g_source_set_callback_indirect: * @source: the source * @callback_data: pointer to callback data "object" * @callback_funcs: functions for reference counting @callback_data * and getting the callback and data * * Sets the callback function storing the data as a refcounted callback * "object". This is used internally. Note that calling * g_source_set_callback_indirect() assumes * an initial reference count on @callback_data, and thus * @callback_funcs->unref will eventually be called once more * than @callback_funcs->ref. */ /** * g_source_set_can_recurse: * @source: a #GSource * @can_recurse: whether recursion is allowed for this source * * Sets whether a source can be called recursively. If @can_recurse is * %TRUE, then while the source is being dispatched then this source * will be processed normally. Otherwise, all processing of this * source is blocked until the dispatch function returns. */ /** * g_source_set_funcs: * @source: a #GSource * @funcs: the new #GSourceFuncs * * Sets the source functions (can be used to override * default implementations) of an unattached source. * * Since: 2.12 */ /** * g_source_set_name: * @source: a #GSource * @name: debug name for the source * * Sets a name for the source, used in debugging and profiling. * The name defaults to #NULL. * * The source name should describe in a human-readable way * what the source does. For example, "X11 event queue" * or "GTK+ repaint idle handler" or whatever it is. * * It is permitted to call this function multiple times, but is not * recommended due to the potential performance impact. For example, * one could change the name in the "check" function of a #GSourceFuncs * to include details like the event type in the source name. * * Since: 2.26 */ /** * g_source_set_name_by_id: * @tag: a #GSource ID * @name: debug name for the source * * Sets the name of a source using its ID. * * This is a convenience utility to set source names from the return * value of g_idle_add(), g_timeout_add(), etc. * * Since: 2.26 */ /** * g_source_set_priority: * @source: a #GSource * @priority: the new priority. * * Sets the priority of a source. While the main loop is being run, a * source will be dispatched if it is ready to be dispatched and no * sources at a higher (numerically smaller) priority are ready to be * dispatched. * * A child source always has the same priority as its parent. It is not * permitted to change the priority of a source once it has been added * as a child of another source. */ /** * g_source_set_ready_time: * @source: a #GSource * @ready_time: the monotonic time at which the source will be ready, * 0 for "immediately", -1 for "never" * * Sets a #GSource to be dispatched when the given monotonic time is * reached (or passed). If the monotonic time is in the past (as it * always will be if @ready_time is 0) then the source will be * dispatched immediately. * * If @ready_time is -1 then the source is never woken up on the basis * of the passage of time. * * Dispatching the source does not reset the ready time. You should do * so yourself, from the source dispatch function. * * Note that if you have a pair of sources where the ready time of one * suggests that it will be delivered first but the priority for the * other suggests that it would be delivered first, and the ready time * for both sources is reached during the same main context iteration * then the order of dispatch is undefined. * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * * Since: 2.36 */ /** * g_source_unref: * @source: a #GSource * * Decreases the reference count of a source by one. If the * resulting reference count is zero the source and associated * memory will be destroyed. */ /** * g_spaced_primes_closest: * @num: a #guint * * Gets the smallest prime number from a built-in array of primes which * is larger than @num. This is used within GLib to calculate the optimum * size of a #GHashTable. * * The built-in array of primes ranges from 11 to 13845163 such that * each prime is approximately 1.5-2 times the previous prime. * * Returns: the smallest prime number from a built-in array of primes * which is larger than @num */ /** * g_spawn_async: * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's * @argv: (array zero-terminated=1): child's argument vector * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags * @child_setup: (scope async) (allow-none): function to run in the child just before exec() * @user_data: (closure): user data for @child_setup * @child_pid: (out) (allow-none): return location for child process reference, or %NULL * @error: return location for error * * See g_spawn_async_with_pipes() for a full description; this function * simply calls the g_spawn_async_with_pipes() without any pipes. * * You should call g_spawn_close_pid() on the returned child process * reference when you don't need it any more. * * If you are writing a GTK+ application, and the program you are * spawning is a graphical application, too, then you may want to * use gdk_spawn_on_screen() instead to ensure that the spawned program * opens its windows on the right screen. * * Note that the returned @child_pid on Windows is a handle to the child * process and not its identifier. Process handles and process identifiers * are different concepts on Windows. * * Returns: %TRUE on success, %FALSE if error is set */ /** * g_spawn_async_with_pipes: * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's, in the GLib file name encoding * @flags: flags from #GSpawnFlags * @child_setup: (scope async) (allow-none): function to run in the child just before exec() * @user_data: (closure): user data for @child_setup * @child_pid: (out) (allow-none): return location for child process ID, or %NULL * @standard_input: (out) (allow-none): return location for file descriptor to write to child's stdin, or %NULL * @standard_output: (out) (allow-none): return location for file descriptor to read child's stdout, or %NULL * @standard_error: (out) (allow-none): return location for file descriptor to read child's stderr, or %NULL * @error: return location for error * * Executes a child program asynchronously (your program will not * block waiting for the child to exit). The child program is * specified by the only argument that must be provided, @argv. * @argv should be a %NULL-terminated array of strings, to be passed * as the argument vector for the child. The first string in @argv * is of course the name of the program to execute. By default, the * name of the program must be a full path. If @flags contains the * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is * used to search for the executable. If @flags contains the * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from * @envp is used to search for the executable. If both the * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags * are set, the `PATH` variable from @envp takes precedence over * the environment variable. * * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not * used, then the program will be run from the current directory (or * @working_directory, if specified); this might be unexpected or even * dangerous in some cases when the current directory is world-writable. * * On Windows, note that all the string or string vector arguments to * this function and the other g_spawn*() functions are in UTF-8, the * GLib file name encoding. Unicode characters that are not part of * the system codepage passed in these arguments will be correctly * available in the spawned program only if it uses wide character API * to retrieve its command line. For C programs built with Microsoft's * tools it is enough to make the program have a wmain() instead of * main(). wmain() has a wide character argument vector as parameter. * * At least currently, mingw doesn't support wmain(), so if you use * mingw to develop the spawned program, it will have to call the * undocumented function __wgetmainargs() to get the wide character * argument vector and environment. See gspawn-win32-helper.c in the * GLib sources or init.c in the mingw runtime sources for a prototype * for that function. Alternatively, you can retrieve the Win32 system * level wide character command line passed to the spawned program * using the GetCommandLineW() function. * * On Windows the low-level child process creation API CreateProcess() * doesn't use argument vectors, but a command line. The C runtime * library's spawn*() family of functions (which g_spawn_async_with_pipes() * eventually calls) paste the argument vector elements together into * a command line, and the C runtime startup code does a corresponding * reconstruction of an argument vector from the command line, to be * passed to main(). Complications arise when you have argument vector * elements that contain spaces of double quotes. The spawn*() functions * don't do any quoting or escaping, but on the other hand the startup * code does do unquoting and unescaping in order to enable receiving * arguments with embedded spaces or double quotes. To work around this * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on * argument vector elements that need it before calling the C runtime * spawn() function. * * The returned @child_pid on Windows is a handle to the child * process, not its identifier. Process handles and process * identifiers are different concepts on Windows. * * @envp is a %NULL-terminated array of strings, where each string * has the form `KEY=VALUE`. This will become the child's environment. * If @envp is %NULL, the child inherits its parent's environment. * * @flags should be the bitwise OR of any flags you want to affect the * function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the * child will not automatically be reaped; you must use a child watch to * be notified about the death of the child process. Eventually you must * call g_spawn_close_pid() on the @child_pid, in order to free * resources which may be associated with the child process. (On Unix, * using a child watch is equivalent to calling waitpid() or handling * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid() * is equivalent to calling CloseHandle() on the process handle returned * in @child_pid). See g_child_watch_add(). * * %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file * descriptors will be inherited by the child; otherwise all descriptors * except stdin/stdout/stderr will be closed before calling exec() in * the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an * absolute path, it will be looked for in the `PATH` environment * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an * absolute path, it will be looked for in the `PATH` variable from * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP * are used, the value from @envp takes precedence over the environment. * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output * will be discarded, instead of going to the same location as the parent's * standard output. If you use this flag, @standard_output must be %NULL. * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error * will be discarded, instead of going to the same location as the parent's * standard error. If you use this flag, @standard_error must be %NULL. * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's * standard input (by default, the child's standard input is attached to * /dev/null). If you use this flag, @standard_input must be %NULL. * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is * the file to execute, while the remaining elements are the actual * argument vector to pass to the file. Normally g_spawn_async_with_pipes() * uses @argv[0] as the file to execute, and passes all of @argv to the child. * * @child_setup and @user_data are a function and user data. On POSIX * platforms, the function is called in the child after GLib has * performed all the setup it plans to perform (including creating * pipes, closing file descriptors, etc.) but before calling exec(). * That is, @child_setup is called just before calling exec() in the * child. Obviously actions taken in this function will only affect * the child, not the parent. * * On Windows, there is no separate fork() and exec() functionality. * Child processes are created and run with a single API call, * CreateProcess(). There is no sensible thing @child_setup * could be used for on Windows so it is ignored and not called. * * If non-%NULL, @child_pid will on Unix be filled with the child's * process ID. You can use the process ID to send signals to the child, * or to use g_child_watch_add() (or waitpid()) if you specified the * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be * filled with a handle to the child process only if you specified the * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child * process using the Win32 API, for example wait for its termination * with the WaitFor*() functions, or examine its exit code with * GetExitCodeProcess(). You should close the handle with CloseHandle() * or g_spawn_close_pid() when you no longer need it. * * If non-%NULL, the @standard_input, @standard_output, @standard_error * locations will be filled with file descriptors for writing to the child's * standard input or reading from its standard output or standard error. * The caller of g_spawn_async_with_pipes() must close these file descriptors * when they are no longer in use. If these parameters are %NULL, the * corresponding pipe won't be created. * * If @standard_input is NULL, the child's standard input is attached to * /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set. * * If @standard_error is NULL, the child's standard error goes to the same * location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL * is set. * * If @standard_output is NULL, the child's standard output goes to the same * location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL * is set. * * @error can be %NULL to ignore errors, or non-%NULL to report errors. * If an error is set, the function returns %FALSE. Errors are reported * even if they occur in the child (for example if the executable in * @argv[0] is not found). Typically the `message` field of returned * errors should be displayed to users. Possible errors are those from * the #G_SPAWN_ERROR domain. * * If an error occurs, @child_pid, @standard_input, @standard_output, * and @standard_error will not be filled with valid values. * * If @child_pid is not %NULL and an error does not occur then the returned * process reference must be closed using g_spawn_close_pid(). * * If you are writing a GTK+ application, and the program you * are spawning is a graphical application, too, then you may * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that * the spawned program opens its windows on the right screen. * * Returns: %TRUE on success, %FALSE if an error was set */ /** * g_spawn_check_exit_status: * @exit_status: An exit code as returned from g_spawn_sync() * @error: a #GError * * Set @error if @exit_status indicates the child exited abnormally * (e.g. with a nonzero exit code, or via a fatal signal). * * The g_spawn_sync() and g_child_watch_add() family of APIs return an * exit status for subprocesses encoded in a platform-specific way. * On Unix, this is guaranteed to be in the same format waitpid() returns, * and on Windows it is guaranteed to be the result of GetExitCodeProcess(). * * Prior to the introduction of this function in GLib 2.34, interpreting * @exit_status required use of platform-specific APIs, which is problematic * for software using GLib as a cross-platform layer. * * Additionally, many programs simply want to determine whether or not * the child exited successfully, and either propagate a #GError or * print a message to standard error. In that common case, this function * can be used. Note that the error message in @error will contain * human-readable information about the exit status. * * The @domain and @code of @error have special semantics in the case * where the process has an "exit code", as opposed to being killed by * a signal. On Unix, this happens if WIFEXITED() would be true of * @exit_status. On Windows, it is always the case. * * The special semantics are that the actual exit code will be the * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR. * This allows you to differentiate between different exit codes. * * If the process was terminated by some means other than an exit * status, the domain will be %G_SPAWN_ERROR, and the code will be * %G_SPAWN_ERROR_FAILED. * * This function just offers convenience; you can of course also check * the available platform via a macro such as %G_OS_UNIX, and use * WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt * to scan or parse the error message string; it may be translated and/or * change in future versions of GLib. * * Returns: %TRUE if child exited successfully, %FALSE otherwise (and * @error will be set) * Since: 2.34 */ /** * g_spawn_close_pid: * @pid: The process reference to close * * On some platforms, notably Windows, the #GPid type represents a resource * which must be closed to prevent resource leaking. g_spawn_close_pid() * is provided for this purpose. It should be used on all platforms, even * though it doesn't do anything under UNIX. */ /** * g_spawn_command_line_async: * @command_line: a command line * @error: return location for errors * * A simple version of g_spawn_async() that parses a command line with * g_shell_parse_argv() and passes it to g_spawn_async(). Runs a * command line in the background. Unlike g_spawn_async(), the * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note * that %G_SPAWN_SEARCH_PATH can have security implications, so * consider using g_spawn_async() directly if appropriate. Possible * errors are those from g_shell_parse_argv() and g_spawn_async(). * * The same concerns on Windows apply as for g_spawn_command_line_sync(). * * Returns: %TRUE on success, %FALSE if error is set */ /** * g_spawn_command_line_sync: * @command_line: a command line * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child output * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child errors * @exit_status: (out) (allow-none): return location for child exit status, as returned by waitpid() * @error: return location for errors * * A simple version of g_spawn_sync() with little-used parameters * removed, taking a command line instead of an argument vector. See * g_spawn_sync() for full details. @command_line will be parsed by * g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag * is enabled. Note that %G_SPAWN_SEARCH_PATH can have security * implications, so consider using g_spawn_sync() directly if * appropriate. Possible errors are those from g_spawn_sync() and those * from g_shell_parse_argv(). * * If @exit_status is non-%NULL, the platform-specific exit status of * the child is stored there; see the documentation of * g_spawn_check_exit_status() for how to use and interpret this. * * On Windows, please note the implications of g_shell_parse_argv() * parsing @command_line. Parsing is done according to Unix shell rules, not * Windows command interpreter rules. * Space is a separator, and backslashes are * special. Thus you cannot simply pass a @command_line containing * canonical Windows paths, like "c:\\program files\\app\\app.exe", as * the backslashes will be eaten, and the space will act as a * separator. You need to enclose such paths with single quotes, like * "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'". * * Returns: %TRUE on success, %FALSE if an error was set */ /** * g_spawn_sync: * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's * @argv: (array zero-terminated=1): child's argument vector * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags * @child_setup: (scope async) (allow-none): function to run in the child just before exec() * @user_data: (closure): user data for @child_setup * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child output, or %NULL * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child error messages, or %NULL * @exit_status: (out) (allow-none): return location for child exit status, as returned by waitpid(), or %NULL * @error: return location for error, or %NULL * * Executes a child synchronously (waits for the child to exit before returning). * All output from the child is stored in @standard_output and @standard_error, * if those parameters are non-%NULL. Note that you must set the * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when * passing %NULL for @standard_output and @standard_error. * * If @exit_status is non-%NULL, the platform-specific exit status of * the child is stored there; see the documentation of * g_spawn_check_exit_status() for how to use and interpret this. * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in * @flags. * * If an error occurs, no data is returned in @standard_output, * @standard_error, or @exit_status. * * This function calls g_spawn_async_with_pipes() internally; see that * function for full details on the other parameters and details on * how these functions work on Windows. * * Returns: %TRUE on success, %FALSE if an error was set */ /** * g_sprintf: * @string: A pointer to a memory buffer to contain the resulting string. It * is up to the caller to ensure that the allocated buffer is large * enough to hold the formatted result * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard sprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * * Note that it is usually better to use g_snprintf(), to avoid the * risk of buffer overflow. * * See also g_strdup_printf(). * * Returns: the number of bytes printed. * Since: 2.2 */ /** * g_stat: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * @buf: a pointer to a stat struct, which will be filled with the file * information * * A wrapper for the POSIX stat() function. The stat() function * returns information about a file. On Windows the stat() function in * the C library checks only the FAT-style READONLY attribute and does * not look at the ACL at all. Thus on Windows the protection bits in * the @st_mode field are a fabrication of little use. * * On Windows the Microsoft C libraries have several variants of the * stat struct and stat() function with names like _stat(), _stat32(), * _stat32i64() and _stat64i32(). The one used here is for 32-bit code * the one with 32-bit size and time fields, specifically called _stat32(). * * In Microsoft's compiler, by default struct stat means one with * 64-bit time fields while in MinGW struct stat is the legacy one * with 32-bit fields. To hopefully clear up this messs, the gstdio.h * header defines a type #GStatBuf which is the appropriate struct type * depending on the platform and/or compiler being used. On POSIX it * is just struct stat, but note that even on POSIX platforms, stat() * might be a macro. * * See your C library manual for more details about stat(). * * Returns: 0 if the information was successfully retrieved, * -1 if an error occurred * Since: 2.6 */ /** * g_stpcpy: * @dest: destination buffer. * @src: source string. * * Copies a nul-terminated string into the dest buffer, include the * trailing nul, and return a pointer to the trailing nul byte. * This is useful for concatenating multiple strings together * without having to repeatedly scan for the end. * * Returns: a pointer to trailing nul byte. */ /** * g_str_equal: * @v1: a key * @v2: a key to compare with @v1 * * Compares two strings for byte-by-byte equality and returns %TRUE * if they are equal. It can be passed to g_hash_table_new() as the * @key_equal_func parameter, when using non-%NULL strings as keys in a * #GHashTable. * * Note that this function is primarily meant as a hash table comparison * function. For a general-purpose, %NULL-safe string comparison function, * see g_strcmp0(). * * Returns: %TRUE if the two keys match */ /** * g_str_has_prefix: * @str: a nul-terminated string * @prefix: the nul-terminated prefix to look for * * Looks whether the string @str begins with @prefix. * * Returns: %TRUE if @str begins with @prefix, %FALSE otherwise. * Since: 2.2 */ /** * g_str_has_suffix: * @str: a nul-terminated string * @suffix: the nul-terminated suffix to look for * * Looks whether the string @str ends with @suffix. * * Returns: %TRUE if @str end with @suffix, %FALSE otherwise. * Since: 2.2 */ /** * g_str_hash: * @v: a string key * * Converts a string to a hash value. * * This function implements the widely used "djb" hash apparently * posted by Daniel Bernstein to comp.lang.c some time ago. The 32 * bit unsigned hash value starts at 5381 and for each byte 'c' in * the string, is updated: `hash = hash * 33 + c`. This function * uses the signed value of each byte. * * It can be passed to g_hash_table_new() as the @hash_func parameter, * when using non-%NULL strings as keys in a #GHashTable. * * Returns: a hash value corresponding to the key */ /** * g_str_is_ascii: * @str: a string * * Determines if a string is pure ASCII. A string is pure ASCII if it * contains no bytes with the high bit set. * * Returns: %TRUE if @str is ASCII * Since: 2.40 */ /** * g_str_match_string: * @search_term: the search term from the user * @potential_hit: the text that may be a hit * @accept_alternates: %TRUE to accept ASCII alternates * * Checks if a search conducted for @search_term should match * @potential_hit. * * This function calls g_str_tokenize_and_fold() on both * @search_term and @potential_hit. ASCII alternates are never taken * for @search_term but will be taken for @potential_hit according to * the value of @accept_alternates. * * A hit occurs when each folded token in @search_term is a prefix of a * folded token from @potential_hit. * * Depending on how you're performing the search, it will typically be * faster to call g_str_tokenize_and_fold() on each string in * your corpus and build an index on the returned folded tokens, then * call g_str_tokenize_and_fold() on the search term and * perform lookups into that index. * * As some examples, searching for "fred" would match the potential hit * "Smith, Fred" and also "Frédéric". Searching for "Fréd" would match * "Frédéric" but not "Frederic" (due to the one-directional nature of * accent matching). Searching "fo" would match "Foo" and "Bar Foo * Baz", but not "SFO" (because no word as "fo" as a prefix). * * Returns: %TRUE if @potential_hit is a hit * Since: 2.40 */ /** * g_str_to_ascii: * @str: a string, in UTF-8 * @from_locale: (allow-none): the source locale, if known * * Transliterate @str to plain ASCII. * * For best results, @str should be in composed normalised form. * * This function performs a reasonably good set of character * replacements. The particular set of replacements that is done may * change by version or even by runtime environment. * * If the source language of @str is known, it can used to improve the * accuracy of the translation by passing it as @from_locale. It should * be a valid POSIX locale string (of the form * "language[_territory][.codeset][@modifier]"). * * If @from_locale is %NULL then the current locale is used. * * If you want to do translation for no specific locale, and you want it * to be done independently of the currently locale, specify "C" for * @from_locale. * * Returns: a string in plain ASCII */ /** * g_str_tokenize_and_fold: * @string: a string * @translit_locale: (allow-none): the language code (like 'de' or * 'en_GB') from which @string originates * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a * return location for ASCII alternates * * Tokenises @string and performs folding on each token. * * A token is a non-empty sequence of alphanumeric characters in the * source string, separated by non-alphanumeric characters. An * "alphanumeric" character for this purpose is one that matches * g_unichar_isalnum() or g_unichar_ismark(). * * Each token is then (Unicode) normalised and case-folded. If * @ascii_alternates is non-%NULL and some of the returned tokens * contain non-ASCII characters, ASCII alternatives will be generated. * * The number of ASCII alternatives that are generated and the method * for doing so is unspecified, but @translit_locale (if specified) may * improve the transliteration if the language of the source string is * known. * * Returns: (transfer full) (array zero-terminated=1): the folded tokens * Since: 2.40 */ /** * g_strcanon: * @string: a nul-terminated array of bytes * @valid_chars: bytes permitted in @string * @substitutor: replacement character for disallowed bytes * * For each character in @string, if the character is not in @valid_chars, * replaces the character with @substitutor. Modifies @string in place, * and return @string itself, not a copy. The return value is to allow * nesting such as * |[ * g_ascii_strup (g_strcanon (str, "abc", '?')) * ]| * * Returns: @string */ /** * g_strcasecmp: * @s1: a string * @s2: a string to compare with @s1 * * A case-insensitive string comparison, corresponding to the standard * strcasecmp() function on platforms which support it. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, * or a positive value if @s1 > @s2. * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this * function is deprecated and how to replace it. */ /** * g_strchomp: * @string: a string to remove the trailing whitespace from * * Removes trailing whitespace from a string. * * This function doesn't allocate or reallocate any memory; * it modifies @string in place. Therefore, it cannot be used * on statically allocated strings. * * The pointer to @string is returned to allow the nesting of functions. * * Also see g_strchug() and g_strstrip(). * * Returns: @string */ /** * g_strchug: * @string: a string to remove the leading whitespace from * * Removes leading whitespace from a string, by moving the rest * of the characters forward. * * This function doesn't allocate or reallocate any memory; * it modifies @string in place. Therefore, it cannot be used on * statically allocated strings. * * The pointer to @string is returned to allow the nesting of functions. * * Also see g_strchomp() and g_strstrip(). * * Returns: @string */ /** * g_strcmp0: * @str1: (allow-none): a C string or %NULL * @str2: (allow-none): another C string or %NULL * * Compares @str1 and @str2 like strcmp(). Handles %NULL * gracefully by sorting it before non-%NULL strings. * Comparing two %NULL pointers returns 0. * * Returns: an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2. * Since: 2.16 */ /** * g_strcompress: * @source: a string to compress * * Replaces all escaped characters with their one byte equivalent. * * This function does the reverse conversion of g_strescape(). * * Returns: a newly-allocated copy of @source with all escaped * character compressed */ /** * g_strconcat: * @string1: the first string to add, which must not be %NULL * @...: a %NULL-terminated list of strings to append to the string * * Concatenates all of the given strings into one long string. The * returned string should be freed with g_free() when no longer needed. * * The variable argument list must end with %NULL. If you forget the %NULL, * g_strconcat() will start appending random memory junk to your string. * * Note that this function is usually not the right function to use to * assemble a translated message from pieces, since proper translation * often requires the pieces to be reordered. * * Returns: a newly-allocated string containing all the string arguments */ /** * g_strdelimit: * @string: the string to convert * @delimiters: (allow-none): a string containing the current delimiters, * or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS * @new_delimiter: the new delimiter character * * Converts any delimiter characters in @string to @new_delimiter. * Any characters in @string which are found in @delimiters are * changed to the @new_delimiter character. Modifies @string in place, * and returns @string itself, not a copy. The return value is to * allow nesting such as * |[ * g_ascii_strup (g_strdelimit (str, "abc", '?')) * ]| * * Returns: @string */ /** * g_strdown: * @string: the string to convert. * * Converts a string to lower case. * * Returns: the string * Deprecated: 2.2: This function is totally broken for the reasons discussed * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() * instead. */ /** * g_strdup: * @str: the string to duplicate * * Duplicates a string. If @str is %NULL it returns %NULL. * The returned string should be freed with g_free() * when no longer needed. * * Returns: a newly-allocated copy of @str */ /** * g_strdup_printf: * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @...: the parameters to insert into the format string * * Similar to the standard C sprintf() function but safer, since it * calculates the maximum space required and allocates memory to hold * the result. The returned string should be freed with g_free() when no * longer needed. * * Returns: a newly-allocated string holding the result */ /** * g_strdup_vprintf: * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @args: the list of parameters to insert into the format string * * Similar to the standard C vsprintf() function but safer, since it * calculates the maximum space required and allocates memory to hold * the result. The returned string should be freed with g_free() when * no longer needed. * * See also g_vasprintf(), which offers the same functionality, but * additionally returns the length of the allocated string. * * Returns: a newly-allocated string holding the result */ /** * g_strdupv: * @str_array: a %NULL-terminated array of strings * * Copies %NULL-terminated array of strings. The copy is a deep copy; * the new array should be freed by first freeing each string, then * the array itself. g_strfreev() does this for you. If called * on a %NULL value, g_strdupv() simply returns %NULL. * * Returns: a new %NULL-terminated array of strings. */ /** * g_strerror: * @errnum: the system error number. See the standard C %errno * documentation * * Returns a string corresponding to the given error code, e.g. * "no such process". You should use this function in preference to * strerror(), because it returns a string in UTF-8 encoding, and since * not all platforms support the strerror() function. * * Returns: a UTF-8 string describing the error code. If the error code * is unknown, it returns "unknown error ()". */ /** * g_strescape: * @source: a string to escape * @exceptions: a string of characters not to escape in @source * * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' * and '"' in the string @source by inserting a '\' before * them. Additionally all characters in the range 0x01-0x1F (everything * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are * replaced with a '\' followed by their octal representation. * Characters supplied in @exceptions are not escaped. * * g_strcompress() does the reverse conversion. * * Returns: a newly-allocated copy of @source with certain * characters escaped. See above. */ /** * g_strfreev: * @str_array: a %NULL-terminated array of strings to free * * Frees a %NULL-terminated array of strings, and the array itself. * If called on a %NULL value, g_strfreev() simply returns. */ /** * g_string_append: * @string: a #GString * @val: the string to append onto the end of @string * * Adds a string onto the end of a #GString, expanding * it if necessary. * * Returns: @string */ /** * g_string_append_c: * @string: a #GString * @c: the byte to append onto the end of @string * * Adds a byte onto the end of a #GString, expanding * it if necessary. * * Returns: @string */ /** * g_string_append_len: * @string: a #GString * @val: bytes to append * @len: number of bytes of @val to use * * Appends @len bytes of @val to @string. Because @len is * provided, @val may contain embedded nuls and need not * be nul-terminated. * * Since this function does not stop at nul bytes, it is * the caller's responsibility to ensure that @val has at * least @len addressable bytes. * * Returns: @string */ /** * g_string_append_printf: * @string: a #GString * @format: the string format. See the printf() documentation * @...: the parameters to insert into the format string * * Appends a formatted string onto the end of a #GString. * This function is similar to g_string_printf() except * that the text is appended to the #GString. */ /** * g_string_append_unichar: * @string: a #GString * @wc: a Unicode character * * Converts a Unicode character into UTF-8, and appends it * to the string. * * Returns: @string */ /** * g_string_append_uri_escaped: * @string: a #GString * @unescaped: a string * @reserved_chars_allowed: a string of reserved characters allowed * to be used, or %NULL * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters * * Appends @unescaped to @string, escaped any characters that * are reserved in URIs using URI-style escape sequences. * * Returns: @string * Since: 2.16 */ /** * g_string_append_vprintf: * @string: a #GString * @format: the string format. See the printf() documentation * @args: the list of arguments to insert in the output * * Appends a formatted string onto the end of a #GString. * This function is similar to g_string_append_printf() * except that the arguments to the format string are passed * as a va_list. * * Since: 2.14 */ /** * g_string_ascii_down: * @string: a GString * * Converts all uppercase ASCII letters to lowercase ASCII letters. * * Returns: passed-in @string pointer, with all the * uppercase characters converted to lowercase in place, * with semantics that exactly match g_ascii_tolower(). */ /** * g_string_ascii_up: * @string: a GString * * Converts all lowercase ASCII letters to uppercase ASCII letters. * * Returns: passed-in @string pointer, with all the * lowercase characters converted to uppercase in place, * with semantics that exactly match g_ascii_toupper(). */ /** * g_string_assign: * @string: the destination #GString. Its current contents * are destroyed. * @rval: the string to copy into @string * * Copies the bytes from a string into a #GString, * destroying any previous contents. It is rather like * the standard strcpy() function, except that you do not * have to worry about having enough space to copy the string. * * Returns: @string */ /** * g_string_chunk_clear: * @chunk: a #GStringChunk * * Frees all strings contained within the #GStringChunk. * After calling g_string_chunk_clear() it is not safe to * access any of the strings which were contained within it. * * Since: 2.14 */ /** * g_string_chunk_free: * @chunk: a #GStringChunk * * Frees all memory allocated by the #GStringChunk. * After calling g_string_chunk_free() it is not safe to * access any of the strings which were contained within it. */ /** * g_string_chunk_insert: * @chunk: a #GStringChunk * @string: the string to add * * Adds a copy of @string to the #GStringChunk. * It returns a pointer to the new copy of the string * in the #GStringChunk. The characters in the string * can be changed, if necessary, though you should not * change anything after the end of the string. * * Unlike g_string_chunk_insert_const(), this function * does not check for duplicates. Also strings added * with g_string_chunk_insert() will not be searched * by g_string_chunk_insert_const() when looking for * duplicates. * * Returns: a pointer to the copy of @string within * the #GStringChunk */ /** * g_string_chunk_insert_const: * @chunk: a #GStringChunk * @string: the string to add * * Adds a copy of @string to the #GStringChunk, unless the same * string has already been added to the #GStringChunk with * g_string_chunk_insert_const(). * * This function is useful if you need to copy a large number * of strings but do not want to waste space storing duplicates. * But you must remember that there may be several pointers to * the same string, and so any changes made to the strings * should be done very carefully. * * Note that g_string_chunk_insert_const() will not return a * pointer to a string added with g_string_chunk_insert(), even * if they do match. * * Returns: a pointer to the new or existing copy of @string * within the #GStringChunk */ /** * g_string_chunk_insert_len: * @chunk: a #GStringChunk * @string: bytes to insert * @len: number of bytes of @string to insert, or -1 to insert a * nul-terminated string * * Adds a copy of the first @len bytes of @string to the #GStringChunk. * The copy is nul-terminated. * * Since this function does not stop at nul bytes, it is the caller's * responsibility to ensure that @string has at least @len addressable * bytes. * * The characters in the returned string can be changed, if necessary, * though you should not change anything after the end of the string. * * Returns: a pointer to the copy of @string within the #GStringChunk * Since: 2.4 */ /** * g_string_chunk_new: * @size: the default size of the blocks of memory which are * allocated to store the strings. If a particular string * is larger than this default size, a larger block of * memory will be allocated for it. * * Creates a new #GStringChunk. * * Returns: a new #GStringChunk */ /** * g_string_down: * @string: a #GString * * Converts a #GString to lowercase. * * Returns: the #GString * Deprecated: 2.2: This function uses the locale-specific * tolower() function, which is almost never the right thing. * Use g_string_ascii_down() or g_utf8_strdown() instead. */ /** * g_string_equal: * @v: a #GString * @v2: another #GString * * Compares two strings for equality, returning %TRUE if they are equal. * For use with #GHashTable. * * Returns: %TRUE if the strings are the same length and contain the * same bytes */ /** * g_string_erase: * @string: a #GString * @pos: the position of the content to remove * @len: the number of bytes to remove, or -1 to remove all * following bytes * * Removes @len bytes from a #GString, starting at position @pos. * The rest of the #GString is shifted down to fill the gap. * * Returns: @string */ /** * g_string_free: * @string: a #GString * @free_segment: if %TRUE, the actual character data is freed as well * * Frees the memory allocated for the #GString. * If @free_segment is %TRUE it also frees the character data. If * it's %FALSE, the caller gains ownership of the buffer and must * free it after use with g_free(). * * Returns: the character data of @string * (i.e. %NULL if @free_segment is %TRUE) */ /** * g_string_free_to_bytes: * @string: (transfer full): a #GString * * Transfers ownership of the contents of @string to a newly allocated * #GBytes. The #GString structure itself is deallocated, and it is * therefore invalid to use @string after invoking this function. * * Note that while #GString ensures that its buffer always has a * trailing nul character (not reflected in its "len"), the returned * #GBytes does not include this extra nul; i.e. it has length exactly * equal to the "len" member. * * Returns: A newly allocated #GBytes containing contents of @string; @string itself is freed * Since: 2.34 */ /** * g_string_hash: * @str: a string to hash * * Creates a hash code for @str; for use with #GHashTable. * * Returns: hash code for @str */ /** * g_string_insert: * @string: a #GString * @pos: the position to insert the copy of the string * @val: the string to insert * * Inserts a copy of a string into a #GString, * expanding it if necessary. * * Returns: @string */ /** * g_string_insert_c: * @string: a #GString * @pos: the position to insert the byte * @c: the byte to insert * * Inserts a byte into a #GString, expanding it if necessary. * * Returns: @string */ /** * g_string_insert_len: * @string: a #GString * @pos: position in @string where insertion should * happen, or -1 for at the end * @val: bytes to insert * @len: number of bytes of @val to insert * * Inserts @len bytes of @val into @string at @pos. * Because @len is provided, @val may contain embedded * nuls and need not be nul-terminated. If @pos is -1, * bytes are inserted at the end of the string. * * Since this function does not stop at nul bytes, it is * the caller's responsibility to ensure that @val has at * least @len addressable bytes. * * Returns: @string */ /** * g_string_insert_unichar: * @string: a #GString * @pos: the position at which to insert character, or -1 * to append at the end of the string * @wc: a Unicode character * * Converts a Unicode character into UTF-8, and insert it * into the string at the given position. * * Returns: @string */ /** * g_string_new: * @init: (allow-none): the initial text to copy into the string, or %NULL to * start with an empty string. * * Creates a new #GString, initialized with the given string. * * Returns: the new #GString */ /** * g_string_new_len: * @init: initial contents of the string * @len: length of @init to use * * Creates a new #GString with @len bytes of the @init buffer. * Because a length is provided, @init need not be nul-terminated, * and can contain embedded nul bytes. * * Since this function does not stop at nul bytes, it is the caller's * responsibility to ensure that @init has at least @len addressable * bytes. * * Returns: a new #GString */ /** * g_string_overwrite: * @string: a #GString * @pos: the position at which to start overwriting * @val: the string that will overwrite the @string starting at @pos * * Overwrites part of a string, lengthening it if necessary. * * Returns: @string * Since: 2.14 */ /** * g_string_overwrite_len: * @string: a #GString * @pos: the position at which to start overwriting * @val: the string that will overwrite the @string starting at @pos * @len: the number of bytes to write from @val * * Overwrites part of a string, lengthening it if necessary. * This function will work with embedded nuls. * * Returns: @string * Since: 2.14 */ /** * g_string_prepend: * @string: a #GString * @val: the string to prepend on the start of @string * * Adds a string on to the start of a #GString, * expanding it if necessary. * * Returns: @string */ /** * g_string_prepend_c: * @string: a #GString * @c: the byte to prepend on the start of the #GString * * Adds a byte onto the start of a #GString, * expanding it if necessary. * * Returns: @string */ /** * g_string_prepend_len: * @string: a #GString * @val: bytes to prepend * @len: number of bytes in @val to prepend * * Prepends @len bytes of @val to @string. * Because @len is provided, @val may contain * embedded nuls and need not be nul-terminated. * * Since this function does not stop at nul bytes, * it is the caller's responsibility to ensure that * @val has at least @len addressable bytes. * * Returns: @string */ /** * g_string_prepend_unichar: * @string: a #GString * @wc: a Unicode character * * Converts a Unicode character into UTF-8, and prepends it * to the string. * * Returns: @string */ /** * g_string_printf: * @string: a #GString * @format: the string format. See the printf() documentation * @...: the parameters to insert into the format string * * Writes a formatted string into a #GString. * This is similar to the standard sprintf() function, * except that the #GString buffer automatically expands * to contain the results. The previous contents of the * #GString are destroyed. */ /** * g_string_set_size: * @string: a #GString * @len: the new length * * Sets the length of a #GString. If the length is less than * the current length, the string will be truncated. If the * length is greater than the current length, the contents * of the newly added area are undefined. (However, as * always, string->str[string->len] will be a nul byte.) * * Returns: @string */ /** * g_string_sized_new: * @dfl_size: the default size of the space allocated to * hold the string * * Creates a new #GString, with enough space for @dfl_size * bytes. This is useful if you are going to add a lot of * text to the string and don't want it to be reallocated * too often. * * Returns: the new #GString */ /** * g_string_sprintf: * @string: a #GString * @format: the string format. See the sprintf() documentation * @...: the parameters to insert into the format string * * Writes a formatted string into a #GString. * This is similar to the standard sprintf() function, * except that the #GString buffer automatically expands * to contain the results. The previous contents of the * #GString are destroyed. * * Deprecated: This function has been renamed to g_string_printf(). */ /** * g_string_sprintfa: * @string: a #GString * @format: the string format. See the sprintf() documentation * @...: the parameters to insert into the format string * * Appends a formatted string onto the end of a #GString. * This function is similar to g_string_sprintf() except that * the text is appended to the #GString. * * Deprecated: This function has been renamed to g_string_append_printf() */ /** * g_string_truncate: * @string: a #GString * @len: the new size of @string * * Cuts off the end of the GString, leaving the first @len bytes. * * Returns: @string */ /** * g_string_up: * @string: a #GString * * Converts a #GString to uppercase. * * Returns: @string * Deprecated: 2.2: This function uses the locale-specific * toupper() function, which is almost never the right thing. * Use g_string_ascii_up() or g_utf8_strup() instead. */ /** * g_string_vprintf: * @string: a #GString * @format: the string format. See the printf() documentation * @args: the parameters to insert into the format string * * Writes a formatted string into a #GString. * This function is similar to g_string_printf() except that * the arguments to the format string are passed as a va_list. * * Since: 2.14 */ /** * g_strip_context: * @msgid: a string * @msgval: another string * * An auxiliary function for gettext() support (see Q_()). * * Returns: @msgval, unless @msgval is identical to @msgid * and contains a '|' character, in which case a pointer to * the substring of msgid after the first '|' character is returned. * Since: 2.4 */ /** * g_strjoin: * @separator: (allow-none): a string to insert between each of the * strings, or %NULL * @...: a %NULL-terminated list of strings to join * * Joins a number of strings together to form one long string, with the * optional @separator inserted between each of them. The returned string * should be freed with g_free(). * * Returns: a newly-allocated string containing all of the strings joined * together, with @separator between them */ /** * g_strjoinv: * @separator: (allow-none): a string to insert between each of the * strings, or %NULL * @str_array: a %NULL-terminated array of strings to join * * Joins a number of strings together to form one long string, with the * optional @separator inserted between each of them. The returned string * should be freed with g_free(). * * Returns: a newly-allocated string containing all of the strings joined * together, with @separator between them */ /** * g_strlcat: * @dest: destination buffer, already containing one nul-terminated string * @src: source buffer * @dest_size: length of @dest buffer in bytes (not length of existing string * inside @dest) * * Portability wrapper that calls strlcat() on systems which have it, * and emulates it otherwise. Appends nul-terminated @src string to @dest, * guaranteeing nul-termination for @dest. The total size of @dest won't * exceed @dest_size. * * At most @dest_size - 1 characters will be copied. Unlike strncat(), * @dest_size is the full size of dest, not the space left over. This * function does not allocate memory. It always nul-terminates (unless * @dest_size == 0 or there were no nul characters in the @dest_size * characters of dest to start with). * * Caveat: this is supposedly a more secure alternative to strcat() or * strncat(), but for real security g_strconcat() is harder to mess up. * * Returns: size of attempted result, which is MIN (dest_size, strlen * (original dest)) + strlen (src), so if retval >= dest_size, * truncation occurred. */ /** * g_strlcpy: * @dest: destination buffer * @src: source buffer * @dest_size: length of @dest in bytes * * Portability wrapper that calls strlcpy() on systems which have it, * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is * guaranteed to be nul-terminated; @src must be nul-terminated; * @dest_size is the buffer size, not the number of bytes to copy. * * At most @dest_size - 1 characters will be copied. Always nul-terminates * (unless @dest_size is 0). This function does not allocate memory. Unlike * strncpy(), this function doesn't pad @dest (so it's often faster). It * returns the size of the attempted result, strlen (src), so if * @retval >= @dest_size, truncation occurred. * * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), * but if you really want to avoid screwups, g_strdup() is an even better * idea. * * Returns: length of @src */ /** * g_strncasecmp: * @s1: a string * @s2: a string to compare with @s1 * @n: the maximum number of characters to compare * * A case-insensitive string comparison, corresponding to the standard * strncasecmp() function on platforms which support it. It is similar * to g_strcasecmp() except it only compares the first @n characters of * the strings. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, * or a positive value if @s1 > @s2. * Deprecated: 2.2: The problem with g_strncasecmp() is that it does * the comparison by calling toupper()/tolower(). These functions * are locale-specific and operate on single bytes. However, it is * impossible to handle things correctly from an internationalization * standpoint by operating on bytes, since characters may be multibyte. * Thus g_strncasecmp() is broken if your string is guaranteed to be * ASCII, since it is locale-sensitive, and it's broken if your string * is localized, since it doesn't work on many encodings at all, * including UTF-8, EUC-JP, etc. * * There are therefore two replacement techniques: g_ascii_strncasecmp(), * which only works on ASCII and is not locale-sensitive, and * g_utf8_casefold() followed by strcmp() on the resulting strings, * which is good for case-insensitive sorting of UTF-8. */ /** * g_strndup: * @str: the string to duplicate * @n: the maximum number of bytes to copy from @str * * Duplicates the first @n bytes of a string, returning a newly-allocated * buffer @n + 1 bytes long which will always be nul-terminated. If @str * is less than @n bytes long the buffer is padded with nuls. If @str is * %NULL it returns %NULL. The returned value should be freed when no longer * needed. * * To copy a number of characters from a UTF-8 encoded string, * use g_utf8_strncpy() instead. * * Returns: a newly-allocated buffer containing the first @n bytes * of @str, nul-terminated */ /** * g_strnfill: * @length: the length of the new string * @fill_char: the byte to fill the string with * * Creates a new string @length bytes long filled with @fill_char. * The returned string should be freed when no longer needed. * * Returns: a newly-allocated string filled the @fill_char */ /** * g_strreverse: * @string: the string to reverse * * Reverses all of the bytes in a string. For example, * `g_strreverse ("abcdef")` will result in "fedcba". * * Note that g_strreverse() doesn't work on UTF-8 strings * containing multibyte characters. For that purpose, use * g_utf8_strreverse(). * * Returns: the same pointer passed in as @string */ /** * g_strrstr: * @haystack: a nul-terminated string * @needle: the nul-terminated string to search for * * Searches the string @haystack for the last occurrence * of the string @needle. * * Returns: a pointer to the found occurrence, or * %NULL if not found. */ /** * g_strrstr_len: * @haystack: a nul-terminated string * @haystack_len: the maximum length of @haystack * @needle: the nul-terminated string to search for * * Searches the string @haystack for the last occurrence * of the string @needle, limiting the length of the search * to @haystack_len. * * Returns: a pointer to the found occurrence, or * %NULL if not found. */ /** * g_strsignal: * @signum: the signal number. See the `signal` documentation * * Returns a string describing the given signal, e.g. "Segmentation fault". * You should use this function in preference to strsignal(), because it * returns a string in UTF-8 encoding, and since not all platforms support * the strsignal() function. * * Returns: a UTF-8 string describing the signal. If the signal is unknown, * it returns "unknown signal ()". */ /** * g_strsplit: * @string: a string to split * @delimiter: a string which specifies the places at which to split * the string. The delimiter is not included in any of the resulting * strings, unless @max_tokens is reached. * @max_tokens: the maximum number of pieces to split @string into. * If this is less than 1, the string is split completely. * * Splits a string into a maximum of @max_tokens pieces, using the given * @delimiter. If @max_tokens is reached, the remainder of @string is * appended to the last token. * * As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a * %NULL-terminated vector containing the six strings "", "a", "bc", "", "d" * and "". * * As a special case, the result of splitting the empty string "" is an empty * vector, not a vector containing a single string. The reason for this * special case is that being able to represent a empty vector is typically * more useful than consistent handling of empty elements. If you do need * to represent empty elements, you'll need to check for the empty string * before calling g_strsplit(). * * Returns: a newly-allocated %NULL-terminated array of strings. Use * g_strfreev() to free it. */ /** * g_strsplit_set: * @string: The string to be tokenized * @delimiters: A nul-terminated string containing bytes that are used * to split the string. * @max_tokens: The maximum number of tokens to split @string into. * If this is less than 1, the string is split completely * * Splits @string into a number of tokens not containing any of the characters * in @delimiter. A token is the (possibly empty) longest string that does not * contain any of the characters in @delimiters. If @max_tokens is reached, the * remainder is appended to the last token. * * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a * %NULL-terminated vector containing the three strings "abc", "def", * and "ghi". * * The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated * vector containing the four strings "", "def", "ghi", and "". * * As a special case, the result of splitting the empty string "" is an empty * vector, not a vector containing a single string. The reason for this * special case is that being able to represent a empty vector is typically * more useful than consistent handling of empty elements. If you do need * to represent empty elements, you'll need to check for the empty string * before calling g_strsplit_set(). * * Note that this function works on bytes not characters, so it can't be used * to delimit UTF-8 strings for anything but ASCII characters. * * Returns: a newly-allocated %NULL-terminated array of strings. Use * g_strfreev() to free it. * Since: 2.4 */ /** * g_strstr_len: * @haystack: a string * @haystack_len: the maximum length of @haystack. Note that -1 is * a valid length, if @haystack is nul-terminated, meaning it will * search through the whole string. * @needle: the string to search for * * Searches the string @haystack for the first occurrence * of the string @needle, limiting the length of the search * to @haystack_len. * * Returns: a pointer to the found occurrence, or * %NULL if not found. */ /** * g_strstrip: * @string: a string to remove the leading and trailing whitespace from * * Removes leading and trailing whitespace from a string. * See g_strchomp() and g_strchug(). * * Returns: @string */ /** * g_strtod: * @nptr: the string to convert to a numeric value. * @endptr: if non-%NULL, it returns the character after * the last character used in the conversion. * * Converts a string to a #gdouble value. * It calls the standard strtod() function to handle the conversion, but * if the string is not completely converted it attempts the conversion * again with g_ascii_strtod(), and returns the best match. * * This function should seldom be used. The normal situation when reading * numbers not for human consumption is to use g_ascii_strtod(). Only when * you know that you must expect both locale formatted and C formatted numbers * should you use this. Make sure that you don't pass strings such as comma * separated lists of values, since the commas may be interpreted as a decimal * point in some locales, causing unexpected results. * * Returns: the #gdouble value. */ /** * g_strup: * @string: the string to convert * * Converts a string to upper case. * * Returns: the string * Deprecated: 2.2: This function is totally broken for the reasons * discussed in the g_strncasecmp() docs - use g_ascii_strup() * or g_utf8_strup() instead. */ /** * g_strv_length: * @str_array: a %NULL-terminated array of strings * * Returns the length of the given %NULL-terminated * string array @str_array. * * Returns: length of @str_array. * Since: 2.6 */ /** * g_test_add: * @testpath: The test path for a new test case. * @Fixture: The type of a fixture data structure. * @tdata: Data argument for the test functions. * @fsetup: The function to set up the fixture data. * @ftest: The actual test function. * @fteardown: The function to tear down the fixture data. * * Hook up a new test case at @testpath, similar to g_test_add_func(). * A fixture data structure with setup and teardown function may be provided * though, similar to g_test_create_case(). * g_test_add() is implemented as a macro, so that the fsetup(), ftest() and * fteardown() callbacks can expect a @Fixture pointer as first argument in * a type safe manner. * * Since: 2.16 */ /** * g_test_add_data_func: * @testpath: /-separated test case path name for the test. * @test_data: Test data argument for the test function. * @test_func: The test function to invoke for this test. * * Create a new test case, similar to g_test_create_case(). However * the test is assumed to use no fixture, and test suites are automatically * created on the fly and added to the root fixture, based on the * slash-separated portions of @testpath. The @test_data argument * will be passed as first argument to @test_func. * * If @testpath includes the component "subprocess" anywhere in it, * the test will be skipped by default, and only run if explicitly * required via the `-p` command-line option or g_test_trap_subprocess(). * * Since: 2.16 */ /** * g_test_add_data_func_full: * @testpath: /-separated test case path name for the test. * @test_data: Test data argument for the test function. * @test_func: The test function to invoke for this test. * @data_free_func: #GDestroyNotify for @test_data. * * Create a new test case, as with g_test_add_data_func(), but freeing * @test_data after the test run is complete. * * Since: 2.34 */ /** * g_test_add_func: * @testpath: /-separated test case path name for the test. * @test_func: The test function to invoke for this test. * * Create a new test case, similar to g_test_create_case(). However * the test is assumed to use no fixture, and test suites are automatically * created on the fly and added to the root fixture, based on the * slash-separated portions of @testpath. * * If @testpath includes the component "subprocess" anywhere in it, * the test will be skipped by default, and only run if explicitly * required via the `-p` command-line option or g_test_trap_subprocess(). * * Since: 2.16 */ /** * g_test_assert_expected_messages: * * Asserts that all messages previously indicated via * g_test_expect_message() have been seen and suppressed. * * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly * expected via g_test_expect_message() then they will be ignored. * * Since: 2.34 */ /** * g_test_bug: * @bug_uri_snippet: Bug specific bug tracker URI portion. * * This function adds a message to test reports that * associates a bug URI with a test case. * Bug URIs are constructed from a base URI set with g_test_bug_base() * and @bug_uri_snippet. * * Since: 2.16 */ /** * g_test_bug_base: * @uri_pattern: the base pattern for bug URIs * * Specify the base URI for bug reports. * * The base URI is used to construct bug report messages for * g_test_message() when g_test_bug() is called. * Calling this function outside of a test case sets the * default base URI for all test cases. Calling it from within * a test case changes the base URI for the scope of the test * case only. * Bug URIs are constructed by appending a bug specific URI * portion to @uri_pattern, or by replacing the special string * '\%s' within @uri_pattern if that is present. * * Since: 2.16 */ /** * g_test_build_filename: * @file_type: the type of file (built vs. distributed) * @first_path: the first segment of the pathname * @...: %NULL-terminated additional path segments * * Creates the pathname to a data file that is required for a test. * * This function is conceptually similar to g_build_filename() except * that the first argument has been replaced with a #GTestFileType * argument. * * The data file should either have been distributed with the module * containing the test (%G_TEST_DIST) or built as part of the build * system of that module (%G_TEST_BUILT). * * In order for this function to work in srcdir != builddir situations, * the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to * have been defined. As of 2.38, this is done by the glib.mk * included in GLib. Please ensure that your copy is up to date before * using this function. * * In case neither variable is set, this function will fall back to * using the dirname portion of argv[0], possibly removing ".libs". * This allows for casual running of tests directly from the commandline * in the srcdir == builddir case and should also support running of * installed tests, assuming the data files have been installed in the * same relative path as the test binary. * * Returns: the path of the file, to be freed using g_free() * Since: 2.38 */ /** * g_test_create_case: * @test_name: the name for the test case * @data_size: the size of the fixture data structure * @test_data: test data argument for the test functions * @data_setup: the function to set up the fixture data * @data_test: the actual test function * @data_teardown: the function to teardown the fixture data * * Create a new #GTestCase, named @test_name, this API is fairly * low level, calling g_test_add() or g_test_add_func() is preferable. * When this test is executed, a fixture structure of size @data_size * will be allocated and filled with 0s. Then @data_setup is called * to initialize the fixture. After fixture setup, the actual test * function @data_test is called. Once the test run completed, the * fixture structure is torn down by calling @data_teardown and * after that the memory is released. * * Splitting up a test run into fixture setup, test function and * fixture teardown is most usful if the same fixture is used for * multiple tests. In this cases, g_test_create_case() will be * called with the same fixture, but varying @test_name and * @data_test arguments. * * Returns: a newly allocated #GTestCase. * Since: 2.16 */ /** * g_test_create_suite: * @suite_name: a name for the suite * * Create a new test suite with the name @suite_name. * * Returns: A newly allocated #GTestSuite instance. * Since: 2.16 */ /** * g_test_expect_message: * @log_domain: (allow-none): the log domain of the message * @log_level: the log level of the message * @pattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Indicates that a message with the given @log_domain and @log_level, * with text matching @pattern, is expected to be logged. When this * message is logged, it will not be printed, and the test case will * not abort. * * Use g_test_assert_expected_messages() to assert that all * previously-expected messages have been seen and suppressed. * * You can call this multiple times in a row, if multiple messages are * expected as a result of a single call. (The messages must appear in * the same order as the calls to g_test_expect_message().) * * For example: * * |[ * // g_main_context_push_thread_default() should fail if the * // context is already owned by another thread. * g_test_expect_message (G_LOG_DOMAIN, * G_LOG_LEVEL_CRITICAL, * "assertion*acquired_context*failed"); * g_main_context_push_thread_default (bad_context); * g_test_assert_expected_messages (); * ]| * * Note that you cannot use this to test g_error() messages, since * g_error() intentionally never returns even if the program doesn't * abort; use g_test_trap_subprocess() in this case. * * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly * expected via g_test_expect_message() then they will be ignored. * * Since: 2.34 */ /** * g_test_fail: * * Indicates that a test failed. This function can be called * multiple times from the same test. You can use this function * if your test failed in a recoverable way. * * Do not use this function if the failure of a test could cause * other tests to malfunction. * * Calling this function will not stop the test from running, you * need to return from the test function yourself. So you can * produce additional diagnostic messages or even continue running * the test. * * If not called from inside a test, this function does nothing. * * Since: 2.30 */ /** * g_test_failed: * * Returns whether a test has already failed. This will * be the case when g_test_fail(), g_test_incomplete() * or g_test_skip() have been called, but also if an * assertion has failed. * * This can be useful to return early from a test if * continuing after a failed assertion might be harmful. * * The return value of this function is only meaningful * if it is called from inside a test function. * * Returns: %TRUE if the test has failed * Since: 2.38 */ /** * g_test_get_dir: * @file_type: the type of file (built vs. distributed) * * Gets the pathname of the directory containing test files of the type * specified by @file_type. * * This is approximately the same as calling g_test_build_filename("."), * but you don't need to free the return value. * * Returns: the path of the directory, owned by GLib * Since: 2.38 */ /** * g_test_get_filename: * @file_type: the type of file (built vs. distributed) * @first_path: the first segment of the pathname * @...: %NULL-terminated additional path segments * * Gets the pathname to a data file that is required for a test. * * This is the same as g_test_build_filename() with two differences. * The first difference is that must only use this function from within * a testcase function. The second difference is that you need not free * the return value -- it will be automatically freed when the testcase * finishes running. * * It is safe to use this function from a thread inside of a testcase * but you must ensure that all such uses occur before the main testcase * function returns (ie: it is best to ensure that all threads have been * joined). * * Returns: the path, automatically freed at the end of the testcase * Since: 2.38 */ /** * g_test_get_root: * * Get the toplevel test suite for the test path API. * * Returns: the toplevel #GTestSuite * Since: 2.16 */ /** * g_test_incomplete: * @msg: (allow-none): explanation * * Indicates that a test failed because of some incomplete * functionality. This function can be called multiple times * from the same test. * * Calling this function will not stop the test from running, you * need to return from the test function yourself. So you can * produce additional diagnostic messages or even continue running * the test. * * If not called from inside a test, this function does nothing. * * Since: 2.38 */ /** * g_test_init: * @argc: Address of the @argc parameter of the main() function. * Changed if any arguments were handled. * @argv: Address of the @argv parameter of main(). * Any parameters understood by g_test_init() stripped before return. * @...: %NULL-terminated list of special options. Currently the only * defined option is `"no_g_set_prgname"`, which * will cause g_test_init() to not call g_set_prgname(). * * Initialize the GLib testing framework, e.g. by seeding the * test random number generator, the name for g_get_prgname() * and parsing test related command line args. * * So far, the following arguments are understood: * * - `-l`: List test cases available in a test executable. * - `--seed=SEED`: Provide a random seed to reproduce test * runs using random numbers. * - `--verbose`: Run tests verbosely. * - `-q`, `--quiet`: Run tests quietly. * - `-p PATH`: Execute all tests matching the given path. * This can also be used to force a test to run that would otherwise * be skipped (ie, a test whose name contains "/subprocess"). * - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: * * `perf`: Performance tests, may take long and report results. * * `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage. * * `quick`: Quick tests, should run really quickly and give good coverage. * * `undefined`: Tests for undefined behaviour, may provoke programming errors * under g_test_trap_subprocess() or g_test_expect_messages() to check * that appropriate assertions or warnings are given * * `no-undefined`: Avoid tests for undefined behaviour * * - `--debug-log`: Debug test logging output. * * Since: 2.16 */ /** * g_test_initialized: * * Returns %TRUE if g_test_init() has been called. * * Returns: %TRUE if g_test_init() has been called. * Since: 2.36 */ /** * g_test_log_buffer_free: * * Internal function for gtester to free test log messages, no ABI guarantees provided. */ /** * g_test_log_buffer_new: * * Internal function for gtester to decode test log messages, no ABI guarantees provided. */ /** * g_test_log_buffer_pop: * * Internal function for gtester to retrieve test log messages, no ABI guarantees provided. */ /** * g_test_log_buffer_push: * * Internal function for gtester to decode test log messages, no ABI guarantees provided. */ /** * g_test_log_msg_free: * * Internal function for gtester to free test log messages, no ABI guarantees provided. */ /** * g_test_log_set_fatal_handler: * @log_func: the log handler function. * @user_data: data passed to the log handler. * * Installs a non-error fatal log handler which can be * used to decide whether log messages which are counted * as fatal abort the program. * * The use case here is that you are running a test case * that depends on particular libraries or circumstances * and cannot prevent certain known critical or warning * messages. So you install a handler that compares the * domain and message to precisely not abort in such a case. * * Note that the handler is reset at the beginning of * any test case, so you have to set it inside each test * function which needs the special behavior. * * This handler has no effect on g_error messages. * * Since: 2.22 */ /** * g_test_maximized_result: * @maximized_quantity: the reported value * @format: the format string of the report message * @...: arguments to pass to the printf() function * * Report the result of a performance or measurement test. * The test should generally strive to maximize the reported * quantities (larger values are better than smaller ones), * this and @maximized_quantity can determine sorting * order for test result reports. * * Since: 2.16 */ /** * g_test_message: * @format: the format string * @...: printf-like arguments to @format * * Add a message to the test report. * * Since: 2.16 */ /** * g_test_minimized_result: * @minimized_quantity: the reported value * @format: the format string of the report message * @...: arguments to pass to the printf() function * * Report the result of a performance or measurement test. * The test should generally strive to minimize the reported * quantities (smaller values are better than larger ones), * this and @minimized_quantity can determine sorting * order for test result reports. * * Since: 2.16 */ /** * g_test_perf: * * Returns %TRUE if tests are run in performance mode. * * Returns: %TRUE if in performance mode */ /** * g_test_queue_destroy: * @destroy_func: Destroy callback for teardown phase. * @destroy_data: Destroy callback data. * * This function enqueus a callback @destroy_func to be executed * during the next test case teardown phase. This is most useful * to auto destruct allocted test resources at the end of a test run. * Resources are released in reverse queue order, that means enqueueing * callback A before callback B will cause B() to be called before * A() during teardown. * * Since: 2.16 */ /** * g_test_queue_free: * @gfree_pointer: the pointer to be stored. * * Enqueue a pointer to be released with g_free() during the next * teardown phase. This is equivalent to calling g_test_queue_destroy() * with a destroy callback of g_free(). * * Since: 2.16 */ /** * g_test_queue_unref: * @gobject: the object to unref * * Enqueue an object to be released with g_object_unref() during * the next teardown phase. This is equivalent to calling * g_test_queue_destroy() with a destroy callback of g_object_unref(). * * Since: 2.16 */ /** * g_test_quick: * * Returns %TRUE if tests are run in quick mode. * Exactly one of g_test_quick() and g_test_slow() is active in any run; * there is no "medium speed". * * Returns: %TRUE if in quick mode */ /** * g_test_quiet: * * Returns %TRUE if tests are run in quiet mode. * The default is neither g_test_verbose() nor g_test_quiet(). * * Returns: %TRUE if in quiet mode */ /** * g_test_rand_bit: * * Get a reproducible random bit (0 or 1), see g_test_rand_int() * for details on test case random numbers. * * Since: 2.16 */ /** * g_test_rand_double: * * Get a reproducible random floating point number, * see g_test_rand_int() for details on test case random numbers. * * Returns: a random number from the seeded random number generator. * Since: 2.16 */ /** * g_test_rand_double_range: * @range_start: the minimum value returned by this function * @range_end: the minimum value not returned by this function * * Get a reproducible random floating pointer number out of a specified range, * see g_test_rand_int() for details on test case random numbers. * * Returns: a number with @range_start <= number < @range_end. * Since: 2.16 */ /** * g_test_rand_int: * * Get a reproducible random integer number. * * The random numbers generated by the g_test_rand_*() family of functions * change with every new test program start, unless the --seed option is * given when starting test programs. * * For individual test cases however, the random number generator is * reseeded, to avoid dependencies between tests and to make --seed * effective for all test cases. * * Returns: a random number from the seeded random number generator. * Since: 2.16 */ /** * g_test_rand_int_range: * @begin: the minimum value returned by this function * @end: the smallest value not to be returned by this function * * Get a reproducible random integer number out of a specified range, * see g_test_rand_int() for details on test case random numbers. * * Returns: a number with @begin <= number < @end. * Since: 2.16 */ /** * g_test_run: * * Runs all tests under the toplevel suite which can be retrieved * with g_test_get_root(). Similar to g_test_run_suite(), the test * cases to be run are filtered according to test path arguments * (`-p testpath`) as parsed by g_test_init(). g_test_run_suite() * or g_test_run() may only be called once in a program. * * In general, the tests and sub-suites within each suite are run in * the order in which they are defined. However, note that prior to * GLib 2.36, there was a bug in the `g_test_add_*` * functions which caused them to create multiple suites with the same * name, meaning that if you created tests "/foo/simple", * "/bar/simple", and "/foo/using-bar" in that order, they would get * run in that order (since g_test_run() would run the first "/foo" * suite, then the "/bar" suite, then the second "/foo" suite). As of * 2.36, this bug is fixed, and adding the tests in that order would * result in a running order of "/foo/simple", "/foo/using-bar", * "/bar/simple". If this new ordering is sub-optimal (because it puts * more-complicated tests before simpler ones, making it harder to * figure out exactly what has failed), you can fix it by changing the * test paths to group tests by suite in a way that will result in the * desired running order. Eg, "/simple/foo", "/simple/bar", * "/complex/foo-using-bar". * * However, you should never make the actual result of a test depend * on the order that tests are run in. If you need to ensure that some * particular code runs before or after a given test case, use * g_test_add(), which lets you specify setup and teardown functions. * * If all tests are skipped, this function will return 0 if * producing TAP output, or 77 (treated as "skip test" by Automake) otherwise. * * Returns: 0 on success, 1 on failure (assuming it returns at all), * 0 or 77 if all tests were skipped with g_test_skip() * Since: 2.16 */ /** * g_test_run_suite: * @suite: a #GTestSuite * * Execute the tests within @suite and all nested #GTestSuites. * The test suites to be executed are filtered according to * test path arguments (`-p testpath`) as parsed by g_test_init(). * See the g_test_run() documentation for more information on the * order that tests are run in. * * g_test_run_suite() or g_test_run() may only be called once * in a program. * * Returns: 0 on success * Since: 2.16 */ /** * g_test_set_nonfatal_assertions: * * Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(), * g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(), * g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), * g_assert_error(), g_test_assert_expected_messages() and the various * g_test_trap_assert_*() macros to not abort to program, but instead * call g_test_fail() and continue. (This also changes the behavior of * g_test_fail() so that it will not cause the test program to abort * after completing the failed test.) * * Note that the g_assert_not_reached() and g_assert() are not * affected by this. * * This function can only be called after g_test_init(). * * Since: 2.38 */ /** * g_test_skip: * @msg: (allow-none): explanation * * Indicates that a test was skipped. * * Calling this function will not stop the test from running, you * need to return from the test function yourself. So you can * produce additional diagnostic messages or even continue running * the test. * * If not called from inside a test, this function does nothing. * * Since: 2.38 */ /** * g_test_slow: * * Returns %TRUE if tests are run in slow mode. * Exactly one of g_test_quick() and g_test_slow() is active in any run; * there is no "medium speed". * * Returns: the opposite of g_test_quick() */ /** * g_test_subprocess: * * Returns %TRUE (after g_test_init() has been called) if the test * program is running under g_test_trap_subprocess(). * * Returns: %TRUE if the test program is running under * g_test_trap_subprocess(). * Since: 2.38 */ /** * g_test_suite_add: * @suite: a #GTestSuite * @test_case: a #GTestCase * * Adds @test_case to @suite. * * Since: 2.16 */ /** * g_test_suite_add_suite: * @suite: a #GTestSuite * @nestedsuite: another #GTestSuite * * Adds @nestedsuite to @suite. * * Since: 2.16 */ /** * g_test_thorough: * * Returns %TRUE if tests are run in thorough mode, equivalent to * g_test_slow(). * * Returns: the same thing as g_test_slow() */ /** * g_test_timer_elapsed: * * Get the time since the last start of the timer with g_test_timer_start(). * * Returns: the time since the last start of the timer, as a double * Since: 2.16 */ /** * g_test_timer_last: * * Report the last result of g_test_timer_elapsed(). * * Returns: the last result of g_test_timer_elapsed(), as a double * Since: 2.16 */ /** * g_test_timer_start: * * Start a timing test. Call g_test_timer_elapsed() when the task is supposed * to be done. Call this function again to restart the timer. * * Since: 2.16 */ /** * g_test_trap_assert_failed: * * Assert that the last test subprocess failed. * See g_test_trap_subprocess(). * * This is sometimes used to test situations that are formally considered to * be undefined behaviour, like inputs that fail a g_return_if_fail() * check. In these situations you should skip the entire test, including the * call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE * to indicate that undefined behaviour may be tested. * * Since: 2.16 */ /** * g_test_trap_assert_passed: * * Assert that the last test subprocess passed. * See g_test_trap_subprocess(). * * Since: 2.16 */ /** * g_test_trap_assert_stderr: * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stderr output of the last test subprocess * matches @serrpattern. See g_test_trap_subprocess(). * * This is sometimes used to test situations that are formally * considered to be undefined behaviour, like code that hits a * g_assert() or g_error(). In these situations you should skip the * entire test, including the call to g_test_trap_subprocess(), unless * g_test_undefined() returns %TRUE to indicate that undefined * behaviour may be tested. * * Since: 2.16 */ /** * g_test_trap_assert_stderr_unmatched: * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stderr output of the last test subprocess * does not match @serrpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ /** * g_test_trap_assert_stdout: * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stdout output of the last test subprocess matches * @soutpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ /** * g_test_trap_assert_stdout_unmatched: * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stdout output of the last test subprocess * does not match @soutpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ /** * g_test_trap_fork: * @usec_timeout: Timeout for the forked test in micro seconds. * @test_trap_flags: Flags to modify forking behaviour. * * Fork the current test program to execute a test case that might * not return or that might abort. * * If @usec_timeout is non-0, the forked test case is aborted and * considered failing if its run time exceeds it. * * The forking behavior can be configured with the #GTestTrapFlags flags. * * In the following example, the test code forks, the forked child * process produces some sample output and exits successfully. * The forking parent process then asserts successful child program * termination and validates child program outputs. * * |[ * static void * test_fork_patterns (void) * { * if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) * { * g_print ("some stdout text: somagic17\n"); * g_printerr ("some stderr text: semagic43\n"); * exit (0); // successful test run * } * g_test_trap_assert_passed (); * g_test_trap_assert_stdout ("*somagic17*"); * g_test_trap_assert_stderr ("*semagic43*"); * } * ]| * * Returns: %TRUE for the forked child and %FALSE for the executing parent process. * Since: 2.16 * Deprecated: This function is implemented only on Unix platforms, * and is not always reliable due to problems inherent in * fork-without-exec. Use g_test_trap_subprocess() instead. */ /** * g_test_trap_has_passed: * * Check the result of the last g_test_trap_subprocess() call. * * Returns: %TRUE if the last test subprocess terminated successfully. * Since: 2.16 */ /** * g_test_trap_reached_timeout: * * Check the result of the last g_test_trap_subprocess() call. * * Returns: %TRUE if the last test subprocess got killed due to a timeout. * Since: 2.16 */ /** * g_test_trap_subprocess: * @test_path: (allow-none): Test to run in a subprocess * @usec_timeout: Timeout for the subprocess test in micro seconds. * @test_flags: Flags to modify subprocess behaviour. * * Respawns the test program to run only @test_path in a subprocess. * This can be used for a test case that might not return, or that * might abort. * * If @test_path is %NULL then the same test is re-run in a subprocess. * You can use g_test_subprocess() to determine whether the test is in * a subprocess or not. * * @test_path can also be the name of the parent test, followed by * "`/subprocess/`" and then a name for the specific subtest (or just * ending with "`/subprocess`" if the test only has one child test); * tests with names of this form will automatically be skipped in the * parent process. * * If @usec_timeout is non-0, the test subprocess is aborted and * considered failing if its run time exceeds it. * * The subprocess behavior can be configured with the * #GTestSubprocessFlags flags. * * You can use methods such as g_test_trap_assert_passed(), * g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to * check the results of the subprocess. (But note that * g_test_trap_assert_stdout() and g_test_trap_assert_stderr() * cannot be used if @test_flags specifies that the child should * inherit the parent stdout/stderr.) * * If your `main ()` needs to behave differently in * the subprocess, you can call g_test_subprocess() (after calling * g_test_init()) to see whether you are in a subprocess. * * The following example tests that calling * `my_object_new(1000000)` will abort with an error * message. * * |[ * static void * test_create_large_object_subprocess (void) * { * if (g_test_subprocess ()) * { * my_object_new (1000000); * return; * } * * // Reruns this same test in a subprocess * g_test_trap_subprocess (NULL, 0, 0); * g_test_trap_assert_failed (); * g_test_trap_assert_stderr ("*ERROR*too large*"); * } * * int * main (int argc, char **argv) * { * g_test_init (&argc, &argv, NULL); * * g_test_add_func ("/myobject/create_large_object", * test_create_large_object); * return g_test_run (); * } * ]| * * Since: 2.38 */ /** * g_test_undefined: * * Returns %TRUE if tests may provoke assertions and other formally-undefined * behaviour, to verify that appropriate warnings are given. It might, in some * cases, be useful to turn this off if running tests under valgrind. * * Returns: %TRUE if tests may provoke programming errors */ /** * g_test_verbose: * * Returns %TRUE if tests are run in verbose mode. * The default is neither g_test_verbose() nor g_test_quiet(). * * Returns: %TRUE if in verbose mode */ /** * g_thread_exit: * @retval: the return value of this thread * * Terminates the current thread. * * If another thread is waiting for us using g_thread_join() then the * waiting thread will be woken up and get @retval as the return value * of g_thread_join(). * * Calling g_thread_exit() with a parameter @retval is equivalent to * returning @retval from the function @func, as given to g_thread_new(). * * You must only call g_thread_exit() from a thread that you created * yourself with g_thread_new() or related APIs. You must not call * this function from a thread created with another threading library * or or from within a #GThreadPool. */ /** * g_thread_join: * @thread: a #GThread * * Waits until @thread finishes, i.e. the function @func, as * given to g_thread_new(), returns or g_thread_exit() is called. * If @thread has already terminated, then g_thread_join() * returns immediately. * * Any thread can wait for any other thread by calling g_thread_join(), * not just its 'creator'. Calling g_thread_join() from multiple threads * for the same @thread leads to undefined behaviour. * * The value returned by @func or given to g_thread_exit() is * returned by this function. * * g_thread_join() consumes the reference to the passed-in @thread. * This will usually cause the #GThread struct and associated resources * to be freed. Use g_thread_ref() to obtain an extra reference if you * want to keep the GThread alive beyond the g_thread_join() call. * * Returns: the return value of the thread */ /** * g_thread_new: * @name: (allow-none): an (optional) name for the new thread * @func: a function to execute in the new thread * @data: an argument to supply to the new thread * * This function creates a new thread. The new thread starts by invoking * @func with the argument data. The thread will run until @func returns * or until g_thread_exit() is called from the new thread. The return value * of @func becomes the return value of the thread, which can be obtained * with g_thread_join(). * * The @name can be useful for discriminating threads in a debugger. * It is not used for other purposes and does not have to be unique. * Some systems restrict the length of @name to 16 bytes. * * If the thread can not be created the program aborts. See * g_thread_try_new() if you want to attempt to deal with failures. * * To free the struct returned by this function, use g_thread_unref(). * Note that g_thread_join() implicitly unrefs the #GThread as well. * * Returns: the new #GThread * Since: 2.32 */ /** * g_thread_pool_free: * @pool: a #GThreadPool * @immediate: should @pool shut down immediately? * @wait_: should the function wait for all tasks to be finished? * * Frees all resources allocated for @pool. * * If @immediate is %TRUE, no new task is processed for @pool. * Otherwise @pool is not freed before the last task is processed. * Note however, that no thread of this pool is interrupted while * processing a task. Instead at least all still running threads * can finish their tasks before the @pool is freed. * * If @wait_ is %TRUE, the functions does not return before all * tasks to be processed (dependent on @immediate, whether all * or only the currently running) are ready. * Otherwise the function returns immediately. * * After calling this function @pool must not be used anymore. */ /** * g_thread_pool_get_max_idle_time: * * This function will return the maximum @interval that a * thread will wait in the thread pool for new tasks before * being stopped. * * If this function returns 0, threads waiting in the thread * pool for new work are not stopped. * * Returns: the maximum @interval (milliseconds) to wait * for new tasks in the thread pool before stopping the * thread * Since: 2.10 */ /** * g_thread_pool_get_max_threads: * @pool: a #GThreadPool * * Returns the maximal number of threads for @pool. * * Returns: the maximal number of threads */ /** * g_thread_pool_get_max_unused_threads: * * Returns the maximal allowed number of unused threads. * * Returns: the maximal number of unused threads */ /** * g_thread_pool_get_num_threads: * @pool: a #GThreadPool * * Returns the number of threads currently running in @pool. * * Returns: the number of threads currently running */ /** * g_thread_pool_get_num_unused_threads: * * Returns the number of currently unused threads. * * Returns: the number of currently unused threads */ /** * g_thread_pool_new: * @func: a function to execute in the threads of the new thread pool * @user_data: user data that is handed over to @func every time it * is called * @max_threads: the maximal number of threads to execute concurrently * in the new thread pool, -1 means no limit * @exclusive: should this thread pool be exclusive? * @error: return location for error, or %NULL * * This function creates a new thread pool. * * Whenever you call g_thread_pool_push(), either a new thread is * created or an unused one is reused. At most @max_threads threads * are running concurrently for this thread pool. @max_threads = -1 * allows unlimited threads to be created for this thread pool. The * newly created or reused thread now executes the function @func * with the two arguments. The first one is the parameter to * g_thread_pool_push() and the second one is @user_data. * * The parameter @exclusive determines whether the thread pool owns * all threads exclusive or shares them with other thread pools. * If @exclusive is %TRUE, @max_threads threads are started * immediately and they will run exclusively for this thread pool * until it is destroyed by g_thread_pool_free(). If @exclusive is * %FALSE, threads are created when needed and shared between all * non-exclusive thread pools. This implies that @max_threads may * not be -1 for exclusive thread pools. * * @error can be %NULL to ignore errors, or non-%NULL to report * errors. An error can only occur when @exclusive is set to %TRUE * and not all @max_threads threads could be created. * * Returns: the new #GThreadPool */ /** * g_thread_pool_push: * @pool: a #GThreadPool * @data: a new task for @pool * @error: return location for error, or %NULL * * Inserts @data into the list of tasks to be executed by @pool. * * When the number of currently running threads is lower than the * maximal allowed number of threads, a new thread is started (or * reused) with the properties given to g_thread_pool_new(). * Otherwise, @data stays in the queue until a thread in this pool * finishes its previous task and processes @data. * * @error can be %NULL to ignore errors, or non-%NULL to report * errors. An error can only occur when a new thread couldn't be * created. In that case @data is simply appended to the queue of * work to do. * * Before version 2.32, this function did not return a success status. * * Returns: %TRUE on success, %FALSE if an error occurred */ /** * g_thread_pool_set_max_idle_time: * @interval: the maximum @interval (in milliseconds) * a thread can be idle * * This function will set the maximum @interval that a thread * waiting in the pool for new tasks can be idle for before * being stopped. This function is similar to calling * g_thread_pool_stop_unused_threads() on a regular timeout, * except this is done on a per thread basis. * * By setting @interval to 0, idle threads will not be stopped. * * The default value is 15000 (15 seconds). * * Since: 2.10 */ /** * g_thread_pool_set_max_threads: * @pool: a #GThreadPool * @max_threads: a new maximal number of threads for @pool, * or -1 for unlimited * @error: return location for error, or %NULL * * Sets the maximal allowed number of threads for @pool. * A value of -1 means that the maximal number of threads * is unlimited. If @pool is an exclusive thread pool, setting * the maximal number of threads to -1 is not allowed. * * Setting @max_threads to 0 means stopping all work for @pool. * It is effectively frozen until @max_threads is set to a non-zero * value again. * * A thread is never terminated while calling @func, as supplied by * g_thread_pool_new(). Instead the maximal number of threads only * has effect for the allocation of new threads in g_thread_pool_push(). * A new thread is allocated, whenever the number of currently * running threads in @pool is smaller than the maximal number. * * @error can be %NULL to ignore errors, or non-%NULL to report * errors. An error can only occur when a new thread couldn't be * created. * * Before version 2.32, this function did not return a success status. * * Returns: %TRUE on success, %FALSE if an error occurred */ /** * g_thread_pool_set_max_unused_threads: * @max_threads: maximal number of unused threads * * Sets the maximal number of unused threads to @max_threads. * If @max_threads is -1, no limit is imposed on the number * of unused threads. * * The default value is 2. */ /** * g_thread_pool_set_sort_function: * @pool: a #GThreadPool * @func: the #GCompareDataFunc used to sort the list of tasks. * This function is passed two tasks. It should return * 0 if the order in which they are handled does not matter, * a negative value if the first task should be processed before * the second or a positive value if the second task should be * processed first. * @user_data: user data passed to @func * * Sets the function used to sort the list of tasks. This allows the * tasks to be processed by a priority determined by @func, and not * just in the order in which they were added to the pool. * * Note, if the maximum number of threads is more than 1, the order * that threads are executed cannot be guaranteed 100%. Threads are * scheduled by the operating system and are executed at random. It * cannot be assumed that threads are executed in the order they are * created. * * Since: 2.10 */ /** * g_thread_pool_stop_unused_threads: * * Stops all currently unused threads. This does not change the * maximal number of unused threads. This function can be used to * regularly stop all unused threads e.g. from g_timeout_add(). */ /** * g_thread_pool_unprocessed: * @pool: a #GThreadPool * * Returns the number of tasks still unprocessed in @pool. * * Returns: the number of unprocessed tasks */ /** * g_thread_ref: * @thread: a #GThread * * Increase the reference count on @thread. * * Returns: a new reference to @thread * Since: 2.32 */ /** * g_thread_self: * * This functions returns the #GThread corresponding to the * current thread. Note that this function does not increase * the reference count of the returned struct. * * This function will return a #GThread even for threads that * were not created by GLib (i.e. those created by other threading * APIs). This may be useful for thread identification purposes * (i.e. comparisons) but you must not use GLib functions (such * as g_thread_join()) on these threads. * * Returns: the #GThread representing the current thread */ /** * g_thread_supported: * * This macro returns %TRUE if the thread system is initialized, * and %FALSE if it is not. * * For language bindings, g_thread_get_initialized() provides * the same functionality as a function. * * Returns: %TRUE, if the thread system is initialized */ /** * g_thread_try_new: * @name: (allow-none): an (optional) name for the new thread * @func: a function to execute in the new thread * @data: an argument to supply to the new thread * @error: return location for error, or %NULL * * This function is the same as g_thread_new() except that * it allows for the possibility of failure. * * If a thread can not be created (due to resource limits), * @error is set and %NULL is returned. * * Returns: the new #GThread, or %NULL if an error occurred * Since: 2.32 */ /** * g_thread_unref: * @thread: a #GThread * * Decrease the reference count on @thread, possibly freeing all * resources associated with it. * * Note that each thread holds a reference to its #GThread while * it is running, so it is safe to drop your own reference to it * if you don't need it anymore. * * Since: 2.32 */ /** * g_thread_yield: * * Causes the calling thread to voluntarily relinquish the CPU, so * that other threads can run. * * This function is often used as a method to make busy wait less evil. */ /** * g_time_val_add: * @time_: a #GTimeVal * @microseconds: number of microseconds to add to @time * * Adds the given number of microseconds to @time_. @microseconds can * also be negative to decrease the value of @time_. */ /** * g_time_val_from_iso8601: * @iso_date: an ISO 8601 encoded date string * @time_: (out): a #GTimeVal * * Converts a string containing an ISO 8601 encoded date and time * to a #GTimeVal and puts it into @time_. * * @iso_date must include year, month, day, hours, minutes, and * seconds. It can optionally include fractions of a second and a time * zone indicator. (In the absence of any time zone indication, the * timestamp is assumed to be in local time.) * * Returns: %TRUE if the conversion was successful. * Since: 2.12 */ /** * g_time_val_to_iso8601: * @time_: a #GTimeVal * * Converts @time_ into an RFC 3339 encoded string, relative to the * Coordinated Universal Time (UTC). This is one of the many formats * allowed by ISO 8601. * * ISO 8601 allows a large number of date/time formats, with or without * punctuation and optional elements. The format returned by this function * is a complete date and time, with optional punctuation included, the * UTC time zone represented as "Z", and the @tv_usec part included if * and only if it is nonzero, i.e. either * "YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ". * * This corresponds to the Internet date/time format defined by * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt), * and to either of the two most-precise formats defined by * the W3C Note * [Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827). * Both of these documents are profiles of ISO 8601. * * Use g_date_time_format() or g_strdup_printf() if a different * variation of ISO 8601 format is required. * * Returns: a newly allocated string containing an ISO 8601 date * Since: 2.12 */ /** * g_time_zone_adjust_time: * @tz: a #GTimeZone * @type: the #GTimeType of @time_ * @time_: a pointer to a number of seconds since January 1, 1970 * * Finds an interval within @tz that corresponds to the given @time_, * possibly adjusting @time_ if required to fit into an interval. * The meaning of @time_ depends on @type. * * This function is similar to g_time_zone_find_interval(), with the * difference that it always succeeds (by making the adjustments * described below). * * In any of the cases where g_time_zone_find_interval() succeeds then * this function returns the same value, without modifying @time_. * * This function may, however, modify @time_ in order to deal with * non-existent times. If the non-existent local @time_ of 02:30 were * requested on March 14th 2010 in Toronto then this function would * adjust @time_ to be 03:00 and return the interval containing the * adjusted time. * * Returns: the interval containing @time_, never -1 * Since: 2.26 */ /** * g_time_zone_find_interval: * @tz: a #GTimeZone * @type: the #GTimeType of @time_ * @time_: a number of seconds since January 1, 1970 * * Finds an the interval within @tz that corresponds to the given @time_. * The meaning of @time_ depends on @type. * * If @type is %G_TIME_TYPE_UNIVERSAL then this function will always * succeed (since universal time is monotonic and continuous). * * Otherwise @time_ is treated as local time. The distinction between * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in * the case that the given @time_ is ambiguous. In Toronto, for example, * 01:30 on November 7th 2010 occurred twice (once inside of daylight * savings time and the next, an hour later, outside of daylight savings * time). In this case, the different value of @type would result in a * different interval being returned. * * It is still possible for this function to fail. In Toronto, for * example, 02:00 on March 14th 2010 does not exist (due to the leap * forward to begin daylight savings time). -1 is returned in that * case. * * Returns: the interval containing @time_, or -1 in case of failure * Since: 2.26 */ /** * g_time_zone_get_abbreviation: * @tz: a #GTimeZone * @interval: an interval within the timezone * * Determines the time zone abbreviation to be used during a particular * @interval of time in the time zone @tz. * * 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: the time zone abbreviation, which belongs to @tz * Since: 2.26 */ /** * g_time_zone_get_offset: * @tz: a #GTimeZone * @interval: an interval within the timezone * * Determines the offset to UTC in effect during a particular @interval * of time in the time zone @tz. * * The offset is the number of seconds that you add to UTC time to * arrive at local time for @tz (ie: negative numbers for time zones * west of GMT, positive numbers for east). * * Returns: the number of seconds that should be added to UTC to get the * local time in @tz * Since: 2.26 */ /** * g_time_zone_is_dst: * @tz: a #GTimeZone * @interval: an interval within the timezone * * Determines if daylight savings time is in effect during a particular * @interval of time in the time zone @tz. * * Returns: %TRUE if daylight savings time is in effect * Since: 2.26 */ /** * g_time_zone_new: * @identifier: (allow-none): a timezone identifier * * Creates a #GTimeZone corresponding to @identifier. * * @identifier can either be an RFC3339/ISO 8601 time offset or * something that would pass as a valid value for the `TZ` environment * variable (including %NULL). * * In Windows, @identifier can also be the unlocalized name of a time * zone for standard time, for example "Pacific Standard Time". * * Valid RFC3339 time offsets are `"Z"` (for UTC) or * `"±hh:mm"`. ISO 8601 additionally specifies * `"±hhmm"` and `"±hh"`. Offsets are * time values to be added to Coordinated Universal Time (UTC) to get * the local time. * * In UNIX, the `TZ` environment variable typically corresponds * to the name of a file in the zoneinfo database, or string in * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format. * There are no spaces in the specification. The name of standard * and daylight savings time zone must be three or more alphabetic * characters. Offsets are time values to be added to local time to * get Coordinated Universal Time (UTC) and should be * `"[±]hh[[:]mm[:ss]]"`. Dates are either * `"Jn"` (Julian day with n between 1 and 365, leap * years not counted), `"n"` (zero-based Julian day * with n between 0 and 365) or `"Mm.w.d"` (day d * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day * 0 is a Sunday). Times are in local wall clock time, the default is * 02:00:00. * * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also * accepts POSIX format. The Windows format uses US rules for all time * zones; daylight savings time is 60 minutes behind the standard time * with date and time of change taken from Pacific Standard Time. * Offsets are time values to be added to the local time to get * Coordinated Universal Time (UTC). * * g_time_zone_new_local() calls this function with the value of the * `TZ` environment variable. This function itself is independent of * the value of `TZ`, but if @identifier is %NULL then `/etc/localtime` * will be consulted to discover the correct time zone on UNIX and the * registry will be consulted or GetTimeZoneInformation() will be used * to get the local time zone on Windows. * * If intervals are not available, only time zone rules from `TZ` * environment variable or other means, then they will be computed * from year 1900 to 2037. If the maximum year for the rules is * available and it is greater than 2037, then it will followed * instead. * * See * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6) * for a precise definition of valid RFC3339 time offsets * (the `time-offset` expansion) and ISO 8601 for the * full list of valid time offsets. See * [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html) * for an explanation of the possible * values of the `TZ` environment variable. See * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) * for the list of time zones on Windows. * * You should release the return value by calling g_time_zone_unref() * when you are done with it. * * Returns: the requested timezone * Since: 2.26 */ /** * g_time_zone_new_local: * * Creates a #GTimeZone corresponding to local time. The local time * zone may change between invocations to this function; for example, * if the system administrator changes it. * * This is equivalent to calling g_time_zone_new() with the value of * the `TZ` environment variable (including the possibility of %NULL). * * You should release the return value by calling g_time_zone_unref() * when you are done with it. * * Returns: the local timezone * Since: 2.26 */ /** * g_time_zone_new_utc: * * Creates a #GTimeZone corresponding to UTC. * * This is equivalent to calling g_time_zone_new() with a value like * "Z", "UTC", "+00", etc. * * You should release the return value by calling g_time_zone_unref() * when you are done with it. * * Returns: the universal timezone * Since: 2.26 */ /** * g_time_zone_ref: * @tz: a #GTimeZone * * Increases the reference count on @tz. * * Returns: a new reference to @tz. * Since: 2.26 */ /** * g_time_zone_unref: * @tz: a #GTimeZone * * Decreases the reference count on @tz. * * Since: 2.26 */ /** * g_timeout_add: * @interval: the time between calls to the function, in milliseconds * (1/1000ths of a second) * @function: function to call * @data: data to pass to @function * * Sets a function to be called at regular intervals, with the default * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly * until it returns %FALSE, at which point the timeout is automatically * destroyed and the function will not be called again. The first call * to the function will be at the end of the first @interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. * After each call to the timeout function, the time of the next * timeout is recalculated based on the current time and the given interval * (it does not try to 'catch up' time lost in delays). * * If you want to have a timer in the "seconds" range and do not care * about the exact time of the first call of the timer, use the * g_timeout_add_seconds() function; this function allows for more * optimizations and more efficient system power usage. * * This internally creates a main loop source using g_timeout_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. * * The interval given is in terms of monotonic time, not wall clock * time. See g_get_monotonic_time(). * * Returns: the ID (greater than 0) of the event source. */ /** * g_timeout_add_full: (rename-to g_timeout_add) * @priority: the priority of the timeout source. Typically this will be in * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * @interval: the time between calls to the function, in milliseconds * (1/1000ths of a second) * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the timeout is removed, or %NULL * * Sets a function to be called at regular intervals, with the given * priority. The function is called repeatedly until it returns * %FALSE, at which point the timeout is automatically destroyed and * the function will not be called again. The @notify function is * called when the timeout is destroyed. The first call to the * function will be at the end of the first @interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. * After each call to the timeout function, the time of the next * timeout is recalculated based on the current time and the given interval * (it does not try to 'catch up' time lost in delays). * * This internally creates a main loop source using g_timeout_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. * * The interval given in terms of monotonic time, not wall clock time. * See g_get_monotonic_time(). * * Returns: the ID (greater than 0) of the event source. */ /** * g_timeout_add_seconds: * @interval: the time between calls to the function, in seconds * @function: function to call * @data: data to pass to @function * * Sets a function to be called at regular intervals with the default * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until * it returns %FALSE, at which point the timeout is automatically destroyed * and the function will not be called again. * * This internally creates a main loop source using * g_timeout_source_new_seconds() and attaches it to the main loop context * using g_source_attach(). You can do these steps manually if you need * greater control. Also see g_timeout_add_seconds_full(). * * Note that the first call of the timer may not be precise for timeouts * of one second. If you need finer precision and have such a timeout, * you may want to use g_timeout_add() instead. * * The interval given is in terms of monotonic time, not wall clock * time. See g_get_monotonic_time(). * * Returns: the ID (greater than 0) of the event source. * Since: 2.14 */ /** * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds) * @priority: the priority of the timeout source. Typically this will be in * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * @interval: the time between calls to the function, in seconds * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the timeout is removed, or %NULL * * Sets a function to be called at regular intervals, with @priority. * The function is called repeatedly until it returns %FALSE, at which * point the timeout is automatically destroyed and the function will * not be called again. * * Unlike g_timeout_add(), this function operates at whole second granularity. * The initial starting point of the timer is determined by the implementation * and the implementation is expected to group multiple timers together so that * they fire all at the same time. * To allow this grouping, the @interval to the first timer is rounded * and can deviate up to one second from the specified interval. * Subsequent timer iterations will generally run at the specified interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. * After each call to the timeout function, the time of the next * timeout is recalculated based on the current time and the given @interval * * If you want timing more precise than whole seconds, use g_timeout_add() * instead. * * The grouping of timers to fire at the same time results in a more power * and CPU efficient behavior so if your timer is in multiples of seconds * and you don't require the first timer exactly one second from now, the * use of g_timeout_add_seconds() is preferred over g_timeout_add(). * * This internally creates a main loop source using * g_timeout_source_new_seconds() and attaches it to the main loop context * using g_source_attach(). You can do these steps manually if you need * greater control. * * The interval given is in terms of monotonic time, not wall clock * time. See g_get_monotonic_time(). * * Returns: the ID (greater than 0) of the event source. * Since: 2.14 */ /** * g_timeout_source_new: * @interval: the timeout interval in milliseconds. * * Creates a new timeout 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. * * The interval given is in terms of monotonic time, not wall clock * time. See g_get_monotonic_time(). * * Returns: the newly-created timeout source */ /** * g_timeout_source_new_seconds: * @interval: the timeout interval in seconds * * Creates a new timeout 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. * * The scheduling granularity/accuracy of this timeout source will be * in seconds. * * The interval given in terms of monotonic time, not wall clock time. * See g_get_monotonic_time(). * * Returns: the newly-created timeout source * Since: 2.14 */ /** * g_timer_continue: * @timer: a #GTimer. * * Resumes a timer that has previously been stopped with * g_timer_stop(). g_timer_stop() must be called before using this * function. * * Since: 2.4 */ /** * g_timer_destroy: * @timer: a #GTimer to destroy. * * Destroys a timer, freeing associated resources. */ /** * g_timer_elapsed: * @timer: a #GTimer. * @microseconds: return location for the fractional part of seconds * elapsed, in microseconds (that is, the total number * of microseconds elapsed, modulo 1000000), or %NULL * * If @timer has been started but not stopped, obtains the time since * the timer was started. If @timer has been stopped, obtains the * elapsed time between the time it was started and the time it was * stopped. The return value is the number of seconds elapsed, * including any fractional part. The @microseconds out parameter is * essentially useless. * * Returns: seconds elapsed as a floating point value, including any * fractional part. */ /** * g_timer_new: * * Creates a new timer, and starts timing (i.e. g_timer_start() is * implicitly called for you). * * Returns: a new #GTimer. */ /** * g_timer_reset: * @timer: a #GTimer. * * This function is useless; it's fine to call g_timer_start() on an * already-started timer to reset the start time, so g_timer_reset() * serves no purpose. */ /** * g_timer_start: * @timer: a #GTimer. * * Marks a start time, so that future calls to g_timer_elapsed() will * report the time since g_timer_start() was called. g_timer_new() * automatically marks the start time, so no need to call * g_timer_start() immediately after creating the timer. */ /** * g_timer_stop: * @timer: a #GTimer. * * Marks an end time, so calls to g_timer_elapsed() will return the * difference between this end time and the start time. */ /** * g_trash_stack_height: * @stack_p: a #GTrashStack * * Returns the height of a #GTrashStack. * * Note that execution of this function is of O(N) complexity * where N denotes the number of items on the stack. * * Returns: the height of the stack */ /** * g_trash_stack_peek: * @stack_p: a #GTrashStack * * Returns the element at the top of a #GTrashStack * which may be %NULL. * * Returns: the element at the top of the stack */ /** * g_trash_stack_pop: * @stack_p: a #GTrashStack * * Pops a piece of memory off a #GTrashStack. * * Returns: the element at the top of the stack */ /** * g_trash_stack_push: * @stack_p: a #GTrashStack * @data_p: the piece of memory to push on the stack * * Pushes a piece of memory onto a #GTrashStack. */ /** * g_tree_destroy: * @tree: a #GTree * * Removes all keys and values from the #GTree and decreases its * reference count by one. If keys and/or values are dynamically * allocated, you should either free them first or create the #GTree * using g_tree_new_full(). In the latter case the destroy functions * you supplied will be called on all keys and values before destroying * the #GTree. */ /** * g_tree_foreach: * @tree: a #GTree * @func: the function to call for each node visited. * If this function returns %TRUE, the traversal is stopped. * @user_data: user data to pass to the function * * Calls the given function for each of the key/value pairs in the #GTree. * The function is passed the key and value of each pair, and the given * @data parameter. The tree is traversed in sorted order. * * The tree may not be modified while iterating over it (you can't * add/remove items). To remove all items matching a predicate, you need * to add each item to a list in your #GTraverseFunc as you walk over * the tree, then walk the list and remove each item. */ /** * g_tree_height: * @tree: a #GTree * * Gets the height of a #GTree. * * If the #GTree contains no nodes, the height is 0. * If the #GTree contains only one root node the height is 1. * If the root node has children the height is 2, etc. * * Returns: the height of @tree */ /** * g_tree_insert: * @tree: a #GTree * @key: the key to insert * @value: the value corresponding to the key * * Inserts a key/value pair into a #GTree. * * If the given key already exists in the #GTree its corresponding value * is set to the new value. If you supplied a @value_destroy_func when * creating the #GTree, the old value is freed using that function. If * you supplied a @key_destroy_func when creating the #GTree, the passed * key is freed using that function. * * The tree is automatically 'balanced' as new key/value pairs are added, * so that the distance from the root to every leaf is as small as possible. */ /** * g_tree_lookup: * @tree: a #GTree * @key: the key to look up * * Gets the value corresponding to the given key. Since a #GTree is * automatically balanced as key/value pairs are added, key lookup * is O(log n) (where n is the number of key/value pairs in the tree). * * Returns: the value corresponding to the key, or %NULL * if the key was not found */ /** * g_tree_lookup_extended: * @tree: a #GTree * @lookup_key: the key to look up * @orig_key: returns the original key * @value: returns the value associated with the key * * Looks up a key in the #GTree, returning the original key and the * associated value. This is useful if you need to free the memory * allocated for the original key, for example before calling * g_tree_remove(). * * Returns: %TRUE if the key was found in the #GTree */ /** * g_tree_new: * @key_compare_func: the function used to order the nodes in the #GTree. * It should return values similar to the standard strcmp() function - * 0 if the two arguments are equal, a negative value if the first argument * comes before the second, or a positive value if the first argument comes * after the second. * * Creates a new #GTree. * * Returns: a newly allocated #GTree */ /** * g_tree_new_full: * @key_compare_func: qsort()-style comparison function * @key_compare_data: data to pass to comparison function * @key_destroy_func: a function to free the memory allocated for the key * used when removing the entry from the #GTree or %NULL if you don't * want to supply such a function * @value_destroy_func: a function to free the memory allocated for the * value used when removing the entry from the #GTree or %NULL if you * don't want to supply such a function * * Creates a new #GTree like g_tree_new() and allows to specify functions * to free the memory allocated for the key and value that get called when * removing the entry from the #GTree. * * Returns: a newly allocated #GTree */ /** * g_tree_new_with_data: * @key_compare_func: qsort()-style comparison function * @key_compare_data: data to pass to comparison function * * Creates a new #GTree with a comparison function that accepts user data. * See g_tree_new() for more details. * * Returns: a newly allocated #GTree */ /** * g_tree_nnodes: * @tree: a #GTree * * Gets the number of nodes in a #GTree. * * Returns: the number of nodes in @tree */ /** * g_tree_ref: * @tree: a #GTree * * Increments the reference count of @tree by one. * * It is safe to call this function from any thread. * * Returns: the passed in #GTree * Since: 2.22 */ /** * g_tree_remove: * @tree: a #GTree * @key: the key to remove * * Removes a key/value pair from a #GTree. * * If the #GTree was created using g_tree_new_full(), the key and value * are freed using the supplied destroy functions, otherwise you have to * make sure that any dynamically allocated values are freed yourself. * If the key does not exist in the #GTree, the function does nothing. * * Returns: %TRUE if the key was found (prior to 2.8, this function * returned nothing) */ /** * g_tree_replace: * @tree: a #GTree * @key: the key to insert * @value: the value corresponding to the key * * Inserts a new key and value into a #GTree similar to g_tree_insert(). * The difference is that if the key already exists in the #GTree, it gets * replaced by the new key. If you supplied a @value_destroy_func when * creating the #GTree, the old value is freed using that function. If you * supplied a @key_destroy_func when creating the #GTree, the old key is * freed using that function. * * The tree is automatically 'balanced' as new key/value pairs are added, * so that the distance from the root to every leaf is as small as possible. */ /** * g_tree_search: * @tree: a #GTree * @search_func: a function used to search the #GTree * @user_data: the data passed as the second argument to @search_func * * Searches a #GTree using @search_func. * * The @search_func is called with a pointer to the key of a key/value * pair in the tree, and the passed in @user_data. If @search_func returns * 0 for a key/value pair, then the corresponding value is returned as * the result of g_tree_search(). If @search_func returns -1, searching * will proceed among the key/value pairs that have a smaller key; if * @search_func returns 1, searching will proceed among the key/value * pairs that have a larger key. * * Returns: the value corresponding to the found key, or %NULL * if the key was not found */ /** * g_tree_steal: * @tree: a #GTree * @key: the key to remove * * Removes a key and its associated value from a #GTree without calling * the key and value destroy functions. * * If the key does not exist in the #GTree, the function does nothing. * * Returns: %TRUE if the key was found (prior to 2.8, this function * returned nothing) */ /** * g_tree_traverse: * @tree: a #GTree * @traverse_func: the function to call for each node visited. If this * function returns %TRUE, the traversal is stopped. * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, * %G_PRE_ORDER and %G_POST_ORDER * @user_data: user data to pass to the function * * Calls the given function for each node in the #GTree. * * Deprecated: 2.2: The order of a balanced tree is somewhat arbitrary. * If you just want to visit all nodes in sorted order, use * g_tree_foreach() instead. If you really need to visit nodes in * a different order, consider using an [n-ary tree][glib-N-ary-Trees]. */ /** * g_tree_unref: * @tree: a #GTree * * Decrements the reference count of @tree by one. * If the reference count drops to 0, all keys and values will * be destroyed (if destroy functions were specified) and all * memory allocated by @tree will be released. * * It is safe to call this function from any thread. * * Since: 2.22 */ /** * g_try_malloc: * @n_bytes: number of bytes to allocate. * * Attempts to allocate @n_bytes, and returns %NULL on failure. * Contrast with g_malloc(), which aborts the program on failure. * * Returns: the allocated memory, or %NULL. */ /** * g_try_malloc0: * @n_bytes: number of bytes to allocate * * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on * failure. Contrast with g_malloc0(), which aborts the program on failure. * * Since: 2.8 * Returns: the allocated memory, or %NULL */ /** * g_try_malloc0_n: * @n_blocks: the number of blocks to allocate * @n_block_bytes: the size of each block in bytes * * This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, * but care is taken to detect possible overflow during multiplication. * * Since: 2.24 * Returns: the allocated memory, or %NULL */ /** * g_try_malloc_n: * @n_blocks: the number of blocks to allocate * @n_block_bytes: the size of each block in bytes * * This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, * but care is taken to detect possible overflow during multiplication. * * Since: 2.24 * Returns: the allocated memory, or %NULL. */ /** * g_try_realloc: * @mem: (allow-none): previously-allocated memory, or %NULL. * @n_bytes: number of bytes to allocate. * * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL * on failure. Contrast with g_realloc(), which aborts the program * on failure. If @mem is %NULL, behaves the same as g_try_malloc(). * * Returns: the allocated memory, or %NULL. */ /** * g_try_realloc_n: * @mem: (allow-none): previously-allocated memory, or %NULL. * @n_blocks: the number of blocks to allocate * @n_block_bytes: the size of each block in bytes * * This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, * but care is taken to detect possible overflow during multiplication. * * Since: 2.24 * Returns: the allocated memory, or %NULL. */ /** * g_ucs4_to_utf16: * @str: a UCS-4 encoded string * @len: the maximum length (number of characters) of @str to use. * If @len < 0, then the string is nul-terminated. * @items_read: (allow-none): location to store number of bytes read, * or %NULL. If an error occurs then the index of the invalid input * is stored here. * @items_written: (allow-none): location to store number of #gunichar2 * written, or %NULL. The value stored here does not include the * trailing 0. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError other than * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UCS-4 to UTF-16. A 0 character will be * added to the result after the converted text. * * Returns: a pointer to a newly allocated UTF-16 string. * This value must be freed with g_free(). If an error occurs, * %NULL will be returned and @error set. */ /** * g_ucs4_to_utf8: * @str: a UCS-4 encoded string * @len: the maximum length (number of characters) of @str to use. * If @len < 0, then the string is nul-terminated. * @items_read: (allow-none): location to store number of characters * read, or %NULL. * @items_written: (allow-none): location to store number of bytes * written or %NULL. The value here stored does not include the * trailing 0 byte. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError other than * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from a 32-bit fixed width representation as UCS-4. * to UTF-8. The result will be terminated with a 0 byte. * * Returns: a pointer to a newly allocated UTF-8 string. * This value must be freed with g_free(). If an error occurs, * %NULL will be returned and @error set. In that case, @items_read * will be set to the position of the first invalid input character. */ /** * g_unichar_break_type: * @c: a Unicode character * * Determines the break type of @c. @c should be a Unicode character * (to derive a character from UTF-8 encoded text, use * g_utf8_get_char()). The break type is used to find word and line * breaks ("text boundaries"), Pango implements the Unicode boundary * resolution algorithms and normally you would use a function such * as pango_break() instead of caring about break types yourself. * * Returns: the break type of @c */ /** * g_unichar_combining_class: * @uc: a Unicode character * * Determines the canonical combining class of a Unicode character. * * Returns: the combining class of the character * Since: 2.14 */ /** * g_unichar_compose: * @a: a Unicode character * @b: a Unicode character * @ch: return location for the composed character * * Performs a single composition step of the * Unicode canonical composition algorithm. * * This function includes algorithmic Hangul Jamo composition, * but it is not exactly the inverse of g_unichar_decompose(). * No composition can have either of @a or @b equal to zero. * To be precise, this function composes if and only if * there exists a Primary Composite P which is canonically * equivalent to the sequence <@a,@b>. See the Unicode * Standard for the definition of Primary Composite. * * If @a and @b do not compose a new character, @ch is set to zero. * * See * [UAX#15](http://unicode.org/reports/tr15/) * for details. * * Returns: %TRUE if the characters could be composed * Since: 2.30 */ /** * g_unichar_decompose: * @ch: a Unicode character * @a: return location for the first component of @ch * @b: return location for the second component of @ch * * Performs a single decomposition step of the * Unicode canonical decomposition algorithm. * * This function does not include compatibility * decompositions. It does, however, include algorithmic * Hangul Jamo decomposition, as well as 'singleton' * decompositions which replace a character by a single * other character. In the case of singletons *@b will * be set to zero. * * If @ch is not decomposable, *@a is set to @ch and *@b * is set to zero. * * Note that the way Unicode decomposition pairs are * defined, it is guaranteed that @b would not decompose * further, but @a may itself decompose. To get the full * canonical decomposition for @ch, one would need to * recursively call this function on @a. Or use * g_unichar_fully_decompose(). * * See * [UAX#15](http://unicode.org/reports/tr15/) * for details. * * Returns: %TRUE if the character could be decomposed * Since: 2.30 */ /** * g_unichar_digit_value: * @c: a Unicode character * * Determines the numeric value of a character as a decimal * digit. * * Returns: If @c is a decimal digit (according to * g_unichar_isdigit()), its numeric value. Otherwise, -1. */ /** * g_unichar_fully_decompose: * @ch: a Unicode character. * @compat: whether perform canonical or compatibility decomposition * @result: (allow-none): location to store decomposed result, or %NULL * @result_len: length of @result * * Computes the canonical or compatibility decomposition of a * Unicode character. For compatibility decomposition, * pass %TRUE for @compat; for canonical decomposition * pass %FALSE for @compat. * * The decomposed sequence is placed in @result. Only up to * @result_len characters are written into @result. The length * of the full decomposition (irrespective of @result_len) is * returned by the function. For canonical decomposition, * currently all decompositions are of length at most 4, but * this may change in the future (very unlikely though). * At any rate, Unicode does guarantee that a buffer of length * 18 is always enough for both compatibility and canonical * decompositions, so that is the size recommended. This is provided * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH. * * See * [UAX#15](http://unicode.org/reports/tr15/) * for details. * * Returns: the length of the full decomposition. * Since: 2.30 */ /** * g_unichar_get_mirror_char: * @ch: a Unicode character * @mirrored_ch: location to store the mirrored character * * In Unicode, some characters are "mirrored". This means that their * images are mirrored horizontally in text that is laid out from right * to left. For instance, "(" would become its mirror image, ")", in * right-to-left text. * * If @ch has the Unicode mirrored property and there is another unicode * character that typically has a glyph that is the mirror image of @ch's * glyph and @mirrored_ch is set, it puts that character in the address * pointed to by @mirrored_ch. Otherwise the original character is put. * * Returns: %TRUE if @ch has a mirrored character, %FALSE otherwise * Since: 2.4 */ /** * g_unichar_get_script: * @ch: a Unicode character * * Looks up the #GUnicodeScript for a particular character (as defined * by Unicode Standard Annex \#24). No check is made for @ch being a * valid Unicode character; if you pass in invalid character, the * result is undefined. * * This function is equivalent to pango_script_for_unichar() and the * two are interchangeable. * * Returns: the #GUnicodeScript for the character. * Since: 2.14 */ /** * g_unichar_isalnum: * @c: a Unicode character * * Determines whether a character is alphanumeric. * Given some UTF-8 text, obtain a character value * with g_utf8_get_char(). * * Returns: %TRUE if @c is an alphanumeric character */ /** * g_unichar_isalpha: * @c: a Unicode character * * Determines whether a character is alphabetic (i.e. a letter). * Given some UTF-8 text, obtain a character value with * g_utf8_get_char(). * * Returns: %TRUE if @c is an alphabetic character */ /** * g_unichar_iscntrl: * @c: a Unicode character * * Determines whether a character is a control character. * Given some UTF-8 text, obtain a character value with * g_utf8_get_char(). * * Returns: %TRUE if @c is a control character */ /** * g_unichar_isdefined: * @c: a Unicode character * * Determines if a given character is assigned in the Unicode * standard. * * Returns: %TRUE if the character has an assigned value */ /** * g_unichar_isdigit: * @c: a Unicode character * * Determines whether a character is numeric (i.e. a digit). This * covers ASCII 0-9 and also digits in other languages/scripts. Given * some UTF-8 text, obtain a character value with g_utf8_get_char(). * * Returns: %TRUE if @c is a digit */ /** * g_unichar_isgraph: * @c: a Unicode character * * Determines whether a character is printable and not a space * (returns %FALSE for control characters, format characters, and * spaces). g_unichar_isprint() is similar, but returns %TRUE for * spaces. Given some UTF-8 text, obtain a character value with * g_utf8_get_char(). * * Returns: %TRUE if @c is printable unless it's a space */ /** * g_unichar_islower: * @c: a Unicode character * * Determines whether a character is a lowercase letter. * Given some UTF-8 text, obtain a character value with * g_utf8_get_char(). * * Returns: %TRUE if @c is a lowercase letter */ /** * g_unichar_ismark: * @c: a Unicode character * * Determines whether a character is a mark (non-spacing mark, * combining mark, or enclosing mark in Unicode speak). * Given some UTF-8 text, obtain a character value * with g_utf8_get_char(). * * Note: in most cases where isalpha characters are allowed, * ismark characters should be allowed to as they are essential * for writing most European languages as well as many non-Latin * scripts. * * Returns: %TRUE if @c is a mark character * Since: 2.14 */ /** * g_unichar_isprint: * @c: a Unicode character * * Determines whether a character is printable. * Unlike g_unichar_isgraph(), returns %TRUE for spaces. * Given some UTF-8 text, obtain a character value with * g_utf8_get_char(). * * Returns: %TRUE if @c is printable */ /** * g_unichar_ispunct: * @c: a Unicode character * * Determines whether a character is punctuation or a symbol. * Given some UTF-8 text, obtain a character value with * g_utf8_get_char(). * * Returns: %TRUE if @c is a punctuation or symbol character */ /** * g_unichar_isspace: * @c: a Unicode character * * Determines whether a character is a space, tab, or line separator * (newline, carriage return, etc.). Given some UTF-8 text, obtain a * character value with g_utf8_get_char(). * * (Note: don't use this to do word breaking; you have to use * Pango or equivalent to get word breaking right, the algorithm * is fairly complex.) * * Returns: %TRUE if @c is a space character */ /** * g_unichar_istitle: * @c: a Unicode character * * Determines if a character is titlecase. Some characters in * Unicode which are composites, such as the DZ digraph * have three case variants instead of just two. The titlecase * form is used at the beginning of a word where only the * first letter is capitalized. The titlecase form of the DZ * digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z. * * Returns: %TRUE if the character is titlecase */ /** * g_unichar_isupper: * @c: a Unicode character * * Determines if a character is uppercase. * * Returns: %TRUE if @c is an uppercase character */ /** * g_unichar_iswide: * @c: a Unicode character * * Determines if a character is typically rendered in a double-width * cell. * * Returns: %TRUE if the character is wide */ /** * g_unichar_iswide_cjk: * @c: a Unicode character * * Determines if a character is typically rendered in a double-width * cell under legacy East Asian locales. If a character is wide according to * g_unichar_iswide(), then it is also reported wide with this function, but * the converse is not necessarily true. See the * [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/) * for details. * * If a character passes the g_unichar_iswide() test then it will also pass * this test, but not the other way around. Note that some characters may * pass both this test and g_unichar_iszerowidth(). * * Returns: %TRUE if the character is wide in legacy East Asian locales * Since: 2.12 */ /** * g_unichar_isxdigit: * @c: a Unicode character. * * Determines if a character is a hexidecimal digit. * * Returns: %TRUE if the character is a hexadecimal digit */ /** * g_unichar_iszerowidth: * @c: a Unicode character * * Determines if a given character typically takes zero width when rendered. * The return value is %TRUE for all non-spacing and enclosing marks * (e.g., combining accents), format characters, zero-width * space, but not U+00AD SOFT HYPHEN. * * A typical use of this function is with one of g_unichar_iswide() or * g_unichar_iswide_cjk() to determine the number of cells a string occupies * when displayed on a grid display (terminals). However, note that not all * terminals support zero-width rendering of zero-width marks. * * Returns: %TRUE if the character has zero width * Since: 2.14 */ /** * g_unichar_to_utf8: * @c: a Unicode character code * @outbuf: output buffer, must have at least 6 bytes of space. * If %NULL, the length will be computed and returned * and nothing will be written to @outbuf. * * Converts a single character to UTF-8. * * Returns: number of bytes written */ /** * g_unichar_tolower: * @c: a Unicode character. * * Converts a character to lower case. * * Returns: the result of converting @c to lower case. * If @c is not an upperlower or titlecase character, * or has no lowercase equivalent @c is returned unchanged. */ /** * g_unichar_totitle: * @c: a Unicode character * * Converts a character to the titlecase. * * Returns: the result of converting @c to titlecase. * If @c is not an uppercase or lowercase character, * @c is returned unchanged. */ /** * g_unichar_toupper: * @c: a Unicode character * * Converts a character to uppercase. * * Returns: the result of converting @c to uppercase. * If @c is not an lowercase or titlecase character, * or has no upper case equivalent @c is returned unchanged. */ /** * g_unichar_type: * @c: a Unicode character * * Classifies a Unicode character by type. * * Returns: the type of the character. */ /** * g_unichar_validate: * @ch: a Unicode character * * Checks whether @ch is a valid Unicode character. Some possible * integer values of @ch will not be valid. 0 is considered a valid * character, though it's normally a string terminator. * * Returns: %TRUE if @ch is a valid Unicode character */ /** * g_unichar_xdigit_value: * @c: a Unicode character * * Determines the numeric value of a character as a hexidecimal * digit. * * Returns: If @c is a hex digit (according to * g_unichar_isxdigit()), its numeric value. Otherwise, -1. */ /** * g_unicode_canonical_decomposition: * @ch: a Unicode character. * @result_len: location to store the length of the return value. * * Computes the canonical decomposition of a Unicode character. * * Returns: a newly allocated string of Unicode characters. * @result_len is set to the resulting length of the string. * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose() * instead. */ /** * g_unicode_canonical_ordering: * @string: a UCS-4 encoded string. * @len: the maximum length of @string to use. * * Computes the canonical ordering of a string in-place. * This rearranges decomposed characters in the string * according to their combining classes. See the Unicode * manual for more information. */ /** * g_unicode_script_from_iso15924: * @iso15924: a Unicode script * * Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter * codes to scripts. For example, the code for Arabic is 'Arab'. * This function accepts four letter codes encoded as a @guint32 in a * big-endian fashion. That is, the code expected for Arabic is * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). * * See * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) * for details. * * Returns: the Unicode script for @iso15924, or * of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and * %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. * Since: 2.30 */ /** * g_unicode_script_to_iso15924: * @script: a Unicode script * * Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter * codes to scripts. For example, the code for Arabic is 'Arab'. The * four letter codes are encoded as a @guint32 by this function in a * big-endian fashion. That is, the code returned for Arabic is * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). * * See * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) * for details. * * Returns: the ISO 15924 code for @script, encoded as an integer, * of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or * ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. * Since: 2.30 */ /** * g_unix_fd_add: * @fd: a file descriptor * @condition: IO conditions to watch for on @fd * @function: a #GPollFDFunc * @user_data: data to pass to @function * * Sets a function to be called when the IO condition, as specified by * @condition becomes true for @fd. * * @function will be called when the specified IO condition becomes * %TRUE. The function is expected to clear whatever event caused the * IO condition to become true and return %TRUE in order to be notified * when it happens again. If @function returns %FALSE then the watch * will be cancelled. * * The return value of this function can be passed to g_source_remove() * to cancel the watch at any time that it exists. * * The source will never close the fd -- you must do it yourself. * * Returns: the ID (greater than 0) of the event source * Since: 2.36 */ /** * g_unix_fd_add_full: * @priority: the priority of the source * @fd: a file descriptor * @condition: IO conditions to watch for on @fd * @function: a #GUnixFDSourceFunc * @user_data: data to pass to @function * @notify: function to call when the idle is removed, or %NULL * * Sets a function to be called when the IO condition, as specified by * @condition becomes true for @fd. * * This is the same as g_unix_fd_add(), except that it allows you to * specify a non-default priority and a provide a #GDestroyNotify for * @user_data. * * Returns: the ID (greater than 0) of the event source * Since: 2.36 */ /** * g_unix_fd_source_new: * @fd: a file descriptor * @condition: IO conditions to watch for on @fd * * Creates a #GSource to watch for a particular IO condition on a file * descriptor. * * The source will never close the fd -- you must do it yourself. * * Returns: the newly created #GSource * Since: 2.36 */ /** * g_unix_open_pipe: * @fds: Array of two integers * @flags: Bitfield of file descriptor flags, as for fcntl() * @error: a #GError * * Similar to the UNIX pipe() call, but on modern systems like Linux * uses the pipe2() system call, which atomically creates a pipe with * the configured flags. The only supported flag currently is * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that * must still be done separately with fcntl(). * * This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if * for fcntl(); these are different on Linux/glibc. * * Returns: %TRUE on success, %FALSE if not (and errno will be set). * Since: 2.30 */ /** * g_unix_set_fd_nonblocking: * @fd: A file descriptor * @nonblock: If %TRUE, set the descriptor to be non-blocking * @error: a #GError * * Control the non-blocking state of the given file descriptor, * according to @nonblock. On most systems this uses %O_NONBLOCK, but * on some older ones may use %O_NDELAY. * * Returns: %TRUE if successful * Since: 2.30 */ /** * g_unix_signal_add: * @signum: Signal number * @handler: Callback * @user_data: Data for @handler * * A convenience function for g_unix_signal_source_new(), which * attaches to the default #GMainContext. You can remove the watch * using g_source_remove(). * * Returns: An ID (greater than 0) for the event source * Since: 2.30 */ /** * g_unix_signal_add_full: (rename-to g_unix_signal_add) * @priority: the priority of the signal source. Typically this will be in * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * @signum: Signal number * @handler: Callback * @user_data: Data for @handler * @notify: #GDestroyNotify for @handler * * A convenience function for g_unix_signal_source_new(), which * attaches to the default #GMainContext. You can remove the watch * using g_source_remove(). * * Returns: An ID (greater than 0) for the event source * Since: 2.30 */ /** * g_unix_signal_source_new: * @signum: A signal number * * Create a #GSource that will be dispatched upon delivery of the UNIX * signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`, * `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2` * were added. * * Note that unlike the UNIX default, all sources which have created a * watch will be dispatched, regardless of which underlying thread * invoked g_unix_signal_source_new(). * * For example, an effective use of this function is to handle `SIGTERM` * cleanly; flushing any outstanding files, and then calling * g_main_loop_quit (). It is not safe to do any of this a regular * UNIX signal handler; your handler may be invoked while malloc() or * another library function is running, causing reentrancy if you * attempt to use it from the handler. None of the GLib/GObject API * is safe against this kind of reentrancy. * * The interaction of this source when combined with native UNIX * functions like sigprocmask() is not defined. * * 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. * * Returns: A newly created #GSource * Since: 2.30 */ /** * g_unlink: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * * A wrapper for the POSIX unlink() function. The unlink() function * deletes a name from the filesystem. If this was the last link to the * file and no processes have it opened, the diskspace occupied by the * file is freed. * * See your C library manual for more details about unlink(). Note * that on Windows, it is in general not possible to delete files that * are open to some process, or mapped into memory. * * Returns: 0 if the name was successfully deleted, -1 if an error * occurred * Since: 2.6 */ /** * g_unsetenv: * @variable: the environment variable to remove, must not contain '=' * * Removes an environment variable from the environment. * * Note that on some systems, when variables are overwritten, the * memory used for the previous variables and its value isn't reclaimed. * * You should be mindful of the fact that environment variable handling * in UNIX is not thread-safe, and your program may crash if one thread * calls g_unsetenv() while another thread is calling getenv(). (And note * that many functions, such as gettext(), call getenv() internally.) This * function is only safe to use at the very start of your program, before * creating any other threads (or creating objects that create worker * threads of their own). * * If you need to set up the environment for a child process, you can * use g_get_environ() to get an environment array, modify that with * g_environ_setenv() and g_environ_unsetenv(), and then pass that * array directly to execvpe(), g_spawn_async(), or the like. * * Since: 2.4 */ /** * g_uri_escape_string: * @unescaped: the unescaped input string. * @reserved_chars_allowed: (allow-none): a string of reserved characters that * are allowed to be used, or %NULL. * @allow_utf8: %TRUE if the result can include UTF-8 characters. * * Escapes a string for use in a URI. * * Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical * characters plus dash, dot, underscore and tilde) are escaped. * But if you specify characters in @reserved_chars_allowed they are not * escaped. This is useful for the "reserved" characters in the URI * specification, since those are allowed unescaped in some portions of * a URI. * * Returns: an escaped version of @unescaped. The returned string should be * freed when no longer needed. * Since: 2.16 */ /** * g_uri_list_extract_uris: * @uri_list: an URI list * * Splits an URI list conforming to the text/uri-list * mime type defined in RFC 2483 into individual URIs, * discarding any comments. The URIs are not validated. * * Returns: (transfer full): a newly allocated %NULL-terminated list * of strings holding the individual URIs. The array should be freed * with g_strfreev(). * Since: 2.6 */ /** * g_uri_parse_scheme: * @uri: a valid URI. * * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] * ]| * Common schemes include "file", "http", "svn+ssh", etc. * * Returns: The "Scheme" component of the URI, or %NULL on error. * The returned string should be freed when no longer needed. * Since: 2.16 */ /** * g_uri_unescape_segment: * @escaped_string: (allow-none): A string, may be %NULL * @escaped_string_end: (allow-none): Pointer to end of @escaped_string, may be %NULL * @illegal_characters: (allow-none): An optional string of illegal characters not to be allowed, may be %NULL * * Unescapes a segment of an escaped string. * * If any of the characters in @illegal_characters or the character zero appears * as an escaped character in @escaped_string then that is an error and %NULL * will be returned. This is useful it you want to avoid for instance having a * slash being expanded in an escaped path element, which might confuse pathname * handling. * * Returns: an unescaped version of @escaped_string or %NULL on error. * The returned string should be freed when no longer needed. As a * special case if %NULL is given for @escaped_string, this function * will return %NULL. * Since: 2.16 */ /** * g_uri_unescape_string: * @escaped_string: an escaped string to be unescaped. * @illegal_characters: (allow-none): a string of illegal characters not to be * allowed, or %NULL. * * Unescapes a whole escaped string. * * If any of the characters in @illegal_characters or the character zero appears * as an escaped character in @escaped_string then that is an error and %NULL * will be returned. This is useful it you want to avoid for instance having a * slash being expanded in an escaped path element, which might confuse pathname * handling. * * Returns: an unescaped version of @escaped_string. The returned string * should be freed when no longer needed. * Since: 2.16 */ /** * g_usleep: * @microseconds: number of microseconds to pause * * Pauses the current thread for the given number of microseconds. * * There are 1 million microseconds per second (represented by the * #G_USEC_PER_SEC macro). g_usleep() may have limited precision, * depending on hardware and operating system; don't rely on the exact * length of the sleep. */ /** * g_utf16_to_ucs4: * @str: a UTF-16 encoded string * @len: the maximum length (number of #gunichar2) of @str to use. * If @len < 0, then the string is nul-terminated. * @items_read: (allow-none): location to store number of words read, * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be * returned in case @str contains a trailing partial character. If * an error occurs then the index of the invalid input is stored here. * @items_written: (allow-none): location to store number of characters * written, or %NULL. The value stored here does not include the trailing * 0 character. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError other than * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-16 to UCS-4. The result will be * nul-terminated. * * Returns: a pointer to a newly allocated UCS-4 string. * This value must be freed with g_free(). If an error occurs, * %NULL will be returned and @error set. */ /** * g_utf16_to_utf8: * @str: a UTF-16 encoded string * @len: the maximum length (number of #gunichar2) of @str to use. * If @len < 0, then the string is nul-terminated. * @items_read: (allow-none): location to store number of words read, * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be * returned in case @str contains a trailing partial character. If * an error occurs then the index of the invalid input is stored here. * @items_written: (allow-none): location to store number of bytes written, * or %NULL. The value stored here does not include the trailing 0 byte. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError other than * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-16 to UTF-8. The result will be * terminated with a 0 byte. * * Note that the input is expected to be already in native endianness, * an initial byte-order-mark character is not handled specially. * g_convert() can be used to convert a byte buffer of UTF-16 data of * ambiguous endianess. * * Further note that this function does not validate the result * string; it may e.g. include embedded NUL characters. The only * validation done by this function is to ensure that the input can * be correctly interpreted as UTF-16, i.e. it doesn't contain * things unpaired surrogates. * * Returns: a pointer to a newly allocated UTF-8 string. * This value must be freed with g_free(). If an error occurs, * %NULL will be returned and @error set. */ /** * g_utf8_casefold: * @str: a UTF-8 encoded string * @len: length of @str, in bytes, or -1 if @str is nul-terminated. * * Converts a string into a form that is independent of case. The * result will not correspond to any particular case, but can be * compared for equality or ordered with the results of calling * g_utf8_casefold() on other strings. * * Note that calling g_utf8_casefold() followed by g_utf8_collate() is * only an approximation to the correct linguistic case insensitive * ordering, though it is a fairly good one. Getting this exactly * right would require a more sophisticated collation function that * takes case sensitivity into account. GLib does not currently * provide such a function. * * Returns: a newly allocated string, that is a * case independent form of @str. */ /** * g_utf8_collate: * @str1: a UTF-8 encoded string * @str2: a UTF-8 encoded string * * Compares two strings for ordering using the linguistically * correct rules for the [current locale][setlocale]. * When sorting a large number of strings, it will be significantly * faster to obtain collation keys with g_utf8_collate_key() and * compare the keys with strcmp() when sorting instead of sorting * the original strings. * * Returns: < 0 if @str1 compares before @str2, * 0 if they compare equal, > 0 if @str1 compares after @str2. */ /** * g_utf8_collate_key: * @str: a UTF-8 encoded string. * @len: length of @str, in bytes, or -1 if @str is nul-terminated. * * Converts a string into a collation key that can be compared * with other collation keys produced by the same function using * strcmp(). * * The results of comparing the collation keys of two strings * with strcmp() will always be the same as comparing the two * original keys with g_utf8_collate(). * * Note that this function depends on the [current locale][setlocale]. * * Returns: a newly allocated string. This string should * be freed with g_free() when you are done with it. */ /** * g_utf8_collate_key_for_filename: * @str: a UTF-8 encoded string. * @len: length of @str, in bytes, or -1 if @str is nul-terminated. * * Converts a string into a collation key that can be compared * with other collation keys produced by the same function using strcmp(). * * In order to sort filenames correctly, this function treats the dot '.' * as a special case. Most dictionary orderings seem to consider it * insignificant, thus producing the ordering "event.c" "eventgenerator.c" * "event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we * would like to treat numbers intelligently so that "file1" "file10" "file5" * is sorted as "file1" "file5" "file10". * * Note that this function depends on the [current locale][setlocale]. * * Returns: a newly allocated string. This string should * be freed with g_free() when you are done with it. * Since: 2.8 */ /** * g_utf8_find_next_char: * @p: a pointer to a position within a UTF-8 encoded string * @end: a pointer to the byte following the end of the string, * or %NULL to indicate that the string is nul-terminated * * Finds the start of the next UTF-8 character in the string after @p. * * @p does not have to be at the beginning of a UTF-8 character. No check * is made to see if the character found is actually valid other than * it starts with an appropriate byte. * * Returns: a pointer to the found character or %NULL */ /** * g_utf8_find_prev_char: * @str: pointer to the beginning of a UTF-8 encoded string * @p: pointer to some position within @str * * Given a position @p with a UTF-8 encoded string @str, find the start * of the previous UTF-8 character starting before @p. Returns %NULL if no * UTF-8 characters are present in @str before @p. * * @p does not have to be at the beginning of a UTF-8 character. No check * is made to see if the character found is actually valid other than * it starts with an appropriate byte. * * Returns: a pointer to the found character or %NULL. */ /** * g_utf8_get_char: * @p: a pointer to Unicode character encoded as UTF-8 * * Converts a sequence of bytes encoded as UTF-8 to a Unicode character. * * If @p does not point to a valid UTF-8 encoded character, results * are undefined. If you are not sure that the bytes are complete * valid Unicode characters, you should use g_utf8_get_char_validated() * instead. * * Returns: the resulting character */ /** * g_utf8_get_char_validated: * @p: a pointer to Unicode character encoded as UTF-8 * @max_len: the maximum number of bytes to read, or -1, for no maximum or * if @p is nul-terminated * * Convert a sequence of bytes encoded as UTF-8 to a Unicode character. * This function checks for incomplete characters, for invalid characters * such as characters that are out of the range of Unicode, and for * overlong encodings of valid characters. * * Returns: the resulting character. If @p points to a partial * sequence at the end of a string that could begin a valid * character (or if @max_len is zero), returns (gunichar)-2; * otherwise, if @p does not point to a valid UTF-8 encoded * Unicode character, returns (gunichar)-1. */ /** * g_utf8_normalize: * @str: a UTF-8 encoded string. * @len: length of @str, in bytes, or -1 if @str is nul-terminated. * @mode: the type of normalization to perform. * * Converts a string into canonical form, standardizing * such issues as whether a character with an accent * is represented as a base character and combining * accent or as a single precomposed character. The * string has to be valid UTF-8, otherwise %NULL is * returned. You should generally call g_utf8_normalize() * before comparing two Unicode strings. * * The normalization mode %G_NORMALIZE_DEFAULT only * standardizes differences that do not affect the * text content, such as the above-mentioned accent * representation. %G_NORMALIZE_ALL also standardizes * the "compatibility" characters in Unicode, such * as SUPERSCRIPT THREE to the standard forms * (in this case DIGIT THREE). Formatting information * may be lost but for most text operations such * characters should be considered the same. * * %G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE * are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL, * but returned a result with composed forms rather * than a maximally decomposed form. This is often * useful if you intend to convert the string to * a legacy encoding or pass it to a system with * less capable Unicode handling. * * Returns: a newly allocated string, that is the * normalized form of @str, or %NULL if @str is not * valid UTF-8. */ /** * g_utf8_offset_to_pointer: * @str: a UTF-8 encoded string * @offset: a character offset within @str * * Converts from an integer character offset to a pointer to a position * within the string. * * Since 2.10, this function allows to pass a negative @offset to * step backwards. It is usually worth stepping backwards from the end * instead of forwards if @offset is in the last fourth of the string, * since moving forward is about 3 times faster than moving backward. * * Note that this function doesn't abort when reaching the end of @str. * Therefore you should be sure that @offset is within string boundaries * before calling that function. Call g_utf8_strlen() when unsure. * This limitation exists as this function is called frequently during * text rendering and therefore has to be as fast as possible. * * Returns: the resulting pointer */ /** * g_utf8_pointer_to_offset: * @str: a UTF-8 encoded string * @pos: a pointer to a position within @str * * Converts from a pointer to position within a string to a integer * character offset. * * Since 2.10, this function allows @pos to be before @str, and returns * a negative offset in this case. * * Returns: the resulting character offset */ /** * g_utf8_prev_char: * @p: a pointer to a position within a UTF-8 encoded string * * Finds the previous UTF-8 character in the string before @p. * * @p does not have to be at the beginning of a UTF-8 character. No check * is made to see if the character found is actually valid other than * it starts with an appropriate byte. If @p might be the first * character of the string, you must use g_utf8_find_prev_char() instead. * * Returns: a pointer to the found character */ /** * g_utf8_strchr: * @p: a nul-terminated UTF-8 encoded string * @len: the maximum length of @p * @c: a Unicode character * * Finds the leftmost occurrence of the given Unicode character * in a UTF-8 encoded string, while limiting the search to @len bytes. * If @len is -1, allow unbounded search. * * Returns: %NULL if the string does not contain the character, * otherwise, a pointer to the start of the leftmost occurrence * of the character in the string. */ /** * g_utf8_strdown: * @str: a UTF-8 encoded string * @len: length of @str, in bytes, or -1 if @str is nul-terminated. * * Converts all Unicode characters in the string that have a case * to lowercase. The exact manner that this is done depends * on the current locale, and may result in the number of * characters in the string changing. * * Returns: a newly allocated string, with all characters * converted to lowercase. */ /** * g_utf8_strlen: * @p: pointer to the start of a UTF-8 encoded string * @max: the maximum number of bytes to examine. If @max * is less than 0, then the string is assumed to be * nul-terminated. If @max is 0, @p will not be examined and * may be %NULL. If @max is greater than 0, up to @max * bytes are examined * * Computes the length of the string in characters, not including * the terminating nul character. If the @max'th byte falls in the * middle of a character, the last (partial) character is not counted. * * Returns: the length of the string in characters */ /** * g_utf8_strncpy: * @dest: buffer to fill with characters from @src * @src: UTF-8 encoded string * @n: character count * * Like the standard C strncpy() function, but copies a given number * of characters instead of a given number of bytes. The @src string * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all * text before trying to use UTF-8 utility functions with it.) * * Returns: @dest */ /** * g_utf8_strrchr: * @p: a nul-terminated UTF-8 encoded string * @len: the maximum length of @p * @c: a Unicode character * * Find the rightmost occurrence of the given Unicode character * in a UTF-8 encoded string, while limiting the search to @len bytes. * If @len is -1, allow unbounded search. * * Returns: %NULL if the string does not contain the character, * otherwise, a pointer to the start of the rightmost occurrence * of the character in the string. */ /** * g_utf8_strreverse: * @str: a UTF-8 encoded string * @len: the maximum length of @str to use, in bytes. If @len < 0, * then the string is nul-terminated. * * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. * (Use g_utf8_validate() on all text before trying to use UTF-8 * utility functions with it.) * * This function is intended for programmatic uses of reversed strings. * It pays no attention to decomposed characters, combining marks, byte * order marks, directional indicators (LRM, LRO, etc) and similar * characters which might need special handling when reversing a string * for display purposes. * * Note that unlike g_strreverse(), this function returns * newly-allocated memory, which should be freed with g_free() when * no longer needed. * * Returns: a newly-allocated string which is the reverse of @str * Since: 2.2 */ /** * g_utf8_strup: * @str: a UTF-8 encoded string * @len: length of @str, in bytes, or -1 if @str is nul-terminated. * * Converts all Unicode characters in the string that have a case * to uppercase. The exact manner that this is done depends * on the current locale, and may result in the number of * characters in the string increasing. (For instance, the * German ess-zet will be changed to SS.) * * Returns: a newly allocated string, with all characters * converted to uppercase. */ /** * g_utf8_substring: * @str: a UTF-8 encoded string * @start_pos: a character offset within @str * @end_pos: another character offset within @str * * Copies a substring out of a UTF-8 encoded string. * The substring will contain @end_pos - @start_pos characters. * * Returns: a newly allocated copy of the requested * substring. Free with g_free() when no longer needed. * Since: 2.30 */ /** * g_utf8_to_ucs4: * @str: a UTF-8 encoded string * @len: the maximum length of @str to use, in bytes. If @len < 0, * then the string is nul-terminated. * @items_read: (allow-none): location to store number of bytes read, or %NULL. * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be * returned in case @str contains a trailing partial * character. If an error occurs then the index of the * invalid input is stored here. * @items_written: (allow-none): location to store number of characters * written or %NULL. The value here stored does not include the * trailing 0 character. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError other than * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4. A trailing 0 character will be added to the * string after the converted text. * * Returns: a pointer to a newly allocated UCS-4 string. * This value must be freed with g_free(). If an error occurs, * %NULL will be returned and @error set. */ /** * g_utf8_to_ucs4_fast: * @str: a UTF-8 encoded string * @len: the maximum length of @str to use, in bytes. If @len < 0, * then the string is nul-terminated. * @items_written: (allow-none): location to store the number of * characters in the result, or %NULL. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4, assuming valid UTF-8 input. * This function is roughly twice as fast as g_utf8_to_ucs4() * but does no error checking on the input. A trailing 0 character * will be added to the string after the converted text. * * Returns: a pointer to a newly allocated UCS-4 string. * This value must be freed with g_free(). */ /** * g_utf8_to_utf16: * @str: a UTF-8 encoded string * @len: the maximum length (number of bytes) of @str to use. * If @len < 0, then the string is nul-terminated. * @items_read: (allow-none): location to store number of bytes read, * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be * returned in case @str contains a trailing partial character. If * an error occurs then the index of the invalid input is stored here. * @items_written: (allow-none): location to store number of #gunichar2 * written, or %NULL. The value stored here does not include the * trailing 0. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError other than * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-8 to UTF-16. A 0 character will be * added to the result after the converted text. * * Returns: a pointer to a newly allocated UTF-16 string. * This value must be freed with g_free(). If an error occurs, * %NULL will be returned and @error set. */ /** * g_utf8_validate: * @str: (array length=max_len) (element-type guint8): a pointer to character data * @max_len: max bytes to validate, or -1 to go until NUL * @end: (allow-none) (out) (transfer none): return location for end of valid data * * Validates UTF-8 encoded text. @str is the text to validate; * if @str is nul-terminated, then @max_len can be -1, otherwise * @max_len should be the number of bytes to validate. * If @end is non-%NULL, then the end of the valid range * will be stored there (i.e. the start of the first invalid * character if some bytes were invalid, or the end of the text * being validated otherwise). * * Note that g_utf8_validate() returns %FALSE if @max_len is * positive and any of the @max_len bytes are nul. * * Returns %TRUE if all of @str was valid. Many GLib and GTK+ * routines require valid UTF-8 as input; so data read from a file * or the network should be checked with g_utf8_validate() before * doing anything else with it. * * Returns: %TRUE if the text was valid UTF-8 */ /** * g_utime: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) * @utb: a pointer to a struct utimbuf. * * A wrapper for the POSIX utime() function. The utime() function * sets the access and modification timestamps of a file. * * See your C library manual for more details about how utime() works * on your system. * * Returns: 0 if the operation was successful, -1 if an error occurred * Since: 2.18 */ /** * g_variant_builder_add: (skip) * @builder: a #GVariantBuilder * @format_string: a #GVariant varargs format string * @...: arguments, as per @format_string * * Adds to a #GVariantBuilder. * * This call is a convenience wrapper that is exactly equivalent to * calling g_variant_new() followed by g_variant_builder_add_value(). * * Note that the arguments must be of the correct width for their types * specified in @format_string. This can be achieved by casting them. See * the [GVariant varargs documentation][gvariant-varargs]. * * This function might be used as follows: * * |[ * GVariant * * make_pointless_dictionary (void) * { * GVariantBuilder builder; * int i; * * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); * for (i = 0; i < 16; i++) * { * gchar buf[3]; * * sprintf (buf, "%d", i); * g_variant_builder_add (&builder, "{is}", i, buf); * } * * return g_variant_builder_end (&builder); * } * ]| * * Since: 2.24 */ /** * g_variant_builder_add_parsed: * @builder: a #GVariantBuilder * @format: a text format #GVariant * @...: arguments as per @format * * Adds to a #GVariantBuilder. * * This call is a convenience wrapper that is exactly equivalent to * calling g_variant_new_parsed() followed by * g_variant_builder_add_value(). * * Note that the arguments must be of the correct width for their types * specified in @format_string. This can be achieved by casting them. See * the [GVariant varargs documentation][gvariant-varargs]. * * This function might be used as follows: * * |[ * GVariant * * make_pointless_dictionary (void) * { * GVariantBuilder builder; * int i; * * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); * g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); * g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); * g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); * return g_variant_builder_end (&builder); * } * ]| * * Since: 2.26 */ /** * g_variant_builder_add_value: * @builder: a #GVariantBuilder * @value: a #GVariant * * Adds @value to @builder. * * It is an error to call this function in any way that would create an * inconsistent value to be constructed. Some examples of this are * putting different types of items into an array, putting the wrong * types or number of items in a tuple, putting more than one value into * a variant, etc. * * If @value is a floating reference (see g_variant_ref_sink()), * the @builder instance takes ownership of @value. * * Since: 2.24 */ /** * g_variant_builder_clear: (skip) * @builder: a #GVariantBuilder * * Releases all memory associated with a #GVariantBuilder without * freeing the #GVariantBuilder structure itself. * * It typically only makes sense to do this on a stack-allocated * #GVariantBuilder if you want to abort building the value part-way * through. This function need not be called if you call * g_variant_builder_end() and it also doesn't need to be called on * builders allocated with g_variant_builder_new (see * g_variant_builder_unref() for that). * * This function leaves the #GVariantBuilder structure set to all-zeros. * It is valid to call this function on either an initialised * #GVariantBuilder or one that is set to all-zeros but it is not valid * to call this function on uninitialised memory. * * Since: 2.24 */ /** * g_variant_builder_close: * @builder: a #GVariantBuilder * * Closes the subcontainer inside the given @builder that was opened by * the most recent call to g_variant_builder_open(). * * It is an error to call this function in any way that would create an * inconsistent value to be constructed (ie: too few values added to the * subcontainer). * * Since: 2.24 */ /** * g_variant_builder_end: * @builder: a #GVariantBuilder * * Ends the builder process and returns the constructed value. * * It is not permissible to use @builder in any way after this call * except for reference counting operations (in the case of a * heap-allocated #GVariantBuilder) or by reinitialising it with * g_variant_builder_init() (in the case of stack-allocated). * * It is an error to call this function in any way that would create an * inconsistent value to be constructed (ie: insufficient number of * items added to a container with a specific number of children * required). It is also an error to call this function if the builder * was created with an indefinite array or maybe type and no children * have been added; in this case it is impossible to infer the type of * the empty array. * * Returns: (transfer none): a new, floating, #GVariant * Since: 2.24 */ /** * g_variant_builder_init: (skip) * @builder: a #GVariantBuilder * @type: a container type * * Initialises a #GVariantBuilder structure. * * @type must be non-%NULL. It specifies the type of container to * construct. It can be an indefinite type such as * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)". * Maybe, array, tuple, dictionary entry and variant-typed values may be * constructed. * * After the builder is initialised, values are added using * g_variant_builder_add_value() or g_variant_builder_add(). * * After all the child values are added, g_variant_builder_end() frees * the memory associated with the builder and returns the #GVariant that * was created. * * This function completely ignores the previous contents of @builder. * On one hand this means that it is valid to pass in completely * uninitialised memory. On the other hand, this means that if you are * initialising over top of an existing #GVariantBuilder you need to * first call g_variant_builder_clear() in order to avoid leaking * memory. * * You must not call g_variant_builder_ref() or * g_variant_builder_unref() on a #GVariantBuilder that was initialised * with this function. If you ever pass a reference to a * #GVariantBuilder outside of the control of your own code then you * should assume that the person receiving that reference may try to use * reference counting; you should use g_variant_builder_new() instead of * this function. * * Since: 2.24 */ /** * g_variant_builder_new: * @type: a container type * * Allocates and initialises a new #GVariantBuilder. * * You should call g_variant_builder_unref() on the return value when it * is no longer needed. The memory will not be automatically freed by * any other call. * * In most cases it is easier to place a #GVariantBuilder directly on * the stack of the calling function and initialise it with * g_variant_builder_init(). * * Returns: (transfer full): a #GVariantBuilder * Since: 2.24 */ /** * g_variant_builder_open: * @builder: a #GVariantBuilder * @type: a #GVariantType * * Opens a subcontainer inside the given @builder. When done adding * items to the subcontainer, g_variant_builder_close() must be called. * * It is an error to call this function in any way that would cause an * inconsistent value to be constructed (ie: adding too many values or * a value of an incorrect type). * * Since: 2.24 */ /** * g_variant_builder_ref: * @builder: a #GVariantBuilder allocated by g_variant_builder_new() * * Increases the reference count on @builder. * * Don't call this on stack-allocated #GVariantBuilder instances or bad * things will happen. * * Returns: (transfer full): a new reference to @builder * Since: 2.24 */ /** * g_variant_builder_unref: * @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new() * * Decreases the reference count on @builder. * * In the event that there are no more references, releases all memory * associated with the #GVariantBuilder. * * Don't call this on stack-allocated #GVariantBuilder instances or bad * things will happen. * * Since: 2.24 */ /** * g_variant_byteswap: * @value: a #GVariant * * Performs a byteswapping operation on the contents of @value. The * result is that all multi-byte numeric data contained in @value is * byteswapped. That includes 16, 32, and 64bit signed and unsigned * integers as well as file handles and double precision floating point * values. * * This function is an identity mapping on any value that does not * contain multi-byte numeric data. That include strings, booleans, * bytes and containers containing only these things (recursively). * * The returned value is always in normal form and is marked as trusted. * * Returns: (transfer full): the byteswapped form of @value * Since: 2.24 */ /** * g_variant_check_format_string: * @value: a #GVariant * @format_string: a valid #GVariant format string * @copy_only: %TRUE to ensure the format string makes deep copies * * Checks if calling g_variant_get() with @format_string on @value would * be valid from a type-compatibility standpoint. @format_string is * assumed to be a valid format string (from a syntactic standpoint). * * If @copy_only is %TRUE then this function additionally checks that it * would be safe to call g_variant_unref() on @value immediately after * the call to g_variant_get() without invalidating the result. This is * only possible if deep copies are made (ie: there are no pointers to * the data inside of the soon-to-be-freed #GVariant instance). If this * check fails then a g_critical() is printed and %FALSE is returned. * * This function is meant to be used by functions that wish to provide * varargs accessors to #GVariant values of uncertain values (eg: * g_variant_lookup() or g_menu_model_get_item_attribute()). * * Returns: %TRUE if @format_string is safe to use * Since: 2.34 */ /** * g_variant_classify: * @value: a #GVariant * * Classifies @value according to its top-level type. * * Returns: the #GVariantClass of @value * Since: 2.24 */ /** * g_variant_compare: * @one: (type GVariant): a basic-typed #GVariant instance * @two: (type GVariant): a #GVariant instance of the same type * * Compares @one and @two. * * The types of @one and @two are #gconstpointer only to allow use of * this function with #GTree, #GPtrArray, etc. They must each be a * #GVariant. * * Comparison is only defined for basic types (ie: booleans, numbers, * strings). For booleans, %FALSE is less than %TRUE. Numbers are * ordered in the usual way. Strings are in ASCII lexographical order. * * It is a programmer error to attempt to compare container values or * two values that have types that are not exactly equal. For example, * you cannot compare a 32-bit signed integer with a 32-bit unsigned * integer. Also note that this function is not particularly * well-behaved when it comes to comparison of doubles; in particular, * the handling of incomparable values (ie: NaN) is undefined. * * If you only require an equality comparison, g_variant_equal() is more * general. * * Returns: negative value if a < b; * zero if a = b; * positive value if a > b. * Since: 2.26 */ /** * g_variant_dict_clear: * @dict: a #GVariantDict * * Releases all memory associated with a #GVariantDict without freeing * the #GVariantDict structure itself. * * It typically only makes sense to do this on a stack-allocated * #GVariantDict if you want to abort building the value part-way * through. This function need not be called if you call * g_variant_dict_end() and it also doesn't need to be called on dicts * allocated with g_variant_dict_new (see g_variant_dict_unref() for * that). * * It is valid to call this function on either an initialised * #GVariantDict or one that was previously cleared by an earlier call * to g_variant_dict_clear() but it is not valid to call this function * on uninitialised memory. * * Since: 2.40 */ /** * g_variant_dict_contains: * @dict: a #GVariantDict * @key: the key to lookup in the dictionary * * Checks if @key exists in @dict. * * Returns: %TRUE if @key is in @dict * Since: 2.40 */ /** * g_variant_dict_end: * @dict: a #GVariantDict * * Returns the current value of @dict as a #GVariant of type * %G_VARIANT_TYPE_VARDICT, clearing it in the process. * * It is not permissible to use @dict in any way after this call except * for reference counting operations (in the case of a heap-allocated * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in * the case of stack-allocated). * * Returns: (transfer none): a new, floating, #GVariant * Since: 2.40 */ /** * g_variant_dict_init: (skip) * @dict: a #GVariantDict * @from_asv: (allow-none): the initial value for @dict * * Initialises a #GVariantDict structure. * * If @from_asv is given, it is used to initialise the dictionary. * * This function completely ignores the previous contents of @dict. On * one hand this means that it is valid to pass in completely * uninitialised memory. On the other hand, this means that if you are * initialising over top of an existing #GVariantDict you need to first * call g_variant_dict_clear() in order to avoid leaking memory. * * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a * #GVariantDict that was initialised with this function. If you ever * pass a reference to a #GVariantDict outside of the control of your * own code then you should assume that the person receiving that * reference may try to use reference counting; you should use * g_variant_dict_new() instead of this function. * * Since: 2.40 */ /** * g_variant_dict_insert: * @dict: a #GVariantDict * @key: the key to insert a value for * @format_string: a #GVariant varargs format string * @...: arguments, as per @format_string * * Inserts a value into a #GVariantDict. * * This call is a convenience wrapper that is exactly equivalent to * calling g_variant_new() followed by g_variant_dict_insert_value(). * * Since: 2.40 */ /** * g_variant_dict_insert_value: * @dict: a #GVariantDict * @key: the key to insert a value for * @value: the value to insert * * Inserts (or replaces) a key in a #GVariantDict. * * @value is consumed if it is floating. * * Since: 2.40 */ /** * g_variant_dict_lookup: * @dict: a #GVariantDict * @key: the key to lookup in the dictionary * @format_string: a GVariant format string * @...: the arguments to unpack the value into * * Looks up a value in a #GVariantDict. * * This function is a wrapper around g_variant_dict_lookup_value() and * g_variant_get(). In the case that %NULL would have been returned, * this function returns %FALSE. Otherwise, it unpacks the returned * value and returns %TRUE. * * @format_string determines the C types that are used for unpacking the * values and also determines if the values are copied or borrowed, see the * section on [GVariant format strings][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked * Since: 2.40 */ /** * g_variant_dict_lookup_value: * @dict: a #GVariantDict * @key: the key to lookup in the dictionary * @expected_type: (allow-none): a #GVariantType, or %NULL * * Looks up a value in a #GVariantDict. * * If @key is not found in @dictionary, %NULL is returned. * * The @expected_type string specifies what type of value is expected. * If the value associated with @key has a different type then %NULL is * returned. * * If the key is found and the value has the correct type, it is * returned. If @expected_type was specified then any non-%NULL return * value will have this type. * * Returns: (transfer full): the value of the dictionary key, or %NULL * Since: 2.40 */ /** * g_variant_dict_new: * @from_asv: (allow-none): the #GVariant with which to initialise the * dictionary * * Allocates and initialises a new #GVariantDict. * * You should call g_variant_dict_unref() on the return value when it * is no longer needed. The memory will not be automatically freed by * any other call. * * In some cases it may be easier to place a #GVariantDict directly on * the stack of the calling function and initialise it with * g_variant_dict_init(). This is particularly useful when you are * using #GVariantDict to construct a #GVariant. * * Returns: (transfer full): a #GVariantDict * Since: 2.40 */ /** * g_variant_dict_ref: * @dict: a heap-allocated #GVariantDict * * Increases the reference count on @dict. * * Don't call this on stack-allocated #GVariantDict instances or bad * things will happen. * * Returns: (transfer full): a new reference to @dict * Since: 2.40 */ /** * g_variant_dict_remove: * @dict: a #GVariantDict * @key: the key to remove * * Removes a key and its associated value from a #GVariantDict. * * Returns: %TRUE if the key was found and removed * Since: 2.40 */ /** * g_variant_dict_unref: * @dict: (transfer full): a heap-allocated #GVariantDict * * Decreases the reference count on @dict. * * In the event that there are no more references, releases all memory * associated with the #GVariantDict. * * Don't call this on stack-allocated #GVariantDict instances or bad * things will happen. * * Since: 2.40 */ /** * g_variant_dup_bytestring: * @value: an array-of-bytes #GVariant instance * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store * the length (not including the nul terminator) * * Similar to g_variant_get_bytestring() except that instead of * returning a constant string, the string is duplicated. * * The return value must be freed using g_free(). * * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8): * a newly allocated string * Since: 2.26 */ /** * g_variant_dup_bytestring_array: * @value: an array of array of bytes #GVariant ('aay') * @length: (out) (allow-none): the length of the result, or %NULL * * Gets the contents of an array of array of bytes #GVariant. This call * makes a deep copy; the return result should be released with * g_strfreev(). * * If @length is non-%NULL then the number of elements in the result is * stored there. In any case, the resulting array will be * %NULL-terminated. * * For an empty array, @length will be set to 0 and a pointer to a * %NULL pointer will be returned. * * Returns: (array length=length) (transfer full): an array of strings * Since: 2.26 */ /** * g_variant_dup_objv: * @value: an array of object paths #GVariant * @length: (out) (allow-none): the length of the result, or %NULL * * Gets the contents of an array of object paths #GVariant. This call * makes a deep copy; the return result should be released with * g_strfreev(). * * If @length is non-%NULL then the number of elements in the result * is stored there. In any case, the resulting array will be * %NULL-terminated. * * For an empty array, @length will be set to 0 and a pointer to a * %NULL pointer will be returned. * * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings * Since: 2.30 */ /** * g_variant_dup_string: * @value: a string #GVariant instance * @length: (out): a pointer to a #gsize, to store the length * * Similar to g_variant_get_string() except that instead of returning * a constant string, the string is duplicated. * * The string will always be utf8 encoded. * * The return value must be freed using g_free(). * * Returns: (transfer full): a newly allocated string, utf8 encoded * Since: 2.24 */ /** * g_variant_dup_strv: * @value: an array of strings #GVariant * @length: (out) (allow-none): the length of the result, or %NULL * * Gets the contents of an array of strings #GVariant. This call * makes a deep copy; the return result should be released with * g_strfreev(). * * If @length is non-%NULL then the number of elements in the result * is stored there. In any case, the resulting array will be * %NULL-terminated. * * For an empty array, @length will be set to 0 and a pointer to a * %NULL pointer will be returned. * * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings * Since: 2.24 */ /** * g_variant_equal: * @one: (type GVariant): a #GVariant instance * @two: (type GVariant): a #GVariant instance * * Checks if @one and @two have the same type and value. * * The types of @one and @two are #gconstpointer only to allow use of * this function with #GHashTable. They must each be a #GVariant. * * Returns: %TRUE if @one and @two are equal * Since: 2.24 */ /** * g_variant_get: (skip) * @value: a #GVariant instance * @format_string: a #GVariant format string * @...: arguments, as per @format_string * * Deconstructs a #GVariant instance. * * Think of this function as an analogue to scanf(). * * The arguments that are expected by this function are entirely * determined by @format_string. @format_string also restricts the * permissible types of @value. It is an error to give a value with * an incompatible type. See the section on * [GVariant format strings][gvariant-format-strings]. * Please note that the syntax of the format string is very likely to be * extended in the future. * * @format_string determines the C types that are used for unpacking * the values and also determines if the values are copied or borrowed, * see the section on * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 */ /** * g_variant_get_boolean: * @value: a boolean #GVariant instance * * Returns the boolean value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_BOOLEAN. * * Returns: %TRUE or %FALSE * Since: 2.24 */ /** * g_variant_get_byte: * @value: a byte #GVariant instance * * Returns the byte value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_BYTE. * * Returns: a #guchar * Since: 2.24 */ /** * g_variant_get_bytestring: * @value: an array-of-bytes #GVariant instance * * Returns the string value of a #GVariant instance with an * array-of-bytes type. The string has no particular encoding. * * If the array does not end with a nul terminator character, the empty * string is returned. For this reason, you can always trust that a * non-%NULL nul-terminated string will be returned by this function. * * If the array contains a nul terminator character somewhere other than * the last byte then the returned string is the string, up to the first * such nul character. * * It is an error to call this function with a @value that is not an * array of bytes. * * The return value remains valid as long as @value exists. * * Returns: (transfer none) (array zero-terminated=1) (element-type guint8): * the constant string * Since: 2.26 */ /** * g_variant_get_bytestring_array: * @value: an array of array of bytes #GVariant ('aay') * @length: (out) (allow-none): the length of the result, or %NULL * * Gets the contents of an array of array of bytes #GVariant. This call * makes a shallow copy; the return result should be released with * g_free(), but the individual strings must not be modified. * * If @length is non-%NULL then the number of elements in the result is * stored there. In any case, the resulting array will be * %NULL-terminated. * * For an empty array, @length will be set to 0 and a pointer to a * %NULL pointer will be returned. * * Returns: (array length=length) (transfer container): an array of constant strings * Since: 2.26 */ /** * g_variant_get_child: (skip) * @value: a container #GVariant * @index_: the index of the child to deconstruct * @format_string: a #GVariant format string * @...: arguments, as per @format_string * * Reads a child item out of a container #GVariant instance and * deconstructs it according to @format_string. This call is * essentially a combination of g_variant_get_child_value() and * g_variant_get(). * * @format_string determines the C types that are used for unpacking * the values and also determines if the values are copied or borrowed, * see the section on * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 */ /** * g_variant_get_child_value: * @value: a container #GVariant * @index_: the index of the child to fetch * * Reads a child item out of a container #GVariant instance. This * includes variants, maybes, arrays, tuples and dictionary * entries. It is an error to call this function on any other type of * #GVariant. * * It is an error if @index_ is greater than the number of child items * in the container. See g_variant_n_children(). * * The returned value is never floating. You should free it with * g_variant_unref() when you're done with it. * * This function is O(1). * * Returns: (transfer full): the child at the specified index * Since: 2.24 */ /** * g_variant_get_data: * @value: a #GVariant instance * * Returns a pointer to the serialised form of a #GVariant instance. * The returned data may not be in fully-normalised form if read from an * untrusted source. The returned data must not be freed; it remains * valid for as long as @value exists. * * If @value is a fixed-sized value that was deserialised from a * corrupted serialised container then %NULL may be returned. In this * case, the proper thing to do is typically to use the appropriate * number of nul bytes in place of @value. If @value is not fixed-sized * then %NULL is never returned. * * In the case that @value is already in serialised form, this function * is O(1). If the value is not already in serialised form, * serialisation occurs implicitly and is approximately O(n) in the size * of the result. * * To deserialise the data returned by this function, in addition to the * serialised data, you must know the type of the #GVariant, and (if the * machine might be different) the endianness of the machine that stored * it. As a result, file formats or network messages that incorporate * serialised #GVariants must include this information either * implicitly (for instance "the file always contains a * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or * explicitly (by storing the type and/or endianness in addition to the * serialised data). * * Returns: (transfer none): the serialised form of @value, or %NULL * Since: 2.24 */ /** * g_variant_get_data_as_bytes: * @value: a #GVariant * * Returns a pointer to the serialised form of a #GVariant instance. * The semantics of this function are exactly the same as * g_variant_get_data(), except that the returned #GBytes holds * a reference to the variant data. * * Returns: (transfer full): A new #GBytes representing the variant data * Since: 2.36 */ /** * g_variant_get_double: * @value: a double #GVariant instance * * Returns the double precision floating point value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_DOUBLE. * * Returns: a #gdouble * Since: 2.24 */ /** * g_variant_get_fixed_array: * @value: a #GVariant array with fixed-sized elements * @n_elements: (out): a pointer to the location to store the number of items * @element_size: the size of each element * * Provides access to the serialised data for an array of fixed-sized * items. * * @value must be an array with fixed-sized elements. Numeric types are * fixed-size, as are tuples containing only other fixed-sized types. * * @element_size must be the size of a single element in the array, * as given by the section on * [serialized data memory][gvariant-serialised-data-memory]. * * In particular, arrays of these fixed-sized types can be interpreted * as an array of the given C type, with @element_size set to the size * the appropriate type: * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) * - %G_VARIANT_TYPE_BYTE: #guchar * - %G_VARIANT_TYPE_HANDLE: #guint32 * - %G_VARIANT_TYPE_DOUBLE: #gdouble * * For example, if calling this function for an array of 32-bit integers, * you might say sizeof(gint32). This value isn't used except for the purpose * of a double-check that the form of the serialised data matches the caller's * expectation. * * @n_elements, which must be non-%NULL is set equal to the number of * items in the array. * * Returns: (array length=n_elements) (transfer none): a pointer to * the fixed array * Since: 2.24 */ /** * g_variant_get_handle: * @value: a handle #GVariant instance * * Returns the 32-bit signed integer value of @value. * * It is an error to call this function with a @value of any type other * than %G_VARIANT_TYPE_HANDLE. * * By convention, handles are indexes into an array of file descriptors * that are sent alongside a D-Bus message. If you're not interacting * with D-Bus, you probably don't need them. * * Returns: a #gint32 * Since: 2.24 */ /** * g_variant_get_int16: * @value: a int16 #GVariant instance * * Returns the 16-bit signed integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_INT16. * * Returns: a #gint16 * Since: 2.24 */ /** * g_variant_get_int32: * @value: a int32 #GVariant instance * * Returns the 32-bit signed integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_INT32. * * Returns: a #gint32 * Since: 2.24 */ /** * g_variant_get_int64: * @value: a int64 #GVariant instance * * Returns the 64-bit signed integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_INT64. * * Returns: a #gint64 * Since: 2.24 */ /** * g_variant_get_maybe: * @value: a maybe-typed value * * Given a maybe-typed #GVariant instance, extract its value. If the * value is Nothing, then this function returns %NULL. * * Returns: (allow-none) (transfer full): the contents of @value, or %NULL * Since: 2.24 */ /** * g_variant_get_normal_form: * @value: a #GVariant * * Gets a #GVariant instance that has the same value as @value and is * trusted to be in normal form. * * If @value is already trusted to be in normal form then a new * reference to @value is returned. * * If @value is not already trusted, then it is scanned to check if it * is in normal form. If it is found to be in normal form then it is * marked as trusted and a new reference to it is returned. * * If @value is found not to be in normal form then a new trusted * #GVariant is created with the same value as @value. * * It makes sense to call this function if you've received #GVariant * data from untrusted sources and you want to ensure your serialised * output is definitely in normal form. * * Returns: (transfer full): a trusted #GVariant * Since: 2.24 */ /** * g_variant_get_objv: * @value: an array of object paths #GVariant * @length: (out) (allow-none): the length of the result, or %NULL * * Gets the contents of an array of object paths #GVariant. This call * makes a shallow copy; the return result should be released with * g_free(), but the individual strings must not be modified. * * If @length is non-%NULL then the number of elements in the result * is stored there. In any case, the resulting array will be * %NULL-terminated. * * For an empty array, @length will be set to 0 and a pointer to a * %NULL pointer will be returned. * * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings * Since: 2.30 */ /** * g_variant_get_size: * @value: a #GVariant instance * * Determines the number of bytes that would be required to store @value * with g_variant_store(). * * If @value has a fixed-sized type then this function always returned * that fixed size. * * In the case that @value is already in serialised form or the size has * already been calculated (ie: this function has been called before) * then this function is O(1). Otherwise, the size is calculated, an * operation which is approximately O(n) in the number of values * involved. * * Returns: the serialised size of @value * Since: 2.24 */ /** * g_variant_get_string: * @value: a string #GVariant instance * @length: (allow-none) (default 0) (out): a pointer to a #gsize, * to store the length * * Returns the string value of a #GVariant instance with a string * type. This includes the types %G_VARIANT_TYPE_STRING, * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. * * The string will always be utf8 encoded. * * If @length is non-%NULL then the length of the string (in bytes) is * returned there. For trusted values, this information is already * known. For untrusted values, a strlen() will be performed. * * It is an error to call this function with a @value of any type * other than those three. * * The return value remains valid as long as @value exists. * * Returns: (transfer none): the constant string, utf8 encoded * Since: 2.24 */ /** * g_variant_get_strv: * @value: an array of strings #GVariant * @length: (out) (allow-none): the length of the result, or %NULL * * Gets the contents of an array of strings #GVariant. This call * makes a shallow copy; the return result should be released with * g_free(), but the individual strings must not be modified. * * If @length is non-%NULL then the number of elements in the result * is stored there. In any case, the resulting array will be * %NULL-terminated. * * For an empty array, @length will be set to 0 and a pointer to a * %NULL pointer will be returned. * * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings * Since: 2.24 */ /** * g_variant_get_type: * @value: a #GVariant * * Determines the type of @value. * * The return value is valid for the lifetime of @value and must not * be freed. * * Returns: a #GVariantType * Since: 2.24 */ /** * g_variant_get_type_string: * @value: a #GVariant * * Returns the type string of @value. Unlike the result of calling * g_variant_type_peek_string(), this string is nul-terminated. This * string belongs to #GVariant and must not be freed. * * Returns: the type string for the type of @value * Since: 2.24 */ /** * g_variant_get_uint16: * @value: a uint16 #GVariant instance * * Returns the 16-bit unsigned integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_UINT16. * * Returns: a #guint16 * Since: 2.24 */ /** * g_variant_get_uint32: * @value: a uint32 #GVariant instance * * Returns the 32-bit unsigned integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_UINT32. * * Returns: a #guint32 * Since: 2.24 */ /** * g_variant_get_uint64: * @value: a uint64 #GVariant instance * * Returns the 64-bit unsigned integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_UINT64. * * Returns: a #guint64 * Since: 2.24 */ /** * g_variant_get_va: (skip) * @value: a #GVariant * @format_string: a string that is prefixed with a format string * @endptr: (allow-none) (default NULL): location to store the end pointer, * or %NULL * @app: a pointer to a #va_list * * This function is intended to be used by libraries based on #GVariant * that want to provide g_variant_get()-like functionality to their * users. * * The API is more general than g_variant_get() to allow a wider range * of possible uses. * * @format_string must still point to a valid format string, but it only * need to be nul-terminated if @endptr is %NULL. If @endptr is * non-%NULL then it is updated to point to the first character past the * end of the format string. * * @app is a pointer to a #va_list. The arguments, according to * @format_string, are collected from this #va_list and the list is left * pointing to the argument following the last. * * These two generalisations allow mixing of multiple calls to * g_variant_new_va() and g_variant_get_va() within a single actual * varargs call by the user. * * @format_string determines the C types that are used for unpacking * the values and also determines if the values are copied or borrowed, * see the section on * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 */ /** * g_variant_get_variant: * @value: a variant #GVariant instance * * Unboxes @value. The result is the #GVariant instance that was * contained in @value. * * Returns: (transfer full): the item contained in the variant * Since: 2.24 */ /** * g_variant_hash: * @value: (type GVariant): a basic #GVariant value as a #gconstpointer * * Generates a hash value for a #GVariant instance. * * The output of this function is guaranteed to be the same for a given * value only per-process. It may change between different processor * architectures or even different versions of GLib. Do not use this * function as a basis for building protocols or file formats. * * The type of @value is #gconstpointer only to allow use of this * function with #GHashTable. @value must be a #GVariant. * * Returns: a hash value corresponding to @value * Since: 2.24 */ /** * g_variant_is_container: * @value: a #GVariant instance * * Checks if @value is a container. * * Returns: %TRUE if @value is a container * Since: 2.24 */ /** * g_variant_is_floating: * @value: a #GVariant * * Checks whether @value has a floating reference count. * * This function should only ever be used to assert that a given variant * is or is not floating, or for debug purposes. To acquire a reference * to a variant that might be floating, always use g_variant_ref_sink() * or g_variant_take_ref(). * * See g_variant_ref_sink() for more information about floating reference * counts. * * Returns: whether @value is floating * Since: 2.26 */ /** * g_variant_is_normal_form: * @value: a #GVariant instance * * Checks if @value is in normal form. * * The main reason to do this is to detect if a given chunk of * serialised data is in normal form: load the data into a #GVariant * using g_variant_new_from_data() and then use this function to * check. * * If @value is found to be in normal form then it will be marked as * being trusted. If the value was already marked as being trusted then * this function will immediately return %TRUE. * * Returns: %TRUE if @value is in normal form * Since: 2.24 */ /** * g_variant_is_object_path: * @string: a normal C nul-terminated string * * Determines if a given string is a valid D-Bus object path. You * should ensure that a string is a valid D-Bus object path before * passing it to g_variant_new_object_path(). * * A valid object path starts with '/' followed by zero or more * sequences of characters separated by '/' characters. Each sequence * must contain only the characters "[A-Z][a-z][0-9]_". No sequence * (including the one following the final '/' character) may be empty. * * Returns: %TRUE if @string is a D-Bus object path * Since: 2.24 */ /** * g_variant_is_of_type: * @value: a #GVariant instance * @type: a #GVariantType * * Checks if a value has a type matching the provided type. * * Returns: %TRUE if the type of @value matches @type * Since: 2.24 */ /** * g_variant_is_signature: * @string: a normal C nul-terminated string * * Determines if a given string is a valid D-Bus type signature. You * should ensure that a string is a valid D-Bus type signature before * passing it to g_variant_new_signature(). * * D-Bus type signatures consist of zero or more definite #GVariantType * strings in sequence. * * Returns: %TRUE if @string is a D-Bus type signature * Since: 2.24 */ /** * g_variant_iter_copy: * @iter: a #GVariantIter * * Creates a new heap-allocated #GVariantIter to iterate over the * container that was being iterated over by @iter. Iteration begins on * the new iterator from the current position of the old iterator but * the two copies are independent past that point. * * Use g_variant_iter_free() to free the return value when you no longer * need it. * * A reference is taken to the container that @iter is iterating over * and will be releated only when g_variant_iter_free() is called. * * Returns: (transfer full): a new heap-allocated #GVariantIter * Since: 2.24 */ /** * g_variant_iter_free: * @iter: (transfer full): a heap-allocated #GVariantIter * * Frees a heap-allocated #GVariantIter. Only call this function on * iterators that were returned by g_variant_iter_new() or * g_variant_iter_copy(). * * Since: 2.24 */ /** * g_variant_iter_init: (skip) * @iter: a pointer to a #GVariantIter * @value: a container #GVariant * * Initialises (without allocating) a #GVariantIter. @iter may be * completely uninitialised prior to this call; its old value is * ignored. * * The iterator remains valid for as long as @value exists, and need not * be freed in any way. * * Returns: the number of items in @value * Since: 2.24 */ /** * g_variant_iter_loop: (skip) * @iter: a #GVariantIter * @format_string: a GVariant format string * @...: the arguments to unpack the value into * * Gets the next item in the container and unpacks it into the variable * argument list according to @format_string, returning %TRUE. * * If no more items remain then %FALSE is returned. * * On the first call to this function, the pointers appearing on the * variable argument list are assumed to point at uninitialised memory. * On the second and later calls, it is assumed that the same pointers * will be given and that they will point to the memory as set by the * previous call to this function. This allows the previous values to * be freed, as appropriate. * * This function is intended to be used with a while loop as * demonstrated in the following example. This function can only be * used when iterating over an array. It is only valid to call this * function with a string constant for the format string and the same * string constant must be used each time. Mixing calls to this * function and g_variant_iter_next() or g_variant_iter_next_value() on * the same iterator causes undefined behavior. * * If you break out of a such a while loop using g_variant_iter_loop() then * you must free or unreference all the unpacked values as you would with * g_variant_get(). Failure to do so will cause a memory leak. * * Here is an example for memory management with g_variant_iter_loop(): * |[ * // Iterates a dictionary of type 'a{sv}' * void * iterate_dictionary (GVariant *dictionary) * { * GVariantIter iter; * GVariant *value; * gchar *key; * * g_variant_iter_init (&iter, dictionary); * while (g_variant_iter_loop (&iter, "{sv}", &key, &value)) * { * g_print ("Item '%s' has type '%s'\n", key, * g_variant_get_type_string (value)); * * // no need to free 'key' and 'value' here * // unless breaking out of this loop * } * } * ]| * * For most cases you should use g_variant_iter_next(). * * This function is really only useful when unpacking into #GVariant or * #GVariantIter in order to allow you to skip the call to * g_variant_unref() or g_variant_iter_free(). * * For example, if you are only looping over simple integer and string * types, g_variant_iter_next() is definitely preferred. For string * types, use the '&' prefix to avoid allocating any memory at all (and * thereby avoiding the need to free anything as well). * * @format_string determines the C types that are used for unpacking * the values and also determines if the values are copied or borrowed. * * See the section on * [GVariant format strings][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked, or %FALSE if there was no * value * Since: 2.24 */ /** * g_variant_iter_n_children: * @iter: a #GVariantIter * * Queries the number of child items in the container that we are * iterating over. This is the total number of items -- not the number * of items remaining. * * This function might be useful for preallocation of arrays. * * Returns: the number of children in the container * Since: 2.24 */ /** * g_variant_iter_new: * @value: a container #GVariant * * Creates a heap-allocated #GVariantIter for iterating over the items * in @value. * * Use g_variant_iter_free() to free the return value when you no longer * need it. * * A reference is taken to @value and will be released only when * g_variant_iter_free() is called. * * Returns: (transfer full): a new heap-allocated #GVariantIter * Since: 2.24 */ /** * g_variant_iter_next: (skip) * @iter: a #GVariantIter * @format_string: a GVariant format string * @...: the arguments to unpack the value into * * Gets the next item in the container and unpacks it into the variable * argument list according to @format_string, returning %TRUE. * * If no more items remain then %FALSE is returned. * * All of the pointers given on the variable arguments list of this * function are assumed to point at uninitialised memory. It is the * responsibility of the caller to free all of the values returned by * the unpacking process. * * Here is an example for memory management with g_variant_iter_next(): * |[ * // Iterates a dictionary of type 'a{sv}' * void * iterate_dictionary (GVariant *dictionary) * { * GVariantIter iter; * GVariant *value; * gchar *key; * * g_variant_iter_init (&iter, dictionary); * while (g_variant_iter_next (&iter, "{sv}", &key, &value)) * { * g_print ("Item '%s' has type '%s'\n", key, * g_variant_get_type_string (value)); * * // must free data for ourselves * g_variant_unref (value); * g_free (key); * } * } * ]| * * For a solution that is likely to be more convenient to C programmers * when dealing with loops, see g_variant_iter_loop(). * * @format_string determines the C types that are used for unpacking * the values and also determines if the values are copied or borrowed. * * See the section on * [GVariant format strings][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value * Since: 2.24 */ /** * g_variant_iter_next_value: * @iter: a #GVariantIter * * Gets the next item in the container. If no more items remain then * %NULL is returned. * * Use g_variant_unref() to drop your reference on the return value when * you no longer need it. * * Here is an example for iterating with g_variant_iter_next_value(): * |[ * // recursively iterate a container * void * iterate_container_recursive (GVariant *container) * { * GVariantIter iter; * GVariant *child; * * g_variant_iter_init (&iter, container); * while ((child = g_variant_iter_next_value (&iter))) * { * g_print ("type '%s'\n", g_variant_get_type_string (child)); * * if (g_variant_is_container (child)) * iterate_container_recursive (child); * * g_variant_unref (child); * } * } * ]| * * Returns: (allow-none) (transfer full): a #GVariant, or %NULL * Since: 2.24 */ /** * g_variant_lookup: (skip) * @dictionary: a dictionary #GVariant * @key: the key to lookup in the dictionary * @format_string: a GVariant format string * @...: the arguments to unpack the value into * * Looks up a value in a dictionary #GVariant. * * This function is a wrapper around g_variant_lookup_value() and * g_variant_get(). In the case that %NULL would have been returned, * this function returns %FALSE. Otherwise, it unpacks the returned * value and returns %TRUE. * * @format_string determines the C types that are used for unpacking * the values and also determines if the values are copied or borrowed, * see the section on * [GVariant format strings][gvariant-format-strings-pointers]. * * This function is currently implemented with a linear scan. If you * plan to do many lookups then #GVariantDict may be more efficient. * * Returns: %TRUE if a value was unpacked * Since: 2.28 */ /** * g_variant_lookup_value: * @dictionary: a dictionary #GVariant * @key: the key to lookup in the dictionary * @expected_type: (allow-none): a #GVariantType, or %NULL * * Looks up a value in a dictionary #GVariant. * * This function works with dictionaries of the type a{s*} (and equally * well with type a{o*}, but we only further discuss the string case * for sake of clarity). * * In the event that @dictionary has the type a{sv}, the @expected_type * string specifies what type of value is expected to be inside of the * variant. If the value inside the variant has a different type then * %NULL is returned. In the event that @dictionary has a value type other * than v then @expected_type must directly match the key type and it is * used to unpack the value directly or an error occurs. * * In either case, if @key is not found in @dictionary, %NULL is returned. * * If the key is found and the value has the correct type, it is * returned. If @expected_type was specified then any non-%NULL return * value will have this type. * * This function is currently implemented with a linear scan. If you * plan to do many lookups then #GVariantDict may be more efficient. * * Returns: (transfer full): the value of the dictionary key, or %NULL * Since: 2.28 */ /** * g_variant_n_children: * @value: a container #GVariant * * Determines the number of children in a container #GVariant instance. * This includes variants, maybes, arrays, tuples and dictionary * entries. It is an error to call this function on any other type of * #GVariant. * * For variants, the return value is always 1. For values with maybe * types, it is always zero or one. For arrays, it is the length of the * array. For tuples it is the number of tuple items (which depends * only on the type). For dictionary entries, it is always 2 * * This function is O(1). * * Returns: the number of children in the container * Since: 2.24 */ /** * g_variant_new: (skip) * @format_string: a #GVariant format string * @...: arguments, as per @format_string * * Creates a new #GVariant instance. * * Think of this function as an analogue to g_strdup_printf(). * * The type of the created instance and the arguments that are expected * by this function are determined by @format_string. See the section on * [GVariant format strings][gvariant-format-strings]. Please note that * the syntax of the format string is very likely to be extended in the * future. * * The first character of the format string must not be '*' '?' '@' or * 'r'; in essence, a new #GVariant must always be constructed by this * function (and not merely passed through it unmodified). * * Note that the arguments must be of the correct width for their types * specified in @format_string. This can be achieved by casting them. See * the [GVariant varargs documentation][gvariant-varargs]. * * |[ * MyFlags some_flags = FLAG_ONE | FLAG_TWO; * const gchar *some_strings[] = { "a", "b", "c", NULL }; * GVariant *new_variant; * * new_variant = g_variant_new ("(t^as)", * /* This cast is required. */ * (guint64) some_flags, * some_strings); * ]| * * Returns: a new floating #GVariant instance * Since: 2.24 */ /** * g_variant_new_array: * @child_type: (allow-none): the element type of the new array * @children: (allow-none) (array length=n_children): an array of * #GVariant pointers, the children * @n_children: the length of @children * * Creates a new #GVariant array from @children. * * @child_type must be non-%NULL if @n_children is zero. Otherwise, the * child type is determined by inspecting the first element of the * @children array. If @child_type is non-%NULL then it must be a * definite type. * * The items of the array are taken from the @children array. No entry * in the @children array may be %NULL. * * All items in the array must have the same type, which must be the * same as @child_type, if given. * * If the @children are floating references (see g_variant_ref_sink()), the * new instance takes ownership of them as if via g_variant_ref_sink(). * * Returns: (transfer none): a floating reference to a new #GVariant array * Since: 2.24 */ /** * g_variant_new_boolean: * @value: a #gboolean value * * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. * * Returns: (transfer none): a floating reference to a new boolean #GVariant instance * Since: 2.24 */ /** * g_variant_new_byte: * @value: a #guint8 value * * Creates a new byte #GVariant instance. * * Returns: (transfer none): a floating reference to a new byte #GVariant instance * Since: 2.24 */ /** * g_variant_new_bytestring: * @string: (array zero-terminated=1) (element-type guint8): a normal * nul-terminated string in no particular encoding * * Creates an array-of-bytes #GVariant with the contents of @string. * This function is just like g_variant_new_string() except that the * string need not be valid utf8. * * The nul terminator character at the end of the string is stored in * the array. * * Returns: (transfer none): a floating reference to a new bytestring #GVariant instance * Since: 2.26 */ /** * g_variant_new_bytestring_array: * @strv: (array length=length): an array of strings * @length: the length of @strv, or -1 * * Constructs an array of bytestring #GVariant from the given array of * strings. * * If @length is -1 then @strv is %NULL-terminated. * * Returns: (transfer none): a new floating #GVariant instance * Since: 2.26 */ /** * g_variant_new_dict_entry: (constructor) * @key: a basic #GVariant, the key * @value: a #GVariant, the value * * Creates a new dictionary entry #GVariant. @key and @value must be * non-%NULL. @key must be a value of a basic type (ie: not a container). * * If the @key or @value are floating references (see g_variant_ref_sink()), * the new instance takes ownership of them as if via g_variant_ref_sink(). * * Returns: (transfer none): a floating reference to a new dictionary entry #GVariant * Since: 2.24 */ /** * g_variant_new_double: * @value: a #gdouble floating point value * * Creates a new double #GVariant instance. * * Returns: (transfer none): a floating reference to a new double #GVariant instance * Since: 2.24 */ /** * g_variant_new_fixed_array: * @element_type: the #GVariantType of each element * @elements: a pointer to the fixed array of contiguous elements * @n_elements: the number of elements * @element_size: the size of each element * * Provides access to the serialised data for an array of fixed-sized * items. * * @value must be an array with fixed-sized elements. Numeric types are * fixed-size as are tuples containing only other fixed-sized types. * * @element_size must be the size of a single element in the array. * For example, if calling this function for an array of 32-bit integers, * you might say sizeof(gint32). This value isn't used except for the purpose * of a double-check that the form of the serialised data matches the caller's * expectation. * * @n_elements, which must be non-%NULL is set equal to the number of * items in the array. * * Returns: (transfer none): a floating reference to a new array #GVariant instance * Since: 2.32 */ /** * g_variant_new_from_bytes: * @type: a #GVariantType * @bytes: a #GBytes * @trusted: if the contents of @bytes are trusted * * Constructs a new serialised-mode #GVariant instance. This is the * inner interface for creation of new serialised values that gets * called from various functions in gvariant.c. * * A reference is taken on @bytes. * * Returns: (transfer none): a new #GVariant with a floating reference * Since: 2.36 */ /** * g_variant_new_from_data: * @type: a definite #GVariantType * @data: (array length=size) (element-type guint8): the serialised data * @size: the size of @data * @trusted: %TRUE if @data is definitely in normal form * @notify: (scope async): function to call when @data is no longer needed * @user_data: data for @notify * * Creates a new #GVariant instance from serialised data. * * @type is the type of #GVariant instance that will be constructed. * The interpretation of @data depends on knowing the type. * * @data is not modified by this function and must remain valid with an * unchanging value until such a time as @notify is called with * @user_data. If the contents of @data change before that time then * the result is undefined. * * If @data is trusted to be serialised data in normal form then * @trusted should be %TRUE. This applies to serialised data created * within this process or read from a trusted location on the disk (such * as a file installed in /usr/lib alongside your application). You * should set trusted to %FALSE if @data is read from the network, a * file in the user's home directory, etc. * * If @data was not stored in this machine's native endianness, any multi-byte * numeric values in the returned variant will also be in non-native * endianness. g_variant_byteswap() can be used to recover the original values. * * @notify will be called with @user_data when @data is no longer * needed. The exact time of this call is unspecified and might even be * before this function returns. * * Returns: (transfer none): a new floating #GVariant of type @type * Since: 2.24 */ /** * g_variant_new_handle: * @value: a #gint32 value * * Creates a new handle #GVariant instance. * * By convention, handles are indexes into an array of file descriptors * that are sent alongside a D-Bus message. If you're not interacting * with D-Bus, you probably don't need them. * * Returns: (transfer none): a floating reference to a new handle #GVariant instance * Since: 2.24 */ /** * g_variant_new_int16: * @value: a #gint16 value * * Creates a new int16 #GVariant instance. * * Returns: (transfer none): a floating reference to a new int16 #GVariant instance * Since: 2.24 */ /** * g_variant_new_int32: * @value: a #gint32 value * * Creates a new int32 #GVariant instance. * * Returns: (transfer none): a floating reference to a new int32 #GVariant instance * Since: 2.24 */ /** * g_variant_new_int64: * @value: a #gint64 value * * Creates a new int64 #GVariant instance. * * Returns: (transfer none): a floating reference to a new int64 #GVariant instance * Since: 2.24 */ /** * g_variant_new_maybe: * @child_type: (allow-none): the #GVariantType of the child, or %NULL * @child: (allow-none): the child value, or %NULL * * Depending on if @child is %NULL, either wraps @child inside of a * maybe container or creates a Nothing instance for the given @type. * * At least one of @child_type and @child must be non-%NULL. * If @child_type is non-%NULL then it must be a definite type. * If they are both non-%NULL then @child_type must be the type * of @child. * * If @child is a floating reference (see g_variant_ref_sink()), the new * instance takes ownership of @child. * * Returns: (transfer none): a floating reference to a new #GVariant maybe instance * Since: 2.24 */ /** * g_variant_new_object_path: * @object_path: a normal C nul-terminated string * * Creates a D-Bus object path #GVariant with the contents of @string. * @string must be a valid D-Bus object path. Use * g_variant_is_object_path() if you're not sure. * * Returns: (transfer none): a floating reference to a new object path #GVariant instance * Since: 2.24 */ /** * g_variant_new_objv: * @strv: (array length=length) (element-type utf8): an array of strings * @length: the length of @strv, or -1 * * Constructs an array of object paths #GVariant from the given array of * strings. * * Each string must be a valid #GVariant object path; see * g_variant_is_object_path(). * * If @length is -1 then @strv is %NULL-terminated. * * Returns: (transfer none): a new floating #GVariant instance * Since: 2.30 */ /** * g_variant_new_parsed: * @format: a text format #GVariant * @...: arguments as per @format * * Parses @format and returns the result. * * @format must be a text format #GVariant with one extension: at any * point that a value may appear in the text, a '%' character followed * by a GVariant format string (as per g_variant_new()) may appear. In * that case, the same arguments are collected from the argument list as * g_variant_new() would have collected. * * Note that the arguments must be of the correct width for their types * specified in @format. This can be achieved by casting them. See * the [GVariant varargs documentation][gvariant-varargs]. * * Consider this simple example: * |[ * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); * ]| * * In the example, the variable argument parameters are collected and * filled in as if they were part of the original string to produce the * result of * |[ * [('one', 1), ('two', 2), ('three', 3)] * ]| * * This function is intended only to be used with @format as a string * literal. Any parse error is fatal to the calling process. If you * want to parse data from untrusted sources, use g_variant_parse(). * * You may not use this function to return, unmodified, a single * #GVariant pointer from the argument list. ie: @format may not solely * be anything along the lines of "%*", "%?", "\%r", or anything starting * with "%@". * * Returns: a new floating #GVariant instance */ /** * g_variant_new_parsed_va: * @format: a text format #GVariant * @app: a pointer to a #va_list * * Parses @format and returns the result. * * This is the version of g_variant_new_parsed() intended to be used * from libraries. * * The return value will be floating if it was a newly created GVariant * instance. In the case that @format simply specified the collection * of a #GVariant pointer (eg: @format was "%*") then the collected * #GVariant pointer will be returned unmodified, without adding any * additional references. * * Note that the arguments in @app must be of the correct width for their types * specified in @format when collected into the #va_list. See * the [GVariant varargs documentation][gvariant-varargs]. * * In order to behave correctly in all cases it is necessary for the * calling function to g_variant_ref_sink() the return result before * returning control to the user that originally provided the pointer. * At this point, the caller will have their own full reference to the * result. This can also be done by adding the result to a container, * or by passing it to another g_variant_new() call. * * Returns: a new, usually floating, #GVariant */ /** * g_variant_new_printf: (skip) * @format_string: a printf-style format string * @...: arguments for @format_string * * Creates a string-type GVariant using printf formatting. * * This is similar to calling g_strdup_printf() and then * g_variant_new_string() but it saves a temporary variable and an * unnecessary copy. * * Returns: (transfer none): a floating reference to a new string * #GVariant instance * Since: 2.38 */ /** * g_variant_new_signature: * @signature: a normal C nul-terminated string * * Creates a D-Bus type signature #GVariant with the contents of * @string. @string must be a valid D-Bus type signature. Use * g_variant_is_signature() if you're not sure. * * Returns: (transfer none): a floating reference to a new signature #GVariant instance * Since: 2.24 */ /** * g_variant_new_string: * @string: a normal utf8 nul-terminated string * * Creates a string #GVariant with the contents of @string. * * @string must be valid utf8. * * Returns: (transfer none): a floating reference to a new string #GVariant instance * Since: 2.24 */ /** * g_variant_new_strv: * @strv: (array length=length) (element-type utf8): an array of strings * @length: the length of @strv, or -1 * * Constructs an array of strings #GVariant from the given array of * strings. * * If @length is -1 then @strv is %NULL-terminated. * * Returns: (transfer none): a new floating #GVariant instance * Since: 2.24 */ /** * g_variant_new_take_string: (skip) * @string: a normal utf8 nul-terminated string * * Creates a string #GVariant with the contents of @string. * * @string must be valid utf8. * * This function consumes @string. g_free() will be called on @string * when it is no longer required. * * You must not modify or access @string in any other way after passing * it to this function. It is even possible that @string is immediately * freed. * * Returns: (transfer none): a floating reference to a new string * #GVariant instance * Since: 2.38 */ /** * g_variant_new_tuple: * @children: (array length=n_children): the items to make the tuple out of * @n_children: the length of @children * * Creates a new tuple #GVariant out of the items in @children. The * type is determined from the types of @children. No entry in the * @children array may be %NULL. * * If @n_children is 0 then the unit tuple is constructed. * * If the @children are floating references (see g_variant_ref_sink()), the * new instance takes ownership of them as if via g_variant_ref_sink(). * * Returns: (transfer none): a floating reference to a new #GVariant tuple * Since: 2.24 */ /** * g_variant_new_uint16: * @value: a #guint16 value * * Creates a new uint16 #GVariant instance. * * Returns: (transfer none): a floating reference to a new uint16 #GVariant instance * Since: 2.24 */ /** * g_variant_new_uint32: * @value: a #guint32 value * * Creates a new uint32 #GVariant instance. * * Returns: (transfer none): a floating reference to a new uint32 #GVariant instance * Since: 2.24 */ /** * g_variant_new_uint64: * @value: a #guint64 value * * Creates a new uint64 #GVariant instance. * * Returns: (transfer none): a floating reference to a new uint64 #GVariant instance * Since: 2.24 */ /** * g_variant_new_va: (skip) * @format_string: a string that is prefixed with a format string * @endptr: (allow-none) (default NULL): location to store the end pointer, * or %NULL * @app: a pointer to a #va_list * * This function is intended to be used by libraries based on * #GVariant that want to provide g_variant_new()-like functionality * to their users. * * The API is more general than g_variant_new() to allow a wider range * of possible uses. * * @format_string must still point to a valid format string, but it only * needs to be nul-terminated if @endptr is %NULL. If @endptr is * non-%NULL then it is updated to point to the first character past the * end of the format string. * * @app is a pointer to a #va_list. The arguments, according to * @format_string, are collected from this #va_list and the list is left * pointing to the argument following the last. * * Note that the arguments in @app must be of the correct width for their * types specified in @format_string when collected into the #va_list. * See the [GVariant varargs documentation][gvariant-varargs. * * These two generalisations allow mixing of multiple calls to * g_variant_new_va() and g_variant_get_va() within a single actual * varargs call by the user. * * The return value will be floating if it was a newly created GVariant * instance (for example, if the format string was "(ii)"). In the case * that the format_string was '*', '?', 'r', or a format starting with * '@' then the collected #GVariant pointer will be returned unmodified, * without adding any additional references. * * In order to behave correctly in all cases it is necessary for the * calling function to g_variant_ref_sink() the return result before * returning control to the user that originally provided the pointer. * At this point, the caller will have their own full reference to the * result. This can also be done by adding the result to a container, * or by passing it to another g_variant_new() call. * * Returns: a new, usually floating, #GVariant * Since: 2.24 */ /** * g_variant_new_variant: (constructor) * @value: a #GVariant instance * * Boxes @value. The result is a #GVariant instance representing a * variant containing the original value. * * If @child is a floating reference (see g_variant_ref_sink()), the new * instance takes ownership of @child. * * Returns: (transfer none): a floating reference to a new variant #GVariant instance * Since: 2.24 */ /** * g_variant_parse: * @type: (allow-none): a #GVariantType, or %NULL * @text: a string containing a GVariant in text form * @limit: (allow-none): a pointer to the end of @text, or %NULL * @endptr: (allow-none): a location to store the end pointer, or %NULL * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL * * Parses a #GVariant from a text representation. * * A single #GVariant is parsed from the content of @text. * * The format is described [here][gvariant-text]. * * The memory at @limit will never be accessed and the parser behaves as * if the character at @limit is the nul terminator. This has the * effect of bounding @text. * * If @endptr is non-%NULL then @text is permitted to contain data * following the value that this function parses and @endptr will be * updated to point to the first character past the end of the text * parsed by this function. If @endptr is %NULL and there is extra data * then an error is returned. * * If @type is non-%NULL then the value will be parsed to have that * type. This may result in additional parse errors (in the case that * the parsed value doesn't fit the type) but may also result in fewer * errors (in the case that the type would have been ambiguous, such as * with empty arrays). * * In the event that the parsing is successful, the resulting #GVariant * is returned. * * In case of any error, %NULL will be returned. If @error is non-%NULL * then it will be set to reflect the error that occurred. * * Officially, the language understood by the parser is "any string * produced by g_variant_print()". * * Returns: a reference to a #GVariant, or %NULL */ /** * g_variant_parse_error_print_context: * @error: a #GError from the #GVariantParseError domain * @source_str: the string that was given to the parser * * Pretty-prints a message showing the context of a #GVariant parse * error within the string for which parsing was attempted. * * The resulting string is suitable for output to the console or other * monospace media where newlines are treated in the usual way. * * The message will typically look something like one of the following: * * |[ * unterminated string constant: * (1, 2, 3, 'abc * ^^^^ * ]| * * or * * |[ * unable to find a common type: * [1, 2, 3, 'str'] * ^ ^^^^^ * ]| * * The format of the message may change in a future version. * * @error must have come from a failed attempt to g_variant_parse() and * @source_str must be exactly the same string that caused the error. * If @source_str was not nul-terminated when you passed it to * g_variant_parse() then you must add nul termination before using this * function. * * Returns: (transfer full): the printed message * Since: 2.40 */ /** * g_variant_parser_get_error_quark: * * Same as g_variant_error_quark(). * * Deprecated: Use g_variant_parse_error_quark() instead. */ /** * g_variant_print: * @value: a #GVariant * @type_annotate: %TRUE if type information should be included in * the output * * Pretty-prints @value in the format understood by g_variant_parse(). * * The format is described [here][gvariant-text]. * * If @type_annotate is %TRUE, then type information is included in * the output. * * Returns: (transfer full): a newly-allocated string holding the result. * Since: 2.24 */ /** * g_variant_print_string: (skip) * @value: a #GVariant * @string: (allow-none) (default NULL): a #GString, or %NULL * @type_annotate: %TRUE if type information should be included in * the output * * Behaves as g_variant_print(), but operates on a #GString. * * If @string is non-%NULL then it is appended to and returned. Else, * a new empty #GString is allocated and it is returned. * * Returns: a #GString containing the string * Since: 2.24 */ /** * g_variant_ref: * @value: a #GVariant * * Increases the reference count of @value. * * Returns: the same @value * Since: 2.24 */ /** * g_variant_ref_sink: * @value: a #GVariant * * #GVariant uses a floating reference count system. All functions with * names starting with `g_variant_new_` return floating * references. * * Calling g_variant_ref_sink() on a #GVariant with a floating reference * will convert the floating reference into a full reference. Calling * g_variant_ref_sink() on a non-floating #GVariant results in an * additional normal reference being added. * * In other words, if the @value is floating, then this call "assumes * ownership" of the floating reference, converting it to a normal * reference. If the @value is not floating, then this call adds a * new normal reference increasing the reference count by one. * * All calls that result in a #GVariant instance being inserted into a * container will call g_variant_ref_sink() on the instance. This means * that if the value was just created (and has only its floating * reference) then the container will assume sole ownership of the value * at that point and the caller will not need to unreference it. This * makes certain common styles of programming much easier while still * maintaining normal refcounting semantics in situations where values * are not floating. * * Returns: the same @value * Since: 2.24 */ /** * g_variant_store: * @value: the #GVariant to store * @data: the location to store the serialised data at * * Stores the serialised form of @value at @data. @data should be * large enough. See g_variant_get_size(). * * The stored data is in machine native byte order but may not be in * fully-normalised form if read from an untrusted source. See * g_variant_get_normal_form() for a solution. * * As with g_variant_get_data(), to be able to deserialise the * serialised variant successfully, its type and (if the destination * machine might be different) its endianness must also be available. * * This function is approximately O(n) in the size of @data. * * Since: 2.24 */ /** * g_variant_take_ref: * @value: a #GVariant * * If @value is floating, sink it. Otherwise, do nothing. * * Typically you want to use g_variant_ref_sink() in order to * automatically do the correct thing with respect to floating or * non-floating references, but there is one specific scenario where * this function is helpful. * * The situation where this function is helpful is when creating an API * that allows the user to provide a callback function that returns a * #GVariant. We certainly want to allow the user the flexibility to * return a non-floating reference from this callback (for the case * where the value that is being returned already exists). * * At the same time, the style of the #GVariant API makes it likely that * for newly-created #GVariant instances, the user can be saved some * typing if they are allowed to return a #GVariant with a floating * reference. * * Using this function on the return value of the user's callback allows * the user to do whichever is more convenient for them. The caller * will alway receives exactly one full reference to the value: either * the one that was returned in the first place, or a floating reference * that has been converted to a full reference. * * This function has an odd interaction when combined with * g_variant_ref_sink() running at the same time in another thread on * the same #GVariant instance. If g_variant_ref_sink() runs first then * the result will be that the floating reference is converted to a hard * reference. If g_variant_take_ref() runs first then the result will * be that the floating reference is converted to a hard reference and * an additional reference on top of that one is added. It is best to * avoid this situation. * * Returns: the same @value */ /** * g_variant_type_copy: * @type: a #GVariantType * * Makes a copy of a #GVariantType. It is appropriate to call * g_variant_type_free() on the return value. @type may not be %NULL. * * Returns: (transfer full): a new #GVariantType * * Since 2.24 */ /** * g_variant_type_dup_string: * @type: a #GVariantType * * Returns a newly-allocated copy of the type string corresponding to * @type. The returned string is nul-terminated. It is appropriate to * call g_free() on the return value. * * Returns: (transfer full): the corresponding type string * * Since 2.24 */ /** * g_variant_type_element: * @type: an array or maybe #GVariantType * * Determines the element type of an array or maybe type. * * This function may only be used with array or maybe types. * * Returns: (transfer none): the element type of @type * * Since 2.24 */ /** * g_variant_type_equal: * @type1: (type GVariantType): a #GVariantType * @type2: (type GVariantType): a #GVariantType * * Compares @type1 and @type2 for equality. * * Only returns %TRUE if the types are exactly equal. Even if one type * is an indefinite type and the other is a subtype of it, %FALSE will * be returned if they are not exactly equal. If you want to check for * subtypes, use g_variant_type_is_subtype_of(). * * The argument types of @type1 and @type2 are only #gconstpointer to * allow use with #GHashTable without function pointer casting. For * both arguments, a valid #GVariantType must be provided. * * Returns: %TRUE if @type1 and @type2 are exactly equal * * Since 2.24 */ /** * g_variant_type_first: * @type: a tuple or dictionary entry #GVariantType * * Determines the first item type of a tuple or dictionary entry * type. * * This function may only be used with tuple or dictionary entry types, * but must not be used with the generic tuple type * %G_VARIANT_TYPE_TUPLE. * * In the case of a dictionary entry type, this returns the type of * the key. * * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT. * * This call, together with g_variant_type_next() provides an iterator * interface over tuple and dictionary entry types. * * Returns: (transfer none): the first item type of @type, or %NULL * * Since 2.24 */ /** * g_variant_type_free: * @type: (allow-none): a #GVariantType, or %NULL * * Frees a #GVariantType that was allocated with * g_variant_type_copy(), g_variant_type_new() or one of the container * type constructor functions. * * In the case that @type is %NULL, this function does nothing. * * Since 2.24 */ /** * g_variant_type_get_string_length: * @type: a #GVariantType * * Returns the length of the type string corresponding to the given * @type. This function must be used to determine the valid extent of * the memory region returned by g_variant_type_peek_string(). * * Returns: the length of the corresponding type string * * Since 2.24 */ /** * g_variant_type_hash: * @type: (type GVariantType): a #GVariantType * * Hashes @type. * * The argument type of @type is only #gconstpointer to allow use with * #GHashTable without function pointer casting. A valid * #GVariantType must be provided. * * Returns: the hash value * * Since 2.24 */ /** * g_variant_type_is_array: * @type: a #GVariantType * * Determines if the given @type is an array type. This is true if the * type string for @type starts with an 'a'. * * This function returns %TRUE for any indefinite type for which every * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for * example. * * Returns: %TRUE if @type is an array type * * Since 2.24 */ /** * g_variant_type_is_basic: * @type: a #GVariantType * * Determines if the given @type is a basic type. * * Basic types are booleans, bytes, integers, doubles, strings, object * paths and signatures. * * Only a basic type may be used as the key of a dictionary entry. * * This function returns %FALSE for all indefinite types except * %G_VARIANT_TYPE_BASIC. * * Returns: %TRUE if @type is a basic type * * Since 2.24 */ /** * g_variant_type_is_container: * @type: a #GVariantType * * Determines if the given @type is a container type. * * Container types are any array, maybe, tuple, or dictionary * entry types plus the variant type. * * This function returns %TRUE for any indefinite type for which every * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for * example. * * Returns: %TRUE if @type is a container type * * Since 2.24 */ /** * g_variant_type_is_definite: * @type: a #GVariantType * * Determines if the given @type is definite (ie: not indefinite). * * A type is definite if its type string does not contain any indefinite * type characters ('*', '?', or 'r'). * * A #GVariant instance may not have an indefinite type, so calling * this function on the result of g_variant_get_type() will always * result in %TRUE being returned. Calling this function on an * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in * %FALSE being returned. * * Returns: %TRUE if @type is definite * * Since 2.24 */ /** * g_variant_type_is_dict_entry: * @type: a #GVariantType * * Determines if the given @type is a dictionary entry type. This is * true if the type string for @type starts with a '{'. * * This function returns %TRUE for any indefinite type for which every * definite subtype is a dictionary entry type -- * %G_VARIANT_TYPE_DICT_ENTRY, for example. * * Returns: %TRUE if @type is a dictionary entry type * * Since 2.24 */ /** * g_variant_type_is_maybe: * @type: a #GVariantType * * Determines if the given @type is a maybe type. This is true if the * type string for @type starts with an 'm'. * * This function returns %TRUE for any indefinite type for which every * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for * example. * * Returns: %TRUE if @type is a maybe type * * Since 2.24 */ /** * g_variant_type_is_subtype_of: * @type: a #GVariantType * @supertype: a #GVariantType * * Checks if @type is a subtype of @supertype. * * This function returns %TRUE if @type is a subtype of @supertype. All * types are considered to be subtypes of themselves. Aside from that, * only indefinite types can have subtypes. * * Returns: %TRUE if @type is a subtype of @supertype * * Since 2.24 */ /** * g_variant_type_is_tuple: * @type: a #GVariantType * * Determines if the given @type is a tuple type. This is true if the * type string for @type starts with a '(' or if @type is * %G_VARIANT_TYPE_TUPLE. * * This function returns %TRUE for any indefinite type for which every * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for * example. * * Returns: %TRUE if @type is a tuple type * * Since 2.24 */ /** * g_variant_type_is_variant: * @type: a #GVariantType * * Determines if the given @type is the variant type. * * Returns: %TRUE if @type is the variant type * * Since 2.24 */ /** * g_variant_type_key: * @type: a dictionary entry #GVariantType * * Determines the key type of a dictionary entry type. * * This function may only be used with a dictionary entry type. Other * than the additional restriction, this call is equivalent to * g_variant_type_first(). * * Returns: (transfer none): the key type of the dictionary entry * * Since 2.24 */ /** * g_variant_type_n_items: * @type: a tuple or dictionary entry #GVariantType * * Determines the number of items contained in a tuple or * dictionary entry type. * * This function may only be used with tuple or dictionary entry types, * but must not be used with the generic tuple type * %G_VARIANT_TYPE_TUPLE. * * In the case of a dictionary entry type, this function will always * return 2. * * Returns: the number of items in @type * * Since 2.24 */ /** * g_variant_type_new: * @type_string: a valid GVariant type string * * Creates a new #GVariantType corresponding to the type string given * by @type_string. It is appropriate to call g_variant_type_free() on * the return value. * * It is a programmer error to call this function with an invalid type * string. Use g_variant_type_string_is_valid() if you are unsure. * * Returns: (transfer full): a new #GVariantType * Since: 2.24 */ /** * g_variant_type_new_array: (constructor) * @element: a #GVariantType * * Constructs the type corresponding to an array of elements of the * type @type. * * It is appropriate to call g_variant_type_free() on the return value. * * Returns: (transfer full): a new array #GVariantType * * Since 2.24 */ /** * g_variant_type_new_dict_entry: (constructor) * @key: a basic #GVariantType * @value: a #GVariantType * * Constructs the type corresponding to a dictionary entry with a key * of type @key and a value of type @value. * * It is appropriate to call g_variant_type_free() on the return value. * * Returns: (transfer full): a new dictionary entry #GVariantType * * Since 2.24 */ /** * g_variant_type_new_maybe: (constructor) * @element: a #GVariantType * * Constructs the type corresponding to a maybe instance containing * type @type or Nothing. * * It is appropriate to call g_variant_type_free() on the return value. * * Returns: (transfer full): a new maybe #GVariantType * * Since 2.24 */ /** * g_variant_type_new_tuple: * @items: (array length=length): an array of #GVariantTypes, one for each item * @length: the length of @items, or -1 * * Constructs a new tuple type, from @items. * * @length is the number of items in @items, or -1 to indicate that * @items is %NULL-terminated. * * It is appropriate to call g_variant_type_free() on the return value. * * Returns: (transfer full): a new tuple #GVariantType * * Since 2.24 */ /** * g_variant_type_next: * @type: a #GVariantType from a previous call * * Determines the next item type of a tuple or dictionary entry * type. * * @type must be the result of a previous call to * g_variant_type_first() or g_variant_type_next(). * * If called on the key type of a dictionary entry then this call * returns the value type. If called on the value type of a dictionary * entry then this call returns %NULL. * * For tuples, %NULL is returned when @type is the last item in a tuple. * * Returns: (transfer none): the next #GVariantType after @type, or %NULL * * Since 2.24 */ /** * g_variant_type_peek_string: (skip) * @type: a #GVariantType * * Returns the type string corresponding to the given @type. The * result is not nul-terminated; in order to determine its length you * must call g_variant_type_get_string_length(). * * To get a nul-terminated string, see g_variant_type_dup_string(). * * Returns: the corresponding type string (not nul-terminated) * * Since 2.24 */ /** * g_variant_type_string_is_valid: * @type_string: a pointer to any string * * Checks if @type_string is a valid GVariant type string. This call is * equivalent to calling g_variant_type_string_scan() and confirming * that the following character is a nul terminator. * * Returns: %TRUE if @type_string is exactly one valid type string * * Since 2.24 */ /** * g_variant_type_string_scan: * @string: a pointer to any string * @limit: (allow-none): the end of @string, or %NULL * @endptr: (out) (allow-none): location to store the end pointer, or %NULL * * Scan for a single complete and valid GVariant type string in @string. * The memory pointed to by @limit (or bytes beyond it) is never * accessed. * * If a valid type string is found, @endptr is updated to point to the * first character past the end of the string that was found and %TRUE * is returned. * * If there is no valid type string starting at @string, or if the type * string does not end before @limit then %FALSE is returned. * * For the simple case of checking if a string is a valid type string, * see g_variant_type_string_is_valid(). * * Returns: %TRUE if a valid type string was found * Since: 2.24 */ /** * g_variant_type_value: * @type: a dictionary entry #GVariantType * * Determines the value type of a dictionary entry type. * * This function may only be used with a dictionary entry type. * * Returns: (transfer none): the value type of the dictionary entry * * Since 2.24 */ /** * g_variant_unref: * @value: a #GVariant * * Decreases the reference count of @value. When its reference count * drops to 0, the memory used by the variant is freed. * * Since: 2.24 */ /** * g_vasprintf: * @string: the return location for the newly-allocated string. * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the GNU vasprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * This function is similar to g_vsprintf(), except that it allocates a * string to hold the output, instead of putting the output in a buffer * you allocate in advance. * * Returns: the number of bytes printed. * Since: 2.4 */ /** * g_vfprintf: * @file: the stream to write to. * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard fprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * * Returns: the number of bytes printed. * Since: 2.2 */ /** * g_vprintf: * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard vprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * * Returns: the number of bytes printed. * Since: 2.2 */ /** * g_vsnprintf: * @string: the buffer to hold the output. * @n: the maximum number of bytes to produce (including the * terminating nul character). * @format: a standard printf() format string, but notice * string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * A safer form of the standard vsprintf() function. The output is guaranteed * to not exceed @n characters (including the terminating nul character), so * it is easy to ensure that a buffer overflow cannot occur. * * See also g_strdup_vprintf(). * * In versions of GLib prior to 1.2.3, this function may return -1 if the * output was truncated, and the truncated string may not be nul-terminated. * In versions prior to 1.3.12, this function returns the length of the output * string. * * The return value of g_vsnprintf() conforms to the vsnprintf() function * as standardized in ISO C99. Note that this is different from traditional * vsnprintf(), which returns the length of the output string. * * The format string may contain positional parameters, as specified in * the Single Unix Specification. * * Returns: the number of bytes which would be produced if the buffer * was large enough. */ /** * g_vsprintf: * @string: the buffer to hold the output. * @format: a standard printf() format string, but notice * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard vsprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * * Returns: the number of bytes printed. * Since: 2.2 */ /** * g_wakeup_acknowledge: * @wakeup: a #GWakeup * * Acknowledges receipt of a wakeup signal on @wakeup. * * You must call this after @wakeup polls as ready. If not, it will * continue to poll as ready until you do so. * * If you call this function and @wakeup is not signaled, nothing * happens. * * Since: 2.30 */ /** * g_wakeup_free: * @wakeup: a #GWakeup * * Frees @wakeup. * * You must not currently be polling on the #GPollFD returned by * g_wakeup_get_pollfd(), or the result is undefined. */ /** * g_wakeup_get_pollfd: * @wakeup: a #GWakeup * @poll_fd: a #GPollFD * * Prepares a @poll_fd such that polling on it will succeed when * g_wakeup_signal() has been called on @wakeup. * * @poll_fd is valid until @wakeup is freed. * * Since: 2.30 */ /** * g_wakeup_new: * * Creates a new #GWakeup. * * You should use g_wakeup_free() to free it when you are done. * * Returns: a new #GWakeup * Since: 2.30 */ /** * g_wakeup_signal: * @wakeup: a #GWakeup * * Signals @wakeup. * * Any future (or present) polling on the #GPollFD returned by * g_wakeup_get_pollfd() will immediately succeed until such a time as * g_wakeup_acknowledge() is called. * * This function is safe to call from a UNIX signal handler. * * Since: 2.30 */ /** * g_warning: * @...: format string, followed by parameters to insert * into the format string (as with printf()) * * A convenience function/macro to log a warning message. * * You can make warnings fatal at runtime by setting the `G_DEBUG` * environment variable (see * [Running GLib Applications](glib-running.html)). * * If g_log_default_handler() is used as the log handler function, * a newline character will automatically be appended to @..., and * need not be entered manually. */ /** * g_win32_error_message: * @error: error code. * * Translate a Win32 error code (as returned by GetLastError() or * WSAGetLastError()) into the corresponding message. The message is * either language neutral, or in the thread's language, or the user's * language, the system's language, or US English (see docs for * FormatMessage()). The returned string is in UTF-8. It should be * deallocated with g_free(). * * Returns: newly-allocated error message */ /** * g_win32_get_command_line: * * Gets the command line arguments, on Windows, in the GLib filename * encoding (ie: UTF-8). * * Normally, on Windows, the command line arguments are passed to main() * in the system codepage encoding. This prevents passing filenames as * arguments if the filenames contain characters that fall outside of * this codepage. If such filenames are passed, then substitutions * will occur (such as replacing some characters with '?'). * * GLib's policy of using UTF-8 as a filename encoding on Windows was * designed to localise the pain of dealing with filenames outside of * the system codepage to one area: dealing with commandline arguments * in main(). * * As such, most GLib programs should ignore the value of argv passed to * their main() function and call g_win32_get_command_line() instead. * This will get the "full Unicode" commandline arguments using * GetCommandLineW() and convert it to the GLib filename encoding (which * is UTF-8 on Windows). * * The strings returned by this function are suitable for use with * functions such as g_open() and g_file_new_for_commandline_arg() but * are not suitable for use with g_option_context_parse(), which assumes * that its input will be in the system codepage. The return value is * suitable for use with g_option_context_parse_strv(), however, which * is a better match anyway because it won't leak memory. * * Unlike argv, the returned value is a normal strv and can (and should) * be freed with g_strfreev() when no longer needed. * * Returns: (transfer full): the commandline arguments in the GLib * filename encoding (ie: UTF-8) * Since: 2.40 */ /** * g_win32_get_package_installation_directory: * @package: (allow-none): You should pass %NULL for this. * @dll_name: (allow-none): The name of a DLL that a package provides in UTF-8, or %NULL. * * Try to determine the installation directory for a software package. * * This function is deprecated. Use * g_win32_get_package_installation_directory_of_module() instead. * * The use of @package is deprecated. You should always pass %NULL. A * warning is printed if non-NULL is passed as @package. * * The original intended use of @package was for a short identifier of * the package, typically the same identifier as used for * `GETTEXT_PACKAGE` in software configured using GNU * autotools. The function first looks in the Windows Registry for the * value `#InstallationDirectory` in the key * `#HKLM\Software\@package`, and if that value * exists and is a string, returns that. * * It is strongly recommended that packagers of GLib-using libraries * for Windows do not store installation paths in the Registry to be * used by this function as that interfers with having several * parallel installations of the library. Enabling multiple * installations of different versions of some GLib-using library, or * GLib itself, is desirable for various reasons. * * For this reason it is recommeded to always pass %NULL as * @package to this function, to avoid the temptation to use the * Registry. In version 2.20 of GLib the @package parameter * will be ignored and this function won't look in the Registry at all. * * If @package is %NULL, or the above value isn't found in the * Registry, but @dll_name is non-%NULL, it should name a DLL loaded * into the current process. Typically that would be the name of the * DLL calling this function, looking for its installation * directory. The function then asks Windows what directory that DLL * was loaded from. If that directory's last component is "bin" or * "lib", the parent directory is returned, otherwise the directory * itself. If that DLL isn't loaded, the function proceeds as if * @dll_name was %NULL. * * If both @package and @dll_name are %NULL, the directory from where * the main executable of the process was loaded is used instead in * the same way as above. * * Returns: a string containing the installation directory for * @package. The string is in the GLib file name encoding, * i.e. UTF-8. The return value should be freed with g_free() when not * needed any longer. If the function fails %NULL is returned. * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to * g_win32_get_package_installation_directory_of_module() instead. */ /** * g_win32_get_package_installation_directory_of_module: * @hmodule: (allow-none): The Win32 handle for a DLL loaded into the current process, or %NULL * * This function tries to determine the installation directory of a * software package based on the location of a DLL of the software * package. * * @hmodule should be the handle of a loaded DLL or %NULL. The * function looks up the directory that DLL was loaded from. If * @hmodule is NULL, the directory the main executable of the current * process is looked up. If that directory's last component is "bin" * or "lib", its parent directory is returned, otherwise the directory * itself. * * It thus makes sense to pass only the handle to a "public" DLL of a * software package to this function, as such DLLs typically are known * to be installed in a "bin" or occasionally "lib" subfolder of the * installation folder. DLLs that are of the dynamically loaded module * or plugin variety are often located in more private locations * deeper down in the tree, from which it is impossible for GLib to * deduce the root of the package installation. * * The typical use case for this function is to have a DllMain() that * saves the handle for the DLL. Then when code in the DLL needs to * construct names of files in the installation tree it calls this * function passing the DLL handle. * * Returns: a string containing the guessed installation directory for * the software package @hmodule is from. The string is in the GLib * file name encoding, i.e. UTF-8. The return value should be freed * with g_free() when not needed any longer. If the function fails * %NULL is returned. * Since: 2.16 */ /** * g_win32_get_package_installation_subdirectory: * @package: (allow-none): You should pass %NULL for this. * @dll_name: (allow-none): The name of a DLL that a package provides, in UTF-8, or %NULL. * @subdir: A subdirectory of the package installation directory, also in UTF-8 * * This function is deprecated. Use * g_win32_get_package_installation_directory_of_module() and * g_build_filename() instead. * * Returns a newly-allocated string containing the path of the * subdirectory @subdir in the return value from calling * g_win32_get_package_installation_directory() with the @package and * @dll_name parameters. See the documentation for * g_win32_get_package_installation_directory() for more details. In * particular, note that it is deprecated to pass anything except NULL * as @package. * * Returns: a string containing the complete path to @subdir inside * the installation directory of @package. The returned string is in * the GLib file name encoding, i.e. UTF-8. The return value should be * freed with g_free() when no longer needed. If something goes wrong, * %NULL is returned. * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to * g_win32_get_package_installation_directory_of_module() instead, and * then construct a subdirectory pathname with g_build_filename(). */ /** * g_win32_get_windows_version: * * Returns version information for the Windows operating system the * code is running on. See MSDN documentation for the GetVersion() * function. To summarize, the most significant bit is one on Win9x, * and zero on NT-based systems. Since version 2.14, GLib works only * on NT-based systems, so checking whether your are running on Win9x * in your own software is moot. The least significant byte is 4 on * Windows NT 4, and 5 on Windows XP. Software that needs really * detailed version and feature information should use Win32 API like * GetVersionEx() and VerifyVersionInfo(). * * Returns: The version information. * Since: 2.6 */ /** * g_win32_getlocale: * * The setlocale() function in the Microsoft C library uses locale * names of the form "English_United States.1252" etc. We want the * UNIXish standard form "en_US", "zh_TW" etc. This function gets the * current thread locale from Windows - without any encoding info - * and returns it as a string of the above form for use in forming * file names etc. The returned string should be deallocated with * g_free(). * * Returns: newly-allocated locale name. */ /** * g_win32_locale_filename_from_utf8: * @utf8filename: a UTF-8 encoded filename. * * Converts a filename from UTF-8 to the system codepage. * * On NT-based Windows, on NTFS file systems, file names are in * Unicode. It is quite possible that Unicode file names contain * characters not representable in the system codepage. (For instance, * Greek or Cyrillic characters on Western European or US Windows * installations, or various less common CJK characters on CJK Windows * installations.) * * In such a case, and if the filename refers to an existing file, and * the file system stores alternate short (8.3) names for directory * entries, the short form of the filename is returned. Note that the * "short" name might in fact be longer than the Unicode name if the * Unicode name has very short pathname components containing * non-ASCII characters. If no system codepage name for the file is * possible, %NULL is returned. * * The return value is dynamically allocated and should be freed with * g_free() when no longer needed. * * Returns: The converted filename, or %NULL on conversion * failure and lack of short names. * Since: 2.8 */ /** * gboolean: * * A standard boolean type. * Variables of this type should only contain the value * %TRUE or %FALSE. */ /** * gchar: * * Corresponds to the standard C char type. */ /** * gconstpointer: * * An untyped pointer to constant data. * The data pointed to should not be changed. * * This is typically used in function prototypes to indicate * that the data pointed to will not be altered by the function. */ /** * gdouble: * * Corresponds to the standard C double type. * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE. */ /** * gfloat: * * Corresponds to the standard C float type. * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT. */ /** * gint: * * Corresponds to the standard C int type. * Values of this type can range from #G_MININT to #G_MAXINT. */ /** * gint16: * * A signed integer guaranteed to be 16 bits on all platforms. * Values of this type can range from #G_MININT16 (= -32,768) to * #G_MAXINT16 (= 32,767). * * To print or scan values of this type, use * %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT. */ /** * gint32: * * A signed integer guaranteed to be 32 bits on all platforms. * Values of this type can range from #G_MININT32 (= -2,147,483,648) * to #G_MAXINT32 (= 2,147,483,647). * * To print or scan values of this type, use * %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT. */ /** * gint64: * * A signed integer guaranteed to be 64 bits on all platforms. * Values of this type can range from #G_MININT64 * (= -9,223,372,036,854,775,808) to #G_MAXINT64 * (= 9,223,372,036,854,775,807). * * To print or scan values of this type, use * %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT. */ /** * gint8: * * A signed integer guaranteed to be 8 bits on all platforms. * Values of this type can range from #G_MININT8 (= -128) to * #G_MAXINT8 (= 127). */ /** * gintptr: * * Corresponds to the C99 type intptr_t, * a signed integer type that can hold any pointer. * * To print or scan values of this type, use * %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT. * * Since: 2.18 */ /** * glib__private__: * @arg: Do not use this argument * * Do not call this function; it is used to share private * API between glib, gobject, and gio. */ /** * glib_binary_age: * * The binary age of the GLib library. * Defines how far back backwards compatibility reaches. * * An integer variable exported from the library linked * against at application run time. */ /** * glib_check_version: * @required_major: the required major version * @required_minor: the required minor version * @required_micro: the required micro version * * Checks that the GLib library in use is compatible with the * given version. Generally you would pass in the constants * #GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION * as the three arguments to this function; that produces * a check that the library in use is compatible with * the version of GLib the application or module was compiled * against. * * Compatibility is defined by two things: first the version * of the running library is newer than the version * @required_major.required_minor.@required_micro. Second * the running library must be binary compatible with the * version @required_major.required_minor.@required_micro * (same major version.) * * Returns: %NULL if the GLib library is compatible with the * given version, or a string describing the version mismatch. * The returned string is owned by GLib and must not be modified * or freed. * Since: 2.6 */ /** * glib_gettext: * @str: The string to be translated * * Returns the translated string from the glib translations. * This is an internal function and should only be used by * the internals of glib (such as libgio). * * Returns: the transation of @str to the current locale */ /** * glib_interface_age: * * The interface age of the GLib library. * Defines how far back the API has last been extended. * * An integer variable exported from the library linked * against at application run time. */ /** * glib_major_version: * * The major version of the GLib library. * * An integer variable exported from the library linked * against at application run time. */ /** * glib_mem_profiler_table: * * A #GMemVTable containing profiling variants of the memory * allocation functions. Use them together with g_mem_profile() * in order to get information about the memory allocation pattern * of your program. */ /** * glib_micro_version: * * The micro version number of the GLib library. * * An integer variable exported from the library linked * against at application run time. */ /** * glib_minor_version: * * The minor version number of the GLib library. * * An integer variable exported from the library linked * against at application run time. */ /** * glib_pgettext: * @msgctxtid: a combined message context and message id, separated * by a \004 character * @msgidoffset: the offset of the message id in @msgctxid * * This function is a variant of glib_gettext() which supports * a disambiguating message context. See g_dpgettext() for full * details. * * This is an internal function and should only be used by * the internals of glib (such as libgio). * * Returns: the translation of @str to the current locale */ /** * glong: * * Corresponds to the standard C long type. * Values of this type can range from #G_MINLONG to #G_MAXLONG. */ /** * goffset: * * A signed integer type that is used for file offsets, * corresponding to the C99 type off64_t. * Values of this type can range from #G_MINOFFSET to * #G_MAXOFFSET. * * To print or scan values of this type, use * %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT. * * Since: 2.14 */ /** * gpointer: * * An untyped pointer. * #gpointer looks better and is easier to use than void*. */ /** * gshort: * * Corresponds to the standard C short type. * Values of this type can range from #G_MINSHORT to #G_MAXSHORT. */ /** * gsize: * * An unsigned integer type of the result of the sizeof operator, * corresponding to the size_t type defined in C99. * This type is wide enough to hold the numeric value of a pointer, * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide * on a 64-bit platform. Values of this type can range from 0 to * #G_MAXSIZE. * * To print or scan values of this type, use * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT. */ /** * gssize: * * A signed variant of #gsize, corresponding to the * ssize_t defined on most platforms. * Values of this type can range from #G_MINSSIZE * to #G_MAXSSIZE. * * To print or scan values of this type, use * %G_GSIZE_MODIFIER and/or %G_GSSIZE_FORMAT. */ /** * guchar: * * Corresponds to the standard C unsigned char type. */ /** * guint: * * Corresponds to the standard C unsigned int type. * Values of this type can range from 0 to #G_MAXUINT. */ /** * guint16: * * An unsigned integer guaranteed to be 16 bits on all platforms. * Values of this type can range from 0 to #G_MAXUINT16 (= 65,535). * * To print or scan values of this type, use * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT. */ /** * guint32: * * An unsigned integer guaranteed to be 32 bits on all platforms. * Values of this type can range from 0 to #G_MAXUINT32 (= 4,294,967,295). * * To print or scan values of this type, use * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT. */ /** * guint64: * * An unsigned integer guaranteed to be 64-bits on all platforms. * Values of this type can range from 0 to #G_MAXUINT64 * (= 18,446,744,073,709,551,615). * * To print or scan values of this type, use * %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT. */ /** * guint8: * * An unsigned integer guaranteed to be 8 bits on all platforms. * Values of this type can range from 0 to #G_MAXUINT8 (= 255). */ /** * guintptr: * * Corresponds to the C99 type uintptr_t, * an unsigned integer type that can hold any pointer. * * To print or scan values of this type, use * %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT. * * Since: 2.18 */ /** * gulong: * * Corresponds to the standard C unsigned long type. * Values of this type can range from 0 to #G_MAXULONG. */ /** * gushort: * * Corresponds to the standard C unsigned short type. * Values of this type can range from 0 to #G_MAXUSHORT. */ /************************************************************/ /* THIS FILE IS GENERATED DO NOT EDIT */ /************************************************************/