Expand description
§Rust GLib and GObject bindings
Rust bindings and wrappers for GLib, part of gtk-rs-core.
GLib 2.56 is the lowest supported version for the underlying library.
This library contains bindings to GLib and GObject types and APIs as well as common building blocks used in both handmade and machine generated bindings to GTK and other GLib-based libraries.
It is the foundation for higher level libraries with uniform Rusty (safe and strongly typed) APIs. It avoids exposing GLib-specific data types where possible and is not meant to provide comprehensive GLib bindings, which would often amount to duplicating the Rust Standard Library or other utility crates.
§Minimum supported Rust version
Currently, the minimum supported Rust version is 1.70.0
.
§Dynamic typing
Most types in the GLib family have Type
identifiers.
Their corresponding Rust types implement the StaticType
trait.
A dynamically typed Value
can carry values of any StaticType
.
Variants can carry values of StaticVariantType
.
§Errors
Errors are represented by Error
, which can
carry values from various error domains such as
FileError
.
§Objects
Each class and interface has a corresponding smart pointer struct
representing an instance of that type (e.g. Object
for GObject
or
gtk4::Widget
for GtkWidget
). They are reference counted and feature
interior mutability similarly to Rust’s
Rc<RefCell<T>>
idiom. Consequently, cloning objects is cheap and their methods never require
mutable borrows. Two smart pointers are equal if they point to the same
object.
The root of the object hierarchy is Object
.
Inheritance and subtyping is denoted with the IsA
marker trait. The Cast
trait enables upcasting
and downcasting.
Interfaces and non-leaf classes also have corresponding traits (e.g.
ObjectExt
or WidgetExt
), which are blanketly implemented for all
their subtypes.
You can create new subclasses of Object
or other object types. Look at
the module’s documentation for further details and a code example.
§Under the hood
GLib-based libraries largely operate on pointers to various boxed or
reference counted structures so the bindings have to implement corresponding
smart pointers (wrappers), which encapsulate resource management and safety
checks. Such wrappers are defined via the
wrapper!
macro, which uses abstractions
defined in the wrapper
, boxed
,
shared
and object
modules.
The translate
module defines and partly implements
conversions between high level Rust types (including the aforementioned
wrappers) and their FFI counterparts.
§Documentation
§Using
We recommend using crates from crates.io, as demonstrated here.
If you want to track the bleeding edge, use the git dependency instead:
[dependencies]
glib = { git = "https://github.com/gtk-rs/gtk-rs-core.git", package = "glib" }
Avoid mixing versioned and git crates like this:
# This will not compile
[dependencies]
glib = "0.13"
glib = { git = "https://github.com/gtk-rs/gtk-rs-core.git", package = "glib" }
§License
glib is available under the MIT License, please refer to it.
Re-exports§
pub use self::closure::Closure;
pub use self::closure::RustClosure;
pub use self::enums::EnumClass;
pub use self::enums::EnumValue;
pub use self::enums::FlagsBuilder;
pub use self::enums::FlagsClass;
pub use self::enums::FlagsValue;
pub use self::enums::UserDirectory;
pub use self::error::BoolError;
pub use self::error::Error;
pub use self::object::BorrowedObject;
pub use self::object::Class;
pub use self::object::InitiallyUnowned;
pub use self::object::Interface;
pub use self::object::Object;
pub use self::object::SendWeakRef;
pub use self::object::WeakRef;
pub use self::signal::signal_handler_block;
pub use self::signal::signal_handler_disconnect;
pub use self::signal::signal_handler_unblock;
pub use self::signal::signal_stop_emission_by_name;
pub use self::signal::Propagation;
pub use self::signal::SignalHandlerId;
pub use self::types::ILong;
pub use self::types::Pointer;
pub use self::types::Type;
pub use self::types::ULong;
pub use self::value::BoxedValue;
pub use self::value::SendValue;
pub use self::value::Value;
pub use self::variant::FixedSizeVariantArray;
pub use self::variant::Variant;
pub use self::FileError;
pub use collections::List;
pub use collections::PtrSlice;
pub use collections::SList;
pub use collections::Slice;
pub use collections::StrV;
pub use self::char::Char;
pub use self::char::UChar;
pub use self::match_info::MatchInfo;
pub use bitflags;
pub use glib_sys as ffi;
pub use gobject_sys as gobject_ffi;
pub use self::source::*;
Modules§
IMPL
Boxed wrapper implementation.IMPL
BoxedInline wrapper implementation.Error
binding and helper trait.IMPL
Object wrapper implementation andObject
binding.- Traits and essential types intended for blanket imports.
- This module is inefficient and should not be used by Rust programs except for compatibility with GLib.Regex based APIs.
IMPL
Shared (reference counted) wrapper implementation.IMPL
Low level signal support.- Module containing infrastructure for subclassing
GObject
s and registering boxed types. - Translation between GLib/GLib-based FFI types and their Rust counterparts.
- Runtime type information.
Value
binding and helper traits.Variant
binding and helper traits.IMPL
Thewrapper!
macro and miscellaneous wrapper traits.
Macros§
- Generic error used for functions that fail without any further information
- Macro for passing variables as strong or weak references into a closure.
- Macro for creating a
Closure
object. This is a wrapper aroundClosure::new
that automatically type checks its arguments at run-time. - The same as
closure!
but usesClosure::new_local
as a constructor. This is useful for closures which can’t be sent across threads. See the documentation ofclosure!
for details. - debug
log
andlog_macros
A macro which behaves exactly aslog::debug!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - error
log
andlog_macros
A macro which behaves exactly aslog::error!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - This macro returns the name of the enclosing function. As the internal implementation is based on the
std::any::type_name
, this macro derives all the limitations of this function. - Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to print messages. It uses g_print.
- Macro used to print error messages. It uses g_printerr.
- Macro used to log using GLib logging system. It uses g_log.
- Creates a
GString
using interpolation of runtime expressions. - Wrapper implementations for BoxedInline types. See
wrapper!
. - Wrapper implementations for Boxed types. See
wrapper!
. - ObjectType implementations for Object types. See
wrapper!
. - Wrapper implementations for shared types. See
wrapper!
. - Converts a static string literal into a static nul-terminated string.
- info
log
andlog_macros
A macro which behaves exactly aslog::info!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - Macro used to log using GLib structured logging system.
- trace
log
andlog_macros
A macro which behaves exactly aslog::trace!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - warn
log
andlog_macros
A macro which behaves exactly aslog::warn!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - Defines a wrapper type and implements the appropriate traits.
Structs§
GObject
instance (or source) and another property on anotherGObject
instance (or target).- Flags to be passed to
ObjectExt::bind_property()
or [ObjectExt::bind_property_full()
][crate::prelude::ObjectExt::bind_property_full()]. - Binding
Group v2_72
GBindingGroup
can be used to bind multiple properties from an object collectively. - Binding
Group Builder v2_72
Builder for binding group bindings. - This is a subclass of
glib::object::Object
capable of storing any Rust type. It let’s you insert a Rust type anywhere aglib::object::Object
is needed. The inserted value can then be borrowed as a Rust type, by using the various provided methods. - Contains the public fields of a GByteArray.
- A shared immutable byte slice (the equivalent of
Rc<[u8]>
). - GLib provides a generic API for computing checksums (or ‘digests’) for a sequence of arbitrary bytes, using various hashing algorithms like MD5, SHA-1 and SHA-256. Checksums are commonly used in various environments and specifications.
- A
CollationKey
allows ordering strings using the linguistically correct rules for the current locale. - GLib type: Inline allocated boxed type with stack copy semantics.
GDateTime
is a structure that combines a Gregorian date and time into a single structure.- File
SetContents Flags v2_66
Flags to pass to g_file_set_contents_full() to affect its safety and performance. - A
FilenameCollationKey
allows ordering file names using the linguistically correct rules for the current locale. Compared toCollationKey
, filename collation keys take into consideration dots and other characters commonly found in file names. - Flags to modify the format of the string returned by g_format_size_full().
- The error returned when a future times out.
- Representation of a borrowed
GString
. - Error type indicating that a buffer had unexpected nul-bytes.
- A type representing an owned, C-compatible, nul-terminated UTF-8 string.
- A mutable text buffer that grows automatically.
- Error type indicating that a buffer had unexpected nul-bytes.
- Error type indicating that a buffer did not have a trailing nul-byte.
NULL
-terminated UTF-8 string as stored inStrV
.- Error type indicating that a buffer had invalid UTF-8.
- Glib
Logger log
An implementation of alog
compatible logger which logs over glib logging facilities. - The GIConv struct wraps an iconv() conversion descriptor. It contains private data and should only be accessed using the following functions.
- A bitwise combination representing a condition to watch for on an event source.
- A structure that provides information to the type system which is used specifically for managing interface types.
- Task failure from awaiting a
JoinHandle
. - A handle to a task running on a
MainContext
. GKeyFile
parses .ini-like config files.- Flags which influence the parsing.
- Structure representing a single field in a structured log entry.
- Flags specifying the level of log messages.
- The
GMainContext
struct is an opaque data type representing a set of sources to be handled in a main loop. - Main
Context Flags v2_72
Flags to pass to g_main_context_new_with_flags() which affect the behaviour of a #GMainContext. - The
GMainLoop
struct is an opaque data type representing the main event loop of a GLib or GTK application. - A parse context is used to parse a stream of bytes that you expect to contain marked-up text.
- Flags which modify individual options.
- Through the
ParamFlags
flag values, certain aspects of parameters can be configured. GParamSpec
encapsulates the metadata required to specify parameters, such asGObject
properties.- GLib type: Shared boxed type with reference counted clone semantics.
- A
ParamSpec
derived structure that contains the meta data for boxed properties. - GLib type: Shared boxed type with reference counted clone semantics.
- A
ParamSpec
derived structure that contains the meta data for double properties. - GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- A
ParamSpec
derived structure that contains the meta data for float properties. - A
ParamSpec
derived structure that contains the meta data forGType
properties. - GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- A
ParamSpec
derived structure that contains the meta data for object properties. - A
ParamSpec
derived structure that contains the meta data forG_TYPE_PARAM
properties. - A
ParamSpec
derived structure that contains the meta data for pointer properties. - A
ParamSpec
derived structure that contains the meta data for string properties. - GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- A
ParamSpec
derived structure that contains the meta data forGValueArray
properties. - A
ParamSpec
derived structure that contains the meta data forGVariant
properties. - A
GRegex
is the “compiled” form of a regular expression pattern. - Flags specifying compile-time options.
- Flags specifying match-time options.
- The signal flags are used to specify a signal’s behaviour.
- Signal
Group v2_74
GSignalGroup
manages a collection of signals on aGObject
. - The
GSource
struct is an opaque data type representing an event source. - Represents a
Future
around aglib::Source
. The future will be resolved once the source has provided a value - Represents a
Stream
around aglib::Source
. The stream will be provide all values that are provided by the source - Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
- Variant of
JoinHandle
that is returned fromMainContext::spawn_from_within
. - A handle to a thread running on a
ThreadPool
. - The
GThreadPool
struct represents a thread pool. - A value representing an interval of time, in microseconds.
- A
GTimeZone
represents a time zone, at no particular point in time. - Bit masks used to check or determine characteristics of a type.
- This structure is used to provide the type system with the information required to initialize and destruct (finalize) a type’s class and its instances.
GTypeModule
provides a simple implementation of theGTypePlugin
interface.- An interface that handles the lifecycle of dynamically loaded types.
- The
TypeValueTable
provides the functions required by theValue
implementation, to serve as a container for values of a type. - Uri
v2_66
TheGUri
type and related functions can be used to parse URIs into their components, and build valid URIs from individual components. - UriFlags
v2_66
Flags that describe a URI. - UriHide
Flags v2_66
Flags describing what parts of the URI to hide in g_uri_to_string_partial(). Note thatPASSWORD
andAUTH_PARAMS
will only work if the #GUri was parsed with the corresponding flags. - UriParams
Flags v2_66
Flags modifying the way parameters are handled by g_uri_parse_params() and #GUriParamsIter. - GLib type: Boxed type with copy-on-clone semantics.
VariantDict
is a mutable key/value store where the keys are always strings and the values areVariant
s.- Iterator over items in a variant.
- Iterator over items in a variant of type
as
. - Describes
Variant
types. - An iterator over the individual components of a tuple VariantTy.
- Describes
Variant
types.
Enums§
- The result of a single step of the Unicode canonical decomposition algorithm
- The hashing algorithm to be used by #GChecksum when performing the digest of some data.
- Continue calling the closure in the future iterations or drop it.
- Error codes returned by character set conversion routines.
- A wrapper for
ConvertError
that can hold an offset into the input string. - The kind of decomposition to perform
- Values corresponding to @errno codes returned from file operations on UNIX. Unlike @errno codes, GFileError values are available on all systems, even Windows. The exact meaning of each code depends on what sort of file operation you were performing; the UNIX documentation gives more details. The following error code descriptions come from the GNU C Library manual, and are under the copyright of that manual.
- Error type holding all possible failures when creating a
GStr
reference. - Error type holding all possible failures when creating a
GString
. - Enumeration of the possible domain handling behaviours for a
GlibLogger
. - Enumeration of the possible formatting behaviours for a
GlibLogger
. - A wrapper for
std::io::Error
that can hold an offset into an input string. - Error codes returned by key file parsing.
- Return values from #GLogWriterFuncs to indicate whether the given log entry was successfully handled by the writer, or whether there was an error in handling it (and hence a fallback writer should be used).
- Error codes returned by markup parsing.
- Defines how a Unicode string is transformed in a 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. Unicode strings should generally be normalized before comparing them.
- The #GOptionArg enum values determine which type of extra argument the options expect to find. If an option expects an extra argument, it can be specified in several ways; with a short option:
-x arg
, with a long option:--name arg
or combined in a single argument:--name=arg
. - An enumeration specifying the base position for a g_io_channel_seek_position() operation.
- Disambiguates a given time in two ways.
- These are the possible line break classifications.
- The #GUnicodeScript enumeration identifies different writing systems. The values correspond to the names as defined in the Unicode standard. The enumeration has been added in GLib 2.14, and is interchangeable with #PangoScript.
- These are the possible character classifications from the Unicode specification. See Unicode Character Database.
- UriError
v2_66
Error codes returned by #GUri methods. - The range of possible top-level types of #GVariant instances.
Constants§
- This is the log domain used by the
clone!
macro. If you want to use a custom logger (it prints to stdout by default), you can set your own logger using the correspondinglog
functions.
Statics§
- The set of uppercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig.
- The set of ASCII digits. Used for specifying valid identifier characters in #GScannerConfig.
- The set of lowercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig.
- The name of the main group of a desktop entry file, as defined in the Desktop Entry Specification. Consult the specification for more details about the meanings of the keys below.
- A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a string list giving the available application actions. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a list of strings giving the categories in which the desktop entry should be shown in a menu. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a localized string giving the tooltip for the desktop entry. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a boolean set to true if the application is D-Bus activatable. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a string giving the command line to execute. It is only valid for desktop entries with theApplication
type. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a localized string giving the generic name of the desktop entry. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a boolean stating whether the desktop entry has been deleted by the user. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a localized string giving the name of the icon to be displayed for the desktop entry. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a list of strings giving the MIME types supported by this desktop entry. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a localized string giving the specific name of the desktop entry. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a list of strings identifying the environments that should not display the desktop entry. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a boolean stating whether the desktop entry should be shown in menus. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a list of strings identifying the environments that should display the desktop entry. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a string containing the working directory to run the program in. It is only valid for desktop entries with theApplication
type. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a boolean stating whether the application supports the Startup Notification Protocol Specification. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is string identifying the WM class or name hint of a window that the application will create, which can be used to emulate Startup Notification with older applications. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a boolean stating whether the program should be run in a terminal window. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a string giving the file name of a binary on disk used to determine if the program is actually installed. It is only valid for desktop entries with theApplication
type. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a string giving the type of the desktop entry. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a string giving the URL to access. It is only valid for desktop entries with theLink
type. - A key under
KEY_FILE_DESKTOP_GROUP
, whose value is a string giving the version of the Desktop Entry Specification used for the desktop entry file. - The value of the
KEY_FILE_DESKTOP_KEY_TYPE
, key for desktop entries representing applications. - The value of the
KEY_FILE_DESKTOP_KEY_TYPE
, key for desktop entries representing directories. - The value of the
KEY_FILE_DESKTOP_KEY_TYPE
, key for desktop entries representing links to documents. - If a long option in the main group has this name, it is not treated as a regular option. Instead it collects all non-option arguments which would otherwise be left in
argv
. The option must be of typeOptionArg::Callback
,OptionArg::StringArray
orOptionArg::FilenameArray
. - The standard delimiters, used in
strdelimit()
. - Creates a unique temporary directory for each unit test and uses g_set_user_dirs() to set XDG directories to point into subdirectories of it for the duration of the unit test. The directory tree is cleaned up after the test finishes successfully. Note that this doesn’t take effect until g_test_run() is called, so calls to (for example) g_get_user_home_dir() will return the system-wide value when made in a test program’s main() function.
- Generic delimiters characters as defined in RFC 3986. Includes
:/?#[]@
. - Subcomponent delimiter characters as defined in RFC 3986. Includes
!$&'()*+,;=
.
Traits§
- A trait implemented by the various
ParamSpec
builder types. - This trait provides access to Unicode character classification and manipulations functions provided by GLib that do not exist in the standard library
Functions§
- 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.
- Gets a human-readable name for the application, as set by g_set_application_name(). This name should be localized if possible, and is intended for display to the user. Contrast with g_get_prgname(), which gets a non-localized name. If g_set_application_name() has not been called, returns the result of g_get_prgname() (which may be
None
if g_set_prgname() has also not been called). - 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.
- Encode a sequence of binary data into its Base-64 stringified representation.
- Obtain the character set for the current locale.
- Checks that the GLib library in use is compatible with the given version.
- Create a
Future
that will resolve once the child process with the given pid exits - Create a
Future
that will resolve once the child process with the given pid exits - Gets the character set for the current locale.
- Computes the checksum for a binary @data. This is a convenience wrapper for g_checksum_new(), g_checksum_get_string() and g_checksum_free().
- Computes the checksum for a binary @data of @length. This is a convenience wrapper for g_checksum_new(), g_checksum_get_string() and g_checksum_free().
- Computes the HMAC for a binary @data. This is a convenience wrapper for g_hmac_new(), g_hmac_get_string() and g_hmac_unref().
- Computes the HMAC for a binary @data of @length. This is a convenience wrapper for g_hmac_new(), g_hmac_get_string() and g_hmac_unref().
- console_
charset v2_62
Obtains the character set used by the console attached to the process, which is suitable for printing output to the terminal. - Converts a string from one character set to another.
- 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.
- Gets the current directory.
- This is a variant of g_dgettext() that allows specifying a locale category instead of always using
LC_MESSAGES
. See g_dgettext() for more information about how this functions differs from calling dcgettext() directly. - 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.
- 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.
- This function is a variant of g_dgettext() which supports a disambiguating message context. GNU gettext uses the ‘\004’ character to separate the message context and message id in @msgctxtid. If 0 is passed as @msgidoffset, this function will fall back to trying to use the deprecated convention of using “|” as a separation character.
- This function is a variant of g_dgettext() which supports a disambiguating message context. GNU gettext uses the ‘\004’ character to separate the message context and message id in @msgctxtid.
- Gets the list of environment variables for the current process.
- Reads an entire file into allocated memory, with good error checking.
- Opens a file for writing in the preferred directory for temporary files (as returned by g_get_tmp_dir()).
- Writes all of @contents to a file named @filename. This is a convenience wrapper around calling g_file_set_contents_full() with
flags
set toG_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING
andmode
set to0666
. - Writes all of @contents to a file named @filename, with good error checking. If a file called @filename already exists it will be overwritten.
- Determines the preferred character sets used for filenames. The first character set from the @charsets is the filename encoding, the subsequent character sets are used when trying to generate a displayable representation of a filename, see g_filename_display_name().
- 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.
- Converts a filename into a valid UTF-8 string. The conversion is not necessarily reversible, so you should keep the original around and use the return value of this function only for display purposes. Unlike g_filename_to_utf8(), the result is guaranteed to be non-
None
even if the filename actually isn’t in the GLib file name encoding. - Converts an escaped ASCII-encoded URI to a local filename in the encoding used for filenames.
- Converts a string from UTF-8 to the encoding GLib uses for filenames. Note that on Windows GLib uses UTF-8 for filenames; on other platforms, this function indirectly depends on the [current locale][setlocale].
- Converts an absolute filename to an escaped ASCII-encoded URI, with the path component following Section 3.3. of RFC 2396.
- Converts a string which is in the encoding used by GLib for filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 for filenames; on other platforms, this function indirectly depends on the [current locale][setlocale].
- 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, andNone
otherwise. - 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.
- Formats a size.
- Add a timeout to a
Future
. - Add a timeout to a
Future
. - Returns the value of an environment variable.
- Gets the current user’s home directory.
- Return a name for the machine.
- Tests if @hostname contains segments with an ASCII-compatible encoding of an Internationalized Domain Name. If this returns
true
, you should decode the hostname with g_hostname_to_unicode() before displaying it to the user. - Tests if @hostname is the string form of an IPv4 or IPv6 address. (Eg, “192.168.0.1”.)
- Tests if @hostname contains Unicode characters. If this returns
true
, you need to encode the hostname with g_hostname_to_ascii() before using it in non-IDN-aware contexts. - Converts @hostname to its canonical ASCII form; an ASCII-only string containing no uppercase letters and not ending with a trailing dot.
- 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.
- Create a
Stream
that will provide a value every given number of milliseconds. - Create a
Stream
that will provide a value every given number of seconds. - Create a
Stream
that will provide a value every given number of seconds. - Create a
Stream
that will provide a value every given number of milliseconds. - 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”.
- 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”.
- Gets the names of all variables set in the environment.
- Converts a string from UTF-8 to the encoding used for strings by the C runtime (usually the same as that used by the operating system) in the [current locale][setlocale]. On Windows this means the system codepage.
- Converts a string which is in the encoding used for strings by the C runtime (usually the same as that used by the operating system) in the [current locale][setlocale] into a UTF-8 string.
- 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. - To set back the default print handler, use the
log_unset_default_handler
function. - To set the default print handler, use the
log_set_default_handler
function. - Sets whether GLib log functions output to stderr or stdout.
- Returns the currently firing source for this thread.
- Returns the depth of the stack of calls to g_main_context_dispatch() on any #GMainContext in the current thread. That is, when called from the toplevel, it gives 0. When called from within a callback from g_main_context_iteration() (or g_main_loop_run(), etc.) it returns 1. When called from within a callback to a recursive call to g_main_context_iteration(), it returns 2. And so forth.
- 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.
- Create a directory if it doesn’t already exist. Create intermediate parent directories as needed, too.
- Creates a temporary directory. See the mkdtemp() documentation on most UNIX-like systems.
- Creates a temporary directory. See the mkdtemp() documentation on most UNIX-like systems.
- Opens a temporary file. See the mkstemp() documentation on most UNIX-like systems.
- Opens a temporary file. See the mkstemp() documentation on most UNIX-like systems.
- Queries the system monotonic time.
- 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.
- 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. - Invokes gdb, which attaches to the current process and shows a stack trace. Called by g_on_error_query() when the “[S]tack trace” option is selected. You can get the current process’s program name with g_get_prgname(), assuming that you have called gtk_init() or gdk_init().
- os_info
v2_64
Get information about the operating system. - Same as
get_prgname()
. - Returns a random #gdouble equally distributed over the range [0..1).
- Returns a random #gdouble equally distributed over the range [@begin..@end).
- Return a random #guint32 equally distributed over the range [0..2^32-1].
- Returns a random #gint32 equally distributed over the range [@begin..@end-1].
- Sets the seed for the global random number generator, which is used by the g_random_* functions, to @seed.
- Gets the real name of the user. This usually comes from the user’s entry in the
passwd
file. The encoding of the returned string is system-defined. (On Windows, it is, however, always UTF-8.) If the real user name cannot be determined, the string “Unknown” is returned. - Queries the system wall-clock time.
- Resets the cache used for g_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.
- Provides a glib log handler which routes all logging messages to the
log crate
. - 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 g_set_prgname(), which sets a non-localized name. g_set_prgname() will be called automatically by gtk_init(), but g_set_application_name() will not.
- To set back the default print handler, use the
unset_print_handler
function. - To set back the default print handler, use the
unset_printerr_handler
function. - Same as
set_prgname()
. - 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.
- 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).
- Quotes a string so that the shell (/bin/sh) will interpret the quoted string to mean @unquoted_string.
- Unquotes a string as the shell (/bin/sh) would.
- 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 #GHashTable.
- Executes a child program asynchronously.
- spawn_
async_ with_ fds v2_58
and non-Windows - spawn_
async_ with_ pipes Non-Windows - spawn_
check_ exit_ status Deprecated An old name for g_spawn_check_wait_status(), deprecated because its name is misleading. - Set @error if @wait_status indicates the child exited abnormally (e.g. with a nonzero exit code, or via a fatal signal).
- A simple version of g_spawn_async() that parses a command line with g_shell_parse_argv() and passes it to g_spawn_async().
- Spawn a new infallible
Future
on the thread-default main context. - Spawn a new infallible
Future
on the thread-default main context. - Returns an ordered list of base directories in which to access system-wide configuration information.
- Returns an ordered list of base directories in which to access system-wide application data.
- Create a
Future
that will resolve after the given number of milliseconds. - Create a
Future
that will resolve after the given number of seconds. - Create a
Future
that will resolve after the given number of seconds. - Create a
Future
that will resolve after the given number of milliseconds. - Gets the directory to use for temporary files.
- 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.
- Create a
Future
that will resolve once the given UNIX signal is raised - Create a
Future
that will resolve once the given UNIX signal is raised - Create a
Stream
that will provide a value whenever the given UNIX signal is raised - Create a
Stream
that will provide a value whenever the given UNIX signal is raised - 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.
- To set the default print handler, use the
set_print_handler
function. - To set the default print handler, use the
set_printerr_handler
function. - Removes an environment variable from the environment.
- Returns a base directory in which to store non-essential, cached data specific to particular user.
- Returns a base directory in which to store user-specific application configuration information such as user preferences and settings.
- Returns a base directory in which to access application data such as icons that is customized for a particular user.
- Gets the user name of the current user. The encoding of the returned string is system-defined. On UNIX, it might be the preferred file name encoding, or something else, and there is no guarantee that it is even consistent on a machine. On Windows, it is always UTF-8.
- Returns a directory that is unique to the current user on the local system.
- Returns the full path of a special directory using its logical id.
- user_
state_ dir v2_72
Returns a base directory in which to store state files specific to particular user. - Pauses the current thread for the given number of microseconds.
- Parses the string @str and verify if it is a UUID.
- Generates a random UUID (RFC 4122 version 4) as a string. It has the same randomness guarantees as #GRand, so must not be used for cryptographic purposes such as key generation, nonces, salts or one-time pads.
Type Aliases§
Attribute Macros§
- When applied to
ObjectImpl
- Attribute macro for defining flags using the
bitflags
crate. This macro will also define aGFlags::type_
function and theglib::Value
traits. - Macro for boilerplate of
ObjectInterface
implementations. - Macro for boilerplate of
ObjectSubclass
implementations.
Derive Macros§
- Derive macro for defining a
BoxedType
::type_
function and theglib::Value
traits. Optionally, the type can be marked asnullable
to get an implementation ofglib::value::ToValueOptional
. - Macro for deriving implementations of
glib::clone::Downgrade
andglib::clone::Upgrade
traits and a weak type. - Derive macro to register a Rust enum in the GLib type system and derive the
glib::Value
traits. - Derive macro for defining a GLib error domain and its associated
ErrorDomain
trait. - This macro enables you to derive object properties in a quick way.
- Derive macro for defining a
SharedType
::get_type
function and theglib::Value
traits. Optionally, the type can be marked asnullable
to get an implementation ofglib::value::ToValueOptional
. - Example
- Derive macro for serializing/deserializing custom structs/enums as
glib::Variant
s.