Functions ========= .. currentmodule:: gi.repository.GLib .. function:: access(filename: str, mode: int) -> int 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(). .. versionadded:: 2.8 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param mode: as in access() :return: zero if the pathname refers to an existing file system object that has all the tested permissions, or -1 otherwise or on error. .. function:: aligned_alloc(n_blocks: int, n_block_bytes: int, alignment: int) -> ~typing.Any | None This function is similar to :func:`~gi.repository.GLib.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. If the allocation fails (because the system is out of memory), the program is terminated. Aligned memory allocations returned by this function can only be freed using :func:`~gi.repository.GLib.aligned_free_sized` or :func:`~gi.repository.GLib.aligned_free`. .. versionadded:: 2.72 :param n_blocks: the number of blocks to allocate :param n_block_bytes: the size of each block in bytes :param alignment: the alignment to be enforced, which must be a positive power of 2 and a multiple of ``sizeof(void*)`` :return: the allocated memory .. function:: aligned_alloc0(n_blocks: int, n_block_bytes: int, alignment: int) -> ~typing.Any | None This function is similar to :func:`~gi.repository.GLib.aligned_alloc`, but it will also clear the allocated memory before returning it. .. versionadded:: 2.72 :param n_blocks: the number of blocks to allocate :param n_block_bytes: the size of each block in bytes :param alignment: the alignment to be enforced, which must be a positive power of 2 and a multiple of ``sizeof(void*)`` :return: the allocated, cleared memory .. function:: aligned_free(mem: ~typing.Any = None) -> None Frees the memory allocated by :func:`~gi.repository.GLib.aligned_alloc`. .. versionadded:: 2.72 :param mem: the memory to deallocate .. function:: aligned_free_sized(mem: ~typing.Any, alignment: int, size: int) -> None Frees the memory pointed to by ``mem``\, assuming it is has the given ``size`` and ``alignment``\. If ``mem`` is :const:`None` this is a no-op (and ``size`` is ignored). It is an error if ``size`` doesn’t match the size, or ``alignment`` doesn’t match the alignment, passed when ``mem`` was allocated. ``size`` and ``alignment`` are passed to this function to allow optimizations in the allocator. If you don’t know either of them, use :func:`~gi.repository.GLib.aligned_free` instead. .. versionadded:: 2.76 :param mem: the memory to free :param alignment: alignment of ``mem`` :param size: size of ``mem``\, in bytes .. function:: ascii_digit_value(c: int) -> int Determines the numeric value of a character as a decimal digit. If the character is not a decimal digit according to :obj:`~gi.repository.GLib.ascii_isdigit`\, ``-1`` is returned. Differs from :obj:`~gi.repository.GLib.unichar_digit_value` because it takes a char, so there's no worry about sign extension if characters are signed. :param c: an ASCII character :return: the numerical value of ``c`` if it is a decimal digit, ``-1`` otherwise .. function:: ascii_dtostr(buffer: str, buf_len: int, d: float) -> str Converts a ``gdouble`` to a string, using the '.' as decimal point. This function generates enough precision that converting the string back using :obj:`~gi.repository.GLib.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 :obj:`~gi.repository.GLib.ASCII_DTOSTR_BUF_SIZE` bytes, including the terminating nul character, which is always added. :param buffer: a buffer to place the resulting string in :param buf_len: the length of the buffer :param d: the value to convert :return: the pointer to the buffer with the converted string .. function:: ascii_formatd(buffer: str, buf_len: int, format: str, d: float) -> str 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 :obj:`~gi.repository.GLib.ascii_dtostr`\. :param buffer: a buffer to place the resulting string in :param buf_len: the length of the buffer :param format: the ``printf()``\-style format to use for the code to use for converting :param d: the value to convert :return: the pointer to the buffer with the converted string .. function:: ascii_strcasecmp(s1: str, s2: str) -> int 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``\. :param s1: string to compare with ``s2`` :param s2: string to compare with ``s1`` :return: 0 if the strings match, a negative value if ``s1`` < ``s2``\, or a positive value if ``s1`` > ``s2`` .. function:: ascii_strdown(str: str, len: int) -> str Converts all upper case ASCII letters to lower case ASCII letters, with semantics that exactly match :obj:`~gi.repository.GLib.ascii_tolower`\. :param str: a string :param len: length of ``str`` in bytes, or ``-1`` if ``str`` is nul-terminated :return: a newly-allocated string, with all the upper case characters in ``str`` converted to lower case. (Note that this is unlike the old :obj:`~gi.repository.GLib.strdown`\, which modified the string in place.) .. function:: ascii_string_to_signed(str: str, base: int, min: int, max: int) -> ~typing.Tuple[bool, int] 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 :obj:`~gi.repository.GLib.NumberParserError.INVALID`\. If the parsed number is out of bounds - :obj:`~gi.repository.GLib.NumberParserError.OUT_OF_BOUNDS`\. See :obj:`~gi.repository.GLib.ascii_strtoll` if you have more complex needs such as parsing a string which starts with a number, but then has other characters. .. versionadded:: 2.54 :param str: a string to convert :param base: base of a parsed number :param min: a lower bound (inclusive) :param max: an upper bound (inclusive) :return: true if ``str`` was a number, false otherwise .. function:: ascii_string_to_unsigned(str: str, base: int, min: int, max: int) -> ~typing.Tuple[bool, int] 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 :obj:`~gi.repository.GLib.NumberParserError.INVALID`\. If the parsed number is out of bounds - :obj:`~gi.repository.GLib.NumberParserError.OUT_OF_BOUNDS`\. See :obj:`~gi.repository.GLib.ascii_strtoull` if you have more complex needs such as parsing a string which starts with a number, but then has other characters. .. versionadded:: 2.54 :param str: a string :param base: base of a parsed number :param min: a lower bound (inclusive) :param max: an upper bound (inclusive) :return: true if ``str`` was a number, false otherwise .. function:: ascii_strncasecmp(s1: str, s2: str, n: int) -> int 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 ``strncasecmp()`` 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 :obj:`~gi.repository.GLib.ascii_strcasecmp` applies: Use this function only on strings known to be in encodings where bytes corresponding to ASCII letters always represent themselves. :param s1: string to compare with ``s2`` :param s2: string to compare with ``s1`` :param n: number of characters to compare :return: 0 if the strings match, a negative value if ``s1`` < ``s2``\, or a positive value if ``s1`` > ``s2`` .. function:: ascii_strtod(nptr: str) -> ~typing.Tuple[float, str] Converts a string to a floating point 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 :obj:`~gi.repository.GLib.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. :param nptr: the string to convert to a numeric value :return: the converted value .. function:: ascii_strtoll(nptr: str, base: int) -> ~typing.Tuple[int, str] 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, :obj:`~gi.repository.GLib.MAXINT64` or :obj:`~gi.repository.GLib.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``\). .. versionadded:: 2.12 :param nptr: the string to convert to a numeric value :param base: to be used for the conversion, 2..36 or 0 :return: the converted value, or zero on error .. function:: ascii_strtoull(nptr: str, base: int) -> ~typing.Tuple[int, str] 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 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, :obj:`~gi.repository.GLib.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``\). .. versionadded:: 2.2 :param nptr: the string to convert to a numeric value :param base: to be used for the conversion, 2..36 or 0 :return: the converted value, or zero on error .. function:: ascii_strup(str: str, len: int) -> str Converts all lower case ASCII letters to upper case ASCII letters, with semantics that exactly match :obj:`~gi.repository.GLib.ascii_toupper`\. :param str: a string :param len: length of ``str`` in bytes, or ``-1`` if ``str`` is nul-terminated :return: a newly-allocated string, with all the lower case characters in ``str`` converted to upper case. (Note that this is unlike the old :obj:`~gi.repository.GLib.strup`\, which modified the string in place.) .. function:: ascii_tolower(c: int) -> int Convert a character to ASCII lower case. If the character is not an ASCII upper case letter, it is returned unchanged. 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. :param c: any character :return: the result of the conversion .. function:: ascii_toupper(c: int) -> int Convert a character to ASCII upper case. If the character is not an ASCII lower case letter, it is returned unchanged. 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. :param c: any character :return: the result of the conversion .. function:: ascii_xdigit_value(c: int) -> int Determines the numeric value of a character as a hexadecimal digit. If the character is not a hex digit according to :obj:`~gi.repository.GLib.ascii_isxdigit`\, ``-1`` is returned. Differs from :obj:`~gi.repository.GLib.unichar_xdigit_value` because it takes a char, so there's no worry about sign extension if characters are signed. Differs from :obj:`~gi.repository.GLib.unichar_xdigit_value` because it takes a char, so there's no worry about sign extension if characters are signed. :param c: an ASCII character :return: the numerical value of ``c`` if it is a hex digit, ``-1`` otherwise .. function:: assert_warning(log_domain: str, file: str, line: int, pretty_function: str, expression: str) -> None :param log_domain: :param file: :param line: :param pretty_function: :param expression: .. function:: assertion_message(domain: str, file: str, line: int, func: str, message: str) -> None :param domain: :param file: :param line: :param func: :param message: .. function:: assertion_message_cmpint(domain: str, file: str, line: int, func: str, expr: str, arg1: int, cmp: str, arg2: int, numtype: int) -> None :param domain: :param file: :param line: :param func: :param expr: :param arg1: :param cmp: :param arg2: :param numtype: .. function:: assertion_message_cmpstr(domain: str, file: str, line: int, func: str, expr: str, arg1: str, cmp: str, arg2: str) -> None :param domain: :param file: :param line: :param func: :param expr: :param arg1: :param cmp: :param arg2: .. function:: assertion_message_cmpstrv(domain: str, file: str, line: int, func: str, expr: str, arg1: str, arg2: str, first_wrong_idx: int) -> None :param domain: :param file: :param line: :param func: :param expr: :param arg1: :param arg2: :param first_wrong_idx: .. function:: assertion_message_error(domain: str, file: str, line: int, func: str, expr: str, error: ~gi.repository.GLib.GError, error_domain: int, error_code: int) -> None :param domain: :param file: :param line: :param func: :param expr: :param error: :param error_domain: :param error_code: .. function:: async_queue_new() -> ~gi.repository.GLib.AsyncQueue .. function:: async_queue_new_full(item_free_func: ~typing.Callable[[~typing.Any], None] | None = None) -> ~gi.repository.GLib.AsyncQueue :param item_free_func: .. function:: atexit(func: ~typing.Callable[[], None]) -> None Specifies a function to be called at normal program termination. Since GLib 2.8.2, on Windows :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.atexit` (or atexit()) except in the main executable of a program. .. deprecated:: 2.32 It is best to avoid :func:`~gi.repository.GLib.atexit`. :param func: the function to call on normal program termination. .. function:: atomic_int_add(atomic: int, val: int) -> int 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 :func:`~gi.repository.GLib.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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`int` or :obj:`int` :param val: the value to add :return: the value of ``atomic`` before the add, signed .. function:: atomic_int_and(atomic: int, val: int) -> int 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``\. .. versionadded:: 2.30 :param atomic: a pointer to a :obj:`int` or :obj:`int` :param val: the value to 'and' :return: the value of ``atomic`` before the operation, unsigned .. function:: atomic_int_compare_and_exchange(atomic: int, oldval: int, newval: int) -> bool 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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`int` or :obj:`int` :param oldval: the value to compare with :param newval: the value to conditionally replace with :return: :const:`True` if the exchange took place .. function:: atomic_int_compare_and_exchange_full(atomic: int, oldval: int, newval: int) -> ~typing.Tuple[bool, int] Compares ``atomic`` to ``oldval`` and, if equal, sets it to ``newval``\. If ``atomic`` was not equal to ``oldval`` then no change occurs. In any case the value of ``atomic`` before this operation is stored in ``preval``\. This compare and exchange is done atomically. Think of this operation as an atomic version of ``{ *preval = *atomic; if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }``\. This call acts as a full compiler and hardware memory barrier. See also :func:`~gi.repository.GLib.atomic_int_compare_and_exchange` .. versionadded:: 2.74 :param atomic: a pointer to a :obj:`int` or :obj:`int` :param oldval: the value to compare with :param newval: the value to conditionally replace with :return: :const:`True` if the exchange took place .. function:: atomic_int_dec_and_test(atomic: int) -> bool 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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`int` or :obj:`int` :return: :const:`True` if the resultant value is zero .. function:: atomic_int_exchange(atomic: int, newval: int) -> int Sets the ``atomic`` to ``newval`` and returns the old value from ``atomic``\. This exchange is done atomically. 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. .. versionadded:: 2.74 :param atomic: a pointer to a :obj:`int` or :obj:`int` :param newval: the value to replace with :return: the value of ``atomic`` before the exchange, signed .. function:: atomic_int_exchange_and_add(atomic: int, val: int) -> int This function existed before :func:`~gi.repository.GLib.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. .. versionadded:: 2.4 .. deprecated:: 2.30 Use :func:`~gi.repository.GLib.atomic_int_add` instead. :param atomic: a pointer to a :obj:`int` :param val: the value to add :return: the value of ``atomic`` before the add, signed .. function:: atomic_int_get(atomic: int) -> int 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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`int` or :obj:`int` :return: the value of the integer .. function:: atomic_int_inc(atomic: int) -> None 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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`int` or :obj:`int` .. function:: atomic_int_or(atomic: int, val: int) -> int 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``\. .. versionadded:: 2.30 :param atomic: a pointer to a :obj:`int` or :obj:`int` :param val: the value to 'or' :return: the value of ``atomic`` before the operation, unsigned .. function:: atomic_int_set(atomic: int, newval: int) -> None 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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`int` or :obj:`int` :param newval: a new value to store .. function:: atomic_int_xor(atomic: int, val: int) -> int 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``\. .. versionadded:: 2.30 :param atomic: a pointer to a :obj:`int` or :obj:`int` :param val: the value to 'xor' :return: the value of ``atomic`` before the operation, unsigned .. function:: atomic_pointer_add(atomic: ~typing.Any, val: int) -> int 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``\. In GLib 2.80, the return type was changed from :obj:`~gi.repository.gssize` to :obj:`int` to add support for platforms with 128-bit pointers. This should not affect existing code. .. versionadded:: 2.30 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param val: the value to add :return: the value of ``atomic`` before the add, signed .. function:: atomic_pointer_and(atomic: ~typing.Any, val: int) -> int 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``\. In GLib 2.80, the return type was changed from :obj:`~gi.repository.gsize` to :obj:`int` to add support for platforms with 128-bit pointers. This should not affect existing code. .. versionadded:: 2.30 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param val: the value to 'and' :return: the value of ``atomic`` before the operation, unsigned .. function:: atomic_pointer_compare_and_exchange(atomic: ~typing.Any, oldval: ~typing.Any = None, newval: ~typing.Any = None) -> bool 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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param oldval: the value to compare with :param newval: the value to conditionally replace with :return: :const:`True` if the exchange took place .. function:: atomic_pointer_compare_and_exchange_full(atomic: ~typing.Any, oldval: ~typing.Any = None, newval: ~typing.Any = None) -> ~typing.Tuple[bool, ~typing.Any] Compares ``atomic`` to ``oldval`` and, if equal, sets it to ``newval``\. If ``atomic`` was not equal to ``oldval`` then no change occurs. In any case the value of ``atomic`` before this operation is stored in ``preval``\. This compare and exchange is done atomically. Think of this operation as an atomic version of ``{ *preval = *atomic; if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }``\. This call acts as a full compiler and hardware memory barrier. See also :func:`~gi.repository.GLib.atomic_pointer_compare_and_exchange` .. versionadded:: 2.74 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param oldval: the value to compare with :param newval: the value to conditionally replace with :return: :const:`True` if the exchange took place .. function:: atomic_pointer_exchange(atomic: ~typing.Any = None, newval: ~typing.Any = None) -> ~typing.Any | None Sets the ``atomic`` to ``newval`` and returns the old value from ``atomic``\. This exchange is done atomically. 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. .. versionadded:: 2.74 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param newval: the value to replace with :return: the value of ``atomic`` before the exchange .. function:: atomic_pointer_get(atomic: ~typing.Any) -> ~typing.Any | None 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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :return: the value of the pointer .. function:: atomic_pointer_or(atomic: ~typing.Any, val: int) -> int 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``\. In GLib 2.80, the return type was changed from :obj:`~gi.repository.gsize` to :obj:`int` to add support for platforms with 128-bit pointers. This should not affect existing code. .. versionadded:: 2.30 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param val: the value to 'or' :return: the value of ``atomic`` before the operation, unsigned .. function:: atomic_pointer_set(atomic: ~typing.Any, newval: ~typing.Any = None) -> None 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``\. .. versionadded:: 2.4 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param newval: a new value to store .. function:: atomic_pointer_xor(atomic: ~typing.Any, val: int) -> int 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``\. In GLib 2.80, the return type was changed from :obj:`~gi.repository.gsize` to :obj:`int` to add support for platforms with 128-bit pointers. This should not affect existing code. .. versionadded:: 2.30 :param atomic: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param val: the value to 'xor' :return: the value of ``atomic`` before the operation, unsigned .. function:: atomic_rc_box_acquire(mem_block: ~typing.Any) -> ~typing.Any Atomically acquires a reference on the data pointed by ``mem_block``\. .. versionadded:: 2.58 :param mem_block: a pointer to reference counted data :return: a pointer to the data, with its reference count increased .. function:: atomic_rc_box_alloc(block_size: int) -> ~typing.Any 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. .. versionadded:: 2.58 :param block_size: the size of the allocation, must be greater than 0 :return: a pointer to the allocated memory .. function:: atomic_rc_box_alloc0(block_size: int) -> ~typing.Any 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. .. versionadded:: 2.58 :param block_size: the size of the allocation, must be greater than 0 :return: a pointer to the allocated memory .. function:: atomic_rc_box_dup(block_size: int, mem_block: ~typing.Any) -> ~typing.Any Allocates a new block of data with atomic reference counting semantics, and copies ``block_size`` bytes of ``mem_block`` into it. .. versionadded:: 2.58 :param block_size: the number of bytes to copy, must be greater than 0 :param mem_block: the memory to copy :return: a pointer to the allocated memory .. function:: atomic_rc_box_get_size(mem_block: ~typing.Any) -> int Retrieves the size of the reference counted data pointed by ``mem_block``\. .. versionadded:: 2.58 :param mem_block: a pointer to reference counted data :return: the size of the data, in bytes .. function:: atomic_rc_box_release(mem_block: ~typing.Any) -> None 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``\. .. versionadded:: 2.58 :param mem_block: a pointer to reference counted data .. function:: atomic_rc_box_release_full(mem_block: ~typing.Any, clear_func: ~typing.Callable[[~typing.Any], None]) -> None 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``\. .. versionadded:: 2.58 :param mem_block: a pointer to reference counted data :param clear_func: a function to call when clearing the data .. function:: base64_decode(text: str) -> list[int] 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. .. versionadded:: 2.12 :param text: zero-terminated string with base64 text to decode :return: newly allocated buffer containing the binary data that ``text`` represents. The returned buffer must be freed with :func:`~gi.repository.GLib.free`. .. function:: base64_decode_inplace(text: list[int]) -> ~typing.Tuple[int, list[int]] Decode a sequence of Base-64 encoded text into binary data by overwriting the input data. .. versionadded:: 2.20 :param text: zero-terminated string with base64 text to decode :return: The binary data that ``text`` responds. This pointer is the same as the input ``text``\. .. function:: base64_encode(data: list[int] | None = None) -> str Encode a sequence of binary data into its Base-64 stringified representation. .. versionadded:: 2.12 :param data: the binary data to encode :return: a newly allocated, zero-terminated Base-64 encoded string representing ``data``\. The returned string must be freed with :func:`~gi.repository.GLib.free`. .. function:: base64_encode_close(break_lines: bool, state: int, save: int) -> ~typing.Tuple[int, list[int], int, int] Flush the status from a sequence of calls to :func:`~gi.repository.GLib.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. .. versionadded:: 2.12 :param break_lines: whether to break long lines :param state: Saved state from :func:`~gi.repository.GLib.base64_encode_step` :param save: Saved state from :func:`~gi.repository.GLib.base64_encode_step` :return: The number of bytes of output that was written .. function:: base64_encode_step(in_: list[int], break_lines: bool, state: int, save: int) -> ~typing.Tuple[int, list[int], int, int] 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 :func:`~gi.repository.GLib.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. .. versionadded:: 2.12 :param in_: :param break_lines: whether to break long lines :param state: Saved state between steps, initialize to 0 :param save: Saved state between steps, initialize to 0 :return: The number of bytes of output that was written .. function:: basename(file_name: str) -> str Gets the name of the file without any leading directory components. It returns a pointer into the given file name string. .. deprecated:: 2.2 Use :func:`~gi.repository.GLib.path_get_basename` instead, but notice that :func:`~gi.repository.GLib.path_get_basename` allocates new memory for the returned string, unlike this function which returns a pointer into the argument. :param file_name: the name of the file :return: the name of the file without any leading directory components .. function:: bit_lock(address: int, lock_bit: int) -> None Sets the indicated ``lock_bit`` in ``address``\. If the bit is already set, this call will block until :func:`~gi.repository.GLib.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``\. .. versionadded:: 2.24 :param address: a pointer to an integer :param lock_bit: a bit value between 0 and 31 .. function:: bit_nth_lsf(mask: int, nth_bit: int) -> int 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(:obj:`~gi.repository.gulong`\) \* 8 - 1 (31 or 63, usually). To start searching from the 0th bit, set ``nth_bit`` to -1. :param mask: a :obj:`~gi.repository.gulong` containing flags :param nth_bit: the index of the bit to start the search from :return: the index of the first bit set which is higher than ``nth_bit``\, or -1 if no higher bits are set .. function:: bit_nth_msf(mask: int, nth_bit: int) -> int 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(:obj:`~gi.repository.gulong`\) \* 8 - 1 (31 or 63, usually). To start searching from the last bit, set ``nth_bit`` to -1 or GLIB_SIZEOF_LONG \* 8. :param mask: a :obj:`~gi.repository.gulong` containing flags :param nth_bit: the index of the bit to start the search from :return: the index of the first bit set which is lower than ``nth_bit``\, or -1 if no lower bits are set .. function:: bit_storage(number: int) -> int Gets the number of bits used to hold ``number``\, e.g. if ``number`` is 4, 3 bits are needed. :param number: a :obj:`int` :return: the number of bits used to hold ``number`` .. function:: bit_trylock(address: int, lock_bit: int) -> bool Sets the indicated ``lock_bit`` in ``address``\, returning :const:`True` if successful. If the bit is already set, returns :const:`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``\. .. versionadded:: 2.24 :param address: a pointer to an integer :param lock_bit: a bit value between 0 and 31 :return: :const:`True` if the lock was acquired .. function:: bit_unlock(address: int, lock_bit: int) -> None Clears the indicated ``lock_bit`` in ``address``\. If another thread is currently blocked in :func:`~gi.repository.GLib.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``\. .. versionadded:: 2.24 :param address: a pointer to an integer :param lock_bit: a bit value between 0 and 31 .. function:: blow_chunks() -> None .. function:: bookmark_file_error_quark() -> int .. function:: build_filenamev(args: list[str]) -> str Creates a filename from a vector of elements using the correct separator for the current platform. This function behaves exactly like :func:`~gi.repository.GLib.build_filename`, but takes the path elements as a string array, instead of varargs. This function is mainly meant for language bindings. If you are building a path programmatically you may want to use :obj:`~gi.repository.GLib.PathBuf` instead. .. versionadded:: 2.8 :param args: :const:`None`-terminated array of strings containing the path elements. :return: the newly allocated path .. function:: build_pathv(separator: str, args: list[str]) -> str Behaves exactly like :func:`~gi.repository.GLib.build_path`, but takes the path elements as a string array, instead of variadic arguments. This function is mainly meant for language bindings. .. versionadded:: 2.8 :param separator: a string used to separator the elements of the path. :param args: :const:`None`-terminated array of strings containing the path elements. :return: a newly-allocated string that must be freed with :func:`~gi.repository.GLib.free`. .. function:: byte_array_append(array: list[int], data: int, len: int) -> list[int] :param array: :param data: :param len: .. function:: byte_array_free(array: list[int], free_segment: bool) -> int :param array: :param free_segment: .. function:: byte_array_free_to_bytes(array: list[int]) -> ~gi.repository.GLib.Bytes :param array: .. function:: byte_array_new() -> list[int] .. function:: byte_array_new_take(data: list[int]) -> list[int] :param data: .. function:: byte_array_prepend(array: list[int], data: int, len: int) -> list[int] :param array: :param data: :param len: .. function:: byte_array_remove_index(array: list[int], index_: int) -> list[int] :param array: :param index_: .. function:: byte_array_remove_index_fast(array: list[int], index_: int) -> list[int] :param array: :param index_: .. function:: byte_array_remove_range(array: list[int], index_: int, length: int) -> list[int] :param array: :param index_: :param length: .. function:: byte_array_set_size(array: list[int], length: int) -> list[int] :param array: :param length: .. function:: byte_array_sized_new(reserved_size: int) -> list[int] :param reserved_size: .. function:: byte_array_sort(array: list[int], compare_func: ~typing.Callable[[~typing.Any, ~typing.Any], int]) -> None :param array: :param compare_func: .. function:: byte_array_sort_with_data(array: list[int], compare_func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], user_data: ~typing.Any = None) -> None :param array: :param compare_func: :param user_data: .. function:: canonicalize_filename(filename: str, relative_to: str | None = None) -> str 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 :const:`None`. If ``relative_to`` is :const:`None`, it'll fallback to :func:`~gi.repository.GLib.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. .. versionadded:: 2.58 :param filename: the name of the file :param relative_to: the relative directory, or :const:`None` to use the current working directory :return: a newly allocated string with the canonical file path .. function:: chdir(path: str) -> int 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(). .. versionadded:: 2.8 :param path: a pathname in the GLib file name encoding (UTF-8 on Windows) :return: 0 on success, -1 if an error occurred. .. function:: check_version(required_major: int, required_minor: int, required_micro: int) -> str | None Checks that the GLib library in use is compatible with the given version. Generally you would pass in the constants :const:`~gi.repository.GLib.MAJOR_VERSION`, :const:`~gi.repository.GLib.MINOR_VERSION`, :const:`~gi.repository.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.) .. versionadded:: 2.6 :param required_major: the required major version :param required_minor: the required minor version :param required_micro: the required micro version :return: :const:`None` if the GLib library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GLib and must not be modified or freed. .. function:: checksum_type_get_length(checksum_type: ~gi.repository.GLib.ChecksumType) -> int :param checksum_type: .. function:: child_watch_add(*args, **kwargs) Sets a function to be called when the child indicated by ``pid`` exits, at a default priority, :obj:`~gi.repository.GLib.PRIORITY_DEFAULT`\. If you obtain ``pid`` from :obj:`~gi.repository.GLib.spawn_async` or :obj:`~gi.repository.GLib.spawn_async_with_pipes` you will need to pass :const:`~gi.repository.GLib.SpawnFlags.DO_NOT_REAP_CHILD` as flag to the spawn function for the child watching to work. Note that on platforms where :obj:`~gi.repository.GLib.Pid` must be explicitly closed (see :obj:`~gi.repository.GLib.spawn_close_pid`\) ``pid`` must not be closed while the source is still active. Typically, you will want to call :obj:`~gi.repository.GLib.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 :obj:`~gi.repository.GLib.child_watch_source_new` apply to this function. This internally creates a main loop source using :obj:`~gi.repository.GLib.child_watch_source_new` and attaches it to the main loop context using :obj:`~gi.repository.GLib.Source.attach`\. You can do these steps manually if you need greater control. .. versionadded:: 2.4 :param args: :param kwargs: :return: the ID (greater than 0) of the event source. .. function:: child_watch_source_new(pid: int) -> ~gi.repository.GLib.Source Creates a new child_watch source. The source will not initially be associated with any :obj:`~gi.repository.GLib.MainContext` and must be added to one with :obj:`~gi.repository.GLib.Source.attach` before it will be executed. Note that child watch sources can only be used in conjunction with ``g_spawn...`` when the :const:`~gi.repository.GLib.SpawnFlags.DO_NOT_REAP_CHILD` flag is used. Note that on platforms where :obj:`~gi.repository.GLib.Pid` must be explicitly closed (see :obj:`~gi.repository.GLib.spawn_close_pid`\) ``pid`` must not be closed while the source is still active. Typically, you will want to call :obj:`~gi.repository.GLib.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 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 ``SIGCHLD`` - Before 2.78, the application could not send a signal (``kill()``\) to the watched ``pid`` in a race free manner. Since 2.78, you can do that while the associated :obj:`~gi.repository.GLib.MainContext` is acquired. - Before 2.78, even after destroying the :obj:`~gi.repository.GLib.Source`\, you could not be sure that ``pid`` wasn't already reaped. Hence, it was also not safe to ``kill()`` or ``waitpid()`` on the process ID after the child watch source was gone. Destroying the source before it fired made it impossible to reliably reap the process. 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. .. versionadded:: 2.4 :param pid: process to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child). :return: the newly-created child watch source .. function:: chmod(filename: str, mode: int) -> int A wrapper for the POSIX chmod() function. The chmod() function is used to set the permissions of a file system object. On Windows the file protection mechanism is not at all POSIX-like, and the underlying chmod() function in the C library just sets or clears the FAT-style READONLY attribute. It does not touch any ACL. Software that needs to manage file permissions on Windows exactly should use the Win32 API. See your C library manual for more details about chmod(). .. versionadded:: 2.8 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param mode: as in chmod() :return: 0 if the operation succeeded, -1 on error .. function:: clear_error() -> None If ``err`` or ``err`` is :const:`None`, does nothing. Otherwise, calls :func:`~gi.repository.GLib.Error.free` on ``err`` and sets ``err`` to :const:`None`. .. function:: close(fd: int) -> bool This wraps the close() call. In case of error, %errno will be preserved, but the error will also be stored as a :obj:`~gi.repository.GLib.Error` in ``error``\. In case of success, %errno is undefined. Besides using :obj:`~gi.repository.GLib.Error`\, 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. It is a bug to call this function with an invalid file descriptor. On POSIX platforms since GLib 2.76, this function is async-signal safe if (and only if) ``error`` is :const:`None` and ``fd`` is a valid open file descriptor. This makes it safe to call from a signal handler or a :obj:`~gi.repository.GLib.SpawnChildSetupFunc` under those conditions. See ```signal(7)`` `__ and ```signal-safety(7)`` `__ for more details. .. versionadded:: 2.36 :param fd: A file descriptor :return: :const:`True` on success, :const:`False` if there was an error. .. function:: closefrom(lowfd: int) -> int Close every file descriptor equal to or greater than ``lowfd``\. Typically ``lowfd`` will be 3, to leave standard input, standard output and standard error open. This is the same as Linux ``close_range (lowfd, ~0U, 0)``\, but portable to other OSs and to older versions of Linux. Equivalently, it is the same as BSD ``closefrom (lowfd)``\, but portable, and async-signal-safe on all OSs. This function is async-signal safe, making it safe to call from a signal handler or a [callback``GLib``\.SpawnChildSetupFunc], as long as ``lowfd`` is non-negative. See ```signal(7)`` `__ and ```signal-safety(7)`` `__ for more details. .. versionadded:: 2.80 :param lowfd: Minimum fd to close, which must be non-negative :return: 0 on success, -1 with errno set on error .. function:: compute_checksum_for_bytes(checksum_type: ~gi.repository.GLib.ChecksumType, data: ~gi.repository.GLib.Bytes) -> str | None Computes the checksum for a binary ``data``\. This is a convenience wrapper for :func:`~gi.repository.GLib.Checksum.new`, :func:`~gi.repository.GLib.Checksum.get_string` and :func:`~gi.repository.GLib.Checksum.free`. The hexadecimal string returned will be in lower case. .. versionadded:: 2.34 :param checksum_type: a :obj:`~gi.repository.GLib.ChecksumType` :param data: binary blob to compute the digest of :return: the digest of the binary data as a string in hexadecimal, or :const:`None` if :func:`~gi.repository.GLib.Checksum.new` fails for ``checksum_type``\. The returned string should be freed with :func:`~gi.repository.GLib.free` when done using it. .. function:: compute_checksum_for_data(checksum_type: ~gi.repository.GLib.ChecksumType, data: list[int]) -> str | None Computes the checksum for a binary ``data`` of ``length``\. This is a convenience wrapper for :func:`~gi.repository.GLib.Checksum.new`, :func:`~gi.repository.GLib.Checksum.get_string` and :func:`~gi.repository.GLib.Checksum.free`. The hexadecimal string returned will be in lower case. .. versionadded:: 2.16 :param checksum_type: a :obj:`~gi.repository.GLib.ChecksumType` :param data: binary blob to compute the digest of :return: the digest of the binary data as a string in hexadecimal, or :const:`None` if :func:`~gi.repository.GLib.Checksum.new` fails for ``checksum_type``\. The returned string should be freed with :func:`~gi.repository.GLib.free` when done using it. .. function:: compute_checksum_for_string(checksum_type: ~gi.repository.GLib.ChecksumType, str: str, length: int) -> str | None Computes the checksum of a string. The hexadecimal string returned will be in lower case. .. versionadded:: 2.16 :param checksum_type: a :obj:`~gi.repository.GLib.ChecksumType` :param str: the string to compute the checksum of :param length: the length of the string, or -1 if the string is null-terminated. :return: the checksum as a hexadecimal string, or :const:`None` if :func:`~gi.repository.GLib.Checksum.new` fails for ``checksum_type``\. The returned string should be freed with :func:`~gi.repository.GLib.free` when done using it. .. function:: compute_hmac_for_bytes(digest_type: ~gi.repository.GLib.ChecksumType, key: ~gi.repository.GLib.Bytes, data: ~gi.repository.GLib.Bytes) -> str Computes the HMAC for a binary ``data``\. This is a convenience wrapper for :func:`~gi.repository.GLib.Hmac.new`, :func:`~gi.repository.GLib.Hmac.get_string` and :func:`~gi.repository.GLib.Hmac.unref`. The hexadecimal string returned will be in lower case. .. versionadded:: 2.50 :param digest_type: a :obj:`~gi.repository.GLib.ChecksumType` to use for the HMAC :param key: the key to use in the HMAC :param data: binary blob to compute the HMAC of :return: the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with :func:`~gi.repository.GLib.free` when done using it. .. function:: compute_hmac_for_data(digest_type: ~gi.repository.GLib.ChecksumType, key: list[int], data: list[int]) -> str Computes the HMAC for a binary ``data`` of ``length``\. This is a convenience wrapper for :func:`~gi.repository.GLib.Hmac.new`, :func:`~gi.repository.GLib.Hmac.get_string` and :func:`~gi.repository.GLib.Hmac.unref`. The hexadecimal string returned will be in lower case. .. versionadded:: 2.30 :param digest_type: a :obj:`~gi.repository.GLib.ChecksumType` to use for the HMAC :param key: the key to use in the HMAC :param data: binary blob to compute the HMAC of :return: the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with :func:`~gi.repository.GLib.free` when done using it. .. function:: compute_hmac_for_string(digest_type: ~gi.repository.GLib.ChecksumType, key: list[int], str: str, length: int) -> str Computes the HMAC for a string. The hexadecimal string returned will be in lower case. .. versionadded:: 2.30 :param digest_type: a :obj:`~gi.repository.GLib.ChecksumType` to use for the HMAC :param key: the key to use in the HMAC :param str: the string to compute the HMAC for :param length: the length of the string, or -1 if the string is nul-terminated :return: the HMAC as a hexadecimal string. The returned string should be freed with :func:`~gi.repository.GLib.free` when done using it. .. function:: convert(str: list[int], to_codeset: str, from_codeset: str) -> ~typing.Tuple[list[int], int] Converts a string from one character set to another. Note that you should use :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.convert`, :func:`~gi.repository.GLib.convert_with_iconv` or :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.str_to_ascii` instead. :param str: the string to convert. :param to_codeset: name of character set into which to convert ``str`` :param from_codeset: character set of ``str``\. :return: If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with :func:`~gi.repository.GLib.free`. Otherwise :const:`None` and ``error`` will be set. .. function:: convert_error_quark() -> int .. function:: convert_with_fallback(str: list[int], to_codeset: str, from_codeset: str, fallback: str) -> ~typing.Tuple[list[int], int] 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 :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.convert`, :func:`~gi.repository.GLib.convert_with_iconv` or :func:`~gi.repository.GLib.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.) :param str: the string to convert. :param to_codeset: name of character set into which to convert ``str`` :param from_codeset: character set of ``str``\. :param fallback: 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 :const:`None`, characters not in the target encoding will be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. :return: If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with :func:`~gi.repository.GLib.free`. Otherwise :const:`None` and ``error`` will be set. .. function:: creat(filename: str, mode: int) -> int A wrapper for the POSIX creat() function. The creat() function is used to convert a pathname into a file descriptor, creating a file if necessary. On POSIX systems file descriptors are implemented by the operating system. On Windows, it's the C library that implements creat() and file descriptors. The actual Windows API for opening files is different, see MSDN documentation for CreateFile(). The Win32 API uses file handles, which are more randomish integers, not small integers like file descriptors. Because file descriptors are specific to the C library on Windows, the file descriptor returned by this function makes sense only to functions in the same C library. Thus if the GLib-using code uses a different C library than GLib does, the file descriptor returned by this function cannot be passed to C library functions like write() or read(). See your C library manual for more details about creat(). .. versionadded:: 2.8 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param mode: as in creat() :return: a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from creat(). .. function:: datalist_foreach(datalist: ~gi.repository.GLib.Data, func: ~typing.Callable[[int, ~typing.Any, ~typing.Any], None], user_data: ~typing.Any = None) -> None Calls the given function for each data element of the datalist. The function is called with each data element's :obj:`~gi.repository.GLib.Quark` 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 :func:`~gi.repository.GLib.datalist_foreach` call, other than skipping over elements that are removed. :param datalist: a datalist. :param func: the function to call for each data element. :param user_data: user data to pass to the function. .. function:: datalist_get_data(datalist: ~gi.repository.GLib.Data, key: str) -> ~typing.Any | None Gets a data element, using its string identifier. This is slower than :func:`~gi.repository.GLib.datalist_id_get_data` because it compares strings. :param datalist: a datalist. :param key: the string identifying a data element. :return: the data element, or :const:`None` if it is not found. .. function:: datalist_get_flags(datalist: ~gi.repository.GLib.Data) -> int Gets flags values packed in together with the datalist. See :func:`~gi.repository.GLib.datalist_set_flags`. .. versionadded:: 2.8 :param datalist: pointer to the location that holds a list :return: the flags of the datalist .. function:: datalist_id_get_data(datalist: ~gi.repository.GLib.Data, key_id: int) -> ~typing.Any | None Retrieves the data element corresponding to ``key_id``\. :param datalist: a datalist. :param key_id: the :obj:`~gi.repository.GLib.Quark` identifying a data element. :return: the data element, or :const:`None` if it is not found. .. function:: datalist_id_remove_multiple(datalist: ~gi.repository.GLib.Data, keys: list[int]) -> None Removes multiple keys from a datalist. This is more efficient than calling :func:`~gi.repository.GLib.datalist_id_remove_data` multiple times in a row. Before 2.80, ``n_keys`` had to be not larger than 16. Now it can be larger, but note that GData does a linear search, so an excessive number of keys will perform badly. .. versionadded:: 2.74 :param datalist: a datalist :param keys: keys to remove .. function:: datalist_set_flags(datalist: ~gi.repository.GLib.Data, flags: int) -> None 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.) .. versionadded:: 2.8 :param datalist: pointer to the location that holds a list :param flags: the flags to turn on. The values of the flags are restricted by :const:`~gi.repository.GLib.DATALIST_FLAGS_MASK` (currently 3; giving two possible boolean flags). A value for ``flags`` that doesn't fit within the mask is an error. .. function:: datalist_unset_flags(datalist: ~gi.repository.GLib.Data, flags: int) -> None Turns off flag values for a data list. See :func:`~gi.repository.GLib.datalist_unset_flags` .. versionadded:: 2.8 :param datalist: pointer to the location that holds a list :param flags: the flags to turn off. The values of the flags are restricted by :const:`~gi.repository.GLib.DATALIST_FLAGS_MASK` (currently 3: giving two possible boolean flags). A value for ``flags`` that doesn't fit within the mask is an error. .. function:: dataset_destroy(dataset_location: ~typing.Any) -> None Destroys the dataset, freeing all memory allocated, and calling any destroy functions set for data elements. :param dataset_location: the location identifying the dataset. .. function:: dataset_foreach(dataset_location: ~typing.Any, func: ~typing.Callable[[int, ~typing.Any, ~typing.Any], None], user_data: ~typing.Any = None) -> None 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 :func:`~gi.repository.GLib.dataset_foreach` call, other than skipping over elements that are removed. :param dataset_location: the location identifying the dataset. :param func: the function to call for each data element. :param user_data: user data to pass to the function. .. function:: dataset_id_get_data(dataset_location: ~typing.Any, key_id: int) -> ~typing.Any | None Gets the data element corresponding to a :obj:`~gi.repository.GLib.Quark`\. :param dataset_location: the location identifying the dataset. :param key_id: the :obj:`~gi.repository.GLib.Quark` id to identify the data element. :return: the data element corresponding to the :obj:`~gi.repository.GLib.Quark`\, or :const:`None` if it is not found. .. function:: date_get_days_in_month(month: ~gi.repository.GLib.DateMonth, year: int) -> int :param month: :param year: .. function:: date_get_monday_weeks_in_year(year: int) -> int :param year: .. function:: date_get_sunday_weeks_in_year(year: int) -> int :param year: .. function:: date_is_leap_year(year: int) -> bool :param year: .. function:: date_strftime(s: str, slen: int, format: str, date: ~gi.repository.GLib.Date) -> int :param s: :param slen: :param format: :param date: .. function:: date_valid_day(day: int) -> bool :param day: .. function:: date_valid_dmy(day: int, month: ~gi.repository.GLib.DateMonth, year: int) -> bool :param day: :param month: :param year: .. function:: date_valid_julian(julian_date: int) -> bool :param julian_date: .. function:: date_valid_month(month: ~gi.repository.GLib.DateMonth) -> bool :param month: .. function:: date_valid_weekday(weekday: ~gi.repository.GLib.DateWeekday) -> bool :param weekday: .. function:: date_valid_year(year: int) -> bool :param year: .. function:: dcgettext(domain: str | None, msgid: str, category: int) -> str This is a variant of :func:`~gi.repository.GLib.dgettext` that allows specifying a locale category instead of always using ``LC_MESSAGES``\. See :func:`~gi.repository.GLib.dgettext` for more information about how this functions differs from calling dcgettext() directly. .. versionadded:: 2.26 :param domain: the translation domain to use, or :const:`None` to use the domain set with textdomain() :param msgid: message to translate :param category: a locale category :return: the translated string for the given locale category .. function:: dgettext(domain: str | None, msgid: str) -> str 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 :func:`~gi.repository.GLib.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 :const:`None` - 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. .. versionadded:: 2.18 :param domain: the translation domain to use, or :const:`None` to use the domain set with textdomain() :param msgid: message to translate :return: The translated string .. function:: dir_make_tmp(tmpl: str | None = None) -> str :param tmpl: .. function:: direct_equal(v1: ~typing.Any = None, v2: ~typing.Any = None) -> bool Compares two :obj:`~gi.repository.gpointer` arguments and returns :const:`True` if they are equal. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``key_equal_func`` parameter, when using opaque pointers compared by pointer value as keys in a :obj:`~gi.repository.GLib.HashTable`\. This equality function is also appropriate for keys that are integers stored in pointers, such as ``GINT_TO_POINTER (n)``\. :param v1: a key :param v2: a key to compare with ``v1`` :return: :const:`True` if the two keys match. .. function:: direct_hash(v: ~typing.Any = None) -> int Converts a gpointer to a hash value. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``hash_func`` parameter, when using opaque pointers compared by pointer value as keys in a :obj:`~gi.repository.GLib.HashTable`\. This hash function is also appropriate for keys that are integers stored in pointers, such as ``GINT_TO_POINTER (n)``\. :param v: a :obj:`~gi.repository.gpointer` key :return: a hash value corresponding to the key. .. function:: dngettext(domain: str | None, msgid: str, msgid_plural: str, n: int) -> str 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 :func:`~gi.repository.GLib.dgettext` for details of how this differs from dngettext() proper. .. versionadded:: 2.18 :param domain: the translation domain to use, or :const:`None` to use the domain set with textdomain() :param msgid: message to translate :param msgid_plural: plural form of the message :param n: the quantity for which translation is needed :return: The translated string .. function:: double_equal(v1: ~typing.Any, v2: ~typing.Any) -> bool Compares the two :obj:`float` values being pointed to and returns :const:`True` if they are equal. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``key_equal_func`` parameter, when using non-:const:`None` pointers to doubles as keys in a :obj:`~gi.repository.GLib.HashTable`\. .. versionadded:: 2.22 :param v1: a pointer to a :obj:`float` key :param v2: a pointer to a :obj:`float` key to compare with ``v1`` :return: :const:`True` if the two keys match. .. function:: double_hash(v: ~typing.Any) -> int Converts a pointer to a :obj:`float` to a hash value. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``hash_func`` parameter, It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``hash_func`` parameter, when using non-:const:`None` pointers to doubles as keys in a :obj:`~gi.repository.GLib.HashTable`\. .. versionadded:: 2.22 :param v: a pointer to a :obj:`float` key :return: a hash value corresponding to the key. .. function:: dpgettext(domain: str | None, msgctxtid: str, msgidoffset: int) -> str This function is a variant of :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.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. .. versionadded:: 2.16 :param domain: the translation domain to use, or :const:`None` to use the domain set with textdomain() :param msgctxtid: a combined message context and message id, separated by a \004 character :param msgidoffset: the offset of the message id in ``msgctxid`` :return: The translated string .. function:: dpgettext2(domain: str | None, context: str, msgid: str) -> str This function is a variant of :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.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. .. versionadded:: 2.18 :param domain: the translation domain to use, or :const:`None` to use the domain set with textdomain() :param context: the message context :param msgid: the message :return: The translated string .. function:: environ_getenv(envp: list[str] | None, variable: str) -> str | None Returns the value of the environment variable ``variable`` in the provided list ``envp``\. .. versionadded:: 2.32 :param envp: an environment list (eg, as returned from :func:`~gi.repository.GLib.get_environ`), or :const:`None` for an empty environment list :param variable: the environment variable to get :return: the value of the environment variable, or :const:`None` if the environment variable is not set in ``envp``\. The returned string is owned by ``envp``\, and will be freed if ``variable`` is set or unset again. .. function:: environ_setenv(envp: list[str] | None, variable: str, value: str, overwrite: bool) -> list[str] Sets the environment variable ``variable`` in the provided list ``envp`` to ``value``\. .. versionadded:: 2.32 :param envp: an environment list that can be freed using :func:`~gi.repository.GLib.strfreev` (e.g., as returned from :func:`~gi.repository.GLib.get_environ`), or :const:`None` for an empty environment list :param variable: the environment variable to set, must not contain '=' :param value: the value for to set the variable to :param overwrite: whether to change the variable if it already exists :return: the updated environment list. Free it using :func:`~gi.repository.GLib.strfreev`. .. function:: environ_unsetenv(envp: list[str] | None, variable: str) -> list[str] Removes the environment variable ``variable`` from the provided environment ``envp``\. .. versionadded:: 2.32 :param envp: an environment list that can be freed using :func:`~gi.repository.GLib.strfreev` (e.g., as returned from :func:`~gi.repository.GLib.get_environ`), or :const:`None` for an empty environment list :param variable: the environment variable to remove, must not contain '=' :return: the updated environment list. Free it using :func:`~gi.repository.GLib.strfreev`. .. function:: error_domain_register(error_type_name: str, error_type_private_size: int, error_type_init: ~typing.Callable[[~gi.repository.GLib.GError], None], error_type_copy: ~typing.Callable[[~gi.repository.GLib.GError, ~gi.repository.GLib.GError], None], error_type_clear: ~typing.Callable[[~gi.repository.GLib.GError], None]) -> int :param error_type_name: :param error_type_private_size: :param error_type_init: :param error_type_copy: :param error_type_clear: .. function:: error_domain_register_static(error_type_name: str, error_type_private_size: int, error_type_init: ~typing.Callable[[~gi.repository.GLib.GError], None], error_type_copy: ~typing.Callable[[~gi.repository.GLib.GError, ~gi.repository.GLib.GError], None], error_type_clear: ~typing.Callable[[~gi.repository.GLib.GError], None]) -> int :param error_type_name: :param error_type_private_size: :param error_type_init: :param error_type_copy: :param error_type_clear: .. function:: fdwalk_set_cloexec(lowfd: int) -> int Mark every file descriptor equal to or greater than ``lowfd`` to be closed at the next ``execve()`` or similar, as if via the ``FD_CLOEXEC`` flag. Typically ``lowfd`` will be 3, to leave standard input, standard output and standard error open after exec. This is the same as Linux ``close_range (lowfd, ~0U, CLOSE_RANGE_CLOEXEC)``\, but portable to other OSs and to older versions of Linux. This function is async-signal safe, making it safe to call from a signal handler or a [callback``GLib``\.SpawnChildSetupFunc], as long as ``lowfd`` is non-negative. See ```signal(7)`` `__ and ```signal-safety(7)`` `__ for more details. .. versionadded:: 2.80 :param lowfd: Minimum fd to act on, which must be non-negative :return: 0 on success, -1 with errno set on error .. function:: file_error_from_errno(err_no: int) -> ~gi.repository.GLib.FileError Gets a :obj:`~gi.repository.GLib.FileError` constant based on the passed-in ``err_no``\. For example, if you pass in ``EEXIST`` this function returns :const:`~gi.repository.GLib.FileError.EXIST`. Unlike ``errno`` values, you can portably assume that all :obj:`~gi.repository.GLib.FileError` values will exist. Normally a :obj:`~gi.repository.GLib.FileError` value goes into a :obj:`~gi.repository.GLib.Error` returned from a function that manipulates files. So you would use :func:`~gi.repository.GLib.file_error_from_errno` when constructing a :obj:`~gi.repository.GLib.Error`\. :param err_no: an "errno" value :return: :obj:`~gi.repository.GLib.FileError` corresponding to the given ``err_no`` .. function:: file_error_quark() -> int .. function:: file_get_contents(filename: str) -> ~typing.Tuple[bool, list[int]] Reads an entire file into allocated memory, with good error checking. If the call was successful, it returns :const:`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 :const:`None` for the ``length`` argument. If the call was not successful, it returns :const:`False` and sets ``error``\. The error domain is %G_FILE_ERROR. Possible error codes are those in the :obj:`~gi.repository.GLib.FileError` enumeration. In the error case, ``contents`` is set to :const:`None` and ``length`` is set to zero. :param filename: name of a file to read contents from, in the GLib file name encoding :return: :const:`True` on success, :const:`False` if an error occurred .. function:: file_open_tmp(tmpl: str | None = None) -> ~typing.Tuple[int, str] Opens a file for writing in the preferred directory for temporary files (as returned by :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.mkstemp`. However, unlike these functions, the template should only be a basename, no directory components are allowed. If template is :const:`None`, a default template is used. Note that in contrast to :func:`~gi.repository.GLib.mkstemp` (and mkstemp()) ``tmpl`` is not modified, and might thus be a read-only literal string. Upon success, and if ``name_used`` is non-:const:`None`, the actual name used is returned in ``name_used``\. This string should be freed with :func:`~gi.repository.GLib.free` when not needed any longer. The returned name is in the GLib file name encoding. :param tmpl: Template for file name, as in :func:`~gi.repository.GLib.mkstemp`, basename only, or :const:`None` for a default template :return: A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and ``error`` will be set. .. function:: file_read_link(filename: str) -> str Reads the contents of the symbolic link ``filename`` like the POSIX ``readlink()`` function. The returned string is in the encoding used for filenames. Use :func:`~gi.repository.GLib.filename_to_utf8` to convert it to UTF-8. The returned string may also be a relative path. Use :func:`~gi.repository.GLib.build_filename` to convert it to an absolute path: .. code-block:: C :dedent: g_autoptr(GError) local_error = NULL; g_autofree gchar *link_target = g_file_read_link ("/etc/localtime", &local_error); if (local_error != NULL) g_error ("Error reading link: %s", local_error->message); if (!g_path_is_absolute (link_target)) { g_autofree gchar *absolute_link_target = g_build_filename ("/etc", link_target, NULL); g_free (link_target); link_target = g_steal_pointer (&absolute_link_target); } .. versionadded:: 2.4 :param filename: the symbolic link :return: A newly-allocated string with the contents of the symbolic link, or :const:`None` if an error occurred. .. function:: file_set_contents(filename: str, contents: list[int]) -> bool Writes all of ``contents`` to a file named ``filename``\. This is a convenience wrapper around calling :func:`~gi.repository.GLib.file_set_contents_full` with ``flags`` set to ``G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING`` and ``mode`` set to ``0666``\. .. versionadded:: 2.8 :param filename: name of a file to write ``contents`` to, in the GLib file name encoding :param contents: string to write to the file :return: :const:`True` on success, :const:`False` if an error occurred .. function:: file_set_contents_full(filename: str, contents: list[int], flags: ~gi.repository.GLib.FileSetContentsFlags, mode: int) -> bool 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 :const:`~gi.repository.GLib.FileSetContentsFlags.NONE` then this function may call ``fsync()``\. If :const:`~gi.repository.GLib.FileSetContentsFlags.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 :const:`~gi.repository.GLib.FileSetContentsFlags.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 :const:`~gi.repository.GLib.FileSetContentsFlags.DURABLE` and :const:`~gi.repository.GLib.FileSetContentsFlags.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 :const:`True`. If the call was not successful, it returns :const:`False` and sets ``error``\. The error domain is %G_FILE_ERROR. Possible error codes are those in the :obj:`~gi.repository.GLib.FileError` 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. .. versionadded:: 2.66 :param filename: name of a file to write ``contents`` to, in the GLib file name encoding :param contents: string to write to the file :param flags: flags controlling the safety vs speed of the operation :param mode: file mode, as passed to ``open()``\; typically this will be ``0666`` :return: :const:`True` on success, :const:`False` if an error occurred .. function:: file_test(filename: str, test: ~gi.repository.GLib.FileTest) -> bool Returns :const:`True` if any of the tests in the bitfield ``test`` are :const:`True`. For example, ``(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`` will return :const:`True` if the file exists; the check whether it's a directory doesn't matter since the existence test is :const:`True`. With the current set of available tests, there's no point passing in more than one test at a time. Apart from :const:`~gi.repository.GLib.FileTest.IS_SYMLINK` all tests follow symbolic links, so for a symbolic link to a regular file :func:`~gi.repository.GLib.file_test` will return :const:`True` for both :const:`~gi.repository.GLib.FileTest.IS_SYMLINK` and :const:`~gi.repository.GLib.FileTest.IS_REGULAR`. Note, that for a dangling symbolic link :func:`~gi.repository.GLib.file_test` will return :const:`True` for :const:`~gi.repository.GLib.FileTest.IS_SYMLINK` and :const:`False` for all other flags. You should never use :func:`~gi.repository.GLib.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, see `TOCTOU `__\. For example, you might think you could use :const:`~gi.repository.GLib.FileTest.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! .. code-block:: C :dedent: // DON'T DO THIS if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) { fd = g_open (filename, O_WRONLY); // write to fd } // DO THIS INSTEAD fd = g_open (filename, O_WRONLY | O_NOFOLLOW | O_CLOEXEC); if (fd == -1) { // check error if (errno == ELOOP) // file is a symlink and can be ignored else // handle errors as before } else { // write to fd } Another thing to note is that :const:`~gi.repository.GLib.FileTest.EXISTS` and :const:`~gi.repository.GLib.FileTest.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 :const:`~gi.repository.GLib.FileTest.IS_SYMLINK` will always return :const:`False`. Testing for :const:`~gi.repository.GLib.FileTest.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. :param filename: a filename to test in the GLib file name encoding :param test: bitfield of :obj:`~gi.repository.GLib.FileTest` flags :return: whether a test was :const:`True` .. function:: filename_display_basename(filename: str) -> str 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 :func:`~gi.repository.GLib.filename_display_name` if you know the whole path, as it allows translation. .. versionadded:: 2.6 :param filename: an absolute pathname in the GLib file name encoding :return: a newly allocated string containing a rendition of the basename of the filename in valid UTF-8 .. function:: filename_display_name(filename: str) -> str 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 :func:`~gi.repository.GLib.filename_to_utf8`, the result is guaranteed to be non-:const:`None` 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 :func:`~gi.repository.GLib.filename_display_basename`, since that allows location-based translation of filenames. .. versionadded:: 2.6 :param filename: a pathname hopefully in the GLib file name encoding :return: a newly allocated string containing a rendition of the filename in valid UTF-8 .. function:: filename_from_uri(uri: str) -> ~typing.Tuple[str, str | None] Converts an escaped ASCII-encoded URI to a local filename in the encoding used for filenames. Since GLib 2.78, the query string and fragment can be present in the URI, but are not part of the resulting filename. We take inspiration from https://url.spec.whatwg.org/``file``-state, but we don't support the entire standard. :param uri: a uri describing a filename (escaped, encoded in ASCII). :return: a newly-allocated string holding the resulting filename, or :const:`None` on an error. .. function:: filename_from_utf8(utf8string, len=-1) 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 :const:`~gi.repository.GLib.ConvertError.ILLEGAL_SEQUENCE`. If the filename encoding is not UTF-8 and the conversion output contains a nul character, the error :const:`~gi.repository.GLib.ConvertError.EMBEDDED_NUL` is set and the function returns :const:`None`. :param utf8string: a UTF-8 encoded string. :param len: the length of the string, or -1 if the string is nul-terminated. :return: The converted string, or :const:`None` on an error. .. function:: filename_to_uri(filename: str, hostname: str | None = None) -> str Converts an absolute filename to an escaped ASCII-encoded URI, with the path component following Section 3.3. of RFC 2396. :param filename: an absolute filename specified in the GLib file name encoding, which is the on-disk file name bytes on Unix, and UTF-8 on Windows :param hostname: A UTF-8 encoded hostname, or :const:`None` for none. :return: a newly-allocated string holding the resulting URI, or :const:`None` on an error. .. function:: filename_to_utf8(opsysstring: str, len: int) -> ~typing.Tuple[str, int, int] 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 :const:`~gi.repository.GLib.ConvertError.ILLEGAL_SEQUENCE`. If the source encoding is not UTF-8 and the conversion output contains a nul character, the error :const:`~gi.repository.GLib.ConvertError.EMBEDDED_NUL` is set and the function returns :const:`None`. Use :func:`~gi.repository.GLib.convert` to produce output that may contain embedded nul characters. :param opsysstring: a string in the encoding for filenames :param len: the length of the string, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the ``len`` parameter is unsafe) :return: The converted string, or :const:`None` on an error. .. function:: find_program_in_path(program: str) -> str | None 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 :const:`None` 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 :const:`None` 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. :param program: a program name in the GLib file name encoding :return: a newly-allocated string with the absolute path, or :const:`None` .. function:: fopen(filename: str, mode: str) -> ~typing.Any | None A wrapper for the stdio ``fopen()`` function. The ``fopen()`` function opens a file and associates a new stream with it. Because file descriptors are specific to the C library on Windows, and a file descriptor is part of the ``FILE`` struct, the ``FILE*`` returned by this function makes sense only to functions in the same C library. Thus if the GLib-using code uses a different C library than GLib does, the FILE* returned by this function cannot be passed to C library functions like ``fprintf()`` or ``fread()``\. See your C library manual for more details about ``fopen()``\. As ``close()`` and ``fclose()`` are part of the C library, this implies that it is currently impossible to close a file if the application C library and the C library used by GLib are different. Convenience functions like :func:`~gi.repository.GLib.file_set_contents_full` avoid this problem. .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param mode: a string describing the mode in which the file should be opened :return: A ``FILE*`` if the file was successfully opened, or :const:`None` if an error occurred .. function:: format_size(size: int) -> str 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 :func:`~gi.repository.GLib.free` when not needed any longer. See :func:`~gi.repository.GLib.format_size_full` for more options about how the size might be formatted. .. versionadded:: 2.30 :param size: a size in bytes :return: a newly-allocated formatted string containing a human readable file size .. function:: format_size_for_display(size: int) -> str 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 :func:`~gi.repository.GLib.free` when not needed any longer. .. versionadded:: 2.16 .. deprecated:: 2.30 This function is broken due to its use of SI suffixes to denote IEC units. Use :func:`~gi.repository.GLib.format_size` instead. :param size: a size in bytes :return: a newly-allocated formatted string containing a human readable file size .. function:: format_size_full(size: int, flags: ~gi.repository.GLib.FormatSizeFlags) -> str Formats a size. This function is similar to :func:`~gi.repository.GLib.format_size` but allows for flags that modify the output. See :obj:`~gi.repository.GLib.FormatSizeFlags`\. .. versionadded:: 2.30 :param size: a size in bytes :param flags: :obj:`~gi.repository.GLib.FormatSizeFlags` to modify the output :return: a newly-allocated formatted string containing a human readable file size .. function:: free(mem: ~typing.Any = None) -> None Frees the memory pointed to by ``mem``\. If you know the allocated size of ``mem``\, calling :func:`~gi.repository.GLib.free_sized` may be faster, depending on the libc implementation in use. Starting from GLib 2.78, this may happen automatically in case a GCC compatible compiler is used with some optimization level and the allocated size is known at compile time (see `documentation of ``__builtin_object_size()`` `__ to understand its caveats). If ``mem`` is :const:`None` it simply returns, so there is no need to check ``mem`` against :const:`None` before calling this function. :param mem: the memory to free .. function:: free_sized(mem: ~typing.Any, size: int) -> None Frees the memory pointed to by ``mem``\, assuming it is has the given ``size``\. If ``mem`` is :const:`None` this is a no-op (and ``size`` is ignored). It is an error if ``size`` doesn’t match the size passed when ``mem`` was allocated. ``size`` is passed to this function to allow optimizations in the allocator. If you don’t know the allocation size, use :func:`~gi.repository.GLib.free` instead. In case a GCC compatible compiler is used, this function may be used automatically via :func:`~gi.repository.GLib.free` if the allocated size is known at compile time, since GLib 2.78. .. versionadded:: 2.76 :param mem: the memory to free :param size: size of ``mem``\, in bytes .. function:: freopen(filename: str, mode: str, stream: ~typing.Any = None) -> ~typing.Any | None A wrapper for the POSIX freopen() function. The freopen() function opens a file and associates it with an existing stream. See your C library manual for more details about freopen(). .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param mode: a string describing the mode in which the file should be opened :param stream: an existing stream which will be reused, or :const:`None` :return: A FILE\* if the file was successfully opened, or :const:`None` if an error occurred. .. function:: fsync(fd: int) -> int A wrapper for the POSIX ``fsync()`` function. On Windows, ``_commit()`` will be used. On macOS, ``fcntl(F_FULLFSYNC)`` will be used. The ``fsync()`` function is used to synchronize a file's in-core state with that of the disk. This wrapper will handle retrying on ``EINTR``\. See the C library manual for more details about fsync(). .. versionadded:: 2.64 :param fd: a file descriptor :return: 0 on success, or -1 if an error occurred. The return value can be used exactly like the return value from fsync(). .. function:: get_application_name() -> str | None Gets a human-readable name for the application, as set by :func:`~gi.repository.GLib.set_application_name`. This name should be localized if possible, and is intended for display to the user. Contrast with :func:`~gi.repository.GLib.get_prgname`, which gets a non-localized name. If :func:`~gi.repository.GLib.set_application_name` has not been called, returns the result of :func:`~gi.repository.GLib.get_prgname` (which may be :const:`None` if :func:`~gi.repository.GLib.set_prgname` has also not been called). .. versionadded:: 2.2 :return: human-readable application name. May return :const:`None` .. function:: get_charset() -> ~typing.Tuple[bool, str] Obtains the character set for the [current locale][setlocale]; you might use this character set as an argument to :func:`~gi.repository.GLib.convert`, to convert from the current locale's encoding to some other encoding. (Frequently :func:`~gi.repository.GLib.locale_to_utf8` and :func:`~gi.repository.GLib.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. nl_langinfo() returns the C locale if no locale has been loaded by setlocale(). The return value is :const:`True` if the locale's encoding is UTF-8, in that case you can perhaps avoid calling :func:`~gi.repository.GLib.convert`. The string returned in ``charset`` is not allocated, and should not be freed. :return: :const:`True` if the returned charset is UTF-8 .. function:: get_codeset() -> str Gets the character set for the current locale. :return: a newly allocated string containing the name of the character set. This string must be freed with :func:`~gi.repository.GLib.free`. .. function:: get_console_charset() -> ~typing.Tuple[bool, str] 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 :func:`~gi.repository.GLib.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 :const:`True` if the locale's encoding is UTF-8, in that case you can perhaps avoid calling :func:`~gi.repository.GLib.convert`. The string returned in ``charset`` is not allocated, and should not be freed. .. versionadded:: 2.62 :return: :const:`True` if the returned charset is UTF-8 .. function:: get_current_dir() -> str 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. :return: the current directory .. function:: get_current_time() Equivalent to the UNIX gettimeofday() function, but portable. You may find :obj:`~gi.repository.GLib.get_real_time` to be more convenient. .. deprecated:: 2.62 :obj:`~gi.repository.GLib.TimeVal` is not year-2038-safe. Use :obj:`~gi.repository.GLib.get_real_time` instead. .. function:: get_environ() -> list[str] Gets the list of environment variables for the current process. The list is :const:`None` 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 :func:`~gi.repository.GLib.strfreev` when it is no longer needed. .. versionadded:: 2.28 :return: the list of environment variables .. function:: get_filename_charsets() -> ~typing.Tuple[bool, list[str]] 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 :func:`~gi.repository.GLib.filename_display_name`. On Unix, the character sets are determined by consulting the environment variables ``G_FILENAME_ENCODING`` and ``G_BROKEN_FILENAMES``\. On Windows, the character set used in the GLib API is always UTF-8 and said environment variables have no effect. ``G_FILENAME_ENCODING`` may be set to a comma-separated list of character set names. The special token "\``locale``\" is taken to mean the character set for the [current locale][setlocale]. If ``G_FILENAME_ENCODING`` is not set, but ``G_BROKEN_FILENAMES`` is, the character set of the current locale is taken as the filename encoding. If neither environment variable is set, UTF-8 is taken as the filename encoding, but the character set of the current locale is also put in the list of encodings. The returned ``charsets`` belong to GLib and must not be freed. Note that on Unix, regardless of the locale character set or ``G_FILENAME_ENCODING`` value, the actual file names present on a system might be in any random encoding or just gibberish. .. versionadded:: 2.6 :return: :const:`True` if the filename encoding is UTF-8. .. function:: get_home_dir() -> str 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: the current user's home directory .. function:: get_host_name() -> str 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. .. versionadded:: 2.8 :return: the host name of the machine. .. function:: get_language_names() -> list[str] 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. .. versionadded:: 2.6 :return: a :const:`None`-terminated array of strings owned by GLib that must not be modified or freed. .. function:: get_language_names_with_category(category_name: str) -> list[str] 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. :func:`~gi.repository.GLib.get_language_names` returns g_get_language_names_with_category("LC_MESSAGES"). .. versionadded:: 2.58 :param category_name: a locale category name :return: a :const:`None`-terminated array of strings owned by the thread g_get_language_names_with_category was called from. It must not be modified or freed. It must be copied if planned to be used in another thread. .. function:: get_locale_variants(locale: str) -> list[str] 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-8@euro``\, then the returned list is ``en_GB.UTF-8@euro``\, ``en_GB.UTF-8``\, ``en_GB@euro``\, ``en_GB``\, ``en.UTF-8@euro``\, ``en.UTF-8``\, ``en@euro``\, ``en``\. If you need the list of variants for the current locale, use :func:`~gi.repository.GLib.get_language_names`. .. versionadded:: 2.28 :param locale: a locale identifier :return: a newly allocated array of newly allocated strings with the locale variants. Free with :func:`~gi.repository.GLib.strfreev`. .. function:: get_monotonic_time() -> int 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. .. versionadded:: 2.28 :return: the monotonic time, in microseconds .. function:: get_num_processors() -> int 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 :func:`~gi.repository.GLib.ThreadPool.new` for CPU bound tasks and similar cases. .. versionadded:: 2.36 :return: Number of schedulable threads, always greater than 0 .. function:: get_os_info(key_name: str) -> str | None 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 :const:`None`. .. versionadded:: 2.64 :param key_name: a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME. :return: The associated value for the requested key or :const:`None` if this information is not provided. .. function:: get_prgname() -> str | None Gets the name of the program. This name should not be localized, in contrast to :func:`~gi.repository.GLib.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]. :return: the name of the program, or :const:`None` if it has not been set yet. The returned string belongs to GLib and must not be modified or freed. .. function:: get_real_name() -> str 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. :return: the user's real name. .. function:: get_real_time() -> int Queries the system wall-clock time. This call is functionally equivalent to :obj:`~gi.repository.GLib.get_current_time` except that the return value is often more convenient than dealing with a :obj:`~gi.repository.GLib.TimeVal`\. You should only use this call if you are actually interested in the real wall-clock time. :obj:`~gi.repository.GLib.get_monotonic_time` is probably more useful for measuring intervals. .. versionadded:: 2.28 :return: the number of microseconds since January 1, 1970 UTC. .. function:: get_system_config_dirs() -> list[str] 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. .. versionadded:: 2.6 :return: a :const:`None`-terminated array of strings owned by GLib that must not be modified or freed. .. function:: get_system_data_dirs() -> list[str] 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. .. versionadded:: 2.6 :return: a :const:`None`-terminated array of strings owned by GLib that must not be modified or freed. .. function:: get_tmp_dir() -> str 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 :const:`None` or the empty string. :return: the directory to use for temporary files. .. function:: get_user_cache_dir() -> str 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. .. versionadded:: 2.6 :return: a string owned by GLib that must not be modified or freed. .. function:: get_user_config_dir() -> str 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 :func:`~gi.repository.GLib.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. .. versionadded:: 2.6 :return: a string owned by GLib that must not be modified or freed. .. function:: get_user_data_dir() -> str 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 :func:`~gi.repository.GLib.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. .. versionadded:: 2.6 :return: a string owned by GLib that must not be modified or freed. .. function:: get_user_name() -> str 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. :return: the user name of the current user. .. function:: get_user_runtime_dir() -> str 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 :func:`~gi.repository.GLib.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. .. versionadded:: 2.28 :return: a string owned by GLib that must not be modified or freed. .. function:: get_user_special_dir(directory: ~gi.repository.GLib.UserDirectory) -> str | None 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, :const:`~gi.repository.GLib.UserDirectory.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. .. versionadded:: 2.14 :param directory: the logical id of special directory :return: the path to the specified special directory, or :const:`None` if the logical id was not found. The returned string is owned by GLib and should not be modified or freed. .. function:: get_user_state_dir() -> str 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 :func:`~gi.repository.GLib.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. .. versionadded:: 2.72 :return: a string owned by GLib that must not be modified or freed. .. function:: getenv(variable: str) -> str | None 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. :param variable: the environment variable to get :return: the value of the environment variable, or :const:`None` if the environment variable is not found. The returned string may be overwritten by the next call to :func:`~gi.repository.GLib.getenv`, :func:`~gi.repository.GLib.setenv` or :func:`~gi.repository.GLib.unsetenv`. .. function:: hash_table_add(hash_table: dict[~typing.Any, ~typing.Any], key: ~typing.Any = None) -> bool :param hash_table: :param key: .. function:: hash_table_contains(hash_table: dict[~typing.Any, ~typing.Any], key: ~typing.Any = None) -> bool :param hash_table: :param key: .. function:: hash_table_destroy(hash_table: dict[~typing.Any, ~typing.Any]) -> None :param hash_table: .. function:: hash_table_find(hash_table: dict[~typing.Any, ~typing.Any], predicate: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], bool], user_data: ~typing.Any = None) -> ~typing.Any | None :param hash_table: :param predicate: :param user_data: .. function:: hash_table_foreach(hash_table: dict[~typing.Any, ~typing.Any], func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], None], user_data: ~typing.Any = None) -> None :param hash_table: :param func: :param user_data: .. function:: hash_table_foreach_remove(hash_table: dict[~typing.Any, ~typing.Any], func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], bool], user_data: ~typing.Any = None) -> int :param hash_table: :param func: :param user_data: .. function:: hash_table_insert(hash_table: dict[~typing.Any, ~typing.Any], key: ~typing.Any = None, value: ~typing.Any = None) -> bool :param hash_table: :param key: :param value: .. function:: hash_table_lookup(hash_table: dict[~typing.Any, ~typing.Any], key: ~typing.Any = None) -> ~typing.Any | None :param hash_table: :param key: .. function:: hash_table_lookup_extended(hash_table: dict[~typing.Any, ~typing.Any], lookup_key: ~typing.Any = None) -> ~typing.Tuple[bool, ~typing.Any | None, ~typing.Any | None] :param hash_table: :param lookup_key: .. function:: hash_table_new_similar(other_hash_table: dict[~typing.Any, ~typing.Any]) -> dict[~typing.Any, ~typing.Any] :param other_hash_table: .. function:: hash_table_remove(hash_table: dict[~typing.Any, ~typing.Any], key: ~typing.Any = None) -> bool :param hash_table: :param key: .. function:: hash_table_remove_all(hash_table: dict[~typing.Any, ~typing.Any]) -> None :param hash_table: .. function:: hash_table_replace(hash_table: dict[~typing.Any, ~typing.Any], key: ~typing.Any = None, value: ~typing.Any = None) -> bool :param hash_table: :param key: :param value: .. function:: hash_table_size(hash_table: dict[~typing.Any, ~typing.Any]) -> int :param hash_table: .. function:: hook_destroy(hook_list: ~gi.repository.GLib.HookList, hook_id: int) -> bool :param hook_list: :param hook_id: .. function:: hook_destroy_link(hook_list: ~gi.repository.GLib.HookList, hook: ~gi.repository.GLib.Hook) -> None :param hook_list: :param hook: .. function:: hook_free(hook_list: ~gi.repository.GLib.HookList, hook: ~gi.repository.GLib.Hook) -> None :param hook_list: :param hook: .. function:: hook_insert_before(hook_list: ~gi.repository.GLib.HookList, sibling: ~gi.repository.GLib.Hook | None, hook: ~gi.repository.GLib.Hook) -> None :param hook_list: :param sibling: :param hook: .. function:: hook_insert_sorted(hook_list: ~gi.repository.GLib.HookList, hook: ~gi.repository.GLib.Hook, func: ~typing.Callable[[~gi.repository.GLib.Hook, ~gi.repository.GLib.Hook], int]) -> None :param hook_list: :param hook: :param func: .. function:: hook_prepend(hook_list: ~gi.repository.GLib.HookList, hook: ~gi.repository.GLib.Hook) -> None :param hook_list: :param hook: .. function:: hostname_is_ascii_encoded(hostname: str) -> bool Tests if ``hostname`` contains segments with an ASCII-compatible encoding of an Internationalized Domain Name. If this returns :const:`True`, you should decode the hostname with :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.hostname_is_non_ascii` and :func:`~gi.repository.GLib.hostname_is_ascii_encoded` to both return :const:`True` for a name. .. versionadded:: 2.22 :param hostname: a hostname :return: :const:`True` if ``hostname`` contains any ASCII-encoded segments. .. function:: hostname_is_ip_address(hostname: str) -> bool 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). .. versionadded:: 2.22 :param hostname: a hostname (or IP address in string form) :return: :const:`True` if ``hostname`` is an IP address .. function:: hostname_is_non_ascii(hostname: str) -> bool Tests if ``hostname`` contains Unicode characters. If this returns :const:`True`, you need to encode the hostname with :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.hostname_is_non_ascii` and :func:`~gi.repository.GLib.hostname_is_ascii_encoded` to both return :const:`True` for a name. .. versionadded:: 2.22 :param hostname: a hostname :return: :const:`True` if ``hostname`` contains any non-ASCII characters .. function:: hostname_to_ascii(hostname: str) -> str | None Converts ``hostname`` to its canonical ASCII form; an ASCII-only string containing no uppercase letters and not ending with a trailing dot. .. versionadded:: 2.22 :param hostname: a valid UTF-8 or ASCII hostname :return: an ASCII hostname, which must be freed, or :const:`None` if ``hostname`` is in some way invalid. .. function:: hostname_to_unicode(hostname: str) -> str | None 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. .. versionadded:: 2.22 :param hostname: a valid UTF-8 or ASCII hostname :return: a UTF-8 hostname, which must be freed, or :const:`None` if ``hostname`` is in some way invalid. .. function:: idle_add(function, *user_data, priority=200) Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the default idle priority, :obj:`~gi.repository.GLib.PRIORITY_DEFAULT_IDLE`\. If the function returns :const:`False` it is automatically removed from the list of event sources and will not be called again. See `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 :obj:`~gi.repository.GLib.idle_source_new` and attaches it to the global :obj:`~gi.repository.GLib.MainContext` using :obj:`~gi.repository.GLib.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. :param function: function to call :param user_data: :param priority: :return: the ID (greater than 0) of the event source. .. function:: idle_remove_by_data(data: ~typing.Any = None) -> bool Removes the idle function with the given data. :param data: the data for the idle source's callback. :return: :const:`True` if an idle source was found and removed. .. function:: idle_source_new() -> ~gi.repository.GLib.Source Creates a new idle source. The source will not initially be associated with any :obj:`~gi.repository.GLib.MainContext` and must be added to one with :obj:`~gi.repository.GLib.Source.attach` before it will be executed. Note that the default priority for idle sources is :obj:`~gi.repository.GLib.PRIORITY_DEFAULT_IDLE`\, as compared to other sources which have a default priority of :obj:`~gi.repository.GLib.PRIORITY_DEFAULT`\. :return: the newly-created idle source .. function:: int64_equal(v1: ~typing.Any, v2: ~typing.Any) -> bool Compares the two :obj:`int` values being pointed to and returns :const:`True` if they are equal. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``key_equal_func`` parameter, when using non-:const:`None` pointers to 64-bit integers as keys in a :obj:`~gi.repository.GLib.HashTable`\. .. versionadded:: 2.22 :param v1: a pointer to a :obj:`int` key :param v2: a pointer to a :obj:`int` key to compare with ``v1`` :return: :const:`True` if the two keys match. .. function:: int64_hash(v: ~typing.Any) -> int Converts a pointer to a :obj:`int` to a hash value. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``hash_func`` parameter, when using non-:const:`None` pointers to 64-bit integer values as keys in a :obj:`~gi.repository.GLib.HashTable`\. .. versionadded:: 2.22 :param v: a pointer to a :obj:`int` key :return: a hash value corresponding to the key. .. function:: int_equal(v1: ~typing.Any, v2: ~typing.Any) -> bool Compares the two :obj:`int` values being pointed to and returns :const:`True` if they are equal. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``key_equal_func`` parameter, when using non-:const:`None` pointers to integers as keys in a :obj:`~gi.repository.GLib.HashTable`\. Note that this function acts on pointers to :obj:`int`, not on :obj:`int` directly: if your hash table's keys are of the form ``GINT_TO_POINTER (n)``\, use :func:`~gi.repository.GLib.direct_equal` instead. :param v1: a pointer to a :obj:`int` key :param v2: a pointer to a :obj:`int` key to compare with ``v1`` :return: :const:`True` if the two keys match. .. function:: int_hash(v: ~typing.Any) -> int Converts a pointer to a :obj:`int` to a hash value. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``hash_func`` parameter, when using non-:const:`None` pointers to integer values as keys in a :obj:`~gi.repository.GLib.HashTable`\. Note that this function acts on pointers to :obj:`int`, not on :obj:`int` directly: if your hash table's keys are of the form ``GINT_TO_POINTER (n)``\, use :func:`~gi.repository.GLib.direct_hash` instead. :param v: a pointer to a :obj:`int` key :return: a hash value corresponding to the key. .. function:: intern_static_string(string: str | None = None) -> str Returns a canonical representation for ``string``\. Interned strings can be compared for equality by comparing the pointers, instead of using strcmp(). :func:`~gi.repository.GLib.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++. .. versionadded:: 2.10 :param string: a static string :return: a canonical representation for the string .. function:: intern_string(string: str | None = None) -> str 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++. .. versionadded:: 2.10 :param string: a string :return: a canonical representation for the string .. function:: io_add_watch(*args, **kwargs) Adds the :obj:`~gi.repository.GLib.IOChannel` into the default main loop context with the default priority. :param args: :param kwargs: :return: the event source id .. function:: io_channel_error_from_errno(en: int) -> ~gi.repository.GLib.IOChannelError :param en: .. function:: io_channel_error_quark() -> int .. function:: io_create_watch(channel: ~gi.repository.GLib.IOChannel, condition: ~gi.repository.GLib.IOCondition) -> ~gi.repository.GLib.Source Creates a :obj:`~gi.repository.GLib.Source` that's dispatched when ``condition`` is met for the given ``channel``\. For example, if condition is :const:`~gi.repository.GLib.IOCondition.IN`, the source will be dispatched when there's data available for reading. The callback function invoked by the :obj:`~gi.repository.GLib.Source` should be added with :func:`~gi.repository.GLib.Source.set_callback`, but it has type :obj:`~gi.repository.GLib.IOFunc` (not :obj:`~gi.repository.GLib.SourceFunc`\). :func:`~gi.repository.GLib.io_add_watch` is a simpler interface to this same functionality, for the case where you want to add the source to the default main loop context at the default priority. On Windows, polling a :obj:`~gi.repository.GLib.Source` created to watch a channel for a socket puts the socket in non-blocking mode. This is a side-effect of the implementation and unavoidable. :param channel: a :obj:`~gi.repository.GLib.IOChannel` to watch :param condition: conditions to watch for :return: a new :obj:`~gi.repository.GLib.Source` .. function:: key_file_error_quark() -> int .. function:: list_pop_allocator() -> None .. function:: list_push_allocator(allocator: ~gi.repository.GLib.Allocator) -> None :param allocator: .. function:: listenv() -> list[str] Gets the names of all variables set in the environment. Programs that want to be portable to Windows should typically use this function and :func:`~gi.repository.GLib.getenv` instead of using the environ array from the C library directly. On Windows, the strings in the environ array are in system codepage encoding, while in most of the typical use cases for environment variables in GLib-using programs you want the UTF-8 encoding that this function and :func:`~gi.repository.GLib.getenv` provide. .. versionadded:: 2.8 :return: a :const:`None`-terminated list of strings which must be freed with :func:`~gi.repository.GLib.strfreev`. .. function:: locale_from_utf8(utf8string: str, len: int) -> ~typing.Tuple[list[int], int] Converts a string from UTF-8 to the encoding used for strings by the C runtime (usually the same as that used by the operating system) in the [current locale][setlocale]. On Windows this means the system codepage. 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 :const:`~gi.repository.GLib.ConvertError.ILLEGAL_SEQUENCE`. Use :func:`~gi.repository.GLib.convert` to convert input that may contain embedded nul characters. :param utf8string: a UTF-8 encoded string :param len: the length of the string, or -1 if the string is nul-terminated. :return: A newly-allocated buffer containing the converted string, or :const:`None` on an error, and error will be set. .. function:: locale_to_utf8(opsysstring: list[int]) -> ~typing.Tuple[str, int, int] Converts a string which is in the encoding used for strings by the C runtime (usually the same as that used by the operating system) in the [current locale][setlocale] into a UTF-8 string. If the source encoding is not UTF-8 and the conversion output contains a nul character, the error :const:`~gi.repository.GLib.ConvertError.EMBEDDED_NUL` is set and the function returns :const:`None`. If the source encoding is UTF-8, an embedded nul character is treated with the :const:`~gi.repository.GLib.ConvertError.ILLEGAL_SEQUENCE` error for backward compatibility with earlier versions of this library. Use :func:`~gi.repository.GLib.convert` to produce output that may contain embedded nul characters. :param opsysstring: a string in the encoding of the current locale. On Windows this means the system codepage. :return: The converted string, or :const:`None` on an error. .. function:: log_default_handler(log_domain: str | None, log_level: ~gi.repository.GLib.LogLevelFlags, message: str | None = None, unused_data: ~typing.Any = None) -> None The default log handler set up by GLib; :obj:`~gi.repository.GLib.log_set_default_handler` allows to install an alternate default log handler. This is used if no log handler has been set for the particular log domain and log level combination. It outputs the message to ``stderr`` or ``stdout`` and if the log level is fatal it calls :obj:`~gi.repository.GLib.BREAKPOINT`\. It automatically prints a new-line character after the message, so one does not need to be manually included in ``message``\. The behavior of this log handler can be influenced by a number of environment variables: - ``G_MESSAGES_PREFIXED``\: A ``:``\-separated list of log levels for which messages should be prefixed by the program name and PID of the application. - ``G_MESSAGES_DEBUG``\: A space-separated list of log domains for which debug and informational messages are printed. By default these messages are not printed. If you need to set the allowed domains at runtime, use :obj:`~gi.repository.GLib.log_writer_default_set_debug_domains`\. ``stderr`` is used for levels :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_ERROR`\, :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_CRITICAL`\, :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_WARNING` and :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_MESSAGE`\. ``stdout`` is used for the rest, unless ``stderr`` was requested by :obj:`~gi.repository.GLib.log_writer_default_set_use_stderr`\. This has no effect if structured logging is enabled; see `Using Structured Logging `__\. :param log_domain: the log domain of the message, or ``NULL`` for the default ``""`` application domain :param log_level: the level of the message :param message: the message :param unused_data: data passed from :obj:`~gi.repository.GLib.log` which is unused .. function:: log_get_debug_enabled() -> bool Return whether debug output from the GLib logging system is enabled. Note that this should not be used to conditionalise calls to :obj:`~gi.repository.GLib.debug` or other logging functions; it should only be used from :obj:`~gi.repository.GLib.LogWriterFunc` implementations. Note also that the value of this does not depend on ``G_MESSAGES_DEBUG``\, nor :obj:`~gi.repository.GLib.log_writer_default_set_debug_domains`\; see the docs for :obj:`~gi.repository.GLib.log_set_debug_enabled`\. .. versionadded:: 2.72 :return: ``TRUE`` if debug output is enabled, ``FALSE`` otherwise .. function:: log_remove_handler(log_domain: str, handler_id: int) -> None Removes the log handler. This has no effect if structured logging is enabled; see `Using Structured Logging `__\. :param log_domain: the log domain :param handler_id: the ID of the handler, which was returned in :obj:`~gi.repository.GLib.log_set_handler` .. function:: log_set_always_fatal(fatal_mask: ~gi.repository.GLib.LogLevelFlags) -> ~gi.repository.GLib.LogLevelFlags Sets the message levels which are always fatal, in any log domain. When a message with any of these levels is logged the program terminates. You can only set the levels defined by GLib to be fatal. :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_ERROR` is always fatal. You can also make some message levels fatal at runtime by setting the ``G_DEBUG`` environment variable (see `Running GLib Applications `__\). Libraries should not call this function, as it affects all messages logged by a process, including those from other libraries. Structured log messages (using :obj:`~gi.repository.GLib.log_structured` and :obj:`~gi.repository.GLib.log_structured_array`\) are fatal only if the default log writer is used; otherwise it is up to the writer function to determine which log messages are fatal. See `Using Structured Logging `__\. :param fatal_mask: the mask containing bits set for each level of error which is to be fatal :return: the old fatal mask .. function:: log_set_debug_enabled(enabled: bool) -> None Enable or disable debug output from the GLib logging system for all domains. This value interacts disjunctively with ``G_MESSAGES_DEBUG`` and :obj:`~gi.repository.GLib.log_writer_default_set_debug_domains` — if any of them would allow a debug message to be outputted, it will be. Note that this should not be used from within library code to enable debug output — it is intended for external use. .. versionadded:: 2.72 :param enabled: ``TRUE`` to enable debug output, ``FALSE`` otherwise .. function:: log_set_fatal_mask(log_domain: str, fatal_mask: ~gi.repository.GLib.LogLevelFlags) -> ~gi.repository.GLib.LogLevelFlags Sets the log levels which are fatal in the given domain. :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_ERROR` is always fatal. This has no effect on structured log messages (using :obj:`~gi.repository.GLib.log_structured` or :obj:`~gi.repository.GLib.log_structured_array`\). To change the fatal behaviour for specific log messages, programs must install a custom log writer function using :obj:`~gi.repository.GLib.log_set_writer_func`\. See `Using Structured Logging `__\. This function is mostly intended to be used with :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_CRITICAL`\. You should typically not set :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_WARNING`\, :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_MESSAGE`\, :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_INFO` or :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_DEBUG` as fatal except inside of test programs. :param log_domain: the log domain :param fatal_mask: the new fatal mask :return: the old fatal mask for the log domain .. function:: log_set_handler(log_domain: str | None, log_levels: ~gi.repository.GLib.LogLevelFlags, log_func: ~typing.Callable[[str, ~gi.repository.GLib.LogLevelFlags, str, ~typing.Any], None], user_data: ~typing.Any = None) -> int Sets the log handler for a domain and a set of log levels. To handle fatal and recursive messages the ``log_levels`` parameter must be combined with the :obj:`~gi.repository.GLib.LogLevelFlags.FLAG_FATAL` and :obj:`~gi.repository.GLib.LogLevelFlags.FLAG_RECURSION` bit flags. Note that since the :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_ERROR` log level is always fatal, if you want to set a handler for this log level you must combine it with :obj:`~gi.repository.GLib.LogLevelFlags.FLAG_FATAL`\. This has no effect if structured logging is enabled; see `Using Structured Logging `__\. Here is an example for adding a log handler for all warning messages in the default domain: .. code-block:: c :dedent: g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); This example adds a log handler for all critical messages from GTK: .. code-block:: c :dedent: g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); This example adds a log handler for all messages from GLib: .. code-block:: c :dedent: g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); :param log_domain: the log domain, or ``NULL`` for the default ``""`` application domain :param log_levels: the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine the log levels with the :obj:`~gi.repository.GLib.LogLevelFlags.FLAG_FATAL` and :obj:`~gi.repository.GLib.LogLevelFlags.FLAG_RECURSION` bit flags. :param log_func: the log handler function :param user_data: data passed to the log handler :return: the id of the new handler .. function:: log_set_writer_func(user_data: ~typing.Any = None) -> None Set a writer function which will be called to format and write out each log message. Each program should set a writer function, or the default writer (:obj:`~gi.repository.GLib.log_writer_default`\) will be used. Libraries **must not** call this function — only programs are allowed to install a writer function, as there must be a single, central point where log messages are formatted and outputted. There can only be one writer function. It is an error to set more than one. .. versionadded:: 2.50 :param user_data: user data to pass to ``func`` .. function:: log_structured_array(log_level: ~gi.repository.GLib.LogLevelFlags, fields: list[~gi.repository.GLib.LogField]) -> None Log a message with structured data. The message will be passed through to the log writer set by the application using :obj:`~gi.repository.GLib.log_set_writer_func`\. If the message is fatal (i.e. its log level is :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_ERROR`\), the program will be aborted at the end of this function. See :obj:`~gi.repository.GLib.log_structured` for more documentation. This assumes that ``log_level`` is already present in ``fields`` (typically as the ``PRIORITY`` field). .. versionadded:: 2.50 :param log_level: log level, either from :obj:`~gi.repository.GLib.LogLevelFlags`\, or a user-defined level :param fields: key–value pairs of structured data to add to the log message .. function:: log_variant(log_domain: str | None, log_level: ~gi.repository.GLib.LogLevelFlags, fields: ~gi.repository.GLib.Variant) -> None Log a message with structured data, accepting the data within a :obj:`~gi.repository.GLib.Variant`\. This version is especially useful for use in other languages, via introspection. The only mandatory item in the ``fields`` dictionary is the ``"MESSAGE"`` which must contain the text shown to the user. The values in the ``fields`` dictionary are likely to be of type ``G_VARIANT_TYPE_STRING``\. Array of bytes (``G_VARIANT_TYPE_BYTESTRING``\) is also supported. In this case the message is handled as binary and will be forwarded to the log writer as such. The size of the array should not be higher than ``G_MAXSSIZE``\. Otherwise it will be truncated to this size. For other types :obj:`~gi.repository.GLib.Variant.print` will be used to convert the value into a string. For more details on its usage and about the parameters, see :obj:`~gi.repository.GLib.log_structured`\. .. versionadded:: 2.50 :param log_domain: log domain, usually ``G_LOG_DOMAIN`` :param log_level: log level, either from :obj:`~gi.repository.GLib.LogLevelFlags`\, or a user-defined level :param fields: a dictionary (:obj:`~gi.repository.GLib.Variant` of the type ``G_VARIANT_TYPE_VARDICT``\) containing the key-value pairs of message data. .. function:: log_writer_default(log_level: ~gi.repository.GLib.LogLevelFlags, fields: list[~gi.repository.GLib.LogField], user_data: ~typing.Any = None) -> ~gi.repository.GLib.LogWriterOutput Format a structured log message and output it to the default log destination for the platform. On Linux, this is typically the systemd journal, falling back to ``stdout`` or ``stderr`` if running from the terminal or if output is being redirected to a file. Support for other platform-specific logging mechanisms may be added in future. Distributors of GLib may modify this function to impose their own (documented) platform-specific log writing policies. This is suitable for use as a :obj:`~gi.repository.GLib.LogWriterFunc`\, and is the default writer used if no other is set using :obj:`~gi.repository.GLib.log_set_writer_func`\. As with :obj:`~gi.repository.GLib.log_default_handler`\, this function drops debug and informational messages unless their log domain (or ``all``\) is listed in the space-separated ``G_MESSAGES_DEBUG`` environment variable, or set at runtime by :obj:`~gi.repository.GLib.log_writer_default_set_debug_domains`\. :obj:`~gi.repository.GLib.log_writer_default` uses the mask set by :obj:`~gi.repository.GLib.log_set_always_fatal` to determine which messages are fatal. When using a custom writer function instead it is up to the writer function to determine which log messages are fatal. .. versionadded:: 2.50 :param log_level: log level, either from :obj:`~gi.repository.GLib.LogLevelFlags`\, or a user-defined level :param fields: key–value pairs of structured data forming the log message :param user_data: user data passed to :obj:`~gi.repository.GLib.log_set_writer_func` :return: :obj:`~gi.repository.GLib.LogWriterOutput.HANDLED` on success, :obj:`~gi.repository.GLib.LogWriterOutput.UNHANDLED` otherwise .. function:: log_writer_default_set_debug_domains(domains: str | None = None) -> None Reset the list of domains to be logged, that might be initially set by the ``G_MESSAGES_DEBUG`` environment variable. This function is thread-safe. .. versionadded:: 2.80 :param domains: ``NULL``\-terminated array with domains to be printed. ``NULL`` or an array with no values means none. Array with a single value ``"all"`` means all. .. function:: log_writer_default_set_use_stderr(use_stderr: bool) -> None Configure whether the built-in log functions will output all log messages to ``stderr``\. The built-in log functions are :obj:`~gi.repository.GLib.log_default_handler` for the old-style API, and both :obj:`~gi.repository.GLib.log_writer_default` and :obj:`~gi.repository.GLib.log_writer_standard_streams` for the structured API. By default, log messages of levels :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_INFO` and :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_DEBUG` are sent to ``stdout``\, and other log messages are sent to ``stderr``\. This is problematic for applications that intend to reserve ``stdout`` for structured output such as JSON or XML. This function sets global state. It is not thread-aware, and should be called at the very start of a program, before creating any other threads or creating objects that could create worker threads of their own. .. versionadded:: 2.68 :param use_stderr: If ``TRUE``\, use ``stderr`` for log messages that would normally have appeared on ``stdout`` .. function:: log_writer_default_would_drop(log_level: ~gi.repository.GLib.LogLevelFlags, log_domain: str | None = None) -> bool Check whether :obj:`~gi.repository.GLib.log_writer_default` and :obj:`~gi.repository.GLib.log_default_handler` would ignore a message with the given domain and level. As with :obj:`~gi.repository.GLib.log_default_handler`\, this function drops debug and informational messages unless their log domain (or ``all``\) is listed in the space-separated ``G_MESSAGES_DEBUG`` environment variable, or by :obj:`~gi.repository.GLib.log_writer_default_set_debug_domains`\. This can be used when implementing log writers with the same filtering behaviour as the default, but a different destination or output format: .. code-block:: c :dedent: if (g_log_writer_default_would_drop (log_level, log_domain)) return G_LOG_WRITER_HANDLED; ]| or to skip an expensive computation if it is only needed for a debugging message, and `G_MESSAGES_DEBUG` is not set: ```c if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN)) { g_autofree gchar *result = expensive_computation (my_object); g_debug ("my_object result: %s", result); } .. versionadded:: 2.68 :param log_level: log level, either from :obj:`~gi.repository.GLib.LogLevelFlags`\, or a user-defined level :param log_domain: log domain :return: ``TRUE`` if the log message would be dropped by GLib’s default log handlers .. function:: log_writer_format_fields(log_level: ~gi.repository.GLib.LogLevelFlags, fields: list[~gi.repository.GLib.LogField], use_color: bool) -> str Format a structured log message as a string suitable for outputting to the terminal (or elsewhere). This will include the values of all fields it knows how to interpret, which includes ``MESSAGE`` and ``GLIB_DOMAIN`` (see the documentation for :obj:`~gi.repository.GLib.log_structured`\). It does not include values from unknown fields. The returned string does **not** have a trailing new-line character. It is encoded in the character set of the current locale, which is not necessarily UTF-8. .. versionadded:: 2.50 :param log_level: log level, either from :obj:`~gi.repository.GLib.LogLevelFlags`\, or a user-defined level :param fields: key–value pairs of structured data forming the log message :param use_color: ``TRUE`` to use `ANSI color escape sequences `__ when formatting the message, ``FALSE`` to not :return: string containing the formatted log message, in the character set of the current locale .. function:: log_writer_is_journald(output_fd: int) -> bool Check whether the given ``output_fd`` file descriptor is a connection to the systemd journal, or something else (like a log file or ``stdout`` or ``stderr``\). Invalid file descriptors are accepted and return ``FALSE``\, which allows for the following construct without needing any additional error handling: .. code-block:: c :dedent: is_journald = g_log_writer_is_journald (fileno (stderr)); .. versionadded:: 2.50 :param output_fd: output file descriptor to check :return: ``TRUE`` if ``output_fd`` points to the journal, ``FALSE`` otherwise .. function:: log_writer_journald(log_level: ~gi.repository.GLib.LogLevelFlags, fields: list[~gi.repository.GLib.LogField], user_data: ~typing.Any = None) -> ~gi.repository.GLib.LogWriterOutput Format a structured log message and send it to the systemd journal as a set of key–value pairs. All fields are sent to the journal, but if a field has length zero (indicating program-specific data) then only its key will be sent. This is suitable for use as a :obj:`~gi.repository.GLib.LogWriterFunc`\. If GLib has been compiled without systemd support, this function is still defined, but will always return :obj:`~gi.repository.GLib.LogWriterOutput.UNHANDLED`\. .. versionadded:: 2.50 :param log_level: log level, either from :obj:`~gi.repository.GLib.LogLevelFlags`\, or a user-defined level :param fields: key–value pairs of structured data forming the log message :param user_data: user data passed to :obj:`~gi.repository.GLib.log_set_writer_func` :return: :obj:`~gi.repository.GLib.LogWriterOutput.HANDLED` on success, :obj:`~gi.repository.GLib.LogWriterOutput.UNHANDLED` otherwise .. function:: log_writer_standard_streams(log_level: ~gi.repository.GLib.LogLevelFlags, fields: list[~gi.repository.GLib.LogField], user_data: ~typing.Any = None) -> ~gi.repository.GLib.LogWriterOutput Format a structured log message and print it to either ``stdout`` or ``stderr``\, depending on its log level. :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_INFO` and :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_DEBUG` messages are sent to ``stdout``\, or to ``stderr`` if requested by :obj:`~gi.repository.GLib.log_writer_default_set_use_stderr`\; all other log levels are sent to ``stderr``\. Only fields which are understood by this function are included in the formatted string which is printed. If the output stream supports `ANSI color escape sequences `__\, they will be used in the output. A trailing new-line character is added to the log message when it is printed. This is suitable for use as a :obj:`~gi.repository.GLib.LogWriterFunc`\. .. versionadded:: 2.50 :param log_level: log level, either from :obj:`~gi.repository.GLib.LogLevelFlags`\, or a user-defined level :param fields: key–value pairs of structured data forming the log message :param user_data: user data passed to :obj:`~gi.repository.GLib.log_set_writer_func` :return: :obj:`~gi.repository.GLib.LogWriterOutput.HANDLED` on success, :obj:`~gi.repository.GLib.LogWriterOutput.UNHANDLED` otherwise .. function:: log_writer_supports_color(output_fd: int) -> bool Check whether the given ``output_fd`` file descriptor supports `ANSI color escape sequences `__\. If so, they can safely be used when formatting log messages. .. versionadded:: 2.50 :param output_fd: output file descriptor to check :return: ``TRUE`` if ANSI color escapes are supported, ``FALSE`` otherwise .. function:: log_writer_syslog(log_level: ~gi.repository.GLib.LogLevelFlags, fields: list[~gi.repository.GLib.LogField], user_data: ~typing.Any = None) -> ~gi.repository.GLib.LogWriterOutput Format a structured log message and send it to the syslog daemon. Only fields which are understood by this function are included in the formatted string which is printed. Log facility will be defined via the SYSLOG_FACILITY field and accepts the following values: "auth", "daemon", and "user". If SYSLOG_FACILITY is not specified, LOG_USER facility will be used. This is suitable for use as a :obj:`~gi.repository.GLib.LogWriterFunc`\. If syslog is not supported, this function is still defined, but will always return :obj:`~gi.repository.GLib.LogWriterOutput.UNHANDLED`\. .. versionadded:: 2.80 :param log_level: log level, either from :obj:`~gi.repository.GLib.LogLevelFlags`\, or a user-defined level :param fields: key–value pairs of structured data forming the log message :param user_data: user data passed to :obj:`~gi.repository.GLib.log_set_writer_func` :return: :obj:`~gi.repository.GLib.LogWriterOutput.HANDLED` on success, :obj:`~gi.repository.GLib.LogWriterOutput.UNHANDLED` otherwise .. function:: lstat(filename: str, buf: ~gi.repository.GLib.StatBuf) -> int A wrapper for the POSIX lstat() function. The lstat() function is like stat() except that in the case of symbolic links, it returns information about the symbolic link itself and not the file that it refers to. If the system does not support symbolic links :func:`~gi.repository.GLib.lstat` is identical to :func:`~gi.repository.GLib.stat`. See your C library manual for more details about lstat(). .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param buf: a pointer to a stat struct, which will be filled with the file information :return: 0 if the information was successfully retrieved, -1 if an error occurred .. function:: main_context_default() -> ~gi.repository.GLib.MainContext .. function:: main_context_get_thread_default() -> ~gi.repository.GLib.MainContext | None .. function:: main_current_source() -> ~gi.repository.GLib.Source | None Returns the currently firing source for this thread. .. versionadded:: 2.12 :return: The currently firing source or :const:`None`. .. function:: main_depth() -> int Returns the depth of the stack of calls to :obj:`~gi.repository.GLib.MainContext.dispatch` on any :obj:`~gi.repository.GLib.MainContext` in the current thread. That is, when called from the toplevel, it gives 0. When called from within a callback from :obj:`~gi.repository.GLib.MainContext.iteration` (or :obj:`~gi.repository.GLib.MainLoop.run`\, etc.) it returns 1. When called from within a callback to a recursive call to :obj:`~gi.repository.GLib.MainContext.iteration`\, it returns 2. And so forth. This function is useful in a situation like the following: Imagine an extremely simple "garbage collected" system. .. code-block:: C :dedent: static GList *free_list; gpointer allocate_memory (gsize size) { gpointer result = g_malloc (size); free_list = g_list_prepend (free_list, result); return result; } void free_allocated_memory (void) { GList *l; for (l = free_list; l; l = l->next); g_free (l->data); g_list_free (free_list); free_list = NULL; } [...] while (TRUE); { g_main_context_iteration (NULL, TRUE); free_allocated_memory(); } This works from an application, however, if you want to do the same thing from a library, it gets more difficult, since you no longer control the main loop. You might think you can simply use an idle function to make the call to free_allocated_memory(), but that doesn't work, since the idle function could be called from a recursive callback. This can be fixed by using :obj:`~gi.repository.GLib.main_depth` .. code-block:: C :dedent: gpointer allocate_memory (gsize size) { FreeListBlock *block = g_new (FreeListBlock, 1); block->mem = g_malloc (size); block->depth = g_main_depth (); free_list = g_list_prepend (free_list, block); return block->mem; } void free_allocated_memory (void) { GList *l; int depth = g_main_depth (); for (l = free_list; l; ); { GList *next = l->next; FreeListBlock *block = l->data; if (block->depth > depth) { g_free (block->mem); g_free (block); free_list = g_list_delete_link (free_list, l); } l = next; } } There is a temptation to use :obj:`~gi.repository.GLib.main_depth` to solve problems with reentrancy. For instance, while waiting for data to be received from the network in response to a menu item, the menu item might be selected again. It might seem that one could make the menu item's callback return immediately and do nothing if :obj:`~gi.repository.GLib.main_depth` returns a value greater than 1. However, this should be avoided since the user then sees selecting the menu item do nothing. Furthermore, you'll find yourself adding these checks all over your code, since there are doubtless many, many things that the user could do. Instead, you can use the following techniques: - Use gtk_widget_set_sensitive() or modal dialogs to prevent the user from interacting with elements while the main loop is recursing. - Avoid main loop recursion in situations where you can't handle arbitrary callbacks. Instead, structure your code so that you simply return to the main loop and then get called again when there is more work to do. :return: The main loop recursion level in the current thread .. function:: malloc(n_bytes: int) -> ~typing.Any | None Allocates ``n_bytes`` bytes of memory. If ``n_bytes`` is 0 it returns :const:`None`. If the allocation fails (because the system is out of memory), the program is terminated. :param n_bytes: the number of bytes to allocate :return: a pointer to the allocated memory .. function:: malloc0(n_bytes: int) -> ~typing.Any | None Allocates ``n_bytes`` bytes of memory, initialized to 0's. If ``n_bytes`` is 0 it returns :const:`None`. If the allocation fails (because the system is out of memory), the program is terminated. :param n_bytes: the number of bytes to allocate :return: a pointer to the allocated memory .. function:: malloc0_n(n_blocks: int, n_block_bytes: int) -> ~typing.Any | None This function is similar to :func:`~gi.repository.GLib.malloc0`, allocating (``n_blocks`` \* ``n_block_bytes``\) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. .. versionadded:: 2.24 :param n_blocks: the number of blocks to allocate :param n_block_bytes: the size of each block in bytes :return: a pointer to the allocated memory .. function:: malloc_n(n_blocks: int, n_block_bytes: int) -> ~typing.Any | None This function is similar to :func:`~gi.repository.GLib.malloc`, allocating (``n_blocks`` \* ``n_block_bytes``\) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. .. versionadded:: 2.24 :param n_blocks: the number of blocks to allocate :param n_block_bytes: the size of each block in bytes :return: a pointer to the allocated memory .. function:: markup_error_quark() -> int .. function:: markup_escape_text(text, length=-1) Escapes text so that the markup parser will parse it verbatim. Less than, greater than, ampersand, etc. are replaced with the corresponding entities. This function would typically be used when writing out a file to be parsed with the markup parser. Note that this function doesn't protect whitespace and line endings from being processed according to the XML rules for normalization of line endings and attribute values. Note also that this function will produce character references in the range of wzxhzdk:0 ... wzxhzdk:1 for all control sequences except for tabstop, newline and carriage return. The character references in this range are not valid XML 1.0, but they are valid XML 1.1 and will be accepted by the GMarkup parser. :param text: some valid UTF-8 text :param length: length of ``text`` in bytes, or -1 if the text is nul-terminated :return: a newly allocated string with the escaped text .. function:: mem_chunk_info() -> None .. function:: mem_is_system_malloc() -> bool Checks whether the allocator used by :func:`~gi.repository.GLib.malloc` is the system's malloc implementation. If it returns :const:`True` memory allocated with malloc() can be used interchangeably with memory allocated using :func:`~gi.repository.GLib.malloc`. This function is useful for avoiding an extra copy of allocated memory returned by a non-GLib-based API. .. deprecated:: 2.46 GLib always uses the system malloc, so this function always returns :const:`True`. :return: if :const:`True`, malloc() and :func:`~gi.repository.GLib.malloc` can be mixed. .. function:: mem_profile() -> None GLib used to support some tools for memory profiling, but this no longer works. There are many other useful tools for memory profiling these days which can be used instead. .. deprecated:: 2.46 Use other memory profiling tools instead .. function:: mem_set_vtable(vtable: ~gi.repository.GLib.MemVTable) -> None This function used to let you override the memory allocation function. However, its use was incompatible with the use of global constructors in GLib and GIO, because those use the GLib allocators before main is reached. Therefore this function is now deprecated and is just a stub. .. deprecated:: 2.46 This function now does nothing. Use other memory profiling tools instead :param vtable: table of memory allocation routines. .. function:: memdup(mem: ~typing.Any, byte_size: int) -> ~typing.Any | None Allocates ``byte_size`` bytes of memory, and copies ``byte_size`` bytes into it from ``mem``\. If ``mem`` is ``NULL`` it returns ``NULL``\. .. deprecated:: 2.68 Use :obj:`~gi.repository.GLib.memdup2` instead, as it accepts a gsize argument for ``byte_size``\, avoiding the possibility of overflow in a ``gsize`` → ``guint`` conversion :param mem: the memory to copy :param byte_size: the number of bytes to copy :return: a pointer to the newly-allocated copy of the memory .. function:: memdup2(mem: ~typing.Any, byte_size: int) -> ~typing.Any | None Allocates ``byte_size`` bytes of memory, and copies ``byte_size`` bytes into it from ``mem``\. If ``mem`` is ``NULL`` it returns ``NULL``\. This replaces :obj:`~gi.repository.GLib.memdup`\, which was prone to integer overflows when converting the argument from a ``gsize`` to a ``guint``\. .. versionadded:: 2.68 :param mem: the memory to copy :param byte_size: the number of bytes to copy :return: a pointer to the newly-allocated copy of the memory .. function:: mkdir(filename: str, mode: int) -> int A wrapper for the POSIX mkdir() function. The mkdir() function attempts to create a directory with the given name and permissions. The mode argument is ignored on Windows. See your C library manual for more details about mkdir(). .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param mode: permissions to use for the newly created directory :return: 0 if the directory was successfully created, -1 if an error occurred .. function:: mkdir_with_parents(pathname: str, mode: int) -> int Create a directory if it doesn't already exist. Create intermediate parent directories as needed, too. .. versionadded:: 2.8 :param pathname: a pathname in the GLib file name encoding :param mode: permissions to use for newly created directories :return: 0 if the directory already exists, or was successfully created. Returns -1 if an error occurred, with errno set. .. function:: node_pop_allocator() -> None .. function:: node_push_allocator(allocator: ~gi.repository.GLib.Allocator) -> None :param allocator: .. function:: nullify_pointer(nullify_location: ~typing.Any) -> None Set the pointer at the specified location to :const:`None`. :param nullify_location: the memory address of the pointer. .. function:: number_parser_error_quark() -> int .. function:: on_error_query(prg_name: str) -> None Prompts the user with ``[E]xit, [H]alt, show [S]tack trace or [P]roceed``\. This function is intended to be used for debugging use only. The following example shows how it can be used together with the :func:`~gi.repository.GLib.log` functions. .. code-block:: C :dedent: #include static void log_handler (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer user_data) { g_log_default_handler (log_domain, log_level, message, user_data); g_on_error_query (MY_PROGRAM_NAME); } int main (int argc, char *argv[]) { g_log_set_handler (MY_LOG_DOMAIN, G_LOG_LEVEL_WARNING | G_LOG_LEVEL_ERROR | G_LOG_LEVEL_CRITICAL, log_handler, NULL); ... If "[E]xit" is selected, the application terminates with a call to _exit(0). If "[S]tack" trace is selected, :func:`~gi.repository.GLib.on_error_stack_trace` is called. This invokes gdb, which attaches to the current process and shows a stack trace. The prompt is then shown again. If "[P]roceed" is selected, the function returns. This function may cause different actions on non-UNIX platforms. On Windows consider using the ``G_DEBUGGER`` environment variable (see `Running GLib Applications `__\) and calling :func:`~gi.repository.GLib.on_error_stack_trace` instead. :param prg_name: the program name, needed by gdb for the "[S]tack trace" option. If ``prg_name`` is :const:`None`, :func:`~gi.repository.GLib.get_prgname` is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called) .. function:: on_error_stack_trace(prg_name: str) -> None Invokes gdb, which attaches to the current process and shows a stack trace. Called by :func:`~gi.repository.GLib.on_error_query` when the "[S]tack trace" option is selected. You can get the current process's program name with :func:`~gi.repository.GLib.get_prgname`, assuming that you have called gtk_init() or gdk_init(). This function may cause different actions on non-UNIX platforms. When running on Windows, this function is *not* called by :func:`~gi.repository.GLib.on_error_query`. If called directly, it will raise an exception, which will crash the program. If the ``G_DEBUGGER`` environment variable is set, a debugger will be invoked to attach and handle that exception (see `Running GLib Applications `__\). :param prg_name: the program name, needed by gdb for the "[S]tack trace" option .. function:: once_init_enter(location: ~typing.Any) -> ~typing.Tuple[bool, ~typing.Any] :param location: .. function:: once_init_enter_impl(location: int) -> bool :param location: .. function:: once_init_enter_pointer(location: ~typing.Any) -> bool :param location: .. function:: once_init_leave(location: ~typing.Any, result: int) -> ~typing.Any :param location: :param result: .. function:: once_init_leave_pointer(location: ~typing.Any, result: ~typing.Any = None) -> None :param location: :param result: .. function:: open(filename: str, flags: int, mode: int) -> int A wrapper for the POSIX open() function. The open() function is used to convert a pathname into a file descriptor. On POSIX systems file descriptors are implemented by the operating system. On Windows, it's the C library that implements open() and file descriptors. The actual Win32 API for opening files is quite different, see MSDN documentation for CreateFile(). The Win32 API uses file handles, which are more randomish integers, not small integers like file descriptors. Because file descriptors are specific to the C library on Windows, the file descriptor returned by this function makes sense only to functions in the same C library. Thus if the GLib-using code uses a different C library than GLib does, the file descriptor returned by this function cannot be passed to C library functions like write() or read(). See your C library manual for more details about open(). .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param flags: as in open() :param mode: as in open() :return: a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from open(). .. function:: option_error_quark() -> int .. function:: parse_debug_string(string: str | None, keys: list[~gi.repository.GLib.DebugKey]) -> int Parses a string containing debugging options into a unsigned :obj:`int` containing bit flags. This is used within GDK and GTK to parse the debug options passed on the command line or through environment variables. If ``string`` is equal to "all", all flags are set. Any flags specified along with "all" in ``string`` are inverted; thus, "all,foo,bar" or "foo,bar,all" sets all flags except those corresponding to "foo" and "bar". If ``string`` is equal to "help", all the available keys in ``keys`` are printed out to standard error. :param string: a list of debug options separated by colons, spaces, or commas, or :const:`None`. :param keys: pointer to an array of :obj:`~gi.repository.GLib.DebugKey` which associate strings with bit flags. :return: the combined set of bit flags. .. function:: path_buf_equal(v1: ~typing.Any, v2: ~typing.Any) -> bool :param v1: :param v2: .. function:: path_get_basename(file_name: str) -> str Gets the last component of the filename. If ``file_name`` ends with a directory separator it gets the component before the last slash. If ``file_name`` consists only of directory separators (and on Windows, possibly a drive letter), a single separator is returned. If ``file_name`` is empty, it gets ".". :param file_name: the name of the file :return: a newly allocated string containing the last component of the filename .. function:: path_get_dirname(file_name: str) -> str Gets the directory components of a file name. For example, the directory component of ``/usr/bin/test`` is ``/usr/bin``\. The directory component of ``/`` is ``/``\. If the file name has no directory components "." is returned. The returned string should be freed when no longer needed. :param file_name: the name of the file :return: the directory components of the file .. function:: path_is_absolute(file_name: str) -> bool Returns :const:`True` if the given ``file_name`` is an absolute file name. Note that this is a somewhat vague concept on Windows. On POSIX systems, an absolute file name is well-defined. It always starts from the single root directory. For example "/usr/local". On Windows, the concepts of current drive and drive-specific current directory introduce vagueness. This function interprets as an absolute file name one that either begins with a directory separator such as "\Users\tml" or begins with the root on a drive, for example "C:\Windows". The first case also includes UNC paths such as "\\myserver\docs\foo". In all cases, either slashes or backslashes are accepted. Note that a file name relative to the current drive root does not truly specify a file uniquely over time and across processes, as the current drive is a per-process value and can be changed. File names relative the current directory on some specific drive, such as "D:foo/bar", are not interpreted as absolute by this function, but they obviously are not relative to the normal current directory as returned by getcwd() or :func:`~gi.repository.GLib.get_current_dir` either. Such paths should be avoided, or need to be handled using Windows-specific code. :param file_name: a file name :return: :const:`True` if ``file_name`` is absolute .. function:: path_skip_root(file_name: str) -> str | None Returns a pointer into ``file_name`` after the root component, i.e. after the "/" in UNIX or "C:\" under Windows. If ``file_name`` is not an absolute path it returns :const:`None`. :param file_name: a file name :return: a pointer into ``file_name`` after the root component .. function:: pattern_match_simple(pattern: str, string: str) -> bool Matches a string against a pattern given as a string. If this function is to be called in a loop, it’s more efficient to compile the pattern once with :obj:`~gi.repository.GLib.PatternSpec.new` and call :obj:`~gi.repository.GLib.PatternSpec.match_string` repeatedly. :param pattern: the UTF-8 encoded pattern :param string: the UTF-8 encoded string to match :return: :const:`True` if ``string`` matches ``pspec`` .. function:: pointer_bit_lock(address: ~typing.Any, lock_bit: int) -> None This is equivalent to g_bit_lock, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of the pointer. While ``address`` has a ``volatile`` qualifier, this is a historical artifact and the argument passed to it should not be ``volatile``\. .. versionadded:: 2.30 :param address: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param lock_bit: a bit value between 0 and 31 .. function:: pointer_bit_lock_and_get(address: ~typing.Any, lock_bit: int) -> int This is equivalent to g_bit_lock, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of the pointer. .. versionadded:: 2.80 :param address: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param lock_bit: a bit value between 0 and 31 .. function:: pointer_bit_lock_mask_ptr(ptr: ~typing.Any, lock_bit: int, set: bool, preserve_mask: int, preserve_ptr: ~typing.Any = None) -> ~typing.Any | None This mangles ``ptr`` as :func:`~gi.repository.GLib.pointer_bit_lock` and :func:`~gi.repository.GLib.pointer_bit_unlock` do. .. versionadded:: 2.80 :param ptr: the pointer to mask :param lock_bit: the bit to set/clear. If set to ``G_MAXUINT``\, the lockbit is taken from ``preserve_ptr`` or ``ptr`` (depending on ``preserve_mask``\). :param set: whether to set (lock) the bit or unset (unlock). This has no effect, if ``lock_bit`` is set to ``G_MAXUINT``\. :param preserve_mask: if non-zero, a bit-mask for ``preserve_ptr``\. The ``preserve_mask`` bits from ``preserve_ptr`` are set in the result. Note that the ``lock_bit`` bit will be always set according to ``set``\, regardless of ``preserve_mask`` and ``preserve_ptr`` (unless ``lock_bit`` is ``G_MAXUINT``\). :param preserve_ptr: if ``preserve_mask`` is non-zero, the bits from this pointer are set in the result. :return: the mangled pointer. .. function:: pointer_bit_trylock(address: ~typing.Any, lock_bit: int) -> bool This is equivalent to :func:`~gi.repository.GLib.bit_trylock`, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of the pointer. While ``address`` has a ``volatile`` qualifier, this is a historical artifact and the argument passed to it should not be ``volatile``\. .. versionadded:: 2.30 :param address: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param lock_bit: a bit value between 0 and 31 :return: :const:`True` if the lock was acquired .. function:: pointer_bit_unlock(address: ~typing.Any, lock_bit: int) -> None This is equivalent to g_bit_unlock, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of the pointer. While ``address`` has a ``volatile`` qualifier, this is a historical artifact and the argument passed to it should not be ``volatile``\. .. versionadded:: 2.30 :param address: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param lock_bit: a bit value between 0 and 31 .. function:: pointer_bit_unlock_and_set(address: ~typing.Any, lock_bit: int, ptr: ~typing.Any, preserve_mask: int) -> None This is equivalent to :func:`~gi.repository.GLib.pointer_bit_unlock` and atomically setting the pointer value. Note that the lock bit will be cleared from the pointer. If the unlocked pointer that was set is not identical to ``ptr``\, an assertion fails. In other words, ``ptr`` must have ``lock_bit`` unset. This also means, you usually can only use this on the lowest bits. .. versionadded:: 2.80 :param address: a pointer to a :obj:`~gi.repository.gpointer`\-sized value :param lock_bit: a bit value between 0 and 31 :param ptr: the new pointer value to set :param preserve_mask: if non-zero, those bits of the current pointer in ``address`` are preserved. Note that the ``lock_bit`` bit will be always set according to ``set``\, regardless of ``preserve_mask`` and the currently set value in ``address``\. .. function:: poll(fds: ~gi.repository.GLib.PollFD, nfds: int, timeout: int) -> int Polls ``fds``\, as with the poll() system call, but portably. (On systems that don't have poll(), it is emulated using select().) This is used internally by :obj:`~gi.repository.GLib.MainContext`\, but it can be called directly if you need to block until a file descriptor is ready, but don't want to run the full main loop. Each element of ``fds`` is a :obj:`~gi.repository.GLib.PollFD` describing a single file descriptor to poll. The ``fd`` field indicates the file descriptor, and the ``events`` field indicates the events to poll for. On return, the ``revents`` fields will be filled with the events that actually occurred. On POSIX systems, the file descriptors in ``fds`` can be any sort of file descriptor, but the situation is much more complicated on Windows. If you need to use :func:`~gi.repository.GLib.poll` in code that has to run on Windows, the easiest solution is to construct all of your :obj:`~gi.repository.GLib.PollFD` with g_io_channel_win32_make_pollfd(). .. versionadded:: 2.20 :param fds: file descriptors to poll :param nfds: the number of file descriptors in ``fds`` :param timeout: amount of time to wait, in milliseconds, or -1 to wait forever :return: the number of entries in ``fds`` whose ``revents`` fields were filled in, or 0 if the operation timed out, or -1 on error or if the call was interrupted. .. function:: prefix_error_literal(err: ~gi.repository.GLib.GError | None, prefix: str) -> ~gi.repository.GLib.GError | None Prefixes ``prefix`` to an existing error message. If ``err`` or ``err`` is :const:`None` (i.e.: no error variable) then do nothing. .. versionadded:: 2.70 :param err: a return location for a :obj:`~gi.repository.GLib.Error`\, or :const:`None` :param prefix: string to prefix ``err`` with .. function:: propagate_error(src: ~gi.repository.GLib.GError) -> ~gi.repository.GLib.GError | None If ``dest`` is :const:`None`, free ``src``\; otherwise, moves ``src`` into ``dest``\. The error variable ``dest`` points to must be :const:`None`. ``src`` must be non-:const:`None`. Note that ``src`` is no longer valid after this call. If you want to keep using the same GError\*, you need to set it to :const:`None` after calling this function on it. :param src: error to move into the return location .. function:: qsort_with_data(pbase: ~typing.Any, total_elems: int, size: int, compare_func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], user_data: ~typing.Any = None) -> None This is just like the standard C ```qsort()`` `__ function, but the comparison routine accepts a user data argument (like ```qsort_r()`` `__\). Unlike ``qsort()``\, this is guaranteed to be a stable sort (since GLib 2.32). .. deprecated:: 2.82 ``total_elems`` is too small to represent larger arrays; use :obj:`~gi.repository.GLib.sort_array` instead :param pbase: start of array to sort :param total_elems: elements in the array :param size: size of each element :param compare_func: function to compare elements :param user_data: data to pass to ``compare_func`` .. function:: quark_from_static_string(string: str | None = None) -> int Gets the :obj:`~gi.repository.GLib.Quark` identifying the given (static) string. If the string does not currently have an associated :obj:`~gi.repository.GLib.Quark`\, a new :obj:`~gi.repository.GLib.Quark` is created, linked to the given string. Note that this function is identical to :func:`~gi.repository.GLib.quark_from_string` except that if a new :obj:`~gi.repository.GLib.Quark` is created the string itself is used rather than a copy. This saves memory, but can only be used if the string will continue to exist until the program terminates. It can be used with statically allocated strings in the main program, but not with statically allocated memory in dynamically loaded modules, if you expect to ever unload the module again (e.g. do not use this function in GTK theme engines). 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++. :param string: a string :return: the :obj:`~gi.repository.GLib.Quark` identifying the string, or 0 if ``string`` is :const:`None` .. function:: quark_from_string(string: str | None = None) -> int Gets the :obj:`~gi.repository.GLib.Quark` identifying the given string. If the string does not currently have an associated :obj:`~gi.repository.GLib.Quark`\, a new :obj:`~gi.repository.GLib.Quark` is created, using a copy of the string. 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++. :param string: a string :return: the :obj:`~gi.repository.GLib.Quark` identifying the string, or 0 if ``string`` is :const:`None` .. function:: quark_to_string(quark: int) -> str Gets the string associated with the given :obj:`~gi.repository.GLib.Quark`\. :param quark: a :obj:`~gi.repository.GLib.Quark`\. :return: the string associated with the :obj:`~gi.repository.GLib.Quark` .. function:: quark_try_string(string: str | None = None) -> int Gets the :obj:`~gi.repository.GLib.Quark` associated with the given string, or 0 if string is :const:`None` or it has no associated :obj:`~gi.repository.GLib.Quark`\. If you want the GQuark to be created if it doesn't already exist, use :func:`~gi.repository.GLib.quark_from_string` or :func:`~gi.repository.GLib.quark_from_static_string`. This function must not be used before library constructors have finished running. :param string: a string :return: the :obj:`~gi.repository.GLib.Quark` associated with the string, or 0 if ``string`` is :const:`None` or there is no :obj:`~gi.repository.GLib.Quark` associated with it .. function:: random_double() -> float Returns a random :obj:`float` equally distributed over the range [0..1). :return: a random number .. function:: random_double_range(begin: float, end: float) -> float Returns a random :obj:`float` equally distributed over the range [``begin``\..``end``\). :param begin: lower closed bound of the interval :param end: upper open bound of the interval :return: a random number .. function:: random_int() -> int Return a random :obj:`int` equally distributed over the range [0..2^32-1]. :return: a random number .. function:: random_int_range(begin: int, end: int) -> int Returns a random :obj:`int` equally distributed over the range [``begin``\..``end``\-1]. :param begin: lower closed bound of the interval :param end: upper open bound of the interval :return: a random number .. function:: random_set_seed(seed: int) -> None Sets the seed for the global random number generator, which is used by the ``g_random_``\* functions, to ``seed``\. :param seed: a value to reinitialize the global random number generator .. function:: rc_box_acquire(mem_block: ~typing.Any) -> ~typing.Any Acquires a reference on the data pointed by ``mem_block``\. .. versionadded:: 2.58 :param mem_block: a pointer to reference counted data :return: a pointer to the data, with its reference count increased .. function:: rc_box_alloc(block_size: int) -> ~typing.Any Allocates ``block_size`` bytes of memory, and adds 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. .. versionadded:: 2.58 :param block_size: the size of the allocation, must be greater than 0 :return: a pointer to the allocated memory .. function:: rc_box_alloc0(block_size: int) -> ~typing.Any Allocates ``block_size`` bytes of memory, and adds 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. .. versionadded:: 2.58 :param block_size: the size of the allocation, must be greater than 0 :return: a pointer to the allocated memory .. function:: rc_box_dup(block_size: int, mem_block: ~typing.Any) -> ~typing.Any Allocates a new block of data with reference counting semantics, and copies ``block_size`` bytes of ``mem_block`` into it. .. versionadded:: 2.58 :param block_size: the number of bytes to copy, must be greater than 0 :param mem_block: the memory to copy :return: a pointer to the allocated memory .. function:: rc_box_get_size(mem_block: ~typing.Any) -> int Retrieves the size of the reference counted data pointed by ``mem_block``\. .. versionadded:: 2.58 :param mem_block: a pointer to reference counted data :return: the size of the data, in bytes .. function:: rc_box_release(mem_block: ~typing.Any) -> None 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``\. .. versionadded:: 2.58 :param mem_block: a pointer to reference counted data .. function:: rc_box_release_full(mem_block: ~typing.Any, clear_func: ~typing.Callable[[~typing.Any], None]) -> None 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``\. .. versionadded:: 2.58 :param mem_block: a pointer to reference counted data :param clear_func: a function to call when clearing the data .. function:: realloc(mem: ~typing.Any, n_bytes: int) -> ~typing.Any | None Reallocates the memory pointed to by ``mem``\, so that it now has space for ``n_bytes`` bytes of memory. It returns the new address of the memory, which may have been moved. ``mem`` may be :const:`None`, in which case it's considered to have zero-length. ``n_bytes`` may be 0, in which case :const:`None` will be returned and ``mem`` will be freed unless it is :const:`None`. If the allocation fails (because the system is out of memory), the program is terminated. :param mem: the memory to reallocate :param n_bytes: new size of the memory in bytes :return: the new address of the allocated memory .. function:: realloc_n(mem: ~typing.Any, n_blocks: int, n_block_bytes: int) -> ~typing.Any | None This function is similar to :func:`~gi.repository.GLib.realloc`, allocating (``n_blocks`` \* ``n_block_bytes``\) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. .. versionadded:: 2.24 :param mem: the memory to reallocate :param n_blocks: the number of blocks to allocate :param n_block_bytes: the size of each block in bytes :return: the new address of the allocated memory .. function:: regex_check_replacement(replacement: str) -> ~typing.Tuple[bool, bool] :param replacement: .. function:: regex_error_quark() -> int .. function:: regex_escape_nul(string: str, length: int) -> str :param string: :param length: .. function:: regex_escape_string(string: str, length: int) -> str :param string: :param length: .. function:: regex_match_simple(pattern: str, string: str, compile_options: ~gi.repository.GLib.RegexCompileFlags, match_options: ~gi.repository.GLib.RegexMatchFlags) -> bool :param pattern: :param string: :param compile_options: :param match_options: .. function:: regex_split_simple(pattern: str, string: str, compile_options: ~gi.repository.GLib.RegexCompileFlags, match_options: ~gi.repository.GLib.RegexMatchFlags) -> list[str] :param pattern: :param string: :param compile_options: :param match_options: .. function:: reload_user_special_dirs_cache() -> None Resets the cache used for :func:`~gi.repository.GLib.get_user_special_dir`, so that the latest on-disk version is used. Call this only if you just changed the data on disk yourself. Due to thread safety issues this may cause leaking of strings that were previously returned from :func:`~gi.repository.GLib.get_user_special_dir` that can't be freed. We ensure to only leak the data for the directories that actually changed value though. .. versionadded:: 2.22 .. function:: remove(filename: str) -> int A wrapper for the POSIX remove() function. The remove() function deletes a name from the filesystem. See your C library manual for more details about how remove() works on your system. On Unix, remove() removes also directories, as it calls unlink() for files and rmdir() for directories. On Windows, although remove() in the C library only works for files, this function tries first remove() and then if that fails rmdir(), and thus works for both files and directories. Note however, that on Windows, it is in general not possible to remove a file that is open to some process, or mapped into memory. If this function fails on Windows you can't infer too much from the errno value. rmdir() is tried regardless of what caused remove() to fail. Any errno value set by remove() will be overwritten by that set by rmdir(). .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :return: 0 if the file was successfully removed, -1 if an error occurred .. function:: rename(oldfilename: str, newfilename: str) -> int A wrapper for the POSIX rename() function. The rename() function renames a file, moving it between directories if required. See your C library manual for more details about how rename() works on your system. It is not possible in general on Windows to rename a file that is open to some process. .. versionadded:: 2.6 :param oldfilename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param newfilename: a pathname in the GLib file name encoding :return: 0 if the renaming succeeded, -1 if an error occurred .. function:: rmdir(filename: str) -> int A wrapper for the POSIX rmdir() function. The rmdir() function deletes a directory from the filesystem. See your C library manual for more details about how rmdir() works on your system. .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :return: 0 if the directory was successfully removed, -1 if an error occurred .. function:: sequence_foreach_range(begin: ~gi.repository.GLib.SequenceIter, end: ~gi.repository.GLib.SequenceIter, func: ~typing.Callable[[~typing.Any, ~typing.Any], None], user_data: ~typing.Any = None) -> None :param begin: :param end: :param func: :param user_data: .. function:: sequence_get(iter: ~gi.repository.GLib.SequenceIter) -> ~typing.Any | None :param iter: .. function:: sequence_insert_before(iter: ~gi.repository.GLib.SequenceIter, data: ~typing.Any = None) -> ~gi.repository.GLib.SequenceIter :param iter: :param data: .. function:: sequence_move(src: ~gi.repository.GLib.SequenceIter, dest: ~gi.repository.GLib.SequenceIter) -> None :param src: :param dest: .. function:: sequence_move_range(dest: ~gi.repository.GLib.SequenceIter, begin: ~gi.repository.GLib.SequenceIter, end: ~gi.repository.GLib.SequenceIter) -> None :param dest: :param begin: :param end: .. function:: sequence_range_get_midpoint(begin: ~gi.repository.GLib.SequenceIter, end: ~gi.repository.GLib.SequenceIter) -> ~gi.repository.GLib.SequenceIter :param begin: :param end: .. function:: sequence_remove(iter: ~gi.repository.GLib.SequenceIter) -> None :param iter: .. function:: sequence_remove_range(begin: ~gi.repository.GLib.SequenceIter, end: ~gi.repository.GLib.SequenceIter) -> None :param begin: :param end: .. function:: sequence_set(iter: ~gi.repository.GLib.SequenceIter, data: ~typing.Any = None) -> None :param iter: :param data: .. function:: sequence_sort_changed(iter: ~gi.repository.GLib.SequenceIter, cmp_func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], cmp_data: ~typing.Any = None) -> None :param iter: :param cmp_func: :param cmp_data: .. function:: sequence_sort_changed_iter(iter: ~gi.repository.GLib.SequenceIter, iter_cmp: ~typing.Callable[[~gi.repository.GLib.SequenceIter, ~gi.repository.GLib.SequenceIter, ~typing.Any], int], cmp_data: ~typing.Any = None) -> None :param iter: :param iter_cmp: :param cmp_data: .. function:: sequence_swap(a: ~gi.repository.GLib.SequenceIter, b: ~gi.repository.GLib.SequenceIter) -> None :param a: :param b: .. function:: set_application_name(application_name: str) -> None Sets a human-readable name for the application. This name should be localized if possible, and is intended for display to the user. Contrast with :func:`~gi.repository.GLib.set_prgname`, which sets a non-localized name. :func:`~gi.repository.GLib.set_prgname` will be called automatically by gtk_init(), but :func:`~gi.repository.GLib.set_application_name` will not. Note that for thread safety reasons, this function can only be called once. The application name will be used in contexts such as error messages, or when displaying an application's name in the task list. .. versionadded:: 2.2 :param application_name: localized name of the application .. function:: set_error_literal(domain: int, code: int, message: str) -> ~gi.repository.GLib.GError Does nothing if ``err`` is :const:`None`; if ``err`` is non-:const:`None`, then ``err`` must be :const:`None`. A new :obj:`~gi.repository.GLib.Error` is created and assigned to ``err``\. Unlike :func:`~gi.repository.GLib.set_error`, ``message`` is not a printf()-style format string. Use this function if ``message`` contains text you don't have control over, that could include printf() escape sequences. .. versionadded:: 2.18 :param domain: error domain :param code: error code :param message: error message .. function:: set_prgname(prgname: str) -> None Sets the name of the program. This name should not be localized, in contrast to :func:`~gi.repository.GLib.set_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]. Since GLib 2.72, this function can be called multiple times and is fully thread safe. Prior to GLib 2.72, this function could only be called once per process. :param prgname: the name of the program. .. function:: set_prgname_once(prgname: str) -> bool If :func:`~gi.repository.GLib.get_prgname` is not set, this is the same as setting the name via :func:`~gi.repository.GLib.set_prgname` and :const:`True` is returned. Otherwise, does nothing and returns :const:`False`. This is thread-safe. :param prgname: the name of the program. :return: whether g_prgname was initialized by the call. .. function:: setenv(variable: str, value: str, overwrite: bool) -> bool Sets an environment variable. On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name cannot contain '='. On Windows, they should be in UTF-8. Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed. You should be mindful of the fact that environment variable handling in UNIX is not thread-safe, and your program may crash if one thread calls :func:`~gi.repository.GLib.setenv` while another thread is calling getenv(). (And note that many functions, such as gettext(), call getenv() internally.) This function is only safe to use at the very start of your program, before creating any other threads (or creating objects that create worker threads of their own). If you need to set up the environment for a child process, you can use :func:`~gi.repository.GLib.get_environ` to get an environment array, modify that with :func:`~gi.repository.GLib.environ_setenv` and :func:`~gi.repository.GLib.environ_unsetenv`, and then pass that array directly to execvpe(), :func:`~gi.repository.GLib.spawn_async`, or the like. .. versionadded:: 2.4 :param variable: the environment variable to set, must not contain '='. :param value: the value for to set the variable to. :param overwrite: whether to change the variable if it already exists. :return: :const:`False` if the environment variable couldn't be set. .. function:: shell_error_quark() -> int .. function:: shell_parse_argv(command_line: str) -> ~typing.Tuple[bool, list[str]] Parses a command line into an argument vector, in much the same way the shell would, but without many of the expansions the shell would perform (variable expansion, globs, operators, filename expansion, etc. are not supported). The results are defined to be the same as those you would get from a UNIX98 ``/bin/sh``\, as long as the input contains none of the unsupported shell expansions. If the input does contain such expansions, they are passed through literally. Possible errors are those from the %G_SHELL_ERROR domain. In particular, if ``command_line`` is an empty string (or a string containing only whitespace), :const:`~gi.repository.GLib.ShellError.EMPTY_STRING` will be returned. It’s guaranteed that ``argvp`` will be a non-empty array if this function returns successfully. Free the returned vector with :func:`~gi.repository.GLib.strfreev`. :param command_line: command line to parse :return: :const:`True` on success, :const:`False` if error set .. function:: shell_quote(unquoted_string: str) -> str Quotes a string so that the shell (/bin/sh) will interpret the quoted string to mean ``unquoted_string``\. If you pass a filename to the shell, for example, you should first quote it with this function. The return value must be freed with :func:`~gi.repository.GLib.free`. The quoting style used is undefined (single or double quotes may be used). :param unquoted_string: a literal string :return: quoted string .. function:: shell_unquote(quoted_string: str) -> str Unquotes a string as the shell (/bin/sh) would. This function only handles quotes; if a string contains file globs, arithmetic operators, variables, backticks, redirections, or other special-to-the-shell features, the result will be different from the result a real shell would produce (the variables, backticks, etc. will be passed through literally instead of being expanded). This function is guaranteed to succeed if applied to the result of :func:`~gi.repository.GLib.shell_quote`. If it fails, it returns :const:`None` and sets the error. The ``quoted_string`` need not actually contain quoted or escaped text; :func:`~gi.repository.GLib.shell_unquote` simply goes through the string and unquotes/unescapes anything that the shell would. Both single and double quotes are handled, as are escapes including escaped newlines. The return value must be freed with :func:`~gi.repository.GLib.free`. Possible errors are in the %G_SHELL_ERROR domain. Shell quoting rules are a bit strange. Single quotes preserve the literal string exactly. escape sequences are not allowed; not even ``\'`` - if you want a ``'`` in the quoted text, you have to do something like ``'foo'\''bar'``\. Double quotes allow ``$``\, ````,``\"``,``\`, and newline to be escaped with backslash. Otherwise double quotes preserve things literally. :param quoted_string: shell-quoted string :return: an unquoted string .. function:: slice_alloc(block_size: int) -> ~typing.Any | None Allocates a block of memory from the libc allocator. The block address handed out can be expected to be aligned to at least ``1 * sizeof (void*)``\. Since GLib 2.76 this always uses the system malloc() implementation internally. .. versionadded:: 2.10 :param block_size: the number of bytes to allocate :return: a pointer to the allocated memory block, which will be :const:`None` if and only if ``mem_size`` is 0 .. function:: slice_alloc0(block_size: int) -> ~typing.Any | None Allocates a block of memory via :func:`~gi.repository.GLib.slice_alloc` and initializes the returned memory to 0. Since GLib 2.76 this always uses the system malloc() implementation internally. .. versionadded:: 2.10 :param block_size: the number of bytes to allocate :return: a pointer to the allocated block, which will be :const:`None` if and only if ``mem_size`` is 0 .. function:: slice_free1(block_size: int, mem_block: ~typing.Any = None) -> None Frees a block of memory. The memory must have been allocated via :func:`~gi.repository.GLib.slice_alloc` or :func:`~gi.repository.GLib.slice_alloc0` and the ``block_size`` has to match the size specified upon allocation. Note that the exact release behaviour can be changed with the [``G_DEBUG=gc-friendly``\][G_DEBUG] environment variable. If ``mem_block`` is :const:`None`, this function does nothing. Since GLib 2.76 this always uses the system free_sized() implementation internally. .. versionadded:: 2.10 :param block_size: the size of the block :param mem_block: a pointer to the block to free .. function:: slice_free_chain_with_offset(block_size: int, mem_chain: ~typing.Any, next_offset: int) -> None Frees a linked list of memory blocks of structure type ``type``\. The memory blocks must be equal-sized, allocated via :func:`~gi.repository.GLib.slice_alloc` or :func:`~gi.repository.GLib.slice_alloc0` and linked together by a ``next`` pointer (similar to ``GSList``). The offset of the ``next`` field in each block is passed as third argument. Note that the exact release behaviour can be changed with the [``G_DEBUG=gc-friendly``\][G_DEBUG] environment variable. If ``mem_chain`` is :const:`None`, this function does nothing. Since GLib 2.76 this always uses the system free_sized() implementation internally. .. versionadded:: 2.10 :param block_size: the size of the blocks :param mem_chain: a pointer to the first block of the chain :param next_offset: the offset of the ``next`` field in the blocks .. function:: slice_get_config(ckey: ~gi.repository.GLib.SliceConfig) -> int :param ckey: .. function:: slice_get_config_state(ckey: ~gi.repository.GLib.SliceConfig, address: int, n_values: int) -> int :param ckey: :param address: :param n_values: .. function:: slice_set_config(ckey: ~gi.repository.GLib.SliceConfig, value: int) -> None :param ckey: :param value: .. function:: slist_pop_allocator() -> None .. function:: slist_push_allocator(allocator: ~gi.repository.GLib.Allocator) -> None :param allocator: .. function:: source_remove(tag: int) -> bool :param tag: .. function:: source_remove_by_funcs_user_data(funcs: ~gi.repository.GLib.SourceFuncs, user_data: ~typing.Any = None) -> bool :param funcs: :param user_data: .. function:: source_remove_by_user_data(user_data: ~typing.Any = None) -> bool :param user_data: .. function:: source_set_name_by_id(tag: int, name: str) -> None :param tag: :param name: .. function:: spaced_primes_closest(num: int) -> int Gets the smallest prime number from a built-in array of primes which is larger than ``num``\. This is used within GLib to calculate the optimum size of a :obj:`~gi.repository.GLib.HashTable`\. The built-in array of primes ranges from 11 to 13845163 such that each prime is approximately 1.5-2 times the previous prime. :param num: a :obj:`int` :return: the smallest prime number from a built-in array of primes which is larger than ``num`` .. function:: spawn_async(argv: ~typing.Sequence[str], envp: ~typing.Sequence[str] | None = None, working_directory: str | None = None, flags: ~gi.repository.GLib.SpawnFlags = , child_setup: ~typing.Callable[[~typing.Any], None] | None = None, user_data: ~typing.Any = None, standard_input: bool = False, standard_output: bool = False, standard_error: bool = False) -> tuple[~gi._gi.Pid, int | None, int | None, int | None] spawn_async(argv, envp=None, working_directory=None, flags=0, child_setup=None, user_data=None, standard_input=None, standard_output=None, standard_error=None) -> (pid, stdin, stdout, stderr) Execute a child program asynchronously within a glib.MainLoop() See the reference manual for a complete reference. :param argv: child's argument vector :param envp: child's environment, or :const:`None` to inherit parent's :param working_directory: child's current working directory, or :const:`None` to inherit parent's :param flags: flags from :obj:`~gi.repository.GLib.SpawnFlags` :param child_setup: function to run in the child just before ``exec()`` :param user_data: user data for ``child_setup`` :param standard_input: :param standard_output: :param standard_error: :return: :const:`True` on success, :const:`False` if error is set .. function:: spawn_async_with_fds(working_directory: str | None, argv: list[str], envp: list[str] | None, flags: ~gi.repository.GLib.SpawnFlags, child_setup: ~typing.Callable[[~typing.Any], None] | None, user_data: ~typing.Any, stdin_fd: int, stdout_fd: int, stderr_fd: int) -> ~typing.Tuple[bool, int] Executes a child program asynchronously. Identical to :func:`~gi.repository.GLib.spawn_async_with_pipes_and_fds` but with ``n_fds`` set to zero, so no FD assignments are used. .. versionadded:: 2.58 :param working_directory: child's current working directory, or :const:`None` to inherit parent's, in the GLib file name encoding :param argv: child's argument vector, in the GLib file name encoding; it must be non-empty and :const:`None`-terminated :param envp: child's environment, or :const:`None` to inherit parent's, in the GLib file name encoding :param flags: flags from :obj:`~gi.repository.GLib.SpawnFlags` :param child_setup: function to run in the child just before ``exec()`` :param user_data: user data for ``child_setup`` :param stdin_fd: file descriptor to use for child's stdin, or ``-1`` :param stdout_fd: file descriptor to use for child's stdout, or ``-1`` :param stderr_fd: file descriptor to use for child's stderr, or ``-1`` :return: :const:`True` on success, :const:`False` if an error was set .. function:: spawn_async_with_pipes(working_directory: str | None, argv: list[str], envp: list[str] | None, flags: ~gi.repository.GLib.SpawnFlags, child_setup: ~typing.Callable[[~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> ~typing.Tuple[bool, int, int, int, int] Identical to :func:`~gi.repository.GLib.spawn_async_with_pipes_and_fds` but with ``n_fds`` set to zero, so no FD assignments are used. :param working_directory: child's current working directory, or :const:`None` to inherit parent's, in the GLib file name encoding :param argv: child's argument vector, in the GLib file name encoding; it must be non-empty and :const:`None`-terminated :param envp: child's environment, or :const:`None` to inherit parent's, in the GLib file name encoding :param flags: flags from :obj:`~gi.repository.GLib.SpawnFlags` :param child_setup: function to run in the child just before ``exec()`` :param user_data: user data for ``child_setup`` :return: :const:`True` on success, :const:`False` if an error was set .. function:: spawn_async_with_pipes_and_fds(working_directory: str | None, argv: list[str], envp: list[str] | None, flags: ~gi.repository.GLib.SpawnFlags, child_setup: ~typing.Callable[[~typing.Any], None] | None, user_data: ~typing.Any, stdin_fd: int, stdout_fd: int, stderr_fd: int, source_fds: list[int] | None = None, target_fds: list[int] | None = None) -> ~typing.Tuple[bool, int, int, int, int] Executes a child program asynchronously (your program will not block waiting for the child to exit). The child program is specified by the only argument that must be provided, ``argv``\. ``argv`` should be a :const:`None`-terminated array of strings, to be passed as the argument vector for the child. The first string in ``argv`` is of course the name of the program to execute. By default, the name of the program must be a full path. If ``flags`` contains the :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` flag, the ``PATH`` environment variable is used to search for the executable. If ``flags`` contains the :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH_FROM_ENVP` flag, the ``PATH`` variable from ``envp`` is used to search for the executable. If both the :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` and :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH_FROM_ENVP` flags are set, the ``PATH`` variable from ``envp`` takes precedence over the environment variable. If the program name is not a full path and :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` flag is not used, then the program will be run from the current directory (or ``working_directory``\, if specified); this might be unexpected or even dangerous in some cases when the current directory is world-writable. On Windows, note that all the string or string vector arguments to this function and the other ``g_spawn*()`` functions are in UTF-8, the GLib file name encoding. Unicode characters that are not part of the system codepage passed in these arguments will be correctly available in the spawned program only if it uses wide character API to retrieve its command line. For C programs built with Microsoft's tools it is enough to make the program have a ``wmain()`` instead of ``main()``\. ``wmain()`` has a wide character argument vector as parameter. At least currently, mingw doesn't support ``wmain()``\, so if you use mingw to develop the spawned program, it should call g_win32_get_command_line() to get arguments in UTF-8. On Windows the low-level child process creation API ``CreateProcess()`` doesn't use argument vectors, but a command line. The C runtime library's ``spawn*()`` family of functions (which :func:`~gi.repository.GLib.spawn_async_with_pipes` eventually calls) paste the argument vector elements together into a command line, and the C runtime startup code does a corresponding reconstruction of an argument vector from the command line, to be passed to ``main()``\. Complications arise when you have argument vector elements that contain spaces or double quotes. The ``spawn*()`` functions don't do any quoting or escaping, but on the other hand the startup code does do unquoting and unescaping in order to enable receiving arguments with embedded spaces or double quotes. To work around this asymmetry, :func:`~gi.repository.GLib.spawn_async_with_pipes` will do quoting and escaping on argument vector elements that need it before calling the C runtime ``spawn()`` function. The returned ``child_pid`` on Windows is a handle to the child process, not its identifier. Process handles and process identifiers are different concepts on Windows. ``envp`` is a :const:`None`-terminated array of strings, where each string has the form ``KEY=VALUE``\. This will become the child's environment. If ``envp`` is :const:`None`, the child inherits its parent's environment. ``flags`` should be the bitwise OR of any flags you want to affect the function's behaviour. The :const:`~gi.repository.GLib.SpawnFlags.DO_NOT_REAP_CHILD` means that the child will not automatically be reaped; you must use a child watch (:func:`~gi.repository.GLib.child_watch_add`) to be notified about the death of the child process, otherwise it will stay around as a zombie process until this process exits. Eventually you must call :func:`~gi.repository.GLib.spawn_close_pid` on the ``child_pid``\, in order to free resources which may be associated with the child process. (On Unix, using a child watch is equivalent to calling waitpid() or handling the ``SIGCHLD`` signal manually. On Windows, calling :func:`~gi.repository.GLib.spawn_close_pid` is equivalent to calling ``CloseHandle()`` on the process handle returned in ``child_pid``\). See :func:`~gi.repository.GLib.child_watch_add`. Open UNIX file descriptors marked as ``FD_CLOEXEC`` will be automatically closed in the child process. :const:`~gi.repository.GLib.SpawnFlags.LEAVE_DESCRIPTORS_OPEN` means that other open file descriptors will be inherited by the child; otherwise all descriptors except stdin/stdout/stderr will be closed before calling ``exec()`` in the child. :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` means that ``argv``\[0] need not be an absolute path, it will be looked for in the ``PATH`` environment variable. :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH_FROM_ENVP` means need not be an absolute path, it will be looked for in the ``PATH`` variable from ``envp``\. If both :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` and :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH_FROM_ENVP` are used, the value from ``envp`` takes precedence over the environment. :const:`~gi.repository.GLib.SpawnFlags.CHILD_INHERITS_STDIN` means that the child will inherit the parent's standard input (by default, the child's standard input is attached to ``/dev/null``\). :const:`~gi.repository.GLib.SpawnFlags.STDIN_FROM_DEV_NULL` explicitly imposes the default behavior. Both flags cannot be enabled at the same time and, in both cases, the ``stdin_pipe_out`` argument is ignored. :const:`~gi.repository.GLib.SpawnFlags.STDOUT_TO_DEV_NULL` means that the child's standard output will be discarded (by default, it goes to the same location as the parent's standard output). :const:`~gi.repository.GLib.SpawnFlags.CHILD_INHERITS_STDOUT` explicitly imposes the default behavior. Both flags cannot be enabled at the same time and, in both cases, the ``stdout_pipe_out`` argument is ignored. :const:`~gi.repository.GLib.SpawnFlags.STDERR_TO_DEV_NULL` means that the child's standard error will be discarded (by default, it goes to the same location as the parent's standard error). :const:`~gi.repository.GLib.SpawnFlags.CHILD_INHERITS_STDERR` explicitly imposes the default behavior. Both flags cannot be enabled at the same time and, in both cases, the ``stderr_pipe_out`` argument is ignored. It is valid to pass the same FD in multiple parameters (e.g. you can pass a single FD for both ``stdout_fd`` and ``stderr_fd``\, and include it in ``source_fds`` too). ``source_fds`` and ``target_fds`` allow zero or more FDs from this process to be remapped to different FDs in the spawned process. If ``n_fds`` is greater than zero, ``source_fds`` and ``target_fds`` must both be non-:const:`None` and the same length. Each FD in ``source_fds`` is remapped to the FD number at the same index in ``target_fds``\. The source and target FD may be equal to simply propagate an FD to the spawned process. FD remappings are processed after standard FDs, so any target FDs which equal ``stdin_fd``\, ``stdout_fd`` or ``stderr_fd`` will overwrite them in the spawned process. ``source_fds`` is supported on Windows since 2.72. :const:`~gi.repository.GLib.SpawnFlags.FILE_AND_ARGV_ZERO` means that the first element of ``argv`` is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally :func:`~gi.repository.GLib.spawn_async_with_pipes` uses ``argv``\[0] as the file to execute, and passes all of ``argv`` to the child. ``child_setup`` and ``user_data`` are a function and user data. On POSIX platforms, the function is called in the child after GLib has performed all the setup it plans to perform (including creating pipes, closing file descriptors, etc.) but before calling ``exec()``\. That is, ``child_setup`` is called just before calling ``exec()`` in the child. Obviously actions taken in this function will only affect the child, not the parent. On Windows, there is no separate ``fork()`` and ``exec()`` functionality. Child processes are created and run with a single API call, ``CreateProcess()``\. There is no sensible thing ``child_setup`` could be used for on Windows so it is ignored and not called. If non-:const:`None`, ``child_pid`` will on Unix be filled with the child's process ID. You can use the process ID to send signals to the child, or to use :func:`~gi.repository.GLib.child_watch_add` (or ``waitpid()``\) if you specified the :const:`~gi.repository.GLib.SpawnFlags.DO_NOT_REAP_CHILD` flag. On Windows, ``child_pid`` will be filled with a handle to the child process only if you specified the :const:`~gi.repository.GLib.SpawnFlags.DO_NOT_REAP_CHILD` flag. You can then access the child process using the Win32 API, for example wait for its termination with the ``WaitFor*()`` functions, or examine its exit code with ``GetExitCodeProcess()``\. You should close the handle with ``CloseHandle()`` or :func:`~gi.repository.GLib.spawn_close_pid` when you no longer need it. If non-:const:`None`, the ``stdin_pipe_out``\, ``stdout_pipe_out``\, ``stderr_pipe_out`` locations will be filled with file descriptors for writing to the child's standard input or reading from its standard output or standard error. The caller of :func:`~gi.repository.GLib.spawn_async_with_pipes` must close these file descriptors when they are no longer in use. If these parameters are :const:`None`, the corresponding pipe won't be created. If ``stdin_pipe_out`` is :const:`None`, the child's standard input is attached to ``/dev/null`` unless :const:`~gi.repository.GLib.SpawnFlags.CHILD_INHERITS_STDIN` is set. If ``stderr_pipe_out`` is NULL, the child's standard error goes to the same location as the parent's standard error unless :const:`~gi.repository.GLib.SpawnFlags.STDERR_TO_DEV_NULL` is set. If ``stdout_pipe_out`` is NULL, the child's standard output goes to the same location as the parent's standard output unless :const:`~gi.repository.GLib.SpawnFlags.STDOUT_TO_DEV_NULL` is set. ``error`` can be :const:`None` to ignore errors, or non-:const:`None` to report errors. If an error is set, the function returns :const:`False`. Errors are reported even if they occur in the child (for example if the executable in ``@argv[0]`` is not found). Typically the ``message`` field of returned errors should be displayed to users. Possible errors are those from the %G_SPAWN_ERROR domain. If an error occurs, ``child_pid``\, ``stdin_pipe_out``\, ``stdout_pipe_out``\, and ``stderr_pipe_out`` will not be filled with valid values. If ``child_pid`` is not :const:`None` and an error does not occur then the returned process reference must be closed using :func:`~gi.repository.GLib.spawn_close_pid`. On modern UNIX platforms, GLib can use an efficient process launching codepath driven internally by ``posix_spawn()``\. This has the advantage of avoiding the fork-time performance costs of cloning the parent process address space, and avoiding associated memory overcommit checks that are not relevant in the context of immediately executing a distinct process. This optimized codepath will be used provided that the following conditions are met: - :const:`~gi.repository.GLib.SpawnFlags.DO_NOT_REAP_CHILD` is set - :const:`~gi.repository.GLib.SpawnFlags.LEAVE_DESCRIPTORS_OPEN` is set - :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH_FROM_ENVP` is not set - ``working_directory`` is :const:`None` - ``child_setup`` is :const:`None` - The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath. If you are writing a GTK application, and the program you are spawning is a graphical application too, then to ensure that the spawned program opens its windows on the right screen, you may want to use ``GdkAppLaunchContext``, ``GAppLaunchContext``, or set the ``DISPLAY`` environment variable. .. versionadded:: 2.68 :param working_directory: child's current working directory, or :const:`None` to inherit parent's, in the GLib file name encoding :param argv: child's argument vector, in the GLib file name encoding; it must be non-empty and :const:`None`-terminated :param envp: child's environment, or :const:`None` to inherit parent's, in the GLib file name encoding :param flags: flags from :obj:`~gi.repository.GLib.SpawnFlags` :param child_setup: function to run in the child just before ``exec()`` :param user_data: user data for ``child_setup`` :param stdin_fd: file descriptor to use for child's stdin, or ``-1`` :param stdout_fd: file descriptor to use for child's stdout, or ``-1`` :param stderr_fd: file descriptor to use for child's stderr, or ``-1`` :param source_fds: array of FDs from the parent process to make available in the child process :param target_fds: array of FDs to remap ``source_fds`` to in the child process :return: :const:`True` on success, :const:`False` if an error was set .. function:: spawn_check_exit_status(wait_status: int) -> bool An old name for :func:`~gi.repository.GLib.spawn_check_wait_status`, deprecated because its name is misleading. Despite the name of the function, ``wait_status`` must be the wait status as returned by :func:`~gi.repository.GLib.spawn_sync`, g_subprocess_get_status(), ``waitpid()``\, etc. On Unix platforms, it is incorrect for it to be the exit status as passed to ``exit()`` or returned by g_subprocess_get_exit_status() or ``WEXITSTATUS()``\. .. versionadded:: 2.34 .. deprecated:: 2.70 Use :func:`~gi.repository.GLib.spawn_check_wait_status` instead, and check whether your code is conflating wait and exit statuses. :param wait_status: A status as returned from :func:`~gi.repository.GLib.spawn_sync` :return: :const:`True` if child exited successfully, :const:`False` otherwise (and ``error`` will be set) .. function:: spawn_check_wait_status(wait_status: int) -> bool Set ``error`` if ``wait_status`` indicates the child exited abnormally (e.g. with a nonzero exit code, or via a fatal signal). The :func:`~gi.repository.GLib.spawn_sync` and :func:`~gi.repository.GLib.child_watch_add` family of APIs return the status of subprocesses encoded in a platform-specific way. On Unix, this is guaranteed to be in the same format waitpid() returns, and on Windows it is guaranteed to be the result of GetExitCodeProcess(). Prior to the introduction of this function in GLib 2.34, interpreting ``wait_status`` required use of platform-specific APIs, which is problematic for software using GLib as a cross-platform layer. Additionally, many programs simply want to determine whether or not the child exited successfully, and either propagate a :obj:`~gi.repository.GLib.Error` or print a message to standard error. In that common case, this function can be used. Note that the error message in ``error`` will contain human-readable information about the wait status. The ``domain`` and ``code`` of ``error`` have special semantics in the case where the process has an "exit code", as opposed to being killed by a signal. On Unix, this happens if WIFEXITED() would be true of ``wait_status``\. On Windows, it is always the case. The special semantics are that the actual exit code will be the code set in ``error``\, and the domain will be %G_SPAWN_EXIT_ERROR. This allows you to differentiate between different exit codes. If the process was terminated by some means other than an exit status (for example if it was killed by a signal), the domain will be %G_SPAWN_ERROR and the code will be :const:`~gi.repository.GLib.SpawnError.FAILED`. This function just offers convenience; you can of course also check the available platform via a macro such as %G_OS_UNIX, and use WIFEXITED() and WEXITSTATUS() on ``wait_status`` directly. Do not attempt to scan or parse the error message string; it may be translated and/or change in future versions of GLib. Prior to version 2.70, :func:`~gi.repository.GLib.spawn_check_exit_status` provides the same functionality, although under a misleading name. .. versionadded:: 2.70 :param wait_status: A platform-specific wait status as returned from :func:`~gi.repository.GLib.spawn_sync` :return: :const:`True` if child exited successfully, :const:`False` otherwise (and ``error`` will be set) .. function:: spawn_close_pid(pid: int) -> None On some platforms, notably Windows, the :obj:`~gi.repository.GLib.Pid` type represents a resource which must be closed to prevent resource leaking. :func:`~gi.repository.GLib.spawn_close_pid` is provided for this purpose. It should be used on all platforms, even though it doesn't do anything under UNIX. :param pid: The process reference to close .. function:: spawn_command_line_async(command_line: str) -> bool A simple version of :func:`~gi.repository.GLib.spawn_async` that parses a command line with :func:`~gi.repository.GLib.shell_parse_argv` and passes it to :func:`~gi.repository.GLib.spawn_async`. Runs a command line in the background. Unlike :func:`~gi.repository.GLib.spawn_async`, the :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` flag is enabled, other flags are not. Note that :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` can have security implications, so consider using :func:`~gi.repository.GLib.spawn_async` directly if appropriate. Possible errors are those from :func:`~gi.repository.GLib.shell_parse_argv` and :func:`~gi.repository.GLib.spawn_async`. The same concerns on Windows apply as for :func:`~gi.repository.GLib.spawn_command_line_sync`. :param command_line: a command line :return: :const:`True` on success, :const:`False` if error is set .. function:: spawn_command_line_sync(command_line: str) -> ~typing.Tuple[bool, list[int], list[int], int] A simple version of :func:`~gi.repository.GLib.spawn_sync` with little-used parameters removed, taking a command line instead of an argument vector. See :func:`~gi.repository.GLib.spawn_sync` for full details. The ``command_line`` argument will be parsed by :func:`~gi.repository.GLib.shell_parse_argv`. Unlike :func:`~gi.repository.GLib.spawn_sync`, the :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` flag is enabled. Note that :const:`~gi.repository.GLib.SpawnFlags.SEARCH_PATH` can have security implications, so consider using :func:`~gi.repository.GLib.spawn_sync` directly if appropriate. Possible errors are those from :func:`~gi.repository.GLib.spawn_sync` and those from :func:`~gi.repository.GLib.shell_parse_argv`. If ``wait_status`` is non-:const:`None`, the platform-specific status of the child is stored there; see the documentation of :func:`~gi.repository.GLib.spawn_check_wait_status` for how to use and interpret this. On Unix platforms, note that it is usually not equal to the integer passed to ``exit()`` or returned from ``main()``\. On Windows, please note the implications of :func:`~gi.repository.GLib.shell_parse_argv` parsing ``command_line``\. Parsing is done according to Unix shell rules, not Windows command interpreter rules. Space is a separator, and backslashes are special. Thus you cannot simply pass a ``command_line`` containing canonical Windows paths, like "c:\program files\app\app.exe", as the backslashes will be eaten, and the space will act as a separator. You need to enclose such paths with single quotes, like "'c:\program files\app\app.exe' 'e:\folder\argument.txt'". :param command_line: a command line :return: :const:`True` on success, :const:`False` if an error was set .. function:: spawn_error_quark() -> int .. function:: spawn_exit_error_quark() -> int .. function:: spawn_sync(working_directory: str | None, argv: list[str], envp: list[str] | None, flags: ~gi.repository.GLib.SpawnFlags, child_setup: ~typing.Callable[[~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> ~typing.Tuple[bool, list[int], list[int], int] Executes a child synchronously (waits for the child to exit before returning). All output from the child is stored in ``standard_output`` and ``standard_error``\, if those parameters are non-:const:`None`. Note that you must set the :const:`~gi.repository.GLib.SpawnFlags.STDOUT_TO_DEV_NULL` and :const:`~gi.repository.GLib.SpawnFlags.STDERR_TO_DEV_NULL` flags when passing :const:`None` for ``standard_output`` and ``standard_error``\. If ``wait_status`` is non-:const:`None`, the platform-specific status of the child is stored there; see the documentation of :func:`~gi.repository.GLib.spawn_check_wait_status` for how to use and interpret this. On Unix platforms, note that it is usually not equal to the integer passed to ``exit()`` or returned from ``main()``\. Note that it is invalid to pass :const:`~gi.repository.GLib.SpawnFlags.DO_NOT_REAP_CHILD` in ``flags``\, and on POSIX platforms, the same restrictions as for :func:`~gi.repository.GLib.child_watch_source_new` apply. If an error occurs, no data is returned in ``standard_output``\, ``standard_error``\, or ``wait_status``\. This function calls :func:`~gi.repository.GLib.spawn_async_with_pipes` internally; see that function for full details on the other parameters and details on how these functions work on Windows. :param working_directory: child's current working directory, or :const:`None` to inherit parent's :param argv: child's argument vector, which must be non-empty and :const:`None`-terminated :param envp: child's environment, or :const:`None` to inherit parent's :param flags: flags from :obj:`~gi.repository.GLib.SpawnFlags` :param child_setup: function to run in the child just before ``exec()`` :param user_data: user data for ``child_setup`` :return: :const:`True` on success, :const:`False` if an error was set .. function:: stat(filename: str, buf: ~gi.repository.GLib.StatBuf) -> int A wrapper for the POSIX stat() function. The stat() function returns information about a file. On Windows the stat() function in the C library checks only the FAT-style READONLY attribute and does not look at the ACL at all. Thus on Windows the protection bits in the ``st_mode`` field are a fabrication of little use. On Windows the Microsoft C libraries have several variants of the stat struct and stat() function with names like _stat(), _stat32(), _stat32i64() and _stat64i32(). The one used here is for 32-bit code the one with 32-bit size and time fields, specifically called _stat32(). In Microsoft's compiler, by default struct stat means one with 64-bit time fields while in MinGW struct stat is the legacy one with 32-bit fields. To hopefully clear up this messs, the gstdio.h header defines a type :obj:`~gi.repository.GLib.StatBuf` which is the appropriate struct type depending on the platform and/or compiler being used. On POSIX it is just struct stat, but note that even on POSIX platforms, stat() might be a macro. See your C library manual for more details about stat(). .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param buf: a pointer to a stat struct, which will be filled with the file information :return: 0 if the information was successfully retrieved, -1 if an error occurred .. function:: stpcpy(dest: str, src: str) -> str Copies a nul-terminated string into the destination buffer, including the trailing nul byte, and returns a pointer to the trailing nul byte in ``dest``\. The return value is useful for concatenating multiple strings without having to repeatedly scan for the end. :param dest: destination buffer :param src: source string :return: a pointer to the trailing nul byte in ``dest`` .. function:: str_equal(v1: ~typing.Any, v2: ~typing.Any) -> bool Compares two strings for byte-by-byte equality and returns :const:`True` if they are equal. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``key_equal_func`` parameter, when using non-:const:`None` strings as keys in a :obj:`~gi.repository.GLib.HashTable`\. This function is typically used for hash table comparisons, but can be used for general purpose comparisons of non-:const:`None` strings. For a :const:`None`-safe string comparison function, see :func:`~gi.repository.GLib.strcmp0`. :param v1: a key :param v2: a key to compare with ``v1`` :return: :const:`True` if the two keys match .. function:: str_has_prefix(str: str, prefix: str) -> bool Looks whether the string ``str`` begins with ``prefix``\. .. versionadded:: 2.2 :param str: a string to look in :param prefix: the prefix to look for :return: true if ``str`` begins with ``prefix``\, false otherwise .. function:: str_has_suffix(str: str, suffix: str) -> bool Looks whether a string ends with ``suffix``\. .. versionadded:: 2.2 :param str: a string to look in :param suffix: the suffix to look for :return: true if ``str`` ends with ``suffix``\, false otherwise .. function:: str_hash(v: ~typing.Any) -> int Converts a string to a hash value. This function implements the widely used "djb" hash apparently posted by Daniel Bernstein to comp.lang.c some time ago. The 32 bit unsigned hash value starts at 5381 and for each byte 'c' in the string, is updated: ``hash = hash * 33 + c``\. This function uses the signed value of each byte. It can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``hash_func`` parameter, when using non-:const:`None` strings as keys in a :obj:`~gi.repository.GLib.HashTable`\. Note that this function may not be a perfect fit for all use cases. For example, it produces some hash collisions with strings as short as 2. :param v: a string key :return: a hash value corresponding to the key .. function:: str_is_ascii(str: str) -> bool Determines if a string is pure ASCII. A string is pure ASCII if it contains no bytes with the high bit set. .. versionadded:: 2.40 :param str: a string :return: true if ``str`` is ASCII .. function:: str_match_string(search_term: str, potential_hit: str, accept_alternates: bool) -> bool Checks if a search conducted for ``search_term`` should match ``potential_hit``\. This function calls :obj:`~gi.repository.GLib.str_tokenize_and_fold` on both ``search_term`` and ``potential_hit``\. ASCII alternates are never taken for ``search_term`` but will be taken for ``potential_hit`` according to the value of ``accept_alternates``\. A hit occurs when each folded token in ``search_term`` is a prefix of a folded token from ``potential_hit``\. Depending on how you're performing the search, it will typically be faster to call ``g_str_tokenize_and_fold()`` on each string in your corpus and build an index on the returned folded tokens, then call ``g_str_tokenize_and_fold()`` on the search term and perform lookups into that index. As some examples, searching for ‘fred’ would match the potential hit ‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix). .. versionadded:: 2.40 :param search_term: the search term from the user :param potential_hit: the text that may be a hit :param accept_alternates: if true, ASCII alternates are accepted :return: true if ``potential_hit`` is a hit .. function:: str_to_ascii(str: str, from_locale: str | None = None) -> str Transliterate ``str`` to plain ASCII. For best results, ``str`` should be in composed normalised form. This function performs a reasonably good set of character replacements. The particular set of replacements that is done may change by version or even by runtime environment. If the source language of ``str`` is known, it can used to improve the accuracy of the translation by passing it as ``from_locale``\. It should be a valid POSIX locale string (of the form ``language[_territory][.codeset][@modifier]``\). If ``from_locale`` is :const:`None` then the current locale is used. If you want to do translation for no specific locale, and you want it to be done independently of the currently locale, specify ``"C"`` for ``from_locale``\. .. versionadded:: 2.40 :param str: a string, in UTF-8 :param from_locale: the source locale, if known :return: a string in plain ASCII .. function:: str_tokenize_and_fold(string: str, translit_locale: str | None = None) -> ~typing.Tuple[list[str], list[str]] Tokenizes ``string`` and performs folding on each token. A token is a non-empty sequence of alphanumeric characters in the source string, separated by non-alphanumeric characters. An "alphanumeric" character for this purpose is one that matches :obj:`~gi.repository.GLib.unichar_isalnum` or :obj:`~gi.repository.GLib.unichar_ismark`\. Each token is then (Unicode) normalised and case-folded. If ``ascii_alternates`` is non-``NULL`` and some of the returned tokens contain non-ASCII characters, ASCII alternatives will be generated. The number of ASCII alternatives that are generated and the method for doing so is unspecified, but ``translit_locale`` (if specified) may improve the transliteration if the language of the source string is known. .. versionadded:: 2.40 :param string: a string to tokenize :param translit_locale: the language code (like 'de' or 'en_GB') from which ``string`` originates :return: the folded tokens .. function:: strcanon(string: str, valid_chars: str, substitutor: int) -> str For each character in ``string``\, if the character is not in ``valid_chars``\, replaces the character with ``substitutor``\. Modifies ``string`` in place, and return ``string`` itself, not a copy. The return value is to allow nesting such as: .. code-block:: C :dedent: g_ascii_strup (g_strcanon (str, "abc", '?')) In order to modify a copy, you may use :obj:`~gi.repository.GLib.strdup`\: .. code-block:: C :dedent: reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); … g_free (reformatted); :param string: a nul-terminated array of bytes :param valid_chars: bytes permitted in ``string`` :param substitutor: replacement character for disallowed bytes :return: the modified ``string`` .. function:: strcasecmp(s1: str, s2: str) -> int A case-insensitive string comparison, corresponding to the standard ``strcasecmp()`` function on platforms which support it. .. deprecated:: 2.2 See :obj:`~gi.repository.GLib.strncasecmp` for a discussion of why this function is deprecated and how to replace it. :param s1: string to compare with ``s2`` :param s2: string to compare with ``s1`` :return: 0 if the strings match, a negative value if ``s1`` < ``s2``\, or a positive value if ``s1`` > ``s2`` .. function:: strchomp(string: str) -> str Removes trailing whitespace from a string. This function doesn't allocate or reallocate any memory; it modifies ``string`` in place. Therefore, it cannot be used on statically allocated strings. The pointer to ``string`` is returned to allow the nesting of functions. Also see :obj:`~gi.repository.GLib.strchug` and :obj:`~gi.repository.GLib.strstrip`\. :param string: a string to remove the trailing whitespace from :return: the modified ``string`` .. function:: strchug(string: str) -> str Removes leading whitespace from a string, by moving the rest of the characters forward. This function doesn't allocate or reallocate any memory; it modifies ``string`` in place. Therefore, it cannot be used on statically allocated strings. The pointer to ``string`` is returned to allow the nesting of functions. Also see :obj:`~gi.repository.GLib.strchomp` and :obj:`~gi.repository.GLib.strstrip`\. :param string: a string to remove the leading whitespace from :return: the modified ``string`` .. function:: strcmp0(str1: str | None = None, str2: str | None = None) -> int Compares ``str1`` and ``str2`` like strcmp(). Handles :const:`None` gracefully by sorting it before non-:const:`None` strings. Comparing two :const:`None` pointers returns 0. .. versionadded:: 2.16 :param str1: a C string or :const:`None` :param str2: another C string or :const:`None` :return: an integer less than, equal to, or greater than zero, if ``str1`` is <, == or > than ``str2``\. .. function:: strcompress(source: str) -> str Makes a copy of a string replacing C string-style escape sequences with their one byte equivalent: - ``\b`` → `U+0008 Backspace `__ - ``\f`` → `U+000C Form Feed `__ - ``\n`` → `U+000A Line Feed `__ - ``\r`` → `U+000D Carriage Return `__ - ``\t`` → `U+0009 Horizontal Tabulation `__ - ``\v`` → `U+000B Vertical Tabulation `__ - ``\`` followed by one to three octal digits → the numeric value (mod 255) - ``\`` followed by any other character → the character as is. For example, ``\\`` will turn into a backslash (``\``\) and ``\"`` into a double quote (``"``\). :obj:`~gi.repository.GLib.strescape` does the reverse conversion. :param source: a string to compress :return: a newly-allocated copy of ``source`` with all escaped character compressed .. function:: strdelimit(string: str, delimiters: str | None, new_delimiter: int) -> str Converts any delimiter characters in ``string`` to ``new_delimiter``\. Any characters in ``string`` which are found in ``delimiters`` are changed to the ``new_delimiter`` character. Modifies ``string`` in place, and returns ``string`` itself, not a copy. The return value is to allow nesting such as: .. code-block:: C :dedent: g_ascii_strup (g_strdelimit (str, "abc", '?')) In order to modify a copy, you may use :obj:`~gi.repository.GLib.strdup`\: .. code-block:: C :dedent: reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); … g_free (reformatted); :param string: the string to convert :param delimiters: a string containing the current delimiters, or ``NULL`` to use the standard delimiters defined in :obj:`~gi.repository.GLib.STR_DELIMITERS` :param new_delimiter: the new delimiter character :return: the modified ``string`` .. function:: strdown(string: str) -> str Converts a string to lower case. .. deprecated:: 2.2 This function is totally broken for the reasons discussed in the :obj:`~gi.repository.GLib.strncasecmp` docs — use :obj:`~gi.repository.GLib.ascii_strdown` or :obj:`~gi.repository.GLib.utf8_strdown` instead. :param string: the string to convert :return: the string .. function:: strdup(str: str | None = None) -> str Duplicates a string. If ``str`` is ``NULL`` it returns ``NULL``\. :param str: the string to duplicate :return: a newly-allocated copy of ``str`` .. function:: strdupv(str_array: list[str] | None = None) -> list[str] | None Copies an array of strings. The copy is a deep copy; each string is also copied. If called on a ``NULL`` value, ``g_strdupv()`` simply returns ``NULL``\. :param str_array: an array of strings to copy :return: a newly-allocated array of strings. Use :obj:`~gi.repository.GLib.strfreev` to free it. .. function:: strerror(errnum: int) -> str Returns a string corresponding to the given error code, e.g. "no such process". Unlike ``strerror()``\, this always returns a string in UTF-8 encoding, and the pointer is guaranteed to remain valid for the lifetime of the process. If the error code is unknown, it returns a string like “Unknown error ”. Note that the string may be translated according to the current locale. The value of ``errno`` will not be changed by this function. However, it may be changed by intermediate function calls, so you should save its value as soon as the call returns: .. code-block:: C :dedent: int saved_errno; ret = read (blah); saved_errno = errno; g_strerror (saved_errno); :param errnum: the system error number. See the standard C ``errno`` documentation :return: the string describing the error code .. function:: strescape(source: str, exceptions: str | None = None) -> str It replaces the following special characters in the string ``source`` with their corresponding C escape sequence: Symbol | Escape ---|--- `U+0008 Backspace `__ | ``\b`` `U+000C Form Feed `__ | ``\f`` `U+000A Line Feed `__ | ``\n`` `U+000D Carriage Return `__ | ``\r`` `U+0009 Horizontal Tabulation `__ | ``\t`` `U+000B Vertical Tabulation `__ | ``\v`` It also inserts a backslash (``\``\) before any backslash or a double quote (``"``\). Additionally all characters in the range 0x01-0x1F (everything below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are replaced with a backslash followed by their octal representation. Characters supplied in ``exceptions`` are not escaped. :obj:`~gi.repository.GLib.strcompress` does the reverse conversion. :param source: a string to escape :param exceptions: a string of characters not to escape in ``source`` :return: a newly-allocated copy of ``source`` with special characters escaped .. function:: strfreev(str_array: list[str] | None = None) -> None Frees an array of strings, as well as each string it contains. If ``str_array`` is ``NULL``\, this function simply returns. :param str_array: an array of strings to free .. function:: strip_context(msgid: str, msgval: str) -> str An auxiliary function for gettext() support (see Q_()). .. versionadded:: 2.4 :param msgid: a string :param msgval: another string :return: ``msgval``\, unless ``msgval`` is identical to ``msgid`` and contains a '|' character, in which case a pointer to the substring of msgid after the first '|' character is returned. .. function:: strjoinv(separator: str | None, str_array: list[str]) -> str Joins an array of strings together to form one long string, with the optional ``separator`` inserted between each of them. If ``str_array`` has no items, the return value will be an empty string. If ``str_array`` contains a single item, ``separator`` will not appear in the resulting string. :param separator: a string to insert between each of the strings :param str_array: an array of strings to join :return: a newly-allocated string containing all of the strings joined together, with ``separator`` between them .. function:: strlcat(dest: str, src: str, dest_size: int) -> int Portability wrapper that calls ``strlcat()`` on systems which have it, and emulates it otherwise. Appends nul-terminated ``src`` string to ``dest``\, guaranteeing nul-termination for ``dest``\. The total size of ``dest`` won't exceed ``dest_size``\. At most ``dest_size`` - 1 characters will be copied. Unlike ``strncat()``\, ``dest_size`` is the full size of dest, not the space left over. This function does not allocate memory. It always nul-terminates (unless ``dest_size`` == 0 or there were no nul characters in the ``dest_size`` characters of dest to start with). Caveat: this is supposedly a more secure alternative to ``strcat()`` or ``strncat()``\, but for real security :obj:`~gi.repository.GLib.strconcat` is harder to mess up. :param dest: destination buffer, already containing one nul-terminated string :param src: source buffer :param dest_size: length of ``dest`` buffer in bytes (not length of existing string inside ``dest``\) :return: size of attempted result, which is ``MIN (dest_size, strlen (original dest)) + strlen (src)``\, so if ``retval`` >= ``dest_size``\, truncation occurred .. function:: strlcpy(dest: str, src: str, dest_size: int) -> int Portability wrapper that calls ``strlcpy()`` on systems which have it, and emulates ``strlcpy()`` otherwise. Copies ``src`` to ``dest``\; ``dest`` is guaranteed to be nul-terminated; ``src`` must be nul-terminated; ``dest_size`` is the buffer size, not the number of bytes to copy. At most ``dest_size`` - 1 characters will be copied. Always nul-terminates (unless ``dest_size`` is 0). This function does not allocate memory. Unlike ``strncpy()``\, this function doesn't pad ``dest`` (so it's often faster). It returns the size of the attempted result, ``strlen (src)``\, so if ``retval`` >= ``dest_size``\, truncation occurred. Caveat: ``strlcpy()`` is supposedly more secure than ``strcpy()`` or ``strncpy()``\, but if you really want to avoid screwups, :obj:`~gi.repository.GLib.strdup` is an even better idea. :param dest: destination buffer :param src: source buffer :param dest_size: length of ``dest`` in bytes :return: length of ``src`` .. function:: strncasecmp(s1: str, s2: str, n: int) -> int A case-insensitive string comparison, corresponding to the standard ``strncasecmp()`` function on platforms which support it. It is similar to :obj:`~gi.repository.GLib.strcasecmp` except it only compares the first ``n`` characters of the strings. .. deprecated:: 2.2 The problem with ``g_strncasecmp()`` is that it does the comparison by calling ``toupper()``\/``tolower()``\. These functions are locale-specific and operate on single bytes. However, it is impossible to handle things correctly from an internationalization standpoint by operating on bytes, since characters may be multibyte. Thus ``g_strncasecmp()`` is broken if your string is guaranteed to be ASCII, since it is locale-sensitive, and it's broken if your string is localized, since it doesn't work on many encodings at all, including UTF-8, EUC-JP, etc. There are therefore two replacement techniques: :obj:`~gi.repository.GLib.ascii_strncasecmp`\, which only works on ASCII and is not locale-sensitive, and :obj:`~gi.repository.GLib.utf8_casefold` followed by ``strcmp()`` on the resulting strings, which is good for case-insensitive sorting of UTF-8. :param s1: string to compare with ``s2`` :param s2: string to compare with ``s1`` :param n: the maximum number of characters to compare :return: 0 if the strings match, a negative value if ``s1`` < ``s2``\, or a positive value if ``s1`` > ``s2`` .. function:: strndup(str: str | None, n: int) -> str | None Duplicates the first ``n`` bytes of a string, returning a newly-allocated buffer ``n`` + 1 bytes long which will always be nul-terminated. If ``str`` is less than ``n`` bytes long the buffer is padded with nuls. If ``str`` is ``NULL`` it returns ``NULL``\. To copy a number of characters from a UTF-8 encoded string, use :obj:`~gi.repository.GLib.utf8_strncpy` instead. :param str: the string to duplicate :param n: the maximum number of bytes to copy from ``str`` :return: a newly-allocated buffer containing the first ``n`` bytes of ``str`` .. function:: strnfill(length: int, fill_char: int) -> str Creates a new string ``length`` bytes long filled with ``fill_char``\. :param length: the length of the new string :param fill_char: the byte to fill the string with :return: a newly-allocated string filled with ``fill_char`` .. function:: strreverse(string: str) -> str Reverses all of the bytes in a string. For example, ``g_strreverse ("abcdef")`` will result in "fedcba". Note that ``g_strreverse()`` doesn't work on UTF-8 strings containing multibyte characters. For that purpose, use :obj:`~gi.repository.GLib.utf8_strreverse`\. :param string: the string to reverse :return: the ``string``\, reversed in place .. function:: strrstr(haystack: str, needle: str) -> str | None Searches the string ``haystack`` for the last occurrence of the string ``needle``\. The fact that this function returns ``gchar *`` rather than ``const gchar *`` is a historical artifact. :param haystack: a string to search in :param needle: the string to search for :return: a pointer to the found occurrence, or ``NULL`` if not found .. function:: strrstr_len(haystack: str, haystack_len: int, needle: str) -> str | None Searches the string ``haystack`` for the last occurrence of the string ``needle``\, limiting the length of the search to ``haystack_len``\. The fact that this function returns ``gchar *`` rather than ``const gchar *`` is a historical artifact. :param haystack: a string to search in :param haystack_len: the maximum length of ``haystack`` in bytes. A length of ``-1`` can be used to mean "search the entire string", like :obj:`~gi.repository.GLib.strrstr` :param needle: the string to search for :return: a pointer to the found occurrence, or ``NULL`` if not found .. function:: strsignal(signum: int) -> str Returns a string describing the given signal, e.g. "Segmentation fault". If the signal is unknown, it returns “unknown signal ()”. You should use this function in preference to ``strsignal()``\, because it returns a string in UTF-8 encoding, and since not all platforms support the ``strsignal()`` function. :param signum: the signal number. See the ``signal`` documentation :return: the string describing the signal .. function:: strsplit(string: str, delimiter: str, max_tokens: int) -> list[str] Splits a string into a maximum of ``max_tokens`` pieces, using the given ``delimiter``\. If ``max_tokens`` is reached, the remainder of ``string`` is appended to the last token. As an example, the result of ``g_strsplit (":a:bc::d:", ":", -1)`` is an array containing the six strings "", "a", "bc", "", "d" and "". As a special case, the result of splitting the empty string "" is an empty array, not an array containing a single string. The reason for this special case is that being able to represent an empty array is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling ``g_strsplit()``\. :param string: a string to split :param delimiter: a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless ``max_tokens`` is reached. :param max_tokens: the maximum number of pieces to split ``string`` into If this is less than 1, the string is split completely :return: a newly-allocated array of strings, freed with :obj:`~gi.repository.GLib.strfreev` .. function:: strsplit_set(string: str, delimiters: str, max_tokens: int) -> list[str] Splits ``string`` into a number of tokens not containing any of the characters in ``delimiters``\. A token is the (possibly empty) longest string that does not contain any of the characters in ``delimiters``\. If ``max_tokens`` is reached, the remainder is appended to the last token. For example, the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is an array containing the three strings "abc", "def", and "ghi". The result of g_strsplit_set (":def/ghi:", ":/", -1) is an array containing the four strings "", "def", "ghi", and "". As a special case, the result of splitting the empty string "" is an empty array, not an array containing a single string. The reason for this special case is that being able to represent an empty array is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling ``g_strsplit_set()``\. Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. .. versionadded:: 2.4 :param string: a string to split :param delimiters: a string containing characters that are used to split the string. Can be empty, which will result in no string splitting :param max_tokens: the maximum number of tokens to split ``string`` into. If this is less than 1, the string is split completely :return: a newly-allocated array of strings. Use :obj:`~gi.repository.GLib.strfreev` to free it. .. function:: strstr_len(haystack: str, haystack_len: int, needle: str) -> str | None Searches the string ``haystack`` for the first occurrence of the string ``needle``\, limiting the length of the search to ``haystack_len`` or a nul terminator byte (whichever is reached first). A length of ``-1`` can be used to mean “search the entire string”, like ``strstr()``\. The fact that this function returns ``gchar *`` rather than ``const gchar *`` is a historical artifact. :param haystack: a string to search in :param haystack_len: the maximum length of ``haystack`` in bytes, or ``-1`` to search it entirely :param needle: the string to search for :return: a pointer to the found occurrence, or ``NULL`` if not found .. function:: strtod(nptr: str) -> ~typing.Tuple[float, str] Converts a string to a floating point value. It calls the standard ``strtod()`` function to handle the conversion, but if the string is not completely converted it attempts the conversion again with :obj:`~gi.repository.GLib.ascii_strtod`\, and returns the best match. This function should seldom be used. The normal situation when reading numbers not for human consumption is to use :obj:`~gi.repository.GLib.ascii_strtod`\. Only when you know that you must expect both locale formatted and C formatted numbers should you use this. Make sure that you don't pass strings such as comma separated lists of values, since the commas may be interpreted as a decimal point in some locales, causing unexpected results. :param nptr: the string to convert to a numeric value :return: the converted value .. function:: strup(string: str) -> str Converts a string to upper case. .. deprecated:: 2.2 This function is totally broken for the reasons discussed in the :obj:`~gi.repository.GLib.strncasecmp` docs — use :obj:`~gi.repository.GLib.ascii_strup` or :obj:`~gi.repository.GLib.utf8_strup` instead. :param string: the string to convert :return: the string .. function:: strv_contains(strv: list[str], str: str) -> bool Checks if an array of strings contains the string ``str`` according to :obj:`~gi.repository.GLib.str_equal`\. ``strv`` must not be ``NULL``\. .. versionadded:: 2.44 :param strv: an array of strings to search in :param str: the string to search for :return: true if ``str`` is an element of ``strv`` .. function:: strv_equal(strv1: list[str], strv2: list[str]) -> bool Checks if two arrays of strings contain exactly the same elements in exactly the same order. Elements are compared using :obj:`~gi.repository.GLib.str_equal`\. To match independently of order, sort the arrays first (using :obj:`~gi.repository.GLib.qsort_with_data` or similar). Elements are compared using :obj:`~gi.repository.GLib.str_equal`\. To match independently of order, sort the arrays first (using :obj:`~gi.repository.GLib.qsort_with_data` or similar). Two empty arrays are considered equal. Neither ``strv1`` nor ``strv2`` may be ``NULL``\. .. versionadded:: 2.60 :param strv1: an array of strings to compare to ``strv2`` :param strv2: an array of strings to compare to ``strv1`` :return: true if ``strv1`` and ``strv2`` are equal .. function:: strv_get_type() -> ~gobject.GType .. function:: strv_length(str_array: list[str]) -> int Returns the length of an array of strings. ``str_array`` must not be ``NULL``\. .. versionadded:: 2.6 :param str_array: an array of strings :return: length of ``str_array`` .. function:: test_add_data_func(testpath: str, test_data: ~typing.Any, test_func: ~typing.Callable[[~typing.Any], None]) -> None Create a new test case, similar to :func:`~gi.repository.GLib.test_create_case`. However the test is assumed to use no fixture, and test suites are automatically created on the fly and added to the root fixture, based on the slash-separated portions of ``testpath``\. The ``test_data`` argument will be passed as first argument to ``test_func``\. If ``testpath`` includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly required via the ``-p`` command-line option or :func:`~gi.repository.GLib.test_trap_subprocess`. No component of ``testpath`` may start with a dot (``.``\) if the :const:`~gi.repository.GLib.TEST_OPTION_ISOLATE_DIRS` option is being used; and it is recommended to do so even if it isn’t. .. versionadded:: 2.16 :param testpath: /-separated test case path name for the test. :param test_data: Test data argument for the test function. :param test_func: The test function to invoke for this test. .. function:: test_add_data_func_full(testpath: str, test_data: ~typing.Any, test_func: ~typing.Callable[[~typing.Any], None]) -> None Create a new test case, as with :func:`~gi.repository.GLib.test_add_data_func`, but freeing ``test_data`` after the test run is complete. .. versionadded:: 2.34 :param testpath: /-separated test case path name for the test. :param test_data: Test data argument for the test function. :param test_func: The test function to invoke for this test. .. function:: test_add_func(testpath: str, test_func: ~typing.Callable[[], None]) -> None Create a new test case, similar to :func:`~gi.repository.GLib.test_create_case`. However the test is assumed to use no fixture, and test suites are automatically created on the fly and added to the root fixture, based on the slash-separated portions of ``testpath``\. If ``testpath`` includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly required via the ``-p`` command-line option or :func:`~gi.repository.GLib.test_trap_subprocess`. No component of ``testpath`` may start with a dot (``.``\) if the :const:`~gi.repository.GLib.TEST_OPTION_ISOLATE_DIRS` option is being used; and it is recommended to do so even if it isn’t. .. versionadded:: 2.16 :param testpath: /-separated test case path name for the test. :param test_func: The test function to invoke for this test. .. function:: test_assert_expected_messages_internal(domain: str, file: str, line: int, func: str) -> None :param domain: :param file: :param line: :param func: .. function:: test_bug(bug_uri_snippet: str) -> None This function adds a message to test reports that associates a bug URI with a test case. Bug URIs are constructed from a base URI set with :func:`~gi.repository.GLib.test_bug_base` and ``bug_uri_snippet``\. If :func:`~gi.repository.GLib.test_bug_base` has not been called, it is assumed to be the empty string, so a full URI can be provided to :func:`~gi.repository.GLib.test_bug` instead. Since GLib 2.70, the base URI is not prepended to ``bug_uri_snippet`` if it is already a valid URI. .. versionadded:: 2.16 :param bug_uri_snippet: Bug specific bug tracker URI or URI portion. .. function:: test_bug_base(uri_pattern: str) -> None Specify the base URI for bug reports. The base URI is used to construct bug report messages for :func:`~gi.repository.GLib.test_message` when :func:`~gi.repository.GLib.test_bug` is called. Calling this function outside of a test case sets the default base URI for all test cases. Calling it from within a test case changes the base URI for the scope of the test case only. Bug URIs are constructed by appending a bug specific URI portion to ``uri_pattern``\, or by replacing the special string ``%s`` within ``uri_pattern`` if that is present. If :func:`~gi.repository.GLib.test_bug_base` is not called, bug URIs are formed solely from the value provided by :func:`~gi.repository.GLib.test_bug`. .. versionadded:: 2.16 :param uri_pattern: the base pattern for bug URIs .. function:: test_disable_crash_reporting() -> None Attempt to disable system crash reporting infrastructure. This function should be called before exercising code paths that are expected or intended to crash, to avoid wasting resources in system-wide crash collection infrastructure such as systemd-coredump or abrt. .. versionadded:: 2.78 .. function:: test_expect_message(log_domain: str | None, log_level: ~gi.repository.GLib.LogLevelFlags, pattern: str) -> None Indicates that a message with the given ``log_domain`` and ``log_level``\, with text matching ``pattern``\, is expected to be logged. When this message is logged, it will not be printed, and the test case will not abort. This API may only be used with the old logging API (:obj:`~gi.repository.GLib.log` without ``G_LOG_USE_STRUCTURED`` defined). It will not work with the structured logging API. See `Testing for Messages `__\. Use :obj:`~gi.repository.GLib.test_assert_expected_messages` to assert that all previously-expected messages have been seen and suppressed. You can call this multiple times in a row, if multiple messages are expected as a result of a single call. (The messages must appear in the same order as the calls to :obj:`~gi.repository.GLib.test_expect_message`\.) For example: .. code-block:: c :dedent: // g_main_context_push_thread_default() should fail if the // context is already owned by another thread. g_test_expect_message (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, "assertion*acquired_context*failed"); g_main_context_push_thread_default (bad_context); g_test_assert_expected_messages (); Note that you cannot use this to test :obj:`~gi.repository.GLib.error` messages, since :obj:`~gi.repository.GLib.error` intentionally never returns even if the program doesn’t abort; use :obj:`~gi.repository.GLib.test_trap_subprocess` in this case. If messages at :obj:`~gi.repository.GLib.LogLevelFlags.LEVEL_DEBUG` are emitted, but not explicitly expected via :obj:`~gi.repository.GLib.test_expect_message` then they will be ignored. .. versionadded:: 2.34 :param log_domain: the log domain of the message :param log_level: the log level of the message :param pattern: a glob-style pattern (see :obj:`~gi.repository.GLib.PatternSpec`\) .. function:: test_fail() -> None Indicates that a test failed. This function can be called multiple times from the same test. You can use this function if your test failed in a recoverable way. Do not use this function if the failure of a test could cause other tests to malfunction. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test. If not called from inside a test, this function does nothing. Note that unlike :func:`~gi.repository.GLib.test_skip` and :func:`~gi.repository.GLib.test_incomplete`, this function does not log a message alongside the test failure. If details of the test failure are available, either log them with :func:`~gi.repository.GLib.test_message` before :func:`~gi.repository.GLib.test_fail`, or use :func:`~gi.repository.GLib.test_fail_printf` instead. .. versionadded:: 2.30 .. function:: test_failed() -> bool Returns whether a test has already failed. This will be the case when :func:`~gi.repository.GLib.test_fail`, :func:`~gi.repository.GLib.test_incomplete` or :func:`~gi.repository.GLib.test_skip` have been called, but also if an assertion has failed. This can be useful to return early from a test if continuing after a failed assertion might be harmful. The return value of this function is only meaningful if it is called from inside a test function. .. versionadded:: 2.38 :return: :const:`True` if the test has failed .. function:: test_get_dir(file_type: ~gi.repository.GLib.TestFileType) -> str Gets the pathname of the directory containing test files of the type specified by ``file_type``\. This is approximately the same as calling g_test_build_filename("."), but you don't need to free the return value. .. versionadded:: 2.38 :param file_type: the type of file (built vs. distributed) :return: the path of the directory, owned by GLib .. function:: test_get_path() -> str Gets the test path for the test currently being run. In essence, it will be the same string passed as the first argument to e.g. :func:`~gi.repository.GLib.test_add` when the test was added. This function returns a valid string only within a test function. Note that this is a test path, not a file system path. .. versionadded:: 2.68 :return: the test path for the test currently being run .. function:: test_incomplete(msg: str | None = None) -> None Indicates that a test failed because of some incomplete functionality. This function can be called multiple times from the same test. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test. If not called from inside a test, this function does nothing. .. versionadded:: 2.38 :param msg: explanation .. function:: test_log_type_name(log_type: ~gi.repository.GLib.TestLogType) -> str :param log_type: .. function:: test_queue_destroy(destroy_func: ~typing.Callable[[~typing.Any], None], destroy_data: ~typing.Any = None) -> None Enqueues a callback ``destroy_func`` to be executed during the next test case teardown phase. This is most useful to auto destroy allocated test resources at the end of a test run. Resources are released in reverse queue order, that means enqueueing callback ``A`` before callback ``B`` will cause ``B()`` to be called before ``A()`` during teardown. .. versionadded:: 2.16 :param destroy_func: Destroy callback for teardown phase. :param destroy_data: Destroy callback data. .. function:: test_queue_free(gfree_pointer: ~typing.Any = None) -> None Enqueue a pointer to be released with :func:`~gi.repository.GLib.free` during the next teardown phase. This is equivalent to calling :func:`~gi.repository.GLib.test_queue_destroy` with a destroy callback of :func:`~gi.repository.GLib.free`. .. versionadded:: 2.16 :param gfree_pointer: the pointer to be stored. .. function:: test_rand_double() -> float Get a reproducible random floating point number, see :func:`~gi.repository.GLib.test_rand_int` for details on test case random numbers. .. versionadded:: 2.16 :return: a random number from the seeded random number generator. .. function:: test_rand_double_range(range_start: float, range_end: float) -> float Get a reproducible random floating pointer number out of a specified range, see :func:`~gi.repository.GLib.test_rand_int` for details on test case random numbers. .. versionadded:: 2.16 :param range_start: the minimum value returned by this function :param range_end: the minimum value not returned by this function :return: a number with ``range_start`` <= number < ``range_end``\. .. function:: test_rand_int() -> int Get a reproducible random integer number. The random numbers generated by the ``g_test_rand_*()`` family of functions change with every new test program start, unless the --seed option is given when starting test programs. For individual test cases however, the random number generator is reseeded, to avoid dependencies between tests and to make --seed effective for all test cases. .. versionadded:: 2.16 :return: a random number from the seeded random number generator. .. function:: test_rand_int_range(begin: int, end: int) -> int Get a reproducible random integer number out of a specified range, see :func:`~gi.repository.GLib.test_rand_int` for details on test case random numbers. .. versionadded:: 2.16 :param begin: the minimum value returned by this function :param end: the smallest value not to be returned by this function :return: a number with ``begin`` <= number < ``end``\. .. function:: test_run() -> int Runs all tests under the toplevel suite which can be retrieved with :func:`~gi.repository.GLib.test_get_root`. Similar to :func:`~gi.repository.GLib.test_run_suite`, the test cases to be run are filtered according to test path arguments (``-p testpath`` and ``-s testpath``\) as parsed by :func:`~gi.repository.GLib.test_init`. :func:`~gi.repository.GLib.test_run_suite` or :func:`~gi.repository.GLib.test_run` may only be called once in a program. In general, the tests and sub-suites within each suite are run in the order in which they are defined. However, note that prior to GLib 2.36, there was a bug in the ``g_test_add_*`` functions which caused them to create multiple suites with the same name, meaning that if you created tests "/foo/simple", "/bar/simple", and "/foo/using-bar" in that order, they would get run in that order (since :func:`~gi.repository.GLib.test_run` would run the first "/foo" suite, then the "/bar" suite, then the second "/foo" suite). As of 2.36, this bug is fixed, and adding the tests in that order would result in a running order of "/foo/simple", "/foo/using-bar", "/bar/simple". If this new ordering is sub-optimal (because it puts more-complicated tests before simpler ones, making it harder to figure out exactly what has failed), you can fix it by changing the test paths to group tests by suite in a way that will result in the desired running order. Eg, "/simple/foo", "/simple/bar", "/complex/foo-using-bar". However, you should never make the actual result of a test depend on the order that tests are run in. If you need to ensure that some particular code runs before or after a given test case, use :func:`~gi.repository.GLib.test_add`, which lets you specify setup and teardown functions. If all tests are skipped or marked as incomplete (expected failures), this function will return 0 if producing TAP output, or 77 (treated as "skip test" by Automake) otherwise. .. versionadded:: 2.16 :return: 0 on success, 1 on failure (assuming it returns at all), 0 or 77 if all tests were skipped with :func:`~gi.repository.GLib.test_skip` and/or :func:`~gi.repository.GLib.test_incomplete` .. function:: test_run_suite(suite: ~gi.repository.GLib.TestSuite) -> int Execute the tests within ``suite`` and all nested :obj:`~gi.repository.GLib.TestSuite`\. The test suites to be executed are filtered according to test path arguments (``-p testpath`` and ``-s testpath``\) as parsed by :func:`~gi.repository.GLib.test_init`. See the :func:`~gi.repository.GLib.test_run` documentation for more information on the order that tests are run in. :func:`~gi.repository.GLib.test_run_suite` or :func:`~gi.repository.GLib.test_run` may only be called once in a program. .. versionadded:: 2.16 :param suite: a :obj:`~gi.repository.GLib.TestSuite` :return: 0 on success .. function:: test_set_nonfatal_assertions() -> None Changes the behaviour of the various ``g_assert_*()`` macros, :func:`~gi.repository.GLib.test_assert_expected_messages` and the various ``g_test_trap_assert_*()`` macros to not abort to program, but instead call :func:`~gi.repository.GLib.test_fail` and continue. (This also changes the behavior of :func:`~gi.repository.GLib.test_fail` so that it will not cause the test program to abort after completing the failed test.) Note that the :func:`~gi.repository.GLib.assert_not_reached` and :func:`~gi.repository.GLib.assert` macros are not affected by this. This function can only be called after :func:`~gi.repository.GLib.test_init`. .. versionadded:: 2.38 .. function:: test_skip(msg: str | None = None) -> None Indicates that a test was skipped. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test. If not called from inside a test, this function does nothing. .. versionadded:: 2.38 :param msg: explanation .. function:: test_subprocess() -> bool Returns :const:`True` (after :func:`~gi.repository.GLib.test_init` has been called) if the test program is running under :func:`~gi.repository.GLib.test_trap_subprocess`. .. versionadded:: 2.38 :return: :const:`True` if the test program is running under :func:`~gi.repository.GLib.test_trap_subprocess`. .. function:: test_summary(summary: str) -> None Set the summary for a test, which describes what the test checks, and how it goes about checking it. This may be included in test report output, and is useful documentation for anyone reading the source code or modifying a test in future. It must be a single line. This should be called at the top of a test function. For example: .. code-block:: C :dedent: static void test_array_sort (void) { g_test_summary ("Test my_array_sort() sorts the array correctly and stably, " "including testing zero length and one-element arrays."); … } .. versionadded:: 2.62 :param summary: One or two sentences summarising what the test checks, and how it checks it. .. function:: test_timer_elapsed() -> float Get the number of seconds since the last start of the timer with :func:`~gi.repository.GLib.test_timer_start`. .. versionadded:: 2.16 :return: the time since the last start of the timer in seconds, as a double .. function:: test_timer_last() -> float Report the last result of :func:`~gi.repository.GLib.test_timer_elapsed`. .. versionadded:: 2.16 :return: the last result of :func:`~gi.repository.GLib.test_timer_elapsed`, as a double .. function:: test_timer_start() -> None Start a timing test. Call :func:`~gi.repository.GLib.test_timer_elapsed` when the task is supposed to be done. Call this function again to restart the timer. .. versionadded:: 2.16 .. function:: test_trap_assertions(domain: str, file: str, line: int, func: str, assertion_flags: int, pattern: str) -> None :param domain: :param file: :param line: :param func: :param assertion_flags: :param pattern: .. function:: test_trap_fork(usec_timeout: int, test_trap_flags: ~gi.repository.GLib.TestTrapFlags) -> bool Fork the current test program to execute a test case that might not return or that might abort. If ``usec_timeout`` is non-0, the forked test case is aborted and considered failing if its run time exceeds it. The forking behavior can be configured with the :obj:`~gi.repository.GLib.TestTrapFlags` flags. In the following example, the test code forks, the forked child process produces some sample output and exits successfully. The forking parent process then asserts successful child program termination and validates child program outputs. .. code-block:: C :dedent: static void test_fork_patterns (void) { if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) { g_print ("some stdout text: somagic17\n"); g_printerr ("some stderr text: semagic43\n"); exit (0); // successful test run } g_test_trap_assert_passed (); g_test_trap_assert_stdout ("*somagic17*"); g_test_trap_assert_stderr ("*semagic43*"); } .. versionadded:: 2.16 .. deprecated:: Unknown This function is implemented only on Unix platforms, is not always reliable due to problems inherent in fork-without-exec and doesn't set close-on-exec flag on its file descriptors. Use :func:`~gi.repository.GLib.test_trap_subprocess` instead. :param usec_timeout: Timeout for the forked test in micro seconds. :param test_trap_flags: Flags to modify forking behaviour. :return: :const:`True` for the forked child and :const:`False` for the executing parent process. .. function:: test_trap_has_passed() -> bool Check the result of the last :func:`~gi.repository.GLib.test_trap_subprocess` call. .. versionadded:: 2.16 :return: :const:`True` if the last test subprocess terminated successfully. .. function:: test_trap_reached_timeout() -> bool Check the result of the last :func:`~gi.repository.GLib.test_trap_subprocess` call. .. versionadded:: 2.16 :return: :const:`True` if the last test subprocess got killed due to a timeout. .. function:: test_trap_subprocess(test_path: str | None, usec_timeout: int, test_flags: ~gi.repository.GLib.TestSubprocessFlags) -> None Respawns the test program to run only ``test_path`` in a subprocess. This is equivalent to calling :func:`~gi.repository.GLib.test_trap_subprocess_with_envp` with ``envp`` set to :const:`None`. See the documentation for that function for full details. .. versionadded:: 2.38 :param test_path: Test to run in a subprocess :param usec_timeout: Timeout for the subprocess test in micro seconds. :param test_flags: Flags to modify subprocess behaviour. .. function:: test_trap_subprocess_with_envp(test_path: str | None, envp: list[str] | None, usec_timeout: int, test_flags: ~gi.repository.GLib.TestSubprocessFlags) -> None Respawns the test program to run only ``test_path`` in a subprocess with the given ``envp`` environment. This can be used for a test case that might not return, or that might abort. If ``test_path`` is :const:`None` then the same test is re-run in a subprocess. You can use :func:`~gi.repository.GLib.test_subprocess` to determine whether the test is in a subprocess or not. ``test_path`` can also be the name of the parent test, followed by "``/subprocess/``\" and then a name for the specific subtest (or just ending with "``/subprocess``\" if the test only has one child test); tests with names of this form will automatically be skipped in the parent process. If ``envp`` is :const:`None`, the parent process’ environment will be inherited. If ``usec_timeout`` is non-0, the test subprocess is aborted and considered failing if its run time exceeds it. The subprocess behavior can be configured with the :obj:`~gi.repository.GLib.TestSubprocessFlags` flags. You can use methods such as :func:`~gi.repository.GLib.test_trap_assert_passed`, :func:`~gi.repository.GLib.test_trap_assert_failed`, and :func:`~gi.repository.GLib.test_trap_assert_stderr` to check the results of the subprocess. (But note that :func:`~gi.repository.GLib.test_trap_assert_stdout` and :func:`~gi.repository.GLib.test_trap_assert_stderr` cannot be used if ``test_flags`` specifies that the child should inherit the parent stdout/stderr.) If your ``main ()`` needs to behave differently in the subprocess, you can call :func:`~gi.repository.GLib.test_subprocess` (after calling :func:`~gi.repository.GLib.test_init`) to see whether you are in a subprocess. Internally, this function tracks the child process using :func:`~gi.repository.GLib.child_watch_source_new`, so your process must not ignore ``SIGCHLD``\, and must not attempt to watch or wait for the child process via another mechanism. The following example tests that calling ``my_object_new(1000000)`` will abort with an error message. .. code-block:: C :dedent: static void test_create_large_object (void) { if (g_test_subprocess ()) { my_object_new (1000000); return; } // Reruns this same test in a subprocess g_test_trap_subprocess (NULL, 0, G_TEST_SUBPROCESS_DEFAULT); g_test_trap_assert_failed (); g_test_trap_assert_stderr ("*ERROR*too large*"); } static void test_different_username (void) { if (g_test_subprocess ()) { // Code under test goes here g_message ("Username is now simulated as %s", g_getenv ("USER")); return; } // Reruns this same test in a subprocess g_autoptr(GStrv) envp = g_get_environ (); envp = g_environ_setenv (g_steal_pointer (&envp), "USER", "charlie", TRUE); g_test_trap_subprocess_with_envp (NULL, envp, 0, G_TEST_SUBPROCESS_DEFAULT); g_test_trap_assert_passed (); g_test_trap_assert_stdout ("Username is now simulated as charlie"); } int main (int argc, char **argv) { g_test_init (&argc, &argv, NULL); g_test_add_func ("/myobject/create-large-object", test_create_large_object); g_test_add_func ("/myobject/different-username", test_different_username); return g_test_run (); } .. versionadded:: 2.80 :param test_path: Test to run in a subprocess :param envp: Environment to run the test in, or :const:`None` to inherit the parent’s environment. This must be in the GLib filename encoding. :param usec_timeout: Timeout for the subprocess test in micro seconds. :param test_flags: Flags to modify subprocess behaviour. .. function:: thread_error_quark() -> int .. function:: thread_exit(retval: ~typing.Any = None) -> None :param retval: .. function:: thread_pool_get_max_idle_time() -> int .. function:: thread_pool_get_max_unused_threads() -> int .. function:: thread_pool_get_num_unused_threads() -> int .. function:: thread_pool_set_max_idle_time(interval: int) -> None :param interval: .. function:: thread_pool_set_max_unused_threads(max_threads: int) -> None :param max_threads: .. function:: thread_pool_stop_unused_threads() -> None .. function:: thread_self() -> ~gi.repository.GLib.Thread .. function:: thread_yield() -> None .. function:: threads_init() .. function:: time_val_from_iso8601(iso_date: str) -> ~typing.Tuple[bool, ~gi.repository.GLib.TimeVal] :param iso_date: .. function:: timeout_add(interval, function, *user_data, priority=0) Sets a function to be called at regular intervals, with the default priority, :obj:`~gi.repository.GLib.PRIORITY_DEFAULT`\. The given ``function`` is called repeatedly until it returns :obj:`~gi.repository.GLib.SOURCE_REMOVE` or :const:`False`, at which point the timeout is automatically destroyed and the function will not be called again. The first call to the function will be at the end of the first ``interval``\. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays). See `mainloop memory management `__ for details on how to handle the return value and memory management of ``data``\. If you want to have a timer in the "seconds" range and do not care about the exact time of the first call of the timer, use the :obj:`~gi.repository.GLib.timeout_add_seconds` function; this function allows for more optimizations and more efficient system power usage. This internally creates a main loop source using :obj:`~gi.repository.GLib.timeout_source_new` and attaches it to the global :obj:`~gi.repository.GLib.MainContext` using :obj:`~gi.repository.GLib.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. It is safe to call this function from any thread. The interval given is in terms of monotonic time, not wall clock time. See :obj:`~gi.repository.GLib.get_monotonic_time`\. :param interval: the time between calls to the function, in milliseconds (1/1000ths of a second) :param function: function to call :param user_data: :param priority: :return: the ID (greater than 0) of the event source. .. function:: timeout_add_seconds(interval, function, *user_data, priority=0) Sets a function to be called at regular intervals with the default priority, :obj:`~gi.repository.GLib.PRIORITY_DEFAULT`\. The function is called repeatedly until it returns :obj:`~gi.repository.GLib.SOURCE_REMOVE` or :const:`False`, at which point the timeout is automatically destroyed and the function will not be called again. This internally creates a main loop source using :obj:`~gi.repository.GLib.timeout_source_new_seconds` and attaches it to the main loop context using :obj:`~gi.repository.GLib.Source.attach`\. You can do these steps manually if you need greater control. Also see :obj:`~gi.repository.GLib.timeout_add_seconds_full`\. It is safe to call this function from any thread. Note that the first call of the timer may not be precise for timeouts of one second. If you need finer precision and have such a timeout, you may want to use :obj:`~gi.repository.GLib.timeout_add` instead. See `mainloop memory management `__ for details on how to handle the return value and memory management of ``data``\. The interval given is in terms of monotonic time, not wall clock time. See :obj:`~gi.repository.GLib.get_monotonic_time`\. .. versionadded:: 2.14 :param interval: the time between calls to the function, in seconds :param function: function to call :param user_data: :param priority: :return: the ID (greater than 0) of the event source. .. function:: timeout_source_new(interval: int) -> ~gi.repository.GLib.Source Creates a new timeout source. The source will not initially be associated with any :obj:`~gi.repository.GLib.MainContext` and must be added to one with :obj:`~gi.repository.GLib.Source.attach` before it will be executed. The interval given is in terms of monotonic time, not wall clock time. See :obj:`~gi.repository.GLib.get_monotonic_time`\. :param interval: the timeout interval in milliseconds. :return: the newly-created timeout source .. function:: timeout_source_new_seconds(interval: int) -> ~gi.repository.GLib.Source Creates a new timeout source. The source will not initially be associated with any :obj:`~gi.repository.GLib.MainContext` and must be added to one with :obj:`~gi.repository.GLib.Source.attach` before it will be executed. The scheduling granularity/accuracy of this timeout source will be in seconds. The interval given is in terms of monotonic time, not wall clock time. See :obj:`~gi.repository.GLib.get_monotonic_time`\. .. versionadded:: 2.14 :param interval: the timeout interval in seconds :return: the newly-created timeout source .. function:: trash_stack_height(stack_p: ~gi.repository.GLib.TrashStack) -> int :param stack_p: .. function:: trash_stack_peek(stack_p: ~gi.repository.GLib.TrashStack) -> ~typing.Any | None :param stack_p: .. function:: trash_stack_pop(stack_p: ~gi.repository.GLib.TrashStack) -> ~typing.Any | None :param stack_p: .. function:: trash_stack_push(stack_p: ~gi.repository.GLib.TrashStack, data_p: ~typing.Any) -> None :param stack_p: :param data_p: .. function:: try_malloc(n_bytes: int) -> ~typing.Any | None Attempts to allocate ``n_bytes``\, and returns :const:`None` on failure. Contrast with :func:`~gi.repository.GLib.malloc`, which aborts the program on failure. :param n_bytes: number of bytes to allocate. :return: the allocated memory, or :const:`None`. .. function:: try_malloc0(n_bytes: int) -> ~typing.Any | None Attempts to allocate ``n_bytes``\, initialized to 0's, and returns :const:`None` on failure. Contrast with :func:`~gi.repository.GLib.malloc0`, which aborts the program on failure. .. versionadded:: 2.8 :param n_bytes: number of bytes to allocate :return: the allocated memory, or :const:`None` .. function:: try_malloc0_n(n_blocks: int, n_block_bytes: int) -> ~typing.Any | None This function is similar to :func:`~gi.repository.GLib.try_malloc0`, allocating (``n_blocks`` \* ``n_block_bytes``\) bytes, but care is taken to detect possible overflow during multiplication. .. versionadded:: 2.24 :param n_blocks: the number of blocks to allocate :param n_block_bytes: the size of each block in bytes :return: the allocated memory, or :const:`None` .. function:: try_malloc_n(n_blocks: int, n_block_bytes: int) -> ~typing.Any | None This function is similar to :func:`~gi.repository.GLib.try_malloc`, allocating (``n_blocks`` \* ``n_block_bytes``\) bytes, but care is taken to detect possible overflow during multiplication. .. versionadded:: 2.24 :param n_blocks: the number of blocks to allocate :param n_block_bytes: the size of each block in bytes :return: the allocated memory, or :const:`None`. .. function:: try_realloc(mem: ~typing.Any, n_bytes: int) -> ~typing.Any | None Attempts to realloc ``mem`` to a new size, ``n_bytes``\, and returns :const:`None` on failure. Contrast with :func:`~gi.repository.GLib.realloc`, which aborts the program on failure. If ``mem`` is :const:`None`, behaves the same as :func:`~gi.repository.GLib.try_malloc`. :param mem: previously-allocated memory, or :const:`None`. :param n_bytes: number of bytes to allocate. :return: the allocated memory, or :const:`None`. .. function:: try_realloc_n(mem: ~typing.Any, n_blocks: int, n_block_bytes: int) -> ~typing.Any | None This function is similar to :func:`~gi.repository.GLib.try_realloc`, allocating (``n_blocks`` \* ``n_block_bytes``\) bytes, but care is taken to detect possible overflow during multiplication. .. versionadded:: 2.24 :param mem: previously-allocated memory, or :const:`None`. :param n_blocks: the number of blocks to allocate :param n_block_bytes: the size of each block in bytes :return: the allocated memory, or :const:`None`. .. function:: ucs4_to_utf16(str: list[str]) -> ~typing.Tuple[int, int, int] Convert a string from UCS-4 to UTF-16. A 0 character will be added to the result after the converted text. :param str: a UCS-4 encoded string :return: a pointer to a newly allocated UTF-16 string. This value must be freed with :func:`~gi.repository.GLib.free`. If an error occurs, :const:`None` will be returned and ``error`` set. .. function:: ucs4_to_utf8(str: list[str]) -> ~typing.Tuple[str, int, int] Convert a string from a 32-bit fixed width representation as UCS-4. to UTF-8. The result will be terminated with a 0 byte. :param str: a UCS-4 encoded string :return: a pointer to a newly allocated UTF-8 string. This value must be freed with :func:`~gi.repository.GLib.free`. If an error occurs, :const:`None` will be returned and ``error`` set. In that case, ``items_read`` will be set to the position of the first invalid input character. .. function:: unichar_break_type(c: str) -> ~gi.repository.GLib.UnicodeBreakType Determines the break type of ``c``\. ``c`` should be a Unicode character (to derive a character from UTF-8 encoded text, use :func:`~gi.repository.GLib.utf8_get_char`). The break type is used to find word and line breaks ("text boundaries"), Pango implements the Unicode boundary resolution algorithms and normally you would use a function such as pango_break() instead of caring about break types yourself. :param c: a Unicode character :return: the break type of ``c`` .. function:: unichar_combining_class(uc: str) -> int Determines the canonical combining class of a Unicode character. .. versionadded:: 2.14 :param uc: a Unicode character :return: the combining class of the character .. function:: unichar_compose(a: str, b: str) -> ~typing.Tuple[bool, str] Performs a single composition step of the Unicode canonical composition algorithm. This function includes algorithmic Hangul Jamo composition, but it is not exactly the inverse of :func:`~gi.repository.GLib.unichar_decompose`. No composition can have either of ``a`` or ``b`` equal to zero. To be precise, this function composes if and only if there exists a Primary Composite P which is canonically equivalent to the sequence `amp#64;amp#97;amp#44;amp#64;amp#98; <amp#109;amp#97;amp#105;amp#108;amp#116;amp#111;amp#58;amp#64;amp#97;amp#44;amp#64;amp#98;>`__\. See the Unicode Standard for the definition of Primary Composite. If ``a`` and ``b`` do not compose a new character, ``ch`` is set to zero. See `UAX `__ for details. .. versionadded:: 2.30 :param a: a Unicode character :param b: a Unicode character :return: :const:`True` if the characters could be composed .. function:: unichar_decompose(ch: str) -> ~typing.Tuple[bool, str, str] Performs a single decomposition step of the Unicode canonical decomposition algorithm. This function does not include compatibility decompositions. It does, however, include algorithmic Hangul Jamo decomposition, as well as 'singleton' decompositions which replace a character by a single other character. In the case of singletons ``b`` will be set to zero. If ``ch`` is not decomposable, ``a`` is set to ``ch`` and ``b`` is set to zero. Note that the way Unicode decomposition pairs are defined, it is guaranteed that ``b`` would not decompose further, but ``a`` may itself decompose. To get the full canonical decomposition for ``ch``\, one would need to recursively call this function on ``a``\. Or use :func:`~gi.repository.GLib.unichar_fully_decompose`. See `UAX `__ for details. .. versionadded:: 2.30 :param ch: a Unicode character :return: :const:`True` if the character could be decomposed .. function:: unichar_digit_value(c: str) -> int Determines the numeric value of a character as a decimal digit. :param c: a Unicode character :return: If ``c`` is a decimal digit (according to :func:`~gi.repository.GLib.unichar_isdigit`), its numeric value. Otherwise, -1. .. function:: unichar_fully_decompose(ch: str, compat: bool, result_len: int) -> ~typing.Tuple[int, str] Computes the canonical or compatibility decomposition of a Unicode character. For compatibility decomposition, pass :const:`True` for ``compat``\; for canonical decomposition pass :const:`False` for ``compat``\. The decomposed sequence is placed in ``result``\. Only up to ``result_len`` characters are written into ``result``\. The length of the full decomposition (irrespective of ``result_len``\) is returned by the function. For canonical decomposition, currently all decompositions are of length at most 4, but this may change in the future (very unlikely though). At any rate, Unicode does guarantee that a buffer of length 18 is always enough for both compatibility and canonical decompositions, so that is the size recommended. This is provided as :const:`~gi.repository.GLib.UNICHAR_MAX_DECOMPOSITION_LENGTH`. See `UAX `__ for details. .. versionadded:: 2.30 :param ch: a Unicode character. :param compat: whether perform canonical or compatibility decomposition :param result_len: length of ``result`` :return: the length of the full decomposition. .. function:: unichar_get_mirror_char(ch: str) -> ~typing.Tuple[bool, str] In Unicode, some characters are "mirrored". This means that their images are mirrored horizontally in text that is laid out from right to left. For instance, "(" would become its mirror image, ")", in right-to-left text. If ``ch`` has the Unicode mirrored property and there is another unicode character that typically has a glyph that is the mirror image of ``ch``\'s glyph and ``mirrored_ch`` is set, it puts that character in the address pointed to by ``mirrored_ch``\. Otherwise the original character is put. .. versionadded:: 2.4 :param ch: a Unicode character :return: :const:`True` if ``ch`` has a mirrored character, :const:`False` otherwise .. function:: unichar_get_script(ch: str) -> ~gi.repository.GLib.UnicodeScript Looks up the :obj:`~gi.repository.GLib.UnicodeScript` for a particular character (as defined by Unicode Standard Annex #24). No check is made for ``ch`` being a valid Unicode character; if you pass in invalid character, the result is undefined. This function is equivalent to pango_script_for_unichar() and the two are interchangeable. .. versionadded:: 2.14 :param ch: a Unicode character :return: the :obj:`~gi.repository.GLib.UnicodeScript` for the character. .. function:: unichar_isalnum(c: str) -> bool Determines whether a character is alphanumeric. Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. :param c: a Unicode character :return: :const:`True` if ``c`` is an alphanumeric character .. function:: unichar_isalpha(c: str) -> bool Determines whether a character is alphabetic (i.e. a letter). Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. :param c: a Unicode character :return: :const:`True` if ``c`` is an alphabetic character .. function:: unichar_iscntrl(c: str) -> bool Determines whether a character is a control character. Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. :param c: a Unicode character :return: :const:`True` if ``c`` is a control character .. function:: unichar_isdefined(c: str) -> bool Determines if a given character is assigned in the Unicode standard. :param c: a Unicode character :return: :const:`True` if the character has an assigned value .. function:: unichar_isdigit(c: str) -> bool Determines whether a character is numeric (i.e. a digit). This covers ASCII 0-9 and also digits in other languages/scripts. Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. :param c: a Unicode character :return: :const:`True` if ``c`` is a digit .. function:: unichar_isgraph(c: str) -> bool Determines whether a character is printable and not a space (returns :const:`False` for control characters, format characters, and spaces). :func:`~gi.repository.GLib.unichar_isprint` is similar, but returns :const:`True` for spaces. Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. :param c: a Unicode character :return: :const:`True` if ``c`` is printable unless it's a space .. function:: unichar_islower(c: str) -> bool Determines whether a character is a lowercase letter. Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. :param c: a Unicode character :return: :const:`True` if ``c`` is a lowercase letter .. function:: unichar_ismark(c: str) -> bool Determines whether a character is a mark (non-spacing mark, combining mark, or enclosing mark in Unicode speak). Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. Note: in most cases where isalpha characters are allowed, ismark characters should be allowed to as they are essential for writing most European languages as well as many non-Latin scripts. .. versionadded:: 2.14 :param c: a Unicode character :return: :const:`True` if ``c`` is a mark character .. function:: unichar_isprint(c: str) -> bool Determines whether a character is printable. Unlike :func:`~gi.repository.GLib.unichar_isgraph`, returns :const:`True` for spaces. Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. :param c: a Unicode character :return: :const:`True` if ``c`` is printable .. function:: unichar_ispunct(c: str) -> bool Determines whether a character is punctuation or a symbol. Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. :param c: a Unicode character :return: :const:`True` if ``c`` is a punctuation or symbol character .. function:: unichar_isspace(c: str) -> bool Determines whether a character is a space, tab, or line separator (newline, carriage return, etc.). Given some UTF-8 text, obtain a character value with :func:`~gi.repository.GLib.utf8_get_char`. (Note: don't use this to do word breaking; you have to use Pango or equivalent to get word breaking right, the algorithm is fairly complex.) :param c: a Unicode character :return: :const:`True` if ``c`` is a space character .. function:: unichar_istitle(c: str) -> bool Determines if a character is titlecase. Some characters in Unicode which are composites, such as the DZ digraph have three case variants instead of just two. The titlecase form is used at the beginning of a word where only the first letter is capitalized. The titlecase form of the DZ digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z. :param c: a Unicode character :return: :const:`True` if the character is titlecase .. function:: unichar_isupper(c: str) -> bool Determines if a character is uppercase. :param c: a Unicode character :return: :const:`True` if ``c`` is an uppercase character .. function:: unichar_iswide(c: str) -> bool Determines if a character is typically rendered in a double-width cell. :param c: a Unicode character :return: :const:`True` if the character is wide .. function:: unichar_iswide_cjk(c: str) -> bool Determines if a character is typically rendered in a double-width cell under legacy East Asian locales. If a character is wide according to :func:`~gi.repository.GLib.unichar_iswide`, then it is also reported wide with this function, but the converse is not necessarily true. See the `Unicode Standard Annex `__ for details. If a character passes the :func:`~gi.repository.GLib.unichar_iswide` test then it will also pass this test, but not the other way around. Note that some characters may pass both this test and :func:`~gi.repository.GLib.unichar_iszerowidth`. .. versionadded:: 2.12 :param c: a Unicode character :return: :const:`True` if the character is wide in legacy East Asian locales .. function:: unichar_isxdigit(c: str) -> bool Determines if a character is a hexadecimal digit. :param c: a Unicode character. :return: :const:`True` if the character is a hexadecimal digit .. function:: unichar_iszerowidth(c: str) -> bool Determines if a given character typically takes zero width when rendered. The return value is :const:`True` for all non-spacing and enclosing marks (e.g., combining accents), format characters, zero-width space, but not U+00AD SOFT HYPHEN. A typical use of this function is with one of :func:`~gi.repository.GLib.unichar_iswide` or :func:`~gi.repository.GLib.unichar_iswide_cjk` to determine the number of cells a string occupies when displayed on a grid display (terminals). However, note that not all terminals support zero-width rendering of zero-width marks. .. versionadded:: 2.14 :param c: a Unicode character :return: :const:`True` if the character has zero width .. function:: unichar_to_utf8(c: str) -> ~typing.Tuple[int, str] Converts a single character to UTF-8. :param c: a Unicode character code :return: number of bytes written .. function:: unichar_tolower(c: str) -> str Converts a character to lower case. :param c: a Unicode character. :return: the result of converting ``c`` to lower case. If ``c`` is not an upperlower or titlecase character, or has no lowercase equivalent ``c`` is returned unchanged. .. function:: unichar_totitle(c: str) -> str Converts a character to the titlecase. :param c: a Unicode character :return: the result of converting ``c`` to titlecase. If ``c`` is not an uppercase or lowercase character, ``c`` is returned unchanged. .. function:: unichar_toupper(c: str) -> str Converts a character to uppercase. :param c: a Unicode character :return: the result of converting ``c`` to uppercase. If ``c`` is not a lowercase or titlecase character, or has no upper case equivalent ``c`` is returned unchanged. .. function:: unichar_type(c: str) -> ~gi.repository.GLib.UnicodeType Classifies a Unicode character by type. :param c: a Unicode character :return: the type of the character. .. function:: unichar_validate(ch: str) -> bool Checks whether ``ch`` is a valid Unicode character. Some possible integer values of ``ch`` will not be valid. 0 is considered a valid character, though it's normally a string terminator. :param ch: a Unicode character :return: :const:`True` if ``ch`` is a valid Unicode character .. function:: unichar_xdigit_value(c: str) -> int Determines the numeric value of a character as a hexadecimal digit. :param c: a Unicode character :return: If ``c`` is a hex digit (according to :func:`~gi.repository.GLib.unichar_isxdigit`), its numeric value. Otherwise, -1. .. function:: unicode_canonical_decomposition(ch: str, result_len: int) -> str Computes the canonical decomposition of a Unicode character. .. deprecated:: 2.30 Use the more flexible :func:`~gi.repository.GLib.unichar_fully_decompose` instead. :param ch: a Unicode character. :param result_len: location to store the length of the return value. :return: a newly allocated string of Unicode characters. ``result_len`` is set to the resulting length of the string. .. function:: unicode_canonical_ordering(string: list[str]) -> None Computes the canonical ordering of a string in-place. This rearranges decomposed characters in the string according to their combining classes. See the Unicode manual for more information. :param string: a UCS-4 encoded string. .. function:: unicode_script_from_iso15924(iso15924: int) -> ~gi.repository.GLib.UnicodeScript :param iso15924: .. function:: unicode_script_to_iso15924(script: ~gi.repository.GLib.UnicodeScript) -> int :param script: .. function:: unix_error_quark() -> int .. function:: unix_fd_add_full(priority: int, fd: int, condition: ~gi.repository.GLib.IOCondition, function: ~typing.Callable[[int, ~gi.repository.GLib.IOCondition, ~typing.Any], bool], user_data: ~typing.Any = None) -> int Sets a function to be called when the IO condition, as specified by ``condition`` becomes true for ``fd``\. This is the same as :func:`~gi.repository.GLib.unix_fd_add`, except that it allows you to specify a non-default priority and a provide a :obj:`~gi.repository.GLib.DestroyNotify` for ``user_data``\. .. versionadded:: 2.36 :param priority: the priority of the source :param fd: a file descriptor :param condition: IO conditions to watch for on ``fd`` :param function: a :obj:`~gi.repository.GLib.UnixFDSourceFunc` :param user_data: data to pass to ``function`` :return: the ID (greater than 0) of the event source .. function:: unix_fd_source_new(fd: int, condition: ~gi.repository.GLib.IOCondition) -> ~gi.repository.GLib.Source Creates a :obj:`~gi.repository.GLib.Source` to watch for a particular I/O condition on a file descriptor. The source will never close the ``fd`` — you must do it yourself. Any callback attached to the returned :obj:`~gi.repository.GLib.Source` must have type :obj:`~gi.repository.GLib.UnixFDSourceFunc`\. .. versionadded:: 2.36 :param fd: a file descriptor :param condition: I/O conditions to watch for on ``fd`` :return: the newly created :obj:`~gi.repository.GLib.Source` .. function:: unix_get_passwd_entry(user_name: str) -> ~typing.Any | None Get the ``passwd`` file entry for the given ``user_name`` using ``getpwnam_r()``\. This can fail if the given ``user_name`` doesn’t exist. The returned ``struct passwd`` has been allocated using :func:`~gi.repository.GLib.malloc` and should be freed using :func:`~gi.repository.GLib.free`. The strings referenced by the returned struct are included in the same allocation, so are valid until the ``struct passwd`` is freed. This function is safe to call from multiple threads concurrently. You will need to include ``pwd.h`` to get the definition of ``struct passwd``\. .. versionadded:: 2.64 :param user_name: the username to get the passwd file entry for :return: passwd entry, or :const:`None` on error; free the returned value with :func:`~gi.repository.GLib.free` .. function:: unix_open_pipe(fds: list[int], flags: int) -> bool Similar to the UNIX pipe() call, but on modern systems like Linux uses the pipe2() system call, which atomically creates a pipe with the configured flags. As of GLib 2.78, the supported flags are ``O_CLOEXEC``\/``FD_CLOEXEC`` (see below) and ``O_NONBLOCK``\. Prior to GLib 2.78, only ``FD_CLOEXEC`` was supported — if you wanted to configure ``O_NONBLOCK`` then that had to be done separately with ``fcntl()``\. Since GLib 2.80, the constants :const:`~gi.repository.GLib.UnixPipeEnd.READ` and :const:`~gi.repository.GLib.UnixPipeEnd.WRITE` can be used as mnemonic indexes in ``fds``\. It is a programmer error to call this function with unsupported flags, and a critical warning will be raised. As of GLib 2.78, it is preferred to pass ``O_CLOEXEC`` in, rather than ``FD_CLOEXEC``\, as that matches the underlying ``pipe()`` API more closely. Prior to 2.78, only ``FD_CLOEXEC`` was supported. Support for ``FD_CLOEXEC`` may be deprecated and removed in future. .. versionadded:: 2.30 :param fds: Array of two integers :param flags: Bitfield of file descriptor flags, as for fcntl() :return: :const:`True` on success, :const:`False` if not (and errno will be set). .. function:: unix_set_fd_nonblocking(fd: int, nonblock: bool) -> bool Control the non-blocking state of the given file descriptor, according to ``nonblock``\. On most systems this uses %O_NONBLOCK, but on some older ones may use %O_NDELAY. .. versionadded:: 2.30 :param fd: A file descriptor :param nonblock: If :const:`True`, set the descriptor to be non-blocking :return: :const:`True` if successful .. function:: unix_signal_add(priority: int, signum: int, handler: ~typing.Callable[[~typing.Any], bool], user_data: ~typing.Any = None) -> int A convenience function for :func:`~gi.repository.GLib.unix_signal_source_new`, which attaches to the default :obj:`~gi.repository.GLib.MainContext`\. You can remove the watch using :func:`~gi.repository.GLib.Source.remove`. .. versionadded:: 2.30 :param priority: :param signum: Signal number :param handler: Callback :param user_data: Data for ``handler`` :return: An ID (greater than 0) for the event source .. function:: unix_signal_add_full(priority: int, signum: int, handler: ~typing.Callable[[~typing.Any], bool], user_data: ~typing.Any = None) -> int A convenience function for :func:`~gi.repository.GLib.unix_signal_source_new`, which attaches to the default :obj:`~gi.repository.GLib.MainContext`\. You can remove the watch using :func:`~gi.repository.GLib.Source.remove`. .. versionadded:: 2.30 .. deprecated:: PyGObject-3.16.0 GLib.unix_signal_add_full is deprecated; use GLib.unix_signal_add instead :param priority: the priority of the signal source. Typically this will be in the range between :const:`~gi.repository.GLib.PRIORITY_DEFAULT` and :const:`~gi.repository.GLib.PRIORITY_HIGH`. :param signum: Signal number :param handler: Callback :param user_data: Data for ``handler`` :return: An ID (greater than 0) for the event source .. function:: unix_signal_source_new(signum: int) -> ~gi.repository.GLib.Source Create a :obj:`~gi.repository.GLib.Source` that will be dispatched upon delivery of the UNIX signal ``signum``\. In GLib versions before 2.36, only ``SIGHUP``\, ``SIGINT``\, ``SIGTERM`` can be monitored. In GLib 2.36, ``SIGUSR1`` and ``SIGUSR2`` were added. In GLib 2.54, ``SIGWINCH`` was added. Note that unlike the UNIX default, all sources which have created a watch will be dispatched, regardless of which underlying thread invoked :func:`~gi.repository.GLib.unix_signal_source_new`. For example, an effective use of this function is to handle ``SIGTERM`` cleanly; flushing any outstanding files, and then calling :func:`~gi.repository.GLib.MainLoop.quit`. It is not safe to do any of this from a regular UNIX signal handler; such a handler may be invoked while malloc() or another library function is running, causing reentrancy issues if the handler attempts to use those functions. None of the GLib/GObject API is safe against this kind of reentrancy. The interaction of this source when combined with native UNIX functions like sigprocmask() is not defined. The source will not initially be associated with any :obj:`~gi.repository.GLib.MainContext` and must be added to one with :func:`~gi.repository.GLib.Source.attach` before it will be executed. .. versionadded:: 2.30 :param signum: A signal number :return: A newly created :obj:`~gi.repository.GLib.Source` .. function:: unlink(filename: str) -> int A wrapper for the POSIX unlink() function. The unlink() function deletes a name from the filesystem. If this was the last link to the file and no processes have it opened, the diskspace occupied by the file is freed. See your C library manual for more details about unlink(). Note that on Windows, it is in general not possible to delete files that are open to some process, or mapped into memory. .. versionadded:: 2.6 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :return: 0 if the name was successfully deleted, -1 if an error occurred .. function:: unsetenv(variable: str) -> None Removes an environment variable from the environment. Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed. You should be mindful of the fact that environment variable handling in UNIX is not thread-safe, and your program may crash if one thread calls :func:`~gi.repository.GLib.unsetenv` while another thread is calling getenv(). (And note that many functions, such as gettext(), call getenv() internally.) This function is only safe to use at the very start of your program, before creating any other threads (or creating objects that create worker threads of their own). If you need to set up the environment for a child process, you can use :func:`~gi.repository.GLib.get_environ` to get an environment array, modify that with :func:`~gi.repository.GLib.environ_setenv` and :func:`~gi.repository.GLib.environ_unsetenv`, and then pass that array directly to execvpe(), :func:`~gi.repository.GLib.spawn_async`, or the like. .. versionadded:: 2.4 :param variable: the environment variable to remove, must not contain '=' .. function:: uri_build(flags: ~gi.repository.GLib.UriFlags, scheme: str, userinfo: str | None, host: str | None, port: int, path: str, query: str | None = None, fragment: str | None = None) -> ~gi.repository.GLib.Uri :param flags: :param scheme: :param userinfo: :param host: :param port: :param path: :param query: :param fragment: .. function:: uri_build_with_user(flags: ~gi.repository.GLib.UriFlags, scheme: str, user: str | None, password: str | None, auth_params: str | None, host: str | None, port: int, path: str, query: str | None = None, fragment: str | None = None) -> ~gi.repository.GLib.Uri :param flags: :param scheme: :param user: :param password: :param auth_params: :param host: :param port: :param path: :param query: :param fragment: .. function:: uri_error_quark() -> int .. function:: uri_escape_bytes(unescaped: list[int], reserved_chars_allowed: str | None = None) -> str :param unescaped: :param reserved_chars_allowed: .. function:: uri_escape_string(unescaped: str, reserved_chars_allowed: str | None, allow_utf8: bool) -> str :param unescaped: :param reserved_chars_allowed: :param allow_utf8: .. function:: uri_is_valid(uri_string: str, flags: ~gi.repository.GLib.UriFlags) -> bool :param uri_string: :param flags: .. function:: uri_join(flags: ~gi.repository.GLib.UriFlags, scheme: str | None, userinfo: str | None, host: str | None, port: int, path: str, query: str | None = None, fragment: str | None = None) -> str :param flags: :param scheme: :param userinfo: :param host: :param port: :param path: :param query: :param fragment: .. function:: uri_join_with_user(flags: ~gi.repository.GLib.UriFlags, scheme: str | None, user: str | None, password: str | None, auth_params: str | None, host: str | None, port: int, path: str, query: str | None = None, fragment: str | None = None) -> str :param flags: :param scheme: :param user: :param password: :param auth_params: :param host: :param port: :param path: :param query: :param fragment: .. function:: uri_list_extract_uris(uri_list: str) -> list[str] :param uri_list: .. function:: uri_parse(uri_string: str, flags: ~gi.repository.GLib.UriFlags) -> ~gi.repository.GLib.Uri :param uri_string: :param flags: .. function:: uri_parse_params(params: str, length: int, separators: str, flags: ~gi.repository.GLib.UriParamsFlags) -> dict[str, str] :param params: :param length: :param separators: :param flags: .. function:: uri_parse_scheme(uri: str) -> str | None :param uri: .. function:: uri_peek_scheme(uri: str) -> str | None :param uri: .. function:: uri_resolve_relative(base_uri_string: str | None, uri_ref: str, flags: ~gi.repository.GLib.UriFlags) -> str :param base_uri_string: :param uri_ref: :param flags: .. function:: uri_split(uri_ref: str, flags: ~gi.repository.GLib.UriFlags) -> ~typing.Tuple[bool, str | None, str | None, str | None, int, str, str | None, str | None] :param uri_ref: :param flags: .. function:: uri_split_network(uri_string: str, flags: ~gi.repository.GLib.UriFlags) -> ~typing.Tuple[bool, str | None, str | None, int] :param uri_string: :param flags: .. function:: uri_split_with_user(uri_ref: str, flags: ~gi.repository.GLib.UriFlags) -> ~typing.Tuple[bool, str | None, str | None, str | None, str | None, str | None, int, str, str | None, str | None] :param uri_ref: :param flags: .. function:: uri_unescape_bytes(escaped_string: str, length: int, illegal_characters: str | None = None) -> ~gi.repository.GLib.Bytes :param escaped_string: :param length: :param illegal_characters: .. function:: uri_unescape_segment(escaped_string: str | None = None, escaped_string_end: str | None = None, illegal_characters: str | None = None) -> str | None :param escaped_string: :param escaped_string_end: :param illegal_characters: .. function:: uri_unescape_string(escaped_string: str, illegal_characters: str | None = None) -> str | None :param escaped_string: :param illegal_characters: .. function:: usleep(microseconds: int) -> None Pauses the current thread for the given number of microseconds. There are 1 million microseconds per second (represented by the :const:`~gi.repository.GLib.USEC_PER_SEC` macro). :func:`~gi.repository.GLib.usleep` may have limited precision, depending on hardware and operating system; don't rely on the exact length of the sleep. :param microseconds: number of microseconds to pause .. function:: utf16_to_ucs4(str: list[int]) -> ~typing.Tuple[str, int, int] Convert a string from UTF-16 to UCS-4. The result will be nul-terminated. :param str: a UTF-16 encoded string :return: a pointer to a newly allocated UCS-4 string. This value must be freed with :func:`~gi.repository.GLib.free`. If an error occurs, :const:`None` will be returned and ``error`` set. .. function:: utf16_to_utf8(str: list[int]) -> ~typing.Tuple[str, int, int] Convert a string from UTF-16 to UTF-8. The result will be terminated with a 0 byte. Note that the input is expected to be already in native endianness, an initial byte-order-mark character is not handled specially. :func:`~gi.repository.GLib.convert` can be used to convert a byte buffer of UTF-16 data of ambiguous endianness. Further note that this function does not validate the result string; it may e.g. include embedded NUL characters. The only validation done by this function is to ensure that the input can be correctly interpreted as UTF-16, i.e. it doesn't contain unpaired surrogates or partial character sequences. :param str: a UTF-16 encoded string :return: a pointer to a newly allocated UTF-8 string. This value must be freed with :func:`~gi.repository.GLib.free`. If an error occurs, :const:`None` will be returned and ``error`` set. .. function:: utf8_casefold(str: str, len: int) -> str Converts a string into a form that is independent of case. The result will not correspond to any particular case, but can be compared for equality or ordered with the results of calling :func:`~gi.repository.GLib.utf8_casefold` on other strings. Note that calling :func:`~gi.repository.GLib.utf8_casefold` followed by :func:`~gi.repository.GLib.utf8_collate` is only an approximation to the correct linguistic case insensitive ordering, though it is a fairly good one. Getting this exactly right would require a more sophisticated collation function that takes case sensitivity into account. GLib does not currently provide such a function. :param str: a UTF-8 encoded string :param len: length of ``str``\, in bytes, or -1 if ``str`` is nul-terminated. :return: a newly allocated string, that is a case independent form of ``str``\. .. function:: utf8_collate(str1: str, str2: str) -> int Compares two strings for ordering using the linguistically correct rules for the [current locale][setlocale]. When sorting a large number of strings, it will be significantly faster to obtain collation keys with :func:`~gi.repository.GLib.utf8_collate_key` and compare the keys with strcmp() when sorting instead of sorting the original strings. If the two strings are not comparable due to being in different collation sequences, the result is undefined. This can happen if the strings are in different language scripts, for example. :param str1: a UTF-8 encoded string :param str2: a UTF-8 encoded string :return: < 0 if ``str1`` compares before ``str2``\, 0 if they compare equal, > 0 if ``str1`` compares after ``str2``\. .. function:: utf8_collate_key(str: str, len: int) -> str Converts a string into a collation key that can be compared with other collation keys produced by the same function using strcmp(). The results of comparing the collation keys of two strings with strcmp() will always be the same as comparing the two original keys with :func:`~gi.repository.GLib.utf8_collate`. Note that this function depends on the [current locale][setlocale]. :param str: a UTF-8 encoded string. :param len: length of ``str``\, in bytes, or -1 if ``str`` is nul-terminated. :return: a newly allocated string. This string should be freed with :func:`~gi.repository.GLib.free` when you are done with it. .. function:: utf8_collate_key_for_filename(str: str, len: int) -> str Converts a string into a collation key that can be compared with other collation keys produced by the same function using strcmp(). In order to sort filenames correctly, this function treats the dot '.' as a special case. Most dictionary orderings seem to consider it insignificant, thus producing the ordering "event.c" "eventgenerator.c" "event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we would like to treat numbers intelligently so that "file1" "file10" "file5" is sorted as "file1" "file5" "file10". Note that this function depends on the [current locale][setlocale]. .. versionadded:: 2.8 :param str: a UTF-8 encoded string. :param len: length of ``str``\, in bytes, or -1 if ``str`` is nul-terminated. :return: a newly allocated string. This string should be freed with :func:`~gi.repository.GLib.free` when you are done with it. .. function:: utf8_find_next_char(p: str, end: str | None = None) -> str | None Finds the start of the next UTF-8 character in the string after ``p``\. ``p`` does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. If ``end`` is :const:`None`, the return value will never be :const:`None`: if the end of the string is reached, a pointer to the terminating nul byte is returned. If ``end`` is non-:const:`None`, the return value will be :const:`None` if the end of the string is reached. :param p: a pointer to a position within a UTF-8 encoded string :param end: a pointer to the byte following the end of the string, or :const:`None` to indicate that the string is nul-terminated :return: a pointer to the found character or :const:`None` if ``end`` is set and is reached .. function:: utf8_find_prev_char(str: str, p: str) -> str | None Given a position ``p`` with a UTF-8 encoded string ``str``\, find the start of the previous UTF-8 character starting before ``p``\. Returns :const:`None` if no UTF-8 characters are present in ``str`` before ``p``\. ``p`` does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. :param str: pointer to the beginning of a UTF-8 encoded string :param p: pointer to some position within ``str`` :return: a pointer to the found character or :const:`None`. .. function:: utf8_get_char(p: str) -> str Converts a sequence of bytes encoded as UTF-8 to a Unicode character. If ``p`` does not point to a valid UTF-8 encoded character, results are undefined. If you are not sure that the bytes are complete valid Unicode characters, you should use :func:`~gi.repository.GLib.utf8_get_char_validated` instead. :param p: a pointer to Unicode character encoded as UTF-8 :return: the resulting character .. function:: utf8_get_char_validated(p: str, max_len: int) -> str Convert a sequence of bytes encoded as UTF-8 to a Unicode character. This function checks for incomplete characters, for invalid characters such as characters that are out of the range of Unicode, and for overlong encodings of valid characters. Note that :func:`~gi.repository.GLib.utf8_get_char_validated` returns (gunichar)-2 if ``max_len`` is positive and any of the bytes in the first UTF-8 character sequence are nul. :param p: a pointer to Unicode character encoded as UTF-8 :param max_len: the maximum number of bytes to read, or -1 if ``p`` is nul-terminated :return: the resulting character. If ``p`` points to a partial sequence at the end of a string that could begin a valid character (or if ``max_len`` is zero), returns (gunichar)-2; otherwise, if ``p`` does not point to a valid UTF-8 encoded Unicode character, returns (gunichar)-1. .. function:: utf8_make_valid(str: str, len: int) -> str If the provided string is valid UTF-8, return a copy of it. If not, return a copy in which bytes that could not be interpreted as valid Unicode are replaced with the Unicode replacement character (U+FFFD). For example, this is an appropriate function to use if you have received a string that was incorrectly declared to be UTF-8, and you need a valid UTF-8 version of it that can be logged or displayed to the user, with the assumption that it is close enough to ASCII or UTF-8 to be mostly readable as-is. .. versionadded:: 2.52 :param str: string to coerce into UTF-8 :param len: the maximum length of ``str`` to use, in bytes. If ``len`` < 0, then the string is nul-terminated. :return: a valid UTF-8 string whose content resembles ``str`` .. function:: utf8_normalize(str: str, len: int, mode: ~gi.repository.GLib.NormalizeMode) -> str | None Converts a string into canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. The string has to be valid UTF-8, otherwise :const:`None` is returned. You should generally call :func:`~gi.repository.GLib.utf8_normalize` before comparing two Unicode strings. The normalization mode :const:`~gi.repository.GLib.NormalizeMode.DEFAULT` only standardizes differences that do not affect the text content, such as the above-mentioned accent representation. :const:`~gi.repository.GLib.NormalizeMode.ALL` also standardizes the "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this case DIGIT THREE). Formatting information may be lost but for most text operations such characters should be considered the same. :const:`~gi.repository.GLib.NormalizeMode.DEFAULT_COMPOSE` and :const:`~gi.repository.GLib.NormalizeMode.ALL_COMPOSE` are like :const:`~gi.repository.GLib.NormalizeMode.DEFAULT` and :const:`~gi.repository.GLib.NormalizeMode.ALL`, but returned a result with composed forms rather than a maximally decomposed form. This is often useful if you intend to convert the string to a legacy encoding or pass it to a system with less capable Unicode handling. :param str: a UTF-8 encoded string. :param len: length of ``str``\, in bytes, or -1 if ``str`` is nul-terminated. :param mode: the type of normalization to perform. :return: a newly allocated string, that is the normalized form of ``str``\, or :const:`None` if ``str`` is not valid UTF-8. .. function:: utf8_offset_to_pointer(str: str, offset: int) -> str Converts from an integer character offset to a pointer to a position within the string. Since 2.10, this function allows to pass a negative ``offset`` to step backwards. It is usually worth stepping backwards from the end instead of forwards if ``offset`` is in the last fourth of the string, since moving forward is about 3 times faster than moving backward. Note that this function doesn't abort when reaching the end of ``str``\. Therefore you should be sure that ``offset`` is within string boundaries before calling that function. Call :func:`~gi.repository.GLib.utf8_strlen` when unsure. This limitation exists as this function is called frequently during text rendering and therefore has to be as fast as possible. :param str: a UTF-8 encoded string :param offset: a character offset within ``str`` :return: the resulting pointer .. function:: utf8_pointer_to_offset(str: str, pos: str) -> int Converts from a pointer to position within a string to an integer character offset. Since 2.10, this function allows ``pos`` to be before ``str``\, and returns a negative offset in this case. :param str: a UTF-8 encoded string :param pos: a pointer to a position within ``str`` :return: the resulting character offset .. function:: utf8_prev_char(p: str) -> str Finds the previous UTF-8 character in the string before ``p``\. ``p`` does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. If ``p`` might be the first character of the string, you must use :func:`~gi.repository.GLib.utf8_find_prev_char` instead. :param p: a pointer to a position within a UTF-8 encoded string :return: a pointer to the found character .. function:: utf8_strchr(p: str, len: int, c: str) -> str | None Finds the leftmost occurrence of the given Unicode character in a UTF-8 encoded string, while limiting the search to ``len`` bytes. If ``len`` is -1, allow unbounded search. :param p: a nul-terminated UTF-8 encoded string :param len: the maximum length of ``p`` :param c: a Unicode character :return: :const:`None` if the string does not contain the character, otherwise, a pointer to the start of the leftmost occurrence of the character in the string. .. function:: utf8_strdown(str: str, len: int) -> str Converts all Unicode characters in the string that have a case to lowercase. The exact manner that this is done depends on the current locale, and may result in the number of characters in the string changing. :param str: a UTF-8 encoded string :param len: length of ``str``\, in bytes, or -1 if ``str`` is nul-terminated. :return: a newly allocated string, with all characters converted to lowercase. .. function:: utf8_strlen(p: str, max: int) -> int Computes the length of the string in characters, not including the terminating nul character. If the ``max``\'th byte falls in the middle of a character, the last (partial) character is not counted. :param p: pointer to the start of a UTF-8 encoded string :param max: the maximum number of bytes to examine. If ``max`` is less than 0, then the string is assumed to be nul-terminated. If ``max`` is 0, ``p`` will not be examined and may be :const:`None`. If ``max`` is greater than 0, up to ``max`` bytes are examined :return: the length of the string in characters .. function:: utf8_strncpy(dest: str, src: str, n: int) -> str Like the standard C strncpy() function, but copies a given number of characters instead of a given number of bytes. The ``src`` string must be valid UTF-8 encoded text. (Use :func:`~gi.repository.GLib.utf8_validate` on all text before trying to use UTF-8 utility functions with it.) Note you must ensure ``dest`` is at least 4 \* ``n`` + 1 to fit the largest possible UTF-8 characters :param dest: buffer to fill with characters from ``src`` :param src: UTF-8 encoded string :param n: character count :return: ``dest`` .. function:: utf8_strrchr(p: str, len: int, c: str) -> str | None Find the rightmost occurrence of the given Unicode character in a UTF-8 encoded string, while limiting the search to ``len`` bytes. If ``len`` is -1, allow unbounded search. :param p: a nul-terminated UTF-8 encoded string :param len: the maximum length of ``p`` :param c: a Unicode character :return: :const:`None` if the string does not contain the character, otherwise, a pointer to the start of the rightmost occurrence of the character in the string. .. function:: utf8_strreverse(str: str, len: int) -> str Reverses a UTF-8 string. ``str`` must be valid UTF-8 encoded text. (Use :func:`~gi.repository.GLib.utf8_validate` on all text before trying to use UTF-8 utility functions with it.) This function is intended for programmatic uses of reversed strings. It pays no attention to decomposed characters, combining marks, byte order marks, directional indicators (LRM, LRO, etc) and similar characters which might need special handling when reversing a string for display purposes. Note that unlike :func:`~gi.repository.GLib.strreverse`, this function returns newly-allocated memory, which should be freed with :func:`~gi.repository.GLib.free` when no longer needed. .. versionadded:: 2.2 :param str: a UTF-8 encoded string :param len: the maximum length of ``str`` to use, in bytes. If ``len`` < 0, then the string is nul-terminated. :return: a newly-allocated string which is the reverse of ``str`` .. function:: utf8_strup(str: str, len: int) -> str Converts all Unicode characters in the string that have a case to uppercase. The exact manner that this is done depends on the current locale, and may result in the number of characters in the string increasing. (For instance, the German ess-zet will be changed to SS.) :param str: a UTF-8 encoded string :param len: length of ``str``\, in bytes, or -1 if ``str`` is nul-terminated. :return: a newly allocated string, with all characters converted to uppercase. .. function:: utf8_substring(str: str, start_pos: int, end_pos: int) -> str Copies a substring out of a UTF-8 encoded string. The substring will contain ``end_pos`` - ``start_pos`` characters. Since GLib 2.72, ``-1`` can be passed to ``end_pos`` to indicate the end of the string. .. versionadded:: 2.30 :param str: a UTF-8 encoded string :param start_pos: a character offset within ``str`` :param end_pos: another character offset within ``str``\, or ``-1`` to indicate the end of the string :return: a newly allocated copy of the requested substring. Free with :func:`~gi.repository.GLib.free` when no longer needed. .. function:: utf8_to_ucs4(str: str, len: int) -> ~typing.Tuple[str, int, int] Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4. A trailing 0 character will be added to the string after the converted text. :param str: a UTF-8 encoded string :param len: the maximum length of ``str`` to use, in bytes. If ``len`` < 0, then the string is nul-terminated. :return: a pointer to a newly allocated UCS-4 string. This value must be freed with :func:`~gi.repository.GLib.free`. If an error occurs, :const:`None` will be returned and ``error`` set. .. function:: utf8_to_ucs4_fast(str: str, len: int) -> ~typing.Tuple[str, int] Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4, assuming valid UTF-8 input. This function is roughly twice as fast as :func:`~gi.repository.GLib.utf8_to_ucs4` but does no error checking on the input. A trailing 0 character will be added to the string after the converted text. :param str: a UTF-8 encoded string :param len: the maximum length of ``str`` to use, in bytes. If ``len`` < 0, then the string is nul-terminated. :return: a pointer to a newly allocated UCS-4 string. This value must be freed with :func:`~gi.repository.GLib.free`. .. function:: utf8_to_utf16(str: str, len: int) -> ~typing.Tuple[int, int, int] Convert a string from UTF-8 to UTF-16. A 0 character will be added to the result after the converted text. :param str: a UTF-8 encoded string :param len: the maximum length (number of bytes) of ``str`` to use. If ``len`` < 0, then the string is nul-terminated. :return: a pointer to a newly allocated UTF-16 string. This value must be freed with :func:`~gi.repository.GLib.free`. If an error occurs, :const:`None` will be returned and ``error`` set. .. function:: utf8_truncate_middle(string: str, truncate_length: int) -> str Cuts off the middle of the string, preserving half of ``truncate_length`` characters at the beginning and half at the end. If ``string`` is already short enough, this returns a copy of ``string``\. If ``truncate_length`` is ``0``\, an empty string is returned. .. versionadded:: 2.78 :param string: a nul-terminated UTF-8 encoded string :param truncate_length: the new size of ``string``\, in characters, including the ellipsis character :return: a newly-allocated copy of ``string`` ellipsized in the middle .. function:: utf8_validate(str: list[int]) -> ~typing.Tuple[bool, str] Validates UTF-8 encoded text. ``str`` is the text to validate; if ``str`` is nul-terminated, then ``max_len`` can be -1, otherwise ``max_len`` should be the number of bytes to validate. If ``end`` is non-:const:`None`, then the end of the valid range will be stored there (i.e. the start of the first invalid character if some bytes were invalid, or the end of the text being validated otherwise). Note that :func:`~gi.repository.GLib.utf8_validate` returns :const:`False` if ``max_len`` is positive and any of the ``max_len`` bytes are nul. Returns :const:`True` if all of ``str`` was valid. Many GLib and GTK routines require valid UTF-8 as input; so data read from a file or the network should be checked with :func:`~gi.repository.GLib.utf8_validate` before doing anything else with it. :param str: a pointer to character data :return: :const:`True` if the text was valid UTF-8 .. function:: utf8_validate_len(str: list[int]) -> ~typing.Tuple[bool, str] Validates UTF-8 encoded text. As with :func:`~gi.repository.GLib.utf8_validate`, but ``max_len`` must be set, and hence this function will always return :const:`False` if any of the bytes of ``str`` are nul. .. versionadded:: 2.60 :param str: a pointer to character data :return: :const:`True` if the text was valid UTF-8 .. function:: utime(filename: str, utb: ~typing.Any = None) -> int A wrapper for the POSIX utime() function. The utime() function sets the access and modification timestamps of a file. See your C library manual for more details about how utime() works on your system. .. versionadded:: 2.18 :param filename: a pathname in the GLib file name encoding (UTF-8 on Windows) :param utb: a pointer to a struct utimbuf. :return: 0 if the operation was successful, -1 if an error occurred .. function:: uuid_string_is_valid(str: str) -> bool Parses the string ``str`` and verify if it is a UUID. The function accepts the following syntax: - simple forms (e.g. ``f81d4fae-7dec-11d0-a765-00a0c91e6bf6``\) Note that hyphens are required within the UUID string itself, as per the aforementioned RFC. .. versionadded:: 2.52 :param str: a string representing a UUID :return: :const:`True` if ``str`` is a valid UUID, :const:`False` otherwise. .. function:: uuid_string_random() -> str Generates a random UUID (RFC 4122 version 4) as a string. It has the same randomness guarantees as :obj:`~gi.repository.GLib.Rand`\, so must not be used for cryptographic purposes such as key generation, nonces, salts or one-time pads. .. versionadded:: 2.52 :return: A string that should be freed with :func:`~gi.repository.GLib.free`. .. function:: variant_get_gtype() -> ~gobject.GType .. function:: variant_is_object_path(string: str) -> bool :param string: .. function:: variant_is_signature(string: str) -> bool :param string: .. function:: variant_parse(type: ~gi.repository.GLib.VariantType | None, text: str, limit: str | None = None, endptr: str | None = None) -> ~gi.repository.GLib.Variant :param type: :param text: :param limit: :param endptr: .. function:: variant_parse_error_print_context(error: ~gi.repository.GLib.GError, source_str: str) -> str :param error: :param source_str: .. function:: variant_parse_error_quark() -> int .. function:: variant_parser_get_error_quark() -> int .. function:: variant_type_checked_(type_string: str) -> ~gi.repository.GLib.VariantType :param type_string: .. function:: variant_type_string_get_depth_(type_string: str) -> int :param type_string: .. function:: variant_type_string_is_valid(type_string: str) -> bool :param type_string: .. function:: variant_type_string_scan(string: str, limit: str | None = None) -> ~typing.Tuple[bool, str] :param string: :param limit: