Specifies one of the possible types of byte order. See %G_BYTE_ORDER.
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 g_datalist_set_flags(). 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.
The directory separator character. This is '/' on UNIX machines and '' under Windows.
The directory separator as a string. This is "/" on UNIX machines and "" under Windows.
The base of natural logarithms.
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);
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);
This is the platform dependent conversion specifier for scanning and printing values of type #gint32. See also %G_GINT16_FORMAT.
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.
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.
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.
This is the platform dependent conversion specifier for scanning and printing values of type #gintptr.
The platform dependent length modifier for conversion specifiers for scanning and printing values of type #gintptr or #guintptr. It is a string literal.
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.
This is the platform dependent conversion specifier for scanning and printing values of type #gsize. See also %G_GINT16_FORMAT.
The platform dependent length modifier for conversion specifiers for scanning and printing values of type #gsize. It is a string literal.
This is the platform dependent conversion specifier for scanning and printing values of type #gssize. See also %G_GINT16_FORMAT.
The platform dependent length modifier for conversion specifiers for scanning and printing values of type #gssize. It is a string literal.
This is the platform dependent conversion specifier for scanning and printing values of type #guint16. See also %G_GINT16_FORMAT
This is the platform dependent conversion specifier for scanning and printing values of type #guint32. See also %G_GINT16_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.
This is the platform dependent conversion specifier for scanning and printing values of type #guintptr.
Defined to 1 if gcc-style visibility handling is supported.
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 bias by which exponents in double-precision floats are offset.
The bias by which exponents in single-precision floats are offset.
The name of the main group of a desktop entry file, as defined in the Desktop Entry Specification. Consult the specification for more details about the meanings of the keys below.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list giving the available application actions.
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.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the tooltip for the desktop entry.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true if the application is D-Bus activatable.
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.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the generic name of the desktop entry.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the desktop entry has been deleted by the user.
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.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of strings giving the MIME types supported by this desktop entry.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the specific name of the desktop entry.
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.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the desktop entry should be shown in menus.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of strings identifying the environments that should display the desktop entry.
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.
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the application supports the Startup Notification Protocol Specification.
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.
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.
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.
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.
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.
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.
The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing applications.
The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing directories.
The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing links to documents.
Specifies one of the possible types of byte order. See %G_BYTE_ORDER.
The natural logarithm of 10.
The natural logarithm of 2.
Multiplying the base 2 exponent by this number yields the base 10 exponent.
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 [Using Structured Logging][using-structured-logging].
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 maximum value which can be held in a #gint16.
The maximum value which can be held in a #gint32.
The maximum value which can be held in a #gint64.
The maximum value which can be held in a #gint8.
The maximum value which can be held in a #guint16.
The maximum value which can be held in a #guint32.
The maximum value which can be held in a #guint64.
The maximum value which can be held in a #guint8.
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 %G_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.
Specifies one of the possible types of byte order (currently unused). See %G_BYTE_ORDER.
The value of pi (ratio of circle's circumference to its diameter).
A format specifier that can be used in printf()-style format strings when printing a #GPid.
Pi divided by 2.
Pi divided by 4.
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 g_timeout_add(). 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 g_idle_add().
Use this for high priority event sources.
It is not used within GLib or GTK+.
Use this for high priority idle functions.
GTK+ uses %G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and %G_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+.
The search path separator character. This is ':' on UNIX machines and ';' under Windows.
The search path separator as a string. This is ":" on UNIX machines and ";" under Windows.
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 square root of two.
The standard delimiters, used in g_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 g_test_run() 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.
The subdirectories may not be created by the test harness; as with normal calls to functions like g_get_user_cache_dir(), 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 RFC 3986. Includes `:/?#[]```.
Subcomponent delimiter characters as defined in
RFC 3986. Includes !$&'()*+,;=.
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_VERSION_MIN_REQUIRED or earlier will cause warnings (but using functions deprecated in later releases will not).
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().
a pathname in the GLib file name encoding (UTF-8 on Windows)
as in access()
This function is similar to g_malloc(), allocating (n_blocks * n_block_bytes)
bytes, but care is taken to align the allocated memory to with the given
alignment value. Additionally, it will detect possible overflow during
multiplication.
Aligned memory allocations returned by this function can only be freed using g_aligned_free().
the number of blocks to allocate
the size of each block in bytes
the alignment to be enforced, which must be a positive power of 2 and a multiple of sizeof(void*)
This function is similar to g_aligned_alloc(), but it will also clear the allocated memory before returning it.
the number of blocks to allocate
the size of each block in bytes
the alignment to be enforced, which must be a positive power of 2 and a multiple of sizeof(void*)
Frees the memory allocated by g_aligned_alloc().
the memory to deallocate
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.
an ASCII character
Converts a #gdouble to a string, using the '.' as decimal point.
This function generates enough precision that converting the string back using g_ascii_strtod() gives the same machine-number (on machines with IEEE compatible 64bit doubles). It is guaranteed that the size of the resulting string will never be larger than %G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating nul character, which is always added.
A buffer to place the resulting string in
The length of the buffer.
The #gdouble to convert
Converts a #gdouble to a string, using the '.' as decimal point. To format the number you pass in a printf()-style format string. Allowed conversion specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
The format must just be a single format specifier
starting with %, expecting a #gdouble argument.
The returned buffer is guaranteed to be nul-terminated.
If you just want to want to serialize the value into a string, use g_ascii_dtostr().
A buffer to place the resulting string in
The length of the buffer.
The printf()-style format to use for the code to use for converting
The #gdouble to convert
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.
string to compare with s2
string to compare with s1
Converts all upper case ASCII letters to lower case ASCII letters.
a string
length of str in bytes, or -1 if str is nul-terminated
A convenience function for converting a string to a signed number.
This function assumes that str contains only a number of the given
base that is within inclusive bounds limited by min and max. If
this is true, then the converted number is stored in out_num. An
empty string is not a valid input. A string with leading or
trailing whitespace is also an invalid input.
base can be between 2 and 36 inclusive. Hexadecimal numbers must
not be prefixed with "0x" or "0X". Such a problem does not exist
for octal numbers, since they were usually prefixed with a zero
which does not change the value of the parsed number.
Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR domain. If the input is invalid, the error code will be %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS.
See g_ascii_strtoll() if you have more complex needs such as parsing a string which starts with a number, but then has other characters.
a string
base of a parsed number
a lower bound (inclusive)
an upper bound (inclusive)
A convenience function for converting a string to an unsigned number.
This function assumes that str contains only a number of the given
base that is within inclusive bounds limited by min and max. If
this is true, then the converted number is stored in out_num. An
empty string is not a valid input. A string with leading or
trailing whitespace is also an invalid input. A string with a leading sign
(- or +) is not a valid input for the unsigned parser.
base can be between 2 and 36 inclusive. Hexadecimal numbers must
not be prefixed with "0x" or "0X". Such a problem does not exist
for octal numbers, since they were usually prefixed with a zero
which does not change the value of the parsed number.
Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR domain. If the input is invalid, the error code will be %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS.
See g_ascii_strtoull() if you have more complex needs such as parsing a string which starts with a number, but then has other characters.
a string
base of a parsed number
a lower bound (inclusive)
an upper bound (inclusive)
Compare s1 and s2, ignoring the case of ASCII characters and any
characters after the first n in each string. If either string is
less than n bytes long, comparison will stop at the first nul byte
encountered.
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.
string to compare with s2
string to compare with s1
number of characters to compare
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.
the string to convert to a numeric value.
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).
the string to convert to a numeric value.
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.
Note that input with a leading minus sign (-) is accepted, and will return
the negation of the parsed number, unless that would overflow a #guint64.
Critically, this means you cannot assume that a short fixed length input will
never result in a low return value, as the input could have a leading -.
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).
the string to convert to a numeric value.
to be used for the conversion, 2..36 or 0
Converts all lower case ASCII letters to upper case ASCII letters.
a string
length of str in bytes, or -1 if str is nul-terminated
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.
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.
any character
Determines the numeric value of a character as a hexadecimal digit. Differs from g_unichar_xdigit_value() because it takes a char, so there's no worry about sign extension if characters are signed.
an ASCII character.
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.
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).
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gint or #guint
the value to add
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; }.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gint or #guint
the value to 'and'
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gint or #guint
the value to compare with
the value to conditionally replace with
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gint or #guint
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.
a pointer to a #gint
the value to add
Gets the current value of atomic.
This call acts as a full compiler and hardware memory barrier (before the get).
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gint or #guint
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gint or #guint
the value to 'or'
Sets the value of atomic to newval.
This call acts as a full compiler and hardware memory barrier (after the set).
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gint or #guint
a new value to store
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gint or #guint
the value to 'xor'
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gpointer-sized value
the value to add
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gpointer-sized value
the value to 'and'
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gpointer-sized value
the value to compare with
the value to conditionally replace with
Gets the current value of atomic.
This call acts as a full compiler and hardware memory barrier (before the get).
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gpointer-sized value
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gpointer-sized value
the value to 'or'
Sets the value of atomic to newval.
This call acts as a full compiler and hardware memory barrier (after the set).
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gpointer-sized value
a new value to store
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.
While atomic has a volatile qualifier, this is a historical artifact and
the pointer passed to it should not be volatile.
a pointer to a #gpointer-sized value
the value to 'xor'
Atomically acquires a reference on the data pointed by mem_block.
a pointer to reference counted data
Allocates block_size bytes of memory, and adds atomic
reference counting semantics to it.
The data will be freed when its reference count drops to zero.
The allocated data is guaranteed to be suitably aligned for any built-in type.
the size of the allocation, must be greater than 0
Allocates block_size bytes of memory, and adds atomic
reference counting semantics to it.
The contents of the returned data is set to zero.
The data will be freed when its reference count drops to zero.
The allocated data is guaranteed to be suitably aligned for any built-in type.
the size of the allocation, must be greater than 0
Allocates a new block of data with atomic reference counting
semantics, and copies block_size bytes of mem_block
into it.
the number of bytes to copy, must be greater than 0
the memory to copy
Retrieves the size of the reference counted data pointed by mem_block.
a pointer to reference counted data
Atomically releases a reference on the data pointed by mem_block.
If the reference was the last one, it will free the
resources allocated for mem_block.
a pointer to reference counted data
Atomically releases a reference on the data pointed by mem_block.
If the reference was the last one, it will call clear_func
to clear the contents of mem_block, and then will free the
resources allocated for mem_block.
a pointer to reference counted data
a function to call when clearing the data
Atomically compares the current value of arc with val.
the address of an atomic reference count variable
the value to compare
Atomically decreases the reference count.
If %TRUE is returned, the reference count reached 0. After this point, arc
is an undefined state and must be reinitialized with
g_atomic_ref_count_init() to be used again.
the address of an atomic reference count variable
Atomically increases the reference count.
the address of an atomic reference count variable
Initializes a reference count variable to 1.
the address of an atomic reference count variable
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.
zero-terminated string with base64 text to decode
Decode a sequence of Base-64 encoded text into binary data by overwriting the input data.
zero-terminated string with base64 text to decode
Encode a sequence of binary data into its Base-64 stringified representation.
the binary data to encode
Flush the status from a sequence of calls to g_base64_encode_step().
The output buffer must be large enough to fit all the data that will be written to it. It will need up to 4 bytes, or up to 5 bytes if line-breaking is enabled.
The out array will not be automatically nul-terminated.
whether to break long lines
Saved state from g_base64_encode_step()
Saved state from g_base64_encode_step()
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) / 76 + 1 bytes of extra space.
break_lines is typically used when putting base64-encoded data in emails.
It breaks the lines at 76 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.
the binary data to encode
whether to break long lines
Saved state between steps, initialize to 0
Saved state between steps, initialize to 0
Gets the name of the file without any leading directory components. It returns a pointer into the given file name string.
the name of the file
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. While address has a volatile qualifier, this is a historical
artifact and the argument passed to it should not be volatile.
a pointer to an integer
a bit value between 0 and 31
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.
a #gulong containing flags
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.
a #gulong containing flags
the index of the bit to start the search from
Gets the number of bits used to hold number,
e.g. if number is 4, 3 bits are needed.
a #guint
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. While address has a volatile qualifier, this is a historical
artifact and the argument passed to it should not be volatile.
a pointer to an integer
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. While address has a volatile qualifier, this is a historical
artifact and the argument passed to it should not be volatile.
a pointer to an integer
a bit value between 0 and 31
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.
%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.
a string used to separator the elements of the path.
%NULL-terminated array of strings containing the path elements.
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.
a #GByteArray
if %TRUE the actual byte data is freed as well
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.
a #GByteArray
Creates a new #GByteArray with a reference count of 1.
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().
Do not use it if len is greater than %G_MAXUINT. #GByteArray
stores the length of its data in #guint, which may be shorter than
#gsize.
byte data for the array
Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller.
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.
A #GByteArray
Gets the canonical file name from filename. All triple slashes are turned into
single slashes, and all .. and .s resolved against relative_to.
Symlinks are not followed, and the returned path is guaranteed to be absolute.
If filename is an absolute path, relative_to is ignored. Otherwise,
relative_to will be prepended to filename to make it absolute. relative_to
must be an absolute path, or %NULL. If relative_to is %NULL, it'll fallback
to g_get_current_dir().
This function never fails, and will canonicalize file paths even if they don't exist.
No file system I/O is done.
the name of the file
the relative directory, or %NULL to use the current working directory
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().
a pathname in the GLib file name encoding (UTF-8 on Windows)
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.)
the required major version
the required minor version
the required micro version
Gets the length in bytes of digests of type checksum_type
a #GChecksumType
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_wait_status() in the callback to determine whether or not the child exited successfully.
Also, note that on platforms where #GPid must be explicitly closed
(see g_spawn_close_pid()) pid must not be closed while the source
is still active. Typically, you should invoke g_spawn_close_pid()
in the callback function for the source.
GLib supports only a single callback per process id. On POSIX platforms, the same restrictions mentioned for g_child_watch_source_new() apply to this function.
This internally creates a main loop source using g_child_watch_source_new() and attaches it to the main loop context using g_source_attach(). You can do these steps manually if you need greater control.
the priority of the idle source. Typically this will be in the range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
process to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child).
function to call
Creates a new child_watch source.
The source will not initially be associated with any #GMainContext and must be added to one with g_source_attach() before it will be executed.
Note that child watch sources can only be used in conjunction with
g_spawn... when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used.
Note that on platforms where #GPid must be explicitly closed
(see g_spawn_close_pid()) pid must not be closed while the
source is still active. Typically, you will want to call
g_spawn_close_pid() in the callback function for the source.
On POSIX platforms, the following restrictions apply to this API due to limitations in POSIX process interfaces:
pid must be a child of this processpid must be positivewaitpid with a non-positive
first argument, for instance in another threadpid to exit by any other
mechanism, including waitpid(pid, ...) or a second child-watch
source for the same pidSIGCHLDIf any of those conditions are not met, this and related APIs will
not work correctly. This can often be diagnosed via a GLib warning
stating that ECHILD was received by waitpid.
Calling waitpid for specific processes other than pid remains a
valid thing to do.
process to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child).
If err or *err is %NULL, does nothing. Otherwise,
calls g_error_free() on *err and sets *err to %NULL.
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.
A file descriptor
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.
a #GChecksumType
binary blob to compute the digest of
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.
a #GChecksumType
binary blob to compute the digest of
Computes the checksum of a string.
The hexadecimal string returned will be in lower case.
a #GChecksumType
the string to compute the checksum of
the length of the string, or -1 if the string is null-terminated.
Computes the HMAC for a binary data. This is a
convenience wrapper for g_hmac_new(), g_hmac_get_string()
and g_hmac_unref().
The hexadecimal string returned will be in lower case.
a #GChecksumType to use for the HMAC
the key to use in the HMAC
binary blob to compute the HMAC of
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.
a #GChecksumType to use for the HMAC
the key to use in the HMAC
binary blob to compute the HMAC of
Computes the HMAC for a string.
The hexadecimal string returned will be in lower case.
a #GChecksumType to use for the HMAC
the key to use in the HMAC
the string to compute the HMAC for
the length of the string, or -1 if the string is nul-terminated
Converts a string from one character set to another.
Note that you should use g_iconv() for streaming conversions.
Despite the fact that bytes_read can return information about partial
characters, the g_convert_... functions are not generally suitable
for streaming. If the underlying converter maintains internal state,
then this won't be preserved across successive calls to g_convert(),
g_convert_with_iconv() or g_convert_with_fallback(). (An example of
this is the GNU C converter for CP1255 which does not emit a base
character until it knows that the next character is not a mark that
could combine with the base character.)
Using extensions such as "//TRANSLIT" may not work (or may not work well) on many platforms. Consider using g_str_to_ascii() instead.
the string to convert.
name of character set into which to convert str
character set of str.
Converts a string from one character set to another, possibly
including fallback sequences for characters not representable
in the output. Note that it is not guaranteed that the specification
for the fallback sequences in fallback will be honored. Some
systems may do an approximate conversion from from_codeset
to to_codeset in their iconv() functions,
in which case GLib will simply return that approximate conversion.
Note that you should use g_iconv() for streaming conversions.
Despite the fact that bytes_read can return information about partial
characters, the g_convert_... functions are not generally suitable
for streaming. If the underlying converter maintains internal state,
then this won't be preserved across successive calls to g_convert(),
g_convert_with_iconv() or g_convert_with_fallback(). (An example of
this is the GNU C converter for CP1255 which does not emit a base
character until it knows that the next character is not a mark that
could combine with the base character.)
the string to convert.
name of character set into which to convert str
character set of str.
UTF-8 string to use in place of characters not present in the target encoding. (The string must be representable in the target encoding). If %NULL, characters not in the target encoding will be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
Calls the given function for each data element of the datalist. The
function is called with each data element's #GQuark id and data,
together with the given user_data parameter. Note that this
function is NOT thread-safe. So unless datalist can be protected
from any modifications during invocation of this function, it should
not be called.
func can make changes to datalist, but the iteration will not
reflect changes made during the g_datalist_foreach() call, other
than skipping over elements that are removed.
a datalist.
the function to call for each data element.
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.)
pointer to the location that holds a list
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 off flag values for a data list. See g_datalist_unset_flags()
pointer to the location that holds a list
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.
Destroys the dataset, freeing all memory allocated, and calling any destroy functions set for data elements.
the location identifying the dataset.
Calls the given function for each data element which is associated
with the given location. Note that this function is NOT thread-safe.
So unless dataset_location can be protected from any modifications
during invocation of this function, it should not be called.
func can make changes to the dataset, but the iteration will not
reflect changes made during the g_dataset_foreach() call, other
than skipping over elements that are removed.
the location identifying the dataset.
the function to call for each data element.
Gets the data element corresponding to a #GQuark.
the location identifying the dataset.
the #GQuark id to identify the data element.
Returns the number of days in a month, taking leap years into account.
month
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.)
a year
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.)
year to count weeks in
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.
year to check
Generates a printed representation of the date, in a [locale][setlocale]-specific way. Works just like the platform's C library strftime() function, but only accepts date-related formats; time-related formats give undefined results. Date must be valid. Unlike strftime() (which uses the locale encoding), works on a UTF-8 format string and stores a UTF-8 result.
This function does not provide any conversion specifiers in addition to those implemented by the platform's C library. For example, don't expect that using g_date_strftime() would make the %F provided by the C99 strftime() work on Windows where the C library only complies to C89.
destination buffer
buffer size
format string
valid #GDate
Returns %TRUE if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive).
day to check
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).
day
month
year
Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a valid Julian, though there is a 32-bit limit.
Julian day to check
Returns %TRUE if the month value is valid. The 12 #GDateMonth enumeration values are the only valid months.
month
Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration values are the only valid weekdays.
weekday
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.
year
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.
the translation domain to use, or %NULL to use the domain set with textdomain()
message to translate
a locale category
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.
the translation domain to use, or %NULL to use the domain set with textdomain()
message to translate
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.
Template for directory name, as in g_mkdtemp(), basename only, or %NULL for a default template
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).
a key
a key to compare with v1
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).
a #gpointer key
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.
the translation domain to use, or %NULL to use the domain set with textdomain()
message to translate
plural form of the message
the quantity for which translation is needed
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.
a pointer to a #gdouble key
a pointer to a #gdouble key to compare with v1
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.
a pointer to a #gdouble key
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.
the translation domain to use, or %NULL to use the domain set with textdomain()
a combined message context and message id, separated by a \004 character
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.
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.
the translation domain to use, or %NULL to use the domain set with textdomain()
the message context
the message
Returns the value of the environment variable variable in the
provided list envp.
an environment list (eg, as returned from g_get_environ()), or %NULL for an empty environment list
the environment variable to get
Sets the environment variable variable in the provided list
envp to value.
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
the environment variable to set, must not contain '='
the value for to set the variable to
whether to change the variable if it already exists
Removes the environment variable variable from the provided
environment envp.
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
the environment variable to remove, must not contain '='
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.
an "errno" value
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.
name of a file to read contents from, in the GLib file name encoding
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.
Template for file name, as in g_mkstemp(), basename only, or %NULL for a default template
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.
the symbolic link
Writes all of contents to a file named filename. This is a convenience
wrapper around calling g_file_set_contents_full() with flags set to
G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING and
mode set to 0666.
name of a file to write contents to, in the GLib file name encoding
string to write to the file
Writes all of contents to a file named filename, with good error checking.
If a file called filename already exists it will be overwritten.
flags control the properties of the write operation: whether it’s atomic,
and what the tradeoff is between returning quickly or being resilient to
system crashes.
As this function performs file I/O, it is recommended to not call it anywhere
where blocking would cause problems, such as in the main loop of a graphical
application. In particular, if flags has any value other than
%G_FILE_SET_CONTENTS_NONE then this function may call fsync().
If %G_FILE_SET_CONTENTS_CONSISTENT is set in flags, the operation 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 UNIX, if filename already exists and is non-empty, and if the system
supports it (via a journalling filesystem or equivalent), and if
%G_FILE_SET_CONTENTS_CONSISTENT is set in flags, the fsync() call (or
equivalent) will be used to ensure atomic replacement: filename
will contain either its old contents or contents, even in the face of
system power loss, the disk being unsafely removed, etc.
On UNIX, if filename does not already exist or is empty, there is a
possibility that system power loss etc. after calling this function will
leave filename empty or full of NUL bytes, depending on the underlying
filesystem, unless %G_FILE_SET_CONTENTS_DURABLE and
%G_FILE_SET_CONTENTS_CONSISTENT are set in flags.
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.
If the file didn’t exist before and is created, it will be given the
permissions from mode. Otherwise, the permissions of the existing file may
be changed to mode depending on flags, or they may remain unchanged.
name of a file to write contents to, in the GLib file name encoding
string to write to the file
flags controlling the safety vs speed of the operation
file mode, as passed to open(); typically this will be 0666
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.
a filename to test in the GLib file name encoding
bitfield of #GFileTest flags
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.
an absolute pathname 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.
a pathname hopefully in the GLib file name encoding
Converts an escaped ASCII-encoded URI to a local filename in the encoding used for filenames.
a uri describing a filename (escaped, encoded in ASCII).
Converts a string from UTF-8 to the encoding GLib uses for filenames. Note that on Windows GLib uses UTF-8 for filenames; on other platforms, this function indirectly depends on the [current locale][setlocale].
The input string shall not contain nul characters even if the len
argument is positive. A nul character found inside the string will result
in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is
not UTF-8 and the conversion output contains a nul character, the error
%G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL.
a UTF-8 encoded string.
the length of the string, or -1 if the string is nul-terminated.
Converts an absolute filename to an escaped ASCII-encoded URI, with the path component following Section 3.3. of RFC 2396.
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
A UTF-8 encoded hostname, or %NULL for none.
Converts a string which is in the encoding used by GLib for filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 for filenames; on other platforms, this function indirectly depends on the [current locale][setlocale].
The input string shall not contain nul characters even if the len
argument is positive. A nul character found inside the string will result
in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
If the source encoding is not UTF-8 and the conversion output contains a
nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
function returns %NULL. Use g_convert() to produce output that
may contain embedded nul characters.
a string in the encoding for filenames
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)
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.
a program name in the GLib file name encoding
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 returned string is UTF-8, and may use a non-breaking space to separate the number and units, to ensure they aren’t separated when line wrapped.
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.
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.
a size in bytes
Formats a size.
This function is similar to g_format_size() but allows for flags that modify the output. See #GFormatSizeFlags.
a size in bytes
#GFormatSizeFlags to modify the output
Frees the memory pointed to by mem.
If mem is %NULL it simply returns, so there is no need to check mem
against %NULL before calling this function.
the memory to free
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).
Obtains the character set for the [current locale][setlocale]; you might use this character set as an argument to g_convert(), to convert from the current locale's encoding to some other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.)
On Windows the character set returned by this function is the so-called system default ANSI code-page. That is the character set used by the "narrow" versions of C library and Win32 functions that handle file names. It might be different from the character set used by the C library's current locale.
On Linux, the character set is found by consulting nl_langinfo() if
available. If not, the environment variables LC_ALL, LC_CTYPE, LANG
and CHARSET are queried in order.
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.
Gets the character set for the current locale.
Obtains the character set used by the console attached to the process, which is suitable for printing output to the terminal.
Usually this matches the result returned by g_get_charset(), but in environments where the locale's character set does not match the encoding of the console this function tries to guess a more suitable value instead.
On Windows the character set returned by this function is the output code page used by the console associated with the calling process. If the codepage can't be determined (for example because there is no console attached) UTF-8 is assumed.
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.
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.
Equivalent to the UNIX gettimeofday() function, but portable.
You may find g_get_real_time() to be more convenient.
#GTimeVal structure in which to store current time.
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.
Determines the preferred character sets used for filenames.
The first character set from the charsets is the filename encoding, the
subsequent character sets are used when trying to generate a displayable
representation of a filename, see g_filename_display_name().
On Unix, the character sets are determined by consulting the
environment variables G_FILENAME_ENCODING and G_BROKEN_FILENAMES.
On Windows, the character set used in the GLib API is always UTF-8
and said environment variables have no effect.
G_FILENAME_ENCODING may be set to a comma-separated list of
character set names. The special token "`locale"is taken to mean the character set for the [current locale][setlocale]. IfG_FILENAME_ENCODINGis not set, butG_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.
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.
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.
The encoding of the returned string is UTF-8.
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.
Computes a list of applicable locale names with a locale category name, which can be used to construct the fallback locale-dependent filenames or search paths. The returned list is sorted from most desirable to least desirable and always contains the default locale "C".
This function consults the environment variables LANGUAGE, LC_ALL,
category_name, and LANG to find the list of locales specified by the
user.
g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").
a locale category name
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. See
setlocale(3) for information about locales and their format.
locale itself is guaranteed to be returned in the output.
For example, if locale is fr_BE, then the returned list
is fr_BE, fr. If locale is en_GB.UTF-8euro, then the returned list is `en_GB.UTF-8`euro, en_GB.UTF-8, en_GBeuro, `en_GB`, `en.UTF-8`euro,
en.UTF-8, eneuro``, en.
If you need the list of variants for the current locale, use g_get_language_names().
a locale identifier
Queries the system monotonic time.
The monotonic clock will always increase and doesn't suffer discontinuities when the user (or NTP) changes the system time. It may or may not continue to tick during times where the machine is suspended.
We try to use the clock that corresponds as closely as possible to the passage of time as measured by system calls such as poll() but it may not always be possible to do this.
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.
Get information about the operating system.
On Linux this comes from the /etc/os-release file. On other systems, it may
come from a variety of sources. You can either use the standard key names
like %G_OS_INFO_KEY_NAME or pass any UTF-8 string key name. For example,
/etc/os-release provides a number of other less commonly used values that may
be useful. No key is guaranteed to be provided, so the caller should always
check if the result is %NULL.
a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME.
Gets the name of the program. This name should not be localized, in contrast to g_get_application_name().
If you are using #GApplication the program name is set in
g_application_run(). In case of GDK or GTK+ it is set in
gdk_init(), which is called by gtk_init() and the
#GtkApplication::startup handler. The program name is found by
taking the last component of argv[0].
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.
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 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.
In this case the list of directories retrieved will be XDG_CONFIG_DIRS.
On Windows it follows XDG Base Directory Specification if XDG_CONFIG_DIRS is defined.
If XDG_CONFIG_DIRS is undefined, the directory that contains application
data for all users is used instead. 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
FOLDERID_ProgramData folder. This information will not roam and is available
to anyone using the computer.
The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime.
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
In this case the list of directories retrieved will be XDG_DATA_DIRS.
On Windows it follows XDG Base Directory Specification if XDG_DATA_DIRS is defined.
If XDG_DATA_DIRS is undefined,
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 FOLDERID_ProgramData and
FOLDERID_PublicDocuments.
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.
The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime.
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 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.
In this case the directory retrieved will be XDG_CACHE_HOME.
On Windows it follows XDG Base Directory Specification if XDG_CACHE_HOME is defined.
If XDG_CACHE_HOME is undefined, the directory that serves as a common
repository for temporary Internet files is used instead. A typical path is
C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
See the documentation for FOLDERID_InternetCache.
The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime.
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.
In this case the directory retrieved will be XDG_CONFIG_HOME.
On Windows it follows XDG Base Directory Specification if XDG_CONFIG_HOME is defined.
If XDG_CONFIG_HOME is undefined, the folder to use for local (as opposed
to roaming) application data is used instead. See the
documentation for FOLDERID_LocalAppData.
Note that in this case on Windows it will be the same
as what g_get_user_data_dir() returns.
The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime.
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.
In this case the directory retrieved will be XDG_DATA_HOME.
On Windows it follows XDG Base Directory Specification if XDG_DATA_HOME
is defined. If XDG_DATA_HOME is undefined, the folder to use for local (as
opposed to roaming) application data is used instead. See the
documentation for FOLDERID_LocalAppData.
Note that in this case on Windows it will be the same
as what g_get_user_config_dir() returns.
The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime.
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 a directory that is unique to the current user on the local system.
This is determined using the mechanisms described
in the
XDG Base Directory Specification.
This is the directory
specified in the XDG_RUNTIME_DIR environment variable.
In the case that this variable is not set, we return the value of
g_get_user_cache_dir(), after verifying that it exists.
The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime.
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.
the logical id of special directory
Returns a base directory in which to store state files specific to particular user.
On UNIX platforms this is determined using the mechanisms described
in the
XDG Base Directory Specification.
In this case the directory retrieved will be XDG_STATE_HOME.
On Windows it follows XDG Base Directory Specification if XDG_STATE_HOME is defined.
If XDG_STATE_HOME is undefined, the folder to use for local (as opposed
to roaming) application data is used instead. See the
documentation for FOLDERID_LocalAppData.
Note that in this case on Windows it will be the same
as what g_get_user_data_dir() returns.
The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime.
Returns the value of an environment variable.
On UNIX, the name and value are byte strings which might or might not be in some consistent character set and encoding. On Windows, they are in UTF-8. On Windows, in case the environment variable's value contains references to other environment variables, they are expanded.
the environment variable to get
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.
In particular, this means that if key already exists in the hash table, then
the old copy of key in the hash table is freed and key replaces it in the
table.
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.
Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not.
a #GHashTable
a key to insert
Checks if key is in hash_table.
a #GHashTable
a key to check
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.
a #GHashTable
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.
Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not.
a #GHashTable
a key to insert
the value to associate with the key
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().
a #GHashTable
the key to look up
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.
a #GHashTable
the key to look up
Creates a new #GHashTable like g_hash_table_new_full() with a reference count of 1.
It inherits the hash function, the key equal function, the key destroy function,
as well as the value destroy function, from other_hash_table.
The returned hash table will be empty; it will not contain the keys
or values from other_hash_table.
Another #GHashTable
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.
a #GHashTable
the key to remove
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.
a #GHashTable
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.
Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not.
a #GHashTable
a key to insert
the value to associate with the key
Returns the number of elements contained in the #GHashTable.
a #GHashTable
Removes a key and its associated value from a #GHashTable without calling the key and value destroy functions.
a #GHashTable
the key to remove
Removes all keys and their associated values from a #GHashTable without calling the key and value destroy functions.
a #GHashTable
Looks up a key in the #GHashTable, stealing the original key and the associated value and returning %TRUE if the key was found. If the key was not found, %FALSE is returned.
If found, the stolen key and value are removed from the hash table without calling the key and value destroy functions, and ownership is transferred to the caller of this method; as with g_hash_table_steal().
You can pass %NULL for lookup_key, provided the hash and equal functions
of hash_table are %NULL-safe.
a #GHashTable
the key to look up
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.
a valid #GHashTable
Destroys a #GHook, given its ID.
a #GHookList
a hook ID
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.
a hostname
Tests if hostname is the string form of an IPv4 or IPv6 address.
(Eg, "192.168.0.1".)
Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).
a hostname (or IP address in string form)
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.
a hostname
Converts hostname to its canonical ASCII form; an ASCII-only
string containing no uppercase letters and not ending with a
trailing dot.
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.
a valid UTF-8 or ASCII hostname
Adds a function to be called whenever there are no higher priority events pending.
If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically removed from the list of event sources and will not be called again.
See [memory management of sources][mainloop-memory-management] for details
on how to handle the return value and memory management of data.
This internally creates a main loop source using g_idle_source_new() and attaches it to the global #GMainContext using g_source_attach(), so the callback will be invoked in whichever thread is running that main context. You can do these steps manually if you need greater control or to use a custom main context.
the priority of the idle source. Typically this will be in the range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
function to call
Removes the idle function with the given data.
the data for the idle source's callback.
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.
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.
a pointer to a #gint64 key
a pointer to a #gint64 key to compare with v1
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.
a pointer to a #gint64 key
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.
a pointer to a #gint key
a pointer to a #gint key to compare with v1
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.
a pointer to a #gint key
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.
This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++.
a static string
Returns a canonical representation for string. Interned strings
can be compared for equality by comparing the pointers, instead of
using strcmp().
This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++.
a string
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.
a #GIOChannel
the priority of the #GIOChannel source
the condition to watch for
the function to call when the condition is satisfied
Converts an errno error number to a #GIOChannelError.
an errno error number, e.g. EINVAL
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: