Methods

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().

Since: 2.8

Determines the numeric value of a character as a decimal digit. Differs from unicharDigitValue because it takes a char, so there's no worry about sign extension if characters are signed.

Converts a gdouble to a string, using the '.' as decimal point.

This function generates enough precision that converting the string back using asciiStrtod 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 gASCIIDTOSTRBUFSIZE bytes, including the terminating nul character, which is always added.

Converts a gdouble to a string, using the '.' as decimal point. To format the number you pass in a printf()-style format string. Allowed conversion specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.

The returned buffer is guaranteed to be nul-terminated.

If you just want to want to serialize the value into a string, use asciiDtostr.

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-Nothing.

Converts all upper case ASCII letters to lower case ASCII letters.

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 outNum. 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 NumberParserErrorInvalid. If the parsed number is out of bounds - NumberParserErrorOutOfBounds.

See asciiStrtoll if you have more complex needs such as parsing a string which starts with a number, but then has other characters.

Since: 2.54

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 outNum. 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 NumberParserErrorInvalid. If the parsed number is out of bounds - NumberParserErrorOutOfBounds.

See asciiStrtoull if you have more complex needs such as parsing a string which starts with a number, but then has other characters.

Since: 2.54

Compare s1 and s2, ignoring the case of ASCII characters and any characters after the first n in each string.

Unlike the BSD strcasecmp() function, this only recognizes standard ASCII letters and ignores the locale, treating all non-ASCII characters as if they are not letters.

The same warning as in asciiStrcasecmp applies: Use this function only on strings known to be in encodings where bytes corresponding to ASCII letters always represent themselves.

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 asciiDtostr.

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.

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, MAXINT64 or 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-Nothing).

Since: 2.12

Converts a string to a guint64 value. This function behaves like the standard strtoull() function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe.

This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the locale-sensitive system strtoull() function.

If the correct value would cause overflow, 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-Nothing).

Since: 2.2

Converts all lower case ASCII letters to upper case ASCII letters.

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.

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.

Determines the numeric value of a character as a hexidecimal digit. Differs from unicharXdigitValue because it takes a char, so there's no worry about sign extension if characters are signed.

No description available in the introspection data.

No description available in the introspection data.

No description available in the introspection data.

No description available in the introspection data.

Specifies a function to be called at normal program termination.

Since GLib 2.8.2, on Windows 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 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 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 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 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 atomicIntExchangeAndAdd did, and had the same meaning).

Since: 2.4

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; }.

Since: 2.30

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.

Since: 2.4

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.

Since: 2.4

This function existed before atomicIntAdd 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.

Since: 2.4

Gets the current value of atomic.

This call acts as a full compiler and hardware memory barrier (before the get).

Since: 2.4

Increments the value of atomic by 1.

Think of this operation as an atomic version of { *atomic += 1; }.

This call acts as a full compiler and hardware memory barrier.

Since: 2.4

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.

Since: 2.30

Sets the value of atomic to newval.

This call acts as a full compiler and hardware memory barrier (after the set).

Since: 2.4

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.

Since: 2.30

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.

Since: 2.30

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.

Since: 2.30

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.

Since: 2.4

Gets the current value of atomic.

This call acts as a full compiler and hardware memory barrier (before the get).

Since: 2.4

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.

Since: 2.30

Sets the value of atomic to newval.

This call acts as a full compiler and hardware memory barrier (after the set).

Since: 2.4

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.

Since: 2.30

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.

Since: 2.12

Decode a sequence of Base-64 encoded text into binary data by overwriting the input data.

Since: 2.20

Encode a sequence of binary data into its Base-64 stringified representation.

Since: 2.12

Gets the name of the file without any leading directory components. It returns a pointer into the given file name string.

Sets the indicated lockBit in address. If the bit is already set, this call will block until bitUnlock unsets the corresponding bit.

Attempting to lock on two different bits within the same integer is not supported and will very probably cause deadlocks.

The value of the bit that is set is (1u << bit). If bit is not between 0 and 31 then the result is undefined.

This function accesses address atomically. All other accesses to address must be atomic in order for this function to work reliably.

Since: 2.24

Find the position of the first bit set in mask, searching from (but not including) nthBit 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 nthBit to -1.

Find the position of the first bit set in mask, searching from (but not including) nthBit 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 nthBit to -1 or GLIB_SIZEOF_LONG * 8.

Gets the number of bits used to hold number, e.g. if number is 4, 3 bits are needed.

Sets the indicated lockBit 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.

Since: 2.24

Clears the indicated lockBit in address. If another thread is currently blocked in bitLock on this same bit then it will be woken up.

This function accesses address atomically. All other accesses to address must be atomic in order for this function to work reliably.

Since: 2.24

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.

Since: 2.8

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.

Since: 2.8

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().

Since: 2.8

Checks that the GLib library in use is compatible with the given version. Generally you would pass in the constants MAJOR_VERSION, MINOR_VERSION, 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 requiredMajor.required_minor.requiredMicro. Second the running library must be binary compatible with the version requiredMajor.required_minor.requiredMicro (same major version.)

Since: 2.6

Sets a function to be called when the child indicated by pid exits, at the priority priority.

If you obtain pid from spawnAsync or spawnAsyncWithPipes 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 spawnCheckExitStatus in the callback to determine whether or not the child exited successfully.

Also, note that on platforms where GPid must be explicitly closed (see spawnClosePid) pid must not be closed while the source is still active. Typically, you should invoke spawnClosePid in the callback function for the source.

