glib.types

Specifies the type of the value_destroy_func and key_destroy_func functions passed to [glib.cache.Cache.new_]. The functions are passed a pointer to the #GCache key or #GCache value and should free any memory and other resources associated with it.

Specifies the type of the key_dup_func function passed to [glib.cache.Cache.new_]. The function is passed a key (__not__ a value as the prototype implies) and should return a duplicate of the key.

Specifies the type of the value_new_func function passed to [glib.cache.Cache.new_]. It is passed a #GCache key and should create the value corresponding to the key.

Prototype of a #GChildWatchSource callback, called when a child process has exited.

To interpret wait_status, see the documentation for [glib.global.spawnCheckWaitStatus]. In particular, on Unix platforms, note that it is usually not equal to the integer passed to exit() or returned from main().

Specifies the type of function passed to [glib.global.clearHandleId]. The implementation is expected to free the resource identified by handle_id; for instance, if handle_id is a #GSource ID, [glib.source.Source.remove] can be used.

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.

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.

Specifies the type of the function passed to [glib.completion.Completion.new_]. It should return the string corresponding to the given target item. This is used when you use data structures as #GCompletion items.

Specifies the type of the function passed to [glib.completion.Completion.setCompare]. This is used when you use strings as #GCompletion items.

A function of this signature is used to copy the node data when doing a deep-copy of a tree.

Specifies the type of function passed to [glib.global.datasetForeach]. It is called with each #GQuark id and associated data element, together with the user_data parameter supplied to [glib.global.datasetForeach].

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.

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.

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.

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.

This is a version of #GEqualFunc which provides a user_data closure from the caller.

Specifies the type of function which is called when an extended error instance is freed. It is passed the error pointer about to be freed, and should free the error's private data fields.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from error.

Specifies the type of function which is called when an extended error instance is copied. It is passed the pointer to the destination error and source error, and should copy only the fields of the private data from src_error to dest_error.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from src_error and dest_error.

Specifies the type of function which is called just after an extended error instance is created and its fields filled. It should only initialize the fields in the private data, which can be received with the generated *_get_private() function.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from error.

Declares a type of function which takes an arbitrary data pointer argument and has no return value. It is not currently used in GLib or GTK.

Specifies the type of functions passed to [glib.list.List.foreach_] and [glib.slist.SList.foreach_].

Specifies the type of the function passed to [glib.hash_table.HashTable.foreach_]. It is called with each key/value pair, together with the user_data parameter which is passed to [glib.hash_table.HashTable.foreach_].

Specifies the type of the function passed to [glib.hash_table.HashTable.foreachRemove]. It is called with each key/value pair, together with the user_data parameter passed to [glib.hash_table.HashTable.foreachRemove]. It should return true if the key/value pair should be removed from the #GHashTable.

Specifies the type of the hash function which is passed to [glib.hash_table.HashTable.new_] when a #GHashTable is created.

The function is passed a key and should return a #guint hash value. The functions [glib.global.directHash], [glib.global.intHash] and [glib.global.strHash] provide hash functions which can be used when the key is a #gpointer, #gint*, and #gchar* respectively.

[glib.global.directHash] 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 [glib.global.strHash] in that situation might make your application vulnerable to

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.

Defines the type of a hook function that can be invoked by [glib.hook_list.HookList.invokeCheck].

Defines the type of function used by [glib.hook_list.HookList.marshalCheck].

Defines the type of function used to compare #GHook elements in [glib.hook.Hook.insertSorted].

Defines the type of function to be called when a hook in a list of hooks gets finalized.

Defines the type of the function passed to [glib.hook.Hook.find].

Defines the type of a hook function that can be invoked by [glib.hook_list.HookList.invoke].

Defines the type of function used by [glib.hook_list.HookList.marshal].

Specifies the type of function passed to [glib.global.ioAddWatch] or [glib.global.ioAddWatchFull], which is called when the requested condition on a #GIOChannel is satisfied.

Specifies the prototype of log handler functions.

The default log handler, funcGLib.log_default_handler, automatically appends a new-line character to message when printing it. It is advised that any custom log handler functions behave similarly, so that logging calls in user code do not need modifying to add a new-line character to the message if the log handler is changed.

This is not used if structured logging is enabled; see

Specifies the type of function passed to [glib.node.Node.childrenForeach]. The function is called with each child node, together with the user data passed to [glib.node.Node.childrenForeach].

Specifies the type of function passed to [glib.node.Node.traverse]. The function is called with each of the nodes visited, together with the user data passed to [glib.node.Node.traverse]. If the function returns true, then the traversal is stopped.

The type of function to be passed as callback for G_OPTION_ARG_CALLBACK options.

The type of function to be used as callback when a parse error occurs.

The type of function that can be called before and after parsing.

Specifies the type of function passed to [glib.main_context.MainContext.setPollFunc]. The semantics of the function should match those of the poll() system call.

Specifies the type of the print handler functions. These are called with the complete formatted string to output.

Specifies the type of the function passed to [glib.regex.Regex.replaceEval]. It is called for each occurrence of the pattern in the string passed to [glib.regex.Regex.replaceEval], and it should append the replacement to result.

Specifies the type of the message handler function.

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.

Dispose function for source. See [glib.source.Source.setDisposeFunction] for details.

This is just a placeholder for #GClosureMarshal, which cannot be used here for dependency reasons.

Specifies the type of function passed to [glib.global.timeoutAdd], [glib.global.timeoutAddFull], [glib.global.idleAdd], and [glib.global.idleAddFull].

When calling [glib.source.Source.setCallback], you may need to cast a function of a different type to this type. Use G_SOURCE_FUNC() to avoid warnings about incompatible function types.

A source function that is only called once before being removed from the main context automatically.

See: [glib.global.idleAddOnce], [glib.global.timeoutAddOnce]

Specifies the type of the setup function passed to [glib.global.spawnAsync], [glib.global.spawnSync] and [glib.global.spawnAsyncWithPipes], which can, in very limited ways, be used to affect the child's execution.

On POSIX platforms, the function is called in the child after GLib has performed all the setup it plans to perform, but before calling exec(). Actions taken in this function will only affect the child, not the parent.

On Windows, the function is called in the parent. Its usefulness on Windows is thus questionable. In many cases executing the child setup function in the parent can have ill effects, and you should be very careful when porting software to Windows that uses child setup functions.

However, even on POSIX, you are extremely limited in what you can safely do from a #GSpawnChildSetupFunc, because any mutexes that were held by other threads in the parent process at the time of the fork() will still be locked in the child process, and they will never be unlocked (since the threads that held them don't exist in the child). POSIX allows only async-signal-safe functions (see signal(7)) to be called in the child between fork() and exec(), which drastically limits the usefulness of child setup functions.

In particular, it is not safe to call any function which may call malloc(), which includes POSIX functions such as setenv(). If you need to set up the child environment differently from the parent, you should use [glib.global.getEnviron], [glib.global.environSetenv], and [glib.global.environUnsetenv], and then pass the complete environment list to the g_spawn... function.

The type used for test case functions that take an extra pointer argument.

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.

The type used for test case functions.

Specifies the prototype of fatal log handler functions.

Specifies the type of the func functions passed to [glib.thread.Thread.new_] or [glib.thread.Thread.tryNew].

The type of functions which are used to translate user-visible strings, for <option>--help</option> output.

Specifies the type of function passed to [glib.tree.Tree.traverse]. It is passed the key and value of each node, together with the user_data parameter passed to [glib.tree.Tree.traverse]. If the function returns true, the traversal is stopped.

Specifies the type of function passed to [glib.tree.Tree.foreachNode]. It is passed each node, together with the user_data parameter passed to [glib.tree.Tree.foreachNode]. If the function returns true, the traversal is stopped.

The type of functions to be called when a UNIX fd watch source triggers.

Declares a type of function which takes no arguments and has no return value. It is used to specify the type function passed to [glib.global.atexit].

A good size for a buffer to be passed into func@GLib.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));

Evaluates to the initial reference count for gatomicrefcount.

This macro is useful for initializing gatomicrefcount fields inside structures, for instance:

typedef struct {
 gatomicrefcount ref_count;
 char *name;
 char *address;
} Person;

static const Person default_person = {
 .ref_count = G_ATOMIC_REF_COUNT_INIT,
 .name = "Default name",
 .address = "Default address",
};

The set of uppercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig.

The set of ASCII digits. Used for specifying valid identifier characters in #GScannerConfig.

The set of lowercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig.

A bitmask that restricts the possible flags passed to [glib.global.datalistSetFlags]. Passing a flags value where flags & ~G_DATALIST_FLAGS_MASK != 0 is an error.

Represents an invalid #GDateDay.

Represents an invalid Julian day number.

Represents an invalid year.

Expands to "" on all modern compilers, and to __FUNCTION__ on gcc version 2.x. Don't use it.

Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ on gcc version 2.x. Don't use it.

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.

The name of the main group of a desktop entry file, as defined in the

Consult the specification for more details about the meanings of the keys below.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a string list giving the available application actions.

