Functions

access (filename, mode)

aligned_alloc (n_blocks, n_block_bytes, alignment)

aligned_alloc0 (n_blocks, n_block_bytes, alignment)

aligned_free (mem)

aligned_free_sized (mem, alignment, size)

ascii_digit_value (c)

ascii_dtostr (buffer, buf_len, d)

ascii_formatd (buffer, buf_len, format, d)

ascii_strcasecmp (s1, s2)

ascii_strdown (str, len)

ascii_string_to_signed (str, base, min, max)

ascii_string_to_unsigned (str, base, min, max)

ascii_strncasecmp (s1, s2, n)

ascii_strtod (nptr)

ascii_strtoll (nptr, base)

ascii_strtoull (nptr, base)

ascii_strup (str, len)

ascii_tolower (c)

ascii_toupper (c)

ascii_xdigit_value (c)

assert_warning (log_domain, file, line, pretty_function, expression)

assertion_message (domain, file, line, func, message)

assertion_message_cmpint (domain, file, line, func, expr, arg1, cmp, arg2, numtype)

assertion_message_cmpstr (domain, file, line, func, expr, arg1, cmp, arg2)

assertion_message_cmpstrv (domain, file, line, func, expr, arg1, arg2, first_wrong_idx)

assertion_message_error (domain, file, line, func, expr, error, error_domain, error_code)

atexit (func)

atomic_int_add (atomic, val)

atomic_int_and (atomic, val)

atomic_int_compare_and_exchange (atomic, oldval, newval)

atomic_int_compare_and_exchange_full (atomic, oldval, newval)

atomic_int_dec_and_test (atomic)

atomic_int_exchange (atomic, newval)

atomic_int_exchange_and_add (atomic, val)

atomic_int_get (atomic)

atomic_int_inc (atomic)

atomic_int_or (atomic, val)

atomic_int_set (atomic, newval)

atomic_int_xor (atomic, val)

atomic_pointer_add (atomic, val)

atomic_pointer_and (atomic, val)

atomic_pointer_compare_and_exchange (atomic, oldval, newval)

atomic_pointer_compare_and_exchange_full (atomic, oldval, newval)

atomic_pointer_exchange (atomic, newval)

atomic_pointer_get (atomic)

atomic_pointer_or (atomic, val)

atomic_pointer_set (atomic, newval)

atomic_pointer_xor (atomic, val)

atomic_rc_box_acquire (mem_block)

atomic_rc_box_alloc (block_size)

atomic_rc_box_alloc0 (block_size)

atomic_rc_box_dup (block_size, mem_block)

atomic_rc_box_get_size (mem_block)

atomic_rc_box_release (mem_block)

atomic_rc_box_release_full (mem_block, clear_func)

atomic_ref_count_compare (arc, val)

atomic_ref_count_dec (arc)

atomic_ref_count_inc (arc)

atomic_ref_count_init (arc)

base64_decode (text)

base64_decode_inplace (text)

base64_encode (data)

base64_encode_close (break_lines, state, save)

base64_encode_step (in_, break_lines, state, save)

basename (file_name)

bit_lock (address, lock_bit)

bit_nth_lsf (mask, nth_bit)

bit_nth_msf (mask, nth_bit)

bit_storage (number)

bit_trylock (address, lock_bit)

bit_unlock (address, lock_bit)

bookmark_file_error_quark ()

build_filenamev (args)

build_pathv (separator, args)

byte_array_free (array, free_segment)

byte_array_free_to_bytes (array)

byte_array_new ()

byte_array_new_take (data)

byte_array_steal (array)

byte_array_unref (array)

canonicalize_filename (filename, relative_to)

chdir (path)

check_version (required_major, required_minor, required_micro)

checksum_type_get_length (checksum_type)

child_watch_add (priority, pid, function, *data)

child_watch_source_new (pid)

clear_error ()

close (fd)

compute_checksum_for_bytes (checksum_type, data)

compute_checksum_for_data (checksum_type, data)

compute_checksum_for_string (checksum_type, str, length)

compute_hmac_for_bytes (digest_type, key, data)

compute_hmac_for_data (digest_type, key, data)

compute_hmac_for_string (digest_type, key, str, length)

convert (str, to_codeset, from_codeset)

convert_error_quark ()

convert_with_fallback (str, to_codeset, from_codeset, fallback)

datalist_foreach (datalist, func, *user_data)

datalist_get_data (datalist, key)

datalist_get_flags (datalist)

datalist_id_get_data (datalist, key_id)

datalist_id_remove_multiple (datalist, keys)

datalist_set_flags (datalist, flags)

datalist_unset_flags (datalist, flags)

dataset_destroy (dataset_location)

dataset_foreach (dataset_location, func, *user_data)

dataset_id_get_data (dataset_location, key_id)

date_get_days_in_month (month, year)

date_get_monday_weeks_in_year (year)

date_get_sunday_weeks_in_year (year)

date_is_leap_year (year)

date_strftime (s, slen, format, date)

date_valid_day (day)

date_valid_dmy (day, month, year)

date_valid_julian (julian_date)

date_valid_month (month)

date_valid_weekday (weekday)

date_valid_year (year)

dcgettext (domain, msgid, category)

dgettext (domain, msgid)

dir_make_tmp (tmpl)

direct_equal (v1, v2)

direct_hash (v)

dngettext (domain, msgid, msgid_plural, n)

double_equal (v1, v2)

double_hash (v)

dpgettext (domain, msgctxtid, msgidoffset)

dpgettext2 (domain, context, msgid)

environ_getenv (envp, variable)

environ_setenv (envp, variable, value, overwrite)

environ_unsetenv (envp, variable)

file_error_from_errno (err_no)

file_error_quark ()

file_get_contents (filename)

file_open_tmp (tmpl)

file_read_link (filename)

file_set_contents (filename, contents)

file_set_contents_full (filename, contents, flags, mode)

file_test (filename, test)

filename_display_basename (filename)

filename_display_name (filename)

filename_from_uri (uri)

filename_from_utf8 (utf8string, len)

filename_to_uri (filename, hostname)

filename_to_utf8 (opsysstring, len)

find_program_in_path (program)

format_size (size)

format_size_for_display (size)

format_size_full (size, flags)

free (mem)

free_sized (mem, size)

get_application_name ()

get_charset ()

get_codeset ()

get_console_charset ()

get_current_dir ()

get_current_time ()

get_environ ()

get_filename_charsets ()

get_home_dir ()

get_host_name ()

get_language_names ()

get_language_names_with_category (category_name)

get_locale_variants (locale)

get_monotonic_time ()

get_num_processors ()

get_os_info (key_name)

get_prgname ()

get_real_name ()

get_real_time ()

get_system_config_dirs ()

get_system_data_dirs ()

get_tmp_dir ()

get_user_cache_dir ()

get_user_config_dir ()

get_user_data_dir ()

get_user_name ()

get_user_runtime_dir ()

get_user_special_dir (directory)

get_user_state_dir ()

getenv (variable)

hash_table_add (hash_table, key)

hash_table_contains (hash_table, key)

hash_table_destroy (hash_table)

hash_table_insert (hash_table, key, value)

hash_table_lookup (hash_table, key)

hash_table_lookup_extended (hash_table, lookup_key)

hash_table_new_similar (other_hash_table)

hash_table_remove (hash_table, key)

hash_table_remove_all (hash_table)

hash_table_replace (hash_table, key, value)

hash_table_size (hash_table)

hash_table_steal (hash_table, key)

hash_table_steal_all (hash_table)

hash_table_steal_extended (hash_table, lookup_key)

hash_table_unref (hash_table)

hook_destroy (hook_list, hook_id)

hook_destroy_link (hook_list, hook)

hook_free (hook_list, hook)

hook_insert_before (hook_list, sibling, hook)

hook_prepend (hook_list, hook)

hook_unref (hook_list, hook)

hostname_is_ascii_encoded (hostname)

hostname_is_ip_address (hostname)

hostname_is_non_ascii (hostname)

hostname_to_ascii (hostname)

hostname_to_unicode (hostname)

idle_add (priority, function, *data)

idle_remove_by_data (data)

idle_source_new ()

int64_equal (v1, v2)

int64_hash (v)

int_equal (v1, v2)

int_hash (v)

intern_static_string (string)

intern_string (string)

io_add_watch (channel, priority, condition, func, *user_data)

io_channel_error_from_errno (en)

io_channel_error_quark ()

io_create_watch (channel, condition)

key_file_error_quark ()

listenv ()

locale_from_utf8 (utf8string, len)

locale_to_utf8 (opsysstring)

log_default_handler (log_domain, log_level, message, unused_data)

log_get_debug_enabled ()

log_remove_handler (log_domain, handler_id)

log_set_always_fatal (fatal_mask)

log_set_debug_enabled (enabled)

log_set_fatal_mask (log_domain, fatal_mask)

log_set_handler (log_domain, log_levels, log_func, *user_data)

log_set_writer_func (*user_data)

log_structured_array (log_level, fields)

log_variant (log_domain, log_level, fields)

log_writer_default (log_level, fields, user_data)

log_writer_default_set_use_stderr (use_stderr)

log_writer_default_would_drop (log_level, log_domain)

log_writer_format_fields (log_level, fields, use_color)

log_writer_is_journald (output_fd)

log_writer_journald (log_level, fields, user_data)

log_writer_standard_streams (log_level, fields, user_data)

log_writer_supports_color (output_fd)

main_context_default ()

main_context_get_thread_default ()

main_context_ref_thread_default ()

main_current_source ()

main_depth ()

malloc (n_bytes)

malloc0 (n_bytes)

malloc0_n (n_blocks, n_block_bytes)

malloc_n (n_blocks, n_block_bytes)

markup_error_quark ()

markup_escape_text (text, length)

mem_is_system_malloc ()

mem_profile ()

mem_set_vtable (vtable)

memdup (mem, byte_size)

memdup2 (mem, byte_size)

mkdir_with_parents (pathname, mode)

nullify_pointer (nullify_location)

number_parser_error_quark ()

on_error_query (prg_name)

on_error_stack_trace (prg_name)

once_init_enter (location)

once_init_leave (location, result)

option_error_quark ()

parse_debug_string (string, keys)

path_buf_equal (v1, v2)

path_get_basename (file_name)

path_get_dirname (file_name)

path_is_absolute (file_name)

path_skip_root (file_name)

pattern_match_simple (pattern, string)

pointer_bit_lock (address, lock_bit)

pointer_bit_trylock (address, lock_bit)

pointer_bit_unlock (address, lock_bit)

poll (fds, nfds, timeout)

prefix_error_literal (err, prefix)

propagate_error (src)

quark_from_static_string (string)

quark_from_string (string)

quark_to_string (quark)

quark_try_string (string)

random_double ()

random_double_range (begin, end)

random_int ()

random_int_range (begin, end)

random_set_seed (seed)

rc_box_acquire (mem_block)

rc_box_alloc (block_size)

rc_box_alloc0 (block_size)

rc_box_dup (block_size, mem_block)

rc_box_get_size (mem_block)

rc_box_release (mem_block)

rc_box_release_full (mem_block, clear_func)

realloc (mem, n_bytes)

realloc_n (mem, n_blocks, n_block_bytes)

ref_count_compare (rc, val)

ref_count_dec (rc)

ref_count_inc (rc)

ref_count_init (rc)

ref_string_acquire (str)

ref_string_length (str)

ref_string_new (str)

ref_string_new_intern (str)

ref_string_new_len (str, len)

ref_string_release (str)

regex_check_replacement (replacement)

regex_error_quark ()

regex_escape_nul (string, length)

regex_escape_string (string, length)

regex_match_simple (pattern, string, compile_options, match_options)

regex_split_simple (pattern, string, compile_options, match_options)

reload_user_special_dirs_cache ()

rmdir (filename)

sequence_get (iter)

sequence_insert_before (iter, data)

sequence_move (src, dest)

sequence_move_range (dest, begin, end)

sequence_range_get_midpoint (begin, end)

sequence_remove (iter)

sequence_remove_range (begin, end)

sequence_set (iter, data)

sequence_swap (a, b)

set_application_name (application_name)

set_error_literal (domain, code, message)

set_prgname (prgname)

setenv (variable, value, overwrite)

shell_error_quark ()

shell_parse_argv (command_line)

shell_quote (unquoted_string)

shell_unquote (quoted_string)

slice_alloc (block_size)

slice_alloc0 (block_size)

slice_copy (block_size, mem_block)

slice_free1 (block_size, mem_block)

slice_free_chain_with_offset (block_size, mem_chain, next_offset)

slice_get_config (ckey)

slice_get_config_state (ckey, address, n_values)

slice_set_config (ckey, value)

source_remove (tag)

source_remove_by_funcs_user_data (funcs, user_data)

source_remove_by_user_data (user_data)

source_set_name_by_id (tag, name)

spaced_primes_closest (num)

spawn_async (argv, envp=None, working_directory=None, flags=GLib.SpawnFlags.DEFAULT, child_setup=None, user_data=None, standard_input=False, standard_output=False, standard_error=False)

spawn_async_with_fds (working_directory, argv, envp, flags, child_setup, user_data, stdin_fd, stdout_fd, stderr_fd)

spawn_async_with_pipes (working_directory, argv, envp, flags, child_setup, *user_data)

spawn_async_with_pipes_and_fds (working_directory, argv, envp, flags, child_setup, user_data, stdin_fd, stdout_fd, stderr_fd, source_fds, target_fds)

spawn_check_exit_status (wait_status)

spawn_check_wait_status (wait_status)

spawn_close_pid (pid)

spawn_command_line_async (command_line)

spawn_command_line_sync (command_line)

spawn_error_quark ()

spawn_exit_error_quark ()

spawn_sync (working_directory, argv, envp, flags, child_setup, *user_data)

stpcpy (dest, src)

str_equal (v1, v2)

str_has_prefix (str, prefix)

str_has_suffix (str, suffix)

str_hash (v)

str_is_ascii (str)

str_match_string (search_term, potential_hit, accept_alternates)

str_to_ascii (str, from_locale)

str_tokenize_and_fold (string, translit_locale)

strcanon (string, valid_chars, substitutor)

strcasecmp (s1, s2)

strchomp (string)

strchug (string)

strcmp0 (str1, str2)

strcompress (source)

strdelimit (string, delimiters, new_delimiter)

strdown (string)

strdup (str)

strerror (errnum)

strescape (source, exceptions)

strfreev (str_array)

strip_context (msgid, msgval)

strjoinv (separator, str_array)

strlcat (dest, src, dest_size)

strlcpy (dest, src, dest_size)

strncasecmp (s1, s2, n)

strndup (str, n)

strnfill (length, fill_char)

strreverse (string)

strrstr (haystack, needle)

strrstr_len (haystack, haystack_len, needle)

strsignal (signum)

strsplit (string, delimiter, max_tokens)

strsplit_set (string, delimiters, max_tokens)

strstr_len (haystack, haystack_len, needle)

strtod (nptr)

strup (string)

strv_contains (strv, str)

strv_equal (strv1, strv2)

strv_get_type ()

strv_length (str_array)

test_add_data_func (testpath, test_data, test_func)

test_add_data_func_full (testpath, test_data, test_func)

test_add_func (testpath, test_func)

test_assert_expected_messages_internal (domain, file, line, func)

test_bug (bug_uri_snippet)

test_bug_base (uri_pattern)

test_disable_crash_reporting ()

test_expect_message (log_domain, log_level, pattern)

test_fail ()

test_failed ()

test_get_dir (file_type)

test_get_path ()

test_incomplete (msg)

test_log_type_name (log_type)

test_queue_destroy (destroy_func, destroy_data)

test_queue_free (gfree_pointer)

test_rand_double ()

test_rand_double_range (range_start, range_end)

test_rand_int ()

test_rand_int_range (begin, end)

test_run ()

test_run_suite (suite)

test_set_nonfatal_assertions ()

test_skip (msg)

test_subprocess ()

test_summary (summary)

test_timer_elapsed ()

test_timer_last ()

test_timer_start ()

test_trap_assertions (domain, file, line, func, assertion_flags, pattern)

test_trap_fork (usec_timeout, test_trap_flags)

test_trap_has_passed ()

test_trap_reached_timeout ()

test_trap_subprocess (test_path, usec_timeout, test_flags)

thread_error_quark ()

thread_exit (retval)

thread_pool_get_max_idle_time ()

thread_pool_get_max_unused_threads ()

thread_pool_get_num_unused_threads ()

thread_pool_set_max_idle_time (interval)

thread_pool_set_max_unused_threads (max_threads)

thread_pool_stop_unused_threads ()

thread_self ()

thread_yield ()

threads_init ()

time_val_from_iso8601 (iso_date)

timeout_add (priority, interval, function, *data)

timeout_add_seconds (priority, interval, function, *data)

timeout_source_new (interval)

timeout_source_new_seconds (interval)

trash_stack_height (stack_p)

trash_stack_peek (stack_p)

trash_stack_pop (stack_p)

trash_stack_push (stack_p, data_p)

try_malloc (n_bytes)

try_malloc0 (n_bytes)

try_malloc0_n (n_blocks, n_block_bytes)

try_malloc_n (n_blocks, n_block_bytes)

try_realloc (mem, n_bytes)

try_realloc_n (mem, n_blocks, n_block_bytes)

ucs4_to_utf16 (str)

ucs4_to_utf8 (str)

unichar_break_type (c)

unichar_combining_class (uc)

unichar_compose (a, b)

unichar_decompose (ch)

unichar_digit_value (c)

unichar_fully_decompose (ch, compat, result_len)

unichar_get_mirror_char (ch)

unichar_get_script (ch)

unichar_isalnum (c)

unichar_isalpha (c)

unichar_iscntrl (c)

unichar_isdefined (c)

unichar_isdigit (c)

unichar_isgraph (c)

unichar_islower (c)

unichar_ismark (c)

unichar_isprint (c)

unichar_ispunct (c)

unichar_isspace (c)

unichar_istitle (c)

unichar_isupper (c)

unichar_iswide (c)

unichar_iswide_cjk (c)

unichar_isxdigit (c)

unichar_iszerowidth (c)

unichar_to_utf8 (c)

unichar_tolower (c)

unichar_totitle (c)

unichar_toupper (c)

unichar_type (c)

unichar_validate (ch)

unichar_xdigit_value (c)

unicode_canonical_decomposition (ch, result_len)

unicode_canonical_ordering (string)

unicode_script_from_iso15924 (iso15924)

unicode_script_to_iso15924 (script)

unix_error_quark ()

unix_fd_add_full (priority, fd, condition, function, *user_data)

unix_fd_source_new (fd, condition)

unix_get_passwd_entry (user_name)

unix_open_pipe (fds, flags)

unix_set_fd_nonblocking (fd, nonblock)

unix_signal_add (priority, signum, handler, *user_data)

unix_signal_add_full (*args)

unix_signal_source_new (signum)

unlink (filename)

unsetenv (variable)

uri_build (flags, scheme, userinfo, host, port, path, query, fragment)

uri_build_with_user (flags, scheme, user, password, auth_params, host, port, path, query, fragment)

uri_error_quark ()

uri_escape_bytes (unescaped, reserved_chars_allowed)

uri_escape_string (unescaped, reserved_chars_allowed, allow_utf8)

uri_is_valid (uri_string, flags)

uri_join (flags, scheme, userinfo, host, port, path, query, fragment)

uri_join_with_user (flags, scheme, user, password, auth_params, host, port, path, query, fragment)

uri_list_extract_uris (uri_list)

uri_parse (uri_string, flags)

uri_parse_params (params, length, separators, flags)

uri_parse_scheme (uri)

uri_peek_scheme (uri)

uri_resolve_relative (base_uri_string, uri_ref, flags)

uri_split (uri_ref, flags)

uri_split_network (uri_string, flags)

uri_split_with_user (uri_ref, flags)

uri_unescape_bytes (escaped_string, length, illegal_characters)

uri_unescape_segment (escaped_string, escaped_string_end, illegal_characters)

uri_unescape_string (escaped_string, illegal_characters)

usleep (microseconds)

utf16_to_ucs4 (str)

utf16_to_utf8 (str)

utf8_casefold (str, len)

utf8_collate (str1, str2)

utf8_collate_key (str, len)

utf8_collate_key_for_filename (str, len)

utf8_find_next_char (p, end)

utf8_find_prev_char (str, p)

utf8_get_char (p)

utf8_get_char_validated (p, max_len)

utf8_make_valid (str, len)

utf8_normalize (str, len, mode)

utf8_offset_to_pointer (str, offset)

utf8_pointer_to_offset (str, pos)

utf8_prev_char (p)

utf8_strchr (p, len, c)

utf8_strdown (str, len)

utf8_strlen (p, max)

utf8_strncpy (dest, src, n)

utf8_strrchr (p, len, c)

utf8_strreverse (str, len)

utf8_strup (str, len)

utf8_substring (str, start_pos, end_pos)

utf8_to_ucs4 (str, len)

utf8_to_ucs4_fast (str, len)

utf8_to_utf16 (str, len)

utf8_truncate_middle (string, truncate_length)

utf8_validate (str)

utf8_validate_len (str)

uuid_string_is_valid (str)

uuid_string_random ()

variant_get_gtype ()

variant_is_object_path (string)

variant_is_signature (string)

variant_parse (type, text, limit, endptr)

variant_parse_error_print_context (error, source_str)

variant_parse_error_quark ()

variant_parser_get_error_quark ()

variant_type_checked_ (arg0)

variant_type_string_get_depth_ (type_string)

variant_type_string_is_valid (type_string)

variant_type_string_scan (string, limit)

Details

GLib.access(filename, mode)[source]
Parameters:

  • filename (str) – a pathname in the GLib file name encoding (UTF-8 on Windows)

  • mode (int) – as in access()

Returns:

zero if the pathname refers to an existing file system object that has all the tested permissions, or -1 otherwise or on error.

Return type:

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

New in version 2.8.

GLib.aligned_alloc(n_blocks, n_block_bytes, alignment)[source]
Parameters:

  • n_blocks (int) – the number of blocks to allocate

  • n_block_bytes (int) – the size of each block in bytes

  • alignment (int) – the alignment to be enforced, which must be a positive power of 2 and a multiple of sizeof(void*)

Returns:

the allocated memory

Return type:

object or None

This function is similar to 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 GLib.aligned_free_sized() or GLib.aligned_free().

New in version 2.72.

GLib.aligned_alloc0(n_blocks, n_block_bytes, alignment)[source]
Parameters:

  • n_blocks (int) – the number of blocks to allocate

  • n_block_bytes (int) – the size of each block in bytes

  • alignment (int) – the alignment to be enforced, which must be a positive power of 2 and a multiple of sizeof(void*)

Returns:

the allocated, cleared memory

Return type:

object or None

This function is similar to GLib.aligned_alloc(), but it will also clear the allocated memory before returning it.

New in version 2.72.

GLib.aligned_free(mem)[source]
Parameters:

mem (object or None) – the memory to deallocate

Frees the memory allocated by GLib.aligned_alloc().

New in version 2.72.

GLib.aligned_free_sized(mem, alignment, size)[source]
Parameters:

  • mem (object or None) – the memory to free

  • alignment (int) – alignment of mem

  • size (int) – size of mem, in bytes

Frees the memory pointed to by mem, assuming it is has the given size and alignment.

If mem is 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 GLib.aligned_free() instead.

New in version 2.76.

GLib.ascii_digit_value(c)[source]
Parameters:

c (int) – an ASCII character

Returns:

If c is a decimal digit (according to g_ascii_isdigit()), its numeric value. Otherwise, -1.

Return type:

int

Determines the numeric value of a character as a decimal digit. Differs from GLib.unichar_digit_value() because it takes a str, so there’s no worry about sign extension if characters are signed.

GLib.ascii_dtostr(buffer, buf_len, d)[source]
Parameters:

  • buffer (str) – A buffer to place the resulting string in

  • buf_len (int) – The length of the buffer.

  • d (float) – The float to convert

Returns:

The pointer to the buffer with the converted string.

Return type:

str

Converts a float to a string, using the ‘.’ as decimal point.

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

GLib.ascii_formatd(buffer, buf_len, format, d)[source]
Parameters:

  • buffer (str) – A buffer to place the resulting string in

  • buf_len (int) – The length of the buffer.

  • format (str) – The printf()-style format to use for the code to use for converting

  • d (float) – The float to convert

Returns:

The pointer to the buffer with the converted string.

Return type:

str

Converts a float 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 float argument.

The returned buffer is guaranteed to be nul-terminated.

If you just want to want to serialize the value into a string, use GLib.ascii_dtostr().

GLib.ascii_strcasecmp(s1, s2)[source]
Parameters:

  • s1 (str) – string to compare with s2

  • s2 (str) – string to compare with s1

Returns:

0 if the strings match, a negative value if s1 < s2, or a positive value if s1 > s2.

Return type:

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

GLib.ascii_strdown(str, len)[source]
Parameters:

  • str (str) – a string

  • len (int) – length of str in bytes, or -1 if str is nul-terminated

Returns:

a newly-allocated string, with all the upper case characters in str converted to lower case, with semantics that exactly match GLib.ascii_tolower(). (Note that this is unlike the old GLib.strdown(), which modified the string in place.)

Return type:

str

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

GLib.ascii_string_to_signed(str, base, min, max)[source]
Parameters:

  • str (str) – a string

  • base (int) – base of a parsed number

  • min (int) – a lower bound (inclusive)

  • max (int) – an upper bound (inclusive)

Raises:

GLib.Error

Returns:

True if str was a number, otherwise False.

out_num:

a return location for a number

Return type:

(bool, out_num: 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 GLib.NumberParserError.INVALID. If the parsed number is out of bounds - GLib.NumberParserError.OUT_OF_BOUNDS.

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

New in version 2.54.

GLib.ascii_string_to_unsigned(str, base, min, max)[source]
Parameters:

  • str (str) – a string

  • base (int) – base of a parsed number

  • min (int) – a lower bound (inclusive)

  • max (int) – an upper bound (inclusive)

Raises:

GLib.Error

Returns:

True if str was a number, otherwise False.

out_num:

a return location for a number

Return type:

(bool, out_num: 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 GLib.NumberParserError.INVALID. If the parsed number is out of bounds - GLib.NumberParserError.OUT_OF_BOUNDS.

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

New in version 2.54.

GLib.ascii_strncasecmp(s1, s2, n)[source]
Parameters:

  • s1 (str) – string to compare with s2

  • s2 (str) – string to compare with s1

  • n (int) – number of characters to compare

Returns:

0 if the strings match, a negative value if s1 < s2, or a positive value if s1 > s2.

Return type:

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 strcasecmp() function, this only recognizes standard ASCII letters and ignores the locale, treating all non-ASCII characters as if they are not letters.

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

GLib.ascii_strtod(nptr)[source]
Parameters:

nptr (str) – the string to convert to a numeric value.

Returns:

the float value.

endptr:

if non-None, it returns the character after the last character used in the conversion.

Return type:

(float, endptr: str)

Converts a string to a float 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 float to a string in a locale-insensitive way, use 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.

GLib.ascii_strtoll(nptr, base)[source]
Parameters:

  • nptr (str) – the string to convert to a numeric value.

  • base (int) – to be used for the conversion, 2..36 or 0

Returns:

the #gint64 value or zero on error.

endptr:

if non-None, it returns the character after the last character used in the conversion.

Return type:

(int, endptr: 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, GLib.MAXINT64 or 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-None).

New in version 2.12.

GLib.ascii_strtoull(nptr, base)[source]
Parameters:

  • nptr (str) – the string to convert to a numeric value.

  • base (int) – to be used for the conversion, 2..36 or 0

Returns:

the #guint64 value or zero on error.

endptr:

if non-None, it returns the character after the last character used in the conversion.

Return type:

(int, endptr: 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 never result in a low return value, as the input could have a leading -.

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

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

New in version 2.2.

GLib.ascii_strup(str, len)[source]
Parameters:

  • str (str) – a string

  • len (int) – length of str in bytes, or -1 if str is nul-terminated

Returns:

a newly allocated string, with all the lower case characters in str converted to upper case, with semantics that exactly match GLib.ascii_toupper(). (Note that this is unlike the old GLib.strup(), which modified the string in place.)

Return type:

str

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

GLib.ascii_tolower(c)[source]
Parameters:

c (int) – any character

Returns:

the result of converting c to lower case. If c is not an ASCII upper case letter, c is returned unchanged.

Return type:

int

Convert a character to ASCII lower case.

Unlike the standard C library tolower() function, this only recognizes standard ASCII letters and ignores the locale, returning all non-ASCII characters unchanged, even if they are lower case letters in a particular character set. Also unlike the standard library function, this takes and returns a str, 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.

GLib.ascii_toupper(c)[source]
Parameters:

c (int) – any character

Returns:

the result of converting c to upper case. If c is not an ASCII lower case letter, c is returned unchanged.

Return type:

int

Convert a character to ASCII upper case.

Unlike the standard C library toupper() function, this only recognizes standard ASCII letters and ignores the locale, returning all non-ASCII characters unchanged, even if they are upper case letters in a particular character set. Also unlike the standard library function, this takes and returns a str, 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.

GLib.ascii_xdigit_value(c)[source]
Parameters:

c (int) – an ASCII character.

Returns:

If c is a hex digit (according to g_ascii_isxdigit()), its numeric value. Otherwise, -1.

Return type:

int

Determines the numeric value of a character as a hexadecimal digit. Differs from GLib.unichar_xdigit_value() because it takes a str, so there’s no worry about sign extension if characters are signed.

GLib.assert_warning(log_domain, file, line, pretty_function, expression)[source]
Parameters:

  • log_domain (str) –

  • file (str) –

  • line (int) –

  • pretty_function (str) –

  • expression (str) –

GLib.assertion_message(domain, file, line, func, message)[source]
Parameters:

  • domain (str) –

  • file (str) –

  • line (int) –

  • func (str) –

  • message (str) –

GLib.assertion_message_cmpint(domain, file, line, func, expr, arg1, cmp, arg2, numtype)[source]
Parameters:

  • domain (str) –

  • file (str) –

  • line (int) –

  • func (str) –

  • expr (str) –

  • arg1 (int) –

  • cmp (str) –

  • arg2 (int) –

  • numtype (int) –

GLib.assertion_message_cmpstr(domain, file, line, func, expr, arg1, cmp, arg2)[source]
Parameters:

  • domain (str) –

  • file (str) –

  • line (int) –

  • func (str) –

  • expr (str) –

  • arg1 (str) –

  • cmp (str) –

  • arg2 (str) –

GLib.assertion_message_cmpstrv(domain, file, line, func, expr, arg1, arg2, first_wrong_idx)[source]
Parameters:

  • domain (str) –

  • file (str) –

  • line (int) –

  • func (str) –

  • expr (str) –

  • arg1 (str) –

  • arg2 (str) –

  • first_wrong_idx (int) –

GLib.assertion_message_error(domain, file, line, func, expr, error, error_domain, error_code)[source]
Parameters:
GLib.atexit(func)[source]
Parameters:

func (GLib.VoidFunc) – the function to call on normal program termination.

Specifies a function to be called at normal program termination.

Since GLib 2.8.2, on Windows 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 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 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 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 GLib.atexit() (or atexit()) except in the main executable of a program.

Deprecated since version 2.32: It is best to avoid GLib.atexit().

GLib.atomic_int_add(atomic, val)[source]
Parameters:

  • atomic (int) – a pointer to a int or int

  • val (int) – the value to add

Returns:

the value of atomic before the add, signed

Return type:

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

New in version 2.4.

GLib.atomic_int_and(atomic, val)[source]
Parameters:

  • atomic (int) – a pointer to a int or int

  • val (int) – the value to ‘and’

Returns:

the value of atomic before the operation, unsigned

Return type:

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.

New in version 2.30.

GLib.atomic_int_compare_and_exchange(atomic, oldval, newval)[source]
Parameters:

  • atomic (int) – a pointer to a int or int

  • oldval (int) – the value to compare with

  • newval (int) – the value to conditionally replace with

Returns:

True if the exchange took place

Return type:

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.

New in version 2.4.

GLib.atomic_int_compare_and_exchange_full(atomic, oldval, newval)[source]
Parameters:

  • atomic (int) – a pointer to a int or int

  • oldval (int) – the value to compare with

  • newval (int) – the value to conditionally replace with

Returns:

True if the exchange took place

preval:

the contents of atomic before this operation

Return type:

(bool, preval: 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 GLib.atomic_int_compare_and_exchange()

New in version 2.74.

GLib.atomic_int_dec_and_test(atomic)[source]
Parameters:

atomic (int) – a pointer to a int or int

Returns:

True if the resultant value is zero

Return type:

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.

New in version 2.4.

GLib.atomic_int_exchange(atomic, newval)[source]
Parameters:

  • atomic (int) – a pointer to a int or int

  • newval (int) – the value to replace with

Returns:

the value of atomic before the exchange, signed

Return type:

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.

New in version 2.74.

GLib.atomic_int_exchange_and_add(atomic, val)[source]
Parameters:

  • atomic (int) – a pointer to a int

  • val (int) – the value to add

Returns:

the value of atomic before the add, signed

Return type:

int

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

New in version 2.4.

Deprecated since version 2.30: Use GLib.atomic_int_add() instead.

GLib.atomic_int_get(atomic)[source]
Parameters:

atomic (int) – a pointer to a int or int

Returns:

the value of the integer

Return type:

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.

New in version 2.4.

GLib.atomic_int_inc(atomic)[source]
Parameters:

atomic (int) – a pointer to a int or int

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.

New in version 2.4.

GLib.atomic_int_or(atomic, val)[source]
Parameters:

  • atomic (int) – a pointer to a int or int

  • val (int) – the value to ‘or’

Returns:

the value of atomic before the operation, unsigned

Return type:

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.

New in version 2.30.

GLib.atomic_int_set(atomic, newval)[source]
Parameters:

  • atomic (int) – a pointer to a int or int

  • newval (int) – a new value to store

Sets the value of atomic to newval.

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

While atomic has a volatile qualifier, this is a historical artifact and the pointer passed to it should not be volatile.

New in version 2.4.

GLib.atomic_int_xor(atomic, val)[source]
Parameters:

  • atomic (int) – a pointer to a int or int

  • val (int) – the value to ‘xor’

Returns:

the value of atomic before the operation, unsigned

Return type:

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.

New in version 2.30.

GLib.atomic_pointer_add(atomic, val)[source]
Parameters:

  • atomic (object) – a pointer to a object-sized value

  • val (int) – the value to add

Returns:

the value of atomic before the add, signed

Return type:

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.

New in version 2.30.

GLib.atomic_pointer_and(atomic, val)[source]
Parameters:

  • atomic (object) – a pointer to a object-sized value

  • val (int) – the value to ‘and’

Returns:

the value of atomic before the operation, unsigned

Return type:

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.

New in version 2.30.

GLib.atomic_pointer_compare_and_exchange(atomic, oldval, newval)[source]
Parameters:

  • atomic (object) – a pointer to a object-sized value

  • oldval (object or None) – the value to compare with

  • newval (object or None) – the value to conditionally replace with

Returns:

True if the exchange took place

Return type:

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.

New in version 2.4.

GLib.atomic_pointer_compare_and_exchange_full(atomic, oldval, newval)[source]
Parameters:

  • atomic (object) – a pointer to a object-sized value

  • oldval (object or None) – the value to compare with

  • newval (object or None) – the value to conditionally replace with

Returns:

True if the exchange took place

preval:

the contents of atomic before this operation

Return type:

(bool, preval: object)

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

New in version 2.74.

GLib.atomic_pointer_exchange(atomic, newval)[source]
Parameters:
Returns:

the value of atomic before the exchange

Return type:

object or 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.

New in version 2.74.

GLib.atomic_pointer_get(atomic)[source]
Parameters:

atomic (object) – a pointer to a object-sized value

Returns:

the value of the pointer

Return type:

object or 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.

New in version 2.4.

GLib.atomic_pointer_or(atomic, val)[source]
Parameters:

  • atomic (object) – a pointer to a object-sized value

  • val (int) – the value to ‘or’

Returns:

the value of atomic before the operation, unsigned

Return type:

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.

New in version 2.30.

GLib.atomic_pointer_set(atomic, newval)[source]
Parameters:

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.

New in version 2.4.

GLib.atomic_pointer_xor(atomic, val)[source]
Parameters:

  • atomic (object) – a pointer to a object-sized value

  • val (int) – the value to ‘xor’

Returns:

the value of atomic before the operation, unsigned

Return type:

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.

New in version 2.30.

GLib.atomic_rc_box_acquire(mem_block)[source]
Parameters:

mem_block (object) – a pointer to reference counted data

Returns:

a pointer to the data, with its reference count increased

Return type:

object

Atomically acquires a reference on the data pointed by mem_block.

New in version 2.58.

GLib.atomic_rc_box_alloc(block_size)[source]
Parameters:

block_size (int) – the size of the allocation, must be greater than 0

Returns:

a pointer to the allocated memory

Return type:

object

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.

New in version 2.58.

GLib.atomic_rc_box_alloc0(block_size)[source]
Parameters:

block_size (int) – the size of the allocation, must be greater than 0

Returns:

a pointer to the allocated memory

Return type:

object

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.

New in version 2.58.

GLib.atomic_rc_box_dup(block_size, mem_block)[source]
Parameters:

  • block_size (int) – the number of bytes to copy, must be greater than 0

  • mem_block (object) – the memory to copy

Returns:

a pointer to the allocated memory

Return type:

object

Allocates a new block of data with atomic reference counting semantics, and copies block_size bytes of mem_block into it.

New in version 2.58.

GLib.atomic_rc_box_get_size(mem_block)[source]
Parameters:

mem_block (object) – a pointer to reference counted data

Returns:

the size of the data, in bytes

Return type:

int

Retrieves the size of the reference counted data pointed by mem_block.

New in version 2.58.

GLib.atomic_rc_box_release(mem_block)[source]
Parameters:

mem_block (object) – a pointer to reference counted data

Atomically releases a reference on the data pointed by mem_block.

If the reference was the last one, it will free the resources allocated for mem_block.

New in version 2.58.

GLib.atomic_rc_box_release_full(mem_block, clear_func)[source]
Parameters:

  • mem_block (object) – a pointer to reference counted data

  • clear_func (GLib.DestroyNotify) – a function to call when clearing the data

Atomically releases a reference on the data pointed by mem_block.

If the reference was the last one, it will call clear_func to clear the contents of mem_block, and then will free the resources allocated for mem_block.

New in version 2.58.

GLib.atomic_ref_count_compare(arc, val)[source]
Parameters:

  • arc (int) – the address of an atomic reference count variable

  • val (int) – the value to compare

Returns:

True if the reference count is the same as the given value

Return type:

bool

Atomically compares the current value of arc with val.

New in version 2.58.

GLib.atomic_ref_count_dec(arc)[source]
Parameters:

arc (int) – the address of an atomic reference count variable

Returns:

True if the reference count reached 0, and False otherwise

Return type:

bool

Atomically decreases the reference count.

If True is returned, the reference count reached 0. After this point, arc is an undefined state and must be reinitialized with GLib.atomic_ref_count_init() to be used again.

New in version 2.58.

GLib.atomic_ref_count_inc(arc)[source]
Parameters:

arc (int) – the address of an atomic reference count variable

Atomically increases the reference count.

New in version 2.58.

GLib.atomic_ref_count_init(arc)[source]
Parameters:

arc (int) – the address of an atomic reference count variable

Initializes a reference count variable to 1.

New in version 2.58.

GLib.base64_decode(text)[source]
Parameters:

text (str) – zero-terminated string with base64 text to decode

Returns:

newly allocated buffer containing the binary data that text represents. The returned buffer must be freed with GLib.free().

Return type:

bytes

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.

New in version 2.12.

GLib.base64_decode_inplace(text)[source]
Parameters:

text (bytes) – zero-terminated string with base64 text to decode

Returns:

The binary data that text responds. This pointer is the same as the input text.

text:

zero-terminated string with base64 text to decode

Return type:

(int, text: bytes)

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

New in version 2.20.

GLib.base64_encode(data)[source]
Parameters:

data (bytes or None) – the binary data to encode

Returns:

a newly allocated, zero-terminated Base-64 encoded string representing data. The returned string must be freed with GLib.free().

Return type:

str

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

New in version 2.12.

GLib.base64_encode_close(break_lines, state, save)[source]
Parameters:
Returns:

The number of bytes of output that was written

out:

pointer to destination buffer

state:

Saved state from GLib.base64_encode_step()

save:

Saved state from GLib.base64_encode_step()

Return type:

(int, out: bytes, state: int, save: int)

Flush the status from a sequence of calls to 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.

New in version 2.12.

GLib.base64_encode_step(in_, break_lines, state, save)[source]
Parameters:

  • in (bytes) – the binary data to encode

  • break_lines (bool) – whether to break long lines

  • state (int) – Saved state between steps, initialize to 0

  • save (int) – Saved state between steps, initialize to 0

Returns:

The number of bytes of output that was written

out:

pointer to destination buffer

state:

Saved state between steps, initialize to 0

save:

Saved state between steps, initialize to 0

Return type:

(int, out: bytes, state: int, save: 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 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.

New in version 2.12.

GLib.basename(file_name)[source]
Parameters:

file_name (str) – the name of the file

Returns:

the name of the file without any leading directory components

Return type:

str

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

Deprecated since version 2.2: Use GLib.path_get_basename() instead, but notice that GLib.path_get_basename() allocates new memory for the returned string, unlike this function which returns a pointer into the argument.

GLib.bit_lock(address, lock_bit)[source]
Parameters:

  • address (int) – a pointer to an integer

  • lock_bit (int) – a bit value between 0 and 31

Sets the indicated lock_bit in address. If the bit is already set, this call will block until 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.

New in version 2.24.

GLib.bit_nth_lsf(mask, nth_bit)[source]
Parameters:

  • mask (int) – a int containing flags

  • nth_bit (int) – the index of the bit to start the search from

Returns:

the index of the first bit set which is higher than nth_bit, or -1 if no higher bits are set

Return type:

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(int) * 8 - 1 (31 or 63, usually). To start searching from the 0th bit, set nth_bit to -1.

GLib.bit_nth_msf(mask, nth_bit)[source]
Parameters:

  • mask (int) – a int containing flags

  • nth_bit (int) – the index of the bit to start the search from

Returns:

the index of the first bit set which is lower than nth_bit, or -1 if no lower bits are set

Return type:

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(int) * 8 - 1 (31 or 63, usually). To start searching from the last bit, set nth_bit to -1 or GLib.SIZEOF_LONG * 8.

GLib.bit_storage(number)[source]
Parameters:

number (int) – a int

Returns:

the number of bits used to hold number

Return type:

int

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

GLib.bit_trylock(address, lock_bit)[source]
Parameters:

  • address (int) – a pointer to an integer

  • lock_bit (int) – a bit value between 0 and 31

Returns:

True if the lock was acquired

Return type:

bool

Sets the indicated lock_bit in address, returning True if successful. If the bit is already set, returns False immediately.

Attempting to lock on two different bits within the same integer is not supported.

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

This function accesses address atomically. All other accesses to address must be atomic in order for this function to work reliably. While address has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

New in version 2.24.

GLib.bit_unlock(address, lock_bit)[source]
Parameters:

  • address (int) – a pointer to an integer

  • lock_bit (int) – a bit value between 0 and 31

Clears the indicated lock_bit in address. If another thread is currently blocked in 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.

New in version 2.24.

GLib.bookmark_file_error_quark()[source]
Return type:

int

GLib.build_filenamev(args)[source]
Parameters:

args ([str]) – None-terminated array of strings containing the path elements.

Returns:

the newly allocated path

Return type:

str

Creates a filename from a vector of elements using the correct separator for the current platform.

This function behaves exactly like g_build_filename(), but takes the path elements as a string array, instead of varargs. This function is mainly meant for language bindings.

If you are building a path programmatically you may want to use GLib.PathBuf instead.

New in version 2.8.

GLib.build_pathv(separator, args)[source]
Parameters:

  • separator (str) – a string used to separator the elements of the path.

  • args ([str]) – None-terminated array of strings containing the path elements.

Returns:

a newly-allocated string that must be freed with GLib.free().

Return type:

str

Behaves exactly like g_build_path(), but takes the path elements as a string array, instead of variadic arguments.

This function is mainly meant for language bindings.

New in version 2.8.

GLib.byte_array_free(array, free_segment)[source]
Parameters:
Returns:

the element data if free_segment is False, otherwise None. The element data should be freed using GLib.free().

Return type:

int

Frees the memory allocated by the GLib.ByteArray. If free_segment is True it frees the actual byte data. If the reference count of array is greater than one, the GLib.ByteArray wrapper is preserved but the size of array will be set to zero.

GLib.byte_array_free_to_bytes(array)[source]
Parameters:

array (bytes) – a GLib.ByteArray

Returns:

a new immutable GLib.Bytes representing same byte data that was in the array

Return type:

GLib.Bytes

Transfers the data from the GLib.ByteArray into a new immutable GLib.Bytes.

The GLib.ByteArray is freed unless the reference count of array is greater than one, the GLib.ByteArray wrapper is preserved but the size of array will be set to zero.

This is identical to using GLib.Bytes.new_take() and GLib.ByteArray.free() together.

New in version 2.32.

GLib.byte_array_new()[source]
Returns:

the new GLib.ByteArray

Return type:

bytes

Creates a new GLib.ByteArray with a reference count of 1.

GLib.byte_array_new_take(data)[source]
Parameters:

data (bytes) – byte data for the array

Returns:

a new GLib.ByteArray

Return type:

bytes

Creates a byte array containing the data. After this call, data belongs to the GLib.ByteArray and may no longer be modified by the caller. The memory of data has to be dynamically allocated and will eventually be freed with GLib.free().

Do not use it if len is greater than %G_MAXUINT. GLib.ByteArray stores the length of its data in int, which may be shorter than #gsize.

New in version 2.32.

GLib.byte_array_steal(array)[source]
Parameters:

array (bytes) – a GLib.ByteArray.

Returns:

the element data, which should be freed using GLib.free().

len:

pointer to retrieve the number of elements of the original array

Return type:

(int, len: int)

Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller.

New in version 2.64.

GLib.byte_array_unref(array)[source]
Parameters:

array (bytes) – A GLib.ByteArray

Atomically decrements the reference count of array by one. If the reference count drops to 0, all memory allocated by the array is released. This function is thread-safe and may be called from any thread.

New in version 2.22.

GLib.canonicalize_filename(filename, relative_to)[source]
Parameters:

  • filename (str) – the name of the file

  • relative_to (str or None) – the relative directory, or None to use the current working directory

Returns:

a newly allocated string with the canonical file path

Return type:

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 None. If relative_to is None, it’ll fallback to 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.

New in version 2.58.

GLib.chdir(path)[source]
Parameters:

path (str) – a pathname in the GLib file name encoding (UTF-8 on Windows)

Returns:

0 on success, -1 if an error occurred.

Return type:

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

New in version 2.8.

GLib.check_version(required_major, required_minor, required_micro)[source]
Parameters:

  • required_major (int) – the required major version

  • required_minor (int) – the required minor version

  • required_micro (int) – the required micro version

Returns:

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.

Return type:

str or None

Checks that the GLib library in use is compatible with the given version.

Generally you would pass in the constants GLib.MAJOR_VERSION, GLib.MINOR_VERSION, GLib.MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GLib the application or module was compiled against.

Compatibility is defined by two things: first the version of the running library is newer than the version @required_major.required_minor.@required_micro. Second the running library must be binary compatible with the version @required_major.@required_minor.@required_micro (same major version.)

New in version 2.6.

GLib.checksum_type_get_length(checksum_type)[source]
Parameters:

checksum_type (GLib.ChecksumType) – a GLib.ChecksumType

Returns:

the checksum length, or -1 if checksum_type is not supported.

Return type:

int

Gets the length in bytes of digests of type checksum_type

New in version 2.16.

GLib.child_watch_add(priority, pid, function, *data)[source]
Parameters:

  • priority – the priority of the idle source. Typically this will be in the range between GLib.PRIORITY_DEFAULT_IDLE and GLib.PRIORITY_HIGH_IDLE.

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

  • function – function to call

  • data – data to pass to function

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

If you obtain pid from GLib.spawn_async() or GLib.spawn_async_with_pipes() you will need to pass GLib.SpawnFlags.DO_NOT_REAP_CHILD as flag to the spawn function for the child watching to work.

In many programs, you will want to call GLib.spawn_check_wait_status() in the callback to determine whether or not the child exited successfully.

Also, note that on platforms where #GPid must be explicitly closed (see GLib.spawn_close_pid()) pid must not be closed while the source is still active. Typically, you should invoke 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 GLib.child_watch_source_new() apply to this function.

This internally creates a main loop source using GLib.child_watch_source_new() and attaches it to the main loop context using GLib.Source.attach(). You can do these steps manually if you need greater control.

New in version 2.4.

GLib.child_watch_source_new(pid)[source]
Parameters:

pid (int) – 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).

Returns:

the newly-created child watch source

Return type:

GLib.Source

Creates a new child_watch source.

The source will not initially be associated with any GLib.MainContext and must be added to one with GLib.Source.attach() before it will be executed.

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

Note that on platforms where #GPid must be explicitly closed (see GLib.spawn_close_pid()) pid must not be closed while the source is still active. Typically, you will want to call 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 GLib.MainContext is acquired.

  • Before 2.78, even after destroying the 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.

New in version 2.4.

GLib.clear_error()[source]
Raises:

GLib.Error

If err or err is None, does nothing. Otherwise, calls GLib.Error.free() on err and sets err to None.

GLib.close(fd)[source]
Parameters:

fd (int) – A file descriptor

Raises:

GLib.Error

Returns:

True on success, False if there was an error.

Return type:

bool

This wraps the close() call. In case of error, %errno will be preserved, but the error will also be stored as a GLib.Error in error. In case of success, %errno is undefined.

Besides using 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 None and fd is a valid open file descriptor. This makes it safe to call from a signal handler or a GLib.SpawnChildSetupFunc under those conditions. See signal(7)) and signal-safety(7)) for more details.

New in version 2.36.

GLib.compute_checksum_for_bytes(checksum_type, data)[source]
Parameters:
Returns:

the digest of the binary data as a string in hexadecimal, or None if GLib.Checksum.new() fails for checksum_type. The returned string should be freed with GLib.free() when done using it.

Return type:

str or None

Computes the checksum for a binary data. This is a convenience wrapper for GLib.Checksum.new(), GLib.Checksum.get_string() and GLib.Checksum.free().

The hexadecimal string returned will be in lower case.

New in version 2.34.

GLib.compute_checksum_for_data(checksum_type, data)[source]
Parameters:
Returns:

the digest of the binary data as a string in hexadecimal, or None if GLib.Checksum.new() fails for checksum_type. The returned string should be freed with GLib.free() when done using it.

Return type:

str or None

Computes the checksum for a binary data of length. This is a convenience wrapper for GLib.Checksum.new(), GLib.Checksum.get_string() and GLib.Checksum.free().

The hexadecimal string returned will be in lower case.

New in version 2.16.

GLib.compute_checksum_for_string(checksum_type, str, length)[source]
Parameters:
Returns:

the checksum as a hexadecimal string, or None if GLib.Checksum.new() fails for checksum_type. The returned string should be freed with GLib.free() when done using it.

Return type:

str or None

Computes the checksum of a string.

The hexadecimal string returned will be in lower case.

New in version 2.16.

GLib.compute_hmac_for_bytes(digest_type, key, data)[source]
Parameters:
Returns:

the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with GLib.free() when done using it.

Return type:

str

Computes the HMAC for a binary data. This is a convenience wrapper for g_hmac_new(), GLib.Hmac.get_string() and GLib.Hmac.unref().

The hexadecimal string returned will be in lower case.

New in version 2.50.

GLib.compute_hmac_for_data(digest_type, key, data)[source]
Parameters:
Returns:

the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with GLib.free() when done using it.

Return type:

str

Computes the HMAC for a binary data of length. This is a convenience wrapper for g_hmac_new(), GLib.Hmac.get_string() and GLib.Hmac.unref().

The hexadecimal string returned will be in lower case.

New in version 2.30.

GLib.compute_hmac_for_string(digest_type, key, str, length)[source]
Parameters:

  • digest_type (GLib.ChecksumType) – a GLib.ChecksumType to use for the HMAC

  • key (bytes) – the key to use in the HMAC

  • str (str) – the string to compute the HMAC for

  • length (int) – the length of the string, or -1 if the string is nul-terminated

Returns:

the HMAC as a hexadecimal string. The returned string should be freed with GLib.free() when done using it.

Return type:

str

Computes the HMAC for a string.

The hexadecimal string returned will be in lower case.

New in version 2.30.

GLib.convert(str, to_codeset, from_codeset)[source]
Parameters:

  • str (bytes) – the string to convert.

  • to_codeset (str) – name of character set into which to convert str

  • from_codeset (str) – character set of str.

Raises:

GLib.Error

Returns:

If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with GLib.free(). Otherwise None and error will be set.

bytes_read:

location to store the number of bytes in the input string that were successfully converted, or None. Even if the conversion was successful, this may be less than len if there were partial characters at the end of the input. If the error GLib.ConvertError.ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence.

Return type:

(bytes, bytes_read: int)

Converts a string from one character set to another.

Note that you should use g_iconv() for streaming conversions. Despite the fact that bytes_read can return information about partial characters, the g_convert_… functions are not generally suitable for streaming. If the underlying converter maintains internal state, then this won’t be preserved across successive calls to GLib.convert(), g_convert_with_iconv() or 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 GLib.str_to_ascii() instead.

GLib.convert_error_quark()[source]
Return type:

int

GLib.convert_with_fallback(str, to_codeset, from_codeset, fallback)[source]
Parameters:

  • str (bytes) – the string to convert.

  • to_codeset (str) – name of character set into which to convert str

  • from_codeset (str) – character set of str.

  • fallback (str) – UTF-8 string to use in place of characters not present in the target encoding. (The string must be representable in the target encoding). If None, characters not in the target encoding will be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.

Raises:

GLib.Error

Returns:

If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with GLib.free(). Otherwise None and error will be set.

bytes_read:

location to store the number of bytes in the input string that were successfully converted, or None. Even if the conversion was successful, this may be less than len if there were partial characters at the end of the input.

Return type:

(bytes, bytes_read: 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 g_iconv() for streaming conversions. Despite the fact that bytes_read can return information about partial characters, the g_convert_… functions are not generally suitable for streaming. If the underlying converter maintains internal state, then this won’t be preserved across successive calls to GLib.convert(), g_convert_with_iconv() or 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.)

GLib.datalist_foreach(datalist, func, *user_data)[source]
Parameters:

Calls the given function for each data element of the datalist. The function is called with each data element’s #GQuark id and data, together with the given user_data parameter. Note that this function is NOT thread-safe. So unless datalist can be protected from any modifications during invocation of this function, it should not be called.

func can make changes to datalist, but the iteration will not reflect changes made during the GLib.datalist_foreach() call, other than skipping over elements that are removed.

GLib.datalist_get_data(datalist, key)[source]
Parameters:

  • datalist (GLib.Data) – a datalist.

  • key (str) – the string identifying a data element.

Returns:

the data element, or None if it is not found.

Return type:

object or None

Gets a data element, using its string identifier. This is slower than GLib.datalist_id_get_data() because it compares strings.

GLib.datalist_get_flags(datalist)[source]
Parameters:

datalist (GLib.Data) – pointer to the location that holds a list

Returns:

the flags of the datalist

Return type:

int

Gets flags values packed in together with the datalist. See GLib.datalist_set_flags().

New in version 2.8.

GLib.datalist_id_get_data(datalist, key_id)[source]
Parameters:

  • datalist (GLib.Data) – a datalist.

  • key_id (int) – the #GQuark identifying a data element.

Returns:

the data element, or None if it is not found.

Return type:

object or None

Retrieves the data element corresponding to key_id.

GLib.datalist_id_remove_multiple(datalist, keys)[source]
Parameters:

  • datalist (GLib.Data) – a datalist

  • keys ([int]) – keys to remove

Removes multiple keys from a datalist.

This is more efficient than calling g_datalist_id_remove_data() multiple times in a row.

New in version 2.74.

GLib.datalist_set_flags(datalist, flags)[source]
Parameters:

  • datalist (GLib.Data) – pointer to the location that holds a list

  • flags (int) – the flags to turn on. The values of the flags are restricted by 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.

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

New in version 2.8.

GLib.datalist_unset_flags(datalist, flags)[source]
Parameters:

  • datalist (GLib.Data) – pointer to the location that holds a list

  • flags (int) – the flags to turn off. The values of the flags are restricted by 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.

Turns off flag values for a data list. See GLib.datalist_unset_flags()

New in version 2.8.

GLib.dataset_destroy(dataset_location)[source]
Parameters:

dataset_location (object) – the location identifying the dataset.

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

GLib.dataset_foreach(dataset_location, func, *user_data)[source]
Parameters:

  • dataset_location (object) – the location identifying the dataset.

  • func (GLib.DataForeachFunc) – the function to call for each data element.

  • user_data (object or None) – user data to pass to the function.

Calls the given function for each data element which is associated with the given location. Note that this function is NOT thread-safe. So unless 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 GLib.dataset_foreach() call, other than skipping over elements that are removed.

GLib.dataset_id_get_data(dataset_location, key_id)[source]
Parameters:

  • dataset_location (object) – the location identifying the dataset.

  • key_id (int) – the #GQuark id to identify the data element.

Returns:

the data element corresponding to the #GQuark, or None if it is not found.

Return type:

object or None

Gets the data element corresponding to a #GQuark.

GLib.date_get_days_in_month(month, year)[source]
Parameters:
Returns:

number of days in month during the year

Return type:

int

Returns the number of days in a month, taking leap years into account.

GLib.date_get_monday_weeks_in_year(year)[source]
Parameters:

year (int) – a year

Returns:

number of Mondays in the year

Return type:

int

Returns the number of weeks in the year, where weeks are taken to start on Monday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it’s a leap year. This function is basically telling you how many Mondays are in the year, i.e. there are 53 Mondays if one of the extra days happens to be a Monday.)

GLib.date_get_sunday_weeks_in_year(year)[source]
Parameters:

year (int) – year to count weeks in

Returns:

the number of weeks in year

Return type:

int

Returns the number of weeks in the year, where weeks are taken to start on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it’s a leap year. This function is basically telling you how many Sundays are in the year, i.e. there are 53 Sundays if one of the extra days happens to be a Sunday.)

GLib.date_is_leap_year(year)[source]
Parameters:

year (int) – year to check

Returns:

True if the year is a leap year

Return type:

bool

Returns True if the year is a leap year.

For the purposes of this function, leap year is every year divisible by 4 unless that year is divisible by 100. If it is divisible by 100 it would be a leap year only if that year is also divisible by 400.

GLib.date_strftime(s, slen, format, date)[source]
Parameters:
Returns:

number of characters written to the buffer, or 0 the buffer was too small

Return type:

int

Generates a printed representation of the date, in a locale-specific way. Works just like the platform’s C library strftime() function, but only accepts date-related formats; time-related formats give undefined results. Date must be valid. Unlike strftime() (which uses the locale encoding), works on a UTF-8 format string and stores a UTF-8 result.

This function does not provide any conversion specifiers in addition to those implemented by the platform’s C library. For example, don’t expect that using GLib.Date.strftime() would make the \%F provided by the C99 strftime() work on Windows where the C library only complies to C89.

GLib.date_valid_day(day)[source]
Parameters:

day (int) – day to check

Returns:

True if the day is valid

Return type:

bool

Returns True if the day of the month is valid (a day is valid if it’s between 1 and 31 inclusive).

GLib.date_valid_dmy(day, month, year)[source]
Parameters:
Returns:

True if the date is a valid one

Return type:

bool

Returns True if the day-month-year triplet forms a valid, existing day in the range of days GLib.Date understands (Year 1 or later, no more than a few thousand years in the future).

GLib.date_valid_julian(julian_date)[source]
Parameters:

julian_date (int) – Julian day to check

Returns:

True if the Julian day is valid

Return type:

bool

Returns True if the Julian day is valid. Anything greater than zero is basically a valid Julian, though there is a 32-bit limit.

GLib.date_valid_month(month)[source]
Parameters:

month (GLib.DateMonth) – month

Returns:

True if the month is valid

Return type:

bool

Returns True if the month value is valid. The 12 GLib.DateMonth enumeration values are the only valid months.

GLib.date_valid_weekday(weekday)[source]
Parameters:

weekday (GLib.DateWeekday) – weekday

Returns:

True if the weekday is valid

Return type:

bool

Returns True if the weekday is valid. The seven GLib.DateWeekday enumeration values are the only valid weekdays.

GLib.date_valid_year(year)[source]
Parameters:

year (int) – year

Returns:

True if the year is valid

Return type:

bool

Returns True if the year is valid. Any year greater than 0 is valid, though there is a 16-bit limit to what GLib.Date will understand.

GLib.dcgettext(domain, msgid, category)[source]
Parameters:

  • domain (str or None) – the translation domain to use, or None to use the domain set with textdomain()

  • msgid (str) – message to translate

  • category (int) – a locale category

Returns:

the translated string for the given locale category

Return type:

str

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

New in version 2.26.

GLib.dgettext(domain, msgid)[source]
Parameters:

  • domain (str or None) – the translation domain to use, or None to use the domain set with textdomain()

  • msgid (str) – message to translate

Returns:

The translated string

Return type:

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

New in version 2.18.

GLib.dir_make_tmp(tmpl)[source]
Parameters:

tmpl (str or None) – Template for directory name, as in g_mkdtemp(), basename only, or None for a default template

Raises:

GLib.Error

Returns:

The actual name used. This string should be freed with GLib.free() when not needed any longer and is is in the GLib file name encoding. In case of errors, None is returned and error will be set.

Return type:

str

