/************************************************************/
/* 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. 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. 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.
* @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. fields
*/
/**
* 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.
* @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 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.
*
*
*
*
*
* In order: A, B, C, D, E, F, G, H, I
*
*
* @G_PRE_ORDER: visits a node, then its children.
*
*
*
*
*
* Pre order: F, B, A, D, C, E, G, I, H
*
*
* @G_POST_ORDER: visits the node's children, then the node itself.
*
*
*
*
*
* Post order: A, C, E, D, B, H, I, G, F
*
*
* @G_LEVEL_ORDER: is not implemented for Balanced Binary
* Trees. For 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.
*
*
*
*
*
* Level order: F, B, G, A, D, I, C, E, H
*
*
*
* Specifies the type of traveral performed by g_tree_traverse(),
* g_node_traverse() and g_node_find().
*/
/**
* GTree:
*
* The GTree struct is an opaque data structure representing a Balanced Binary Tree.
* 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: (skip)
*
* #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 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_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_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_MAXDOUBLE:
*
* The maximum value which can be held in a #gdouble.
*/
/**
* G_MAXFLOAT:
*
* The maximum value which can be held in a #gfloat.
*/
/**
* G_MAXINT:
*
* The maximum value which can be held in a #gint.
*/
/**
* G_MAXINT16:
*
* The maximum value which can be held in a #gint16.
*
* Since: 2.4
*/
/**
* G_MAXINT32:
*
* The maximum value which can be held in a #gint32.
*
* Since: 2.4
*/
/**
* G_MAXINT64:
*
* The maximum value which can be held in a #gint64.
*/
/**
* G_MAXINT8:
*
* The maximum value which can be held in a #gint8.
*
* Since: 2.4
*/
/**
* G_MAXLONG:
*
* The maximum value which can be held in a #glong.
*/
/**
* G_MAXOFFSET:
*
* The maximum value which can be held in a #goffset.
*/
/**
* G_MAXSHORT:
*
* The maximum value which can be held in a #gshort.
*/
/**
* G_MAXSIZE:
*
* The maximum value which can be held in a #gsize.
*
* Since: 2.4
*/
/**
* G_MAXSSIZE:
*
* The maximum value which can be held in a #gssize.
*
* Since: 2.14
*/
/**
* G_MAXUINT:
*
* The maximum value which can be held in a #guint.
*/
/**
* G_MAXUINT16:
*
* The maximum value which can be held in a #guint16.
*
* Since: 2.4
*/
/**
* G_MAXUINT32:
*
* The maximum value which can be held in a #guint32.
*
* Since: 2.4
*/
/**
* G_MAXUINT64:
*
* The maximum value which can be held in a #guint64.
*/
/**
* G_MAXUINT8:
*
* The maximum value which can be held in a #guint8.
*
* Since: 2.4
*/
/**
* G_MAXULONG:
*
* The maximum value which can be held in a #gulong.
*/
/**
* G_MAXUSHORT:
*
* The maximum value which can be held in a #gushort.
*/
/**
* G_MINDOUBLE:
*
* The minimum positive value which can be held in a #gdouble.
*
* If you are interested in the smallest value which can be held
* in a #gdouble, use -%G_MAXDOUBLE.
*/
/**
* G_MINFLOAT:
*
* The minimum positive value which can be held in a #gfloat.
*
* If you are interested in the smallest value which can be held
* in a #gfloat, use -%G_MAXFLOAT.
*/
/**
* G_MININT:
*
* The minimum value which can be held in a #gint.
*/
/**
* G_MININT16:
*
* The minimum value which can be held in a #gint16.
*
* Since: 2.4
*/
/**
* G_MININT32:
*
* The minimum value which can be held in a #gint32.
*
* Since: 2.4
*/
/**
* G_MININT64:
*
* The minimum value which can be held in a #gint64.
*/
/**
* G_MININT8:
*
* The minimum value which can be held in a #gint8.
*
* Since: 2.4
*/
/**
* G_MINLONG:
*
* The minimum value which can be held in a #glong.
*/
/**
* G_MINOFFSET:
*
* The minimum value which can be held in a #goffset.
*/
/**
* G_MINSHORT:
*
* The minimum value which can be held in a #gshort.
*/
/**
* G_MINSSIZE:
*
* The minimum value which can be held in a #gssize.
*
* Since: 2.14
*/
/**
* G_N_ELEMENTS:
* @arr: the array
*
* Determines the number of elements in an array. The array must be
* declared so the compiler knows its size at compile-time; this
* macro will not work on an array allocated on the heap, only static
* arrays or arrays on the stack.
*/
/**
* G_ONCE_INIT:
*
* A #GOnce must be initialized with this macro before it can be used.
*
* |[
* 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
* <xbel> root element; each bookmark is stored inside a
* <bookmark> 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
* <metadata> 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`
* 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.
* 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 <NAMESPACE>_<MODULE>_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
* <namespace>_<module>_error_quark,
* for example g_spawn_error_quark() or g_thread_error_quark().
*
* - The error codes are in an enumeration called
* <Namespace><Module>Error;
* for example,#GThreadError or #GSpawnError.
*
* - Members of the error code enumeration are called
* <NAMESPACE>_<MODULE>_ERROR_<CODE>,
* 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 <NAMESPACE>_<MODULE>_ERROR_FAILED,
* for example %G_SPAWN_ERROR_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. If %FALSE is
* returned, the error must be set to a non-%NULL value.
*
* - 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:
*
* 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:
*
*
*
*
*
*
* Character
*
*
*
*
* Meaning
*
*
*
*
*
*
* 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.
*/
/**
* 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
* `<glib/gi18n.h>`. For use in a library, you must include
* `<glib/gi18n-lib.h>`
* 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. 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 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 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 instead.
*
* The data contained in each element can be either integer values, by
* using one of the Type
* Conversion Macros, or simply pointers to any type of data.
*
* List elements are allocated from the slice allocator, 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 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, or simply pointers to any type of data.
*
* List elements are allocated from the slice allocator, 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
*
* /* ... setup context ... */
*
* if (!g_option_context_parse_strv (context, &args, &error))
* {
* /* ... error ... */
* }
*
* /* ... */
*
* 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 and 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, 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,
* 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
*/
/**
* SECTION:spawn
* @Short_description: process launching
* @Title: Spawning 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 `<glib/gprintf.h>` 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-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()).
*
* - 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.
*
* - setlocale() 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.
*
* - fork() 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.
*
* - daemon() 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_equal_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 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 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 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.
*
* 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, 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.)
*
* 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, 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, 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
* 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-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.
*
* 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.
*
* 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.
*
* 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.
* @...: 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; 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. 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, if available.
*
* On POSIX systems with clock_gettime() and `CLOCK_MONOTONIC` this call
* is a very shallow wrapper for that. Otherwise, we make a best effort
* that probably involves returning the wall clock time (with at least
* microsecond accuracy, subject to the limitations of the OS kernel).
*
* It's important to note that POSIX `CLOCK_MONOTONIC` does
* not count time spent while the machine is suspended.
*
* On Windows, "limitations of the OS kernel" is a rather substantial
* statement. Depending on the configuration of the system, the wall
* clock time is updated as infrequently as 64 times a second (which
* is approximately every 16ms). Also, on XP (but not on Vista or later)
* the monotonic clock is locally monotonic, but may differ in exact
* value between processes due to timer wrap handling.
*
* 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.
*
* 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.
*
* 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_error_quark:
*
* Returns: the quark used as %G_IO_CHANNEL_ERROR
*/
/**
* 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. 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 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.
*
* 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.
*/
/**
* 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 ().
*
* 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-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.
*
* 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 "(?P<X>a)?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 "(?P<X>a)?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 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.
* @...: 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
* "<a> <b> <c>" against the pattern "<.*>"
* you get "<a> <b> <c>".
*
* 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
* "<a> <b> <c>" against the pattern "<.*>"
* you would obtain three matches: "<a> <b> <c>",
* "<a> <b>" and "<a>".
*
* 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<number>' in the replacement text are interpolated by the
* number-th captured subexpression of the match, '\g<name>' 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 fo 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): return location for number of args
* @argvp: (out) (array length=argcp zero-terminated=1): return location for array of args
* @error: return location for error
*
* 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
* 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
* 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
* 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 environment
* variable, also see 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 environment
* variable, also see 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 environment
* variable, also see 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 environment
* variable, also see 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
* 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
* 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.
* @...: 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.
*
* 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.
*
* 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.
*
* 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().
*
* 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.
*
* 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.
*
* 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.
*/
/**
* 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.
*
* 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.
*/
/**
* 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.
*
* 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.
* @...: 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_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
* @...: 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
* @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 (<code>)".
*/
/**
* 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: the initial text to copy into the 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 (<signum>)".
*/
/**
* 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 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 if 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
*
* 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.
*
* Returns: 0 on success, 1 on failure (assuming it returns at all),
* 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
*
* 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
*
* 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
*
* 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
*
* 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 is 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.
*/
/**
* 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
* pas 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.
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
* 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.
*
* 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.
*
* 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
* 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:
*
*
*
* element type C 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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. 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.
*
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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:
*
* 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.
*
* 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.
* @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.
* @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.
* @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.
* @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.
* @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()) 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_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_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_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 */
/************************************************************/