GLib supports only a single callback per process id. On POSIX platforms, the same restrictions mentioned for childWatchSourceNew apply to this function.

This internally creates a main loop source using childWatchSourceNew and attaches it to the main loop context using sourceAttach. You can do these steps manually if you need greater control.

Since: 2.4

Creates a new child_watch source.

The source will not initially be associated with any MainContext and must be added to one with sourceAttach before it will be executed.

Note that child watch sources can only be used in conjunction with g_spawn... when the SpawnFlagsDoNotReapChild flag is used.

Note that on platforms where GPid must be explicitly closed (see spawnClosePid) pid must not be closed while the source is still active. Typically, you will want to call spawnClosePid in the callback function for the source.

On POSIX platforms, the following restrictions apply to this API due to limitations in POSIX process interfaces:

• pid must be a child of this process
• pid must be positive
• the application must not call waitpid with a non-positive first argument, for instance in another thread
• the application must not wait for pid to exit by any other mechanism, including waitpid(pid, ...) or a second child-watch source for the same pid
• the application must not ignore SIGCHILD

If any of those conditions are not met, this and related APIs will not work correctly. This can often be diagnosed via a GLib warning stating that ECHILD was received by waitpid.

Calling waitpid for specific processes other than pid remains a valid thing to do.

Since: 2.4

If err or *err is Nothing, does nothing. Otherwise, calls errorFree on *err and sets *err to Nothing.

This wraps the close() call; in case of error, errno will be preserved, but the error will also be stored as a GError in error.

Besides using GError, there is another major reason to prefer this function over the call provided by the system; on Unix, it will attempt to correctly handle EINTR, which has platform-specific semantics.

Since: 2.36

Computes the checksum for a binary data. This is a convenience wrapper for checksumNew, checksumGetString and checksumFree.

The hexadecimal string returned will be in lower case.

Since: 2.34

Computes the checksum for a binary data of length. This is a convenience wrapper for checksumNew, checksumGetString and checksumFree.

The hexadecimal string returned will be in lower case.

Since: 2.16

Computes the checksum of a string.

The hexadecimal string returned will be in lower case.

Since: 2.16

Computes the HMAC for a binary data. This is a convenience wrapper for g_hmac_new(), hmacGetString and hmacUnref.

The hexadecimal string returned will be in lower case.

Since: 2.50

Computes the HMAC for a binary data of length. This is a convenience wrapper for g_hmac_new(), hmacGetString and hmacUnref.

The hexadecimal string returned will be in lower case.

Since: 2.30

Computes the HMAC for a string.

The hexadecimal string returned will be in lower case.

Since: 2.30

Converts a string from one character set to another.

Note that you should use g_iconv() for streaming conversions. Despite the fact that bytesRead 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 convert, g_convert_with_iconv() or convertWithFallback. (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 strToAscii instead.

No description available in the introspection data.

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 fromCodeset to toCodeset 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 bytesRead 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 convert, g_convert_with_iconv() or convertWithFallback. (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.)

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 userData 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 datalistForeach call, other than skipping over elements that are removed.

Gets a data element, using its string identifier. This is slower than datalistIdGetData because it compares strings.

Gets flags values packed in together with the datalist. See datalistSetFlags.

Since: 2.8

Retrieves the data element corresponding to keyId.

Turns on flag values for a data list. This function is used to keep a small number of boolean flags in an object with a data list without using any additional space. It is not generally useful except in circumstances where space is very tight. (It is used in the base GObject type, for example.)

Since: 2.8

Turns off flag values for a data list. See datalistUnsetFlags

Since: 2.8

Destroys the dataset, freeing all memory allocated, and calling any destroy functions set for data elements.

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 datasetLocation 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 datasetForeach call, other than skipping over elements that are removed.

Gets the data element corresponding to a GQuark.

This is a variant of dgettext that allows specifying a locale category instead of always using LC_MESSAGES. See dgettext for more information about how this functions differs from calling dcgettext() directly.

Since: 2.26

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 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 Nothing
• 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.

Since: 2.18

Compares two gpointer arguments and returns True if they are equal. It can be passed to g_hash_table_new() as the keyEqualFunc parameter, when using opaque pointers compared by pointer value as keys in a HashTable.

This equality function is also appropriate for keys that are integers stored in pointers, such as GINT_TO_POINTER (n).

Converts a gpointer to a hash value. It can be passed to g_hash_table_new() as the hashFunc parameter, when using opaque pointers compared by pointer value as keys in a HashTable.

This hash function is also appropriate for keys that are integers stored in pointers, such as GINT_TO_POINTER (n).

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 dgettext for details of how this differs from dngettext() proper.

Since: 2.18

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 keyEqualFunc parameter, when using non-Nothing pointers to doubles as keys in a HashTable.

Since: 2.22

Converts a pointer to a gdouble to a hash value. It can be passed to g_hash_table_new() as the hashFunc parameter, It can be passed to g_hash_table_new() as the hashFunc parameter, when using non-Nothing pointers to doubles as keys in a HashTable.

Since: 2.22

This function is a variant of 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 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.

Since: 2.16

This function is a variant of 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 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.

Since: 2.18

Returns the value of the environment variable variable in the provided list envp.

Since: 2.32

Sets the environment variable variable in the provided list envp to value.

Since: 2.32

Removes the environment variable variable from the provided environment envp.

Since: 2.32

Gets a FileError constant based on the passed-in errNo. For example, if you pass in EEXIST this function returns G_FILE_ERROR_EXIST. Unlike errno values, you can portably assume that all FileError values will exist.