Creates a subdirectory in the preferred directory for temporary files (as returned by 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 g_mkstemp(). However, unlike these functions, the template should only be a basename, no directory components are allowed. If template is None, a default template is used.

Note that in contrast to g_mkdtemp() (and mkdtemp()) tmpl is not modified, and might thus be a read-only literal string.

New in version 2.30.

GLib.direct_equal(v1, v2)[source]
Parameters:
Returns:

True if the two keys match.

Return type:

bool

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

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

GLib.direct_hash(v)[source]
Parameters:

v (object or None) – a object key

Returns:

a hash value corresponding to the key.

Return type:

int

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

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

GLib.dngettext(domain, msgid, msgid_plural, n)[source]
Parameters:

  • domain (str or None) – the translation domain to use, or None to use the domain set with textdomain()

  • msgid (str) – message to translate

  • msgid_plural (str) – plural form of the message

  • n (int) – the quantity for which translation is needed

Returns:

The translated string

Return type:

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

New in version 2.18.

GLib.double_equal(v1, v2)[source]
Parameters:
Returns:

True if the two keys match.

Return type:

bool

Compares the two float values being pointed to and returns True if they are equal. It can be passed to g_hash_table_new() as the key_equal_func parameter, when using non-None pointers to doubles as keys in a GLib.HashTable.

New in version 2.22.

GLib.double_hash(v)[source]
Parameters:

v (object) – a pointer to a float key

Returns:

a hash value corresponding to the key.

Return type:

int

Converts a pointer to a float to a hash value. It can be passed to g_hash_table_new() as the hash_func parameter, It can be passed to g_hash_table_new() as the hash_func parameter, when using non-None pointers to doubles as keys in a GLib.HashTable.

New in version 2.22.

GLib.dpgettext(domain, msgctxtid, msgidoffset)[source]
Parameters:

  • domain (str or None) – the translation domain to use, or None to use the domain set with textdomain()

  • msgctxtid (str) – a combined message context and message id, separated by a \004 character

  • msgidoffset (int) – the offset of the message id in msgctxid

Returns:

The translated string

Return type:

str

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

New in version 2.16.

GLib.dpgettext2(domain, context, msgid)[source]
Parameters:

  • domain (str or None) – the translation domain to use, or None to use the domain set with textdomain()

  • context (str) – the message context

  • msgid (str) – the message

Returns:

The translated string

Return type:

str

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

New in version 2.18.

GLib.environ_getenv(envp, variable)[source]
Parameters:

  • envp ([str] or None) – an environment list (eg, as returned from GLib.get_environ()), or None for an empty environment list

  • variable (str) – the environment variable to get

Returns:

the value of the environment variable, or 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.

Return type:

str or None

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

New in version 2.32.

GLib.environ_setenv(envp, variable, value, overwrite)[source]
Parameters:

  • envp ([str] or None) – an environment list that can be freed using GLib.strfreev() (e.g., as returned from GLib.get_environ()), or None for an empty environment list

  • variable (str) – the environment variable to set, must not contain ‘=’

  • value (str) – the value for to set the variable to

  • overwrite (bool) – whether to change the variable if it already exists

Returns:

the updated environment list. Free it using GLib.strfreev().

Return type:

[str]

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

New in version 2.32.

GLib.environ_unsetenv(envp, variable)[source]
Parameters:

  • envp ([str] or None) – an environment list that can be freed using GLib.strfreev() (e.g., as returned from GLib.get_environ()), or None for an empty environment list

  • variable (str) – the environment variable to remove, must not contain ‘=’

Returns:

the updated environment list. Free it using GLib.strfreev().

Return type:

[str]

Removes the environment variable variable from the provided environment envp.

New in version 2.32.

GLib.file_error_from_errno(err_no)[source]
Parameters:

err_no (int) – an “errno” value

Returns:

GLib.FileError corresponding to the given err_no

Return type:

GLib.FileError

Gets a GLib.FileError constant based on the passed-in err_no.

For example, if you pass in EEXIST this function returns GLib.FileError.EXIST. Unlike errno values, you can portably assume that all GLib.FileError values will exist.

Normally a GLib.FileError value goes into a GLib.Error returned from a function that manipulates files. So you would use GLib.file_error_from_errno() when constructing a GLib.Error.

GLib.file_error_quark()[source]
Return type:

int

GLib.file_get_contents(filename)[source]
Parameters:

filename (str) – name of a file to read contents from, in the GLib file name encoding

Raises:

GLib.Error

Returns:

True on success, False if an error occurred

contents:

location to store an allocated string, use GLib.free() to free the returned string

Return type:

(bool, contents: bytes)

Reads an entire file into allocated memory, with good error checking.

If the call was successful, it returns True and sets contents to the file contents and length to the length of the file contents in bytes. The string stored in contents will be nul-terminated, so for text files you can pass None for the length argument. If the call was not successful, it returns False and sets error. The error domain is %G_FILE_ERROR. Possible error codes are those in the GLib.FileError enumeration. In the error case, contents is set to None and length is set to zero.

GLib.file_open_tmp(tmpl)[source]
Parameters:

tmpl (str or None) – Template for file name, as in g_mkstemp(), basename only, or None for a default template

Raises:

GLib.Error

Returns:

A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and error will be set.

name_used:

location to store actual name used, or None

Return type:

(int, name_used: str)

Opens a file for writing in the preferred directory for temporary files (as returned by 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 g_mkstemp(). However, unlike these functions, the template should only be a basename, no directory components are allowed. If template is None, a default template is used.

Note that in contrast to g_mkstemp() (and mkstemp()) tmpl is not modified, and might thus be a read-only literal string.

Upon success, and if name_used is non-None, the actual name used is returned in name_used. This string should be freed with GLib.free() when not needed any longer. The returned name is in the GLib file name encoding.

Parameters:

filename (str) – the symbolic link

Raises:

GLib.Error

Returns:

A newly-allocated string with the contents of the symbolic link, or None if an error occurred.

Return type:

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 GLib.filename_to_utf8() to convert it to UTF-8.

The returned string may also be a relative path. Use g_build_filename() to convert it to an absolute path:

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

New in version 2.4.

GLib.file_set_contents(filename, contents)[source]
Parameters:

  • filename (str) – name of a file to write contents to, in the GLib file name encoding

  • contents (bytes) – string to write to the file

Raises:

GLib.Error

Returns:

True on success, False if an error occurred

Return type:

bool

Writes all of contents to a file named filename. This is a convenience wrapper around calling 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.

New in version 2.8.

GLib.file_set_contents_full(filename, contents, flags, mode)[source]
Parameters:

  • filename (str) – name of a file to write contents to, in the GLib file name encoding

  • contents (bytes) – string to write to the file

  • flags (GLib.FileSetContentsFlags) – flags controlling the safety vs speed of the operation

  • mode (int) – file mode, as passed to open(); typically this will be 0666

Raises:

GLib.Error

Returns:

True on success, False if an error occurred

Return type:

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 GLib.FileSetContentsFlags.NONE then this function may call fsync().

If 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 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 GLib.FileSetContentsFlags.DURABLE and 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 True. If the call was not successful, it returns False and sets error. The error domain is %G_FILE_ERROR. Possible error codes are those in the 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.

New in version 2.66.

GLib.file_test(filename, test)[source]
Parameters:
Returns:

whether a test was True

Return type:

bool

Returns True if any of the tests in the bitfield test are True. For example, (G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR) will return True if the file exists; the check whether it’s a directory doesn’t matter since the existence test is True. With the current set of available tests, there’s no point passing in more than one test at a time.

Apart from GLib.FileTest.IS_SYMLINK all tests follow symbolic links, so for a symbolic link to a regular file GLib.file_test() will return True for both GLib.FileTest.IS_SYMLINK and GLib.FileTest.IS_REGULAR.

Note, that for a dangling symbolic link GLib.file_test() will return True for GLib.FileTest.IS_SYMLINK and False for all other flags.

You should never use 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 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!

// 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 GLib.FileTest.EXISTS and 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 GLib.FileTest.IS_SYMLINK will always return False. Testing for 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.

GLib.filename_display_basename(filename)[source]
Parameters:

filename (str) – an absolute pathname in the GLib file name encoding

Returns:

a newly allocated string containing a rendition of the basename of the filename in valid UTF-8

Return type:

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 GLib.filename_display_name() if you know the whole path, as it allows translation.

New in version 2.6.

GLib.filename_display_name(filename)[source]
Parameters:

filename (str) – a pathname hopefully in the GLib file name encoding

Returns:

a newly allocated string containing a rendition of the filename in valid UTF-8

Return type:

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 GLib.filename_to_utf8(), the result is guaranteed to be non-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 GLib.filename_display_basename(), since that allows location-based translation of filenames.

New in version 2.6.

GLib.filename_from_uri(uri)[source]
Parameters:

uri (str) – a uri describing a filename (escaped, encoded in ASCII).

Raises:

GLib.Error

Returns:

a newly-allocated string holding the resulting filename, or None on an error.

hostname:

Location to store hostname for the URI. If there is no hostname in the URI, None will be stored in this location.

Return type:

(str, hostname: str or 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.

GLib.filename_from_utf8(utf8string, len)[source]
Parameters:

  • utf8string (str) – a UTF-8 encoded string.

  • len (int) – the length of the string, or -1 if the string is nul-terminated.

Raises:

GLib.Error

Returns:

The converted string, or None on an error.

bytes_read:

location to store the number of bytes in the input string that were successfully converted, or None. Even if the conversion was successful, this may be less than len if there were partial characters at the end of the input. If the error GLib.ConvertError.ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence.

bytes_written:

the number of bytes stored in the output buffer (not including the terminating nul).

Return type:

(str, bytes_read: int, bytes_written: int)

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.

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 GLib.ConvertError.ILLEGAL_SEQUENCE. If the filename encoding is not UTF-8 and the conversion output contains a nul character, the error GLib.ConvertError.EMBEDDED_NUL is set and the function returns None.

GLib.filename_to_uri(filename, hostname)[source]
Parameters:

  • filename (str) – an absolute filename specified in the GLib file name encoding, which is the on-disk file name bytes on Unix, and UTF-8 on Windows

  • hostname (str or None) – A UTF-8 encoded hostname, or None for none.

Raises:

GLib.Error

Returns:

a newly-allocated string holding the resulting URI, or None on an error.

Return type:

str

Converts an absolute filename to an escaped ASCII-encoded URI, with the path component following Section 3.3. of RFC 2396.

GLib.filename_to_utf8(opsysstring, len)[source]
Parameters:

  • opsysstring (str) – a string in the encoding for filenames

  • len (int) – 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)

Raises:

GLib.Error

Returns:

The converted string, or None on an error.

bytes_read:

location to store the number of bytes in the input string that were successfully converted, or None. Even if the conversion was successful, this may be less than len if there were partial characters at the end of the input. If the error GLib.ConvertError.ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence.

bytes_written:

the number of bytes stored in the output buffer (not including the terminating nul).

Return type:

(str, bytes_read: int, bytes_written: 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.

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 GLib.ConvertError.ILLEGAL_SEQUENCE. If the source encoding is not UTF-8 and the conversion output contains a nul character, the error GLib.ConvertError.EMBEDDED_NUL is set and the function returns None. Use GLib.convert() to produce output that may contain embedded nul characters.

GLib.find_program_in_path(program)[source]
Parameters:

program (str) – a program name in the GLib file name encoding

Returns:

a newly-allocated string with the absolute path, or None

Return type:

str or 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 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 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.

GLib.format_size(size)[source]
Parameters:

size (int) – a size in bytes

Returns:

a newly-allocated formatted string containing a human readable file size

Return type:

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 GLib.free() when not needed any longer.

See GLib.format_size_full() for more options about how the size might be formatted.

New in version 2.30.

GLib.format_size_for_display(size)[source]
Parameters:

size (int) – a size in bytes

Returns:

a newly-allocated formatted string containing a human readable file size

Return type:

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 GLib.free() when not needed any longer.

New in version 2.16.

Deprecated since version 2.30: This function is broken due to its use of SI suffixes to denote IEC units. Use GLib.format_size() instead.

GLib.format_size_full(size, flags)[source]
Parameters:
Returns:

a newly-allocated formatted string containing a human readable file size

Return type:

str

Formats a size.

This function is similar to GLib.format_size() but allows for flags that modify the output. See GLib.FormatSizeFlags.

New in version 2.30.

GLib.free(mem)[source]
Parameters:

mem (object or None) – the memory to free

Frees the memory pointed to by mem.

If you know the allocated size of mem, calling 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 None it simply returns, so there is no need to check mem against None before calling this function.

GLib.free_sized(mem, size)[source]
Parameters:

  • mem (object or None) – the memory to free

  • size (int) – size of mem, in bytes

Frees the memory pointed to by mem, assuming it is has the given size.

If mem is 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 GLib.free() instead.

In case a GCC compatible compiler is used, this function may be used automatically via GLib.free() if the allocated size is known at compile time, since GLib 2.78.

New in version 2.76.

GLib.get_application_name()[source]
Returns:

human-readable application name. May return None

Return type:

str or None

Gets a human-readable name for the application, as set by GLib.set_application_name(). This name should be localized if possible, and is intended for display to the user. Contrast with GLib.get_prgname(), which gets a non-localized name. If GLib.set_application_name() has not been called, returns the result of GLib.get_prgname() (which may be None if GLib.set_prgname() has also not been called).

New in version 2.2.

GLib.get_charset()[source]
Returns:

True if the returned charset is UTF-8

charset:

return location for character set name, or None.

Return type:

(bool, charset: str)

Obtains the character set for the current locale; you might use this character set as an argument to GLib.convert(), to convert from the current locale’s encoding to some other encoding. (Frequently GLib.locale_to_utf8() and 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 True if the locale’s encoding is UTF-8, in that case you can perhaps avoid calling GLib.convert().

The string returned in charset is not allocated, and should not be freed.

GLib.get_codeset()[source]
Returns:

a newly allocated string containing the name of the character set. This string must be freed with GLib.free().

Return type:

str

Gets the character set for the current locale.

GLib.get_console_charset()[source]
Returns:

True if the returned charset is UTF-8

charset:

return location for character set name, or None.

Return type:

(bool, charset: 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 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 True if the locale’s encoding is UTF-8, in that case you can perhaps avoid calling GLib.convert().

The string returned in charset is not allocated, and should not be freed.

New in version 2.62.

GLib.get_current_dir()[source]
Returns:

the current directory

Return type:

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.

GLib.get_current_time()[source]
Returns:

Time in seconds since the Epoch

Return type:

float

Equivalent to the UNIX gettimeofday() function, but portable.

You may find GLib.get_real_time() to be more convenient.

Deprecated since version 2.62: GLib.TimeVal is not year-2038-safe. Use GLib.get_real_time() instead.

GLib.get_environ()[source]
Returns:

the list of environment variables

Return type:

[str]

Gets the list of environment variables for the current process.

The list is 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 GLib.strfreev() when it is no longer needed.

New in version 2.28.

GLib.get_filename_charsets()[source]
Returns:

True if the filename encoding is UTF-8.

filename_charsets:

return location for the None-terminated list of encoding names

Return type:

(bool, filename_charsets: [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 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. 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.

New in version 2.6.

GLib.get_home_dir()[source]
Returns:

the current user’s home directory

Return type:

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.

GLib.get_host_name()[source]
Returns:

the host name of the machine.

Return type:

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.

New in version 2.8.

GLib.get_language_names()[source]
Returns:

a None-terminated array of strings owned by GLib that must not be modified or freed.

Return type:

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

New in version 2.6.

GLib.get_language_names_with_category(category_name)[source]
Parameters:

category_name (str) – a locale category name

Returns:

a None-terminated array of strings owned by the thread GLib.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.

Return type:

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

GLib.get_language_names() returns GLib.get_language_names_with_category(“LC_MESSAGES”).

New in version 2.58.

GLib.get_locale_variants(locale)[source]
Parameters:

locale (str) – a locale identifier

Returns:

a newly allocated array of newly allocated strings with the locale variants. Free with GLib.strfreev().

Return type:

[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 GLib.get_language_names().

New in version 2.28.

GLib.get_monotonic_time()[source]
Returns:

the monotonic time, in microseconds

Return type:

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.

New in version 2.28.

GLib.get_num_processors()[source]
Returns:

Number of schedulable threads, always greater than 0

Return type:

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 g_thread_pool_new() for CPU bound tasks and similar cases.

New in version 2.36.

GLib.get_os_info(key_name)[source]
Parameters:

key_name (str) – a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME.

Returns:

The associated value for the requested key or None if this information is not provided.

Return type:

str or 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 None.

New in version 2.64.

GLib.get_prgname()[source]
Returns:

the name of the program, or None if it has not been set yet. The returned string belongs to GLib and must not be modified or freed.

Return type:

str or None

Gets the name of the program. This name should not be localized, in contrast to 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].

GLib.get_real_name()[source]
Returns:

the user’s real name.

Return type:

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.

GLib.get_real_time()[source]
Returns:

the number of microseconds since January 1, 1970 UTC.

Return type:

int

Queries the system wall-clock time.

This call is functionally equivalent to GLib.get_current_time() except that the return value is often more convenient than dealing with a GLib.TimeVal.

You should only use this call if you are actually interested in the real wall-clock time. GLib.get_monotonic_time() is probably more useful for measuring intervals.

New in version 2.28.

GLib.get_system_config_dirs()[source]
Returns:

a None-terminated array of strings owned by GLib that must not be modified or freed.

Return type:

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

New in version 2.6.

GLib.get_system_data_dirs()[source]
Returns:

a None-terminated array of strings owned by GLib that must not be modified or freed.

Return type:

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

New in version 2.6.

GLib.get_tmp_dir()[source]
Returns:

the directory to use for temporary files.

Return type:

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 None or the empty string.

GLib.get_user_cache_dir()[source]
Returns:

a string owned by GLib that must not be modified or freed.

Return type:

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.

New in version 2.6.

GLib.get_user_config_dir()[source]
Returns:

a string owned by GLib that must not be modified or freed.

Return type:

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

New in version 2.6.

GLib.get_user_data_dir()[source]
Returns:

a string owned by GLib that must not be modified or freed.

Return type:

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

New in version 2.6.

GLib.get_user_name()[source]
Returns:

the user name of the current user.

Return type:

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.

GLib.get_user_runtime_dir()[source]
Returns:

a string owned by GLib that must not be modified or freed.

Return type:

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

New in version 2.28.

GLib.get_user_special_dir(directory)[source]
Parameters:

directory (GLib.UserDirectory) – the logical id of special directory

Returns:

the path to the specified special directory, or None if the logical id was not found. The returned string is owned by GLib and should not be modified or freed.

Return type:

str or 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, 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.

New in version 2.14.

GLib.get_user_state_dir()[source]
Returns:

a string owned by GLib that must not be modified or freed.

Return type:

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

New in version 2.72.

GLib.getenv(variable)[source]
Parameters:

variable (str) – the environment variable to get

Returns:

the value of the environment variable, or None if the environment variable is not found. The returned string may be overwritten by the next call to GLib.getenv(), GLib.setenv() or GLib.unsetenv().

Return type:

str or 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.

GLib.hash_table_add(hash_table, key)[source]
Parameters:
Returns:

True if the key did not exist yet

Return type:

bool

This is a convenience function for using a GLib.HashTable as a set. It is equivalent to calling GLib.HashTable.replace() with key as both the key and the value.

In particular, this means that if key already exists in the hash table, then the old copy of key in the hash table is freed and key replaces it in the table.

When a hash table only ever contains keys that have themselves as the corresponding value it is able to be stored more efficiently. See the discussion in the section description.

Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not.

New in version 2.32.

GLib.hash_table_contains(hash_table, key)[source]
Parameters:
Returns:

True if key is in hash_table, False otherwise.

Return type:

bool

Checks if key is in hash_table.

New in version 2.32.

GLib.hash_table_destroy(hash_table)[source]
Parameters:

hash_table ({object: object}) – a GLib.HashTable

Destroys all keys and values in the GLib.HashTable and decrements its reference count by 1. If keys and/or values are dynamically allocated, you should either free them first or create the GLib.HashTable with destroy notifiers using g_hash_table_new_full(). In the latter case the destroy functions you supplied will be called on all keys and values during the destruction phase.

GLib.hash_table_insert(hash_table, key, value)[source]
Parameters:
Returns:

True if the key did not exist yet

Return type:

bool

Inserts a new key and value into a GLib.HashTable.

If the key already exists in the GLib.HashTable its current value is replaced with the new value. If you supplied a value_destroy_func when creating the GLib.HashTable, the old value is freed using that function. If you supplied a key_destroy_func when creating the GLib.HashTable, the passed key is freed using that function.

Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not.

GLib.hash_table_lookup(hash_table, key)[source]
Parameters:
Returns:

the associated value, or None if the key is not found

Return type:

object or None

Looks up a key in a GLib.HashTable. Note that this function cannot distinguish between a key that is not present and one which is present and has the value None. If you need this distinction, use GLib.HashTable.lookup_extended().

GLib.hash_table_lookup_extended(hash_table, lookup_key)[source]
Parameters:
Returns:

True if the key was found in the GLib.HashTable

orig_key:

return location for the original key

value:

return location for the value associated with the key

Return type:

(bool, orig_key: object, value: object)

Looks up a key in the GLib.HashTable, returning the original key and the associated value and a bool which is True if the key was found. This is useful if you need to free the memory allocated for the original key, for example before calling GLib.HashTable.remove().

You can actually pass None for lookup_key to test whether the None key exists, provided the hash and equal functions of hash_table are None-safe.

GLib.hash_table_new_similar(other_hash_table)[source]
Parameters:

other_hash_table ({object: object}) – Another GLib.HashTable

Returns:

a new GLib.HashTable

Return type:

{object: object}

Creates a new GLib.HashTable like g_hash_table_new_full() with a reference count of 1.

It inherits the hash function, the key equal function, the key destroy function, as well as the value destroy function, from other_hash_table.

The returned hash table will be empty; it will not contain the keys or values from other_hash_table.

New in version 2.72.

GLib.hash_table_remove(hash_table, key)[source]
Parameters:
Returns:

True if the key was found and removed from the GLib.HashTable

Return type:

bool

Removes a key and its associated value from a GLib.HashTable.

If the GLib.HashTable was created using g_hash_table_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself.

GLib.hash_table_remove_all(hash_table)[source]
Parameters:

hash_table ({object: object}) – a GLib.HashTable

Removes all keys and their associated values from a GLib.HashTable.

If the GLib.HashTable was created using g_hash_table_new_full(), the keys and values are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself.

New in version 2.12.

GLib.hash_table_replace(hash_table, key, value)[source]
Parameters:
Returns:

True if the key did not exist yet

Return type:

bool

Inserts a new key and value into a GLib.HashTable similar to GLib.HashTable.insert(). The difference is that if the key already exists in the GLib.HashTable, it gets replaced by the new key. If you supplied a value_destroy_func when creating the GLib.HashTable, the old value is freed using that function. If you supplied a key_destroy_func when creating the GLib.HashTable, the old key is freed using that function.

Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not.

GLib.hash_table_size(hash_table)[source]
Parameters:

hash_table ({object: object}) – a GLib.HashTable

Returns:

the number of key/value pairs in the GLib.HashTable.

Return type:

int

Returns the number of elements contained in the GLib.HashTable.

GLib.hash_table_steal(hash_table, key)[source]
Parameters:
Returns:

True if the key was found and removed from the GLib.HashTable

Return type:

bool

Removes a key and its associated value from a GLib.HashTable without calling the key and value destroy functions.

GLib.hash_table_steal_all(hash_table)[source]
Parameters:

hash_table ({object: object}) – a GLib.HashTable

Removes all keys and their associated values from a GLib.HashTable without calling the key and value destroy functions.

New in version 2.12.

GLib.hash_table_steal_extended(hash_table, lookup_key)[source]
Parameters:
Returns:

True if the key was found in the GLib.HashTable

stolen_key:

return location for the original key

stolen_value:

return location for the value associated with the key

Return type:

(bool, stolen_key: object, stolen_value: object)

Looks up a key in the GLib.HashTable, stealing the original key and the associated value and returning True if the key was found. If the key was not found, False is returned.

If found, the stolen key and value are removed from the hash table without calling the key and value destroy functions, and ownership is transferred to the caller of this method, as with GLib.HashTable.steal(). That is the case regardless whether stolen_key or stolen_value output parameters are requested.

You can pass None for lookup_key, provided the hash and equal functions of hash_table are None-safe.

The dictionary implementation optimizes for having all values identical to their keys, for example by using GLib.HashTable.add(). When stealing both the key and the value from such a dictionary, the value will be None.

New in version 2.58.

GLib.hash_table_unref(hash_table)[source]
Parameters:

hash_table ({object: object}) – a valid GLib.HashTable

Atomically decrements the reference count of hash_table by one. If the reference count drops to 0, all keys and values will be destroyed, and all memory allocated by the hash table is released. This function is MT-safe and may be called from any thread.

New in version 2.10.

GLib.hook_destroy(hook_list, hook_id)[source]
Parameters:
Returns:

True if the GLib.Hook was found in the GLib.HookList and destroyed

Return type:

bool

Destroys a GLib.Hook, given its ID.

Parameters:

Removes one GLib.Hook from a GLib.HookList, marking it inactive and calling GLib.Hook.unref() on it.

GLib.hook_free(hook_list, hook)[source]
Parameters:

Calls the GLib.HookList finalize_hook function if it exists, and frees the memory allocated for the GLib.Hook.

GLib.hook_insert_before(hook_list, sibling, hook)[source]
Parameters:

Inserts a GLib.Hook into a GLib.HookList, before a given GLib.Hook.

GLib.hook_prepend(hook_list, hook)[source]
Parameters:

Prepends a GLib.Hook on the start of a GLib.HookList.

GLib.hook_unref(hook_list, hook)[source]
Parameters:

Decrements the reference count of a GLib.Hook. If the reference count falls to 0, the GLib.Hook is removed from the GLib.HookList and GLib.Hook.free() is called to free it.

GLib.hostname_is_ascii_encoded(hostname)[source]
Parameters:

hostname (str) – a hostname

Returns:

True if hostname contains any ASCII-encoded segments.

Return type:

bool

Tests if hostname contains segments with an ASCII-compatible encoding of an Internationalized Domain Name. If this returns True, you should decode the hostname with 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 GLib.hostname_is_non_ascii() and GLib.hostname_is_ascii_encoded() to both return True for a name.

New in version 2.22.

GLib.hostname_is_ip_address(hostname)[source]
Parameters:

hostname (str) – a hostname (or IP address in string form)

Returns:

True if hostname is an IP address

Return type:

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

New in version 2.22.

GLib.hostname_is_non_ascii(hostname)[source]
Parameters:

hostname (str) – a hostname

Returns:

True if hostname contains any non-ASCII characters

Return type:

bool

Tests if hostname contains Unicode characters. If this returns True, you need to encode the hostname with 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 GLib.hostname_is_non_ascii() and GLib.hostname_is_ascii_encoded() to both return True for a name.

New in version 2.22.

GLib.hostname_to_ascii(hostname)[source]
Parameters:

hostname (str) – a valid UTF-8 or ASCII hostname

Returns:

an ASCII hostname, which must be freed, or None if hostname is in some way invalid.

Return type:

str or None

Converts hostname to its canonical ASCII form; an ASCII-only string containing no uppercase letters and not ending with a trailing dot.

New in version 2.22.

GLib.hostname_to_unicode(hostname)[source]
Parameters:

hostname (str) – a valid UTF-8 or ASCII hostname

Returns:

a UTF-8 hostname, which must be freed, or None if hostname is in some way invalid.

Return type:

str or 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.

New in version 2.22.

GLib.idle_add(priority, function, *data)[source]
Parameters:
Returns:

the ID (greater than 0) of the event source.

Return type:

int

Adds a function to be called whenever there are no higher priority events pending.

If the function returns GLib.SOURCE_REMOVE or False it is automatically removed from the list of event sources and will not be called again.

See memory management of sources for details on how to handle the return value and memory management of data.

This internally creates a main loop source using GLib.idle_source_new() and attaches it to the global GLib.MainContext using 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.

GLib.idle_remove_by_data(data)[source]
Parameters:

data (object or None) – the data for the idle source’s callback.

Returns:

True if an idle source was found and removed.

Return type:

bool

Removes the idle function with the given data.

GLib.idle_source_new()[source]
Returns:

the newly-created idle source

Return type:

GLib.Source

Creates a new idle source.

The source will not initially be associated with any GLib.MainContext and must be added to one with GLib.Source.attach() before it will be executed. Note that the default priority for idle sources is GLib.PRIORITY_DEFAULT_IDLE, as compared to other sources which have a default priority of GLib.PRIORITY_DEFAULT.

GLib.int64_equal(v1, v2)[source]
Parameters:

  • v1 (object) – a pointer to a #gint64 key

  • v2 (object) – a pointer to a #gint64 key to compare with v1

Returns:

True if the two keys match.

Return type:

bool

Compares the two #gint64 values being pointed to and returns True if they are equal. It can be passed to g_hash_table_new() as the key_equal_func parameter, when using non-None pointers to 64-bit integers as keys in a GLib.HashTable.

New in version 2.22.

GLib.int64_hash(v)[source]
Parameters:

v (object) – a pointer to a #gint64 key

Returns:

a hash value corresponding to the key.

Return type:

int

Converts a pointer to a #gint64 to a hash value.

It can be passed to g_hash_table_new() as the hash_func parameter, when using non-None pointers to 64-bit integer values as keys in a GLib.HashTable.

New in version 2.22.

GLib.int_equal(v1, v2)[source]
Parameters:

  • v1 (object) – a pointer to a int key

  • v2 (object) – a pointer to a int key to compare with v1

Returns:

True if the two keys match.

Return type:

bool

Compares the two int values being pointed to and returns True if they are equal. It can be passed to g_hash_table_new() as the key_equal_func parameter, when using non-None pointers to integers as keys in a GLib.HashTable.

Note that this function acts on pointers to int, not on int directly: if your hash table’s keys are of the form GINT_TO_POINTER (n), use GLib.direct_equal() instead.

GLib.int_hash(v)[source]
Parameters:

v (object) – a pointer to a int key

Returns:

a hash value corresponding to the key.

Return type:

int

Converts a pointer to a int to a hash value. It can be passed to g_hash_table_new() as the hash_func parameter, when using non-None pointers to integer values as keys in a GLib.HashTable.

Note that this function acts on pointers to int, not on int directly: if your hash table’s keys are of the form GINT_TO_POINTER (n), use GLib.direct_hash() instead.

GLib.intern_static_string(string)[source]
Parameters:

string (str or None) – a static string

Returns:

a canonical representation for the string

Return type:

str

Returns a canonical representation for string. Interned strings can be compared for equality by comparing the pointers, instead of using strcmp(). 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++.

New in version 2.10.

GLib.intern_string(string)[source]
Parameters:

string (str or None) – a string

Returns:

a canonical representation for the string

Return type:

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

New in version 2.10.

GLib.io_add_watch(channel, priority, condition, func, *user_data)[source]
Parameters:

  • channel – a GLib.IOChannel

  • priority – the priority of the GLib.IOChannel source

  • condition – the condition to watch for

  • func – the function to call when the condition is satisfied

  • user_data – user data to pass to func

Returns:

the event source id

Return type:

event_source_id

Adds the GLib.IOChannel into the default main loop context with the given priority.

This internally creates a main loop source using GLib.io_create_watch() and attaches it to the main loop context with GLib.Source.attach(). You can do these steps manually if you need greater control.

GLib.io_channel_error_from_errno(en)[source]
Parameters:

en (int) – an errno error number, e.g. EINVAL

Returns:

a GLib.IOChannelError error number, e.g. GLib.IOChannelError.INVAL.

Return type:

GLib.IOChannelError

Converts an errno error number to a GLib.IOChannelError.

GLib.io_channel_error_quark()[source]
Return type:

int

GLib.io_create_watch(channel, condition)[source]
Parameters:
Returns:

a new GLib.Source

Return type:

GLib.Source

Creates a GLib.Source that’s dispatched when condition is met for the given channel. For example, if condition is GLib.IOCondition.IN, the source will be dispatched when there’s data available for reading.

The callback function invoked by the GLib.Source should be added with GLib.Source.set_callback(), but it has type GLib.IOFunc (not GLib.SourceFunc).

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

GLib.key_file_error_quark()[source]
Return type:

int

GLib.listenv()[source]
Returns:

a None-terminated list of strings which must be freed with GLib.strfreev().

Return type:

[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 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 GLib.getenv() provide.

New in version 2.8.

GLib.locale_from_utf8(utf8string, len)[source]
Parameters:

  • utf8string (str) – a UTF-8 encoded string

  • len (int) – the length of the string, or -1 if the string is nul-terminated.

Raises:

GLib.Error

Returns:

A newly-allocated buffer containing the converted string, or None on an error, and error will be set.

bytes_read:

location to store the number of bytes in the input string that were successfully converted, or None. Even if the conversion was successful, this may be less than len if there were partial characters at the end of the input. If the error GLib.ConvertError.ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence.

Return type:

(bytes, bytes_read: 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. 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 GLib.ConvertError.ILLEGAL_SEQUENCE. Use GLib.convert() to convert input that may contain embedded nul characters.

GLib.locale_to_utf8(opsysstring)[source]
Parameters:

opsysstring (bytes) – a string in the encoding of the current locale. On Windows this means the system codepage.

Raises:

GLib.Error

Returns:

The converted string, or None on an error.

bytes_read:

location to store the number of bytes in the input string that were successfully converted, or None. Even if the conversion was successful, this may be less than len if there were partial characters at the end of the input. If the error GLib.ConvertError.ILLEGAL_SEQUENCE occurs, the value stored will be the byte offset after the last valid input sequence.

bytes_written:

the number of bytes stored in the output buffer (not including the terminating nul).

Return type:

(str, bytes_read: int, bytes_written: 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 into a UTF-8 string.

If the source encoding is not UTF-8 and the conversion output contains a nul character, the error GLib.ConvertError.EMBEDDED_NUL is set and the function returns None. If the source encoding is UTF-8, an embedded nul character is treated with the GLib.ConvertError.ILLEGAL_SEQUENCE error for backward compatibility with earlier versions of this library. Use GLib.convert() to produce output that may contain embedded nul characters.

GLib.log_default_handler(log_domain, log_level, message, unused_data)[source]
Parameters:

  • log_domain (str or None) – the log domain of the message, or None for the default “” application domain

  • log_level (GLib.LogLevelFlags) – the level of the message

  • message (str or None) – the message

  • unused_data (object or None) – data passed from g_log() which is unused

The default log handler set up by GLib; g_log_set_default_handler() allows to install an alternate default log handler. This is used if no log handler has been set for the particular log domain and log level combination. It outputs the message to stderr or stdout and if the log level is fatal it calls G_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.

stderr is used for levels GLib.LogLevelFlags.LEVEL_ERROR, GLib.LogLevelFlags.LEVEL_CRITICAL, GLib.LogLevelFlags.LEVEL_WARNING and GLib.LogLevelFlags.LEVEL_MESSAGE. stdout is used for the rest, unless stderr was requested by GLib.log_writer_default_set_use_stderr().

This has no effect if structured logging is enabled; see Using Structured Logging.

GLib.log_get_debug_enabled()[source]
Returns:

True if debug output is enabled, False otherwise

Return type:

bool

Return whether debug output from the GLib logging system is enabled.

Note that this should not be used to conditionalise calls to g_debug() or other logging functions; it should only be used from GLib.LogWriterFunc implementations.

Note also that the value of this does not depend on G_MESSAGES_DEBUG; see the docs for GLib.log_set_debug_enabled().

New in version 2.72.

GLib.log_remove_handler(log_domain, handler_id)[source]
Parameters:

Removes the log handler.

This has no effect if structured logging is enabled; see Using Structured Logging.

GLib.log_set_always_fatal(fatal_mask)[source]
Parameters:

fatal_mask (GLib.LogLevelFlags) – the mask containing bits set for each level of error which is to be fatal

Returns:

the old fatal mask

Return type:

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

GLib.log_set_debug_enabled(enabled)[source]
Parameters:

enabled (bool) – True to enable debug output, False otherwise

Enable or disable debug output from the GLib logging system for all domains. This value interacts disjunctively with G_MESSAGES_DEBUG — if either 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.

New in version 2.72.

GLib.log_set_fatal_mask(log_domain, fatal_mask)[source]
Parameters:
Returns:

the old fatal mask for the log domain

Return type:

GLib.LogLevelFlags

Sets the log levels which are fatal in the given domain. GLib.LogLevelFlags.LEVEL_ERROR is always fatal.

This has no effect on structured log messages (using g_log_structured() or GLib.log_structured_array()). To change the fatal behaviour for specific log messages, programs must install a custom log writer function using GLib.log_set_writer_func(). See Using Structured Logging.

This function is mostly intended to be used with GLib.LogLevelFlags.LEVEL_CRITICAL. You should typically not set GLib.LogLevelFlags.LEVEL_WARNING, GLib.LogLevelFlags.LEVEL_MESSAGE, GLib.LogLevelFlags.LEVEL_INFO or GLib.LogLevelFlags.LEVEL_DEBUG as fatal except inside of test programs.

GLib.log_set_handler(log_domain, log_levels, log_func, *user_data)[source]
Parameters:
Returns:

the id of the new handler

Return type:

int

Like GLib.log_set_handler(), but takes a destroy notify for the user_data.

This has no effect if structured logging is enabled; see Using Structured Logging.

New in version 2.46.

GLib.log_set_writer_func(*user_data)[source]
Parameters:

user_data (object or None) – user data to pass to func

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

New in version 2.50.

GLib.log_structured_array(log_level, fields)[source]
Parameters:

Log a message with structured data. The message will be passed through to the log writer set by the application using GLib.log_set_writer_func(). If the message is fatal (i.e. its log level is GLib.LogLevelFlags.LEVEL_ERROR), the program will be aborted at the end of this function.

See g_log_structured() for more documentation.

This assumes that log_level is already present in fields (typically as the PRIORITY field).

New in version 2.50.

GLib.log_variant(log_domain, log_level, fields)[source]
Parameters:

Log a message with structured data, accepting the data within a 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 String (%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 GLib.Variant.print_() will be used to convert the value into a string.

For more details on its usage and about the parameters, see g_log_structured().

New in version 2.50.

GLib.log_writer_default(log_level, fields, user_data)[source]
Parameters:
Returns:

GLib.LogWriterOutput.HANDLED on success, GLib.LogWriterOutput.UNHANDLED otherwise

Return type:

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 GLib.LogWriterFunc, and is the default writer used if no other is set using GLib.log_set_writer_func().

As with 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.

GLib.log_writer_default() uses the mask set by GLib.log_set_always_fatal() to determine which messages are fatal. When using a custom writer func instead it is up to the writer function to determine which log messages are fatal.

New in version 2.50.

GLib.log_writer_default_set_use_stderr(use_stderr)[source]
Parameters:

use_stderr (bool) – If True, use stderr for log messages that would normally have appeared on stdout

Configure whether the built-in log functions (GLib.log_default_handler() for the old-style API, and both GLib.log_writer_default() and GLib.log_writer_standard_streams() for the structured API) will output all log messages to stderr.

By default, log messages of levels GLib.LogLevelFlags.LEVEL_INFO and 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.

New in version 2.68.

GLib.log_writer_default_would_drop(log_level, log_domain)[source]
Parameters:
Returns:

True if the log message would be dropped by GLib’s default log handlers

Return type:

bool

Check whether GLib.log_writer_default() and GLib.log_default_handler() would ignore a message with the given domain and level.

As with 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.

This can be used when implementing log writers with the same filtering behaviour as the default, but a different destination or output format:

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:

if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN))
{
  gchar *result = expensive_computation (my_object);

  g_debug ("my_object result: %s", result);
  g_free (result);
}

New in version 2.68.

GLib.log_writer_format_fields(log_level, fields, use_color)[source]
Parameters:
Returns:

string containing the formatted log message, in the character set of the current locale

Return type:

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

New in version 2.50.

GLib.log_writer_is_journald(output_fd)[source]
Parameters:

output_fd (int) – output file descriptor to check

Returns:

True if output_fd points to the journal, False otherwise

Return type:

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:

is_journald = g_log_writer_is_journald (fileno (stderr));

New in version 2.50.

GLib.log_writer_journald(log_level, fields, user_data)[source]
Parameters:
Returns:

GLib.LogWriterOutput.HANDLED on success, GLib.LogWriterOutput.UNHANDLED otherwise

Return type:

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 GLib.LogWriterFunc.

If GLib has been compiled without systemd support, this function is still defined, but will always return GLib.LogWriterOutput.UNHANDLED.

New in version 2.50.

GLib.log_writer_standard_streams(log_level, fields, user_data)[source]
Parameters:
Returns:

GLib.LogWriterOutput.HANDLED on success, GLib.LogWriterOutput.UNHANDLED otherwise

Return type:

GLib.LogWriterOutput

Format a structured log message and print it to either stdout or stderr, depending on its log level. GLib.LogLevelFlags.LEVEL_INFO and GLib.LogLevelFlags.LEVEL_DEBUG messages are sent to stdout, or to stderr if requested by 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 GLib.LogWriterFunc.

New in version 2.50.

GLib.log_writer_supports_color(output_fd)[source]
Parameters:

output_fd (int) – output file descriptor to check

Returns:

True if ANSI color escapes are supported, False otherwise

Return type:

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.

New in version 2.50.

GLib.main_context_default()[source]
Returns:

the global-default main context.

Return type:

GLib.MainContext

Returns the global-default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the “main” main loop. See also GLib.MainContext.get_thread_default().

GLib.main_context_get_thread_default()[source]
Returns:

the thread-default GLib.MainContext, or None if the thread-default context is the global-default main context.

Return type:

GLib.MainContext or None

Gets the thread-default GLib.MainContext for this thread. Asynchronous operations that want to be able to be run in contexts other than the default one should call this method or GLib.MainContext.ref_thread_default() to get a GLib.MainContext to add their GLib.Sources to. (Note that even in single-threaded programs applications may sometimes want to temporarily push a non-default context, so it is not safe to assume that this will always return None if you are running in the default thread.)

If you need to hold a reference on the context, use GLib.MainContext.ref_thread_default() instead.

New in version 2.22.

GLib.main_context_ref_thread_default()[source]
Returns:

the thread-default GLib.MainContext. Unref with GLib.MainContext.unref() when you are done with it.

Return type:

GLib.MainContext

Gets the thread-default GLib.MainContext for this thread, as with GLib.MainContext.get_thread_default(), but also adds a reference to it with GLib.MainContext.ref(). In addition, unlike GLib.MainContext.get_thread_default(), if the thread-default context is the global-default context, this will return that GLib.MainContext (with a ref added to it) rather than returning None.

New in version 2.32.

GLib.main_current_source()[source]
Returns:

The currently firing source or None.

Return type:

GLib.Source or None

Returns the currently firing source for this thread.

New in version 2.12.

GLib.main_depth()[source]
Returns:

The main loop recursion level in the current thread

Return type:

int

Returns the depth of the stack of calls to GLib.MainContext.dispatch() on any GLib.MainContext in the current thread. That is, when called from the toplevel, it gives 0. When called from within a callback from GLib.MainContext.iteration() (or GLib.MainLoop.run(), etc.) it returns 1. When called from within a callback to a recursive call to 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.

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

gpointer
allocate_memory (gsize size)
{
  FreeListBlock *block = g_new (FreeListBlock, 1);
  block->mem = g_malloc (size);
  block->depth = g_main_depth ();
  free_list = g_list_prepend (free_list, block);
  return block->mem;
}

void
free_allocated_memory (void)
{
  GList *l;

  int depth = g_main_depth ();
  for (l = free_list; l; );
    {
      GList *next = l->next;
      FreeListBlock *block = l->data;
      if (block->depth > depth)
        {
          g_free (block->mem);
          g_free (block);
          free_list = g_list_delete_link (free_list, l);
        }

      l = next;
    }
  }

There is a temptation to use 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 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.

GLib.malloc(n_bytes)[source]
Parameters:

n_bytes (int) – the number of bytes to allocate

Returns:

a pointer to the allocated memory

Return type:

object or None

Allocates n_bytes bytes of memory. If n_bytes is 0 it returns None.

If the allocation fails (because the system is out of memory), the program is terminated.

GLib.malloc0(n_bytes)[source]
Parameters:

n_bytes (int) – the number of bytes to allocate

Returns:

a pointer to the allocated memory

Return type:

object or None

Allocates n_bytes bytes of memory, initialized to 0’s. If n_bytes is 0 it returns None.

If the allocation fails (because the system is out of memory), the program is terminated.

GLib.malloc0_n(n_blocks, n_block_bytes)[source]
Parameters:

  • n_blocks (int) – the number of blocks to allocate

  • n_block_bytes (int) – the size of each block in bytes

Returns:

a pointer to the allocated memory

Return type:

object or None

This function is similar to 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.

New in version 2.24.

GLib.malloc_n(n_blocks, n_block_bytes)[source]
Parameters:

  • n_blocks (int) – the number of blocks to allocate

  • n_block_bytes (int) – the size of each block in bytes

Returns:

a pointer to the allocated memory

Return type:

object or None

This function is similar to 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.

New in version 2.24.

GLib.markup_error_quark()[source]
Return type:

int

GLib.markup_escape_text(text, length)[source]
Parameters:

  • text (str) – some valid UTF-8 text

  • length (int) – length of text in bytes, or -1 if the text is nul-terminated

Returns:

a newly allocated string with the escaped text

Return type:

str

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 &#x1; … &#x1f; 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.

GLib.mem_is_system_malloc()[source]
Returns:

if True, malloc() and GLib.malloc() can be mixed.

Return type:

bool

Checks whether the allocator used by GLib.malloc() is the system’s malloc implementation. If it returns True memory allocated with malloc() can be used interchangeably with memory allocated using GLib.malloc(). This function is useful for avoiding an extra copy of allocated memory returned by a non-GLib-based API.

Deprecated since version 2.46: GLib always uses the system malloc, so this function always returns True.

GLib.mem_profile()[source]

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 since version 2.46: Use other memory profiling tools instead

GLib.mem_set_vtable(vtable)[source]
Parameters:

vtable (GLib.MemVTable) – table of memory allocation routines.

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 since version 2.46: This function now does nothing. Use other memory profiling tools instead

GLib.memdup(mem, byte_size)[source]
Parameters:

  • mem (object or None) – the memory to copy.

  • byte_size (int) – the number of bytes to copy.

Returns:

a pointer to the newly-allocated copy of the memory, or None if mem is None.

Return type:

object or None

Allocates byte_size bytes of memory, and copies byte_size bytes into it from mem. If mem is None it returns None.

Deprecated since version 2.68: Use GLib.memdup2() instead, as it accepts a #gsize argument for byte_size, avoiding the possibility of overflow in a #gsize → int conversion

GLib.memdup2(mem, byte_size)[source]
Parameters:

  • mem (object or None) – the memory to copy.

  • byte_size (int) – the number of bytes to copy.

Returns:

a pointer to the newly-allocated copy of the memory, or None if mem is None.

Return type:

object or None

Allocates byte_size bytes of memory, and copies byte_size bytes into it from mem. If mem is None it returns None.

This replaces GLib.memdup(), which was prone to integer overflows when converting the argument from a #gsize to a int.

New in version 2.68.

GLib.mkdir_with_parents(pathname, mode)[source]
Parameters:

  • pathname (str) – a pathname in the GLib file name encoding

  • mode (int) – permissions to use for newly created directories

Returns:

0 if the directory already exists, or was successfully created. Returns -1 if an error occurred, with errno set.

Return type:

int

Create a directory if it doesn’t already exist. Create intermediate parent directories as needed, too.

New in version 2.8.

GLib.nullify_pointer(nullify_location)[source]
Parameters:

nullify_location (object) – the memory address of the pointer.

Set the pointer at the specified location to None.

GLib.number_parser_error_quark()[source]
Return type:

int

GLib.on_error_query(prg_name)[source]
Parameters:

prg_name (str) – the program name, needed by gdb for the “[S]tack trace” option. If prg_name is None, GLib.get_prgname() is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called)

Prompts the user with [E]xit, [H]alt, show [S]tack trace or [P]roceed. This function is intended to be used for debugging use only. The following example shows how it can be used together with the g_log() functions.

#include <glib.h>

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, 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 GLib.on_error_stack_trace() instead.

GLib.on_error_stack_trace(prg_name)[source]
Parameters:

prg_name (str) – the program name, needed by gdb for the “[S]tack trace” option

Invokes gdb, which attaches to the current process and shows a stack trace. Called by GLib.on_error_query() when the “[S]tack trace” option is selected. You can get the current process’s program name with 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 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).

GLib.once_init_enter(location)[source]
Parameters:

location (object) – location of a static initializable variable containing 0

Returns:

True if the initialization section should be entered, False and blocks otherwise

Return type:

bool

Function to be called when starting a critical initialization section. The argument location must point to a static 0-initialized variable that will be set to a value other than 0 at the end of the initialization section. In combination with GLib.Once.init_leave() and the unique address value_location, it can be ensured that an initialization section will be executed only once during a program’s life time, and that concurrent threads are blocked until initialization completed. To be used in constructs like this:

static gsize initialization_value = 0;

if (g_once_init_enter (&initialization_value))
  {
    gsize setup_value = 42; // initialization code here

    g_once_init_leave (&initialization_value, setup_value);
  }

// use initialization_value here

While location has a volatile qualifier, this is a historical artifact and the pointer passed to it should not be volatile.

New in version 2.14.

GLib.once_init_leave(location, result)[source]
Parameters:

  • location (object) – location of a static initializable variable containing 0

  • result (int) – new non-0 value for value_location

Counterpart to GLib.Once.init_enter(). Expects a location of a static 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in GLib.Once.init_enter() on this initialization variable.

While location has a volatile qualifier, this is a historical artifact and the pointer passed to it should not be volatile.

New in version 2.14.

GLib.option_error_quark()[source]
Return type:

int

GLib.parse_debug_string(string, keys)[source]
Parameters:

  • string (str or None) – a list of debug options separated by colons, spaces, or commas, or None.

  • keys ([GLib.DebugKey]) – pointer to an array of GLib.DebugKey which associate strings with bit flags.

Returns:

the combined set of bit flags.

Return type:

int

Parses a string containing debugging options into a 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.

GLib.path_buf_equal(v1, v2)[source]
Parameters:

  • v1 (object) – a path buffer to compare

  • v2 (object) – a path buffer to compare

Returns:

TRUE if the two path buffers are equal, and FALSE otherwise

Return type:

bool

Compares two path buffers for equality and returns TRUE if they are equal.

The path inside the paths buffers are not going to be normalized, so X/Y/Z/A/.., X/./Y/Z and X/Y/Z are not going to be considered equal.

This function can be passed to g_hash_table_new() as the key_equal_func parameter.

New in version 2.76.

GLib.path_get_basename(file_name)[source]
Parameters:

file_name (str) – the name of the file

Returns:

a newly allocated string containing the last component of the filename

Return type:

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 “.”.

GLib.path_get_dirname(file_name)[source]
Parameters:

file_name (str) – the name of the file

Returns:

the directory components of the file

Return type:

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.

GLib.path_is_absolute(file_name)[source]
Parameters:

file_name (str) – a file name

Returns:

True if file_name is absolute

Return type:

bool

Returns True if the given file_name is an absolute file name. Note that this is a somewhat vague concept on Windows.

On POSIX systems, an absolute file name is well-defined. It always starts from the single root directory. For example “/usr/local”.

On Windows, the concepts of current drive and drive-specific current directory introduce vagueness. This function interprets as an absolute file name one that either begins with a directory separator such as “\Users\tml” or begins with the root on a drive, for example “C:\Windows”. The first case also includes UNC paths such as “\\\\myserver\docs\foo”. In all cases, either slashes or backslashes are accepted.

Note that a file name relative to the current drive root does not truly specify a file uniquely over time and across processes, as the current drive is a per-process value and can be changed.

File names relative the current directory on some specific drive, such as “D:foo/bar”, are not interpreted as absolute by this function, but they obviously are not relative to the normal current directory as returned by getcwd() or GLib.get_current_dir() either. Such paths should be avoided, or need to be handled using Windows-specific code.

GLib.path_skip_root(file_name)[source]
Parameters:

file_name (str) – a file name

Returns:

a pointer into file_name after the root component

Return type:

str or 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 None.

GLib.pattern_match_simple(pattern, string)[source]
Parameters:

  • pattern (str) – the UTF-8 encoded pattern

  • string (str) – the UTF-8 encoded string to match

Returns:

True if string matches pspec

Return type:

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 GLib.PatternSpec.new() and call g_pattern_match_string() repeatedly.

GLib.pointer_bit_lock(address, lock_bit)[source]
Parameters:

  • address (object) – a pointer to a object-sized value

  • lock_bit (int) – a bit value between 0 and 31

This is equivalent to GLib.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.

New in version 2.30.

GLib.pointer_bit_trylock(address, lock_bit)[source]
Parameters:

  • address (object) – a pointer to a object-sized value

  • lock_bit (int) – a bit value between 0 and 31

Returns:

True if the lock was acquired

Return type:

bool

This is equivalent to 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.

New in version 2.30.

GLib.pointer_bit_unlock(address, lock_bit)[source]
Parameters:

  • address (object) – a pointer to a object-sized value

  • lock_bit (int) – a bit value between 0 and 31

This is equivalent to GLib.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.

New in version 2.30.

GLib.poll(fds, nfds, timeout)[source]
Parameters:

  • fds (GLib.PollFD) – file descriptors to poll

  • nfds (int) – the number of file descriptors in fds

  • timeout (int) – amount of time to wait, in milliseconds, or -1 to wait forever

Returns:

the number of entries in fds whose revents fields were filled in, or 0 if the operation timed out, or -1 on error or if the call was interrupted.

Return type:

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 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 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 GLib.poll() in code that has to run on Windows, the easiest solution is to construct all of your GLib.PollFDs with g_io_channel_win32_make_pollfd().

New in version 2.20.

GLib.prefix_error_literal(err, prefix)[source]
Parameters:

Prefixes prefix to an existing error message. If err or err is None (i.e.: no error variable) then do nothing.

New in version 2.70.

GLib.propagate_error(src)[source]
Parameters:

src (GLib.Error) – error to move into the return location

Returns:

error return location

Return type:

dest: GLib.Error or None

If dest is None, free src; otherwise, moves src into dest. The error variable dest points to must be None.

src must be non-None.

Note that src is no longer valid after this call. If you want to keep using the same GLib.Error, you need to set it to None after calling this function on it.

GLib.quark_from_static_string(string)[source]
Parameters:

string (str or None) – a string

Returns:

the #GQuark identifying the string, or 0 if string is None

Return type:

int

Gets the #GQuark identifying the given (static) string. If the string does not currently have an associated #GQuark, a new #GQuark is created, linked to the given string.

Note that this function is identical to GLib.quark_from_string() except that if a new #GQuark is created the string itself is used rather than a copy. This saves memory, but can only be used if the string will continue to exist until the program terminates. It can be used with statically allocated strings in the main program, but not with statically allocated memory in dynamically loaded modules, if you expect to ever unload the module again (e.g. do not use this function in GTK theme engines).

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

GLib.quark_from_string(string)[source]
Parameters:

string (str or None) – a string

Returns:

the #GQuark identifying the string, or 0 if string is None

Return type:

int

Gets the #GQuark identifying the given string. If the string does not currently have an associated #GQuark, a new #GQuark is created, using a copy of the string.

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

GLib.quark_to_string(quark)[source]
Parameters:

quark (int) – a #GQuark.

Returns:

the string associated with the #GQuark

Return type:

str

Gets the string associated with the given #GQuark.

GLib.quark_try_string(string)[source]
Parameters:

string (str or None) – a string

Returns:

the #GQuark associated with the string, or 0 if string is None or there is no #GQuark associated with it

Return type:

int

Gets the #GQuark associated with the given string, or 0 if string is None or it has no associated #GQuark.

If you want the GQuark to be created if it doesn’t already exist, use GLib.quark_from_string() or GLib.quark_from_static_string().

This function must not be used before library constructors have finished running.

GLib.random_double()[source]
Returns:

a random number

Return type:

float

Returns a random float equally distributed over the range [0..1).

GLib.random_double_range(begin, end)[source]
Parameters:

  • begin (float) – lower closed bound of the interval

  • end (float) – upper open bound of the interval

Returns:

a random number

Return type:

float

Returns a random float equally distributed over the range [begin..`end`).

GLib.random_int()[source]
Returns:

a random number

Return type:

int

Return a random #guint32 equally distributed over the range [0..2^32-1].

GLib.random_int_range(begin, end)[source]
Parameters:

  • begin (int) – lower closed bound of the interval

  • end (int) – upper open bound of the interval

Returns:

a random number

Return type:

int

Returns a random #gint32 equally distributed over the range [begin..`end`-1].

GLib.random_set_seed(seed)[source]
Parameters:

seed (int) – a value to reinitialize the global random number generator

Sets the seed for the global random number generator, which is used by the g_random_* functions, to seed.

GLib.rc_box_acquire(mem_block)[source]
Parameters:

mem_block (object) – a pointer to reference counted data

Returns:

a pointer to the data, with its reference count increased

Return type:

object

Acquires a reference on the data pointed by mem_block.

New in version 2.58.

GLib.rc_box_alloc(block_size)[source]
Parameters:

block_size (int) – the size of the allocation, must be greater than 0

Returns:

a pointer to the allocated memory

Return type:

object

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.

New in version 2.58.

GLib.rc_box_alloc0(block_size)[source]
Parameters:

block_size (int) – the size of the allocation, must be greater than 0

Returns:

a pointer to the allocated memory

Return type:

object

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.

New in version 2.58.

GLib.rc_box_dup(block_size, mem_block)[source]
Parameters:

  • block_size (int) – the number of bytes to copy, must be greater than 0

  • mem_block (object) – the memory to copy

Returns:

a pointer to the allocated memory

Return type:

object

Allocates a new block of data with reference counting semantics, and copies block_size bytes of mem_block into it.

New in version 2.58.

GLib.rc_box_get_size(mem_block)[source]
Parameters:

mem_block (object) – a pointer to reference counted data

Returns:

the size of the data, in bytes

Return type:

int

Retrieves the size of the reference counted data pointed by mem_block.

New in version 2.58.

GLib.rc_box_release(mem_block)[source]
Parameters:

mem_block (object) – a pointer to reference counted data

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.

New in version 2.58.

GLib.rc_box_release_full(mem_block, clear_func)[source]
Parameters:

  • mem_block (object) – a pointer to reference counted data

  • clear_func (GLib.DestroyNotify) – a function to call when clearing the data

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.

New in version 2.58.

GLib.realloc(mem, n_bytes)[source]
Parameters:

  • mem (object or None) – the memory to reallocate

  • n_bytes (int) – new size of the memory in bytes

Returns:

the new address of the allocated memory

Return type:

object or 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 None, in which case it’s considered to have zero-length. n_bytes may be 0, in which case None will be returned and mem will be freed unless it is None.

If the allocation fails (because the system is out of memory), the program is terminated.

GLib.realloc_n(mem, n_blocks, n_block_bytes)[source]
Parameters:

  • mem (object or None) – the memory to reallocate

  • n_blocks (int) – the number of blocks to allocate

  • n_block_bytes (int) – the size of each block in bytes

Returns:

the new address of the allocated memory

Return type:

object or None

This function is similar to 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.

New in version 2.24.

GLib.ref_count_compare(rc, val)[source]
Parameters:

  • rc (int) – the address of a reference count variable

  • val (int) – the value to compare

Returns:

True if the reference count is the same as the given value

Return type:

bool

Compares the current value of rc with val.

New in version 2.58.

GLib.ref_count_dec(rc)[source]
Parameters:

rc (int) – the address of a reference count variable

Returns:

True if the reference count reached 0, and False otherwise

Return type:

bool

Decreases the reference count.

If True is returned, the reference count reached 0. After this point, rc is an undefined state and must be reinitialized with GLib.ref_count_init() to be used again.

New in version 2.58.

GLib.ref_count_inc(rc)[source]
Parameters:

rc (int) – the address of a reference count variable

Increases the reference count.

New in version 2.58.

GLib.ref_count_init(rc)[source]
Parameters:

rc (int) – the address of a reference count variable

Initializes a reference count variable to 1.

New in version 2.58.

GLib.ref_string_acquire(str)[source]
Parameters:

str (str) – a reference counted string

Returns:

the given string, with its reference count increased

Return type:

str

Acquires a reference on a string.

New in version 2.58.

GLib.ref_string_length(str)[source]
Parameters:

str (str) – a reference counted string

Returns:

the length of the given string, in bytes

Return type:

int

Retrieves the length of str.

New in version 2.58.

GLib.ref_string_new(str)[source]
Parameters:

str (str) – a NUL-terminated string

Returns:

the newly created reference counted string

Return type:

str

Creates a new reference counted string and copies the contents of str into it.

New in version 2.58.

GLib.ref_string_new_intern(str)[source]
Parameters:

str (str) – a NUL-terminated string

Returns:

the newly created reference counted string, or a new reference to an existing string

Return type:

str

Creates a new reference counted string and copies the content of str into it.

If you call this function multiple times with the same str, or with the same contents of str, it will return a new reference, instead of creating a new string.

New in version 2.58.

GLib.ref_string_new_len(str, len)[source]
Parameters:

  • str (str) – a string

  • len (int) – length of str to use, or -1 if str is nul-terminated

Returns:

the newly created reference counted string

Return type:

str

Creates a new reference counted string and copies the contents of str into it, up to len bytes.

Since this function does not stop at nul bytes, it is the caller’s responsibility to ensure that str has at least len addressable bytes.

New in version 2.58.

GLib.ref_string_release(str)[source]
Parameters:

str (str) – a reference counted string

Releases a reference on a string; if it was the last reference, the resources allocated by the string are freed as well.

New in version 2.58.

GLib.regex_check_replacement(replacement)[source]
Parameters:

replacement (str) – the replacement string

Raises:

GLib.Error

Returns:

whether replacement is a valid replacement string

has_references:

location to store information about references in replacement or None

Return type:

(bool, has_references: bool)

Checks whether replacement is a valid replacement string (see GLib.Regex.replace()), i.e. that all escape sequences in it are valid.

If has_references is not None then replacement is checked for pattern references. For instance, replacement text ‘foo\n’ does not contain references and may be evaluated without information about actual match, but ‘\0\1’ (whole match followed by first subpattern) requires valid GLib.MatchInfo object.

New in version 2.14.

GLib.regex_error_quark()[source]
Return type:

int

GLib.regex_escape_nul(string, length)[source]
Parameters:

  • string (str) – the string to escape

  • length (int) – the length of string

Returns:

a newly-allocated escaped string

Return type:

str

Escapes the nul characters in string to “\x00”. It can be used to compile a regex with embedded nul characters.

For completeness, length can be -1 for a nul-terminated string. In this case the output string will be of course equal to string.

New in version 2.30.

GLib.regex_escape_string(string, length)[source]
Parameters:

  • string (str) – the string to escape

  • length (int) – the length of string, in bytes, or -1 if string is nul-terminated

Returns:

a newly-allocated escaped string

Return type:

str

Escapes the special characters used for regular expressions in string, for instance “a.b*c” becomes “a\.b\*c”. This function is useful to dynamically generate regular expressions.

string can contain nul characters that are replaced with “\0”, in this case remember to specify the correct length of string in length.

New in version 2.14.

GLib.regex_match_simple(pattern, string, compile_options, match_options)[source]
Parameters:

  • pattern (str) – the regular expression

  • string (str) – the string to scan for matches

  • compile_options (GLib.RegexCompileFlags) – compile options for the regular expression, or 0

  • match_options (GLib.RegexMatchFlags) – match options, or 0

Returns:

True if the string matched, False otherwise

Return type:

bool

Scans for a match in string for pattern.

This function is equivalent to GLib.Regex.match() but it does not require to compile the pattern with GLib.Regex.new(), avoiding some lines of code when you need just to do a match without extracting substrings, capture counts, and so on.

If this function is to be called on the same pattern more than once, it’s more efficient to compile the pattern once with GLib.Regex.new() and then use GLib.Regex.match().

New in version 2.14.

GLib.regex_split_simple(pattern, string, compile_options, match_options)[source]
Parameters:

  • pattern (str) – the regular expression

  • string (str) – the string to scan for matches

  • compile_options (GLib.RegexCompileFlags) – compile options for the regular expression, or 0

  • match_options (GLib.RegexMatchFlags) – match options, or 0

Returns:

a None-terminated array of strings. Free it using GLib.strfreev()

Return type:

[str]

Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the whole string is returned as the first token.

This function is equivalent to GLib.Regex.split() but it does not require to compile the pattern with GLib.Regex.new(), avoiding some lines of code when you need just to do a split without extracting substrings, capture counts, and so on.

If this function is to be called on the same pattern more than once, it’s more efficient to compile the pattern once with GLib.Regex.new() and then use GLib.Regex.split().

As a special case, the result of splitting the empty string “” is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you’ll need to check for the empty string before calling this function.

A pattern that can match empty strings splits string into separate characters wherever it matches the empty string between characters. For example splitting “ab c” using as a separator “\s*”, you will get “a”, “b” and “c”.

New in version 2.14.

GLib.reload_user_special_dirs_cache()[source]

Resets the cache used for 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 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.

New in version 2.22.

GLib.rmdir(filename)[source]
Parameters:

filename (str) – a pathname in the GLib file name encoding (UTF-8 on Windows)

Returns:

0 if the directory was successfully removed, -1 if an error occurred

Return type:

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.

New in version 2.6.

GLib.sequence_get(iter)[source]
Parameters:

iter (GLib.SequenceIter) – a GLib.SequenceIter

Returns:

the data that iter points to

Return type:

object or None

Returns the data that iter points to.

New in version 2.14.

GLib.sequence_insert_before(iter, data)[source]
Parameters:
Returns:

an iterator pointing to the new item

Return type:

GLib.SequenceIter

Inserts a new item just before the item pointed to by iter.

New in version 2.14.

GLib.sequence_move(src, dest)[source]
Parameters:

Moves the item pointed to by src to the position indicated by dest. After calling this function dest will point to the position immediately after src. It is allowed for src and dest to point into different sequences.

New in version 2.14.

GLib.sequence_move_range(dest, begin, end)[source]
Parameters:

Inserts the (begin, end) range at the destination pointed to by dest. The begin and end iters must point into the same sequence. It is allowed for dest to point to a different sequence than the one pointed into by begin and end.

If dest is None, the range indicated by begin and end is removed from the sequence. If dest points to a place within the (begin, end) range, the range does not move.

New in version 2.14.

GLib.sequence_range_get_midpoint(begin, end)[source]
Parameters:
Returns:

a GLib.SequenceIter pointing somewhere in the (begin, end) range

Return type:

GLib.SequenceIter

Finds an iterator somewhere in the range (begin, end). This iterator will be close to the middle of the range, but is not guaranteed to be exactly in the middle.

The begin and end iterators must both point to the same sequence and begin must come before or be equal to end in the sequence.

New in version 2.14.

GLib.sequence_remove(iter)[source]
Parameters:

iter (GLib.SequenceIter) – a GLib.SequenceIter

Removes the item pointed to by iter. It is an error to pass the end iterator to this function.

If the sequence has a data destroy function associated with it, this function is called on the data for the removed item.

New in version 2.14.

GLib.sequence_remove_range(begin, end)[source]
Parameters:

Removes all items in the (begin, end) range.

If the sequence has a data destroy function associated with it, this function is called on the data for the removed items.

New in version 2.14.

GLib.sequence_set(iter, data)[source]
Parameters:

Changes the data for the item pointed to by iter to be data. If the sequence has a data destroy function associated with it, that function is called on the existing data that iter pointed to.

New in version 2.14.

GLib.sequence_swap(a, b)[source]
Parameters:

Swaps the items pointed to by a and b. It is allowed for a and b to point into difference sequences.

New in version 2.14.

GLib.set_application_name(application_name)[source]
Parameters:

application_name (str) – localized name of the application

Sets a human-readable name for the application. This name should be localized if possible, and is intended for display to the user. Contrast with GLib.set_prgname(), which sets a non-localized name. GLib.set_prgname() will be called automatically by gtk_init(), but 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.

New in version 2.2.

GLib.set_error_literal(domain, code, message)[source]
Parameters:

  • domain (int) – error domain

  • code (int) – error code

  • message (str) – error message

Returns:

a return location for a GLib.Error

Return type:

err: GLib.Error

Does nothing if err is None; if err is non-None, then err must be None. A new GLib.Error is created and assigned to err. Unlike g_set_error(), message is not a printf()-style format string. Use this function if message contains text you don’t have control over, that could include printf() escape sequences.

New in version 2.18.

GLib.set_prgname(prgname)[source]
Parameters:

prgname (str) – the name of the program.

Sets the name of the program. This name should not be localized, in contrast to 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.

GLib.setenv(variable, value, overwrite)[source]
Parameters:

  • variable (str) – the environment variable to set, must not contain ‘=’.

  • value (str) – the value for to set the variable to.

  • overwrite (bool) – whether to change the variable if it already exists.

Returns:

False if the environment variable couldn’t be set.

Return type:

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 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 GLib.get_environ() to get an environment array, modify that with GLib.environ_setenv() and GLib.environ_unsetenv(), and then pass that array directly to execvpe(), GLib.spawn_async(), or the like.

New in version 2.4.

GLib.shell_error_quark()[source]
Return type:

int

GLib.shell_parse_argv(command_line)[source]
Parameters:

command_line (str) – command line to parse

Raises:

GLib.Error

Returns:

True on success, False if error set

argvp:

return location for array of args

Return type:

(bool, argvp: [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), 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 GLib.strfreev().

GLib.shell_quote(unquoted_string)[source]
Parameters:

unquoted_string (str) – a literal string

Returns:

quoted string

Return type:

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

The quoting style used is undefined (single or double quotes may be used).

GLib.shell_unquote(quoted_string)[source]
Parameters:

quoted_string (str) – shell-quoted string

Raises:

GLib.Error

Returns:

an unquoted string

Return type:

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 GLib.shell_quote(). If it fails, it returns None and sets the error.

The quoted_string need not actually contain quoted or escaped text; 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 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.

GLib.slice_alloc(block_size)[source]
Parameters:

block_size (int) – the number of bytes to allocate

Returns:

a pointer to the allocated memory block, which will be None if and only if mem_size is 0

Return type:

object or 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.

New in version 2.10.

GLib.slice_alloc0(block_size)[source]
Parameters:

block_size (int) – the number of bytes to allocate

Returns:

a pointer to the allocated block, which will be None if and only if mem_size is 0

Return type:

object or None

Allocates a block of memory via GLib.slice_alloc() and initializes the returned memory to 0.

Since GLib 2.76 this always uses the system malloc() implementation internally.

New in version 2.10.

GLib.slice_copy(block_size, mem_block)[source]
Parameters:

  • block_size (int) – the number of bytes to allocate

  • mem_block (object or None) – the memory to copy

Returns:

a pointer to the allocated memory block, which will be None if and only if mem_size is 0

Return type:

object or None

Allocates a block of memory from the slice allocator and copies block_size bytes into it from mem_block.

mem_block must be non-None if block_size is non-zero.

Since GLib 2.76 this always uses the system malloc() implementation internally.

New in version 2.14.

GLib.slice_free1(block_size, mem_block)[source]
Parameters:

  • block_size (int) – the size of the block

  • mem_block (object or None) – a pointer to the block to free

Frees a block of memory.

The memory must have been allocated via GLib.slice_alloc() or 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 None, this function does nothing.

Since GLib 2.76 this always uses the system free_sized() implementation internally.

New in version 2.10.

GLib.slice_free_chain_with_offset(block_size, mem_chain, next_offset)[source]
Parameters:

  • block_size (int) – the size of the blocks

  • mem_chain (object or None) – a pointer to the first block of the chain

  • next_offset (int) – the offset of the next field in the blocks

Frees a linked list of memory blocks of structure type type.

The memory blocks must be equal-sized, allocated via GLib.slice_alloc() or GLib.slice_alloc0() and linked together by a next pointer (similar to GLib.SList). 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 None, this function does nothing.

Since GLib 2.76 this always uses the system free_sized() implementation internally.

New in version 2.10.

GLib.slice_get_config(ckey)[source]
Parameters:

ckey (GLib.SliceConfig) –

Return type:

int

GLib.slice_get_config_state(ckey, address, n_values)[source]
Parameters:
Return type:

int

GLib.slice_set_config(ckey, value)[source]
Parameters:
GLib.source_remove(tag)[source]
Parameters:

tag (int) – the ID of the source to remove.

Returns:

True if the source was found and removed.

Return type:

bool

Removes the source with the given ID from the default main context. You must use GLib.Source.destroy() for sources added to a non-default main context.

The ID of a GLib.Source is given by GLib.Source.get_id(), or will be returned by the functions GLib.Source.attach(), GLib.idle_add(), GLib.idle_add(), GLib.timeout_add(), GLib.timeout_add(), GLib.child_watch_add(), GLib.child_watch_add(), GLib.io_add_watch(), and GLib.io_add_watch().

It is a programmer error to attempt to remove a non-existent source.

More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with GLib.idle_add(): the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source.

GLib.source_remove_by_funcs_user_data(funcs, user_data)[source]
Parameters:
Returns:

True if a source was found and removed.

Return type:

bool

Removes a source from the default main loop context given the source functions and user data. If multiple sources exist with the same source functions and user data, only one will be destroyed.

GLib.source_remove_by_user_data(user_data)[source]
Parameters:

user_data (object or None) – the user_data for the callback.

Returns:

True if a source was found and removed.

Return type:

bool

Removes a source from the default main loop context given the user data for the callback. If multiple sources exist with the same user data, only one will be destroyed.

GLib.source_set_name_by_id(tag, name)[source]
Parameters:

Sets the name of a source using its ID.

This is a convenience utility to set source names from the return value of GLib.idle_add(), GLib.timeout_add(), etc.

It is a programmer error to attempt to set the name of a non-existent source.

More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with GLib.idle_add(): the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source.

New in version 2.26.

GLib.spaced_primes_closest(num)[source]
Parameters:

num (int) – a int

Returns:

the smallest prime number from a built-in array of primes which is larger than num

Return type:

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

GLib.spawn_async(argv, envp=None, working_directory=None, flags=GLib.SpawnFlags.DEFAULT, child_setup=None, user_data=None, standard_input=False, standard_output=False, standard_error=False)[source]
Parameters:
Raises:

GLib.Error

Returns:

pid:

child process ID

stdin:

file descriptor to child’s stdin, or None

stdout:

file descriptor to read child’s stdout, or None

stderr:

file descriptor to read child’s stderr, or None

Return type:

(pid: int, stdin: int or None, stdout: int or None, stderr: int or None)

See GLib.spawn_async_with_pipes() for a full description; this function simply calls the GLib.spawn_async_with_pipes()

You should call GLib.spawn_close_pid() on the returned child process reference when you don’t need it any more.

In case standard_input/standard_output/standard_error are True a file descriptor is returned which needs to be closed by the caller after it is no longer needed.

GLib.spawn_async_with_fds(working_directory, argv, envp, flags, child_setup, user_data, stdin_fd, stdout_fd, stderr_fd)[source]
Parameters:

  • working_directory (str or None) – child’s current working directory, or None to inherit parent’s, in the GLib file name encoding

  • argv ([str]) – child’s argument vector, in the GLib file name encoding; it must be non-empty and None-terminated

  • envp ([str] or None) – child’s environment, or None to inherit parent’s, in the GLib file name encoding

  • flags (GLib.SpawnFlags) – flags from GLib.SpawnFlags

  • child_setup (GLib.SpawnChildSetupFunc or None) – function to run in the child just before exec()

  • user_data (object or None) – user data for child_setup

  • stdin_fd (int) – file descriptor to use for child’s stdin, or -1

  • stdout_fd (int) – file descriptor to use for child’s stdout, or -1

  • stderr_fd (int) – file descriptor to use for child’s stderr, or -1

Raises:

GLib.Error

Returns:

True on success, False if an error was set

child_pid:

return location for child process ID, or None

Return type:

(bool, child_pid: int)

Executes a child program asynchronously.

Identical to GLib.spawn_async_with_pipes_and_fds() but with n_fds set to zero, so no FD assignments are used.

New in version 2.58.

GLib.spawn_async_with_pipes(working_directory, argv, envp, flags, child_setup, *user_data)[source]
Parameters:

  • working_directory (str or None) – child’s current working directory, or None to inherit parent’s, in the GLib file name encoding

  • argv ([str]) – child’s argument vector, in the GLib file name encoding; it must be non-empty and None-terminated

  • envp ([str] or None) – child’s environment, or None to inherit parent’s, in the GLib file name encoding

  • flags (GLib.SpawnFlags) – flags from GLib.SpawnFlags

  • child_setup (GLib.SpawnChildSetupFunc or None) – function to run in the child just before exec()

  • user_data (object or None) – user data for child_setup

Raises:

GLib.Error

Returns:

True on success, False if an error was set

child_pid:

return location for child process ID, or None

standard_input:

return location for file descriptor to write to child’s stdin, or None

standard_output:

return location for file descriptor to read child’s stdout, or None

standard_error:

return location for file descriptor to read child’s stderr, or None

Return type:

(bool, child_pid: int, standard_input: int, standard_output: int, standard_error: int)

Identical to GLib.spawn_async_with_pipes_and_fds() but with n_fds set to zero, so no FD assignments are used.

GLib.spawn_async_with_pipes_and_fds(working_directory, argv, envp, flags, child_setup, user_data, stdin_fd, stdout_fd, stderr_fd, source_fds, target_fds)[source]
Parameters:

  • working_directory (str or None) – child’s current working directory, or None to inherit parent’s, in the GLib file name encoding

  • argv ([str]) – child’s argument vector, in the GLib file name encoding; it must be non-empty and None-terminated

  • envp ([str] or None) – child’s environment, or None to inherit parent’s, in the GLib file name encoding

  • flags (GLib.SpawnFlags) – flags from GLib.SpawnFlags

  • child_setup (GLib.SpawnChildSetupFunc or None) – function to run in the child just before exec()

  • user_data (object or None) – user data for child_setup

  • stdin_fd (int) – file descriptor to use for child’s stdin, or -1

  • stdout_fd (int) – file descriptor to use for child’s stdout, or -1

  • stderr_fd (int) – file descriptor to use for child’s stderr, or -1

  • source_fds ([int] or None) – array of FDs from the parent process to make available in the child process

  • target_fds ([int] or None) – array of FDs to remap source_fds to in the child process

Raises:

GLib.Error

Returns:

True on success, False if an error was set

child_pid_out:

return location for child process ID, or None

stdin_pipe_out:

return location for file descriptor to write to child’s stdin, or None

stdout_pipe_out:

return location for file descriptor to read child’s stdout, or None

stderr_pipe_out:

return location for file descriptor to read child’s stderr, or None

Return type:

(bool, child_pid_out: int, stdin_pipe_out: int, stdout_pipe_out: int, stderr_pipe_out: 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 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 GLib.SpawnFlags.SEARCH_PATH flag, the PATH environment variable is used to search for the executable. If flags contains the GLib.SpawnFlags.SEARCH_PATH_FROM_ENVP flag, the PATH variable from envp is used to search for the executable. If both the GLib.SpawnFlags.SEARCH_PATH and 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 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 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, 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 None-terminated array of strings, where each string has the form KEY=VALUE. This will become the child’s environment. If envp is 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 GLib.SpawnFlags.DO_NOT_REAP_CHILD means that the child will not automatically be reaped; you must use a child watch (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 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 GLib.spawn_close_pid() is equivalent to calling CloseHandle() on the process handle returned in child_pid). See GLib.child_watch_add().

Open UNIX file descriptors marked as FD_CLOEXEC will be automatically closed in the child process. 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. GLib.SpawnFlags.SEARCH_PATH means that argv[0] need not be an absolute path, it will be looked for in the PATH environment variable. 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 GLib.SpawnFlags.SEARCH_PATH and GLib.SpawnFlags.SEARCH_PATH_FROM_ENVP are used, the value from envp takes precedence over the environment.

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

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

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

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 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-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 GLib.child_watch_add() (or waitpid()) if you specified the 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 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 GLib.spawn_close_pid() when you no longer need it.

If non-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 GLib.spawn_async_with_pipes() must close these file descriptors when they are no longer in use. If these parameters are None, the corresponding pipe won’t be created.

If stdin_pipe_out is None, the child’s standard input is attached to /dev/null unless GLib.SpawnFlags.CHILD_INHERITS_STDIN is set.

If stderr_pipe_out is None, the child’s standard error goes to the same location as the parent’s standard error unless GLib.SpawnFlags.STDERR_TO_DEV_NULL is set.

If stdout_pipe_out is None, the child’s standard output goes to the same location as the parent’s standard output unless GLib.SpawnFlags.STDOUT_TO_DEV_NULL is set.

error can be None to ignore errors, or non-None to report errors. If an error is set, the function returns False. Errors are reported even if they occur in the child (for example if the executable in @argv[0] is not found). Typically the message field of returned errors should be displayed to users. Possible errors are those from the %G_SPAWN_ERROR domain.

If an error occurs, child_pid, stdin_pipe_out, stdout_pipe_out, and stderr_pipe_out will not be filled with valid values.

If child_pid is not None and an error does not occur then the returned process reference must be closed using 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:

GLib.SpawnFlags.DO_NOT_REAP_CHILD is set

GLib.SpawnFlags.LEAVE_DESCRIPTORS_OPEN is set

GLib.SpawnFlags.SEARCH_PATH_FROM_ENVP is not set

working_directory is None

child_setup is 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.

New in version 2.68.

GLib.spawn_check_exit_status(wait_status)[source]
Parameters:

wait_status (int) – A status as returned from GLib.spawn_sync()

Raises:

GLib.Error

Returns:

True if child exited successfully, False otherwise (and error will be set)

Return type:

bool

An old name for 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 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().

New in version 2.34.

Deprecated since version 2.70: Use GLib.spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses.

GLib.spawn_check_wait_status(wait_status)[source]
Parameters:

wait_status (int) – A platform-specific wait status as returned from GLib.spawn_sync()

Raises:

GLib.Error

Returns:

True if child exited successfully, False otherwise (and error will be set)

Return type:

bool

Set error if wait_status indicates the child exited abnormally (e.g. with a nonzero exit code, or via a fatal signal).

The GLib.spawn_sync() and 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 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 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, GLib.spawn_check_exit_status() provides the same functionality, although under a misleading name.

New in version 2.70.

GLib.spawn_close_pid(pid)[source]
Parameters:

pid (int) – The process reference to close

On some platforms, notably Windows, the #GPid type represents a resource which must be closed to prevent resource leaking. 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.

GLib.spawn_command_line_async(command_line)[source]
Parameters:

command_line (str) – a command line

Raises:

GLib.Error

Returns:

True on success, False if error is set

Return type:

bool

A simple version of GLib.spawn_async() that parses a command line with GLib.shell_parse_argv() and passes it to GLib.spawn_async().

Runs a command line in the background. Unlike GLib.spawn_async(), the GLib.SpawnFlags.SEARCH_PATH flag is enabled, other flags are not. Note that GLib.SpawnFlags.SEARCH_PATH can have security implications, so consider using GLib.spawn_async() directly if appropriate. Possible errors are those from GLib.shell_parse_argv() and GLib.spawn_async().

The same concerns on Windows apply as for GLib.spawn_command_line_sync().

GLib.spawn_command_line_sync(command_line)[source]
Parameters:

command_line (str) – a command line

Raises:

GLib.Error

Returns:

True on success, False if an error was set

standard_output:

return location for child output

standard_error:

return location for child errors

wait_status:

return location for child wait status, as returned by waitpid()

Return type:

(bool, standard_output: bytes, standard_error: bytes, wait_status: int)

A simple version of GLib.spawn_sync() with little-used parameters removed, taking a command line instead of an argument vector.

See GLib.spawn_sync() for full details.

The command_line argument will be parsed by GLib.shell_parse_argv().

Unlike GLib.spawn_sync(), the GLib.SpawnFlags.SEARCH_PATH flag is enabled. Note that GLib.SpawnFlags.SEARCH_PATH can have security implications, so consider using GLib.spawn_sync() directly if appropriate.

Possible errors are those from GLib.spawn_sync() and those from GLib.shell_parse_argv().

If wait_status is non-None, the platform-specific status of the child is stored there; see the documentation of 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 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’”.

GLib.spawn_error_quark()[source]
Return type:

int

GLib.spawn_exit_error_quark()[source]
Return type:

int

GLib.spawn_sync(working_directory, argv, envp, flags, child_setup, *user_data)[source]
Parameters:
Raises:

GLib.Error

Returns:

True on success, False if an error was set

standard_output:

return location for child output, or None

standard_error:

return location for child error messages, or None

wait_status:

return location for child wait status, as returned by waitpid(), or None

Return type:

(bool, standard_output: bytes, standard_error: bytes, wait_status: 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-None. Note that you must set the GLib.SpawnFlags.STDOUT_TO_DEV_NULL and GLib.SpawnFlags.STDERR_TO_DEV_NULL flags when passing None for standard_output and standard_error.

If wait_status is non-None, the platform-specific status of the child is stored there; see the documentation of 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 GLib.SpawnFlags.DO_NOT_REAP_CHILD in flags, and on POSIX platforms, the same restrictions as for 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 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.

GLib.stpcpy(dest, src)[source]
Parameters:

  • dest (str) – destination buffer.

  • src (str) – source string.

Returns:

a pointer to the trailing nul byte in dest.

Return type:

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.

GLib.str_equal(v1, v2)[source]
Parameters:

  • v1 (object) – a key

  • v2 (object) – a key to compare with v1

Returns:

True if the two keys match

Return type:

bool

Compares two strings for byte-by-byte equality and returns True if they are equal. It can be passed to g_hash_table_new() as the key_equal_func parameter, when using non-None strings as keys in a GLib.HashTable.

This function is typically used for hash table comparisons, but can be used for general purpose comparisons of non-None strings. For a None-safe string comparison function, see GLib.strcmp0().

GLib.str_has_prefix(str, prefix)[source]
Parameters:

  • str (str) – a nul-terminated string

  • prefix (str) – the nul-terminated prefix to look for

Returns:

True if str begins with prefix, False otherwise.

Return type:

bool

Looks whether the string str begins with prefix.

New in version 2.2.

GLib.str_has_suffix(str, suffix)[source]
Parameters:

  • str (str) – a nul-terminated string

  • suffix (str) – the nul-terminated suffix to look for

Returns:

True if str end with suffix, False otherwise.

Return type:

bool

Looks whether the string str ends with suffix.

New in version 2.2.

GLib.str_hash(v)[source]
Parameters:

v (object) – a string key

Returns:

a hash value corresponding to the key

Return type:

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 g_hash_table_new() as the hash_func parameter, when using non-None strings as keys in a 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.

GLib.str_is_ascii(str)[source]
Parameters:

str (str) – a string

Returns:

True if str is ASCII

Return type:

bool

Determines if a string is pure ASCII. A string is pure ASCII if it contains no bytes with the high bit set.

New in version 2.40.

GLib.str_match_string(search_term, potential_hit, accept_alternates)[source]
Parameters:

  • search_term (str) – the search term from the user

  • potential_hit (str) – the text that may be a hit

  • accept_alternates (bool) – True to accept ASCII alternates

Returns:

True if potential_hit is a hit

Return type:

bool

Checks if a search conducted for search_term should match potential_hit.

This function calls 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 GLib.str_tokenize_and_fold() on each string in your corpus and build an index on the returned folded tokens, then call GLib.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).

New in version 2.40.

GLib.str_to_ascii(str, from_locale)[source]
Parameters:

  • str (str) – a string, in UTF-8

  • from_locale (str or None) – the source locale, if known

Returns:

a string in plain ASCII

Return type:

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

New in version 2.40.

GLib.str_tokenize_and_fold(string, translit_locale)[source]
Parameters:

  • string (str) – a string

  • translit_locale (str or None) – the language code (like ‘de’ or ‘en_GB’) from which string originates

Returns:

the folded tokens

ascii_alternates:

a return location for ASCII alternates

Return type:

([str], ascii_alternates: [str])

Tokenises string and performs folding on each token.

A token is a non-empty sequence of alphanumeric characters in the source string, separated by non-alphanumeric characters. An “alphanumeric” character for this purpose is one that matches GLib.unichar_isalnum() or GLib.unichar_ismark().

Each token is then (Unicode) normalised and case-folded. If ascii_alternates is non-None 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.

New in version 2.40.

GLib.strcanon(string, valid_chars, substitutor)[source]
Parameters:

  • string (str) – a nul-terminated array of bytes

  • valid_chars (str) – bytes permitted in string

  • substitutor (int) – replacement character for disallowed bytes

Returns:

the modified string

Return type:

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:

g_ascii_strup (g_strcanon (str, "abc", '?'))

In order to modify a copy, you may use GLib.strdup():

reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
...
g_free (reformatted);
GLib.strcasecmp(s1, s2)[source]
Parameters:

  • s1 (str) – a string

  • s2 (str) – a string to compare with s1

Returns:

0 if the strings match, a negative value if s1 < s2, or a positive value if s1 > s2.

Return type:

int

A case-insensitive string comparison, corresponding to the standard strcasecmp() function on platforms which support it.

Deprecated since version 2.2: See GLib.strncasecmp() for a discussion of why this function is deprecated and how to replace it.

GLib.strchomp(string)[source]
Parameters:

string (str) – a string to remove the trailing whitespace from

Returns:

string

Return type:

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 GLib.strchug() and g_strstrip().

GLib.strchug(string)[source]
Parameters:

string (str) – a string to remove the leading whitespace from

Returns:

string

Return type:

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 GLib.strchomp() and g_strstrip().

GLib.strcmp0(str1, str2)[source]
Parameters:
Returns:

an integer less than, equal to, or greater than zero, if str1 is <, == or > than str2.

Return type:

int

Compares str1 and str2 like strcmp(). Handles None gracefully by sorting it before non-None strings. Comparing two None pointers returns 0.

New in version 2.16.

GLib.strcompress(source)[source]
Parameters:

source (str) – a string to compress

Returns:

a newly-allocated copy of source with all escaped character compressed

Return type:

str

Replaces all escaped characters with their one byte equivalent.

This function does the reverse conversion of GLib.strescape().

GLib.strdelimit(string, delimiters, new_delimiter)[source]
Parameters:

  • string (str) – the string to convert

  • delimiters (str or None) – a string containing the current delimiters, or None to use the standard delimiters defined in GLib.STR_DELIMITERS

  • new_delimiter (int) – the new delimiter character

Returns:

the modified string

Return type:

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:

g_ascii_strup (g_strdelimit (str, "abc", '?'))

In order to modify a copy, you may use GLib.strdup():

reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
...
g_free (reformatted);
GLib.strdown(string)[source]
Parameters:

string (str) – the string to convert.

Returns:

the string

Return type:

str

Converts a string to lower case.

Deprecated since version 2.2: This function is totally broken for the reasons discussed in the GLib.strncasecmp() docs - use GLib.ascii_strdown() or GLib.utf8_strdown() instead.

GLib.strdup(str)[source]
Parameters:

str (str or None) – the string to duplicate

Returns:

a newly-allocated copy of str

Return type:

str

Duplicates a string. If str is None it returns None. The returned string should be freed with GLib.free() when no longer needed.

GLib.strerror(errnum)[source]
Parameters:

errnum (int) – the system error number. See the standard C %errno documentation

Returns:

a UTF-8 string describing the error code. If the error code is unknown, it returns a string like “Unknown error: <code>”.

Return type:

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.

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:

int saved_errno;

ret = read (blah);
saved_errno = errno;

g_strerror (saved_errno);
GLib.strescape(source, exceptions)[source]
Parameters:

  • source (str) – a string to escape

  • exceptions (str or None) – a string of characters not to escape in source

Returns:

a newly-allocated copy of source with certain characters escaped. See above.

Return type:

str

Escapes the special characters ‘\b’, ‘\f’, ‘\n’, ‘\r’, ‘\t’, ‘\v’, ‘\’ and ‘”’ in the string source by inserting a ‘\’ before them. Additionally all characters in the range 0x01-0x1F (everything below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are replaced with a ‘\’ followed by their octal representation. Characters supplied in exceptions are not escaped.

GLib.strcompress() does the reverse conversion.

GLib.strfreev(str_array)[source]
Parameters:

str_array (str or None) – a None-terminated array of strings to free

Frees a None-terminated array of strings, as well as each string it contains.

If str_array is None, this function simply returns.

GLib.strip_context(msgid, msgval)[source]
Parameters:

  • msgid (str) – a string

  • msgval (str) – another string

Returns:

msgval, unless msgval is identical to msgid and contains a ‘|’ character, in which case a pointer to the substring of msgid after the first ‘|’ character is returned.

Return type:

str

An auxiliary function for gettext() support (see Q_()).

New in version 2.4.

GLib.strjoinv(separator, str_array)[source]
Parameters:

  • separator (str or None) – a string to insert between each of the strings, or None

  • str_array (str) – a None-terminated array of strings to join

Returns:

a newly-allocated string containing all of the strings joined together, with separator between them

Return type:

str

Joins a number of strings together to form one long string, with the optional separator inserted between each of them. The returned string should be freed with GLib.free().

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.

GLib.strlcat(dest, src, dest_size)[source]
Parameters:

  • dest (str) – destination buffer, already containing one nul-terminated string

  • src (str) – source buffer

  • dest_size (int) – length of dest buffer in bytes (not length of existing string inside dest)

Returns:

size of attempted result, which is MIN (dest_size, strlen (original dest)) + strlen (src), so if retval >= dest_size, truncation occurred.

Return type:

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 g_strconcat() is harder to mess up.

GLib.strlcpy(dest, src, dest_size)[source]
Parameters:

  • dest (str) – destination buffer

  • src (str) – source buffer

  • dest_size (int) – length of dest in bytes

Returns:

length of src

Return type:

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, GLib.strdup() is an even better idea.

GLib.strncasecmp(s1, s2, n)[source]
Parameters:

  • s1 (str) – a string

  • s2 (str) – a string to compare with s1

  • n (int) – the maximum number of characters to compare

Returns:

0 if the strings match, a negative value if s1 < s2, or a positive value if s1 > s2.

Return type:

int

A case-insensitive string comparison, corresponding to the standard strncasecmp() function on platforms which support it. It is similar to GLib.strcasecmp() except it only compares the first n characters of the strings.

Deprecated since version 2.2: The problem with GLib.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 GLib.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: GLib.ascii_strncasecmp(), which only works on ASCII and is not locale-sensitive, and GLib.utf8_casefold() followed by strcmp() on the resulting strings, which is good for case-insensitive sorting of UTF-8.

GLib.strndup(str, n)[source]
Parameters:

  • str (str) – the string to duplicate

  • n (int) – the maximum number of bytes to copy from str

Returns:

a newly-allocated buffer containing the first n bytes of str, nul-terminated

Return type:

str

Duplicates the first n bytes of a string, returning a newly-allocated buffer n + 1 bytes long which will always be nul-terminated. If str is less than n bytes long the buffer is padded with nuls. If str is None it returns None. The returned value should be freed when no longer needed.

To copy a number of characters from a UTF-8 encoded string, use GLib.utf8_strncpy() instead.

GLib.strnfill(length, fill_char)[source]
Parameters:

  • length (int) – the length of the new string

  • fill_char (int) – the byte to fill the string with

Returns:

a newly-allocated string filled the fill_char

Return type:

str

Creates a new string length bytes long filled with fill_char. The returned string should be freed when no longer needed.

GLib.strreverse(string)[source]
Parameters:

string (str) – the string to reverse

Returns:

the same pointer passed in as string

Return type:

str

Reverses all of the bytes in a string. For example, g_strreverse ("abcdef") will result in “fedcba”.

Note that GLib.strreverse() doesn’t work on UTF-8 strings containing multibyte characters. For that purpose, use GLib.utf8_strreverse().

GLib.strrstr(haystack, needle)[source]
Parameters:

  • haystack (str) – a nul-terminated string

  • needle (str) – the nul-terminated string to search for

Returns:

a pointer to the found occurrence, or None if not found.

Return type:

str

Searches the string haystack for the last occurrence of the string needle.

GLib.strrstr_len(haystack, haystack_len, needle)[source]
Parameters:

  • haystack (str) – a nul-terminated string

  • haystack_len (int) – the maximum length of haystack in bytes. A length of -1 can be used to mean “search the entire string”, like GLib.strrstr().

  • needle (str) – the nul-terminated string to search for

Returns:

a pointer to the found occurrence, or None if not found.

Return type:

str

Searches the string haystack for the last occurrence of the string needle, limiting the length of the search to haystack_len.

GLib.strsignal(signum)[source]
Parameters:

signum (int) – the signal number. See the signal documentation

Returns:

a UTF-8 string describing the signal. If the signal is unknown, it returns “unknown signal (<signum>)”.

Return type:

str

Returns a string describing the given signal, e.g. “Segmentation fault”. You should use this function in preference to strsignal(), because it returns a string in UTF-8 encoding, and since not all platforms support the strsignal() function.

GLib.strsplit(string, delimiter, max_tokens)[source]
Parameters:

  • string (str) – a string to split

  • delimiter (str) – a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless max_tokens is reached.

  • max_tokens (int) – the maximum number of pieces to split string into. If this is less than 1, the string is split completely.

Returns:

a newly-allocated None-terminated array of strings. Use GLib.strfreev() to free it.

Return type:

[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 GLib.strsplit (”:a:bc::d:”, “:”, -1) is a None-terminated vector containing the six strings “”, “a”, “bc”, “”, “d” and “”.

As a special case, the result of splitting the empty string “” is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you’ll need to check for the empty string before calling GLib.strsplit().

GLib.strsplit_set(string, delimiters, max_tokens)[source]
Parameters:

  • string (str) – The string to be tokenized

  • delimiters (str) – A nul-terminated string containing bytes that are used to split the string (it can accept an empty string, which will result in no string splitting).

  • max_tokens (int) – The maximum number of tokens to split string into. If this is less than 1, the string is split completely

Returns:

a newly-allocated None-terminated array of strings. Use GLib.strfreev() to free it.

Return type:

[str]

Splits string into a number of tokens not containing any of the characters in delimiter. A token is the (possibly empty) longest string that does not contain any of the characters in delimiters. If max_tokens is reached, the remainder is appended to the last token.

For example the result of GLib.strsplit_set (“abc:def/ghi”, “:/”, -1) is a None-terminated vector containing the three strings “abc”, “def”, and “ghi”.

The result of GLib.strsplit_set (”:def/ghi:”, “:/”, -1) is a None-terminated vector containing the four strings “”, “def”, “ghi”, and “”.

As a special case, the result of splitting the empty string “” is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you’ll need to check for the empty string before calling GLib.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.

New in version 2.4.

GLib.strstr_len(haystack, haystack_len, needle)[source]
Parameters:

  • haystack (str) – a nul-terminated string

  • haystack_len (int) – the maximum length of haystack in bytes. A length of -1 can be used to mean “search the entire string”, like strstr().

  • needle (str) – the string to search for

Returns:

a pointer to the found occurrence, or None if not found.

Return type:

str

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

GLib.strtod(nptr)[source]
Parameters:

nptr (str) – the string to convert to a numeric value.

Returns:

the float value.

endptr:

if non-None, it returns the character after the last character used in the conversion.

Return type:

(float, endptr: str)

Converts a string to a float 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 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 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.

GLib.strup(string)[source]
Parameters:

string (str) – the string to convert

Returns:

the string

Return type:

str

Converts a string to upper case.

Deprecated since version 2.2: This function is totally broken for the reasons discussed in the GLib.strncasecmp() docs - use GLib.ascii_strup() or GLib.utf8_strup() instead.

GLib.strv_contains(strv, str)[source]
Parameters:

  • strv (str) – a None-terminated array of strings

  • str (str) – a string

Returns:

True if str is an element of strv, according to GLib.str_equal().

Return type:

bool

Checks if strv contains str. strv must not be None.

New in version 2.44.

GLib.strv_equal(strv1, strv2)[source]
Parameters:

  • strv1 (str) – a None-terminated array of strings

  • strv2 (str) – another None-terminated array of strings

Returns:

True if strv1 and strv2 are equal

Return type:

bool

Checks if strv1 and strv2 contain exactly the same elements in exactly the same order. Elements are compared using GLib.str_equal(). To match independently of order, sort the arrays first (using g_qsort_with_data() or similar).

Two empty arrays are considered equal. Neither strv1 not strv2 may be None.

New in version 2.60.

GLib.strv_get_type()
Return type:

GObject.GType

GLib.strv_length(str_array)[source]
Parameters:

str_array (str) – a None-terminated array of strings

Returns:

length of str_array.

Return type:

int

Returns the length of the given None-terminated string array str_array. str_array must not be None.

New in version 2.6.

GLib.test_add_data_func(testpath, test_data, test_func)[source]
Parameters:

  • testpath (str) – /-separated test case path name for the test.

  • test_data (object or None) – Test data argument for the test function.

  • test_func (GLib.TestDataFunc) – The test function to invoke for this test.

Create a new test case, similar to g_test_create_case(). However the test is assumed to use no fixture, and test suites are automatically created on the fly and added to the root fixture, based on the slash-separated portions of testpath. The test_data argument will be passed as first argument to test_func.

If testpath includes the component “subprocess” anywhere in it, the test will be skipped by default, and only run if explicitly required via the -p command-line option or GLib.test_trap_subprocess().

No component of testpath may start with a dot (.) if the GLib.TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to do so even if it isn’t.

New in version 2.16.

GLib.test_add_data_func_full(testpath, test_data, test_func)[source]
Parameters:

  • testpath (str) – /-separated test case path name for the test.

  • test_data (object or None) – Test data argument for the test function.

  • test_func (GLib.TestDataFunc) – The test function to invoke for this test.

Create a new test case, as with GLib.test_add_data_func(), but freeing test_data after the test run is complete.

New in version 2.34.

GLib.test_add_func(testpath, test_func)[source]
Parameters:

  • testpath (str) – /-separated test case path name for the test.

  • test_func (GLib.TestFunc) – The test function to invoke for this test.

Create a new test case, similar to g_test_create_case(). However the test is assumed to use no fixture, and test suites are automatically created on the fly and added to the root fixture, based on the slash-separated portions of testpath.

If testpath includes the component “subprocess” anywhere in it, the test will be skipped by default, and only run if explicitly required via the -p command-line option or GLib.test_trap_subprocess().

No component of testpath may start with a dot (.) if the GLib.TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to do so even if it isn’t.

New in version 2.16.

GLib.test_assert_expected_messages_internal(domain, file, line, func)[source]
Parameters:

  • domain (str) –

  • file (str) –

  • line (int) –

  • func (str) –

GLib.test_bug(bug_uri_snippet)[source]
Parameters:

bug_uri_snippet (str) – Bug specific bug tracker URI or URI portion.

This function adds a message to test reports that associates a bug URI with a test case.

Bug URIs are constructed from a base URI set with GLib.test_bug_base() and bug_uri_snippet. If GLib.test_bug_base() has not been called, it is assumed to be the empty string, so a full URI can be provided to 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.

New in version 2.16.

GLib.test_bug_base(uri_pattern)[source]
Parameters:

uri_pattern (str) – the base pattern for bug URIs

Specify the base URI for bug reports.

The base URI is used to construct bug report messages for g_test_message() when 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 GLib.test_bug_base() is not called, bug URIs are formed solely from the value provided by GLib.test_bug().

New in version 2.16.

GLib.test_disable_crash_reporting()[source]

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.

New in version 2.78.

GLib.test_expect_message(log_domain, log_level, pattern)[source]
Parameters:

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 (g_log() without %G_LOG_USE_STRUCTURED defined). It will not work with the structured logging API. See Testing for Messages.

Use g_test_assert_expected_messages() to assert that all previously-expected messages have been seen and suppressed.

You can call this multiple times in a row, if multiple messages are expected as a result of a single call. (The messages must appear in the same order as the calls to GLib.test_expect_message().)

For example:

// g_main_context_push_thread_default() should fail if the
// context is already owned by another thread.
g_test_expect_message (G_LOG_DOMAIN,
                       G_LOG_LEVEL_CRITICAL,
                       "assertion*acquired_context*failed");
g_main_context_push_thread_default (bad_context);
g_test_assert_expected_messages ();

Note that you cannot use this to test g_error() messages, since g_error() intentionally never returns even if the program doesn’t abort; use GLib.test_trap_subprocess() in this case.

If messages at GLib.LogLevelFlags.LEVEL_DEBUG are emitted, but not explicitly expected via GLib.test_expect_message() then they will be ignored.

New in version 2.34.

GLib.test_fail()[source]

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 GLib.test_skip() and 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 g_test_message() before GLib.test_fail(), or use g_test_fail_printf() instead.

New in version 2.30.

GLib.test_failed()[source]
Returns:

True if the test has failed

Return type:

bool

Returns whether a test has already failed. This will be the case when GLib.test_fail(), GLib.test_incomplete() or 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.

New in version 2.38.

GLib.test_get_dir(file_type)[source]
Parameters:

file_type (GLib.TestFileType) – the type of file (built vs. distributed)

Returns:

the path of the directory, owned by GLib

Return type:

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.

New in version 2.38.

GLib.test_get_path()[source]
Returns:

the test path for the test currently being run

Return type:

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

New in version 2.68.

GLib.test_incomplete(msg)[source]
Parameters:

msg (str or None) – explanation

Indicates that a test failed because of some incomplete functionality. This function can be called multiple times from the same test.

Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test.

If not called from inside a test, this function does nothing.

New in version 2.38.

GLib.test_log_type_name(log_type)[source]
Parameters:

log_type (GLib.TestLogType) –

Return type:

str

GLib.test_queue_destroy(destroy_func, destroy_data)[source]
Parameters:

This function enqueus a callback destroy_func to be executed during the next test case teardown phase. This is most useful to auto destruct 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.

New in version 2.16.

GLib.test_queue_free(gfree_pointer)[source]
Parameters:

gfree_pointer (object or None) – the pointer to be stored.

Enqueue a pointer to be released with GLib.free() during the next teardown phase. This is equivalent to calling GLib.test_queue_destroy() with a destroy callback of GLib.free().

New in version 2.16.

GLib.test_rand_double()[source]
Returns:

a random number from the seeded random number generator.

Return type:

float

Get a reproducible random floating point number, see GLib.test_rand_int() for details on test case random numbers.

New in version 2.16.

GLib.test_rand_double_range(range_start, range_end)[source]
Parameters:

  • range_start (float) – the minimum value returned by this function

  • range_end (float) – the minimum value not returned by this function

Returns:

a number with range_start <= number < range_end.

Return type:

float

Get a reproducible random floating pointer number out of a specified range, see GLib.test_rand_int() for details on test case random numbers.

New in version 2.16.

GLib.test_rand_int()[source]
Returns:

a random number from the seeded random number generator.

Return type:

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.

New in version 2.16.

GLib.test_rand_int_range(begin, end)[source]
Parameters:

  • begin (int) – the minimum value returned by this function

  • end (int) – the smallest value not to be returned by this function

Returns:

a number with begin <= number < end.

Return type:

int

Get a reproducible random integer number out of a specified range, see GLib.test_rand_int() for details on test case random numbers.

New in version 2.16.

GLib.test_run()[source]
Returns:

0 on success, 1 on failure (assuming it returns at all), 0 or 77 if all tests were skipped with GLib.test_skip() and/or GLib.test_incomplete()

Return type:

int

Runs all tests under the toplevel suite which can be retrieved with g_test_get_root(). Similar to 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 g_test_init(). GLib.test_run_suite() or 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 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 g_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.

New in version 2.16.

GLib.test_run_suite(suite)[source]
Parameters:

suite (GLib.TestSuite) – a GLib.TestSuite

Returns:

0 on success

Return type:

int

Execute the tests within suite and all nested GLib.TestSuites. The test suites to be executed are filtered according to test path arguments (-p testpath and -s testpath) as parsed by g_test_init(). See the GLib.test_run() documentation for more information on the order that tests are run in.

GLib.test_run_suite() or GLib.test_run() may only be called once in a program.

New in version 2.16.

GLib.test_set_nonfatal_assertions()[source]

Changes the behaviour of the various g_assert_*() macros, g_test_assert_expected_messages() and the various g_test_trap_assert_*() macros to not abort to program, but instead call GLib.test_fail() and continue. (This also changes the behavior of GLib.test_fail() so that it will not cause the test program to abort after completing the failed test.)

Note that the g_assert_not_reached() and g_assert() macros are not affected by this.

This function can only be called after g_test_init().

New in version 2.38.

GLib.test_skip(msg)[source]
Parameters:

msg (str or None) – explanation

Indicates that a test was skipped.

Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test.

If not called from inside a test, this function does nothing.

New in version 2.38.

GLib.test_subprocess()[source]
Returns:

True if the test program is running under GLib.test_trap_subprocess().

Return type:

bool

Returns True (after g_test_init() has been called) if the test program is running under GLib.test_trap_subprocess().

New in version 2.38.

GLib.test_summary(summary)[source]
Parameters:

summary (str) – One or two sentences summarising what the test checks, and how it checks it.

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:

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.");

  …
}

New in version 2.62.

GLib.test_timer_elapsed()[source]
Returns:

the time since the last start of the timer in seconds, as a double

Return type:

float

Get the number of seconds since the last start of the timer with GLib.test_timer_start().

New in version 2.16.

GLib.test_timer_last()[source]
Returns:

the last result of GLib.test_timer_elapsed(), as a double

Return type:

float

Report the last result of GLib.test_timer_elapsed().

New in version 2.16.

GLib.test_timer_start()[source]

Start a timing test. Call GLib.test_timer_elapsed() when the task is supposed to be done. Call this function again to restart the timer.

New in version 2.16.

GLib.test_trap_assertions(domain, file, line, func, assertion_flags, pattern)[source]
Parameters:

  • domain (str) –

  • file (str) –

  • line (int) –

  • func (str) –

  • assertion_flags (int) –

  • pattern (str) –

GLib.test_trap_fork(usec_timeout, test_trap_flags)[source]
Parameters:

  • usec_timeout (int) – Timeout for the forked test in micro seconds.

  • test_trap_flags (GLib.TestTrapFlags) – Flags to modify forking behaviour.

Returns:

True for the forked child and False for the executing parent process.

Return type:

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

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*");
}

New in version 2.16.

Deprecated since version ???: 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 GLib.test_trap_subprocess() instead.

GLib.test_trap_has_passed()[source]
Returns:

True if the last test subprocess terminated successfully.

Return type:

bool

Check the result of the last GLib.test_trap_subprocess() call.

New in version 2.16.

GLib.test_trap_reached_timeout()[source]
Returns:

True if the last test subprocess got killed due to a timeout.

Return type:

bool

Check the result of the last GLib.test_trap_subprocess() call.

New in version 2.16.

GLib.test_trap_subprocess(test_path, usec_timeout, test_flags)[source]
Parameters:

  • test_path (str or None) – Test to run in a subprocess

  • usec_timeout (int) – Timeout for the subprocess test in micro seconds.

  • test_flags (GLib.TestSubprocessFlags) – Flags to modify subprocess behaviour.

Respawns the test program to run only test_path in a subprocess. This can be used for a test case that might not return, or that might abort.

If test_path is None then the same test is re-run in a subprocess. You can use 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 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 GLib.TestSubprocessFlags flags.

You can use methods such as g_test_trap_assert_passed(), g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to check the results of the subprocess. (But note that g_test_trap_assert_stdout() and g_test_trap_assert_stderr() cannot be used if test_flags specifies that the child should inherit the parent stdout/stderr.)

If your main () needs to behave differently in the subprocess, you can call GLib.test_subprocess() (after calling g_test_init()) to see whether you are in a subprocess.

Internally, this function tracks the child process using 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.

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*");
}

int
main (int argc, char **argv)
{
  g_test_init (&argc, &argv, NULL);

  g_test_add_func ("/myobject/create_large_object",
                   test_create_large_object);
  return g_test_run ();
}

New in version 2.38.

GLib.thread_error_quark()[source]
Return type:

int

GLib.thread_exit(retval)[source]
Parameters:

retval (object or None) – the return value of this thread

Terminates the current thread.

If another thread is waiting for us using GLib.Thread.join() then the waiting thread will be woken up and get retval as the return value of GLib.Thread.join().

Calling GLib.Thread.exit() with a parameter retval is equivalent to returning retval from the function func, as given to GLib.Thread.new().

You must only call GLib.Thread.exit() from a thread that you created yourself with GLib.Thread.new() or related APIs. You must not call this function from a thread created with another threading library or or from within a GLib.ThreadPool.

GLib.thread_pool_get_max_idle_time()[source]
Returns:

the maximum interval (milliseconds) to wait for new tasks in the thread pool before stopping the thread

Return type:

int

This function will return the maximum interval that a thread will wait in the thread pool for new tasks before being stopped.

If this function returns 0, threads waiting in the thread pool for new work are not stopped.

New in version 2.10.

GLib.thread_pool_get_max_unused_threads()[source]
Returns:

the maximal number of unused threads

Return type:

int

Returns the maximal allowed number of unused threads.

GLib.thread_pool_get_num_unused_threads()[source]
Returns:

the number of currently unused threads

Return type:

int

Returns the number of currently unused threads.

GLib.thread_pool_set_max_idle_time(interval)[source]
Parameters:

interval (int) – the maximum interval (in milliseconds) a thread can be idle

This function will set the maximum interval that a thread waiting in the pool for new tasks can be idle for before being stopped. This function is similar to calling GLib.ThreadPool.stop_unused_threads() on a regular timeout, except this is done on a per thread basis.

By setting interval to 0, idle threads will not be stopped.

The default value is 15000 (15 seconds).

New in version 2.10.

GLib.thread_pool_set_max_unused_threads(max_threads)[source]
Parameters:

max_threads (int) – maximal number of unused threads

Sets the maximal number of unused threads to max_threads. If max_threads is -1, no limit is imposed on the number of unused threads.

The default value is 2.

GLib.thread_pool_stop_unused_threads()[source]

Stops all currently unused threads. This does not change the maximal number of unused threads. This function can be used to regularly stop all unused threads e.g. from GLib.timeout_add().

GLib.thread_self()[source]
Returns:

the GLib.Thread representing the current thread

Return type:

GLib.Thread

This function returns the GLib.Thread corresponding to the current thread. Note that this function does not increase the reference count of the returned struct.

This function will return a GLib.Thread even for threads that were not created by GLib (i.e. those created by other threading APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as GLib.Thread.join()) on these threads.

GLib.thread_yield()[source]

Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run.

This function is often used as a method to make busy wait less evil.

GLib.threads_init()
GLib.time_val_from_iso8601(iso_date)[source]
Parameters:

iso_date (str) – an ISO 8601 encoded date string

Returns:

True if the conversion was successful.

time_:

a GLib.TimeVal

Return type:

(bool, time_: GLib.TimeVal)

Converts a string containing an ISO 8601 encoded date and time to a GLib.TimeVal and puts it into time_.

iso_date must include year, month, day, hours, minutes, and seconds. It can optionally include fractions of a second and a time zone indicator. (In the absence of any time zone indication, the timestamp is assumed to be in local time.)

Any leading or trailing space in iso_date is ignored.

This function was deprecated, along with GLib.TimeVal itself, in GLib 2.62. Equivalent functionality is available using code like:

GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL);
gint64 time_val = g_date_time_to_unix (dt);
g_date_time_unref (dt);

New in version 2.12.

Deprecated since version 2.62: GLib.TimeVal is not year-2038-safe. Use GLib.DateTime.new_from_iso8601() instead.

GLib.timeout_add(priority, interval, function, *data)[source]
Parameters:
Returns:

the ID (greater than 0) of the event source.

Return type:

int

Sets a function to be called at regular intervals, with the given priority. The function is called repeatedly until it returns False, at which point the timeout is automatically destroyed and the function will not be called again. The notify function is called when the timeout is destroyed. The first call to the function will be at the end of the first interval.

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to ‘catch up’ time lost in delays).

See memory management of sources for details on how to handle the return value and memory management of data.

This internally creates a main loop source using GLib.timeout_source_new() and attaches it to the global GLib.MainContext using 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.

The interval given is in terms of monotonic time, not wall clock time. See GLib.get_monotonic_time().

GLib.timeout_add_seconds(priority, interval, function, *data)[source]
Parameters:
Returns:

the ID (greater than 0) of the event source.

Return type:

int

Sets a function to be called at regular intervals, with priority.

The function is called repeatedly until it returns GLib.SOURCE_REMOVE or False, at which point the timeout is automatically destroyed and the function will not be called again.

Unlike GLib.timeout_add(), this function operates at whole second granularity. The initial starting point of the timer is determined by the implementation and the implementation is expected to group multiple timers together so that they fire all at the same time. To allow this grouping, the interval to the first timer is rounded and can deviate up to one second from the specified interval. Subsequent timer iterations will generally run at the specified interval.

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval

See memory management of sources for details on how to handle the return value and memory management of data.

If you want timing more precise than whole seconds, use GLib.timeout_add() instead.

The grouping of timers to fire at the same time results in a more power and CPU efficient behavior so if your timer is in multiples of seconds and you don’t require the first timer exactly one second from now, the use of GLib.timeout_add_seconds() is preferred over GLib.timeout_add().

This internally creates a main loop source using GLib.timeout_source_new_seconds() and attaches it to the main loop context using GLib.Source.attach(). You can do these steps manually if you need greater control.

It is safe to call this function from any thread.

The interval given is in terms of monotonic time, not wall clock time. See GLib.get_monotonic_time().

New in version 2.14.

GLib.timeout_source_new(interval)[source]
Parameters:

interval (int) – the timeout interval in milliseconds.

Returns:

the newly-created timeout source

Return type:

GLib.Source

Creates a new timeout source.

The source will not initially be associated with any GLib.MainContext and must be added to one with GLib.Source.attach() before it will be executed.

The interval given is in terms of monotonic time, not wall clock time. See GLib.get_monotonic_time().

GLib.timeout_source_new_seconds(interval)[source]
Parameters:

interval (int) – the timeout interval in seconds

Returns:

the newly-created timeout source

Return type:

GLib.Source

Creates a new timeout source.

The source will not initially be associated with any GLib.MainContext and must be added to one with 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 GLib.get_monotonic_time().

New in version 2.14.

GLib.trash_stack_height(stack_p)[source]
Parameters:

stack_p (GLib.TrashStack) – a GLib.TrashStack

Returns:

the height of the stack

Return type:

int

Returns the height of a GLib.TrashStack.

Note that execution of this function is of O(N) complexity where N denotes the number of items on the stack.

Deprecated since version 2.48: GLib.TrashStack is deprecated without replacement

GLib.trash_stack_peek(stack_p)[source]
Parameters:

stack_p (GLib.TrashStack) – a GLib.TrashStack

Returns:

the element at the top of the stack

Return type:

object or None

Returns the element at the top of a GLib.TrashStack which may be None.

Deprecated since version 2.48: GLib.TrashStack is deprecated without replacement

GLib.trash_stack_pop(stack_p)[source]
Parameters:

stack_p (GLib.TrashStack) – a GLib.TrashStack

Returns:

the element at the top of the stack

Return type:

object or None

Pops a piece of memory off a GLib.TrashStack.

Deprecated since version 2.48: GLib.TrashStack is deprecated without replacement

GLib.trash_stack_push(stack_p, data_p)[source]
Parameters:

Pushes a piece of memory onto a GLib.TrashStack.

Deprecated since version 2.48: GLib.TrashStack is deprecated without replacement

GLib.try_malloc(n_bytes)[source]
Parameters:

n_bytes (int) – number of bytes to allocate.

Returns:

the allocated memory, or None.

Return type:

object or None

Attempts to allocate n_bytes, and returns None on failure. Contrast with GLib.malloc(), which aborts the program on failure.

GLib.try_malloc0(n_bytes)[source]
Parameters:

n_bytes (int) – number of bytes to allocate

Returns:

the allocated memory, or None

Return type:

object or None

Attempts to allocate n_bytes, initialized to 0’s, and returns None on failure. Contrast with GLib.malloc0(), which aborts the program on failure.

New in version 2.8.

GLib.try_malloc0_n(n_blocks, n_block_bytes)[source]
Parameters:

  • n_blocks (int) – the number of blocks to allocate

  • n_block_bytes (int) – the size of each block in bytes

Returns:

the allocated memory, or None

Return type:

object or None

This function is similar to GLib.try_malloc0(), allocating (n_blocks * n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication.

New in version 2.24.

GLib.try_malloc_n(n_blocks, n_block_bytes)[source]
Parameters:

  • n_blocks (int) – the number of blocks to allocate

  • n_block_bytes (int) – the size of each block in bytes

Returns:

the allocated memory, or None.

Return type:

object or None

This function is similar to GLib.try_malloc(), allocating (n_blocks * n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication.

New in version 2.24.

GLib.try_realloc(mem, n_bytes)[source]
Parameters:

  • mem (object or None) – previously-allocated memory, or None.

  • n_bytes (int) – number of bytes to allocate.

Returns:

the allocated memory, or None.

Return type:

object or None

Attempts to realloc mem to a new size, n_bytes, and returns None on failure. Contrast with GLib.realloc(), which aborts the program on failure.

If mem is None, behaves the same as GLib.try_malloc().

GLib.try_realloc_n(mem, n_blocks, n_block_bytes)[source]
Parameters:

  • mem (object or None) – previously-allocated memory, or None.

  • n_blocks (int) – the number of blocks to allocate

  • n_block_bytes (int) – the size of each block in bytes

Returns:

the allocated memory, or None.

Return type:

object or None

This function is similar to GLib.try_realloc(), allocating (n_blocks * n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication.

New in version 2.24.

GLib.ucs4_to_utf16(str)[source]
Parameters:

str ([str]) – a UCS-4 encoded string

Raises:

GLib.Error

Returns:

a pointer to a newly allocated UTF-16 string. This value must be freed with GLib.free(). If an error occurs, None will be returned and error set.

items_read:

location to store number of bytes read, or None. If an error occurs then the index of the invalid input is stored here.

items_written:

location to store number of #gunichar2 written, or None. The value stored here does not include the trailing 0.

Return type:

(int, items_read: int, items_written: int)

Convert a string from UCS-4 to UTF-16. A 0 character will be added to the result after the converted text.

GLib.ucs4_to_utf8(str)[source]
Parameters:

str ([str]) – a UCS-4 encoded string

Raises:

GLib.Error

Returns:

a pointer to a newly allocated UTF-8 string. This value must be freed with GLib.free(). If an error occurs, None will be returned and error set. In that case, items_read will be set to the position of the first invalid input character.

items_read:

location to store number of characters read, or None.

items_written:

location to store number of bytes written or None. The value here stored does not include the trailing 0 byte.

Return type:

(str, items_read: int, items_written: 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.

GLib.unichar_break_type(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

the break type of c

Return type:

GLib.UnicodeBreakType

Determines the break type of c. c should be a Unicode character (to derive a character from UTF-8 encoded text, use 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.

GLib.unichar_combining_class(uc)[source]
Parameters:

uc (str) – a Unicode character

Returns:

the combining class of the character

Return type:

int

Determines the canonical combining class of a Unicode character.

New in version 2.14.

GLib.unichar_compose(a, b)[source]
Parameters:

  • a (str) – a Unicode character

  • b (str) – a Unicode character

Returns:

True if the characters could be composed

ch:

return location for the composed character

Return type:

(bool, ch: 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 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 <a,`b`>. See the Unicode Standard for the definition of Primary Composite.

If a and b do not compose a new character, ch is set to zero.

See UAX#15 for details.

New in version 2.30.

GLib.unichar_decompose(ch)[source]
Parameters:

ch (str) – a Unicode character

Returns:

True if the character could be decomposed

a:

return location for the first component of ch

b:

return location for the second component of ch

Return type:

(bool, a: str, b: 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 GLib.unichar_fully_decompose().

See UAX#15 for details.

New in version 2.30.

GLib.unichar_digit_value(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

If c is a decimal digit (according to GLib.unichar_isdigit()), its numeric value. Otherwise, -1.

Return type:

int

Determines the numeric value of a character as a decimal digit.

GLib.unichar_fully_decompose(ch, compat, result_len)[source]
Parameters:

  • ch (str) – a Unicode character.

  • compat (bool) – whether perform canonical or compatibility decomposition

  • result_len (int) – length of result

Returns:

the length of the full decomposition.

result:

location to store decomposed result, or None

Return type:

(int, result: str)

Computes the canonical or compatibility decomposition of a Unicode character. For compatibility decomposition, pass True for compat; for canonical decomposition pass False for compat.

The decomposed sequence is placed in result. Only up to result_len characters are written into result. The length of the full decomposition (irrespective of result_len) is returned by the function. For canonical decomposition, currently all decompositions are of length at most 4, but this may change in the future (very unlikely though). At any rate, Unicode does guarantee that a buffer of length 18 is always enough for both compatibility and canonical decompositions, so that is the size recommended. This is provided as GLib.UNICHAR_MAX_DECOMPOSITION_LENGTH.

See UAX#15 for details.

New in version 2.30.

GLib.unichar_get_mirror_char(ch)[source]
Parameters:

ch (str) – a Unicode character

Returns:

True if ch has a mirrored character, False otherwise

mirrored_ch:

location to store the mirrored character

Return type:

(bool, mirrored_ch: 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.

New in version 2.4.

GLib.unichar_get_script(ch)[source]
Parameters:

ch (str) – a Unicode character

Returns:

the GLib.UnicodeScript for the character.

Return type:

GLib.UnicodeScript

Looks up the 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.

New in version 2.14.

GLib.unichar_isalnum(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is an alphanumeric character

Return type:

bool

Determines whether a character is alphanumeric. Given some UTF-8 text, obtain a character value with GLib.utf8_get_char().

GLib.unichar_isalpha(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is an alphabetic character

Return type:

bool

Determines whether a character is alphabetic (i.e. a letter). Given some UTF-8 text, obtain a character value with GLib.utf8_get_char().

GLib.unichar_iscntrl(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is a control character

Return type:

bool

Determines whether a character is a control character. Given some UTF-8 text, obtain a character value with GLib.utf8_get_char().

GLib.unichar_isdefined(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if the character has an assigned value

Return type:

bool

Determines if a given character is assigned in the Unicode standard.

GLib.unichar_isdigit(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is a digit

Return type:

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

GLib.unichar_isgraph(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is printable unless it’s a space

Return type:

bool

Determines whether a character is printable and not a space (returns False for control characters, format characters, and spaces). GLib.unichar_isprint() is similar, but returns True for spaces. Given some UTF-8 text, obtain a character value with GLib.utf8_get_char().

GLib.unichar_islower(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is a lowercase letter

Return type:

bool

Determines whether a character is a lowercase letter. Given some UTF-8 text, obtain a character value with GLib.utf8_get_char().

GLib.unichar_ismark(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is a mark character

Return type:

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

New in version 2.14.

GLib.unichar_isprint(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is printable

Return type:

bool

Determines whether a character is printable. Unlike GLib.unichar_isgraph(), returns True for spaces. Given some UTF-8 text, obtain a character value with GLib.utf8_get_char().

GLib.unichar_ispunct(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is a punctuation or symbol character

Return type:

bool

Determines whether a character is punctuation or a symbol. Given some UTF-8 text, obtain a character value with GLib.utf8_get_char().

GLib.unichar_isspace(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is a space character

Return type:

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

GLib.unichar_istitle(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if the character is titlecase

Return type:

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.

GLib.unichar_isupper(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if c is an uppercase character

Return type:

bool

Determines if a character is uppercase.

GLib.unichar_iswide(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if the character is wide

Return type:

bool

Determines if a character is typically rendered in a double-width cell.

GLib.unichar_iswide_cjk(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if the character is wide in legacy East Asian locales

Return type:

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 GLib.unichar_iswide(), then it is also reported wide with this function, but the converse is not necessarily true. See the Unicode Standard Annex #11 for details.

If a character passes the 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 GLib.unichar_iszerowidth().

New in version 2.12.

GLib.unichar_isxdigit(c)[source]
Parameters:

c (str) – a Unicode character.

Returns:

True if the character is a hexadecimal digit

Return type:

bool

Determines if a character is a hexadecimal digit.

GLib.unichar_iszerowidth(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

True if the character has zero width

Return type:

bool

Determines if a given character typically takes zero width when rendered. The return value is True for all non-spacing and enclosing marks (e.g., combining accents), format characters, zero-width space, but not U+00AD SOFT HYPHEN.

A typical use of this function is with one of GLib.unichar_iswide() or 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.

New in version 2.14.

GLib.unichar_to_utf8(c)[source]
Parameters:

c (str) – a Unicode character code

Returns:

number of bytes written

outbuf:

output buffer, must have at least 6 bytes of space. If None, the length will be computed and returned and nothing will be written to outbuf.

Return type:

(int, outbuf: str)

Converts a single character to UTF-8.

GLib.unichar_tolower(c)[source]
Parameters:

c (str) – a Unicode character.

Returns:

the result of converting c to lower case. If c is not an upperlower or titlecase character, or has no lowercase equivalent c is returned unchanged.

Return type:

str

Converts a character to lower case.

GLib.unichar_totitle(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

the result of converting c to titlecase. If c is not an uppercase or lowercase character, c is returned unchanged.

Return type:

str

Converts a character to the titlecase.

GLib.unichar_toupper(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

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.

Return type:

str

Converts a character to uppercase.

GLib.unichar_type(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

the type of the character.

Return type:

GLib.UnicodeType

Classifies a Unicode character by type.

GLib.unichar_validate(ch)[source]
Parameters:

ch (str) – a Unicode character

Returns:

True if ch is a valid Unicode character

Return type:

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.

GLib.unichar_xdigit_value(c)[source]
Parameters:

c (str) – a Unicode character

Returns:

If c is a hex digit (according to GLib.unichar_isxdigit()), its numeric value. Otherwise, -1.

Return type:

int

Determines the numeric value of a character as a hexadecimal digit.

GLib.unicode_canonical_decomposition(ch, result_len)[source]
Parameters:

  • ch (str) – a Unicode character.

  • result_len (int) – location to store the length of the return value.

Returns:

a newly allocated string of Unicode characters. result_len is set to the resulting length of the string.

Return type:

str

Computes the canonical decomposition of a Unicode character.

Deprecated since version 2.30: Use the more flexible GLib.unichar_fully_decompose() instead.

GLib.unicode_canonical_ordering(string)[source]
Parameters:

string ([str]) – a UCS-4 encoded string.

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.

GLib.unicode_script_from_iso15924(iso15924)[source]
Parameters:

iso15924 (int) – a Unicode script

Returns:

the Unicode script for iso15924, or of GLib.UnicodeScript.INVALID_CODE if iso15924 is zero and GLib.UnicodeScript.UNKNOWN if iso15924 is unknown.

Return type:

GLib.UnicodeScript

Looks up the Unicode script for iso15924. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is ‘Arab’. This function accepts four letter codes encoded as a guint32 in a big-endian fashion. That is, the code expected for Arabic is 0x41726162 (0x41 is ASCII code for ‘A’, 0x72 is ASCII code for ‘r’, etc).

See Codes for the representation of names of scripts for details.

New in version 2.30.

GLib.unicode_script_to_iso15924(script)[source]
Parameters:

script (GLib.UnicodeScript) – a Unicode script

Returns:

the ISO 15924 code for script, encoded as an integer, of zero if script is GLib.UnicodeScript.INVALID_CODE or ISO 15924 code ‘Zzzz’ (script code for UNKNOWN) if script is not understood.

Return type:

int

Looks up the ISO 15924 code for script. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is ‘Arab’. The four letter codes are encoded as a guint32 by this function in a big-endian fashion. That is, the code returned for Arabic is 0x41726162 (0x41 is ASCII code for ‘A’, 0x72 is ASCII code for ‘r’, etc).

See Codes for the representation of names of scripts for details.

New in version 2.30.

GLib.unix_error_quark()[source]
Return type:

int

GLib.unix_fd_add_full(priority, fd, condition, function, *user_data)[source]
Parameters:
Returns:

the ID (greater than 0) of the event source

Return type:

int

Sets a function to be called when the IO condition, as specified by condition becomes true for fd.

This is the same as g_unix_fd_add(), except that it allows you to specify a non-default priority and a provide a GLib.DestroyNotify for user_data.

New in version 2.36.

GLib.unix_fd_source_new(fd, condition)[source]
Parameters:

  • fd (int) – a file descriptor

  • condition (GLib.IOCondition) – I/O conditions to watch for on fd

Returns:

the newly created GLib.Source

Return type:

GLib.Source

Creates a 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 GLib.Source must have type GLib.UnixFDSourceFunc.

New in version 2.36.

GLib.unix_get_passwd_entry(user_name)[source]
Parameters:

user_name (str) – the username to get the passwd file entry for

Raises:

GLib.Error

Returns:

passwd entry, or None on error; free the returned value with GLib.free()

Return type:

object or 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 GLib.malloc() and should be freed using 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.

New in version 2.64.

GLib.unix_open_pipe(fds, flags)[source]
Parameters:

  • fds ([int]) – Array of two integers

  • flags (int) – Bitfield of file descriptor flags, as for fcntl()

Raises:

GLib.Error

Returns:

True on success, False if not (and errno will be set).

Return type:

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

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.

New in version 2.30.

GLib.unix_set_fd_nonblocking(fd, nonblock)[source]
Parameters:

  • fd (int) – A file descriptor

  • nonblock (bool) – If True, set the descriptor to be non-blocking

Raises:

GLib.Error

Returns:

True if successful

Return type:

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.

New in version 2.30.

GLib.unix_signal_add(priority, signum, handler, *user_data)[source]
Parameters:
Returns:

An ID (greater than 0) for the event source

Return type:

int

A convenience function for GLib.unix_signal_source_new(), which attaches to the default GLib.MainContext. You can remove the watch using GLib.Source.remove().

New in version 2.30.

GLib.unix_signal_add_full(*args)
GLib.unix_signal_source_new(signum)[source]
Parameters:

signum (int) – A signal number

Returns:

A newly created GLib.Source

Return type:

GLib.Source

Create a 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 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 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 GLib.MainContext and must be added to one with GLib.Source.attach() before it will be executed.

New in version 2.30.

Parameters:

filename (str) – a pathname in the GLib file name encoding (UTF-8 on Windows)

Returns:

0 if the name was successfully deleted, -1 if an error occurred

Return type:

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.

New in version 2.6.

GLib.unsetenv(variable)[source]
Parameters:

variable (str) – the environment variable to remove, must not contain ‘=’

Removes an environment variable from the environment.

Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn’t reclaimed.

You should be mindful of the fact that environment variable handling in UNIX is not thread-safe, and your program may crash if one thread calls 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 GLib.get_environ() to get an environment array, modify that with GLib.environ_setenv() and GLib.environ_unsetenv(), and then pass that array directly to execvpe(), GLib.spawn_async(), or the like.

New in version 2.4.

GLib.uri_build(flags, scheme, userinfo, host, port, path, query, fragment)[source]
Parameters:

  • flags (GLib.UriFlags) – flags describing how to build the GLib.Uri

  • scheme (str) – the URI scheme

  • userinfo (str or None) – the userinfo component, or None

  • host (str or None) – the host component, or None

  • port (int) – the port, or -1

  • path (str) – the path component

  • query (str or None) – the query component, or None

  • fragment (str or None) – the fragment, or None

Returns:

a new GLib.Uri

Return type:

GLib.Uri

Creates a new GLib.Uri from the given components according to flags.

See also GLib.Uri.build_with_user(), which allows specifying the components of the “userinfo” separately.

New in version 2.66.

GLib.uri_build_with_user(flags, scheme, user, password, auth_params, host, port, path, query, fragment)[source]
Parameters:

  • flags (GLib.UriFlags) – flags describing how to build the GLib.Uri

  • scheme (str) – the URI scheme

  • user (str or None) – the user component of the userinfo, or None

  • password (str or None) – the password component of the userinfo, or None

  • auth_params (str or None) – the auth params of the userinfo, or None

  • host (str or None) – the host component, or None

  • port (int) – the port, or -1

  • path (str) – the path component

  • query (str or None) – the query component, or None

  • fragment (str or None) – the fragment, or None

Returns:

a new GLib.Uri

Return type:

GLib.Uri

Creates a new GLib.Uri from the given components according to flags (GLib.UriFlags.HAS_PASSWORD is added unconditionally). The flags must be coherent with the passed values, in particular use %-encoded values with GLib.UriFlags.ENCODED.

In contrast to GLib.Uri.build(), this allows specifying the components of the ‘userinfo’ field separately. Note that user must be non-None if either password or auth_params is non-None.

New in version 2.66.

GLib.uri_error_quark()[source]
Return type:

int

GLib.uri_escape_bytes(unescaped, reserved_chars_allowed)[source]
Parameters:

  • unescaped (bytes) – the unescaped input data.

  • reserved_chars_allowed (str or None) – a string of reserved characters that are allowed to be used, or None.

Returns:

an escaped version of unescaped. The returned string should be freed when no longer needed.

Return type:

str

Escapes arbitrary data for use in a URI.

Normally all characters that are not ‘unreserved’ (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are escaped. But if you specify characters in reserved_chars_allowed they are not escaped. This is useful for the ‘reserved’ characters in the URI specification, since those are allowed unescaped in some portions of a URI.

Though technically incorrect, this will also allow escaping nul bytes as `%` 00.

New in version 2.66.

GLib.uri_escape_string(unescaped, reserved_chars_allowed, allow_utf8)[source]
Parameters:

  • unescaped (str) – the unescaped input string.

  • reserved_chars_allowed (str or None) – a string of reserved characters that are allowed to be used, or None.

  • allow_utf8 (bool) – True if the result can include UTF-8 characters.

Returns:

an escaped version of unescaped. The returned string should be freed when no longer needed.

Return type:

str

Escapes a string for use in a URI.

Normally all characters that are not “unreserved” (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are escaped. But if you specify characters in reserved_chars_allowed they are not escaped. This is useful for the “reserved” characters in the URI specification, since those are allowed unescaped in some portions of a URI.

New in version 2.16.

GLib.uri_is_valid(uri_string, flags)[source]
Parameters:

  • uri_string (str) – a string containing an absolute URI

  • flags (GLib.UriFlags) – flags for parsing uri_string

Raises:

GLib.Error

Returns:

True if uri_string is a valid absolute URI, False on error.

Return type:

bool

Parses uri_string according to flags, to determine whether it is a valid ‘absolute URI [relative-absolute-uris]’, i.e. it does not need to be resolved relative to another URI using GLib.Uri.parse_relative().

If it’s not a valid URI, an error is returned explaining how it’s invalid.

See GLib.Uri.split(), and the definition of GLib.UriFlags, for more information on the effect of flags.

New in version 2.66.

GLib.uri_join(flags, scheme, userinfo, host, port, path, query, fragment)[source]
Parameters:

  • flags (GLib.UriFlags) – flags describing how to build the URI string

  • scheme (str or None) – the URI scheme, or None

  • userinfo (str or None) – the userinfo component, or None

  • host (str or None) – the host component, or None

  • port (int) – the port, or -1

  • path (str) – the path component

  • query (str or None) – the query component, or None

  • fragment (str or None) – the fragment, or None

Returns:

an absolute URI string

Return type:

str

Joins the given components together according to flags to create an absolute URI string. path may not be None (though it may be the empty string).

When host is present, path must either be empty or begin with a slash (/) character. When host is not present, path cannot begin with two slash characters (//). See RFC 3986, section 3.

See also GLib.Uri.join_with_user(), which allows specifying the components of the ‘userinfo’ separately.

GLib.UriFlags.HAS_PASSWORD and GLib.UriFlags.HAS_AUTH_PARAMS are ignored if set in flags.

New in version 2.66.

GLib.uri_join_with_user(flags, scheme, user, password, auth_params, host, port, path, query, fragment)[source]
Parameters:

  • flags (GLib.UriFlags) – flags describing how to build the URI string

  • scheme (str or None) – the URI scheme, or None

  • user (str or None) – the user component of the userinfo, or None

  • password (str or None) – the password component of the userinfo, or None

  • auth_params (str or None) – the auth params of the userinfo, or None

  • host (str or None) – the host component, or None

  • port (int) – the port, or -1

  • path (str) – the path component

  • query (str or None) – the query component, or None

  • fragment (str or None) – the fragment, or None

Returns:

an absolute URI string

Return type:

str

Joins the given components together according to flags to create an absolute URI string. path may not be None (though it may be the empty string).

In contrast to GLib.Uri.join(), this allows specifying the components of the ‘userinfo’ separately. It otherwise behaves the same.

GLib.UriFlags.HAS_PASSWORD and GLib.UriFlags.HAS_AUTH_PARAMS are ignored if set in flags.

New in version 2.66.

GLib.uri_list_extract_uris(uri_list)[source]
Parameters:

uri_list (str) – an URI list

Returns:

a newly allocated None-terminated list of strings holding the individual URIs. The array should be freed with GLib.strfreev().

Return type:

[str]

Splits an URI list conforming to the text/uri-list mime type defined in RFC 2483 into individual URIs, discarding any comments. The URIs are not validated.

New in version 2.6.

GLib.uri_parse(uri_string, flags)[source]
Parameters:

  • uri_string (str) – a string representing an absolute URI

  • flags (GLib.UriFlags) – flags describing how to parse uri_string

Raises:

GLib.Error

Returns:

a new GLib.Uri, or None on error.

Return type:

GLib.Uri

Parses uri_string according to flags. If the result is not a valid ‘absolute URI [relative-absolute-uris]’, it will be discarded, and an error returned.

New in version 2.66.

GLib.uri_parse_params(params, length, separators, flags)[source]
Parameters:

  • params (str) – a %-encoded string containing attribute=value parameters

  • length (int) – the length of params, or -1 if it is nul-terminated

  • separators (str) – the separator byte character set between parameters. (usually &, but sometimes ; or both &;). 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. You may pass an empty set, in which case no splitting will occur.

  • flags (GLib.UriParamsFlags) – flags to modify the way the parameters are handled.

Raises:

GLib.Error

Returns:

A hash table of attribute/value pairs, with both names and values fully-decoded; or None on error.

Return type:

{str: str}

Many URI schemes include one or more attribute/value pairs as part of the URI value. This method can be used to parse them into a hash table. When an attribute has multiple occurrences, the last value is the final returned value. If you need to handle repeated attributes differently, use GLib.UriParamsIter.

The params string is assumed to still be %-encoded, but the returned values will be fully decoded. (Thus it is possible that the returned values may contain = or separators, if the value was encoded in the input.) Invalid %-encoding is treated as with the GLib.UriFlags.PARSE_RELAXED rules for GLib.Uri.parse(). (However, if params is the path or query string from a GLib.Uri that was parsed without GLib.UriFlags.PARSE_RELAXED and GLib.UriFlags.ENCODED, then you already know that it does not contain any invalid encoding.)

GLib.UriParamsFlags.WWW_FORM is handled as documented for GLib.UriParamsIter.init().

If GLib.UriParamsFlags.CASE_INSENSITIVE is passed to flags, attributes will be compared case-insensitively, so a params string attr=123&Attr=456 will only return a single attribute–value pair, Attr=456. Case will be preserved in the returned attributes.

If params cannot be parsed (for example, it contains two separators characters in a row), then error is set and None is returned.

New in version 2.66.

GLib.uri_parse_scheme(uri)[source]
Parameters:

uri (str) – a valid URI.

Returns:

The ‘scheme’ component of the URI, or None on error. The returned string should be freed when no longer needed.

Return type:

str or None

Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Common schemes include file, https, svn+ssh, etc.

New in version 2.16.

GLib.uri_peek_scheme(uri)[source]
Parameters:

uri (str) – a valid URI.

Returns:

The ‘scheme’ component of the URI, or None on error. The returned string is normalized to all-lowercase, and interned via GLib.intern_string(), so it does not need to be freed.

Return type:

str or None

Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Common schemes include file, https, svn+ssh, etc.

Unlike GLib.Uri.parse_scheme(), the returned scheme is normalized to all-lowercase and does not need to be freed.

New in version 2.66.

GLib.uri_resolve_relative(base_uri_string, uri_ref, flags)[source]
Parameters:

  • base_uri_string (str or None) – a string representing a base URI

  • uri_ref (str) – a string representing a relative or absolute URI

  • flags (GLib.UriFlags) – flags describing how to parse uri_ref

Raises:

GLib.Error

Returns:

the resolved URI string, or None on error.

Return type:

str

Parses uri_ref according to flags and, if it is a ‘relative URI [relative-absolute-uris]’, resolves it relative to base_uri_string. If the result is not a valid absolute URI, it will be discarded, and an error returned.

(If base_uri_string is None, this just returns uri_ref, or None if uri_ref is invalid or not absolute.)

New in version 2.66.

GLib.uri_split(uri_ref, flags)[source]
Parameters:

  • uri_ref (str) – a string containing a relative or absolute URI

  • flags (GLib.UriFlags) – flags for parsing uri_ref

Raises:

GLib.Error

Returns:

True if uri_ref parsed successfully, False on error.

scheme:

on return, contains the scheme (converted to lowercase), or None

userinfo:

on return, contains the userinfo, or None

host:

on return, contains the host, or None

port:

on return, contains the port, or -1

path:

on return, contains the path

query:

on return, contains the query, or None

fragment:

on return, contains the fragment, or None

Return type:

(bool, scheme: str or None, userinfo: str or None, host: str or None, port: int, path: str, query: str or None, fragment: str or None)

Parses uri_ref (which can be an ‘absolute or relative URI [relative-absolute-uris]’) according to flags, and returns the pieces. Any component that doesn’t appear in uri_ref will be returned as None (but note that all URIs always have a path component, though it may be the empty string).

If flags contains GLib.UriFlags.ENCODED, then %-encoded characters in uri_ref will remain encoded in the output strings. (If not, then all such characters will be decoded.) Note that decoding will only work if the URI components are ASCII or UTF-8, so you will need to use GLib.UriFlags.ENCODED if they are not.

Note that the GLib.UriFlags.HAS_PASSWORD and GLib.UriFlags.HAS_AUTH_PARAMS flags are ignored by GLib.Uri.split(), since it always returns only the full userinfo; use GLib.Uri.split_with_user() if you want it split up.

New in version 2.66.

GLib.uri_split_network(uri_string, flags)[source]
Parameters:

  • uri_string (str) – a string containing an absolute URI

  • flags (GLib.UriFlags) – flags for parsing uri_string

Raises:

GLib.Error

Returns:

True if uri_string parsed successfully, False on error.

scheme:

on return, contains the scheme (converted to lowercase), or None

host:

on return, contains the host, or None

port:

on return, contains the port, or -1

Return type:

(bool, scheme: str or None, host: str or None, port: int)

Parses uri_string (which must be an ‘absolute URI [relative-absolute-uris]’) according to flags, and returns the pieces relevant to connecting to a host. See the documentation for GLib.Uri.split() for more details; this is mostly a wrapper around that function with simpler arguments. However, it will return an error if uri_string is a relative URI, or does not contain a hostname component.

New in version 2.66.

GLib.uri_split_with_user(uri_ref, flags)[source]
Parameters:

  • uri_ref (str) – a string containing a relative or absolute URI

  • flags (GLib.UriFlags) – flags for parsing uri_ref

Raises:

GLib.Error

Returns:

True if uri_ref parsed successfully, False on error.

scheme:

on return, contains the scheme (converted to lowercase), or None

user:

on return, contains the user, or None

password:

on return, contains the password, or None

auth_params:

on return, contains the auth_params, or None

host:

on return, contains the host, or None

port:

on return, contains the port, or -1

path:

on return, contains the path

query:

on return, contains the query, or None

fragment:

on return, contains the fragment, or None

Return type:

(bool, scheme: str or None, user: str or None, password: str or None, auth_params: str or None, host: str or None, port: int, path: str, query: str or None, fragment: str or None)

Parses uri_ref (which can be an ‘absolute or relative URI [relative-absolute-uris]’) according to flags, and returns the pieces. Any component that doesn’t appear in uri_ref will be returned as None (but note that all URIs always have a path component, though it may be the empty string).

See GLib.Uri.split(), and the definition of GLib.UriFlags, for more information on the effect of flags. Note that password will only be parsed out if flags contains GLib.UriFlags.HAS_PASSWORD, and auth_params will only be parsed out if flags contains GLib.UriFlags.HAS_AUTH_PARAMS.

New in version 2.66.

GLib.uri_unescape_bytes(escaped_string, length, illegal_characters)[source]
Parameters:

  • escaped_string (str) – A URI-escaped string

  • length (int) – the length (in bytes) of escaped_string to escape, or -1 if it is nul-terminated.

  • illegal_characters (str or None) – a string of illegal characters not to be allowed, or None.

Raises:

GLib.Error

Returns:

an unescaped version of escaped_string or None on error (if decoding failed, using GLib.UriError.FAILED error code). The returned GLib.Bytes should be unreffed when no longer needed.

Return type:

GLib.Bytes

Unescapes a segment of an escaped string as binary data.

Note that in contrast to GLib.Uri.unescape_string(), this does allow nul bytes to appear in the output.

If any of the characters in illegal_characters appears as an escaped character in escaped_string, then that is an error and None will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling.

New in version 2.66.

GLib.uri_unescape_segment(escaped_string, escaped_string_end, illegal_characters)[source]
Parameters:

  • escaped_string (str or None) – A string, may be None

  • escaped_string_end (str or None) – Pointer to end of escaped_string, may be None

  • illegal_characters (str or None) – An optional string of illegal characters not to be allowed, may be None

Returns:

an unescaped version of escaped_string, or None on error. The returned string should be freed when no longer needed. As a special case if None is given for escaped_string, this function will return None.

Return type:

str or None

Unescapes a segment of an escaped string.

If any of the characters in illegal_characters or the NUL character appears as an escaped character in escaped_string, then that is an error and None will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling.

Note: NUL byte is not accepted in the output, in contrast to GLib.Uri.unescape_bytes().

New in version 2.16.

GLib.uri_unescape_string(escaped_string, illegal_characters)[source]
Parameters:

  • escaped_string (str) – an escaped string to be unescaped.

  • illegal_characters (str or None) – a string of illegal characters not to be allowed, or None.

Returns:

an unescaped version of escaped_string. The returned string should be freed when no longer needed.

Return type:

str or None

Unescapes a whole escaped string.

If any of the characters in illegal_characters or the NUL character appears as an escaped character in escaped_string, then that is an error and None will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling.

New in version 2.16.

GLib.usleep(microseconds)[source]
Parameters:

microseconds (int) – number of microseconds to pause

Pauses the current thread for the given number of microseconds.

There are 1 million microseconds per second (represented by the GLib.USEC_PER_SEC macro). GLib.usleep() may have limited precision, depending on hardware and operating system; don’t rely on the exact length of the sleep.

GLib.utf16_to_ucs4(str)[source]
Parameters:

str ([int]) – a UTF-16 encoded string

Raises:

GLib.Error

Returns:

a pointer to a newly allocated UCS-4 string. This value must be freed with GLib.free(). If an error occurs, None will be returned and error set.

items_read:

location to store number of words read, or None. If None, then GLib.ConvertError.PARTIAL_INPUT will be returned in case str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here.

items_written:

location to store number of characters written, or None. The value stored here does not include the trailing 0 character.

Return type:

(str, items_read: int, items_written: int)

Convert a string from UTF-16 to UCS-4. The result will be nul-terminated.

GLib.utf16_to_utf8(str)[source]
Parameters:

str ([int]) – a UTF-16 encoded string

Raises:

GLib.Error

Returns:

a pointer to a newly allocated UTF-8 string. This value must be freed with GLib.free(). If an error occurs, None will be returned and error set.

items_read:

location to store number of words read, or None. If None, then GLib.ConvertError.PARTIAL_INPUT will be returned in case str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. It’s guaranteed to be non-negative.

items_written:

location to store number of bytes written, or None. The value stored here does not include the trailing 0 byte. It’s guaranteed to be non-negative.

Return type:

(str, items_read: int, items_written: 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. 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.

GLib.utf8_casefold(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • len (int) – length of str, in bytes, or -1 if str is nul-terminated.

Returns:

a newly allocated string, that is a case independent form of str.

Return type:

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 GLib.utf8_casefold() on other strings.

Note that calling GLib.utf8_casefold() followed by 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.

GLib.utf8_collate(str1, str2)[source]
Parameters:

  • str1 (str) – a UTF-8 encoded string

  • str2 (str) – a UTF-8 encoded string

Returns:

< 0 if str1 compares before str2, 0 if they compare equal, > 0 if str1 compares after str2.

Return type:

int

Compares two strings for ordering using the linguistically correct rules for the current locale. When sorting a large number of strings, it will be significantly faster to obtain collation keys with 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.

GLib.utf8_collate_key(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string.

  • len (int) – length of str, in bytes, or -1 if str is nul-terminated.

Returns:

a newly allocated string. This string should be freed with GLib.free() when you are done with it.

Return type:

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

Note that this function depends on the current locale.

GLib.utf8_collate_key_for_filename(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string.

  • len (int) – length of str, in bytes, or -1 if str is nul-terminated.

Returns:

a newly allocated string. This string should be freed with GLib.free() when you are done with it.

Return type:

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.

New in version 2.8.

GLib.utf8_find_next_char(p, end)[source]
Parameters:

  • p (str) – a pointer to a position within a UTF-8 encoded string

  • end (str or None) – a pointer to the byte following the end of the string, or None to indicate that the string is nul-terminated

Returns:

a pointer to the found character or None if end is set and is reached

Return type:

str or 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 None, the return value will never be None: if the end of the string is reached, a pointer to the terminating nul byte is returned. If end is non-None, the return value will be None if the end of the string is reached.

GLib.utf8_find_prev_char(str, p)[source]
Parameters:

  • str (str) – pointer to the beginning of a UTF-8 encoded string

  • p (str) – pointer to some position within str

Returns:

a pointer to the found character or None.

Return type:

str or 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 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.

GLib.utf8_get_char(p)[source]
Parameters:

p (str) – a pointer to Unicode character encoded as UTF-8

Returns:

the resulting character

Return type:

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 GLib.utf8_get_char_validated() instead.

GLib.utf8_get_char_validated(p, max_len)[source]
Parameters:

  • p (str) – a pointer to Unicode character encoded as UTF-8

  • max_len (int) – the maximum number of bytes to read, or -1 if p is nul-terminated

Returns:

the resulting character. If p points to a partial sequence at the end of a string that could begin a valid character (or if max_len is zero), returns (gunichar)-2; otherwise, if p does not point to a valid UTF-8 encoded Unicode character, returns (gunichar)-1.

Return type:

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

GLib.utf8_make_valid(str, len)[source]
Parameters:

  • str (str) – string to coerce into UTF-8

  • len (int) – the maximum length of str to use, in bytes. If len < 0, then the string is nul-terminated.

Returns:

a valid UTF-8 string whose content resembles str

Return type:

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.

New in version 2.52.

GLib.utf8_normalize(str, len, mode)[source]
Parameters:

  • str (str) – a UTF-8 encoded string.

  • len (int) – length of str, in bytes, or -1 if str is nul-terminated.

  • mode (GLib.NormalizeMode) – the type of normalization to perform.

Returns:

a newly allocated string, that is the normalized form of str, or None if str is not valid UTF-8.

Return type:

str or 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 None is returned. You should generally call GLib.utf8_normalize() before comparing two Unicode strings.

The normalization mode GLib.NormalizeMode.DEFAULT only standardizes differences that do not affect the text content, such as the above-mentioned accent representation. 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.

GLib.NormalizeMode.DEFAULT_COMPOSE and GLib.NormalizeMode.ALL_COMPOSE are like GLib.NormalizeMode.DEFAULT and 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.

GLib.utf8_offset_to_pointer(str, offset)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • offset (int) – a character offset within str

Returns:

the resulting pointer

Return type:

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

GLib.utf8_pointer_to_offset(str, pos)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • pos (str) – a pointer to a position within str

Returns:

the resulting character offset

Return type:

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.

GLib.utf8_prev_char(p)[source]
Parameters:

p (str) – a pointer to a position within a UTF-8 encoded string

Returns:

a pointer to the found character

Return type:

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 GLib.utf8_find_prev_char() instead.

GLib.utf8_strchr(p, len, c)[source]
Parameters:

  • p (str) – a nul-terminated UTF-8 encoded string

  • len (int) – the maximum length of p

  • c (str) – a Unicode character

Returns:

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.

Return type:

str or 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.

GLib.utf8_strdown(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • len (int) – length of str, in bytes, or -1 if str is nul-terminated.

Returns:

a newly allocated string, with all characters converted to lowercase.

Return type:

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.

GLib.utf8_strlen(p, max)[source]
Parameters:

  • p (str) – pointer to the start of a UTF-8 encoded string

  • max (int) – 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 None. If max is greater than 0, up to max bytes are examined

Returns:

the length of the string in characters

Return type:

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.

GLib.utf8_strncpy(dest, src, n)[source]
Parameters:

  • dest (str) – buffer to fill with characters from src

  • src (str) – UTF-8 encoded string

  • n (int) – character count

Returns:

dest

Return type:

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

GLib.utf8_strrchr(p, len, c)[source]
Parameters:

  • p (str) – a nul-terminated UTF-8 encoded string

  • len (int) – the maximum length of p

  • c (str) – a Unicode character

Returns:

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.

Return type:

str or 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.

GLib.utf8_strreverse(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • len (int) – the maximum length of str to use, in bytes. If len < 0, then the string is nul-terminated.

Returns:

a newly-allocated string which is the reverse of str

Return type:

str

Reverses a UTF-8 string. str must be valid UTF-8 encoded text. (Use 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 GLib.strreverse(), this function returns newly-allocated memory, which should be freed with GLib.free() when no longer needed.

New in version 2.2.

GLib.utf8_strup(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • len (int) – length of str, in bytes, or -1 if str is nul-terminated.

Returns:

a newly allocated string, with all characters converted to uppercase.

Return type:

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

GLib.utf8_substring(str, start_pos, end_pos)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • start_pos (int) – a character offset within str

  • end_pos (int) – another character offset within str, or -1 to indicate the end of the string

Returns:

a newly allocated copy of the requested substring. Free with GLib.free() when no longer needed.

Return type:

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.

New in version 2.30.

GLib.utf8_to_ucs4(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • len (int) – the maximum length of str to use, in bytes. If len < 0, then the string is nul-terminated.

Raises:

GLib.Error

Returns:

a pointer to a newly allocated UCS-4 string. This value must be freed with GLib.free(). If an error occurs, None will be returned and error set.

items_read:

location to store number of bytes read, or None. If None, then GLib.ConvertError.PARTIAL_INPUT will be returned in case str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here.

items_written:

location to store number of characters written or None. The value here stored does not include the trailing 0 character.

Return type:

(str, items_read: int, items_written: 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.

GLib.utf8_to_ucs4_fast(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • len (int) – the maximum length of str to use, in bytes. If len < 0, then the string is nul-terminated.

Returns:

a pointer to a newly allocated UCS-4 string. This value must be freed with GLib.free().

items_written:

location to store the number of characters in the result, or None.

Return type:

(str, items_written: 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 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.

GLib.utf8_to_utf16(str, len)[source]
Parameters:

  • str (str) – a UTF-8 encoded string

  • len (int) – the maximum length (number of bytes) of str to use. If len < 0, then the string is nul-terminated.

Raises:

GLib.Error

Returns:

a pointer to a newly allocated UTF-16 string. This value must be freed with GLib.free(). If an error occurs, None will be returned and error set.

items_read:

location to store number of bytes read, or None. If None, then GLib.ConvertError.PARTIAL_INPUT will be returned in case str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here.

items_written:

location to store number of #gunichar2 written, or None. The value stored here does not include the trailing 0.

Return type:

(int, items_read: int, items_written: int)

Convert a string from UTF-8 to UTF-16. A 0 character will be added to the result after the converted text.

GLib.utf8_truncate_middle(string, truncate_length)[source]
Parameters:

  • string (str) – a nul-terminated UTF-8 encoded string

  • truncate_length (int) – the new size of string, in characters, including the ellipsis character

Returns:

a newly-allocated copy of string ellipsized in the middle

Return type:

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.

New in version 2.78.

GLib.utf8_validate(str)[source]
Parameters:

str (bytes) – a pointer to character data

Returns:

True if the text was valid UTF-8

end:

return location for end of valid data

Return type:

(bool, end: 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-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 GLib.utf8_validate() returns False if max_len is positive and any of the max_len bytes are nul.

Returns True if all of str was valid. Many GLib and GTK routines require valid UTF-8 as input; so data read from a file or the network should be checked with GLib.utf8_validate() before doing anything else with it.

GLib.utf8_validate_len(str)[source]
Parameters:

str (bytes) – a pointer to character data

Returns:

True if the text was valid UTF-8

end:

return location for end of valid data

Return type:

(bool, end: str)

Validates UTF-8 encoded text.

As with GLib.utf8_validate(), but max_len must be set, and hence this function will always return False if any of the bytes of str are nul.

New in version 2.60.

GLib.uuid_string_is_valid(str)[source]
Parameters:

str (str) – a string representing a UUID

Returns:

True if str is a valid UUID, False otherwise.

Return type:

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.

New in version 2.52.

GLib.uuid_string_random()[source]
Returns:

A string that should be freed with GLib.free().

Return type:

str

Generates a random UUID (RFC 4122 version 4) as a string. It has the same randomness guarantees as GLib.Rand, so must not be used for cryptographic purposes such as key generation, nonces, salts or one-time pads.

New in version 2.52.

GLib.variant_get_gtype()
Return type:

GObject.GType

GLib.variant_is_object_path(string)[source]
Parameters:

string (str) – a normal C nul-terminated string

Returns:

True if string is a D-Bus object path

Return type:

bool

Determines if a given string is a valid D-Bus object path. You should ensure that a string is a valid D-Bus object path before passing it to GLib.Variant.new_object_path().

A valid object path starts with / followed by zero or more sequences of characters separated by / characters. Each sequence must contain only the characters [A-Z][a-z][0-9]_. No sequence (including the one following the final / character) may be empty.

New in version 2.24.

GLib.variant_is_signature(string)[source]
Parameters:

string (str) – a normal C nul-terminated string

Returns:

True if string is a D-Bus type signature

Return type:

bool

Determines if a given string is a valid D-Bus type signature. You should ensure that a string is a valid D-Bus type signature before passing it to GLib.Variant.new_signature().

D-Bus type signatures consist of zero or more definite GLib.VariantType strings in sequence.

New in version 2.24.

GLib.variant_parse(type, text, limit, endptr)[source]
Parameters:
Raises:

GLib.Error

Returns:

a non-floating reference to a GLib.Variant, or None

Return type:

GLib.Variant

Parses a GLib.Variant from a text representation.

A single GLib.Variant is parsed from the content of text.

The format is described here.

The memory at limit will never be accessed and the parser behaves as if the character at limit is the nul terminator. This has the effect of bounding text.

If endptr is non-None then text is permitted to contain data following the value that this function parses and endptr will be updated to point to the first character past the end of the text parsed by this function. If endptr is None and there is extra data then an error is returned.

If type is non-None then the value will be parsed to have that type. This may result in additional parse errors (in the case that the parsed value doesn’t fit the type) but may also result in fewer errors (in the case that the type would have been ambiguous, such as with empty arrays).

In the event that the parsing is successful, the resulting GLib.Variant is returned. It is never floating, and must be freed with GLib.Variant.unref().

In case of any error, None will be returned. If error is non-None then it will be set to reflect the error that occurred.

Officially, the language understood by the parser is “any string produced by GLib.Variant.print_()”.

There may be implementation specific restrictions on deeply nested values, which would result in a GLib.VariantParseError.RECURSION error. GLib.Variant is guaranteed to handle nesting up to at least 64 levels.

GLib.variant_parse_error_print_context(error, source_str)[source]
Parameters:
Returns:

the printed message

Return type:

str

Pretty-prints a message showing the context of a GLib.Variant parse error within the string for which parsing was attempted.

The resulting string is suitable for output to the console or other monospace media where newlines are treated in the usual way.

The message will typically look something like one of the following:

unterminated string constant:
(1, 2, 3, 'abc
          ^^^^

or

unable to find a common type:
[1, 2, 3, 'str']
 ^        ^^^^^

The format of the message may change in a future version.

error must have come from a failed attempt to GLib.Variant.parse() and source_str must be exactly the same string that caused the error. If source_str was not nul-terminated when you passed it to GLib.Variant.parse() then you must add nul termination before using this function.

New in version 2.40.

GLib.variant_parse_error_quark()[source]
Return type:

int

GLib.variant_parser_get_error_quark()[source]
Return type:

int

Same as g_variant_error_quark().

Deprecated since version ???: Use GLib.Variant.parse_error_quark() instead.

GLib.variant_type_checked_(arg0)[source]
Parameters:

arg0 (str) –

Return type:

GLib.VariantType

GLib.variant_type_string_get_depth_(type_string)[source]
Parameters:

type_string (str) –

Return type:

int

GLib.variant_type_string_is_valid(type_string)[source]
Parameters:

type_string (str) – a pointer to any string

Returns:

True if type_string is exactly one valid type string

Return type:

bool

Checks if type_string is a valid GLib.Variant type string. This call is equivalent to calling GLib.VariantType.string_scan() and confirming that the following character is a nul terminator.

GLib.variant_type_string_scan(string, limit)[source]
Parameters:

  • string (str) – a pointer to any string

  • limit (str or None) – the end of string, or None

Returns:

True if a valid type string was found

endptr:

location to store the end pointer, or None

Return type:

(bool, endptr: str)

Scan for a single complete and valid GLib.Variant type string in string. The memory pointed to by limit (or bytes beyond it) is never accessed.

If a valid type string is found, endptr is updated to point to the first character past the end of the string that was found and True is returned.

If there is no valid type string starting at string, or if the type string does not end before limit then False is returned.

For the simple case of checking if a string is a valid type string, see GLib.VariantType.string_is_valid().

New in version 2.24.