A key under [glib.types.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.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the tooltip for the desktop entry.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a boolean set to true if the application is D-Bus activatable.

A key under [glib.types.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.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the generic name of the desktop entry.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the desktop entry has been deleted by the user.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the name of the icon to be displayed for the desktop entry.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings giving the MIME types supported by this desktop entry.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the specific name of the desktop entry.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings identifying the environments that should not display the desktop entry.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the desktop entry should be shown in menus.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings identifying the environments that should display the desktop entry.

A key under [glib.types.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.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the application supports the

A key under [glib.types.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.

A key under [glib.types.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.

A key under [glib.types.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.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the type of the desktop entry.

Usually [glib.types.KEY_FILE_DESKTOP_TYPE_APPLICATION], [glib.types.KEY_FILE_DESKTOP_TYPE_LINK], or [glib.types.KEY_FILE_DESKTOP_TYPE_DIRECTORY].

A key under [glib.types.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.

A key under [glib.types.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the version of the Desktop Entry Specification used for the desktop entry file.

The value of the [glib.types.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing applications.

The value of the [glib.types.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing directories.

The value of the [glib.types.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing links to documents.

Defines the log domain. See Log Domains.

Libraries should define this so that any messages which they log can be differentiated from messages from other libraries and application code. But be careful not to define it in any public header files.

Log domains must be unique, and it is recommended that they are the application or library name, optionally followed by a hyphen and a sub-domain name. For example, bloatpad or bloatpad-io.

If undefined, it defaults to the default null (or `""`) log domain; this is not advisable, as it cannot be filtered against using the G_MESSAGES_DEBUG environment variable.

For example, GTK uses this in its Makefile.am:

AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\"

Applications can choose to leave it as the default null (or `""`) domain. However, defining the domain offers the same advantages as above.

GLib log levels that are considered fatal by default.

This is not used if structured logging is enabled; see

Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib. Higher bits can be used for user-defined log levels.

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.

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.

The minimum value which can be held in a #gint16.

The minimum value which can be held in a #gint32.

The minimum value which can be held in a #gint64.

The minimum value which can be held in a #gint8.

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.

If a long option in the main group has this name, it is not treated as a regular option. Instead it collects all non-option arguments which would otherwise be left in argv. The option must be of type G_OPTION_ARG_CALLBACK, G_OPTION_ARG_STRING_ARRAY or G_OPTION_ARG_FILENAME_ARRAY.

Using [glib.types.OPTION_REMAINING] instead of simply scanning argv for leftover arguments has the advantage that GOption takes care of necessary encoding conversions for strings or filenames.

A format specifier that can be used in printf()-style format strings when printing a #GPid.

A format specifier that can be used in printf()-style format strings when printing the @fd member of a #GPollFD.

Use this for default priority event sources.

In GLib this priority is used when adding timeout functions with [glib.global.timeoutAdd]. In GDK this priority is used for events from the X server.

Use this for default priority idle functions.

In GLib this priority is used when adding idle functions with [glib.global.idleAdd].

Use this for high priority event sources.

It is not used within GLib or GTK.

Use this for high priority idle functions.

GTK uses [glib.types.PRIORITY_HIGH_IDLE] + 10 for resizing operations, and [glib.types.PRIORITY_HIGH_IDLE] + 20 for redrawing operations. (This is done to ensure that any pending resizes are processed before any pending redraws, so that widgets are not redrawn twice unnecessarily.)

Use this for very low priority background tasks.

It is not used within GLib or GTK.

Evaluates to the initial reference count for grefcount.

This macro is useful for initializing grefcount fields inside structures, for instance:

typedef struct {
 grefcount ref_count;
 char *name;
 char *address;
} Person;

static const Person default_person = {
 .ref_count = G_REF_COUNT_INIT,
 .name = "Default name",
 .address = "Default address",
};

Use this macro as the return value of a #GSourceFunc to leave the #GSource in the main loop.

Use this macro as the return value of a #GSourceFunc to remove the #GSource from the main loop.

The standard delimiters, used in func@GLib.strdelimit.

Creates a unique temporary directory for each unit test and uses g_set_user_dirs() to set XDG directories to point into subdirectories of it for the duration of the unit test. The directory tree is cleaned up after the test finishes successfully. Note that this doesn’t take effect until [glib.global.testRun] is called, so calls to (for example) g_get_user_home_dir() will return the system-wide value when made in a test program’s main() function.

The following functions will return subdirectories of the temporary directory when this option is used. The specific subdirectory paths in use are not guaranteed to be stable API — always use a getter function to retrieve them.

• [glib.global.getHomeDir]
• [glib.global.getUserCacheDir]
• [glib.global.getSystemConfigDirs]
• [glib.global.getUserConfigDir]
• [glib.global.getSystemDataDirs]
• [glib.global.getUserDataDir]
• [glib.global.getUserStateDir]
• [glib.global.getUserRuntimeDir]

The subdirectories may not be created by the test harness; as with normal calls to functions like [glib.global.getUserCacheDir], the caller must be prepared to create the directory if it doesn’t exist.

Evaluates to a time span of one day.

Evaluates to a time span of one hour.

Evaluates to a time span of one millisecond.

Evaluates to a time span of one minute.

Evaluates to a time span of one second.

The maximum length (in codepoints) of a compatibility or canonical decomposition of a single Unicode character.

This is as defined by Unicode 6.1.

Generic delimiters characters as defined in

Subcomponent delimiter characters as defined in

Number of microseconds in one second (1 million). This macro is provided for code readability.

A macro that should be defined by the user prior to including the glib.h header. The definition should be one of the predefined GLib version macros: GLIB_VERSION_2_26, GLIB_VERSION_2_28,...

This macro defines the earliest version of GLib that the package is required to be able to compile against.

If the compiler is configured to warn about the use of deprecated functions, then using functions that were deprecated in version [glib.types.VERSION_MIN_REQUIRED] or earlier will cause warnings (but using functions deprecated in later releases will not).