Module: GLib

Extended by:
Deprecatable
Defined in:
lib/gio2/deprecated.rb

Overview

Copyright (C) 2013-2017 Ruby-GNOME2 Project Team

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Defined Under Namespace

Modules: AsciiType, BookmarkFileError, ChecksumType, ConvertError, DateDMY, DateMonth, DateWeekday, ErrorType, FileError, FileSetContentsFlags, FileTest, FormatSizeFlags, HookFlagMask, IOChannelError, IOCondition, IOError, IOFlags, IOStatus, KeyFileError, KeyFileFlags, LogLevelFlags, LogWriterOutput, MainContextFlags, MarkupCollectType, MarkupError, MarkupParseFlags, NormalizeMode, NumberParserError, OnceStatus, OptionArg, OptionError, OptionFlags, RegexCompileFlags, RegexError, RegexMatchFlags, SeekType, ShellError, SliceConfig, SpawnError, SpawnFlags, TestFileType, TestLogType, TestResult, TestSubprocessFlags, TestTrapFlags, ThreadError, ThreadPriority, TimeType, TokenType, TraverseFlags, TraverseType, UnicodeBreakType, UnicodeScript, UnicodeType, UnixPipeEnd, UriError, UriFlags, UriHideFlags, UriParamsFlags, UserDirectory, VariantClass, VariantParseError

Constant Summary collapse

ALLOCATOR_LIST = 
1
ALLOCATOR_NODE = 
3
ALLOCATOR_SLIST = 
2
ALLOC_AND_FREE = 
2
ALLOC_ONLY = 
1
ANALYZER_ANALYZING = 
1
ASCII_DTOSTR_BUF_SIZE =

A good size for a buffer to be passed into [funcGLib.ascii_dtostr]. It is guaranteed to be enough for all output of that function on systems with 64bit IEEE-compatible doubles.

The typical usage would be something like:

char buf[G_ASCII_DTOSTR_BUF_SIZE];

fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));

39
ATOMIC_REF_COUNT_INIT =

Evaluates to the initial reference count for gatomicrefcount.

This macro is useful for initializing gatomicrefcount fields inside structures, for instance:

typedef struct {
  gatomicrefcount ref_count;
  char *name;
  char *address;
} Person;

static const Person default_person = {
  .ref_count = G_ATOMIC_REF_COUNT_INIT,
  .name = "Default name",
  .address = "Default address",
};

1
BIG_ENDIAN = 
4321
CSET_A_2_Z =

The set of uppercase ASCII alphabet characters. Used for specifying valid identifier characters in GScanner::Config.

ABCDEFGHIJKLMNOPQRSTUVWXYZ
CSET_DIGITS =

The set of ASCII digits. Used for specifying valid identifier characters in GScanner::Config.

0123456789
CSET_a_2_z =

The set of lowercase ASCII alphabet characters. Used for specifying valid identifier characters in GScanner::Config.

abcdefghijklmnopqrstuvwxyz
C_STD_VERSION = 
199000
DATALIST_FLAGS_MASK =

A bitmask that restricts the possible flags passed to g_datalist_set_flags(). Passing a flags value where flags & ~G_DATALIST_FLAGS_MASK != 0 is an error.

3
DATE_BAD_DAY =

Represents an invalid GDate::Day.

0
DATE_BAD_JULIAN =

Represents an invalid Julian day number.

0
DATE_BAD_YEAR =

Represents an invalid year.

0
DIR_SEPARATOR = 
47
DIR_SEPARATOR_S = 
/
E = 
2.718282
GINT16_FORMAT = 
hi
GINT16_MODIFIER = 
h
GINT32_FORMAT = 
i
GINT32_MODIFIER = 

      
        
GINT64_FORMAT =
          
        

        
li

      
        
GINT64_MODIFIER =
          
        

        
l

      
        
GINTPTR_FORMAT =
          
        

        
li

      
        
GINTPTR_MODIFIER =
          
        

        
l

      
        
GNUC_FUNCTION =
          

  

    
Expands to "" on all modern compilers, and to  FUNCTION on gcc
version 2.x. Don't use it.



  





  



        

        

      
        
GNUC_PRETTY_FUNCTION =
          

  

    
Expands to "" on all modern compilers, and to PRETTY_FUNCTION
on gcc version 2.x. Don't use it.



  





  



        

        

      
        
GSIZE_FORMAT =
          
        

        
lu

      
        
GSIZE_MODIFIER =
          
        

        
l

      
        
GSSIZE_FORMAT =
          
        

        
li

      
        
GSSIZE_MODIFIER =
          
        

        
l

      
        
GUINT16_FORMAT =
          
        

        
hu

      
        
GUINT32_FORMAT =
          
        

        
u

      
        
GUINT64_FORMAT =
          
        

        
lu

      
        
GUINTPTR_FORMAT =
          
        

        
lu

      
        
HAVE_GINT64 =
          
        

        
1

      
        
HAVE_GNUC_VARARGS =
          
        

        
1

      
        
HAVE_GNUC_VISIBILITY =
          
        

        
1

      
        
HAVE_GROWING_STACK =
          
        

        
0

      
        
HAVE_ISO_VARARGS =
          
        

        
1

      
        
HOOK_FLAG_USER_SHIFT =
          

  

    
The position of the first bit which is not reserved for internal
use be the #GHook implementation, i.e.
1 << G_HOOK_FLAG_USER_SHIFT is the first
bit which can be used for application-defined flags.



  





  



        

        
4

      
        
IEEE754_DOUBLE_BIAS =
          
        

        
1023

      
        
IEEE754_FLOAT_BIAS =
          
        

        
127

      
        
KEY_FILE_DESKTOP_GROUP =
          

  

    
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.



  





  



        

        
Desktop Entry

      
        
KEY_FILE_DESKTOP_KEY_ACTIONS =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list
giving the available application actions.



  





  



        

        
Actions

      
        
KEY_FILE_DESKTOP_KEY_CATEGORIES =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list
of strings giving the categories in which the desktop entry
should be shown in a menu.



  





  



        

        
Categories

      
        
KEY_FILE_DESKTOP_KEY_COMMENT =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
string giving the tooltip for the desktop entry.



  





  



        

        
Comment

      
        
KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
set to true if the application is D-Bus activatable.



  





  



        

        
DBusActivatable

      
        
KEY_FILE_DESKTOP_KEY_EXEC =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
giving the command line to execute. It is only valid for desktop
entries with the Application type.



  





  



        

        
Exec

      
        
KEY_FILE_DESKTOP_KEY_GENERIC_NAME =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
string giving the generic name of the desktop entry.



  





  



        

        
GenericName

      
        
KEY_FILE_DESKTOP_KEY_HIDDEN =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
stating whether the desktop entry has been deleted by the user.



  





  



        

        
Hidden

      
        
KEY_FILE_DESKTOP_KEY_ICON =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
string giving the name of the icon to be displayed for the desktop
entry.



  





  



        

        
Icon

      
        
KEY_FILE_DESKTOP_KEY_MIME_TYPE =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list
of strings giving the MIME types supported by this desktop entry.



  





  



        

        
MimeType

      
        
KEY_FILE_DESKTOP_KEY_NAME =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
string giving the specific name of the desktop entry.



  





  



        

        
Name

      
        
KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
strings identifying the environments that should not display the
desktop entry.



  





  



        

        
NotShowIn

      
        
KEY_FILE_DESKTOP_KEY_NO_DISPLAY =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
stating whether the desktop entry should be shown in menus.



  





  



        

        
NoDisplay

      
        
KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
strings identifying the environments that should display the
desktop entry.



  





  



        

        
OnlyShowIn

      
        
KEY_FILE_DESKTOP_KEY_PATH =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
containing the working directory to run the program in. It is only
valid for desktop entries with the Application type.



  





  



        

        
Path

      
        
KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
stating whether the application supports the
Startup Notification Protocol Specification.



  





  



        

        
StartupNotify

      
        
KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string
identifying the WM class or name hint of a window that the application
will create, which can be used to emulate Startup Notification with
older applications.



  





  



        

        
StartupWMClass

      
        
KEY_FILE_DESKTOP_KEY_TERMINAL =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
stating whether the program should be run in a terminal window.


It is only valid for desktop entries with the Application type.



  





  



        

        
Terminal

      
        
KEY_FILE_DESKTOP_KEY_TRY_EXEC =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
giving the file name of a binary on disk used to determine if the
program is actually installed. It is only valid for desktop entries
with the Application type.



  





  



        

        
TryExec

      
        
KEY_FILE_DESKTOP_KEY_TYPE =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
giving the type of the desktop entry.


Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
%G_KEY_FILE_DESKTOP_TYPE_LINK, or
%G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.



  





  



        

        
Type

      
        
KEY_FILE_DESKTOP_KEY_URL =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
giving the URL to access. It is only valid for desktop entries
with the Link type.



  





  



        

        
URL

      
        
KEY_FILE_DESKTOP_KEY_VERSION =
          

  

    
A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
giving the version of the Desktop Entry Specification used for
the desktop entry file.



  





  



        

        
Version

      
        
KEY_FILE_DESKTOP_TYPE_APPLICATION =
          

  

    
The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
entries representing applications.



  





  



        

        
Application

      
        
KEY_FILE_DESKTOP_TYPE_DIRECTORY =
          

  

    
The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
entries representing directories.



  





  



        

        
Directory

      
        
        
Link

      
        
LITTLE_ENDIAN =
          
        

        
1234

      
        
LN10 =
          
        

        
2.302585

      
        
LN2 =
          
        

        
0.693147

      
        
LOG_2_BASE_10 =
          
        

        
0.301030

      
        
LOG_DOMAIN =
          

  

    
Defines the log domain. See Log Domains.


Libraries should define this so that any messages
which they log can be differentiated from messages from other
libraries and application code. But be careful not to define
it in any public header files.


Log domains must be unique, and it is recommended that they are the
application or library name, optionally followed by a hyphen and a sub-domain
name. For example, bloatpad or bloatpad-io.


If undefined, it defaults to the default nil (or "") log domain; this is
not advisable, as it cannot be filtered against using the G_MESSAGES_DEBUG
environment variable.


For example, GTK uses this in its Makefile.am:
|[
AM_CPPFLAGS = -DG_LOG_DOMAIN="Gtk"
]|


Applications can choose to leave it as the default nil (or "")
domain. However, defining the domain offers the same advantages as
above.



  





  



        

        
0

      
        
LOG_FATAL_MASK =
          

  

    
GLib log levels that are considered fatal by default.


This is not used if structured logging is enabled; see
Using Structured Logging.



  





  



        

        
5

      
        
LOG_LEVEL_USER_SHIFT =
          

  

    
Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib.
Higher bits can be used for user-defined log levels.



  





  



        

        
8

      
        
MAJOR_VERSION =
          

  

    
The major version number of the GLib library.


Like #glib_major_version, but from the headers used at
application compile time, rather than from the library
linked against at application run time.



  





  



        

        
2

      
        
MAXINT16 =
          
        

        
32767

      
        
MAXINT32 =
          
        

        
2147483647

      
        
MAXINT64 =
          
        

        
9223372036854775807

      
        
MAXINT8 =
          
        

        
127

      
        
MAXUINT16 =
          
        

        
65535

      
        
MAXUINT32 =
          
        

        
4294967295

      
        
MAXUINT64 =
          
        

        
18446744073709551615

      
        
MAXUINT8 =
          
        

        
255

      
        
MICRO_VERSION =
          

  

    
The micro version number of the GLib library.


Like #gtk_micro_version, but from the headers used at
application compile time, rather than from the library
linked against at application run time.



  





  



        

        
0

      
        
MININT16 =
          

  

    
The minimum value which can be held in a #gint16.



  





  



        

        
-32768

      
        
MININT32 =
          

  

    
The minimum value which can be held in a #gint32.



  





  



        

        
-2147483648

      
        
MININT64 =
          

  

    
The minimum value which can be held in a #gint64.



  





  



        

        
-9223372036854775808

      
        
MININT8 =
          

  

    
The minimum value which can be held in a #gint8.



  





  



        

        
-128

      
        
MINOR_VERSION =
          

  

    
The minor version number of the GLib library.


Like #gtk_minor_version, but from the headers used at
application compile time, rather than from the library
linked against at application run time.



  





  



        

        
80

      
        
MODULE_SUFFIX =
          
        

        
so

      
        
OPTION_REMAINING =
          

  

    
If a long option in the main group has this name, it is not treated as a
regular option. Instead it collects all non-option arguments which would
otherwise be left in argv. The option must be of type
%G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
or %G_OPTION_ARG_FILENAME_ARRAY.


Using %G_OPTION_REMAINING instead of simply scanning argv
for leftover arguments has the advantage that GOption takes care of
necessary encoding conversions for strings or filenames.



  





  



        

        

      
        
PDP_ENDIAN =
          
        

        
3412

      
        
PI =
          
        

        
3.141593

      
        
PID_FORMAT =
          

  

    
A format specifier that can be used in printf()-style format strings
when printing a #GPid.



  





  



        

        
i

      
        
PI_2 =
          
        

        
1.570796

      
        
PI_4 =
          
        

        
0.785398

      
        
POLLFD_FORMAT =
          

  

    
A format specifier that can be used in printf()-style format strings
when printing the fd member of a GPoll::FD.



  





  



        

        
%d

      
        
PRIORITY_DEFAULT =
          

  

    
Use this for default priority event sources.


In GLib this priority is used when adding timeout functions
with g_timeout_add(). In GDK this priority is used for events
from the X server.



  





  



        

        
0

      
        
PRIORITY_DEFAULT_IDLE =
          

  

    
Use this for default priority idle functions.


In GLib this priority is used when adding idle functions with
g_idle_add().



  





  



        

        
200

      
        
PRIORITY_HIGH =
          

  

    
Use this for high priority event sources.


It is not used within GLib or GTK.



  





  



        

        
-100

      
        
PRIORITY_HIGH_IDLE =
          

  

    
Use this for high priority idle functions.


GTK uses %G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
and %G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
done to ensure that any pending resizes are processed before any
pending redraws, so that widgets are not redrawn twice unnecessarily.)



  





  



        

        
100

      
        
PRIORITY_LOW =
          

  

    
Use this for very low priority background tasks.


It is not used within GLib or GTK.



  





  



        

        
300

      
        
REF_COUNT_INIT =
          

  

    
Evaluates to the initial reference count for grefcount.


This macro is useful for initializing grefcount fields inside
structures, for instance:


typedef struct {
  grefcount ref_count;
  char *name;
  char *address;
} Person;

static const Person default_person = {
  .ref_count = G_REF_COUNT_INIT,
  .name = "Default name",
  .address = "Default address",
};




  





  



        

        
-1

      
        
SEARCHPATH_SEPARATOR =
          
        

        
58

      
        
SEARCHPATH_SEPARATOR_S =
          
        

        
:

      
        
SIZEOF_LONG =
          
        

        
8

      
        
SIZEOF_SIZE_T =
          
        

        
8

      
        
SIZEOF_SSIZE_T =
          
        

        
8

      
        
SIZEOF_VOID_P =
          
        

        
8

      
        
SOURCE_CONTINUE =
          

  

    
Use this macro as the return value of a GSource::Func to leave
the #GSource in the main loop.



  





  



        

        
true

      
        
SOURCE_REMOVE =
          

  

    
Use this macro as the return value of a GSource::Func to remove
the #GSource from the main loop.



  





  



        

        
false

      
        
SQRT2 =
          
        

        
1.414214

      
        
STR_DELIMITERS =
          

  

    
The standard delimiters, used in [funcGLib.strdelimit].



  





  



        

        
_-|> <.

      
        
SYSDEF_AF_INET =
          
        

        
2

      
        
SYSDEF_AF_INET6 =
          
        

        
10

      
        
SYSDEF_AF_UNIX =
          
        

        
1

      
        
SYSDEF_MSG_DONTROUTE =
          
        

        
4

      
        
SYSDEF_MSG_OOB =
          
        

        
1

      
        
SYSDEF_MSG_PEEK =
          
        

        
2

      
        
TEST_OPTION_ISOLATE_DIRS =
          

  

    
Creates a unique temporary directory for each unit test and uses
g_set_user_dirs() to set XDG directories to point into subdirectories of it
for the duration of the unit test. The directory tree is cleaned up after the
test finishes successfully. Note that this doesn’t take effect until
g_test_run() is called, so calls to (for example) g_get_user_home_dir() will
return the system-wide value when made in a test program’s main() function.


The following functions will return subdirectories of the temporary directory
when this option is used. The specific subdirectory paths in use are not
guaranteed to be stable API — always use a getter function to retrieve them.


    

  • g_get_home_dir()
    • 

  • g_get_user_cache_dir()
    • 

  • g_get_system_config_dirs()
    • 

  • g_get_user_config_dir()
    • 

  • g_get_system_data_dirs()
    • 

  • g_get_user_data_dir()
    • 

  • g_get_user_state_dir()
    • 

  • g_get_user_runtime_dir()
    • 



The subdirectories may not be created by the test harness; as with normal
calls to functions like g_get_user_cache_dir(), the caller must be prepared
to create the directory if it doesn’t exist.



  





  



        

        
isolate_dirs

      
        
TIME_SPAN_DAY =
          

  

    
Evaluates to a time span of one day.



  





  



        

        
86400000000

      
        
TIME_SPAN_HOUR =
          

  

    
Evaluates to a time span of one hour.



  





  



        

        
3600000000

      
        
TIME_SPAN_MILLISECOND =
          

  

    
Evaluates to a time span of one millisecond.



  





  



        

        
1000

      
        
TIME_SPAN_MINUTE =
          

  

    
Evaluates to a time span of one minute.



  





  



        

        
60000000

      
        
TIME_SPAN_SECOND =
          

  

    
Evaluates to a time span of one second.



  





  



        

        
1000000

      
        
UNICHAR_MAX_DECOMPOSITION_LENGTH =
          

  

    
The maximum length (in codepoints) of a compatibility or canonical
decomposition of a single Unicode character.


This is as defined by Unicode 6.1.



  





  



        

        
18

      
        
URI_RESERVED_CHARS_GENERIC_DELIMITERS =
          

  

    
Generic delimiters characters as defined in
RFC 3986. Includes :/?#[]@.



  





  



        

        
:/?#[]@

      
        
URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS =
          

  

    
Subcomponent delimiter characters as defined in
RFC 3986. Includes !$&'()*+,;=.



  





  



        

        
!$&'()*+,;=

      
        
USEC_PER_SEC =
          

  

    
Number of microseconds in one second (1 million).
This macro is provided for code readability.



  





  



        

        
1000000

      
        
VA_COPY_AS_ARRAY =
          
        

        
1

      
        
VERSION_MIN_REQUIRED =
          

  

    
A macro that should be defined by the user prior to including
the glib.h header.
The definition should be one of the predefined GLib version
macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,...


This macro defines the earliest version of GLib that the package is
required to be able to compile against.


If the compiler is configured to warn about the use of deprecated
functions, then using functions that were deprecated in version
%GLIB_VERSION_MIN_REQUIRED or earlier will cause warnings (but
using functions deprecated in later releases will not).



  





  



        

        
2

      
        
WIN32_MSG_HANDLE =
          
        

        
19981206

      
        
macro__has_attribute___noreturn__ =
          
        

        
0

      
    

  







  
    

      Instance Method Summary
      collapse
    


    
  


  

  

    
Instance Method Details


    
      

  

  
    #access(filename, mode)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (Integer)
      
      
      
        —
        
    as in access()
    

    
      
    
    • 
  




Returns:


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

    
      
    
    • 
  







    
      

  

  
    #aligned_alloc(n_blocks, n_block_bytes, alignment)  ⇒ GObject 
  

  

  


  

    
This function is similar to g_malloc(), allocating (n_blocks * n_block_bytes)
bytes, but care is taken to align the allocated memory to with the given
alignment value. Additionally, it will detect possible overflow during
multiplication.


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 g_aligned_free_sized() or g_aligned_free().



  





  
Parameters:


    
  
    
  • 
      
        n_blocks
      
      
        (Integer)
      
      
      
        —
        
    the number of blocks to allocate
    

    
      
    
    • 
  
    
  • 
      
        n_block_bytes
      
      
        (Integer)
      
      
      
        —
        
    the size of each block in bytes
    

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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #aligned_alloc0(n_blocks, n_block_bytes, alignment)  ⇒ GObject 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        n_blocks
      
      
        (Integer)
      
      
      
        —
        
    the number of blocks to allocate
    

    
      
    
    • 
  
    
  • 
      
        n_block_bytes
      
      
        (Integer)
      
      
      
        —
        
    the size of each block in bytes
    

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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the allocated, cleared memory
    

    
      
    
    • 
  







    
      

  

  
    #aligned_free(mem)  ⇒ nil 
  

  

  


  

    
Frees the memory allocated by g_aligned_alloc().



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    the memory to deallocate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #aligned_free_sized(mem, alignment, size)  ⇒ nil 
  

  

  


  

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


If mem is nil 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 g_aligned_free() instead.



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    the memory to free
    

    
      
    
    • 
  
    
  • 
      
        alignment
      
      
        (Integer)
      
      
      
        —
        
    alignment of mem
    

    
      
    
    • 
  
    
  • 
      
        size
      
      
        (Integer)
      
      
      
        —
        
    size of mem, in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #application_name  ⇒ String 
  

  

  


  

    
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 nil if g_set_prgname() has also not
been called).



  





  

Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    human-readable application
name. May return nil
    

    
      
    
    • 
  







    
      

  

  
    #application_name=(application_name)  ⇒ nil 
  

  

  


  

    
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.


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.



  





  
Parameters:


    
  
    
  • 
      
        application_name
      
      
        (String)
      
      
      
        —
        
    localized name of the application
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #array_new_take(data, len, clear, element_size)  ⇒ Array<GObject> 
  

  

  


  

    
Creates a new #GArray with data as array data, len as length and a
reference count of 1.


This avoids having to copy the data manually, when it can just be
inherited.
After this call, data belongs to the #GArray and may no longer be
modified by the caller. The memory of data has to be dynamically
allocated and will eventually be freed with g_free().


In case the elements need to be cleared when the array is freed, use
g_array_set_clear_func() to set a GDestroy::Notify function to perform
such task.


Do not use it if len or element_size are greater than %G_MAXUINT.
#GArray stores the length of its data in #guint, which may be shorter
than #gsize.



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (Array<GObject>)
      
      
      
        —
        
    an array of
elements of element_size, or nil for an empty array
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    the number of elements in data
    

    
      
    
    • 
  
    
  • 
      
        clear
      
      
        (Boolean)
      
      
      
        —
        
    true if #GArray elements should be automatically cleared
to 0 when they are allocated
    

    
      
    
    • 
  
    
  • 
      
        element_size
      
      
        (Integer)
      
      
      
        —
        
    the size of each element in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    A new #GArray
    

    
      
    
    • 
  







    
      

  

  
    #array_new_take_zero_terminated(data, clear, element_size)  ⇒ Array<GObject> 
  

  

  


  

    
Creates a new #GArray with data as array data, computing the length of it
and setting the reference count to 1.


This avoids having to copy the data manually, when it can just be
inherited.
After this call, data belongs to the #GArray and may no longer be
modified by the caller. The memory of data has to be dynamically
allocated and will eventually be freed with g_free().


The length is calculated by iterating through data until the first nil
element is found.


In case the elements need to be cleared when the array is freed, use
g_array_set_clear_func() to set a GDestroy::Notify function to perform
such task.


Do not use it if data length or element_size are greater than %G_MAXUINT.
#GArray stores the length of its data in #guint, which may be shorter
than #gsize.



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (Array<GObject>)
      
      
      
        —
        
    an array of elements of element_size
    

    
      
    
    • 
  
    
  • 
      
        clear
      
      
        (Boolean)
      
      
      
        —
        
    true if #GArray elements should be automatically cleared
to 0 when they are allocated
    

    
      
    
    • 
  
    
  • 
      
        element_size
      
      
        (Integer)
      
      
      
        —
        
    the size of each element in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    A new #GArray
    

    
      
    
    • 
  







    
      

  

  
    #ascii_digit_value(c)  ⇒ Integer 
  

  

  


  

    
Determines the numeric value of a character as a decimal digit. If the
character is not a decimal digit according to [funcGLib.ascii_isdigit],
-1 is returned.


Differs from [funcGLib.unichar_digit_value] because it takes a char, so
there's no worry about sign extension if characters are signed.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (GLib::gchar)
      
      
      
        —
        
    an ASCII character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the numerical value of c if it is a decimal digit, -1 otherwise
    

    
      
    
    • 
  







    
      

  

  
    #ascii_dtostr(buffer, buf_len, d)  ⇒ String 
  

  

  


  

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


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



  





  
Parameters:


    
  
    
  • 
      
        buffer
      
      
        (String)
      
      
      
        —
        
    a buffer to place the resulting string in
    

    
      
    
    • 
  
    
  • 
      
        buf_len
      
      
        (Integer)
      
      
      
        —
        
    the length of the buffer
    

    
      
    
    • 
  
    
  • 
      
        d
      
      
        (Float)
      
      
      
        —
        
    the value to convert
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the pointer to the buffer with the converted string
    

    
      
    
    • 
  







    
      

  

  
    #ascii_formatd(buffer, buf_len, format, d)  ⇒ String 
  

  

  


  

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


The format must just be a single format specifier
starting with %, expecting a gdouble argument.


The returned buffer is guaranteed to be nul-terminated.


If you just want to want to serialize the value into a
string, use [funcGLib.ascii_dtostr].



  





  
Parameters:


    
  
    
  • 
      
        buffer
      
      
        (String)
      
      
      
        —
        
    a buffer to place the resulting string in
    

    
      
    
    • 
  
    
  • 
      
        buf_len
      
      
        (Integer)
      
      
      
        —
        
    the length of the buffer
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the printf()-style format to use for the
code to use for converting
    

    
      
    
    • 
  
    
  • 
      
        d
      
      
        (Float)
      
      
      
        —
        
    the value to convert
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the pointer to the buffer with the converted string
    

    
      
    
    • 
  







    
      

  

  
    #ascii_strcasecmp(s1, s2)  ⇒ Integer 
  

  

  


  

    
Compare two strings, ignoring the case of ASCII characters.


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


This function should be used only on strings that are known to be
in encodings where the bytes corresponding to ASCII letters always
represent themselves. This includes UTF-8 and the ISO-8859-*
charsets, but not for instance double-byte encodings like the
Windows Codepage 932, where the trailing bytes of double-byte
characters include all ASCII letters. If you compare two CP932
strings using this function, you will get false matches.


Both s1 and s2 must be non-NULL.



  





  
Parameters:


    
  
    
  • 
      
        s1
      
      
        (String)
      
      
      
        —
        
    string to compare with s2
    

    
      
    
    • 
  
    
  • 
      
        s2
      
      
        (String)
      
      
      
        —
        
    string to compare with s1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the strings match, a negative value if s1 < s2,
or a positive value if s1 > s2
    

    
      
    
    • 
  







    
      

  

  
    #ascii_strdown(str, len)  ⇒ String 
  

  

  


  

    
Converts all upper case ASCII letters to lower case ASCII letters, with
semantics that exactly match [funcGLib.ascii_tolower].



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str in bytes, or -1 if str is nul-terminated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string, with all the upper case characters in
str converted to lower case. (Note that this is unlike the old
[funcGLib.strdown], which modified the string in place.)
    

    
      
    
    • 
  







    
      

  

  
    #ascii_string_to_signed(str, base, min, max, out_num)  ⇒ Boolean 
  

  

  


  

    
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
[errorGLib.NumberParserError.INVALID]. If the parsed number is out of
bounds - [errorGLib.NumberParserError.OUT_OF_BOUNDS].


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



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string to convert
    

    
      
    
    • 
  
    
  • 
      
        base
      
      
        (Integer)
      
      
      
        —
        
    base of a parsed number
    

    
      
    
    • 
  
    
  • 
      
        min
      
      
        (Integer)
      
      
      
        —
        
    a lower bound (inclusive)
    

    
      
    
    • 
  
    
  • 
      
        max
      
      
        (Integer)
      
      
      
        —
        
    an upper bound (inclusive)
    

    
      
    
    • 
  
    
  • 
      
        out_num
      
      
        (Integer)
      
      
      
        —
        
    a return location for a number
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if str was a number, false otherwise
    

    
      
    
    • 
  







    
      

  

  
    #ascii_string_to_unsigned(str, base, min, max, out_num)  ⇒ Boolean 
  

  

  


  

    
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
[errorGLib.NumberParserError.INVALID]. If the parsed number is out of
bounds - [errorGLib.NumberParserError.OUT_OF_BOUNDS].


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



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  
    
  • 
      
        base
      
      
        (Integer)
      
      
      
        —
        
    base of a parsed number
    

    
      
    
    • 
  
    
  • 
      
        min
      
      
        (Integer)
      
      
      
        —
        
    a lower bound (inclusive)
    

    
      
    
    • 
  
    
  • 
      
        max
      
      
        (Integer)
      
      
      
        —
        
    an upper bound (inclusive)
    

    
      
    
    • 
  
    
  • 
      
        out_num
      
      
        (Integer)
      
      
      
        —
        
    a return location for a number
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if str was a number, false otherwise
    

    
      
    
    • 
  







    
      

  

  
    #ascii_strncasecmp(s1, s2, n)  ⇒ Integer 
  

  

  


  

    
Compare s1 and s2, ignoring the case of ASCII characters and any
characters after the first n in each string. If either string is
less than n bytes long, comparison will stop at the first nul byte
encountered.


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


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



  





  
Parameters:


    
  
    
  • 
      
        s1
      
      
        (String)
      
      
      
        —
        
    string to compare with s2
    

    
      
    
    • 
  
    
  • 
      
        s2
      
      
        (String)
      
      
      
        —
        
    string to compare with s1
    

    
      
    
    • 
  
    
  • 
      
        n
      
      
        (Integer)
      
      
      
        —
        
    number of characters to compare
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the strings match, a negative value if s1 < s2,
or a positive value if s1 > s2
    

    
      
    
    • 
  







    
      

  

  
    #ascii_strtod(nptr, endptr)  ⇒ Float 
  

  

  


  

    
Converts a string to a floating point value.


This function behaves like the standard strtod() function
does in the C locale. It does this without actually changing
the current locale, since that would not be thread-safe.
A limitation of the implementation is that this function
will still accept localized versions of infinities and NANs.


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


To convert from a gdouble to a string in a locale-insensitive
way, use [funcGLib.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.



  





  
Parameters:


    
  
    
  • 
      
        nptr
      
      
        (String)
      
      
      
        —
        
    the string to convert to a numeric value
    

    
      
    
    • 
  
    
  • 
      
        endptr
      
      
        (String)
      
      
      
        —
        
    if non-NULL, it returns the
character after the last character used in the conversion
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Float)
      
      
      
        —
        
    the converted value
    

    
      
    
    • 
  







    
      

  

  
    #ascii_strtoll(nptr, endptr, base)  ⇒ Integer 
  

  

  


  

    
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, [constGLib.MAXINT64] or
[constGLib.MININT64] is returned, and ERANGE is stored in errno.
If the base is outside the valid range, zero is returned, and
EINVAL is stored in errno. If the
string conversion fails, zero is returned, and endptr returns nptr
(if endptr is non-NULL).



  





  
Parameters:


    
  
    
  • 
      
        nptr
      
      
        (String)
      
      
      
        —
        
    the string to convert to a numeric value
    

    
      
    
    • 
  
    
  • 
      
        endptr
      
      
        (String)
      
      
      
        —
        
    if non-NULL, it returns the
character after the last character used in the conversion
    

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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the converted value, or zero on error
    

    
      
    
    • 
  







    
      

  

  
    #ascii_strtoull(nptr, endptr, base)  ⇒ Integer 
  

  

  


  

    
Converts a string to a guint64 value.


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


Note that input with a leading minus sign (-) is accepted, and will return
the negation of the parsed number, unless that would overflow a guint64.
Critically, this means you cannot assume that a short fixed length input will
result in a low return value, as the input could have a leading -.


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


If the correct value would cause overflow, [constGLib.MAXUINT64]
is returned, and ERANGE is stored in errno.
If the base is outside the valid range, zero is returned, and
EINVAL is stored in errno.
If the string conversion fails, zero is returned, and endptr returns
nptr (if endptr is non-NULL).



  





  
Parameters:


    
  
    
  • 
      
        nptr
      
      
        (String)
      
      
      
        —
        
    the string to convert to a numeric value
    

    
      
    
    • 
  
    
  • 
      
        endptr
      
      
        (String)
      
      
      
        —
        
    if non-NULL, it returns the
character after the last character used in the conversion
    

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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the converted value, or zero on error
    

    
      
    
    • 
  







    
      

  

  
    #ascii_strup(str, len)  ⇒ String 
  

  

  


  

    
Converts all lower case ASCII letters to upper case ASCII letters, with
semantics that exactly match [funcGLib.ascii_toupper].



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str in bytes, or -1 if str is nul-terminated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string, with all the lower case characters
in str converted to upper case. (Note that this is unlike the old
[funcGLib.strup], which modified the string in place.)
    

    
      
    
    • 
  







    
      

  

  
    #ascii_tolower(c)  ⇒ GLib::gchar 
  

  

  


  

    
Convert a character to ASCII lower case. If the character is not an
ASCII upper case letter, it is returned unchanged.


Unlike the standard C library tolower() function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on EOF but no need to worry about casting to guchar
before passing a possibly non-ASCII character in.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (GLib::gchar)
      
      
      
        —
        
    any character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::gchar)
      
      
      
        —
        
    the result of the conversion
    

    
      
    
    • 
  







    
      

  

  
    #ascii_toupper(c)  ⇒ GLib::gchar 
  

  

  


  

    
Convert a character to ASCII upper case. If the character is not an
ASCII lower case letter, it is returned unchanged.


Unlike the standard C library toupper() function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on EOF but no need to worry about casting to guchar
before passing a possibly non-ASCII character in.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (GLib::gchar)
      
      
      
        —
        
    any character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::gchar)
      
      
      
        —
        
    the result of the conversion
    

    
      
    
    • 
  







    
      

  

  
    #ascii_xdigit_value(c)  ⇒ Integer 
  

  

  


  

    
Determines the numeric value of a character as a hexadecimal digit. If the
character is not a hex digit according to [funcGLib.ascii_isxdigit],
-1 is returned.


Differs from [funcGLib.unichar_xdigit_value] because it takes a char, so
there's no worry about sign extension if characters are signed.


Differs from [funcGLib.unichar_xdigit_value] because it takes a char, so
there's no worry about sign extension if characters are signed.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (GLib::gchar)
      
      
      
        —
        
    an ASCII character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the numerical value of c if it is a hex digit, -1 otherwise
    

    
      
    
    • 
  







    
      

  

  
    #assert_warning(log_domain, file, line, pretty_function, expression)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        pretty_function
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        expression
      
      
        (String)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #assertion_message(domain, file, line, func, message)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        message
      
      
        (String)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

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

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        expr
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        arg1
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        cmp
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        arg2
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        numtype
      
      
        (GLib::gchar)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #assertion_message_cmpnum(domain, file, line, func, expr, arg1, cmp, arg2, numtype)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        expr
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        arg1
      
      
        (GLib::long double)
      
      
      
    
    • 
  
    
  • 
      
        cmp
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        arg2
      
      
        (GLib::long double)
      
      
      
    
    • 
  
    
  • 
      
        numtype
      
      
        (GLib::gchar)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

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

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        expr
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        arg1
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        cmp
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        arg2
      
      
        (String)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

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

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        expr
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        arg1
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        arg2
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        first_wrong_idx
      
      
        (Integer)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

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

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        expr
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        error
      
      
        (GLib::Error)
      
      
      
    
    • 
  
    
  • 
      
        error_domain
      
      
        (GLib::Quark)
      
      
      
    
    • 
  
    
  • 
      
        error_code
      
      
        (Integer)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #assertion_message_expr(domain, file, line, func, expr)  ⇒ nil 
  

  

  


  

    
Internal function used to print messages from the public g_assert() and
g_assert_not_reached() macros.



  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
        —
        
    log domain
    

    
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
        —
        
    file containing the assertion
    

    
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
        —
        
    line number of the assertion
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
        —
        
    function containing the assertion
    

    
      
    
    • 
  
    
  • 
      
        expr
      
      
        (String)
      
      
      
        —
        
    expression which failed
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #atexit(func)  ⇒ nil 
  

  

  


  

    
Specifies a function to be called at normal program termination.


Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor
macro that maps to a call to the atexit() function in the C
library. This means that in case the code that calls g_atexit(),
i.e. atexit(), is in a DLL, the function will be called when the
DLL is detached from the program. This typically makes more sense
than that the function is called when the GLib DLL is detached,
which happened earlier when g_atexit() was a function in the GLib
DLL.


The behaviour of atexit() in the context of dynamically loaded
modules is not formally specified and varies wildly.


On POSIX systems, calling g_atexit() (or atexit()) in a dynamically
loaded module which is unloaded before the program terminates might
well cause a crash at program exit.


Some POSIX systems implement atexit() like Windows, and have each
dynamically loaded module maintain an own atexit chain that is
called when the module is unloaded.


On other POSIX systems, before a dynamically loaded module is
unloaded, the registered atexit functions (if any) residing in that
module are called, regardless where the code that registered them
resided. This is presumably the most robust approach.


As can be seen from the above, for portability it's best to avoid
calling g_atexit() (or atexit()) except in the main executable of a
program.



  





  
Parameters:


    
  
    
  • 
      
        func
      
      
        (GLib::VoidFunc)
      
      
      
        —
        
    the function to call on normal program termination.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #atomic_int_add(atomic, val)  ⇒ Integer 
  

  

  


  

    
Atomically adds val to the value of atomic.


Think of this operation as an atomic version of
{ tmp = *atomic; *atomic += val; return tmp; }.


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


Before version 2.30, this function did not return a value
(but g_atomic_int_exchange_and_add() did, and had the same meaning).


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



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to add
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the add, signed
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_and(atomic, val)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to 'and'
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the operation, unsigned
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_compare_and_exchange(atomic, oldval, newval)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  
    
  • 
      
        oldval
      
      
        (Integer)
      
      
      
        —
        
    the value to compare with
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (Integer)
      
      
      
        —
        
    the value to conditionally replace with
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the exchange took place
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_compare_and_exchange_full(atomic, oldval, newval, preval)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  
    
  • 
      
        oldval
      
      
        (Integer)
      
      
      
        —
        
    the value to compare with
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (Integer)
      
      
      
        —
        
    the value to conditionally replace with
    

    
      
    
    • 
  
    
  • 
      
        preval
      
      
        (Integer)
      
      
      
        —
        
    the contents of atomic before this operation
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the exchange took place
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_dec_and_test(atomic)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the resultant value is zero
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_exchange(atomic, newval)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (Integer)
      
      
      
        —
        
    the value to replace with
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the exchange, signed
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_exchange_and_add(atomic, val)  ⇒ Integer 
  

  

  


  

    
This function existed before g_atomic_int_add() returned the prior
value of the integer (which it now does).  It is retained only for
compatibility reasons.  Don't use this function in new code.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to add
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the add, signed
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_get(atomic)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of the integer
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_inc(atomic)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #atomic_int_or(atomic, val)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to 'or'
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the operation, unsigned
    

    
      
    
    • 
  







    
      

  

  
    #atomic_int_set(atomic, newval)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (Integer)
      
      
      
        —
        
    a new value to store
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #atomic_int_xor(atomic, val)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a #gint or #guint
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to 'xor'
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the operation, unsigned
    

    
      
    
    • 
  







    
      

  

  
    #atomic_pointer_add(atomic, val)  ⇒ Integer 
  

  

  


  

    
Atomically adds val to the value of atomic.


Think of this operation as an atomic version of
{ tmp = *atomic; *atomic += val; return tmp; }.


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


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


In GLib 2.80, the return type was changed from #gssize to #gintptr to add
support for platforms with 128-bit pointers. This should not affect existing
code.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (GLib::gssize)
      
      
      
        —
        
    the value to add
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the add, signed
    

    
      
    
    • 
  







    
      

  

  
    #atomic_pointer_and(atomic, val)  ⇒ Integer 
  

  

  


  

    
Performs an atomic bitwise 'and' of the value of atomic and val,
storing the result back in atomic.


Think of this operation as an atomic version of
{ tmp = *atomic; *atomic &= val; return tmp; }.


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


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


In GLib 2.80, the return type was changed from #gsize to #guintptr to add
support for platforms with 128-bit pointers. This should not affect existing
code.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to 'and'
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the operation, unsigned
    

    
      
    
    • 
  







    
      

  

  
    #atomic_pointer_compare_and_exchange(atomic, oldval, newval)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        oldval
      
      
        (GObject)
      
      
      
        —
        
    the value to compare with
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (GObject)
      
      
      
        —
        
    the value to conditionally replace with
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the exchange took place
    

    
      
    
    • 
  







    
      

  

  
    #atomic_pointer_compare_and_exchange_full(atomic, oldval, newval, preval)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        oldval
      
      
        (GObject)
      
      
      
        —
        
    the value to compare with
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (GObject)
      
      
      
        —
        
    the value to conditionally replace with
    

    
      
    
    • 
  
    
  • 
      
        preval
      
      
        (GObject)
      
      
      
        —
        
    the contents of atomic before this operation
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the exchange took place
    

    
      
    
    • 
  







    
      

  

  
    #atomic_pointer_exchange(atomic, newval)  ⇒ GObject 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (GObject)
      
      
      
        —
        
    the value to replace with
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the value of atomic before the exchange
    

    
      
    
    • 
  







    
      

  

  
    #atomic_pointer_get(atomic)  ⇒ GObject 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the value of the pointer
    

    
      
    
    • 
  







    
      

  

  
    #atomic_pointer_or(atomic, val)  ⇒ Integer 
  

  

  


  

    
Performs an atomic bitwise 'or' of the value of atomic and val,
storing the result back in atomic.


Think of this operation as an atomic version of
{ tmp = *atomic; *atomic |= val; return tmp; }.


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


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


In GLib 2.80, the return type was changed from #gsize to #guintptr to add
support for platforms with 128-bit pointers. This should not affect existing
code.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to 'or'
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the operation, unsigned
    

    
      
    
    • 
  







    
      

  

  
    #atomic_pointer_set(atomic, newval)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (GObject)
      
      
      
        —
        
    a new value to store
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #atomic_pointer_xor(atomic, val)  ⇒ Integer 
  

  

  


  

    
Performs an atomic bitwise 'xor' of the value of atomic and val,
storing the result back in atomic.


Think of this operation as an atomic version of
{ tmp = *atomic; *atomic ^= val; return tmp; }.


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


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


In GLib 2.80, the return type was changed from #gsize to #guintptr to add
support for platforms with 128-bit pointers. This should not affect existing
code.



  





  
Parameters:


    
  
    
  • 
      
        atomic
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to 'xor'
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the value of atomic before the operation, unsigned
    

    
      
    
    • 
  







    
      

  

  
    #atomic_rc_box_acquire(mem_block)  ⇒ GObject 
  

  

  


  

    
Atomically acquires a reference on the data pointed by mem_block.



  





  
Parameters:


    
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to reference counted data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the data,
with its reference count increased
    

    
      
    
    • 
  







    
      

  

  
    #atomic_rc_box_alloc(block_size)  ⇒ GObject 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the size of the allocation, must be greater than 0
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #atomic_rc_box_alloc0(block_size)  ⇒ GObject 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the size of the allocation, must be greater than 0
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #atomic_rc_box_dup(block_size, mem_block)  ⇒ GObject 
  

  

  


  

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



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    the memory to copy
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated
memory
    

    
      
    
    • 
  







    
      

  

  
    #atomic_rc_box_get_size(mem_block)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to reference counted data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the size of the data, in bytes
    

    
      
    
    • 
  







    
      

  

  
    #atomic_rc_box_release(mem_block)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to reference counted data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #atomic_rc_box_release_full(mem_block, clear_func)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to reference counted data
    

    
      
    
    • 
  
    
  • 
      
        clear_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    a function to call when clearing the data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #atomic_ref_count_compare(arc, val)  ⇒ Boolean 
  

  

  


  

    
Atomically compares the current value of arc with val.



  





  
Parameters:


    
  
    
  • 
      
        arc
      
      
        (Integer)
      
      
      
        —
        
    the address of an atomic reference count variable
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to compare
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the reference count is the same
as the given value
    

    
      
    
    • 
  







    
      

  

  
    #atomic_ref_count_dec(arc)  ⇒ Boolean 
  

  

  


  

    
Atomically decreases the reference count.


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



  





  
Parameters:


    
  
    
  • 
      
        arc
      
      
        (Integer)
      
      
      
        —
        
    the address of an atomic reference count variable
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the reference count reached 0, and false otherwise
    

    
      
    
    • 
  







    
      

  

  
    #atomic_ref_count_inc(arc)  ⇒ nil 
  

  

  


  

    
Atomically increases the reference count.



  





  
Parameters:


    
  
    
  • 
      
        arc
      
      
        (Integer)
      
      
      
        —
        
    the address of an atomic reference count variable
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #atomic_ref_count_init(arc)  ⇒ nil 
  

  

  


  

    
Initializes a reference count variable to 1.



  





  
Parameters:


    
  
    
  • 
      
        arc
      
      
        (Integer)
      
      
      
        —
        
    the address of an atomic reference count variable
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #base64_decode(text, out_len)  ⇒ Array<Integer> 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        text
      
      
        (String)
      
      
      
        —
        
    zero-terminated string with base64 text to decode
    

    
      
    
    • 
  
    
  • 
      
        out_len
      
      
        (Integer)
      
      
      
        —
        
    The length of the decoded data is written here
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    newly allocated buffer containing the binary data
that text represents. The returned buffer must
be freed with g_free().
    

    
      
    
    • 
  







    
      

  

  
    #base64_decode_inplace(text, out_len)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        text
      
      
        (Array<Integer>)
      
      
      
        —
        
    zero-terminated
string with base64 text to decode
    

    
      
    
    • 
  
    
  • 
      
        out_len
      
      
        (Integer)
      
      
      
        —
        
    The length of the decoded data is written here
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    The binary data that text responds. This pointer
is the same as the input text.
    

    
      
    
    • 
  







    
      

  

  
    #base64_decode_step(in, len, out, state, save)  ⇒ Integer 
  

  

  


  

    
Incrementally decode a sequence of binary data from 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.


The output buffer must be large enough to fit all the data that will
be written to it. Since base64 encodes 3 bytes in 4 chars you need
at least: (len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
state).



  





  
Parameters:


    
  
    
  • 
      
        in
      
      
        (Array<Integer>)
      
      
      
        —
        
    binary input data
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    max length of in data to decode
    

    
      
    
    • 
  
    
  • 
      
        out
      
      
        (Array<Integer>)
      
      
      
        —
        
    output buffer
    

    
      
    
    • 
  
    
  • 
      
        state
      
      
        (Integer)
      
      
      
        —
        
    Saved state between steps, initialize to 0
    

    
      
    
    • 
  
    
  • 
      
        save
      
      
        (Integer)
      
      
      
        —
        
    Saved state between steps, initialize to 0
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    The number of bytes of output that was written
    

    
      
    
    • 
  







    
      

  

  
    #base64_encode(data, len)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (Array<Integer>)
      
      
      
        —
        
    the binary data to encode
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    the length of data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated, zero-terminated Base-64
encoded string representing data. The returned string must
be freed with g_free().
    

    
      
    
    • 
  







    
      

  

  
    #base64_encode_close(break_lines, out, state, save)  ⇒ Integer 
  

  

  


  

    
Flush the status from a sequence of calls to g_base64_encode_step().


The output buffer must be large enough to fit all the data that will
be written to it. It will need up to 4 bytes, or up to 5 bytes if
line-breaking is enabled.


The out array will not be automatically nul-terminated.



  





  
Parameters:


    
  
    
  • 
      
        break_lines
      
      
        (Boolean)
      
      
      
        —
        
    whether to break long lines
    

    
      
    
    • 
  
    
  • 
      
        out
      
      
        (Array<Integer>)
      
      
      
        —
        
    pointer to destination buffer
    

    
      
    
    • 
  
    
  • 
      
        state
      
      
        (Integer)
      
      
      
        —
        
    Saved state from g_base64_encode_step()
    

    
      
    
    • 
  
    
  • 
      
        save
      
      
        (Integer)
      
      
      
        —
        
    Saved state from g_base64_encode_step()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    The number of bytes of output that was written
    

    
      
    
    • 
  







    
      

  

  
    #base64_encode_step(in, len, break_lines, out, state, save)  ⇒ Integer 
  

  

  


  

    
Incrementally encode a sequence of binary data into its Base-64 stringified
representation. By calling this function multiple times you can convert
data in chunks to avoid having to have the full encoded data in memory.


When all of the data has been converted you must call
g_base64_encode_close() to flush the saved state.


The output buffer must be large enough to fit all the data that will
be written to it. Due to the way base64 encodes you will need
at least: (len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
non-zero state). If you enable line-breaking you will need at least:
((len / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space.


break_lines is typically used when putting base64-encoded data in emails.
It breaks the lines at 76 columns instead of putting all of the text on
the same line. This avoids problems with long lines in the email system.
Note however that it breaks the lines with LF characters, not
CR LF sequences, so the result cannot be passed directly to SMTP
or certain other protocols.



  





  
Parameters:


    
  
    
  • 
      
        in
      
      
        (Array<Integer>)
      
      
      
        —
        
    the binary data to encode
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    the length of in
    

    
      
    
    • 
  
    
  • 
      
        break_lines
      
      
        (Boolean)
      
      
      
        —
        
    whether to break long lines
    

    
      
    
    • 
  
    
  • 
      
        out
      
      
        (Array<Integer>)
      
      
      
        —
        
    pointer to destination buffer
    

    
      
    
    • 
  
    
  • 
      
        state
      
      
        (Integer)
      
      
      
        —
        
    Saved state between steps, initialize to 0
    

    
      
    
    • 
  
    
  • 
      
        save
      
      
        (Integer)
      
      
      
        —
        
    Saved state between steps, initialize to 0
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    The number of bytes of output that was written
    

    
      
    
    • 
  







    
      

  

  
    #basename(file_name)  ⇒ GLib::filename 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        file_name
      
      
        (GLib::filename)
      
      
      
        —
        
    the name of the file
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the name of the file without any leading
directory components
    

    
      
    
    • 
  







    
      

  

  
    #bit_lock(address, lock_bit)  ⇒ nil 
  

  

  


  

    
Sets the indicated lock_bit in address.  If the bit is already
set, this call will block until g_bit_unlock() unsets the
corresponding bit.


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


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


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



  





  
Parameters:


    
  
    
  • 
      
        address
      
      
        (Integer)
      
      
      
        —
        
    a pointer to an integer
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    a bit value between 0 and 31
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #bit_nth_lsf(mask, nth_bit)  ⇒ Integer 
  

  

  


  

    
Find the position of the first bit set in mask, searching
from (but not including) nth_bit upwards. Bits are numbered
from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
usually). To start searching from the 0th bit, set nth_bit to -1.



  





  
Parameters:


    
  
    
  • 
      
        mask
      
      
        (GLib::gulong)
      
      
      
        —
        
    a #gulong containing flags
    

    
      
    
    • 
  
    
  • 
      
        nth_bit
      
      
        (Integer)
      
      
      
        —
        
    the index of the bit to start the search from
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the index of the first bit set which is higher than nth_bit, or -1
if no higher bits are set
    

    
      
    
    • 
  







    
      

  

  
    #bit_nth_msf(mask, nth_bit)  ⇒ Integer 
  

  

  


  

    
Find the position of the first bit set in mask, searching
from (but not including) nth_bit downwards. Bits are numbered
from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
usually). To start searching from the last bit, set nth_bit to
-1 or GLIB_SIZEOF_LONG * 8.



  





  
Parameters:


    
  
    
  • 
      
        mask
      
      
        (GLib::gulong)
      
      
      
        —
        
    a #gulong containing flags
    

    
      
    
    • 
  
    
  • 
      
        nth_bit
      
      
        (Integer)
      
      
      
        —
        
    the index of the bit to start the search from
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the index of the first bit set which is lower than nth_bit, or -1
if no lower bits are set
    

    
      
    
    • 
  







    
      

  

  
    #bit_storage(number)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        number
      
      
        (GLib::gulong)
      
      
      
        —
        
    a #guint
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bits used to hold number
    

    
      
    
    • 
  







    
      

  

  
    #bit_trylock(address, lock_bit)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        address
      
      
        (Integer)
      
      
      
        —
        
    a pointer to an integer
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    a bit value between 0 and 31
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the lock was acquired
    

    
      
    
    • 
  







    
      

  

  
    #bit_unlock(address, lock_bit)  ⇒ nil 
  

  

  


  

    
Clears the indicated lock_bit in address.  If another thread is
currently blocked in g_bit_lock() on this same bit then it will be
woken up.


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



  





  
Parameters:


    
  
    
  • 
      
        address
      
      
        (Integer)
      
      
      
        —
        
    a pointer to an integer
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    a bit value between 0 and 31
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #blow_chunks  ⇒ nil 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #bookmark_file_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #build_filename(first_element, array)  ⇒ GLib::filename 
  

  

  


  

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


On Unix, this function behaves identically to g_build_path (G_DIR_SEPARATOR_S, first_element, ....).


On Windows, it takes into account that either the backslash
(\ or slash (/) can be used as separator in filenames, but
otherwise behaves as on UNIX. When file pathname separators need
to be inserted, the one that last previously occurred in the
parameters (reading from left to right) is used.


No attempt is made to force the resulting filename to be an absolute
path. If the first element is a relative path, the result will
be a relative path.


If you are building a path programmatically you may want to use
GPath::Buf instead.



  





  
Parameters:


    
  
    
  • 
      
        first_element
      
      
        (GLib::filename)
      
      
      
        —
        
    the first element in the path
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    remaining elements in path, terminated by nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the newly allocated path
    

    
      
    
    • 
  







    
      

  

  
    #build_filename_valist(first_element, args)  ⇒ GLib::filename 
  

  

  


  

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


Behaves exactly like g_build_filename(), but takes the path elements
as a va_list.


This function is mainly meant for implementing other variadic arguments
functions.



  





  
Parameters:


    
  
    
  • 
      
        first_element
      
      
        (GLib::filename)
      
      
      
        —
        
    the first element in the path
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    va_list of remaining elements in path
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the newly allocated path
    

    
      
    
    • 
  







    
      

  

  
    #build_filenamev(args)  ⇒ GLib::filename 
  

  

  


  

    
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
GPath::Buf instead.



  





  
Parameters:


    
  
    
  • 
      
        args
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    nil-terminated
array of strings containing the path elements.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the newly allocated path
    

    
      
    
    • 
  







    
      

  

  
    #build_path(separator, first_element, array)  ⇒ GLib::filename 
  

  

  


  

    
Creates a path from a series of elements using separator as the
separator between elements.


At the boundary between two elements, any trailing occurrences of
separator in the first element, or leading occurrences of separator
in the second element are removed and exactly one copy of the
separator is inserted.


Empty elements are ignored.


The number of leading copies of the separator on the result is
the same as the number of leading copies of the separator on
the first non-empty element.


The number of trailing copies of the separator on the result is
the same as the number of trailing copies of the separator on
the last non-empty element. (Determination of the number of
trailing copies is done without stripping leading copies, so
if the separator is ABA, then ABABA has 1 trailing copy.)


However, if there is only a single non-empty element, and there
are no characters in that element not part of the leading or
trailing separators, then the result is exactly the original value
of that element.


Other than for determination of the number of leading and trailing
copies of the separator, elements consisting only of copies
of the separator are ignored.



  





  
Parameters:


    
  
    
  • 
      
        separator
      
      
        (GLib::filename)
      
      
      
        —
        
    a string used to separator the elements of the path.
    

    
      
    
    • 
  
    
  • 
      
        first_element
      
      
        (GLib::filename)
      
      
      
        —
        
    the first element in the path
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    remaining elements in path, terminated by nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the newly allocated path
    

    
      
    
    • 
  







    
      

  

  
    #build_pathv(separator, args)  ⇒ GLib::filename 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        separator
      
      
        (String)
      
      
      
        —
        
    a string used to separator the elements of the path.
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    nil-terminated
array of strings containing the path elements.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a newly-allocated string that
must be freed with g_free().
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_append(array, data, len)  ⇒ Array<Integer> 
  

  

  


  

    
Adds the given bytes to the end of the GByte::Array.
The array will grow in size automatically if necessary.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (Integer)
      
      
      
        —
        
    the byte data to be added
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to add
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    the GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_free(array, free_segment)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  
    
  • 
      
        free_segment
      
      
        (Boolean)
      
      
      
        —
        
    if true the actual byte data is freed as well
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the element data if free_segment is false, otherwise
nil.  The element data should be freed using g_free().
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_free_to_bytes(array)  ⇒ GLib::Bytes 
  

  

  


  

    
Transfers the data from the GByte::Array into a new immutable #GBytes.


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


This is identical to using g_bytes_new_take() and g_byte_array_free()
together.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Bytes)
      
      
      
        —
        
    a new immutable #GBytes representing same
byte data that was in the array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_new  ⇒ Array<Integer> 
  

  

  


  

    
Creates a new GByte::Array with a reference count of 1.



  





  

Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    the new GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_new_take(data, len)  ⇒ Array<Integer> 
  

  

  


  

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


Do not use it if len is greater than %G_MAXUINT. GByte::Array
stores the length of its data in #guint, which may be shorter than
#gsize.



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (Array<Integer>)
      
      
      
        —
        
    byte data for the array
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    length of data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    a new GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_prepend(array, data, len)  ⇒ Array<Integer> 
  

  

  


  

    
Adds the given data to the start of the GByte::Array.
The array will grow in size automatically if necessary.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (Integer)
      
      
      
        —
        
    the byte data to be added
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to add
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    the GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_ref(array)  ⇒ Array<Integer> 
  

  

  


  

    
Atomically increments the reference count of array by one.
This function is thread-safe and may be called from any thread.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    A GByte::Array
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    The passed in GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_remove_index(array, index_)  ⇒ Array<Integer> 
  

  

  


  

    
Removes the byte at the given index from a GByte::Array.
The following bytes are moved down one place.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  
    
  • 
      
        index_
      
      
        (Integer)
      
      
      
        —
        
    the index of the byte to remove
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    the GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_remove_index_fast(array, index_)  ⇒ Array<Integer> 
  

  

  


  

    
Removes the byte at the given index from a GByte::Array. The last
element in the array is used to fill in the space, so this function
does not preserve the order of the GByte::Array. But it is faster
than g_byte_array_remove_index().



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  
    
  • 
      
        index_
      
      
        (Integer)
      
      
      
        —
        
    the index of the byte to remove
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    the GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_remove_range(array, index_, length)  ⇒ Array<Integer> 
  

  

  


  

    
Removes the given number of bytes starting at the given index from a
GByte::Array.  The following elements are moved to close the gap.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByteArray
    

    
      
    
    • 
  
    
  • 
      
        index_
      
      
        (Integer)
      
      
      
        —
        
    the index of the first byte to remove
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to remove
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    the GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_set_size(array, length)  ⇒ Array<Integer> 
  

  

  


  

    
Sets the size of the GByte::Array, expanding it if necessary.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    the new size of the GByte::Array
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    the GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_sized_new(reserved_size)  ⇒ Array<Integer> 
  

  

  


  

    
Creates a new GByte::Array with reserved_size bytes preallocated.
This avoids frequent reallocation, if you are going to add many
bytes to the array. Note however that the size of the array is still
0.



  





  
Parameters:


    
  
    
  • 
      
        reserved_size
      
      
        (Integer)
      
      
      
        —
        
    number of bytes preallocated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    the new GByte::Array
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_sort(array, compare_func)  ⇒ nil 
  

  

  


  

    
Sorts a byte array, using compare_func which should be a
qsort()-style comparison function (returns less than zero for first
arg is less than second arg, zero for equal, greater than zero if
first arg is greater than second arg).


If two array elements compare equal, their order in the sorted array
is undefined. If you want equal elements to keep their order (i.e.
you want a stable sort) you can write a comparison function that,
if two elements would otherwise compare equal, compares them by
their addresses.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  
    
  • 
      
        compare_func
      
      
        (GLib::CompareFunc)
      
      
      
        —
        
    comparison function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #byte_array_sort_with_data(array, compare_func, user_data)  ⇒ nil 
  

  

  


  

    
Like g_byte_array_sort(), but the comparison function takes an extra
user data argument.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array
    

    
      
    
    • 
  
    
  • 
      
        compare_func
      
      
        (GLib::CompareDataFunc)
      
      
      
        —
        
    comparison function
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to compare_func
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #byte_array_steal(array, len)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    a GByte::Array.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    pointer to retrieve the number of
elements of the original array
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the element data, which should be
freed using g_free().
    

    
      
    
    • 
  







    
      

  

  
    #byte_array_unref(array)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        array
      
      
        (Array<Integer>)
      
      
      
        —
        
    A GByte::Array
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #canonicalize_filename(filename, relative_to)  ⇒ GLib::filename 
  

  

  


  

    
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 nil. If relative_to is nil, it'll fallback
to g_get_current_dir().


This function never fails, and will canonicalize file paths even if they don't
exist.


No file system I/O is done.
to use the current working directory



  





  
Parameters:


    
  
    
  • 
      
        filename
      
      
        (GLib::filename)
      
      
      
        —
        
    the name of the file
    

    
      
    
    • 
  
    
  • 
      
        relative_to
      
      
        (GLib::filename)
      
      
      
        —
        
    the relative directory, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a newly allocated string with the
canonical file path
    

    
      
    
    • 
  







    
      

  

  
    #chdir(path)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        path
      
      
        (GLib::filename)
      
      
      
        —
        
    a pathname in the GLib file name encoding
(UTF-8 on Windows)
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 on success, -1 if an error occurred.
    

    
      
    
    • 
  







    
      

  

  
    #check_version(required_major, required_minor, required_micro)  ⇒ String 
  

  

  


  

    
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
<b>required_major</b>.required_minor.<b>required_micro</b>. Second
the running library must be binary compatible with the
version <b>required_major</b>.<b>required_minor</b>.<b>required_micro</b>
(same major version.)



  





  
Parameters:


    
  
    
  • 
      
        required_major
      
      
        (Integer)
      
      
      
        —
        
    the required major version
    

    
      
    
    • 
  
    
  • 
      
        required_minor
      
      
        (Integer)
      
      
      
        —
        
    the required minor version
    

    
      
    
    • 
  
    
  • 
      
        required_micro
      
      
        (Integer)
      
      
      
        —
        
    the required micro version
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    nil 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.
    

    
      
    
    • 
  







    
      

  

  
    #checksum_type_get_length(checksum_type)  ⇒ GLib::gssize 
  

  

  


  

    
Gets the length in bytes of digests of type checksum_type
not supported.



  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (GLib::gssize)
      
      
      
        —
        
    the checksum length, or -1 if checksum_type is
    

    
      
    
    • 
  







    
      

  

  
    #child_watch_add(pid, function, data)  ⇒ Integer 
  

  

  


  

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


If you obtain pid from g_spawn_async() or g_spawn_async_with_pipes()
you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to
the spawn function for the child watching to work.


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


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


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



  





  
Parameters:


    
  
    
  • 
      
        pid
      
      
        (GLib::Pid)
      
      
      
        —
        
    process id 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
      
      
        (GLib::ChildWatchFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source.
    

    
      
    
    • 
  







    
      

  

  
    #child_watch_add_full(priority, pid, function, data, notify)  ⇒ Integer 
  

  

  


  

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


If you obtain pid from g_spawn_async() or g_spawn_async_with_pipes()
you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to
the spawn function for the child watching to work.


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


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


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


This internally creates a main loop source using
g_child_watch_source_new() and attaches it to the main loop context
using g_source_attach(). You can do these steps manually if you
need greater control.
Windows a handle for a process (which doesn't have to be a child).



  





  
Parameters:


    
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
        —
        
    the priority of the idle source. Typically this will be in the
range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
    

    
      
    
    • 
  
    
  • 
      
        pid
      
      
        (GLib::Pid)
      
      
      
        —
        
    process to watch. On POSIX the positive pid of a child process. On
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::ChildWatchFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  
    
  • 
      
        notify
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    function to call when the idle is removed, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source.
    

    
      
    
    • 
  







    
      

  

  
    #child_watch_source_new(pid)  ⇒ GLib::Source 
  

  

  


  

    
Creates a new child_watch source.


The source will not initially be associated with any GMain::Context
and must be added to one with g_source_attach() before it will be
executed.


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


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


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


    

  • pid must be a child of this 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 GMain::Context is acquired.
    • 

  • Before 2.78, even after destroying the #GSource, 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.
Windows a handle for a process (which doesn't have to be a child).



  





  
Parameters:


    
  
    
  • 
      
        pid
      
      
        (GLib::Pid)
      
      
      
        —
        
    process to watch. On POSIX the positive pid of a child process. On
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Source)
      
      
      
        —
        
    the newly-created child watch source
    

    
      
    
    • 
  







    
      

  

  
    #chmod(filename, mode)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX chmod() function. The chmod() function is
used to set the permissions of a file system object.


On Windows the file protection mechanism is not at all POSIX-like,
and the underlying chmod() function in the C library just sets or
clears the FAT-style READONLY attribute. It does not touch any
ACL. Software that needs to manage file permissions on Windows
exactly should use the Win32 API.


See your C library manual for more details about chmod().



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (Integer)
      
      
      
        —
        
    as in chmod()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the operation succeeded, -1 on error
    

    
      
    
    • 
  







    
      

  

  
    #clear_error  ⇒ nil 
  

  

  


  

    
If err or *err is nil, does nothing. Otherwise,
calls g_error_free() on *err and sets *err to nil.



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #clear_handle_id(tag_ptr, clear_func)  ⇒ nil 
  

  

  


  

    
Clears a numeric handler, such as a #GSource ID.


tag_ptr must be a valid pointer to the variable holding the handler.


If the ID is zero then this function does nothing.
Otherwise, clear_func() is called with the ID as a parameter, and the tag is
set to zero.


A macro is also included that allows this function to be used without
pointer casts.



  





  
Parameters:


    
  
    
  • 
      
        tag_ptr
      
      
        (Integer)
      
      
      
        —
        
    a pointer to the handler ID
    

    
      
    
    • 
  
    
  • 
      
        clear_func
      
      
        (GLib::ClearHandleFunc)
      
      
      
        —
        
    the function to call to clear the handler
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #clear_list(list_ptr, destroy)  ⇒ nil 
  

  

  


  

    
Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using destroy.


list_ptr must be a valid pointer. If list_ptr points to a null #GList, this does nothing.



  





  
Parameters:


    
  
    
  • 
      
        list_ptr
      
      
        (GLib::List<GObject>)
      
      
      
        —
        
    a #GList return location
    

    
      
    
    • 
  
    
  • 
      
        destroy
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    the function to pass to g_list_free_full() or nil to not free elements
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #clear_pointer(pp, destroy)  ⇒ nil 
  

  

  


  

    
Clears a reference to a variable.


pp must not be nil.


If the reference is nil then this function does nothing.
Otherwise, the variable is destroyed using destroy and the
pointer is set to nil.


A macro is also included that allows this function to be used without
pointer casts. This will mask any warnings about incompatible function types
or calling conventions, so you must ensure that your destroy function is
compatible with being called as GDestroyNotify using the standard calling
convention for the platform that GLib was compiled for; otherwise the program
will experience undefined behaviour.



  





  
Parameters:


    
  
    
  • 
      
        pp
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a
variable, struct member etc. holding a pointer
    

    
      
    
    • 
  
    
  • 
      
        destroy
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    a function to which a gpointer can be passed, to destroy *pp
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #clear_slist(slist_ptr, destroy)  ⇒ nil 
  

  

  


  

    
Clears a pointer to a #GSList, freeing it and, optionally, freeing its elements using destroy.


slist_ptr must be a valid pointer. If slist_ptr points to a null #GSList, this does nothing.



  





  
Parameters:


    
  
    
  • 
      
        slist_ptr
      
      
        (GLib::SList<GObject>)
      
      
      
        —
        
    a #GSList return location
    

    
      
    
    • 
  
    
  • 
      
        destroy
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    the function to pass to g_slist_free_full() or nil to not free elements
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #close(fd)  ⇒ Boolean 
  

  

  


  

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


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


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



  





  
Parameters:


    
  
    
  • 
      
        fd
      
      
        (Integer)
      
      
      
        —
        
    A file descriptor
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if there was an error.
    

    
      
    
    • 
  







    
      

  

  
    #closefrom(lowfd)  ⇒ Integer 
  

  

  


  

    
Close every file descriptor equal to or greater than lowfd.


Typically lowfd will be 3, to leave standard input, standard output
and standard error open.


This is the same as Linux close_range (lowfd, ~0U, 0),
but portable to other OSs and to older versions of Linux.
Equivalently, it is the same as BSD closefrom (lowfd), but portable,
and async-signal-safe on all OSs.


This function is async-signal safe, making it safe to call from a
signal handler or a [callbackGLib.SpawnChildSetupFunc], as long as lowfd is
non-negative.
See signal(7) and
signal-safety(7) for more details.



  





  
Parameters:


    
  
    
  • 
      
        lowfd
      
      
        (Integer)
      
      
      
        —
        
    Minimum fd to close, which must be non-negative
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 on success, -1 with errno set on error
    

    
      
    
    • 
  







    
      

  

  
    #codeset  ⇒ String 
  

  

  


  

    
Gets the character set for the current locale.



  





  

Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string containing the name
of the character set. This string must be freed with g_free().
    

    
      
    
    • 
  







    
      

  

  
    #compute_checksum_for_bytes(checksum_type, data)  ⇒ String 
  

  

  


  

    
Computes the checksum for a binary data. This is a
convenience wrapper for g_checksum_new(), g_checksum_get_string()
and g_checksum_free().


The hexadecimal string returned will be in lower case.



  





  
Parameters:


    
  
    
  • 
      
        checksum_type
      
      
        (GLib::ChecksumType)
      
      
      
        —
        
    a GChecksum::Type
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GLib::Bytes)
      
      
      
        —
        
    binary blob to compute the digest of
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the digest of the binary data as a
string in hexadecimal, or nil if g_checksum_new() fails for
checksum_type. The returned string should be freed with g_free() when
done using it.
    

    
      
    
    • 
  







    
      

  

  
    #compute_checksum_for_data(checksum_type, data, length)  ⇒ String 
  

  

  


  

    
Computes the checksum for a binary data of length. This is a
convenience wrapper for g_checksum_new(), g_checksum_get_string()
and g_checksum_free().


The hexadecimal string returned will be in lower case.



  





  
Parameters:


    
  
    
  • 
      
        checksum_type
      
      
        (GLib::ChecksumType)
      
      
      
        —
        
    a GChecksum::Type
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (Array<Integer>)
      
      
      
        —
        
    binary blob to compute the digest of
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    length of data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the digest of the binary data as a
string in hexadecimal, or nil if g_checksum_new() fails for
checksum_type. The returned string should be freed with g_free() when
done using it.
    

    
      
    
    • 
  







    
      

  

  
    #compute_checksum_for_string(checksum_type, str, length)  ⇒ String 
  

  

  


  

    
Computes the checksum of a string.


The hexadecimal string returned will be in lower case.



  





  
Parameters:


    
  
    
  • 
      
        checksum_type
      
      
        (GLib::ChecksumType)
      
      
      
        —
        
    a GChecksum::Type
    

    
      
    
    • 
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    the string to compute the checksum of
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length of the string, or -1 if the string is null-terminated.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the checksum as a hexadecimal string,
or nil if g_checksum_new() fails for checksum_type. The returned string
should be freed with g_free() when done using it.
    

    
      
    
    • 
  







    
      

  

  
    #compute_hmac_for_bytes(digest_type, key, data)  ⇒ String 
  

  

  


  

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


The hexadecimal string returned will be in lower case.



  





  
Parameters:


    
  
    
  • 
      
        digest_type
      
      
        (GLib::ChecksumType)
      
      
      
        —
        
    a GChecksum::Type to use for the HMAC
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (GLib::Bytes)
      
      
      
        —
        
    the key to use in the HMAC
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GLib::Bytes)
      
      
      
        —
        
    binary blob to compute the HMAC of
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the HMAC of the binary data as a string in hexadecimal.
The returned string should be freed with g_free() when done using it.
    

    
      
    
    • 
  







    
      

  

  
    #compute_hmac_for_data(digest_type, key, key_len, data, length)  ⇒ String 
  

  

  


  

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


The hexadecimal string returned will be in lower case.



  





  
Parameters:


    
  
    
  • 
      
        digest_type
      
      
        (GLib::ChecksumType)
      
      
      
        —
        
    a GChecksum::Type to use for the HMAC
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (Array<Integer>)
      
      
      
        —
        
    the key to use in the HMAC
    

    
      
    
    • 
  
    
  • 
      
        key_len
      
      
        (Integer)
      
      
      
        —
        
    the length of the key
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (Array<Integer>)
      
      
      
        —
        
    binary blob to compute the HMAC of
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    length of data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the HMAC of the binary data as a string in hexadecimal.
The returned string should be freed with g_free() when done using it.
    

    
      
    
    • 
  







    
      

  

  
    #compute_hmac_for_string(digest_type, key, key_len, str, length)  ⇒ String 
  

  

  


  

    
Computes the HMAC for a string.


The hexadecimal string returned will be in lower case.



  





  
Parameters:


    
  
    
  • 
      
        digest_type
      
      
        (GLib::ChecksumType)
      
      
      
        —
        
    a GChecksum::Type to use for the HMAC
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (Array<Integer>)
      
      
      
        —
        
    the key to use in the HMAC
    

    
      
    
    • 
  
    
  • 
      
        key_len
      
      
        (Integer)
      
      
      
        —
        
    the length of the key
    

    
      
    
    • 
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    the string to compute the HMAC for
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length of the string, or -1 if the string is nul-terminated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the HMAC as a hexadecimal string.
The returned string should be freed with g_free()
when done using it.
    

    
      
    
    • 
  







    
      

  

  
    #cond_new  ⇒ GLib::Cond 
  

  

  


  

    
Allocates and initializes a new #GCond.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Cond)
      
      
      
        —
        
    a newly allocated #GCond. Free with g_cond_free()
    

    
      
    
    • 
  







    
      

  

  
    #convert(str, len, to_codeset, from_codeset, bytes_read, bytes_written)  ⇒ Array<Integer> 
  

  

  


  

    
Converts a string from one character set to another.


Note that you should use g_iconv() for streaming conversions.
Despite the fact that bytes_read can return information about partial
characters, the g_convert_... functions are not generally suitable
for streaming. If the underlying converter maintains internal state,
then this won't be preserved across successive calls to g_convert(),
g_convert_with_iconv() or g_convert_with_fallback(). (An example of
this is the GNU C converter for CP1255 which does not emit a base
character until it knows that the next character is not a mark that
could combine with the base character.)


Using extensions such as "//TRANSLIT" may not work (or may not work
well) on many platforms.  Consider using g_str_to_ascii() instead.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<Integer>)
      
      
      
        —
        
    the string to convert.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length of the string in bytes, 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)
    

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

    
      
    
    • 
  
    
  • 
      
        from_codeset
      
      
        (String)
      
      
      
        —
        
    character set of str.
    

    
      
    
    • 
  
    
  • 
      
        bytes_read
      
      
        (Integer)
      
      
      
        —
        
    location to store the number of bytes in
the input string that were successfully converted, or nil.
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
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will be the byte offset after the last valid
input sequence.
    

    
      
    
    • 
  
    
  • 
      
        bytes_written
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes stored in
the output buffer (not including the terminating nul).
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    If the conversion was successful, a newly allocated buffer
containing the converted string, which must be freed with g_free().
Otherwise nil and error will be set.
    

    
      
    
    • 
  







    
      

  

  
    #convert_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #convert_with_fallback(str, len, to_codeset, from_codeset, fallback, bytes_read, bytes_written)  ⇒ Array<Integer> 
  

  

  


  

    
Converts a string from one character set to another, possibly
including fallback sequences for characters not representable
in the output. Note that it is not guaranteed that the specification
for the fallback sequences in fallback will be honored. Some
systems may do an approximate conversion from from_codeset
to to_codeset in their iconv() functions,
in which case GLib will simply return that approximate conversion.


Note that you should use g_iconv() for streaming conversions.
Despite the fact that bytes_read can return information about partial
characters, the g_convert_... functions are not generally suitable
for streaming. If the underlying converter maintains internal state,
then this won't be preserved across successive calls to g_convert(),
g_convert_with_iconv() or g_convert_with_fallback(). (An example of
this is the GNU C converter for CP1255 which does not emit a base
character until it knows that the next character is not a mark that
could combine with the base character.)



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<Integer>)
      
      
      
        —
        
    the string to convert.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length of the string in bytes, 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)
    

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

    
      
    
    • 
  
    
  • 
      
        from_codeset
      
      
        (String)
      
      
      
        —
        
    character set of str.
    

    
      
    
    • 
  
    
  • 
      
        fallback
      
      
        (String)
      
      
      
        —
        
    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 nil, characters not in the target encoding will
be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
    

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

    
      
    
    • 
  
    
  • 
      
        bytes_written
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes stored in
the output buffer (not including the terminating nul).
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    If the conversion was successful, a newly allocated buffer
containing the converted string, which must be freed with g_free().
Otherwise nil and error will be set.
    

    
      
    
    • 
  







    
      

  

  
    #convert_with_iconv(str, len, converter, bytes_read, bytes_written)  ⇒ Array<Integer> 
  

  

  


  

    
Converts a string from one character set to another.


Note that you should use g_iconv() for streaming conversions.
Despite the fact that bytes_read can return information about partial
characters, the g_convert_... functions are not generally suitable
for streaming. If the underlying converter maintains internal state,
then this won't be preserved across successive calls to g_convert(),
g_convert_with_iconv() or g_convert_with_fallback(). (An example of
this is the GNU C converter for CP1255 which does not emit a base
character until it knows that the next character is not a mark that
could combine with the base character.)


Characters which are valid in the input character set, but which have no
representation in the output character set will result in a
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv()
specification, which leaves this behaviour implementation defined. Note that
this is the same error code as is returned for an invalid byte sequence in
the input character set. To get defined behaviour for conversion of
unrepresentable characters, use g_convert_with_fallback().



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<Integer>)
      
      
      
        —
        
    the string to convert.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length of the string in bytes, 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)
    

    
      
    
    • 
  
    
  • 
      
        converter
      
      
        (GLib::IConv)
      
      
      
        —
        
    conversion descriptor from g_iconv_open()
    

    
      
    
    • 
  
    
  • 
      
        bytes_read
      
      
        (Integer)
      
      
      
        —
        
    location to store the number of bytes in
the input string that were successfully converted, or nil.
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
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will be the byte offset after the last valid
input sequence.
    

    
      
    
    • 
  
    
  • 
      
        bytes_written
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes stored in
the output buffer (not including the terminating nul).
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    If the conversion was successful, a newly allocated buffer
containing the converted string, which must be freed with
g_free(). Otherwise nil and error will be set.
    

    
      
    
    • 
  







    
      

  

  
    #creat(filename, mode)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX creat() function. The creat() function is
used to convert a pathname into a file descriptor, creating a file
if necessary.


On POSIX systems file descriptors are implemented by the operating
system. On Windows, it's the C library that implements creat() and
file descriptors. The actual Windows API for opening files is
different, see MSDN documentation for CreateFile(). The Win32 API
uses file handles, which are more randomish integers, not small
integers like file descriptors.


Because file descriptors are specific to the C library on Windows,
the file descriptor returned by this function makes sense only to
functions in the same C library. Thus if the GLib-using code uses a
different C library than GLib does, the file descriptor returned by
this function cannot be passed to C library functions like write()
or read().


See your C library manual for more details about creat().



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (Integer)
      
      
      
        —
        
    as in creat()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a new file descriptor, or -1 if an error occurred.
The return value can be used exactly like the return value
from creat().
    

    
      
    
    • 
  







    
      

  

  
    #current_dir  ⇒ GLib::filename 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the current directory
    

    
      
    
    • 
  







    
      

  

  
    #datalist_clear(datalist)  ⇒ nil 
  

  

  


  

    
Frees all the data elements of the datalist.
The data elements' destroy functions are called
if they have been set.



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    a datalist.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #datalist_foreach(datalist, func, user_data)  ⇒ nil 
  

  

  


  

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


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



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    a datalist.
    

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

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to the function.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #datalist_get_data(datalist, key)  ⇒ GObject 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    a datalist.
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (String)
      
      
      
        —
        
    the string identifying a data element.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the data element, or nil if it
is not found.
    

    
      
    
    • 
  







    
      

  

  
    #datalist_get_flags(datalist)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    pointer to the location that holds a list
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the flags of the datalist
    

    
      
    
    • 
  







    
      

  

  
    #datalist_id_dup_data(datalist, key_id, dup_func, user_data)  ⇒ GObject 
  

  

  


  

    
This is a variant of g_datalist_id_get_data() which
returns a 'duplicate' of the value. dup_func defines the
meaning of 'duplicate' in this context, it could e.g.
take a reference on a ref-counted object.


If the key_id is not set in the datalist then dup_func
will be called with a nil argument.


Note that dup_func is called while the datalist is locked, so it
is not allowed to read or modify the datalist.


This function can be useful to avoid races when multiple
threads are using the same datalist and the same key.



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    location of a datalist
    

    
      
    
    • 
  
    
  • 
      
        key_id
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark identifying a data element
    

    
      
    
    • 
  
    
  • 
      
        dup_func
      
      
        (GLib::DuplicateFunc)
      
      
      
        —
        
    function to
duplicate the old value
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    passed as user_data to dup_func
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the result of calling dup_func on the value
associated with key_id in datalist, or nil if not set.
If dup_func is nil, the value is returned unmodified.
    

    
      
    
    • 
  







    
      

  

  
    #datalist_id_get_data(datalist, key_id)  ⇒ GObject 
  

  

  


  

    
Retrieves the data element corresponding to key_id.



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    a datalist.
    

    
      
    
    • 
  
    
  • 
      
        key_id
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark identifying a data element.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the data element, or nil if
it is not found.
    

    
      
    
    • 
  







    
      

  

  
    #datalist_id_remove_multiple(datalist, keys, n_keys)  ⇒ nil 
  

  

  


  

    
Removes multiple keys from a datalist.


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


Before 2.80, n_keys had to be not larger than 16. Now it can be larger, but
note that GData does a linear search, so an excessive number of keys will
perform badly.



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    a datalist
    

    
      
    
    • 
  
    
  • 
      
        keys
      
      
        (Array<GLib::Quark>)
      
      
      
        —
        
    keys to remove
    

    
      
    
    • 
  
    
  • 
      
        n_keys
      
      
        (Integer)
      
      
      
        —
        
    length of keys.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #datalist_id_remove_no_notify(datalist, key_id)  ⇒ GObject 
  

  

  


  

    
Removes an element, without calling its destroy notification
function.



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    a datalist.
    

    
      
    
    • 
  
    
  • 
      
        key_id
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark identifying a data element.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the data previously stored at key_id,
or nil if none.
    

    
      
    
    • 
  







    
      

  

  
    #datalist_id_replace_data(datalist, key_id, oldval, newval, destroy, old_destroy)  ⇒ Boolean 
  

  

  


  

    
Compares the member that is associated with key_id in
datalist to oldval, and if they are the same, replace
oldval with newval.


This is like a typical atomic compare-and-exchange
operation, for a member of datalist.


If the previous value was replaced then ownership of the
old value (oldval) is passed to the caller, including
the registered destroy notify for it (passed out in old_destroy).
Its up to the caller to free this as they wish, which may
or may not include using old_destroy as sometimes replacement
should not destroy the object in the normal way.



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    location of a datalist
    

    
      
    
    • 
  
    
  • 
      
        key_id
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark identifying a data element
    

    
      
    
    • 
  
    
  • 
      
        oldval
      
      
        (GObject)
      
      
      
        —
        
    the old value to compare against
    

    
      
    
    • 
  
    
  • 
      
        newval
      
      
        (GObject)
      
      
      
        —
        
    the new value to replace it with
    

    
      
    
    • 
  
    
  • 
      
        destroy
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    destroy notify for the new value
    

    
      
    
    • 
  
    
  • 
      
        old_destroy
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    destroy notify for the existing value
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the existing value for key_id was replaced
by newval, false otherwise.
    

    
      
    
    • 
  







    
      

  

  
    #datalist_id_set_data_full(datalist, key_id, data, destroy_func)  ⇒ nil 
  

  

  


  

    
Sets the data corresponding to the given #GQuark id, and the
function to be called when the element is removed from the datalist.
Any previous data with the same key is removed, and its destroy
function is called.



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    a datalist.
    

    
      
    
    • 
  
    
  • 
      
        key_id
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark to identify the data element.
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    the data element or nil to remove any previous element
corresponding to key_id.
    

    
      
    
    • 
  
    
  • 
      
        destroy_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    the function to call when the data element is
removed. This function will be called with the data
element and can be used to free any memory allocated
for it. If data is nil, then destroy_func must
also be nil.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #datalist_init(datalist)  ⇒ nil 
  

  

  


  

    
Resets the datalist to nil. It does not free any memory or call
any destroy functions.



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    a pointer to a pointer to a datalist.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #datalist_set_flags(datalist, flags)  ⇒ nil 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    pointer to the location that holds a list
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (Integer)
      
      
      
        —
        
    the flags to turn on. The values of the flags are
restricted by %G_DATALIST_FLAGS_MASK (currently
3; giving two possible boolean flags).
A value for flags that doesn't fit within the mask is
an error.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #datalist_unset_flags(datalist, flags)  ⇒ nil 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        datalist
      
      
        (GLib::Data)
      
      
      
        —
        
    pointer to the location that holds a list
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (Integer)
      
      
      
        —
        
    the flags to turn off. The values of the flags are
restricted by %G_DATALIST_FLAGS_MASK (currently
3: giving two possible boolean flags).
A value for flags that doesn't fit within the mask is
an error.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #dataset_destroy(dataset_location)  ⇒ nil 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        dataset_location
      
      
        (GObject)
      
      
      
        —
        
    the location identifying the dataset.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #dataset_foreach(dataset_location, func, user_data)  ⇒ nil 
  

  

  


  

    
Calls the given function for each data element which is associated
with the given location. Note that this function is NOT thread-safe.
So unless dataset_location can be protected from any modifications
during invocation of this function, it should not be called.


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



  





  
Parameters:


    
  
    
  • 
      
        dataset_location
      
      
        (GObject)
      
      
      
        —
        
    the location identifying the dataset.
    

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

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to the function.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #dataset_id_get_data(dataset_location, key_id)  ⇒ GObject 
  

  

  


  

    
Gets the data element corresponding to a #GQuark.



  





  
Parameters:


    
  
    
  • 
      
        dataset_location
      
      
        (GObject)
      
      
      
        —
        
    the location identifying the dataset.
    

    
      
    
    • 
  
    
  • 
      
        key_id
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark id to identify the data element.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the data element corresponding to
the #GQuark, or nil if it is not found.
    

    
      
    
    • 
  







    
      

  

  
    #dataset_id_remove_no_notify(dataset_location, key_id)  ⇒ GObject 
  

  

  


  

    
Removes an element, without calling its destroy notification
function.



  





  
Parameters:


    
  
    
  • 
      
        dataset_location
      
      
        (GObject)
      
      
      
        —
        
    the location identifying the dataset.
    

    
      
    
    • 
  
    
  • 
      
        key_id
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark ID identifying the data element.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the data previously stored at key_id,
or nil if none.
    

    
      
    
    • 
  







    
      

  

  
    #dataset_id_set_data_full(dataset_location, key_id, data, destroy_func)  ⇒ nil 
  

  

  


  

    
Sets the data element associated with the given #GQuark id, and also
the function to call when the data element is destroyed. Any
previous data with the same key is removed, and its destroy function
is called.



  





  
Parameters:


    
  
    
  • 
      
        dataset_location
      
      
        (GObject)
      
      
      
        —
        
    the location identifying the dataset.
    

    
      
    
    • 
  
    
  • 
      
        key_id
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark id to identify the data element.
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    the data element.
    

    
      
    
    • 
  
    
  • 
      
        destroy_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    the function to call when the data element is
removed. This function will be called with the data
element and can be used to free any memory allocated
for it.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #date_get_days_in_month(month, year)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    number of days in month during the year
    

    
      
    
    • 
  







    
      

  

  
    #date_get_monday_weeks_in_year(year)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        year
      
      
        (GLib::DateYear)
      
      
      
        —
        
    a year
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    number of Mondays in the year
    

    
      
    
    • 
  







    
      

  

  
    #date_get_sunday_weeks_in_year(year)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        year
      
      
        (GLib::DateYear)
      
      
      
        —
        
    year to count weeks in
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of weeks in year
    

    
      
    
    • 
  







    
      

  

  
    #date_is_leap_year(year)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        year
      
      
        (GLib::DateYear)
      
      
      
        —
        
    year to check
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the year is a leap year
    

    
      
    
    • 
  







    
      

  

  
    #date_strftime(s, slen, format, date)  ⇒ Integer 
  

  

  


  

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


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



  





  
Parameters:


    
  
    
  • 
      
        s
      
      
        (String)
      
      
      
        —
        
    destination buffer
    

    
      
    
    • 
  
    
  • 
      
        slen
      
      
        (Integer)
      
      
      
        —
        
    buffer size
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    format string
    

    
      
    
    • 
  
    
  • 
      
        date
      
      
        (GLib::Date)
      
      
      
        —
        
    valid #GDate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    number of characters written to the buffer, or 0 the buffer was too small
    

    
      
    
    • 
  







    
      

  

  
    #date_valid_day(day)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        day
      
      
        (GLib::DateDay)
      
      
      
        —
        
    day to check
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the day is valid
    

    
      
    
    • 
  







    
      

  

  
    #date_valid_dmy(day, month, year)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        day
      
      
        (GLib::DateDay)
      
      
      
        —
        
    day
    

    
      
    
    • 
  
    
  • 
      
        month
      
      
        (GLib::DateMonth)
      
      
      
        —
        
    month
    

    
      
    
    • 
  
    
  • 
      
        year
      
      
        (GLib::DateYear)
      
      
      
        —
        
    year
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the date is a valid one
    

    
      
    
    • 
  







    
      

  

  
    #date_valid_julian(julian_date)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        julian_date
      
      
        (Integer)
      
      
      
        —
        
    Julian day to check
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the Julian day is valid
    

    
      
    
    • 
  







    
      

  

  
    #date_valid_month(month)  ⇒ Boolean 
  

  

  


  

    
Returns true if the month value is valid. The 12 GDate::Month
enumeration values are the only valid months.



  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the month is valid
    

    
      
    
    • 
  







    
      

  

  
    #date_valid_weekday(weekday)  ⇒ Boolean 
  

  

  


  

    
Returns true if the weekday is valid. The seven GDate::Weekday enumeration
values are the only valid weekdays.



  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the weekday is valid
    

    
      
    
    • 
  







    
      

  

  
    #date_valid_year(year)  ⇒ Boolean 
  

  

  


  

    
Returns true if the year is valid. Any year greater than 0 is valid,
though there is a 16-bit limit to what #GDate will understand.



  





  
Parameters:


    
  
    
  • 
      
        year
      
      
        (GLib::DateYear)
      
      
      
        —
        
    year
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the year is valid
    

    
      
    
    • 
  







    
      

  

  
    #dcgettext(domain, msgid, category)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
        —
        
    the translation domain to use, or nil to use
the domain set with textdomain()
    

    
      
    
    • 
  
    
  • 
      
        msgid
      
      
        (String)
      
      
      
        —
        
    message to translate
    

    
      
    
    • 
  
    
  • 
      
        category
      
      
        (Integer)
      
      
      
        —
        
    a locale category
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the translated string for the given locale category
    

    
      
    
    • 
  







    
      

  

  
    #dgettext(domain, msgid)  ⇒ String 
  

  

  


  

    
This function is a wrapper of dgettext() which does not translate
the message if the default domain as set with textdomain() has no
translations for the current locale.


The advantage of using this function over dgettext() proper is that
libraries using this function (like GTK) will not use translations
if the application using the library does not have translations for
the current locale.  This results in a consistent English-only
interface instead of one having partial translations.  For this
feature to work, the call to textdomain() and setlocale() should
precede any g_dgettext() invocations.  For GTK, it means calling
textdomain() before gtk_init or its variants.


This function disables translations if and only if upon its first
call all the following conditions hold:


    

  • 

    domain is not nil
    

    • 

  • 

    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.



  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
        —
        
    the translation domain to use, or nil to use
the domain set with textdomain()
    

    
      
    
    • 
  
    
  • 
      
        msgid
      
      
        (String)
      
      
      
        —
        
    message to translate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The translated string
    

    
      
    
    • 
  







    
      

  

  
    #dir_make_tmp(tmpl)  ⇒ GLib::filename 
  

  

  


  

    
Creates a subdirectory in the preferred directory for temporary
files (as returned by g_get_tmp_dir()).


tmpl should be a string in the GLib file name encoding containing
a sequence of six 'X' characters, as the parameter to g_mkstemp().
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
nil, 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.



  





  
Parameters:


    
  
    
  • 
      
        tmpl
      
      
        (GLib::filename)
      
      
      
        —
        
    Template for directory name,
as in g_mkdtemp(), basename only, or nil for a default template
    

    
      
    
    • 
  




Returns:


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

    
      
    
    • 
  







    
      

  

  
    #direct_equal(v1, v2)  ⇒ Boolean 
  

  

  


  

    
Compares two #gpointer arguments and returns true if they are equal.
It can be passed to g_hash_table_new() as the key_equal_func
parameter, when using opaque pointers compared by pointer value as
keys in a GHash::Table.


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



  





  
Parameters:


    
  
    
  • 
      
        v1
      
      
        (GObject)
      
      
      
        —
        
    a key
    

    
      
    
    • 
  
    
  • 
      
        v2
      
      
        (GObject)
      
      
      
        —
        
    a key to compare with v1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the two keys match.
    

    
      
    
    • 
  







    
      

  

  
    #direct_hash(v)  ⇒ Integer 
  

  

  


  

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


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



  





  
Parameters:


    
  
    
  • 
      
        v
      
      
        (GObject)
      
      
      
        —
        
    a #gpointer key
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a hash value corresponding to the key.
    

    
      
    
    • 
  







    
      

  

  
    #dngettext(domain, msgid, msgid_plural, n)  ⇒ String 
  

  

  


  

    
This function is a wrapper of dngettext() which does not translate
the message if the default domain as set with textdomain() has no
translations for the current locale.


See g_dgettext() for details of how this differs from dngettext()
proper.



  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
        —
        
    the translation domain to use, or nil to use
the domain set with textdomain()
    

    
      
    
    • 
  
    
  • 
      
        msgid
      
      
        (String)
      
      
      
        —
        
    message to translate
    

    
      
    
    • 
  
    
  • 
      
        msgid_plural
      
      
        (String)
      
      
      
        —
        
    plural form of the message
    

    
      
    
    • 
  
    
  • 
      
        n
      
      
        (GLib::gulong)
      
      
      
        —
        
    the quantity for which translation is needed
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The translated string
    

    
      
    
    • 
  







    
      

  

  
    #double_equal(v1, v2)  ⇒ Boolean 
  

  

  


  

    
Compares the two #gdouble values being pointed to and returns
true if they are equal.
It can be passed to g_hash_table_new() as the key_equal_func
parameter, when using non-nil pointers to doubles as keys in a
GHash::Table.



  





  
Parameters:


    
  
    
  • 
      
        v1
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gdouble key
    

    
      
    
    • 
  
    
  • 
      
        v2
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gdouble key to compare with v1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the two keys match.
    

    
      
    
    • 
  







    
      

  

  
    #double_hash(v)  ⇒ Integer 
  

  

  


  

    
Converts a pointer to a #gdouble to a hash value.
It can be passed to g_hash_table_new() as the hash_func parameter,
It can be passed to g_hash_table_new() as the hash_func parameter,
when using non-nil pointers to doubles as keys in a GHash::Table.



  





  
Parameters:


    
  
    
  • 
      
        v
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gdouble key
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a hash value corresponding to the key.
    

    
      
    
    • 
  







    
      

  

  
    #dpgettext(domain, msgctxtid, msgidoffset)  ⇒ String 
  

  

  


  

    
This function is a variant of g_dgettext() which supports
a disambiguating message context. GNU gettext uses the
'\004' character to separate the message context and
message id in msgctxtid.
If 0 is passed as msgidoffset, this function will fall back to
trying to use the deprecated convention of using "|" as a separation
character.


This uses g_dgettext() internally. See that functions for differences
with dgettext() proper.


Applications should normally not use this function directly,
but use the C_() macro for translations with context.



  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
        —
        
    the translation domain to use, or nil to use
the domain set with textdomain()
    

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

    
      
    
    • 
  
    
  • 
      
        msgidoffset
      
      
        (Integer)
      
      
      
        —
        
    the offset of the message id in msgctxid
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The translated string
    

    
      
    
    • 
  







    
      

  

  
    #dpgettext2(domain, context, msgid)  ⇒ String 
  

  

  


  

    
This function is a variant of g_dgettext() which supports
a disambiguating message context. GNU gettext uses the
'\004' character to separate the message context and
message id in msgctxtid.


This uses g_dgettext() internally. See that functions for differences
with dgettext() proper.


This function differs from C_() in that it is not a macro and
thus you may use non-string-literals as context and msgid arguments.



  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
        —
        
    the translation domain to use, or nil to use
the domain set with textdomain()
    

    
      
    
    • 
  
    
  • 
      
        context
      
      
        (String)
      
      
      
        —
        
    the message context
    

    
      
    
    • 
  
    
  • 
      
        msgid
      
      
        (String)
      
      
      
        —
        
    the message
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The translated string
    

    
      
    
    • 
  







    
      

  

  
    #environ  ⇒ Array<GLib::filename> 
  

  

  


  

    
Gets the list of environment variables for the current process.


The list is nil terminated and each item in the list is of the
form 'NAME=VALUE'.


This is equivalent to direct access to the 'environ' global variable,
except portable.


The return value is freshly allocated and it should be freed with
g_strfreev() when it is no longer needed.



  





  

Returns:


    
  
    
  • 
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    the list of environment variables
    

    
      
    
    • 
  







    
      

  

  
    #environ_getenv(envp, variable)  ⇒ GLib::filename 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        envp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    an environment list (eg, as returned from g_get_environ()), or nil
for an empty environment list
    

    
      
    
    • 
  
    
  • 
      
        variable
      
      
        (GLib::filename)
      
      
      
        —
        
    the environment variable to get
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the value of the environment variable, or nil 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.
    

    
      
    
    • 
  







    
      

  

  
    #environ_setenv(envp, variable, value, overwrite)  ⇒ Array<GLib::filename> 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        envp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    an environment list that can be freed using g_strfreev() (e.g., as
returned from g_get_environ()), or nil for an empty
environment list
    

    
      
    
    • 
  
    
  • 
      
        variable
      
      
        (GLib::filename)
      
      
      
        —
        
    the environment variable to set, must not
contain '='
    

    
      
    
    • 
  
    
  • 
      
        value
      
      
        (GLib::filename)
      
      
      
        —
        
    the value for to set the variable to
    

    
      
    
    • 
  
    
  • 
      
        overwrite
      
      
        (Boolean)
      
      
      
        —
        
    whether to change the variable if it already exists
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    the updated environment list. Free it using g_strfreev().
    

    
      
    
    • 
  







    
      

  

  
    #environ_unsetenv(envp, variable)  ⇒ Array<GLib::filename> 
  

  

  


  

    
Removes the environment variable variable from the provided
environment envp.



  





  
Parameters:


    
  
    
  • 
      
        envp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    an environment list that can be freed using g_strfreev() (e.g., as
returned from g_get_environ()), or nil for an empty environment list
    

    
      
    
    • 
  
    
  • 
      
        variable
      
      
        (GLib::filename)
      
      
      
        —
        
    the environment variable to remove, must not
contain '='
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    the updated environment list. Free it using g_strfreev().
    

    
      
    
    • 
  







    
      

  

  
    #error_domain_register(error_type_name, error_type_private_size, error_type_init, error_type_copy, error_type_clear)  ⇒ GLib::Quark 
  

  

  


  

    
This function registers an extended #GError domain.
error_type_name will be duplicated. Otherwise does the same as
g_error_domain_register_static().



  





  
Parameters:


    
  
    
  • 
      
        error_type_name
      
      
        (String)
      
      
      
        —
        
    string to create a #GQuark from
    

    
      
    
    • 
  
    
  • 
      
        error_type_private_size
      
      
        (Integer)
      
      
      
        —
        
    size of the private error data in bytes
    

    
      
    
    • 
  
    
  • 
      
        error_type_init
      
      
        (GLib::ErrorInitFunc)
      
      
      
        —
        
    function initializing fields of the private error data
    

    
      
    
    • 
  
    
  • 
      
        error_type_copy
      
      
        (GLib::ErrorCopyFunc)
      
      
      
        —
        
    function copying fields of the private error data
    

    
      
    
    • 
  
    
  • 
      
        error_type_clear
      
      
        (GLib::ErrorClearFunc)
      
      
      
        —
        
    function freeing fields of the private error data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
        —
        
    #GQuark representing the error domain
    

    
      
    
    • 
  







    
      

  

  
    #error_domain_register_static(error_type_name, error_type_private_size, error_type_init, error_type_copy, error_type_clear)  ⇒ GLib::Quark 
  

  

  


  

    
This function registers an extended #GError domain.


error_type_name should not be freed. error_type_private_size must
be greater than 0.


error_type_init receives an initialized #GError and should then initialize
the private data.


error_type_copy is a function that receives both original and a copy
#GError and should copy the fields of the private error data. The standard
#GError fields are already handled.


error_type_clear receives the pointer to the error, and it should free the
fields of the private error data. It should not free the struct itself though.


Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
already takes care of passing valid information to this function.



  





  
Parameters:


    
  
    
  • 
      
        error_type_name
      
      
        (String)
      
      
      
        —
        
    static string to create a #GQuark from
    

    
      
    
    • 
  
    
  • 
      
        error_type_private_size
      
      
        (Integer)
      
      
      
        —
        
    size of the private error data in bytes
    

    
      
    
    • 
  
    
  • 
      
        error_type_init
      
      
        (GLib::ErrorInitFunc)
      
      
      
        —
        
    function initializing fields of the private error data
    

    
      
    
    • 
  
    
  • 
      
        error_type_copy
      
      
        (GLib::ErrorCopyFunc)
      
      
      
        —
        
    function copying fields of the private error data
    

    
      
    
    • 
  
    
  • 
      
        error_type_clear
      
      
        (GLib::ErrorClearFunc)
      
      
      
        —
        
    function freeing fields of the private error data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
        —
        
    #GQuark representing the error domain
    

    
      
    
    • 
  







    
      

  

  
    #fdwalk_set_cloexec(lowfd)  ⇒ Integer 
  

  

  


  

    
Mark every file descriptor equal to or greater than lowfd to be closed
at the next execve() or similar, as if via the FD_CLOEXEC flag.


Typically lowfd will be 3, to leave standard input, standard output
and standard error open after exec.


This is the same as Linux close_range (lowfd, ~0U, CLOSE_RANGE_CLOEXEC),
but portable to other OSs and to older versions of Linux.


This function is async-signal safe, making it safe to call from a
signal handler or a [callbackGLib.SpawnChildSetupFunc], as long as lowfd is
non-negative.
See signal(7) and
signal-safety(7) for more details.



  





  
Parameters:


    
  
    
  • 
      
        lowfd
      
      
        (Integer)
      
      
      
        —
        
    Minimum fd to act on, which must be non-negative
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 on success, -1 with errno set on error
    

    
      
    
    • 
  







    
      

  

  
    #file_error_from_errno(err_no)  ⇒ GLib::FileError 
  

  

  


  

    
Gets a GFile::Error constant based on the passed-in err_no.


For example, if you pass in EEXIST this function returns
%G_FILE_ERROR_EXIST. Unlike errno values, you can portably
assume that all GFile::Error values will exist.


Normally a GFile::Error value goes into a #GError returned
from a function that manipulates files. So you would use
g_file_error_from_errno() when constructing a #GError.



  





  
Parameters:


    
  
    
  • 
      
        err_no
      
      
        (Integer)
      
      
      
        —
        
    an "errno" value
    

    
      
    
    • 
  




Returns:







    
      

  

  
    #file_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #file_get_contents(filename, contents, length)  ⇒ Boolean 
  

  

  


  

    
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
nil 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 GFile::Error enumeration. In the error case,
contents is set to nil and length is set to zero.



  





  
Parameters:


    
  
    
  • 
      
        filename
      
      
        (GLib::filename)
      
      
      
        —
        
    name of a file to read contents from, in the GLib file name encoding
    

    
      
    
    • 
  
    
  • 
      
        contents
      
      
        (Array<Integer>)
      
      
      
        —
        
    location to store an allocated string, use g_free() to free
the returned string
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    location to store length in bytes of the contents, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if an error occurred
    

    
      
    
    • 
  







    
      

  

  
    #file_open_tmp(tmpl, name_used)  ⇒ Integer 
  

  

  


  

    
Opens a file for writing in the preferred directory for temporary
files (as returned by g_get_tmp_dir()).


tmpl should be a string in the GLib file name encoding containing
a sequence of six 'X' characters, as the parameter to g_mkstemp().
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
nil, 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-nil, the actual name used
is returned in name_used. This string should be freed with g_free()
when not needed any longer. The returned name is in the GLib file
name encoding.



  





  
Parameters:


    
  
    
  • 
      
        tmpl
      
      
        (GLib::filename)
      
      
      
        —
        
    Template for file name, as in
g_mkstemp(), basename only, or nil for a default template
    

    
      
    
    • 
  
    
  • 
      
        name_used
      
      
        (GLib::filename)
      
      
      
        —
        
    location to store actual name used,
or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    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.
    

    
      
    
    • 
  







    
      

  

  
    #file_read_link(filename)  ⇒ GLib::filename 
  

  

  


  

    
Reads the contents of the symbolic link filename like the POSIX
readlink() function.


The returned string is in the encoding used for filenames. Use
g_filename_to_utf8() to convert it to UTF-8.


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




  





  
Parameters:


    
  
    
  • 
      
        filename
      
      
        (GLib::filename)
      
      
      
        —
        
    the symbolic link
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    A newly-allocated string with
the contents of the symbolic link, or nil if an error occurred.
    

    
      
    
    • 
  







    
      

  

  
    #file_set_contents(filename, contents, length)  ⇒ Boolean 
  

  

  


  

    
Writes all of contents to a file named filename. This is a convenience
wrapper around calling g_file_set_contents_full() with flags set to
G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING and
mode set to 0666.



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        contents
      
      
        (Array<Integer>)
      
      
      
        —
        
    string to write to the file
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of contents, or -1 if contents is a nul-terminated string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if an error occurred
    

    
      
    
    • 
  







    
      

  

  
    #file_set_contents_full(filename, contents, length, flags, mode)  ⇒ Boolean 
  

  

  


  

    
Writes all of contents to a file named filename, with good error checking.
If a file called filename already exists it will be overwritten.


flags control the properties of the write operation: whether it’s atomic,
and what the tradeoff is between returning quickly or being resilient to
system crashes.


As this function performs file I/O, it is recommended to not call it anywhere
where blocking would cause problems, such as in the main loop of a graphical
application. In particular, if flags has any value other than
%G_FILE_SET_CONTENTS_NONE then this function may call fsync().


If %G_FILE_SET_CONTENTS_CONSISTENT is set in flags, the operation is atomic
in the sense that it is first written to a temporary file which is then
renamed to the final name.


Notes:


    

  • 

    On UNIX, if filename already exists hard links to filename will break.
Also since the file is recreated, existing permissions, access control
lists, metadata etc. may be lost. If filename is a symbolic link,
the link itself will be replaced, not the linked file.
    

    • 

  • 

    On UNIX, if filename already exists and is non-empty, and if the system
supports it (via a journalling filesystem or equivalent), and if
%G_FILE_SET_CONTENTS_CONSISTENT is set in flags, the fsync() call (or
equivalent) will be used to ensure atomic replacement: filename
will contain either its old contents or contents, even in the face of
system power loss, the disk being unsafely removed, etc.
    

    • 

  • 

    On UNIX, if filename does not already exist or is empty, there is a
possibility that system power loss etc. after calling this function will
leave filename empty or full of NUL bytes, depending on the underlying
filesystem, unless %G_FILE_SET_CONTENTS_DURABLE and
%G_FILE_SET_CONTENTS_CONSISTENT are set in flags.
    

    • 

  • 

    On Windows renaming a file will not remove an existing file with the
new name, so on Windows there is a race condition between the existing
file being removed and the temporary file being renamed.
    

    • 

  • 

    On Windows there is no way to remove a file that is open to some
process, or mapped into memory. Thus, this function will fail if
filename already exists and is open.
    

    • 



If the call was successful, it returns true. If the call was not successful,
it returns false and sets error. The error domain is %G_FILE_ERROR.
Possible error codes are those in the GFile::Error 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.



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        contents
      
      
        (Array<Integer>)
      
      
      
        —
        
    string to write to the file
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of contents, or -1 if contents is a nul-terminated string
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::FileSetContentsFlags)
      
      
      
        —
        
    flags controlling the safety vs speed of the operation
    

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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if an error occurred
    

    
      
    
    • 
  







    
      

  

  
    #file_test(filename, test)  ⇒ Boolean 
  

  

  


  

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


Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
so for a symbolic link to a regular file g_file_test() will return
true for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR.


Note, that for a dangling symbolic link g_file_test() will return
true for %G_FILE_TEST_IS_SYMLINK and false for all other flags.


You should never use g_file_test() to test whether it is safe
to perform an operation, because there is always the possibility
of the condition changing before you actually perform the operation,
see TOCTOU.


For example, you might think you could use %G_FILE_TEST_IS_SYMLINK
to know whether it is safe to write to a file without being
tricked into writing into a different location. It doesn't work!


 // DON'T DO THIS
 if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
   {
     fd = g_open (filename, O_WRONLY);
     // write to fd
   }

 // 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 %G_FILE_TEST_EXISTS and
%G_FILE_TEST_IS_EXECUTABLE are implemented using the access()
system call. This usually doesn't matter, but if your program
is setuid or setgid it means that these tests will give you
the answer for the real user ID and group ID, rather than the
effective user ID and group ID.


On Windows, there are no symlinks, so testing for
%G_FILE_TEST_IS_SYMLINK will always return false. Testing for
%G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
its name indicates that it is executable, checking for well-known
extensions and those listed in the PATHEXT environment variable.



  





  
Parameters:


    
  
    
  • 
      
        filename
      
      
        (GLib::filename)
      
      
      
        —
        
    a filename to test in the
GLib file name encoding
    

    
      
    
    • 
  
    
  • 
      
        test
      
      
        (GLib::FileTest)
      
      
      
        —
        
    bitfield of GFile::Test flags
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    whether a test was true
    

    
      
    
    • 
  







    
      

  

  
    #filename_display_basename(filename)  ⇒ String 
  

  

  


  

    
Returns the display basename for the particular filename, guaranteed
to be valid UTF-8. The display name might not be identical to the filename,
for instance there might be problems converting it to UTF-8, and some files
can be translated in the display.


If GLib cannot make sense of the encoding of filename, as a last resort it
replaces unknown characters with U+FFFD, the Unicode replacement character.
You can search the result for the UTF-8 encoding of this character (which is
"\357\277\275" in octal notation) to find out if filename was in an invalid
encoding.


You must pass the whole absolute pathname to this functions so that
translation of well known locations can be done.


This function is preferred over g_filename_display_name() if you know the
whole path, as it allows translation.



  





  
Parameters:


    
  
    
  • 
      
        filename
      
      
        (GLib::filename)
      
      
      
        —
        
    an absolute pathname in the
GLib file name encoding
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string containing
a rendition of the basename of the filename in valid UTF-8
    

    
      
    
    • 
  







    
      

  

  
    #filename_display_name(filename)  ⇒ String 
  

  

  


  

    
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-nil
even if the filename actually isn't in the GLib file name encoding.


If GLib cannot make sense of the encoding of filename, as a last resort it
replaces unknown characters with U+FFFD, the Unicode replacement character.
You can search the result for the UTF-8 encoding of this character (which is
"\357\277\275" in octal notation) to find out if filename was in an invalid
encoding.


If you know the whole pathname of the file you should use
g_filename_display_basename(), since that allows location-based
translation of filenames.



  





  
Parameters:


    
  
    
  • 
      
        filename
      
      
        (GLib::filename)
      
      
      
        —
        
    a pathname hopefully in the
GLib file name encoding
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string containing
a rendition of the filename in valid UTF-8
    

    
      
    
    • 
  







    
      

  

  
    #filename_from_uri(uri, hostname)  ⇒ GLib::filename 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        uri
      
      
        (String)
      
      
      
        —
        
    a uri describing a filename (escaped, encoded in ASCII).
    

    
      
    
    • 
  
    
  • 
      
        hostname
      
      
        (String)
      
      
      
        —
        
    Location to store hostname for the URI.
If there is no hostname in the URI, nil will be
stored in this location.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a newly-allocated string holding
the resulting filename, or nil on an error.
    

    
      
    
    • 
  







    
      

  

  
    #filename_from_utf8(utf8string, len, bytes_read, bytes_written)  ⇒ GLib::filename 
  

  

  


  

    
Converts a string from UTF-8 to the encoding GLib uses for
filenames. Note that on Windows GLib uses UTF-8 for filenames;
on other platforms, this function indirectly depends on the
[current locale][setlocale].


The input string shall not contain nul characters even if the len
argument is positive. A nul character found inside the string will result
in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is
not UTF-8 and the conversion output contains a nul character, the error
%G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns nil.



  





  
Parameters:


    
  
    
  • 
      
        utf8string
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length of the string, or -1 if the string is
nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        bytes_read
      
      
        (Integer)
      
      
      
        —
        
    location to store the number of bytes in
the input string that were successfully converted, or nil.
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
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will be the byte offset after the last valid
input sequence.
    

    
      
    
    • 
  
    
  • 
      
        bytes_written
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes stored in
the output buffer (not including the terminating nul).
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    The converted string, or nil on an error.
    

    
      
    
    • 
  







    
      

  

  
    #filename_to_uri(filename, hostname)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        hostname
      
      
        (String)
      
      
      
        —
        
    A UTF-8 encoded hostname, or nil for none.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string holding the resulting
URI, or nil on an error.
    

    
      
    
    • 
  







    
      

  

  
    #filename_to_utf8(opsysstring, len, bytes_read, bytes_written)  ⇒ String 
  

  

  


  

    
Converts a string which is in the encoding used by GLib for
filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
for filenames; on other platforms, this function indirectly depends on
the [current locale][setlocale].


The input string shall not contain nul characters even if the len
argument is positive. A nul character found inside the string will result
in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
If the source encoding is not UTF-8 and the conversion output contains a
nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
function returns nil. Use g_convert() to produce output that
may contain embedded nul characters.



  





  
Parameters:


    
  
    
  • 
      
        opsysstring
      
      
        (GLib::filename)
      
      
      
        —
        
    a string in the encoding for filenames
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    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)
    

    
      
    
    • 
  
    
  • 
      
        bytes_read
      
      
        (Integer)
      
      
      
        —
        
    location to store the number of bytes in the
input string that were successfully converted, or nil.
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
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will be the byte offset after the last valid
input sequence.
    

    
      
    
    • 
  
    
  • 
      
        bytes_written
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes stored in the output
buffer (not including the terminating nul).
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The converted string, or nil on an error.
    

    
      
    
    • 
  







    
      

  

  
    #find_program_in_path(program)  ⇒ GLib::filename 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        program
      
      
        (GLib::filename)
      
      
      
        —
        
    a program name in the GLib file name encoding
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a newly-allocated
string with the absolute path, or nil
    

    
      
    
    • 
  







    
      

  

  
    #fopen(filename, mode)  ⇒ GObject 
  

  

  


  

    
A wrapper for the stdio fopen() function. The fopen() function
opens a file and associates a new stream with it.


Because file descriptors are specific to the C library on Windows,
and a file descriptor is part of the FILE struct, the FILE* returned
by this function makes sense only to functions in the same C library.
Thus if the GLib-using code uses a different C library than GLib does,
the FILE* returned by this function cannot be passed to C library
functions like fprintf() or fread().


See your C library manual for more details about fopen().


As close() and fclose() are part of the C library, this implies that it is
currently impossible to close a file if the application C library and the C library
used by GLib are different. Convenience functions like g_file_set_contents_full()
avoid this problem.



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (String)
      
      
      
        —
        
    a string describing the mode in which the file should be opened
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    A FILE* if the file was successfully opened, or nil if
an error occurred
    

    
      
    
    • 
  







    
      

  

  
    #format_size(size)  ⇒ String 
  

  

  


  

    
Formats a size (for example the size of a file) into a human readable
string.  Sizes are rounded to the nearest size prefix (kB, MB, GB)
and are displayed rounded to the nearest tenth. E.g. the file size
3292528 bytes will be converted into the string "3.2 MB". The returned string
is UTF-8, and may use a non-breaking space to separate the number and units,
to ensure they aren’t separated when line wrapped.


The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).


This string should be freed with g_free() when not needed any longer.


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



  





  
Parameters:


    
  
    
  • 
      
        size
      
      
        (Integer)
      
      
      
        —
        
    a size in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated formatted string containing
a human readable file size
    

    
      
    
    • 
  







    
      

  

  
    #format_size_for_display(size)  ⇒ String 
  

  

  


  

    
Formats a size (for example the size of a file) into a human
readable string. Sizes are rounded to the nearest size prefix
(KB, MB, GB) and are displayed rounded to the nearest tenth.
E.g. the file size 3292528 bytes will be converted into the
string "3.1 MB".


The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).


This string should be freed with g_free() when not needed any longer.



  





  
Parameters:


    
  
    
  • 
      
        size
      
      
        (Integer)
      
      
      
        —
        
    a size in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated formatted string
containing a human readable file size
    

    
      
    
    • 
  







    
      

  

  
    #format_size_full(size, flags)  ⇒ String 
  

  

  


  

    
Formats a size.


This function is similar to g_format_size() but allows for flags
that modify the output. See GFormat::SizeFlags.



  





  
Parameters:


    
  
    
  • 
      
        size
      
      
        (Integer)
      
      
      
        —
        
    a size in bytes
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::FormatSizeFlags)
      
      
      
        —
        
    GFormat::SizeFlags to modify the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated formatted string
containing a human readable file size
    

    
      
    
    • 
  







    
      

  

  
    #fprintf(file, format, array)  ⇒ Integer 
  

  

  


  

    
An implementation of the standard fprintf() function which supports
positional parameters, as specified in the Single Unix Specification.


glib/gprintf.h must be explicitly included in order to use this function.



  





  
Parameters:


    
  
    
  • 
      
        file
      
      
        (GObject)
      
      
      
        —
        
    the stream to write to
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes printed
    

    
      
    
    • 
  







    
      

  

  
    #free(mem)  ⇒ nil 
  

  

  


  

    
Frees the memory pointed to by mem.


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



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    the memory to free
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #free_sized(mem, size)  ⇒ nil 
  

  

  


  

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


If mem is nil 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 g_free() instead.


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



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    the memory to free
    

    
      
    
    • 
  
    
  • 
      
        size
      
      
        (Integer)
      
      
      
        —
        
    size of mem, in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #freopen(filename, mode, stream)  ⇒ GObject 
  

  

  


  

    
A wrapper for the POSIX freopen() function. The freopen() function
opens a file and associates it with an existing stream.


See your C library manual for more details about freopen().



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (String)
      
      
      
        —
        
    a string describing the mode in which the file should be  opened
    

    
      
    
    • 
  
    
  • 
      
        stream
      
      
        (GObject)
      
      
      
        —
        
    an existing stream which will be reused, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    A FILE* if the file was successfully opened, or nil if
an error occurred.
    

    
      
    
    • 
  







    
      

  

  
    #fsync(fd)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX fsync() function. On Windows, _commit() will be
used. On macOS, fcntl(F_FULLFSYNC) will be used.
The fsync() function is used to synchronize a file's in-core
state with that of the disk.


This wrapper will handle retrying on EINTR.


See the C library manual for more details about fsync().
The return value can be used exactly like the return value from fsync().



  





  
Parameters:


    
  
    
  • 
      
        fd
      
      
        (Integer)
      
      
      
        —
        
    a file descriptor
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 on success, or -1 if an error occurred.
    

    
      
    
    • 
  







    
      

  

  
    #get_charset(charset)  ⇒ Boolean 
  

  

  


  

    
Obtains the character set for the [current locale][setlocale]; you
might use this character set as an argument to g_convert(), to convert
from the current locale's encoding to some other encoding. (Frequently
g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.)


On Windows the character set returned by this function is the
so-called system default ANSI code-page. That is the character set
used by the "narrow" versions of C library and Win32 functions that
handle file names. It might be different from the character set
used by the C library's current locale.


On Linux, the character set is found by consulting nl_langinfo() if
available. If not, the environment variables LC_ALL, LC_CTYPE, LANG
and CHARSET are queried in order. 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 g_convert().


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



  





  
Parameters:


    
  
    
  • 
      
        charset
      
      
        (String)
      
      
      
        —
        
    return location for character set
name, or nil.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the returned charset is UTF-8
    

    
      
    
    • 
  







    
      

  

  
    #get_console_charset(charset)  ⇒ Boolean 
  

  

  


  

    
Obtains the character set used by the console attached to the process,
which is suitable for printing output to the terminal.


Usually this matches the result returned by g_get_charset(), but in
environments where the locale's character set does not match the encoding
of the console this function tries to guess a more suitable value instead.


On Windows the character set returned by this function is the
output code page used by the console associated with the calling process.
If the codepage can't be determined (for example because there is no
console attached) UTF-8 is assumed.


The return value is true if the locale's encoding is UTF-8, in that
case you can perhaps avoid calling g_convert().


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



  





  
Parameters:


    
  
    
  • 
      
        charset
      
      
        (String)
      
      
      
        —
        
    return location for character set
name, or nil.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the returned charset is UTF-8
    

    
      
    
    • 
  







    
      

  

  
    #get_current_time(result)  ⇒ nil 
  

  

  


  

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


You may find g_get_real_time() to be more convenient.



  





  
Parameters:


    
  
    
  • 
      
        result
      
      
        (GLib::TimeVal)
      
      
      
        —
        
    GTime::Val structure in which to store current time.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #get_filename_charsets(filename_charsets)  ⇒ Boolean 
  

  

  


  

    
Determines the preferred character sets used for filenames.
The first character set from the charsets is the filename encoding, the
subsequent character sets are used when trying to generate a displayable
representation of a filename, see g_filename_display_name().


On Unix, the character sets are determined by consulting the
environment variables G_FILENAME_ENCODING and G_BROKEN_FILENAMES.
On Windows, the character set used in the GLib API is always UTF-8
and said environment variables have no effect.


G_FILENAME_ENCODING may be set to a comma-separated list of
character set names. The special token "<b>locale" is taken
to  mean the character set for the [current locale][setlocale].
If G_FILENAME_ENCODING is not set, but G_BROKEN_FILENAMES is,
the character set of the current locale is taken as the filename
encoding. If neither environment variable  is set, UTF-8 is taken
as the filename encoding, but the character set of the current locale
is also put in the list of encodings.


The returned charsets belong to GLib and must not be freed.


Note that on Unix, regardless of the locale character set or
G_FILENAME_ENCODING value, the actual file names present
on a system might be in any random encoding or just gibberish.



  





  
Parameters:


    
  
    
  • 
      
        filename_charsets
      
      
        (Array<String>)
      
      
      
        —
        
    return location for the nil-terminated list of encoding names
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the filename encoding is UTF-8.
    

    
      
    
    • 
  







    
      

  

  
    #get_language_names_with_category(category_name)  ⇒ Array<String> 
  

  

  


  

    
Computes a list of applicable locale names with a locale category name,
which can be used to construct the fallback locale-dependent filenames
or search paths. The returned list is sorted from most desirable to
least desirable and always contains the default locale "C".


This function consults the environment variables LANGUAGE, LC_ALL,
category_name, and LANG to find the list of locales specified by the
user.


g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").



  





  
Parameters:


    
  
    
  • 
      
        category_name
      
      
        (String)
      
      
      
        —
        
    a locale category name
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings owned by
the thread g_get_language_names_with_category was called from.
It must not be modified or freed. It must be copied if planned to be used in another thread.
    

    
      
    
    • 
  







    
      

  

  
    #get_locale_variants(locale)  ⇒ Array<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.


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<b>euro</b>, then the returned list
is en_GB.UTF-8<b>euro</b>, en_GB.UTF-8, en_GB<b>euro</b>, en_GB, en.UTF-8<b>euro</b>,
en.UTF-8, en<b>euro</b>, en.


If you need the list of variants for the current locale,
use g_get_language_names().



  





  
Parameters:


    
  
    
  • 
      
        locale
      
      
        (String)
      
      
      
        —
        
    a locale identifier
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    a newly
allocated array of newly allocated strings with the locale variants. Free with
g_strfreev().
    

    
      
    
    • 
  







    
      

  

  
    #get_os_info(key_name)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        key_name
      
      
        (String)
      
      
      
        —
        
    a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The associated value for the requested key or nil if
this information is not provided.
    

    
      
    
    • 
  







    
      

  

  
    #get_user_special_dir(directory)  ⇒ GLib::filename 
  

  

  


  

    
Returns the full path of a special directory using its logical id.


On UNIX this is done using the XDG special user directories.
For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
falls back to $HOME/Desktop when XDG special user directories have
not been set up.


Depending on the platform, the user might be able to change the path
of the special directory without requiring the session to restart; GLib
will not reflect any change once the special directories are loaded.



  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the path to the specified special
directory, or nil if the logical id was not found. The returned string is
owned by GLib and should not be modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #getenv(variable)  ⇒ GLib::filename 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        variable
      
      
        (GLib::filename)
      
      
      
        —
        
    the environment variable to get
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the value of the environment variable, or nil if
the environment variable is not found. The returned string
may be overwritten by the next call to g_getenv(), g_setenv()
or g_unsetenv().
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_add(hash_table, key)  ⇒ Boolean 
  

  

  


  

    
This is a convenience function for using a GHash::Table as a set.  It
is equivalent to calling g_hash_table_replace() with key as both the
key and the value.


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


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


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



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (GObject)
      
      
      
        —
        
    a key to insert
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the key did not exist yet
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_contains(hash_table, key)  ⇒ Boolean 
  

  

  


  

    
Checks if key is in hash_table.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (GObject)
      
      
      
        —
        
    a key to check
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if key is in hash_table, false otherwise.
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_destroy(hash_table)  ⇒ nil 
  

  

  


  

    
Destroys all keys and values in the GHash::Table and decrements its
reference count by 1. If keys and/or values are dynamically allocated,
you should either free them first or create the GHash::Table 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.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hash_table_find(hash_table, predicate, user_data)  ⇒ GObject 
  

  

  


  

    
Calls the given function for key/value pairs in the GHash::Table
until predicate returns true. The function is passed the key
and value of each pair, and the given user_data parameter. The
hash table may not be modified while iterating over it (you can't
add/remove items).


Note, that hash tables are really only optimized for forward
lookups, i.e. g_hash_table_lookup(). So code that frequently issues
g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of
once per every entry in a hash table) should probably be reworked
to use additional or different data structures for reverse lookups
(keep in mind that an O(n) find/foreach operation issued for all n
values in a hash table ends up needing O(n*n) operations).



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        predicate
      
      
        (GLib::HRFunc)
      
      
      
        —
        
    function to test the key/value pairs for a certain property
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to the function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    The value of the first key/value pair is returned,
for which predicate evaluates to true. If no pair with the
requested property is found, nil is returned.
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_foreach(hash_table, func, user_data)  ⇒ nil 
  

  

  


  

    
Calls the given function for each of the key/value pairs in the
GHash::Table.  The function is passed the key and value of each
pair, and the given user_data parameter.  The hash table may not
be modified while iterating over it (you can't add/remove
items). To remove all items matching a predicate, use
g_hash_table_foreach_remove().


The order in which g_hash_table_foreach() iterates over the keys/values in
the hash table is not defined.


See g_hash_table_find() for performance caveats for linear
order searches in contrast to g_hash_table_lookup().



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (GLib::HFunc)
      
      
      
        —
        
    the function to call for each key/value pair
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to the function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hash_table_foreach_remove(hash_table, func, user_data)  ⇒ Integer 
  

  

  


  

    
Calls the given function for each key/value pair in the
GHash::Table. If the function returns true, then the key/value
pair is removed from the GHash::Table. If you supplied key or
value destroy functions when creating the GHash::Table, they are
used to free the memory allocated for the removed keys and values.


See GHash::TableIter for an alternative way to loop over the
key/value pairs in the hash table.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (GLib::HRFunc)
      
      
      
        —
        
    the function to call for each key/value pair
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to the function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of key/value pairs removed
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_foreach_steal(hash_table, func, user_data)  ⇒ Integer 
  

  

  


  

    
Calls the given function for each key/value pair in the
GHash::Table. If the function returns true, then the key/value
pair is removed from the GHash::Table, but no key or value
destroy functions are called.


See GHash::TableIter for an alternative way to loop over the
key/value pairs in the hash table.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (GLib::HRFunc)
      
      
      
        —
        
    the function to call for each key/value pair
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to the function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of key/value pairs removed.
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_get_keys_as_ptr_array(hash_table)  ⇒ Array<GObject> 
  

  

  


  

    
Retrieves every key inside hash_table, as a GPtr::Array.
The returned data is valid until changes to the hash release those keys.


This iterates over every entry in the hash table to build its return value.
To iterate over the entries in a GHash::Table more efficiently, use a
GHash::TableIter.


You should always unref the returned array with g_ptr_array_unref().
the table. Unref with with g_ptr_array_unref() when done.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    a GPtr::Array containing each key from
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_get_values_as_ptr_array(hash_table)  ⇒ Array<GObject> 
  

  

  


  

    
Retrieves every value inside hash_table, as a GPtr::Array.
The returned data is valid until changes to the hash release those values.


This iterates over every entry in the hash table to build its return value.
To iterate over the entries in a GHash::Table more efficiently, use a
GHash::TableIter.


You should always unref the returned array with g_ptr_array_unref().
the table. Unref with with g_ptr_array_unref() when done.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    a GPtr::Array containing each value from
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_insert(hash_table, key, value)  ⇒ Boolean 
  

  

  


  

    
Inserts a new key and value into a GHash::Table.


If the key already exists in the GHash::Table its current
value is replaced with the new value. If you supplied a
value_destroy_func when creating the GHash::Table, the old
value is freed using that function. If you supplied a
key_destroy_func when creating the GHash::Table, 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.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (GObject)
      
      
      
        —
        
    a key to insert
    

    
      
    
    • 
  
    
  • 
      
        value
      
      
        (GObject)
      
      
      
        —
        
    the value to associate with the key
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the key did not exist yet
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_lookup(hash_table, key)  ⇒ GObject 
  

  

  


  

    
Looks up a key in a GHash::Table. Note that this function cannot
distinguish between a key that is not present and one which is present
and has the value nil. If you need this distinction, use
g_hash_table_lookup_extended().



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (GObject)
      
      
      
        —
        
    the key to look up
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the associated value, or nil if the key is not found
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_lookup_extended(hash_table, lookup_key, orig_key, value)  ⇒ Boolean 
  

  

  


  

    
Looks up a key in the GHash::Table, returning the original key and the
associated value and a #gboolean which is true if the key was found. This
is useful if you need to free the memory allocated for the original key,
for example before calling g_hash_table_remove().


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



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        lookup_key
      
      
        (GObject)
      
      
      
        —
        
    the key to look up
    

    
      
    
    • 
  
    
  • 
      
        orig_key
      
      
        (GObject)
      
      
      
        —
        
    return location for the original key
    

    
      
    
    • 
  
    
  • 
      
        value
      
      
        (GObject)
      
      
      
        —
        
    return location for the value associated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the key was found in the GHash::Table
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_new_similar(other_hash_table)  ⇒ GLib::HashTable<GObject> 
  

  

  


  

    
Creates a new GHash::Table 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.



  





  
Parameters:


    
  
    
  • 
      
        other_hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    Another GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a new GHash::Table
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_ref(hash_table)  ⇒ GLib::HashTable<GObject> 
  

  

  


  

    
Atomically increments the reference count of hash_table by one.
This function is MT-safe and may be called from any thread.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a valid GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    the passed in GHash::Table
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_remove(hash_table, key)  ⇒ Boolean 
  

  

  


  

    
Removes a key and its associated value from a GHash::Table.


If the GHash::Table 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.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (GObject)
      
      
      
        —
        
    the key to remove
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the key was found and removed from the GHash::Table
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_remove_all(hash_table)  ⇒ nil 
  

  

  


  

    
Removes all keys and their associated values from a GHash::Table.


If the GHash::Table 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.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hash_table_replace(hash_table, key, value)  ⇒ Boolean 
  

  

  


  

    
Inserts a new key and value into a GHash::Table similar to
g_hash_table_insert(). The difference is that if the key
already exists in the GHash::Table, it gets replaced by the
new key. If you supplied a value_destroy_func when creating
the GHash::Table, the old value is freed using that function.
If you supplied a key_destroy_func when creating the
GHash::Table, 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.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (GObject)
      
      
      
        —
        
    a key to insert
    

    
      
    
    • 
  
    
  • 
      
        value
      
      
        (GObject)
      
      
      
        —
        
    the value to associate with the key
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the key did not exist yet
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_size(hash_table)  ⇒ Integer 
  

  

  


  

    
Returns the number of elements contained in the GHash::Table.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of key/value pairs in the GHash::Table.
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_steal(hash_table, key)  ⇒ Boolean 
  

  

  


  

    
Removes a key and its associated value from a GHash::Table without
calling the key and value destroy functions.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        key
      
      
        (GObject)
      
      
      
        —
        
    the key to remove
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the key was found and removed from the GHash::Table
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_steal_all(hash_table)  ⇒ nil 
  

  

  


  

    
Removes all keys and their associated values from a GHash::Table
without calling the key and value destroy functions.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hash_table_steal_all_keys(hash_table)  ⇒ Array<GObject> 
  

  

  


  

    
Removes all keys and their associated values from a GHash::Table
without calling the key destroy functions, returning the keys
as a GPtr::Array with the free func set to the hash_table key
destroy function.
the table. Unref with with g_ptr_array_unref() when done.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    a GPtr::Array containing each key of
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_steal_all_values(hash_table)  ⇒ Array<GObject> 
  

  

  


  

    
Removes all keys and their associated values from a GHash::Table
without calling the value destroy functions, returning the values
as a GPtr::Array with the free func set to the hash_table value
destroy function.
the table. Unref with with g_ptr_array_unref() when done.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    a GPtr::Array containing each value of
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_steal_extended(hash_table, lookup_key, stolen_key, stolen_value)  ⇒ Boolean 
  

  

  


  

    
Looks up a key in the GHash::Table, stealing the original key and the
associated value and returning true if the key was found. If the key was
not found, false is returned.


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


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


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



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a GHash::Table
    

    
      
    
    • 
  
    
  • 
      
        lookup_key
      
      
        (GObject)
      
      
      
        —
        
    the key to look up
    

    
      
    
    • 
  
    
  • 
      
        stolen_key
      
      
        (GObject)
      
      
      
        —
        
    return location for the
original key
    

    
      
    
    • 
  
    
  • 
      
        stolen_value
      
      
        (GObject)
      
      
      
        —
        
    return location
for the value associated with the key
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the key was found in the GHash::Table
    

    
      
    
    • 
  







    
      

  

  
    #hash_table_unref(hash_table)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        hash_table
      
      
        (GLib::HashTable<GObject>)
      
      
      
        —
        
    a valid GHash::Table
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #home_dir  ⇒ GLib::filename 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the current user's home directory
    

    
      
    
    • 
  







    
      

  

  
    #hook_destroy(hook_list, hook_id)  ⇒ Boolean 
  

  

  


  

    
Destroys a #GHook, given its ID.



  





  
Parameters:


    
  
    
  • 
      
        hook_list
      
      
        (GLib::HookList)
      
      
      
        —
        
    a GHook::List
    

    
      
    
    • 
  
    
  • 
      
        hook_id
      
      
        (GLib::gulong)
      
      
      
        —
        
    a hook ID
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the #GHook was found in the GHook::List and destroyed
    

    
      
    
    • 
  







    
      

  

  
    #hook_destroy_link(hook_list, hook)  ⇒ nil 
  

  

  


  

    
Removes one #GHook from a GHook::List, marking it
inactive and calling g_hook_unref() on it.



  





  
Parameters:


    
  
    
  • 
      
        hook_list
      
      
        (GLib::HookList)
      
      
      
        —
        
    a GHook::List
    

    
      
    
    • 
  
    
  • 
      
        hook
      
      
        (GLib::Hook)
      
      
      
        —
        
    the #GHook to remove
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hook_free(hook_list, hook)  ⇒ nil 
  

  

  


  

    
Calls the GHook::List finalize_hook function if it exists,
and frees the memory allocated for the #GHook.



  





  
Parameters:


    
  
    
  • 
      
        hook_list
      
      
        (GLib::HookList)
      
      
      
        —
        
    a GHook::List
    

    
      
    
    • 
  
    
  • 
      
        hook
      
      
        (GLib::Hook)
      
      
      
        —
        
    the #GHook to free
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hook_insert_before(hook_list, sibling, hook)  ⇒ nil 
  

  

  


  

    
Inserts a #GHook into a GHook::List, before a given #GHook.



  





  
Parameters:


    
  
    
  • 
      
        hook_list
      
      
        (GLib::HookList)
      
      
      
        —
        
    a GHook::List
    

    
      
    
    • 
  
    
  • 
      
        sibling
      
      
        (GLib::Hook)
      
      
      
        —
        
    the #GHook to insert the new #GHook before
    

    
      
    
    • 
  
    
  • 
      
        hook
      
      
        (GLib::Hook)
      
      
      
        —
        
    the #GHook to insert
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hook_insert_sorted(hook_list, hook, func)  ⇒ nil 
  

  

  


  

    
Inserts a #GHook into a GHook::List, sorted by the given function.



  





  
Parameters:


    
  
    
  • 
      
        hook_list
      
      
        (GLib::HookList)
      
      
      
        —
        
    a GHook::List
    

    
      
    
    • 
  
    
  • 
      
        hook
      
      
        (GLib::Hook)
      
      
      
        —
        
    the #GHook to insert
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (GLib::HookCompareFunc)
      
      
      
        —
        
    the comparison function used to sort the #GHook elements
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hook_prepend(hook_list, hook)  ⇒ nil 
  

  

  


  

    
Prepends a #GHook on the start of a GHook::List.



  





  
Parameters:


    
  
    
  • 
      
        hook_list
      
      
        (GLib::HookList)
      
      
      
        —
        
    a GHook::List
    

    
      
    
    • 
  
    
  • 
      
        hook
      
      
        (GLib::Hook)
      
      
      
        —
        
    the #GHook to add to the start of hook_list
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #hook_unref(hook_list, hook)  ⇒ nil 
  

  

  


  

    
Decrements the reference count of a #GHook.
If the reference count falls to 0, the #GHook is removed
from the GHook::List and g_hook_free() is called to free it.



  





  
Parameters:


    
  
    
  • 
      
        hook_list
      
      
        (GLib::HookList)
      
      
      
        —
        
    a GHook::List
    

    
      
    
    • 
  
    
  • 
      
        hook
      
      
        (GLib::Hook)
      
      
      
        —
        
    the #GHook to unref
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #host_name  ⇒ String 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the host name of the machine.
    

    
      
    
    • 
  







    
      

  

  
    #hostname_is_ascii_encoded(hostname)  ⇒ Boolean 
  

  

  


  

    
Tests if hostname contains segments with an ASCII-compatible
encoding of an Internationalized Domain Name. If this returns
true, you should decode the hostname with g_hostname_to_unicode()
before displaying it to the user.


Note that a hostname might contain a mix of encoded and unencoded
segments, and so it is possible for g_hostname_is_non_ascii() and
g_hostname_is_ascii_encoded() to both return true for a name.
segments.



  





  
Parameters:


    
  
    
  • 
      
        hostname
      
      
        (String)
      
      
      
        —
        
    a hostname
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if hostname contains any ASCII-encoded
    

    
      
    
    • 
  







    
      

  

  
    #hostname_is_ip_address(hostname)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        hostname
      
      
        (String)
      
      
      
        —
        
    a hostname (or IP address in string form)
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if hostname is an IP address
    

    
      
    
    • 
  







    
      

  

  
    #hostname_is_non_ascii(hostname)  ⇒ Boolean 
  

  

  


  

    
Tests if hostname contains Unicode characters. If this returns
true, you need to encode the hostname with g_hostname_to_ascii()
before using it in non-IDN-aware contexts.


Note that a hostname might contain a mix of encoded and unencoded
segments, and so it is possible for g_hostname_is_non_ascii() and
g_hostname_is_ascii_encoded() to both return true for a name.



  





  
Parameters:


    
  
    
  • 
      
        hostname
      
      
        (String)
      
      
      
        —
        
    a hostname
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if hostname contains any non-ASCII characters
    

    
      
    
    • 
  







    
      

  

  
    #hostname_to_ascii(hostname)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        hostname
      
      
        (String)
      
      
      
        —
        
    a valid UTF-8 or ASCII hostname
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    an ASCII hostname, which must be freed,
or nil if hostname is in some way invalid.
    

    
      
    
    • 
  







    
      

  

  
    #hostname_to_unicode(hostname)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        hostname
      
      
        (String)
      
      
      
        —
        
    a valid UTF-8 or ASCII hostname
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a UTF-8 hostname, which must be freed,
or nil if hostname is in some way invalid.
    

    
      
    
    • 
  







    
      

  

  
    #iconv(converter, inbuf, inbytes_left, outbuf, outbytes_left)  ⇒ Integer 
  

  

  


  

    
Same as the standard UNIX routine iconv(), but
may be implemented via libiconv on UNIX flavors that lack
a native implementation.


GLib provides g_convert() and g_locale_to_utf8() which are likely
more convenient than the raw iconv wrappers.


Note that the behaviour of iconv() for characters which are valid in the
input character set, but which have no representation in the output character
set, is implementation defined. This function may return success (with a
positive number of non-reversible conversions as replacement characters were
used), or it may return -1 and set an error such as %EILSEQ, in such a
situation.



  





  
Parameters:


    
  
    
  • 
      
        converter
      
      
        (GLib::IConv)
      
      
      
        —
        
    conversion descriptor from g_iconv_open()
    

    
      
    
    • 
  
    
  • 
      
        inbuf
      
      
        (String)
      
      
      
        —
        
    bytes to convert
    

    
      
    
    • 
  
    
  • 
      
        inbytes_left
      
      
        (Integer)
      
      
      
        —
        
    inout parameter, bytes remaining to convert in inbuf
    

    
      
    
    • 
  
    
  • 
      
        outbuf
      
      
        (String)
      
      
      
        —
        
    converted output bytes
    

    
      
    
    • 
  
    
  • 
      
        outbytes_left
      
      
        (Integer)
      
      
      
        —
        
    inout parameter, bytes available to fill in outbuf
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    count of non-reversible conversions, or -1 on error
    

    
      
    
    • 
  







    
      

  

  
    #iconv_open(to_codeset, from_codeset)  ⇒ GLib::IConv 
  

  

  


  

    
Same as the standard UNIX routine iconv_open(), but
may be implemented via libiconv on UNIX flavors that lack
a native implementation.


GLib provides g_convert() and g_locale_to_utf8() which are likely
more convenient than the raw iconv wrappers.



  





  
Parameters:


    
  
    
  • 
      
        to_codeset
      
      
        (String)
      
      
      
        —
        
    destination codeset
    

    
      
    
    • 
  
    
  • 
      
        from_codeset
      
      
        (String)
      
      
      
        —
        
    source codeset
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::IConv)
      
      
      
        —
        
    a "conversion descriptor", or (GIConv)-1 if
opening the converter failed.
    

    
      
    
    • 
  







    
      

  

  
    #idle_add(function, data)  ⇒ Integer 
  

  

  


  

    
Adds a function to be called whenever there are no higher priority
events pending to the default main loop. The function is given the
default idle priority, %G_PRIORITY_DEFAULT_IDLE.  If the function
returns false it is automatically removed from the list of event
sources and will not be called again.


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


This internally creates a main loop source using g_idle_source_new()
and attaches it to the global GMain::Context using g_source_attach(), so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.



  





  
Parameters:


    
  
    
  • 
      
        function
      
      
        (GLib::SourceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source.
    

    
      
    
    • 
  







    
      

  

  
    #idle_add_full(priority, function, data, notify)  ⇒ Integer 
  

  

  


  

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


If the function returns %G_SOURCE_REMOVE or false it is automatically
removed from the list of event sources and will not be called again.


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


This internally creates a main loop source using g_idle_source_new()
and attaches it to the global GMain::Context using g_source_attach(), so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.



  





  
Parameters:


    
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
        —
        
    the priority of the idle source. Typically this will be in the
range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::SourceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  
    
  • 
      
        notify
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    function to call when the idle is removed, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source.
    

    
      
    
    • 
  







    
      

  

  
    #idle_add_once(function, data)  ⇒ Integer 
  

  

  


  

    
Adds a function to be called whenever there are no higher priority
events pending to the default main loop. The function is given the
default idle priority, %G_PRIORITY_DEFAULT_IDLE.


The function will only be called once and then the source will be
automatically removed from the main context.


This function otherwise behaves like g_idle_add().



  





  
Parameters:


    
  
    
  • 
      
        function
      
      
        (GLib::SourceOnceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source
    

    
      
    
    • 
  







    
      

  

  
    #idle_remove_by_data(data)  ⇒ Boolean 
  

  

  


  

    
Removes the idle function with the given data.



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    the data for the idle source's callback.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if an idle source was found and removed.
    

    
      
    
    • 
  







    
      

  

  
    #idle_source_new  ⇒ GLib::Source 
  

  

  


  

    
Creates a new idle source.


The source will not initially be associated with any GMain::Context
and must be added to one with g_source_attach() before it will be
executed. Note that the default priority for idle sources is
%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which
have a default priority of %G_PRIORITY_DEFAULT.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Source)
      
      
      
        —
        
    the newly-created idle source
    

    
      
    
    • 
  







    
      

  

  
    #int64_equal(v1, v2)  ⇒ Boolean 
  

  

  


  

    
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-nil pointers to 64-bit integers as keys in a
GHash::Table.



  





  
Parameters:


    
  
    
  • 
      
        v1
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gint64 key
    

    
      
    
    • 
  
    
  • 
      
        v2
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gint64 key to compare with v1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the two keys match.
    

    
      
    
    • 
  







    
      

  

  
    #int64_hash(v)  ⇒ Integer 
  

  

  


  

    
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-nil pointers to 64-bit integer values as keys in a
GHash::Table.



  





  
Parameters:


    
  
    
  • 
      
        v
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gint64 key
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a hash value corresponding to the key.
    

    
      
    
    • 
  







    
      

  

  
    #int_equal(v1, v2)  ⇒ Boolean 
  

  

  


  

    
Compares the two #gint values being pointed to and returns
true if they are equal.
It can be passed to g_hash_table_new() as the key_equal_func
parameter, when using non-nil pointers to integers as keys in a
GHash::Table.


Note that this function acts on pointers to #gint, not on #gint
directly: if your hash table's keys are of the form
GINT_TO_POINTER (n), use g_direct_equal() instead.



  





  
Parameters:


    
  
    
  • 
      
        v1
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gint key
    

    
      
    
    • 
  
    
  • 
      
        v2
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gint key to compare with v1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the two keys match.
    

    
      
    
    • 
  







    
      

  

  
    #int_hash(v)  ⇒ Integer 
  

  

  


  

    
Converts a pointer to a #gint to a hash value.
It can be passed to g_hash_table_new() as the hash_func parameter,
when using non-nil pointers to integer values as keys in a GHash::Table.


Note that this function acts on pointers to #gint, not on #gint
directly: if your hash table's keys are of the form
GINT_TO_POINTER (n), use g_direct_hash() instead.



  





  
Parameters:


    
  
    
  • 
      
        v
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gint key
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a hash value corresponding to the key.
    

    
      
    
    • 
  







    
      

  

  
    #intern_static_string(string)  ⇒ String 
  

  

  


  

    
Returns a canonical representation for string. Interned strings
can be compared for equality by comparing the pointers, instead of
using strcmp(). g_intern_static_string() does not copy the string,
therefore string must not be freed or modified.


This function must not be used before library constructors have finished
running. In particular, this means it cannot be used to initialize global
variables in C++.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a static string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a canonical representation for the string
    

    
      
    
    • 
  







    
      

  

  
    #intern_string(string)  ⇒ String 
  

  

  


  

    
Returns a canonical representation for string. Interned strings
can be compared for equality by comparing the pointers, instead of
using strcmp().


This function must not be used before library constructors have finished
running. In particular, this means it cannot be used to initialize global
variables in C++.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a canonical representation for the string
    

    
      
    
    • 
  







    
      

  

  
    #io_add_watch(channel, condition, func, user_data)  ⇒ Integer 
  

  

  


  

    
Adds the #GIOChannel into the default main loop context
with the default priority.



  





  
Parameters:


    
  
    
  • 
      
        channel
      
      
        (GLib::IOChannel)
      
      
      
        —
        
    a #GIOChannel
    

    
      
    
    • 
  
    
  • 
      
        condition
      
      
        (GLib::IOCondition)
      
      
      
        —
        
    the condition to watch for
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (GLib::IOFunc)
      
      
      
        —
        
    the function to call when the condition is satisfied
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to func
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the event source id
    

    
      
    
    • 
  







    
      

  

  
    #io_add_watch_full(channel, priority, condition, func, user_data, notify)  ⇒ Integer 
  

  

  


  

    
Adds the #GIOChannel into the default main loop context
with the given priority.


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



  





  
Parameters:


    
  
    
  • 
      
        channel
      
      
        (GLib::IOChannel)
      
      
      
        —
        
    a #GIOChannel
    

    
      
    
    • 
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
        —
        
    the priority of the #GIOChannel source
    

    
      
    
    • 
  
    
  • 
      
        condition
      
      
        (GLib::IOCondition)
      
      
      
        —
        
    the condition to watch for
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (GLib::IOFunc)
      
      
      
        —
        
    the function to call when the condition is satisfied
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to func
    

    
      
    
    • 
  
    
  • 
      
        notify
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    the function to call when the source is removed
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the event source id
    

    
      
    
    • 
  







    
      

  

  
    #io_channel_error_from_errno(en)  ⇒ GLib::IOChannelError 
  

  

  


  

    
Converts an errno error number to a GIOChannel::Error.



  





  
Parameters:


    
  
    
  • 
      
        en
      
      
        (Integer)
      
      
      
        —
        
    an errno error number, e.g. EINVAL
    

    
      
    
    • 
  




Returns:







    
      

  

  
    #io_channel_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #io_create_watch(channel, condition)  ⇒ GLib::Source 
  

  

  


  

    
Creates a #GSource that's dispatched when condition is met for the
given channel. For example, if condition is %G_IO_IN, the source will
be dispatched when there's data available for reading.


The callback function invoked by the #GSource should be added with
g_source_set_callback(), but it has type #GIOFunc (not GSource::Func).


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



  





  
Parameters:


    
  
    
  • 
      
        channel
      
      
        (GLib::IOChannel)
      
      
      
        —
        
    a #GIOChannel to watch
    

    
      
    
    • 
  
    
  • 
      
        condition
      
      
        (GLib::IOCondition)
      
      
      
        —
        
    conditions to watch for
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Source)
      
      
      
        —
        
    a new #GSource
    

    
      
    
    • 
  







    
      

  

  
    #key_file_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #language_names  ⇒ Array<String> 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings owned by GLib
that must not be modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #list_pop_allocator  ⇒ nil 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #list_push_allocator(allocator)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        allocator
      
      
        (GLib::Allocator)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #listenv  ⇒ Array<GLib::filename> 
  

  

  


  

    
Gets the names of all variables set in the environment.


Programs that want to be portable to Windows should typically use
this function and g_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 g_getenv() provide.



  





  

Returns:


    
  
    
  • 
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    a nil-terminated list of strings which must be freed with
g_strfreev().
    

    
      
    
    • 
  







    
      

  

  
    #locale_from_utf8(utf8string, len, bytes_read, bytes_written)  ⇒ Array<Integer> 
  

  

  


  

    
Converts a string from UTF-8 to the encoding used for strings by
the C runtime (usually the same as that used by the operating
system) in the [current locale][setlocale]. On Windows this means
the system codepage.


The input string shall not contain nul characters even if the len
argument is positive. A nul character found inside the string will result
in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert
input that may contain embedded nul characters.



  





  
Parameters:


    
  
    
  • 
      
        utf8string
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length of the string, or -1 if the string is
nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        bytes_read
      
      
        (Integer)
      
      
      
        —
        
    location to store the number of bytes in the
input string that were successfully converted, or nil.
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
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will be the byte offset after the last valid
input sequence.
    

    
      
    
    • 
  
    
  • 
      
        bytes_written
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes stored in the output
buffer (not including the terminating nul).
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<Integer>)
      
      
      
        —
        
    A newly-allocated buffer containing the converted string,
or nil on an error, and error will be set.
    

    
      
    
    • 
  







    
      

  

  
    #locale_to_utf8(opsysstring, len, bytes_read, bytes_written)  ⇒ String 
  

  

  


  

    
Converts a string which is in the encoding used for strings by
the C runtime (usually the same as that used by the operating
system) in the [current locale][setlocale] into a UTF-8 string.


If the source encoding is not UTF-8 and the conversion output contains a
nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
function returns nil.
If the source encoding is UTF-8, an embedded nul character is treated with
the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with
earlier versions of this library. Use g_convert() to produce output that
may contain embedded nul characters.



  





  
Parameters:


    
  
    
  • 
      
        opsysstring
      
      
        (Array<Integer>)
      
      
      
        —
        
    a string in the
encoding of the current locale. On Windows
this means the system codepage.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    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)
    

    
      
    
    • 
  
    
  • 
      
        bytes_read
      
      
        (Integer)
      
      
      
        —
        
    location to store the number of bytes in the
input string that were successfully converted, or nil.
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
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will be the byte offset after the last valid
input sequence.
    

    
      
    
    • 
  
    
  • 
      
        bytes_written
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes stored in the output
buffer (not including the terminating nul).
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The converted string, or nil on an error.
    

    
      
    
    • 
  







    
      

  

  
    #log(log_domain, log_level, format, array)  ⇒ nil 
  

  

  


  

    
Logs an error or debugging message.


If the log level has been set as fatal, [funcGLib.BREAKPOINT] is called
to terminate the program. See the documentation for [funcGLib.BREAKPOINT] for
details of the debugging options this provides.


If [funcGLib.log_default_handler] is used as the log handler function, a new-line
character will automatically be appended to @..., and need not be entered
manually.


If structured logging is enabled this will
output via the structured log writer function (see [funcGLib.log_set_writer_func]).



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    the log domain, usually G_LOG_DOMAIN, or NULL
for the default
    

    
      
    
    • 
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    the log level, either from [typeGLib.LogLevelFlags]
or a user-defined level
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the message format. See the printf() documentation
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the parameters to insert into the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_default_handler(log_domain, log_level, message, unused_data)  ⇒ nil 
  

  

  


  

    
The default log handler set up by GLib; [funcGLib.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 [funcGLib.BREAKPOINT]. It automatically
prints a new-line character after the message, so one does not need to be
manually included in message.


The behavior of this log handler can be influenced by a number of
environment variables:


    

  • G_MESSAGES_PREFIXED: A :-separated list of log levels for which
messages should be prefixed by the program name and PID of the
application.
    • 

  • G_MESSAGES_DEBUG: A space-separated list of log domains for
which debug and informational messages are printed. By default
these messages are not printed. If you need to set the allowed
domains at runtime, use [funcGLib.log_writer_default_set_debug_domains].
    • 



stderr is used for levels [flagsGLib.LogLevelFlags.LEVEL_ERROR],
[flagsGLib.LogLevelFlags.LEVEL_CRITICAL], [flagsGLib.LogLevelFlags.LEVEL_WARNING] and
[flagsGLib.LogLevelFlags.LEVEL_MESSAGE]. stdout is used for
the rest, unless stderr was requested by
[funcGLib.log_writer_default_set_use_stderr].


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



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    the log domain of the message, or NULL for the
default "" application domain
    

    
      
    
    • 
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    the level of the message
    

    
      
    
    • 
  
    
  • 
      
        message
      
      
        (String)
      
      
      
        —
        
    the message
    

    
      
    
    • 
  
    
  • 
      
        unused_data
      
      
        (GObject)
      
      
      
        —
        
    data passed from [funcGLib.log] which is unused
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_get_debug_enabled  ⇒ Boolean 
  

  

  


  

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


Note that this should not be used to conditionalise calls to [funcGLib.debug] or
other logging functions; it should only be used from [typeGLib.LogWriterFunc]
implementations.


Note also that the value of this does not depend on G_MESSAGES_DEBUG, nor
[funcGLib.log_writer_default_set_debug_domains]; see the docs for [funcGLib.log_set_debug_enabled].



  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    TRUE if debug output is enabled, FALSE otherwise
    

    
      
    
    • 
  







    
      

  

  
    #log_remove_handler(log_domain, handler_id)  ⇒ nil 
  

  

  


  

    
Removes the log handler.


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



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    the log domain
    

    
      
    
    • 
  
    
  • 
      
        handler_id
      
      
        (Integer)
      
      
      
        —
        
    the ID of the handler, which was returned
in [funcGLib.log_set_handler]
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_set_always_fatal(fatal_mask)  ⇒ 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.
[flagsGLib.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 [funcGLib.log_structured] and
[funcGLib.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.



  





  
Parameters:


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

    
      
    
    • 
  




Returns:







    
      

  

  
    #log_set_debug_enabled(enabled)  ⇒ nil 
  

  

  


  

    
Enable or disable debug output from the GLib logging system for all domains.


This value interacts disjunctively with G_MESSAGES_DEBUG and
[funcGLib.log_writer_default_set_debug_domains] — if any of them would allow
a debug message to be outputted, it will be.


Note that this should not be used from within library code to enable debug
output — it is intended for external use.



  





  
Parameters:


    
  
    
  • 
      
        enabled
      
      
        (Boolean)
      
      
      
        —
        
    TRUE to enable debug output, FALSE otherwise
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_set_default_handler(log_func, user_data)  ⇒ GLib::LogFunc 
  

  

  


  

    
Installs a default log handler which is used if no
log handler has been set for the particular log domain
and log level combination.


By default, GLib uses [funcGLib.log_default_handler] as default log handler.


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



  





  
Parameters:


    
  
    
  • 
      
        log_func
      
      
        (GLib::LogFunc)
      
      
      
        —
        
    the log handler function
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    data passed to the log handler
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::LogFunc)
      
      
      
        —
        
    the previous default log handler
    

    
      
    
    • 
  







    
      

  

  
    #log_set_fatal_mask(log_domain, fatal_mask)  ⇒ GLib::LogLevelFlags 
  

  

  


  

    
Sets the log levels which are fatal in the given domain.


[flagsGLib.LogLevelFlags.LEVEL_ERROR] is always fatal.


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


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



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    the log domain
    

    
      
    
    • 
  
    
  • 
      
        fatal_mask
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    the new fatal mask
    

    
      
    
    • 
  




Returns:







    
      

  

  
    #log_set_handler(log_domain, log_levels, log_func, user_data)  ⇒ Integer 
  

  

  


  

    
Sets the log handler for a domain and a set of log levels.


To handle fatal and recursive messages the log_levels parameter
must be combined with the [flagsGLib.LogLevelFlags.FLAG_FATAL] and [flagsGLib.LogLevelFlags.FLAG_RECURSION]
bit flags.


Note that since the [flagsGLib.LogLevelFlags.LEVEL_ERROR] log level is always fatal, if
you want to set a handler for this log level you must combine it with
[flagsGLib.LogLevelFlags.FLAG_FATAL].


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


Here is an example for adding a log handler for all warning messages
in the default domain:


g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);



This example adds a log handler for all critical messages from GTK:


g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);



This example adds a log handler for all messages from GLib:


g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);




  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    the log domain, or NULL for the default ""
application domain
    

    
      
    
    • 
  
    
  • 
      
        log_levels
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    the log levels to apply the log handler for.
To handle fatal and recursive messages as well, combine
the log levels with the [flagsGLib.LogLevelFlags.FLAG_FATAL] and
[flagsGLib.LogLevelFlags.FLAG_RECURSION] bit flags.
    

    
      
    
    • 
  
    
  • 
      
        log_func
      
      
        (GLib::LogFunc)
      
      
      
        —
        
    the log handler function
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    data passed to the log handler
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the id of the new handler
    

    
      
    
    • 
  







    
      

  

  
    #log_set_handler_full(log_domain, log_levels, log_func, user_data, destroy)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    the log domain, or NULL for the default ""
application domain
    

    
      
    
    • 
  
    
  • 
      
        log_levels
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    the log levels to apply the log handler for.
To handle fatal and recursive messages as well, combine
the log levels with the [flagsGLib.LogLevelFlags.FLAG_FATAL] and
[flagsGLib.LogLevelFlags.FLAG_RECURSION] bit flags.
    

    
      
    
    • 
  
    
  • 
      
        log_func
      
      
        (GLib::LogFunc)
      
      
      
        —
        
    the log handler function
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    data passed to the log handler
    

    
      
    
    • 
  
    
  • 
      
        destroy
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    destroy notify for user_data, or NULL
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID of the new handler
    

    
      
    
    • 
  







    
      

  

  
    #log_set_writer_func(func, user_data, user_data_free)  ⇒ nil 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        func
      
      
        (GLib::LogWriterFunc)
      
      
      
        —
        
    log writer function, which must not be NULL
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data to pass to func
    

    
      
    
    • 
  
    
  • 
      
        user_data_free
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    function to free user_data once it’s
finished with, if non-NULL
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_structured(log_domain, log_level, array)  ⇒ nil 
  

  

  


  

    
Log a message with structured data.


The message will be passed through to the log writer set by the application
using [funcGLib.log_set_writer_func]. If the message is fatal (i.e. its log level
is [flagsGLib.LogLevelFlags.LEVEL_ERROR]), the program will be aborted by calling
[funcGLib.BREAKPOINT] at the end of this function. If the log writer returns
[enumGLib.LogWriterOutput.UNHANDLED] (failure), no other fallback writers will be tried.
See the documentation for [typeGLib.LogWriterFunc] for information on chaining
writers.


The structured data is provided as key–value pairs, where keys are UTF-8
strings, and values are arbitrary pointers — typically pointing to UTF-8
strings, but that is not a requirement. To pass binary (non-nul-terminated)
structured data, use [funcGLib.log_structured_array]. The keys for structured data
should follow the systemd journal
fields
specification. It is suggested that custom keys are namespaced according to
the code which sets them. For example, custom keys from GLib all have a
GLIB_ prefix.


Note that keys that expect UTF-8 strings (specifically "MESSAGE" and
"GLIB_DOMAIN") must be passed as nul-terminated UTF-8 strings until GLib
version 2.74.1 because the default log handler did not consider the length of
the GLogField. Starting with GLib 2.74.1 this is fixed and
non-nul-terminated UTF-8 strings can be passed with their correct length.


The log_domain will be converted into a GLIB_DOMAIN field. log_level will
be converted into a
PRIORITY
field. The format string will have its placeholders substituted for the provided
values and be converted into a
MESSAGE
field.


Other fields you may commonly want to pass into this function:



Note that CODE_FILE, CODE_LINE and CODE_FUNC are automatically set by
the logging macros, [funcGLib.DEBUG_HERE], [funcGLib.message], [funcGLib.warning], [funcGLib.critical],
[funcGLib.error], etc, if the symbol G_LOG_USE_STRUCTURED is defined before including
glib.h.


For example:


g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
                  "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
                  "MY_APPLICATION_CUSTOM_FIELD", "some debug string",
                  "MESSAGE", "This is a debug message about pointer %p and integer %u.",
                  some_pointer, some_integer);



Note that each MESSAGE_ID must be uniquely and randomly
generated.
If adding a MESSAGE_ID, consider shipping a message
catalog with
your software.


To pass a user data pointer to the log writer function which is specific to
this logging call, you must use [funcGLib.log_structured_array] and pass the pointer
as a field with GLogField.length set to zero, otherwise it will be
interpreted as a string.


For example:


const GLogField fields[] = {
  { "MESSAGE", "This is a debug message.", -1 },
  { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 },
  { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 },
  { "MY_APPLICATION_STATE", state_object, 0 },
};
g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields));



Note also that, even if no other structured fields are specified, there
must always be a MESSAGE key before the format string. The MESSAGE-format
pair has to be the last of the key-value pairs, and MESSAGE is the only
field for which printf()-style formatting is supported.


The default writer function for stdout and stderr will automatically
append a new-line character after the message, so you should not add one
manually to the format string.



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    log domain, usually G_LOG_DOMAIN
    

    
      
    
    • 
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    key-value pairs of structured data to add to the log entry, followed
by the key MESSAGE, followed by a printf()-style message format,
followed by parameters to insert in the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_structured_array(log_level, fields, n_fields)  ⇒ nil 
  

  

  


  

    
Log a message with structured data.


The message will be passed through to the log writer set by the application
using [funcGLib.log_set_writer_func]. If the
message is fatal (i.e. its log level is [flagsGLib.LogLevelFlags.LEVEL_ERROR]), the program will
be aborted at the end of this function.


See [funcGLib.log_structured] for more documentation.


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



  





  
Parameters:


    
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        fields
      
      
        (Array<GLib::LogField>)
      
      
      
        —
        
    key–value pairs of structured data to add
to the log message
    

    
      
    
    • 
  
    
  • 
      
        n_fields
      
      
        (Integer)
      
      
      
        —
        
    number of elements in the fields array
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_structured_standard(log_domain, log_level, file, line, func, message_format, array)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        message_format
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_variant(log_domain, log_level, fields)  ⇒ nil 
  

  

  


  

    
Log a message with structured data, accepting the data within a [typeGLib.Variant].


This version is especially useful for use in other languages, via introspection.


The only mandatory item in the fields dictionary is the "MESSAGE" which must
contain the text shown to the user.


The values in the fields dictionary are likely to be of type G_VARIANT_TYPE_STRING.
Array of bytes (G_VARIANT_TYPE_BYTESTRING) is also
supported. In this case the message is handled as binary and will be forwarded
to the log writer as such. The size of the array should not be higher than
G_MAXSSIZE. Otherwise it will be truncated to this size. For other types
[methodGLib.Variant.print] will be used to convert the value into a string.


For more details on its usage and about the parameters, see [funcGLib.log_structured].
containing the key-value pairs of message data.



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    log domain, usually G_LOG_DOMAIN
    

    
      
    
    • 
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        fields
      
      
        (GLib::Variant)
      
      
      
        —
        
    a dictionary ([typeGLib.Variant] of the type G_VARIANT_TYPE_VARDICT)
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_writer_default(log_level, fields, n_fields, user_data)  ⇒ 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 [typeGLib.LogWriterFunc], and is the default writer used
if no other is set using [funcGLib.log_set_writer_func].


As with [funcGLib.log_default_handler], this function drops debug and informational
messages unless their log domain (or all) is listed in the space-separated
G_MESSAGES_DEBUG environment variable, or set at runtime by [funcGLib.log_writer_default_set_debug_domains].


[funcGLib.log_writer_default] uses the mask set by [funcGLib.log_set_always_fatal] to
determine which messages are fatal. When using a custom writer function instead it is
up to the writer function to determine which log messages are fatal.



  





  
Parameters:


    
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        fields
      
      
        (Array<GLib::LogField>)
      
      
      
        —
        
    key–value pairs of structured data forming
the log message
    

    
      
    
    • 
  
    
  • 
      
        n_fields
      
      
        (Integer)
      
      
      
        —
        
    number of elements in the fields array
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to [funcGLib.log_set_writer_func]
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::LogWriterOutput)
      
      
      
        —
        
    [enumGLib.LogWriterOutput.HANDLED] on success,
[enumGLib.LogWriterOutput.UNHANDLED] otherwise
    

    
      
    
    • 
  







    
      

  

  
    #log_writer_default_set_debug_domains(domains)  ⇒ nil 
  

  

  


  

    
Reset the list of domains to be logged, that might be initially set by the
G_MESSAGES_DEBUG environment variable.


This function is thread-safe.



  





  
Parameters:


    
  
    
  • 
      
        domains
      
      
        (String)
      
      
      
        —
        
    NULL-terminated array with domains to be printed.
NULL or an array with no values means none. Array with a single value "all" means all.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_writer_default_set_use_stderr(use_stderr)  ⇒ nil 
  

  

  


  

    
Configure whether the built-in log functions will output all log messages to
stderr.


The built-in log functions are [funcGLib.log_default_handler] for the
old-style API, and both [funcGLib.log_writer_default] and
[funcGLib.log_writer_standard_streams] for the structured API.


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



  





  
Parameters:


    
  
    
  • 
      
        use_stderr
      
      
        (Boolean)
      
      
      
        —
        
    If TRUE, use stderr for log messages that would
normally have appeared on stdout
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #log_writer_default_would_drop(log_level, log_domain)  ⇒ Boolean 
  

  

  


  

    
Check whether [funcGLib.log_writer_default] and [funcGLib.log_default_handler] would
ignore a message with the given domain and level.


As with [funcGLib.log_default_handler], this function drops debug and informational
messages unless their log domain (or all) is listed in the space-separated
G_MESSAGES_DEBUG environment variable, or by [funcGLib.log_writer_default_set_debug_domains].


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


if (g_log_writer_default_would_drop (log_level, log_domain))
  return G_LOG_WRITER_HANDLED;
]|

or to skip an expensive computation if it is only needed for a debugging
message, and `G_MESSAGES_DEBUG` is not set:

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

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




  





  
Parameters:


    
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    log domain
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    TRUE if the log message would be dropped by GLib’s
default log handlers
    

    
      
    
    • 
  







    
      

  

  
    #log_writer_format_fields(log_level, fields, n_fields, use_color)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        fields
      
      
        (Array<GLib::LogField>)
      
      
      
        —
        
    key–value pairs of structured data forming
the log message
    

    
      
    
    • 
  
    
  • 
      
        n_fields
      
      
        (Integer)
      
      
      
        —
        
    number of elements in the fields array
    

    
      
    
    • 
  
    
  • 
      
        use_color
      
      
        (Boolean)
      
      
      
        —
        
    TRUE to use
ANSI color escape sequences
when formatting the message, FALSE to not
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    string containing the formatted log message, in
the character set of the current locale
    

    
      
    
    • 
  







    
      

  

  
    #log_writer_is_journald(output_fd)  ⇒ Boolean 
  

  

  


  

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




  





  
Parameters:


    
  
    
  • 
      
        output_fd
      
      
        (Integer)
      
      
      
        —
        
    output file descriptor to check
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    TRUE if output_fd points to the journal, FALSE otherwise
    

    
      
    
    • 
  







    
      

  

  
    #log_writer_journald(log_level, fields, n_fields, user_data)  ⇒ 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 [typeGLib.LogWriterFunc].


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



  





  
Parameters:


    
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        fields
      
      
        (Array<GLib::LogField>)
      
      
      
        —
        
    key–value pairs of structured data forming
the log message
    

    
      
    
    • 
  
    
  • 
      
        n_fields
      
      
        (Integer)
      
      
      
        —
        
    number of elements in the fields array
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to [funcGLib.log_set_writer_func]
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::LogWriterOutput)
      
      
      
        —
        
    [enumGLib.LogWriterOutput.HANDLED] on success, [enumGLib.LogWriterOutput.UNHANDLED] otherwise
    

    
      
    
    • 
  







    
      

  

  
    #log_writer_standard_streams(log_level, fields, n_fields, user_data)  ⇒ GLib::LogWriterOutput 
  

  

  


  

    
Format a structured log message and print it to either stdout or stderr,
depending on its log level.


[flagsGLib.LogLevelFlags.LEVEL_INFO] and [flagsGLib.LogLevelFlags.LEVEL_DEBUG] messages
are sent to stdout, or to stderr if requested by
[funcGLib.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 [typeGLib.LogWriterFunc].



  





  
Parameters:


    
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        fields
      
      
        (Array<GLib::LogField>)
      
      
      
        —
        
    key–value pairs of structured data forming
the log message
    

    
      
    
    • 
  
    
  • 
      
        n_fields
      
      
        (Integer)
      
      
      
        —
        
    number of elements in the fields array
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to [funcGLib.log_set_writer_func]
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::LogWriterOutput)
      
      
      
        —
        
    [enumGLib.LogWriterOutput.HANDLED] on success,
[enumGLib.LogWriterOutput.UNHANDLED] otherwise
    

    
      
    
    • 
  







    
      

  

  
    #log_writer_supports_color(output_fd)  ⇒ Boolean 
  

  

  


  

    
Check whether the given output_fd file descriptor supports
ANSI color escape sequences.


If so, they can safely be used when formatting log messages.



  





  
Parameters:


    
  
    
  • 
      
        output_fd
      
      
        (Integer)
      
      
      
        —
        
    output file descriptor to check
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    TRUE if ANSI color escapes are supported, FALSE otherwise
    

    
      
    
    • 
  







    
      

  

  
    #log_writer_syslog(log_level, fields, n_fields, user_data)  ⇒ GLib::LogWriterOutput 
  

  

  


  

    
Format a structured log message and send it to the syslog daemon. Only fields
which are understood by this function are included in the formatted string
which is printed.


Log facility will be defined via the SYSLOG_FACILITY field and accepts the following
values: "auth", "daemon", and "user". If SYSLOG_FACILITY is not specified, LOG_USER
facility will be used.


This is suitable for use as a [typeGLib.LogWriterFunc].


If syslog is not supported, this function is still defined, but will always
return [enumGLib.LogWriterOutput.UNHANDLED].



  





  
Parameters:


    
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    log level, either from [typeGLib.LogLevelFlags], or a user-defined
level
    

    
      
    
    • 
  
    
  • 
      
        fields
      
      
        (Array<GLib::LogField>)
      
      
      
        —
        
    key–value pairs of structured data forming
the log message
    

    
      
    
    • 
  
    
  • 
      
        n_fields
      
      
        (Integer)
      
      
      
        —
        
    number of elements in the fields array
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to [funcGLib.log_set_writer_func]
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::LogWriterOutput)
      
      
      
        —
        
    [enumGLib.LogWriterOutput.HANDLED] on success, [enumGLib.LogWriterOutput.UNHANDLED] otherwise
    

    
      
    
    • 
  







    
      

  

  
    #logv(log_domain, log_level, format, args)  ⇒ nil 
  

  

  


  

    
Logs an error or debugging message.


If the log level has been set as fatal, [funcGLib.BREAKPOINT] is called
to terminate the program. See the documentation for [funcGLib.BREAKPOINT] for
details of the debugging options this provides.


If [funcGLib.log_default_handler] is used as the log handler function, a new-line
character will automatically be appended to @..., and need not be entered
manually.


If structured logging is enabled this will
output via the structured log writer function (see [funcGLib.log_set_writer_func]).



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    the log domain, or NULL for the default ""
application domain
    

    
      
    
    • 
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    the log level
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the message format. See the printf() documentation
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    the parameters to insert into the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #lstat(filename, buf)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX lstat() function. The lstat() function is
like stat() except that in the case of symbolic links, it returns
information about the symbolic link itself and not the file that it
refers to. If the system does not support symbolic links g_lstat()
is identical to g_stat().


See your C library manual for more details about lstat().



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        buf
      
      
        (GLib::StatBuf)
      
      
      
        —
        
    a pointer to a stat struct, which will be filled with the file
information
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the information was successfully retrieved,
-1 if an error occurred
    

    
      
    
    • 
  







    
      

  

  
    #main_context_default  ⇒ 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
g_main_context_get_thread_default().



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::MainContext)
      
      
      
        —
        
    the global-default main context.
    

    
      
    
    • 
  







    
      

  

  
    #main_context_get_thread_default  ⇒ GLib::MainContext 
  

  

  


  

    
Gets the thread-default GMain::Context 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
g_main_context_ref_thread_default() to get a GMain::Context to add
their #GSources 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 nil if you are running in the default thread.)


If you need to hold a reference on the context, use
g_main_context_ref_thread_default() instead.
nil if the thread-default context is the global-default main context.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::MainContext)
      
      
      
        —
        
    the thread-default GMain::Context, or
    

    
      
    
    • 
  







    
      

  

  
    #main_context_ref_thread_default  ⇒ GLib::MainContext 
  

  

  


  

    
Gets the thread-default GMain::Context for this thread, as with
g_main_context_get_thread_default(), but also adds a reference to
it with g_main_context_ref(). In addition, unlike
g_main_context_get_thread_default(), if the thread-default context
is the global-default context, this will return that GMain::Context
(with a ref added to it) rather than returning nil.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::MainContext)
      
      
      
        —
        
    the thread-default GMain::Context. Unref
with g_main_context_unref() when you are done with it.
    

    
      
    
    • 
  







    
      

  

  
    #main_current_source  ⇒ GLib::Source 
  

  

  


  

    
Returns the currently firing source for this thread.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Source)
      
      
      
        —
        
    The currently firing source or nil.
    

    
      
    
    • 
  







    
      

  

  
    #main_depth  ⇒ Integer 
  

  

  


  

    
Returns the depth of the stack of calls to
g_main_context_dispatch() on any GMain::Context 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.


This function is useful in a situation like the following:
Imagine an extremely simple "garbage collected" system.


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


    

  1. 

    Use gtk_widget_set_sensitive() or modal dialogs to prevent
the user from interacting with elements while the main
loop is recursing.
    

    2. 

  2. 

    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.
    

    3. 




  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    The main loop recursion level in the current thread
    

    
      
    
    • 
  







    
      

  

  
    #malloc(n_bytes)  ⇒ GObject 
  

  

  


  

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


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



  





  
Parameters:


    
  
    
  • 
      
        n_bytes
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to allocate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #malloc0(n_bytes)  ⇒ GObject 
  

  

  


  

    
Allocates n_bytes bytes of memory, initialized to 0's.
If n_bytes is 0 it returns nil.


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



  





  
Parameters:


    
  
    
  • 
      
        n_bytes
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to allocate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #malloc0_n(n_blocks, n_block_bytes)  ⇒ GObject 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        n_blocks
      
      
        (Integer)
      
      
      
        —
        
    the number of blocks to allocate
    

    
      
    
    • 
  
    
  • 
      
        n_block_bytes
      
      
        (Integer)
      
      
      
        —
        
    the size of each block in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #malloc_n(n_blocks, n_block_bytes)  ⇒ GObject 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        n_blocks
      
      
        (Integer)
      
      
      
        —
        
    the number of blocks to allocate
    

    
      
    
    • 
  
    
  • 
      
        n_block_bytes
      
      
        (Integer)
      
      
      
        —
        
    the size of each block in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #markup_collect_attributes(element_name, attribute_names, attribute_values, error, first_type, first_attr, array)  ⇒ Boolean 
  

  

  


  

    
Collects the attributes of the element from the data passed to the
GMarkup::Parser start_element function, dealing with common error
conditions and supporting boolean values.


This utility function is not required to write a parser but can save
a lot of typing.


The element_name, attribute_names, attribute_values and error
parameters passed to the start_element callback should be passed
unmodified to this function.


Following these arguments is a list of "supported" attributes to collect.
It is an error to specify multiple attributes with the same name. If any
attribute not in the list appears in the attribute_names array then an
unknown attribute error will result.


The GMarkup::CollectType field allows specifying the type of collection
to perform and if a given attribute must appear or is optional.


The attribute name is simply the name of the attribute to collect.


The pointer should be of the appropriate type (see the descriptions
under GMarkup::CollectType) and may be nil in case a particular
attribute is to be allowed but ignored.


This function deals with issuing errors for missing attributes
(of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes
(of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate
attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well
as parse errors for boolean-valued attributes (again of type
%G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases false
will be returned and error will be set as appropriate.



  





  
Parameters:


    
  
    
  • 
      
        element_name
      
      
        (String)
      
      
      
        —
        
    the current tag name
    

    
      
    
    • 
  
    
  • 
      
        attribute_names
      
      
        (String)
      
      
      
        —
        
    the attribute names
    

    
      
    
    • 
  
    
  • 
      
        attribute_values
      
      
        (String)
      
      
      
        —
        
    the attribute values
    

    
      
    
    • 
  
    
  • 
      
        error
      
      
        (GLib::Error)
      
      
      
        —
        
    a pointer to a #GError or nil
    

    
      
    
    • 
  
    
  • 
      
        first_type
      
      
        (GLib::MarkupCollectType)
      
      
      
        —
        
    the GMarkup::CollectType of the first attribute
    

    
      
    
    • 
  
    
  • 
      
        first_attr
      
      
        (String)
      
      
      
        —
        
    the name of the first attribute
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    a pointer to the storage location of the first attribute
(or nil), followed by more types names and pointers, ending
with %G_MARKUP_COLLECT_INVALID
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if successful
    

    
      
    
    • 
  







    
      

  

  
    #markup_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #markup_escape_text(text, length)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        text
      
      
        (String)
      
      
      
        —
        
    some valid UTF-8 text
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of text in bytes, or -1 if the text is nul-terminated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string with the escaped text
    

    
      
    
    • 
  







    
      

  

  
    #markup_printf_escaped(format, array)  ⇒ String 
  

  

  


  

    
Formats arguments according to format, escaping
all string and character arguments in the fashion
of g_markup_escape_text(). This is useful when you
want to insert literal strings into XML-style markup
output, without having to worry that the strings
might themselves contain markup.


const char *store = "Fortnum & Mason";
const char *item = "Tea";
char *output;

output = g_markup_printf_escaped ("<purchase>"
                                  "<store>%s</store>"
                                  "<item>%s</item>"
                                  "</purchase>",
                                  store, item);




  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    printf() style format string
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the arguments to insert in the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    newly allocated result from formatting
operation. Free with g_free().
    

    
      
    
    • 
  







    
      

  

  
    #markup_vprintf_escaped(format, args)  ⇒ String 
  

  

  


  

    
Formats the data in args according to format, escaping
all string and character arguments in the fashion
of g_markup_escape_text(). See g_markup_printf_escaped().



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    printf() style format string
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    variable argument list, similar to vprintf()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    newly allocated result from formatting
operation. Free with g_free().
    

    
      
    
    • 
  







    
      

  

  
    #mem_chunk_info  ⇒ nil 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #mem_is_system_malloc  ⇒ Boolean 
  

  

  


  

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



  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    if true, malloc() and g_malloc() can be mixed.
    

    
      
    
    • 
  







    
      

  

  
    #mem_profile  ⇒ nil 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #mem_set_vtable(vtable)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        vtable
      
      
        (GLib::MemVTable)
      
      
      
        —
        
    table of memory allocation routines.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #memdup(mem, byte_size)  ⇒ GObject 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    the memory to copy
    

    
      
    
    • 
  
    
  • 
      
        byte_size
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to copy
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the newly-allocated copy of the memory
    

    
      
    
    • 
  







    
      

  

  
    #memdup2(mem, byte_size)  ⇒ GObject 
  

  

  


  

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


This replaces [funcGLib.memdup], which was prone to integer overflows when
converting the argument from a gsize to a guint.



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    the memory to copy
    

    
      
    
    • 
  
    
  • 
      
        byte_size
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to copy
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the newly-allocated copy of the memory
    

    
      
    
    • 
  







    
      

  

  
    #mkdir(filename, mode)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX mkdir() function. The mkdir() function
attempts to create a directory with the given name and permissions.
The mode argument is ignored on Windows.


See your C library manual for more details about mkdir().



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (Integer)
      
      
      
        —
        
    permissions to use for the newly created directory
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the directory was successfully created, -1 if an error
occurred
    

    
      
    
    • 
  







    
      

  

  
    #mkdir_with_parents(pathname, mode)  ⇒ Integer 
  

  

  


  

    
Create a directory if it doesn't already exist. Create intermediate
parent directories as needed, too.
created. Returns -1 if an error occurred, with errno set.



  





  
Parameters:


    
  
    
  • 
      
        pathname
      
      
        (GLib::filename)
      
      
      
        —
        
    a pathname in the GLib file name encoding
    

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (Integer)
      
      
      
        —
        
    permissions to use for newly created directories
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the directory already exists, or was successfully
    

    
      
    
    • 
  







    
      

  

  
    #mkdtemp(tmpl)  ⇒ GLib::filename 
  

  

  


  

    
Creates a temporary directory. See the mkdtemp() documentation
on most UNIX-like systems.


The parameter is a string that should follow the rules for
mkdtemp() templates, i.e. contain the string "XXXXXX".
g_mkdtemp() is slightly more flexible than mkdtemp() in that the
sequence does not have to occur at the very end of the template.
The X string will be modified to form the name of a directory that
didn't exist.
The string should be in the GLib file name encoding. Most importantly,
on Windows it should be in UTF-8.


If you are going to be creating a temporary directory inside the
directory returned by g_get_tmp_dir(), you might want to use
g_dir_make_tmp() instead.



  





  
Parameters:


    
  
    
  • 
      
        tmpl
      
      
        (GLib::filename)
      
      
      
        —
        
    template directory name
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    A pointer to tmpl, which has been
modified to hold the directory name.  In case of errors, nil is
returned and %errno will be set.
    

    
      
    
    • 
  







    
      

  

  
    #mkdtemp_full(tmpl, mode)  ⇒ GLib::filename 
  

  

  


  

    
Creates a temporary directory. See the mkdtemp() documentation
on most UNIX-like systems.


The parameter is a string that should follow the rules for
mkdtemp() templates, i.e. contain the string "XXXXXX".
g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the
sequence does not have to occur at the very end of the template
and you can pass a mode. The X string will be modified to form
the name of a directory that didn't exist. The string should be
in the GLib file name encoding. Most importantly, on Windows it
should be in UTF-8.


If you are going to be creating a temporary directory inside the
directory returned by g_get_tmp_dir(), you might want to use
g_dir_make_tmp() instead.



  





  
Parameters:


    
  
    
  • 
      
        tmpl
      
      
        (GLib::filename)
      
      
      
        —
        
    template directory name
    

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (Integer)
      
      
      
        —
        
    permissions to create the temporary directory with
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    A pointer to tmpl, which has been
modified to hold the directory name. In case of errors, nil is
returned, and %errno will be set.
    

    
      
    
    • 
  







    
      

  

  
    #mkstemp(tmpl)  ⇒ Integer 
  

  

  


  

    
Opens a temporary file. See the mkstemp() documentation
on most UNIX-like systems.


The parameter is a string that should follow the rules for
mkstemp() templates, i.e. contain the string "XXXXXX".
g_mkstemp() is slightly more flexible than mkstemp() in that the
sequence does not have to occur at the very end of the template.
The X string will be modified to form the name of a file that
didn't exist. The string should be in the GLib file name encoding.
Most importantly, on Windows it should be in UTF-8.



  





  
Parameters:


    
  
    
  • 
      
        tmpl
      
      
        (GLib::filename)
      
      
      
        —
        
    template filename
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    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 %errno will be set.
    

    
      
    
    • 
  







    
      

  

  
    #mkstemp_full(tmpl, flags, mode)  ⇒ Integer 
  

  

  


  

    
Opens a temporary file. See the mkstemp() documentation
on most UNIX-like systems.


The parameter is a string that should follow the rules for
mkstemp() templates, i.e. contain the string "XXXXXX".
g_mkstemp_full() is slightly more flexible than mkstemp()
in that the sequence does not have to occur at the very end of the
template and you can pass a mode and additional flags. The X
string will be modified to form the name of a file that didn't exist.
The string should be in the GLib file name encoding. Most importantly,
on Windows it should be in UTF-8.



  





  
Parameters:


    
  
    
  • 
      
        tmpl
      
      
        (GLib::filename)
      
      
      
        —
        
    template filename
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (Integer)
      
      
      
        —
        
    flags to pass to an open() call in addition to O_EXCL
and O_CREAT, which are passed automatically
    

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (Integer)
      
      
      
        —
        
    permissions to create the temporary file with
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    A file handle (as from open()) to the file
opened for reading and writing. The file handle should be
closed with close(). In case of errors, -1 is returned
and %errno will be set.
    

    
      
    
    • 
  







    
      

  

  
    #monotonic_time  ⇒ Integer 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the monotonic time, in microseconds
    

    
      
    
    • 
  







    
      

  

  
    #mutex_new  ⇒ GLib::Mutex 
  

  

  


  

    
Allocates and initializes a new #GMutex.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Mutex)
      
      
      
        —
        
    a newly allocated #GMutex. Use g_mutex_free() to free
    

    
      
    
    • 
  







    
      

  

  
    #node_pop_allocator  ⇒ nil 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #node_push_allocator(allocator)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        allocator
      
      
        (GLib::Allocator)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #nullify_pointer(nullify_location)  ⇒ nil 
  

  

  


  

    
Set the pointer at the specified location to nil.



  





  
Parameters:


    
  
    
  • 
      
        nullify_location
      
      
        (GObject)
      
      
      
        —
        
    the memory address of the pointer.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #num_processors  ⇒ Integer 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    Number of schedulable threads, always greater than 0
    

    
      
    
    • 
  







    
      

  

  
    #number_parser_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #on_error_query(prg_name)  ⇒ nil 
  

  

  


  

    
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, g_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 g_on_error_stack_trace() instead.



  





  
Parameters:


    
  
    
  • 
      
        prg_name
      
      
        (String)
      
      
      
        —
        
    the program name, needed by gdb for the "[S]tack trace"
option. If prg_name is nil, g_get_prgname() is called to get
the program name (which will work correctly if gdk_init() or
gtk_init() has been called)
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #on_error_stack_trace(prg_name)  ⇒ nil 
  

  

  


  

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


This function may cause different actions on non-UNIX platforms.


When running on Windows, this function is not called by
g_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).



  





  
Parameters:


    
  
    
  • 
      
        prg_name
      
      
        (String)
      
      
      
        —
        
    the program name, needed by gdb for the "[S]tack trace"
option
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #once_init_enter(location)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        location
      
      
        (GObject)
      
      
      
        —
        
    location of a static initializable variable
containing 0
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the initialization section should be entered,
false and blocks otherwise
    

    
      
    
    • 
  







    
      

  

  
    #once_init_enter_impl(location)  ⇒ Boolean 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        location
      
      
        (Integer)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
    
    • 
  







    
      

  

  
    #once_init_enter_pointer(location)  ⇒ Boolean 
  

  

  


  

    
This functions behaves in the same way as g_once_init_enter(), but can
can be used to initialize pointers (or #guintptr) instead of #gsize.


  static MyStruct *interesting_struct = NULL;

  if (g_once_init_enter_pointer (&interesting_struct))
    {
      MyStruct *setup_value = allocate_my_struct (); // initialization code here

      g_once_init_leave_pointer (&interesting_struct, g_steal_pointer (&setup_value));
    }

  // use interesting_struct here




  





  
Parameters:


    
  
    
  • 
      
        location
      
      
        (GObject)
      
      
      
        —
        
    location of a static initializable variable
containing NULL
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the initialization section should be entered,
false and blocks otherwise
    

    
      
    
    • 
  







    
      

  

  
    #once_init_leave(location, result)  ⇒ nil 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        location
      
      
        (GObject)
      
      
      
        —
        
    location of a static initializable variable
containing 0
    

    
      
    
    • 
  
    
  • 
      
        result
      
      
        (Integer)
      
      
      
        —
        
    new non-0 value for *value_location
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #once_init_leave_pointer(location, result)  ⇒ nil 
  

  

  


  

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


This functions behaves in the same way as g_once_init_leave(), but
can be used to initialize pointers (or #guintptr) instead of #gsize.



  





  
Parameters:


    
  
    
  • 
      
        location
      
      
        (GObject)
      
      
      
        —
        
    location of a static initializable variable
containing NULL
    

    
      
    
    • 
  
    
  • 
      
        result
      
      
        (GObject)
      
      
      
        —
        
    new non-NULL value for *location
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #open(filename, flags, mode)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX open() function. The open() function is
used to convert a pathname into a file descriptor.


On POSIX systems file descriptors are implemented by the operating
system. On Windows, it's the C library that implements open() and
file descriptors. The actual Win32 API for opening files is quite
different, see MSDN documentation for CreateFile(). The Win32 API
uses file handles, which are more randomish integers, not small
integers like file descriptors.


Because file descriptors are specific to the C library on Windows,
the file descriptor returned by this function makes sense only to
functions in the same C library. Thus if the GLib-using code uses a
different C library than GLib does, the file descriptor returned by
this function cannot be passed to C library functions like write()
or read().


See your C library manual for more details about open().



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (Integer)
      
      
      
        —
        
    as in open()
    

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (Integer)
      
      
      
        —
        
    as in open()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a new file descriptor, or -1 if an error occurred.
The return value can be used exactly like the return value
from open().
    

    
      
    
    • 
  







    
      

  

  
    #option_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #parse_debug_string(string, keys, nkeys)  ⇒ Integer 
  

  

  


  

    
Parses a string containing debugging options
into a %guint 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.
commas, or nil.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a list of debug options separated by colons, spaces, or
    

    
      
    
    • 
  
    
  • 
      
        keys
      
      
        (Array<GLib::DebugKey>)
      
      
      
        —
        
    pointer to an array of GDebug::Key which associate
strings with bit flags.
    

    
      
    
    • 
  
    
  • 
      
        nkeys
      
      
        (Integer)
      
      
      
        —
        
    the number of GDebug::Keys in the array.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the combined set of bit flags.
    

    
      
    
    • 
  







    
      

  

  
    #path_buf_equal(v1, v2)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        v1
      
      
        (GObject)
      
      
      
        —
        
    a path buffer to compare
    

    
      
    
    • 
  
    
  • 
      
        v2
      
      
        (GObject)
      
      
      
        —
        
    a path buffer to compare
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    TRUE if the two path buffers are equal,
and FALSE otherwise
    

    
      
    
    • 
  







    
      

  

  
    #path_get_basename(file_name)  ⇒ GLib::filename 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        file_name
      
      
        (GLib::filename)
      
      
      
        —
        
    the name of the file
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a newly allocated string
containing the last component of the filename
    

    
      
    
    • 
  







    
      

  

  
    #path_get_dirname(file_name)  ⇒ GLib::filename 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        file_name
      
      
        (GLib::filename)
      
      
      
        —
        
    the name of the file
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the directory components of the file
    

    
      
    
    • 
  







    
      

  

  
    #path_is_absolute(file_name)  ⇒ Boolean 
  

  

  


  

    
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 g_get_current_dir()
either. Such paths should be avoided, or need to be handled using
Windows-specific code.



  





  
Parameters:


    
  
    
  • 
      
        file_name
      
      
        (GLib::filename)
      
      
      
        —
        
    a file name
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if file_name is absolute
    

    
      
    
    • 
  







    
      

  

  
    #path_skip_root(file_name)  ⇒ GLib::filename 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        file_name
      
      
        (GLib::filename)
      
      
      
        —
        
    a file name
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a pointer into file_name after the
root component
    

    
      
    
    • 
  







    
      

  

  
    #pattern_match(pspec, string_length, string, string_reversed)  ⇒ Boolean 
  

  

  


  

    
Matches a string against a compiled pattern. Passing the correct
length of the string given is mandatory. The reversed string can be
omitted by passing nil, this is more efficient if the reversed
version of the string to be matched is not at hand, as
g_pattern_match() will only construct it if the compiled pattern
requires reverse matches.


Note that, if the user code will (possibly) match a string against a
multitude of patterns containing wildcards, chances are high that
some patterns will require a reversed string. In this case, it's
more efficient to provide the reversed string to avoid multiple
constructions thereof in the various calls to g_pattern_match().


Note also that the reverse of a UTF-8 encoded string can in general
not be obtained by g_strreverse(). This works only if the string
does not contain any multibyte characters. GLib offers the
g_utf8_strreverse() function to reverse UTF-8 encoded strings.



  





  
Parameters:


    
  
    
  • 
      
        pspec
      
      
        (GLib::PatternSpec)
      
      
      
        —
        
    a GPattern::Spec
    

    
      
    
    • 
  
    
  • 
      
        string_length
      
      
        (Integer)
      
      
      
        —
        
    the length of string (in bytes, i.e. strlen(),
not g_utf8_strlen())
    

    
      
    
    • 
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the UTF-8 encoded string to match
    

    
      
    
    • 
  
    
  • 
      
        string_reversed
      
      
        (String)
      
      
      
        —
        
    the reverse of string or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if string matches pspec
    

    
      
    
    • 
  







    
      

  

  
    #pattern_match_simple(pattern, string)  ⇒ Boolean 
  

  

  


  

    
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 g_pattern_spec_new() and call
g_pattern_match_string() repeatedly.



  





  
Parameters:


    
  
    
  • 
      
        pattern
      
      
        (String)
      
      
      
        —
        
    the UTF-8 encoded pattern
    

    
      
    
    • 
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the UTF-8 encoded string to match
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if string matches pspec
    

    
      
    
    • 
  







    
      

  

  
    #pattern_match_string(pspec, string)  ⇒ Boolean 
  

  

  


  

    
Matches a string against a compiled pattern. If the string is to be
matched against more than one pattern, consider using
g_pattern_match() instead while supplying the reversed string.



  





  
Parameters:


    
  
    
  • 
      
        pspec
      
      
        (GLib::PatternSpec)
      
      
      
        —
        
    a GPattern::Spec
    

    
      
    
    • 
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the UTF-8 encoded string to match
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if string matches pspec
    

    
      
    
    • 
  







    
      

  

  
    #pointer_bit_lock(address, lock_bit)  ⇒ nil 
  

  

  


  

    
This is equivalent to g_bit_lock, but working on pointers (or other
pointer-sized values).


For portability reasons, you may only lock on the bottom 32 bits of
the pointer.


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



  





  
Parameters:


    
  
    
  • 
      
        address
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    a bit value between 0 and 31
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #pointer_bit_lock_and_get(address, lock_bit, out_ptr)  ⇒ nil 
  

  

  


  

    
This is equivalent to g_bit_lock, but working on pointers (or other
pointer-sized values).


For portability reasons, you may only lock on the bottom 32 bits of
the pointer.



  





  
Parameters:


    
  
    
  • 
      
        address
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    a bit value between 0 and 31
    

    
      
    
    • 
  
    
  • 
      
        out_ptr
      
      
        (Integer)
      
      
      
        —
        
    returns the set pointer atomically.
This is the value after setting the lock, it thus always has the
lock bit set, while previously address had the lockbit unset.
You may also use g_pointer_bit_lock_mask_ptr() to clear the lock bit.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #pointer_bit_lock_mask_ptr(ptr, lock_bit, set, preserve_mask, preserve_ptr)  ⇒ GObject 
  

  

  


  

    
This mangles ptr as g_pointer_bit_lock() and g_pointer_bit_unlock()
do.



  





  
Parameters:


    
  
    
  • 
      
        ptr
      
      
        (GObject)
      
      
      
        —
        
    the pointer to mask
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    the bit to set/clear. If set to G_MAXUINT, the
lockbit is taken from preserve_ptr or ptr (depending on preserve_mask).
    

    
      
    
    • 
  
    
  • 
      
        set
      
      
        (Boolean)
      
      
      
        —
        
    whether to set (lock) the bit or unset (unlock). This
has no effect, if lock_bit is set to G_MAXUINT.
    

    
      
    
    • 
  
    
  • 
      
        preserve_mask
      
      
        (Integer)
      
      
      
        —
        
    if non-zero, a bit-mask for preserve_ptr. The
preserve_mask bits from preserve_ptr are set in the result.
Note that the lock_bit bit will be always set according to set,
regardless of preserve_mask and preserve_ptr (unless lock_bit is
G_MAXUINT).
    

    
      
    
    • 
  
    
  • 
      
        preserve_ptr
      
      
        (GObject)
      
      
      
        —
        
    if preserve_mask is non-zero, the bits
from this pointer are set in the result.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the mangled pointer.
    

    
      
    
    • 
  







    
      

  

  
    #pointer_bit_trylock(address, lock_bit)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        address
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    a bit value between 0 and 31
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the lock was acquired
    

    
      
    
    • 
  







    
      

  

  
    #pointer_bit_unlock(address, lock_bit)  ⇒ nil 
  

  

  


  

    
This is equivalent to g_bit_unlock, but working on pointers (or other
pointer-sized values).


For portability reasons, you may only lock on the bottom 32 bits of
the pointer.


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



  





  
Parameters:


    
  
    
  • 
      
        address
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    a bit value between 0 and 31
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #pointer_bit_unlock_and_set(address, lock_bit, ptr, preserve_mask)  ⇒ nil 
  

  

  


  

    
This is equivalent to g_pointer_bit_unlock() and atomically setting
the pointer value.


Note that the lock bit will be cleared from the pointer. If the unlocked
pointer that was set is not identical to ptr, an assertion fails. In other
words, ptr must have lock_bit unset. This also means, you usually can
only use this on the lowest bits.



  





  
Parameters:


    
  
    
  • 
      
        address
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a #gpointer-sized value
    

    
      
    
    • 
  
    
  • 
      
        lock_bit
      
      
        (Integer)
      
      
      
        —
        
    a bit value between 0 and 31
    

    
      
    
    • 
  
    
  • 
      
        ptr
      
      
        (GObject)
      
      
      
        —
        
    the new pointer value to set
    

    
      
    
    • 
  
    
  • 
      
        preserve_mask
      
      
        (Integer)
      
      
      
        —
        
    if non-zero, those bits of the current pointer in address
are preserved.
Note that the lock_bit bit will be always set according to set,
regardless of preserve_mask and the currently set value in address.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #poll(fds, nfds, timeout)  ⇒ Integer 
  

  

  


  

    
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 GMain::Context, 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 GPoll::FD 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 g_poll() in code that has to run on
Windows, the easiest solution is to construct all of your
GPoll::FDs with g_io_channel_win32_make_pollfd().
were filled in, or 0 if the operation timed out, or -1 on error or
if the call was interrupted.



  





  
Parameters:


    
  
    
  • 
      
        fds
      
      
        (GLib::PollFD)
      
      
      
        —
        
    file descriptors to poll
    

    
      
    
    • 
  
    
  • 
      
        nfds
      
      
        (Integer)
      
      
      
        —
        
    the number of file descriptors in fds
    

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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of entries in fds whose revents fields
    

    
      
    
    • 
  







    
      

  

  
    #prefix_error(err, format, array)  ⇒ nil 
  

  

  


  

    
Formats a string according to format and prefix it to an existing
error message. If err is nil (ie: no error variable) then do
nothing.


If *err is nil (ie: an error variable is present but there is no
error condition) then also do nothing.



  





  
Parameters:


    
  
    
  • 
      
        err
      
      
        (GLib::Error)
      
      
      
        —
        
    a return location for a #GError
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    printf()-style format string
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    arguments to format
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #prefix_error_literal(err, prefix)  ⇒ nil 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        err
      
      
        (GLib::Error)
      
      
      
        —
        
    a return location for a #GError, or nil
    

    
      
    
    • 
  
    
  • 
      
        prefix
      
      
        (String)
      
      
      
        —
        
    string to prefix err with
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #prgname  ⇒ String 
  

  

  


  

    
Gets the name of the program. This name should not be localized,
in contrast to g_get_application_name().


If you are using #GApplication the program name is set in
g_application_run(). In case of GDK or GTK it is set in
gdk_init(), which is called by gtk_init() and the
Gtk::Application::startup handler. The program name is found by
taking the last component of argv[0].



  





  

Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the name of the program,
or nil if it has not been set yet. The returned string belongs
to GLib and must not be modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #prgname=(prgname)  ⇒ nil 
  

  

  


  

    
Sets the name of the program. This name should not be localized,
in contrast to g_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
Gtk::Application::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.



  





  
Parameters:


    
  
    
  • 
      
        prgname
      
      
        (String)
      
      
      
        —
        
    the name of the program.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #print(format, array)  ⇒ nil 
  

  

  


  

    
Outputs a formatted message via the print handler.


The default print handler outputs the encoded message to stdout, without
appending a trailing new-line character. Typically, format should end with
its own new-line character.


This function should not be used from within libraries for debugging
messages, since it may be redirected by applications to special
purpose message windows or even files. Instead, libraries should
use [funcGLib.log], [funcGLib.log_structured], or the convenience macros
[funcGLib.message], [funcGLib.warning] and [funcGLib.error].



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the message format. See the printf() documentation
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the parameters to insert into the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #print_handler=(func)  ⇒ GLib::PrintFunc 
  

  

  


  

    
Sets the print handler to func, or resets it to the
default GLib handler if NULL.


Any messages passed to [funcGLib.print] will be output via
the new handler. The default handler outputs
the encoded message to stdout. By providing your own handler
you can redirect the output, to a GTK widget or a
log file for example.


Since 2.76 this functions always returns a valid
[typeGLib.PrintFunc], and never returns NULL. If no custom
print handler was set, it will return the GLib
default print handler and that can be re-used to
decorate its output and/or to write to stderr
in all platforms. Before GLib 2.76, this was NULL.



  





  
Parameters:


    
  
    
  • 
      
        func
      
      
        (GLib::PrintFunc)
      
      
      
        —
        
    the new print handler or NULL to
reset to the default
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::PrintFunc)
      
      
      
        —
        
    the old print handler
    

    
      
    
    • 
  







    
      

  

  
    #printerr(format, array)  ⇒ nil 
  

  

  


  

    
Outputs a formatted message via the error message handler.


The default handler outputs the encoded message to stderr, without appending
a trailing new-line character. Typically, format should end with its own
new-line character.


This function should not be used from within libraries.
Instead [funcGLib.log] or [funcGLib.log_structured] should be used, or the convenience
macros [funcGLib.message], [funcGLib.warning] and [funcGLib.error].



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the message format. See the printf() documentation
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the parameters to insert into the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #printerr_handler=(func)  ⇒ GLib::PrintFunc 
  

  

  


  

    
Sets the handler for printing error messages to func,
or resets it to the default GLib handler if NULL.


Any messages passed to [funcGLib.printerr] will be output via
the new handler. The default handler outputs the encoded
message to stderr. By providing your own handler you can
redirect the output, to a GTK widget or a log file for
example.


Since 2.76 this functions always returns a valid
[typeGLib.PrintFunc], and never returns NULL. If no custom error
print handler was set, it will return the GLib default
error print handler and that can be re-used to decorate
its output and/or to write to stderr in all platforms.
Before GLib 2.76, this was NULL.



  





  
Parameters:


    
  
    
  • 
      
        func
      
      
        (GLib::PrintFunc)
      
      
      
        —
        
    he new error message handler or NULL
to reset to the default
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::PrintFunc)
      
      
      
        —
        
    the old error message handler
    

    
      
    
    • 
  







    
      

  

  
    #printf(format, array)  ⇒ Integer 
  

  

  


  

    
An implementation of the standard printf() function which supports
positional parameters, as specified in the Single Unix Specification.


As with the standard printf(), this does not automatically append a trailing
new-line character to the message, so typically format should end with its
own new-line character.


glib/gprintf.h must be explicitly included in order to use this function.



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes printed
    

    
      
    
    • 
  







    
      

  

  
    #printf_string_upper_bound(format, args)  ⇒ Integer 
  

  

  


  

    
Calculates the maximum space needed to store the output
of the sprintf() function.


If format or args are invalid, 0 is returned. This could happen if, for
example, format contains an %lc or %ls placeholder and args contains a
wide character which cannot be represented in multibyte encoding. 0
can also be returned legitimately if, for example, format is %s and args
is an empty string. The caller is responsible for differentiating these two
return cases if necessary. It is recommended to not use %lc or %ls
placeholders in any case, as their behaviour is locale-dependent.



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the format string. See the printf() documentation
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    the parameters to be inserted into the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the maximum space needed to store the formatted string, or 0 on error
    

    
      
    
    • 
  







    
      

  

  
    #private_new(notify)  ⇒ GLib::Private 
  

  

  


  

    
Creates a new #GPrivate.



  





  
Parameters:


    
  
    
  • 
      
        notify
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    a GDestroy::Notify
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Private)
      
      
      
        —
        
    a newly allocated #GPrivate (which can never be destroyed)
    

    
      
    
    • 
  







    
      

  

  
    #propagate_error(dest, src)  ⇒ nil 
  

  

  


  

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


src must be non-nil.


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



  





  
Parameters:


    
  
    
  • 
      
        dest
      
      
        (GLib::Error)
      
      
      
        —
        
    error return location
    

    
      
    
    • 
  
    
  • 
      
        src
      
      
        (GLib::Error)
      
      
      
        —
        
    error to move into the return location
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #propagate_prefixed_error(dest, src, format, array)  ⇒ nil 
  

  

  


  

    
If dest is nil, free src; otherwise, moves src into *dest.
*dest must be nil. After the move, add a prefix as with
g_prefix_error().



  





  
Parameters:


    
  
    
  • 
      
        dest
      
      
        (GLib::Error)
      
      
      
        —
        
    error return location
    

    
      
    
    • 
  
    
  • 
      
        src
      
      
        (GLib::Error)
      
      
      
        —
        
    error to move into the return location
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    printf()-style format string
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    arguments to format
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #ptr_array_find(haystack, needle, index_)  ⇒ Boolean 
  

  

  


  

    
Checks whether needle exists in haystack. If the element is found, true is
returned and the element’s index is returned in index_ (if non-nil).
Otherwise, false is returned and index_ is undefined. If needle exists
multiple times in haystack, the index of the first instance is returned.


This does pointer comparisons only. If you want to use more complex equality
checks, such as string comparisons, use g_ptr_array_find_with_equal_func().



  





  
Parameters:


    
  
    
  • 
      
        haystack
      
      
        (Array<GObject>)
      
      
      
        —
        
    pointer array to be searched
    

    
      
    
    • 
  
    
  • 
      
        needle
      
      
        (GObject)
      
      
      
        —
        
    pointer to look for
    

    
      
    
    • 
  
    
  • 
      
        index_
      
      
        (Integer)
      
      
      
        —
        
    return location for the index of
the element, if found
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if needle is one of the elements of haystack
    

    
      
    
    • 
  







    
      

  

  
    #ptr_array_find_with_equal_func(haystack, needle, equal_func, index_)  ⇒ Boolean 
  

  

  


  

    
Checks whether needle exists in haystack, using the given equal_func.
If the element is found, true is returned and the element’s index is
returned in index_ (if non-nil). Otherwise, false is returned and index_
is undefined. If needle exists multiple times in haystack, the index of
the first instance is returned.


equal_func is called with the element from the array as its first parameter,
and needle as its second parameter. If equal_func is nil, pointer
equality is used.



  





  
Parameters:


    
  
    
  • 
      
        haystack
      
      
        (Array<GObject>)
      
      
      
        —
        
    pointer array to be searched
    

    
      
    
    • 
  
    
  • 
      
        needle
      
      
        (GObject)
      
      
      
        —
        
    pointer to look for
    

    
      
    
    • 
  
    
  • 
      
        equal_func
      
      
        (GLib::EqualFunc)
      
      
      
        —
        
    the function to call for each element, which should
return true when the desired element is found; or nil to use pointer
equality
    

    
      
    
    • 
  
    
  • 
      
        index_
      
      
        (Integer)
      
      
      
        —
        
    return location for the index of
the element, if found
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if needle is one of the elements of haystack
    

    
      
    
    • 
  







    
      

  

  
    #ptr_array_new_from_array(data, len, copy_func, copy_func_user_data, element_free_func)  ⇒ Array<GObject> 
  

  

  


  

    
Creates a new GPtr::Array, copying len pointers from data, and setting
the array’s reference count to 1.


This avoids having to manually add each element one by one.


If copy_func is provided, then it is used to copy each element before
adding them to the new array. If it is nil then the pointers are copied
directly.


It also sets element_free_func for freeing each element when the array is
destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
with free_segment set to true or when removing elements.


Do not use it if len is greater than %G_MAXUINT. GPtr::Array
stores the length of its data in #guint, which may be shorter than
#gsize.
or nil for an empty array



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (Array<GObject>)
      
      
      
        —
        
    an array of pointers,
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    the number of pointers in data
    

    
      
    
    • 
  
    
  • 
      
        copy_func
      
      
        (GLib::CopyFunc)
      
      
      
        —
        
    a copy function used to copy every element in the
array or nil.
    

    
      
    
    • 
  
    
  • 
      
        copy_func_user_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to copy_func, or nil
    

    
      
    
    • 
  
    
  • 
      
        element_free_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    a function to free elements on array
destruction or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    A new GPtr::Array
    

    
      
    
    • 
  







    
      

  

  
    #ptr_array_new_from_null_terminated_array(data, copy_func, copy_func_user_data, element_free_func)  ⇒ Array<GObject> 
  

  

  


  

    
Creates a new GPtr::Array copying the pointers from data after having
computed the length of it and with a reference count of 1.
This avoids having to manually add each element one by one.
If copy_func is provided, then it is used to copy the data in the new
array.
It also set element_free_func for freeing each element when the array is
destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
with free_segment set to true or when removing elements.


Do not use it if the data has more than %G_MAXUINT elements. GPtr::Array
stores the length of its data in #guint, which may be shorter than
#gsize.



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (Array<GObject>)
      
      
      
        —
        
    an array of
pointers, nil terminated; or nil for an empty array
    

    
      
    
    • 
  
    
  • 
      
        copy_func
      
      
        (GLib::CopyFunc)
      
      
      
        —
        
    a copy function used to copy every element in the
array or nil.
    

    
      
    
    • 
  
    
  • 
      
        copy_func_user_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to copy_func, or nil
    

    
      
    
    • 
  
    
  • 
      
        element_free_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    a function to free elements on array
destruction or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    A new GPtr::Array
    

    
      
    
    • 
  







    
      

  

  
    #ptr_array_new_take(data, len, element_free_func)  ⇒ Array<GObject> 
  

  

  


  

    
Creates a new GPtr::Array with data as pointers, len as length and a
reference count of 1.


This avoids having to copy such data manually.
After this call, data belongs to the GPtr::Array and may no longer be
modified by the caller. The memory of data has to be dynamically
allocated and will eventually be freed with g_free().


It also sets element_free_func for freeing each element when the array is
destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
with free_segment set to true or when removing elements.


Do not use it if len is greater than %G_MAXUINT. GPtr::Array
stores the length of its data in #guint, which may be shorter than
#gsize.



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (Array<GObject>)
      
      
      
        —
        
    an array of pointers,
or nil for an empty array
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    the number of pointers in data
    

    
      
    
    • 
  
    
  • 
      
        element_free_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    A function to free elements on array
destruction or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    A new GPtr::Array
    

    
      
    
    • 
  







    
      

  

  
    #ptr_array_new_take_null_terminated(data, element_free_func)  ⇒ Array<GObject> 
  

  

  


  

    
Creates a new GPtr::Array with data as pointers, computing the length of it
and setting the reference count to 1.


This avoids having to copy such data manually.
After this call, data belongs to the GPtr::Array and may no longer be
modified by the caller. The memory of data has to be dynamically
allocated and will eventually be freed with g_free().


The length is calculated by iterating through data until the first nil
element is found.


It also sets element_free_func for freeing each element when the array is
destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
with free_segment set to true or when removing elements.


Do not use it if the data length is greater than %G_MAXUINT. GPtr::Array
stores the length of its data in #guint, which may be shorter than
#gsize.



  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (Array<GObject>)
      
      
      
        —
        
    an array
of pointers, nil terminated, or nil for an empty array
    

    
      
    
    • 
  
    
  • 
      
        element_free_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    a function to free elements on array
destruction or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<GObject>)
      
      
      
        —
        
    A new GPtr::Array
    

    
      
    
    • 
  







    
      

  

  
    #qsort_with_data(pbase, total_elems, size, compare_func, user_data)  ⇒ nil 
  

  

  


  

    
This is just like the standard C qsort() function, but
the comparison routine accepts a user data argument.


This is guaranteed to be a stable sort since version 2.32.



  





  
Parameters:


    
  
    
  • 
      
        pbase
      
      
        (GObject)
      
      
      
        —
        
    start of array to sort
    

    
      
    
    • 
  
    
  • 
      
        total_elems
      
      
        (Integer)
      
      
      
        —
        
    elements in the array
    

    
      
    
    • 
  
    
  • 
      
        size
      
      
        (Integer)
      
      
      
        —
        
    size of each element
    

    
      
    
    • 
  
    
  • 
      
        compare_func
      
      
        (GLib::CompareDataFunc)
      
      
      
        —
        
    function to compare elements
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to compare_func
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #quark_from_static_string(string)  ⇒ GLib::Quark 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark identifying the string, or 0 if string is nil
    

    
      
    
    • 
  







    
      

  

  
    #quark_from_string(string)  ⇒ GLib::Quark 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark identifying the string, or 0 if string is nil
    

    
      
    
    • 
  







    
      

  

  
    #quark_to_string(quark)  ⇒ String 
  

  

  


  

    
Gets the string associated with the given #GQuark.



  





  
Parameters:


    
  
    
  • 
      
        quark
      
      
        (GLib::Quark)
      
      
      
        —
        
    a #GQuark.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the string associated with the #GQuark
    

    
      
    
    • 
  







    
      

  

  
    #quark_try_string(string)  ⇒ GLib::Quark 
  

  

  


  

    
Gets the #GQuark associated with the given string, or 0 if string is
nil or it has no associated #GQuark.


If you want the GQuark to be created if it doesn't already exist,
use g_quark_from_string() or g_quark_from_static_string().


This function must not be used before library constructors have finished
running.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
        —
        
    the #GQuark associated with the string, or 0 if string is
nil or there is no #GQuark associated with it
    

    
      
    
    • 
  







    
      

  

  
    #random_double  ⇒ Float 
  

  

  


  

    
Returns a random #gdouble equally distributed over the range [0..1).



  





  

Returns:


    
  
    
  • 
      
      
        (Float)
      
      
      
        —
        
    a random number
    

    
      
    
    • 
  







    
      

  

  
    #random_double_range(begin, end)  ⇒ Float 
  

  

  


  

    
Returns a random #gdouble equally distributed over the range
[begin..end).



  





  
Parameters:


    
  
    
  • 
      
        begin
      
      
        (Float)
      
      
      
        —
        
    lower closed bound of the interval
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (Float)
      
      
      
        —
        
    upper open bound of the interval
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Float)
      
      
      
        —
        
    a random number
    

    
      
    
    • 
  







    
      

  

  
    #random_int  ⇒ Integer 
  

  

  


  

    
Return a random #guint32 equally distributed over the range
[0..2^32-1].



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a random number
    

    
      
    
    • 
  







    
      

  

  
    #random_int_range(begin, end)  ⇒ Integer 
  

  

  


  

    
Returns a random #gint32 equally distributed over the range
[begin..end-1].



  





  
Parameters:


    
  
    
  • 
      
        begin
      
      
        (Integer)
      
      
      
        —
        
    lower closed bound of the interval
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (Integer)
      
      
      
        —
        
    upper open bound of the interval
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a random number
    

    
      
    
    • 
  







    
      

  

  
    #random_set_seed(seed)  ⇒ nil 
  

  

  


  

    
Sets the seed for the global random number generator, which is used
by the g_random_* functions, to seed.



  





  
Parameters:


    
  
    
  • 
      
        seed
      
      
        (Integer)
      
      
      
        —
        
    a value to reinitialize the global random number generator
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #rc_box_acquire(mem_block)  ⇒ GObject 
  

  

  


  

    
Acquires a reference on the data pointed by mem_block.



  





  
Parameters:


    
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to reference counted data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the data,
with its reference count increased
    

    
      
    
    • 
  







    
      

  

  
    #rc_box_alloc(block_size)  ⇒ GObject 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the size of the allocation, must be greater than 0
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #rc_box_alloc0(block_size)  ⇒ GObject 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the size of the allocation, must be greater than 0
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #rc_box_dup(block_size, mem_block)  ⇒ GObject 
  

  

  


  

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



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    the memory to copy
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated
memory
    

    
      
    
    • 
  







    
      

  

  
    #rc_box_get_size(mem_block)  ⇒ Integer 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to reference counted data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the size of the data, in bytes
    

    
      
    
    • 
  







    
      

  

  
    #rc_box_release(mem_block)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to reference counted data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #rc_box_release_full(mem_block, clear_func)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to reference counted data
    

    
      
    
    • 
  
    
  • 
      
        clear_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    a function to call when clearing the data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #real_name  ⇒ GLib::filename 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the user's real name.
    

    
      
    
    • 
  







    
      

  

  
    #real_time  ⇒ Integer 
  

  

  


  

    
Queries the system wall-clock time.


This call is functionally equivalent to g_get_current_time() except
that the return value is often more convenient than dealing with a
GTime::Val.


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



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of microseconds since January 1, 1970 UTC.
    

    
      
    
    • 
  







    
      

  

  
    #realloc(mem, n_bytes)  ⇒ GObject 
  

  

  


  

    
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 nil, in which case it's considered to
have zero-length. n_bytes may be 0, in which case nil will be returned
and mem will be freed unless it is nil.


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



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    the memory to reallocate
    

    
      
    
    • 
  
    
  • 
      
        n_bytes
      
      
        (Integer)
      
      
      
        —
        
    new size of the memory in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the new address of the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #realloc_n(mem, n_blocks, n_block_bytes)  ⇒ GObject 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    the memory to reallocate
    

    
      
    
    • 
  
    
  • 
      
        n_blocks
      
      
        (Integer)
      
      
      
        —
        
    the number of blocks to allocate
    

    
      
    
    • 
  
    
  • 
      
        n_block_bytes
      
      
        (Integer)
      
      
      
        —
        
    the size of each block in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the new address of the allocated memory
    

    
      
    
    • 
  







    
      

  

  
    #ref_count_compare(rc, val)  ⇒ Boolean 
  

  

  


  

    
Compares the current value of rc with val.



  





  
Parameters:


    
  
    
  • 
      
        rc
      
      
        (Integer)
      
      
      
        —
        
    the address of a reference count variable
    

    
      
    
    • 
  
    
  • 
      
        val
      
      
        (Integer)
      
      
      
        —
        
    the value to compare
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the reference count is the same
as the given value
    

    
      
    
    • 
  







    
      

  

  
    #ref_count_dec(rc)  ⇒ Boolean 
  

  

  


  

    
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
g_ref_count_init() to be used again.



  





  
Parameters:


    
  
    
  • 
      
        rc
      
      
        (Integer)
      
      
      
        —
        
    the address of a reference count variable
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the reference count reached 0, and false otherwise
    

    
      
    
    • 
  







    
      

  

  
    #ref_count_inc(rc)  ⇒ nil 
  

  

  


  

    
Increases the reference count.



  





  
Parameters:


    
  
    
  • 
      
        rc
      
      
        (Integer)
      
      
      
        —
        
    the address of a reference count variable
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #ref_count_init(rc)  ⇒ nil 
  

  

  


  

    
Initializes a reference count variable to 1.



  





  
Parameters:


    
  
    
  • 
      
        rc
      
      
        (Integer)
      
      
      
        —
        
    the address of a reference count variable
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #ref_string_acquire(str)  ⇒ String 
  

  

  


  

    
Acquires a reference on a string.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a reference counted string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the given string, with its reference count increased
    

    
      
    
    • 
  







    
      

  

  
    #ref_string_length(str)  ⇒ Integer 
  

  

  


  

    
Retrieves the length of str.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a reference counted string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the length of the given string, in bytes
    

    
      
    
    • 
  







    
      

  

  
    #ref_string_new(str)  ⇒ String 
  

  

  


  

    
Creates a new reference counted string and copies the contents of str
into it.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a NUL-terminated string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the newly created reference counted string
    

    
      
    
    • 
  







    
      

  

  
    #ref_string_new_intern(str)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a NUL-terminated string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the newly created reference
counted string, or a new reference to an existing string
    

    
      
    
    • 
  







    
      

  

  
    #ref_string_new_len(str, len)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str to use, or -1 if str is nul-terminated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the newly created reference counted string
    

    
      
    
    • 
  







    
      

  

  
    #ref_string_release(str)  ⇒ nil 
  

  

  


  

    
Releases a reference on a string; if it was the last reference, the
resources allocated by the string are freed as well.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a reference counted string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #regex_check_replacement(replacement, has_references)  ⇒ Boolean 
  

  

  


  

    
Checks whether replacement is a valid replacement string
(see g_regex_replace()), i.e. that all escape sequences in
it are valid.


If has_references is not nil 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 GMatch::Info object.



  





  
Parameters:


    
  
    
  • 
      
        replacement
      
      
        (String)
      
      
      
        —
        
    the replacement string
    

    
      
    
    • 
  
    
  • 
      
        has_references
      
      
        (Boolean)
      
      
      
        —
        
    location to store information about
references in replacement or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    whether replacement is a valid replacement string
    

    
      
    
    • 
  







    
      

  

  
    #regex_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #regex_escape_nul(string, length)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the string to escape
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    the length of string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated escaped string
    

    
      
    
    • 
  







    
      

  

  
    #regex_escape_string(string, length)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the string to escape
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    the length of string, in bytes, or -1 if string is nul-terminated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated escaped string
    

    
      
    
    • 
  







    
      

  

  
    #regex_match_simple(pattern, string, compile_options, match_options)  ⇒ Boolean 
  

  

  


  

    
Scans for a match in string for pattern.


This function is equivalent to g_regex_match() but it does not
require to compile the pattern with g_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
g_regex_new() and then use g_regex_match().



  





  
Parameters:


    
  
    
  • 
      
        pattern
      
      
        (String)
      
      
      
        —
        
    the regular expression
    

    
      
    
    • 
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    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:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the string matched, false otherwise
    

    
      
    
    • 
  







    
      

  

  
    #regex_split_simple(pattern, string, compile_options, match_options)  ⇒ Array<String> 
  

  

  


  

    
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 g_regex_split() but it does
not require to compile the pattern with g_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
g_regex_new() and then use g_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".
it using g_strfreev()



  





  
Parameters:


    
  
    
  • 
      
        pattern
      
      
        (String)
      
      
      
        —
        
    the regular expression
    

    
      
    
    • 
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    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:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings. Free
    

    
      
    
    • 
  







    
      

  

  
    #reload_user_special_dirs_cache  ⇒ nil 
  

  

  


  

    
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.


Due to thread safety issues this may cause leaking of strings
that were previously returned from g_get_user_special_dir()
that can't be freed. We ensure to only leak the data for
the directories that actually changed value though.



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #remove(filename)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX remove() function. The remove() function
deletes a name from the filesystem.


See your C library manual for more details about how remove() works
on your system. On Unix, remove() removes also directories, as it
calls unlink() for files and rmdir() for directories. On Windows,
although remove() in the C library only works for files, this
function tries first remove() and then if that fails rmdir(), and
thus works for both files and directories. Note however, that on
Windows, it is in general not possible to remove a file that is
open to some process, or mapped into memory.


If this function fails on Windows you can't infer too much from the
errno value. rmdir() is tried regardless of what caused remove() to
fail. Any errno value set by remove() will be overwritten by that
set by rmdir().



  





  
Parameters:


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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the file was successfully removed, -1 if an error
occurred
    

    
      
    
    • 
  







    
      

  

  
    #rename(oldfilename, newfilename)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX rename() function. The rename() function
renames a file, moving it between directories if required.


See your C library manual for more details about how rename() works
on your system. It is not possible in general on Windows to rename
a file that is open to some process.



  





  
Parameters:


    
  
    
  • 
      
        oldfilename
      
      
        (GLib::filename)
      
      
      
        —
        
    a pathname in the GLib file name encoding
(UTF-8 on Windows)
    

    
      
    
    • 
  
    
  • 
      
        newfilename
      
      
        (GLib::filename)
      
      
      
        —
        
    a pathname in the GLib file name encoding
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the renaming succeeded, -1 if an error occurred
    

    
      
    
    • 
  







    
      

  

  
    #return_if_fail_warning(log_domain, pretty_function, expression)  ⇒ nil 
  

  

  


  

    
Internal function used to print messages from the public [funcGLib.return_if_fail]
and [funcGLib.return_val_if_fail] macros.



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    log domain
    

    
      
    
    • 
  
    
  • 
      
        pretty_function
      
      
        (String)
      
      
      
        —
        
    function containing the assertion
    

    
      
    
    • 
  
    
  • 
      
        expression
      
      
        (String)
      
      
      
        —
        
    expression which failed
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #rmdir(filename)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:


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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the directory was successfully removed, -1 if an error
occurred
    

    
      
    
    • 
  







    
      

  

  
    #sequence_foreach_range(begin, end, func, user_data)  ⇒ nil 
  

  

  


  

    
Calls func for each item in the range (begin, end) passing
user_data to the function. func must not modify the sequence
itself.



  





  
Parameters:


    
  
    
  • 
      
        begin
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (GLib::Func)
      
      
      
        —
        
    a #GFunc
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to func
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #sequence_get(iter)  ⇒ GObject 
  

  

  


  

    
Returns the data that iter points to.



  





  
Parameters:


    
  
    
  • 
      
        iter
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the data that iter points to
    

    
      
    
    • 
  







    
      

  

  
    #sequence_insert_before(iter, data)  ⇒ GLib::SequenceIter 
  

  

  


  

    
Inserts a new item just before the item pointed to by iter.



  





  
Parameters:


    
  
    
  • 
      
        iter
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    the data for the new item
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    an iterator pointing to the new item
    

    
      
    
    • 
  







    
      

  

  
    #sequence_move(src, dest)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        src
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter pointing to the item to move
    

    
      
    
    • 
  
    
  • 
      
        dest
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter pointing to the position to which
the item is moved
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #sequence_move_range(dest, begin, end)  ⇒ nil 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        dest
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        begin
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #sequence_range_get_midpoint(begin, end)  ⇒ 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.



  





  
Parameters:


    
  
    
  • 
      
        begin
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter pointing somewhere in the
(begin, end) range
    

    
      
    
    • 
  







    
      

  

  
    #sequence_remove(iter)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        iter
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #sequence_remove_range(begin, end)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        begin
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #sequence_set(iter, data)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        iter
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    new data for the item
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #sequence_sort_changed(iter, cmp_func, cmp_data)  ⇒ nil 
  

  

  


  

    
Moves the data pointed to by iter to a new position as indicated by
cmp_func. This
function should be called for items in a sequence already sorted according
to cmp_func whenever some aspect of an item changes so that cmp_func
may return different values for that item.


cmp_func is called with two items of the seq, and cmp_data.
It should return 0 if the items are equal, a negative value if
the first item comes before the second, and a positive value if
the second item comes before the first.



  





  
Parameters:


    
  
    
  • 
      
        iter
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    A GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        cmp_func
      
      
        (GLib::CompareDataFunc)
      
      
      
        —
        
    the function used to compare items in the sequence
    

    
      
    
    • 
  
    
  • 
      
        cmp_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to cmp_func.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #sequence_sort_changed_iter(iter, iter_cmp, cmp_data)  ⇒ nil 
  

  

  


  

    
Like g_sequence_sort_changed(), but uses
a GSequence::IterCompareFunc instead of a #GCompareDataFunc as
the compare function.


iter_cmp is called with two iterators pointing into the #GSequence that
iter points into. It should
return 0 if the iterators are equal, a negative value if the first
iterator comes before the second, and a positive value if the second
iterator comes before the first.



  





  
Parameters:


    
  
    
  • 
      
        iter
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        iter_cmp
      
      
        (GLib::SequenceIterCompareFunc)
      
      
      
        —
        
    the function used to compare iterators in the sequence
    

    
      
    
    • 
  
    
  • 
      
        cmp_data
      
      
        (GObject)
      
      
      
        —
        
    user data passed to cmp_func
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #sequence_swap(a, b)  ⇒ nil 
  

  

  


  

    
Swaps the items pointed to by a and b. It is allowed for a and b
to point into difference sequences.



  





  
Parameters:


    
  
    
  • 
      
        a
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  
    
  • 
      
        b
      
      
        (GLib::SequenceIter)
      
      
      
        —
        
    a GSequence::Iter
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #set_error(err, domain, code, format, array)  ⇒ nil 
  

  

  


  

    
Does nothing if err is nil; if err is non-nil, then *err
must be nil. A new #GError is created and assigned to *err.



  





  
Parameters:


    
  
    
  • 
      
        err
      
      
        (GLib::Error)
      
      
      
        —
        
    a return location for a #GError
    

    
      
    
    • 
  
    
  • 
      
        domain
      
      
        (GLib::Quark)
      
      
      
        —
        
    error domain
    

    
      
    
    • 
  
    
  • 
      
        code
      
      
        (Integer)
      
      
      
        —
        
    error code
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    printf()-style format
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    args for format
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #set_error_literal(err, domain, code, message)  ⇒ nil 
  

  

  


  

    
Does nothing if err is nil; if err is non-nil, then *err
must be nil. A new #GError 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.



  





  
Parameters:


    
  
    
  • 
      
        err
      
      
        (GLib::Error)
      
      
      
        —
        
    a return location for a #GError
    

    
      
    
    • 
  
    
  • 
      
        domain
      
      
        (GLib::Quark)
      
      
      
        —
        
    error domain
    

    
      
    
    • 
  
    
  • 
      
        code
      
      
        (Integer)
      
      
      
        —
        
    error code
    

    
      
    
    • 
  
    
  • 
      
        message
      
      
        (String)
      
      
      
        —
        
    error message
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #setenv(variable, value, overwrite)  ⇒ Boolean 
  

  

  


  

    
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 g_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 g_get_environ() to get an environment array, modify that with
g_environ_setenv() and g_environ_unsetenv(), and then pass that
array directly to execvpe(), g_spawn_async(), or the like.



  





  
Parameters:


    
  
    
  • 
      
        variable
      
      
        (GLib::filename)
      
      
      
        —
        
    the environment variable to set, must not
contain '='.
    

    
      
    
    • 
  
    
  • 
      
        value
      
      
        (GLib::filename)
      
      
      
        —
        
    the value for to set the variable to.
    

    
      
    
    • 
  
    
  • 
      
        overwrite
      
      
        (Boolean)
      
      
      
        —
        
    whether to change the variable if it already exists.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    false if the environment variable couldn't be set.
    

    
      
    
    • 
  







    
      

  

  
    #shell_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #shell_parse_argv(command_line, argcp, argvp)  ⇒ Boolean 
  

  

  


  

    
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), %G_SHELL_ERROR_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 g_strfreev().



  





  
Parameters:


    
  
    
  • 
      
        command_line
      
      
        (GLib::filename)
      
      
      
        —
        
    command line to parse
    

    
      
    
    • 
  
    
  • 
      
        argcp
      
      
        (Integer)
      
      
      
        —
        
    return location for number of args
    

    
      
    
    • 
  
    
  • 
      
        argvp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    return location for array of args
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if error set
    

    
      
    
    • 
  







    
      

  

  
    #shell_quote(unquoted_string)  ⇒ GLib::filename 
  

  

  


  

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


The quoting style used is undefined (single or double quotes may be
used).



  





  
Parameters:


    
  
    
  • 
      
        unquoted_string
      
      
        (GLib::filename)
      
      
      
        —
        
    a literal string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    quoted string
    

    
      
    
    • 
  







    
      

  

  
    #shell_unquote(quoted_string)  ⇒ GLib::filename 
  

  

  


  

    
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
g_shell_quote(). If it fails, it returns nil and sets the
error.


The quoted_string need not actually contain quoted or escaped text;
g_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 g_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.



  





  
Parameters:


    
  
    
  • 
      
        quoted_string
      
      
        (GLib::filename)
      
      
      
        —
        
    shell-quoted string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    an unquoted string
    

    
      
    
    • 
  







    
      

  

  
    #slice_alloc(block_size)  ⇒ GObject 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to allocate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory block, which will
be nil if and only if mem_size is 0
    

    
      
    
    • 
  







    
      

  

  
    #slice_alloc0(block_size)  ⇒ GObject 
  

  

  


  

    
Allocates a block of memory via g_slice_alloc() and initializes
the returned memory to 0.


Since GLib 2.76 this always uses the system malloc() implementation
internally.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to allocate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated block, which will be nil
if and only if mem_size is 0
    

    
      
    
    • 
  







    
      

  

  
    #slice_copy(block_size, mem_block)  ⇒ GObject 
  

  

  


  

    
Allocates a block of memory from the slice allocator
and copies block_size bytes into it from mem_block.


mem_block must be non-nil if block_size is non-zero.


Since GLib 2.76 this always uses the system malloc() implementation
internally.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes to allocate
    

    
      
    
    • 
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    the memory to copy
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the allocated memory block,
which will be nil if and only if mem_size is 0
    

    
      
    
    • 
  







    
      

  

  
    #slice_free1(block_size, mem_block)  ⇒ nil 
  

  

  


  

    
Frees a block of memory.


The memory must have been allocated via g_slice_alloc() or
g_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 nil, this function does nothing.


Since GLib 2.76 this always uses the system free_sized() implementation
internally.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the size of the block
    

    
      
    
    • 
  
    
  • 
      
        mem_block
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the block to free
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #slice_free_chain_with_offset(block_size, mem_chain, next_offset)  ⇒ nil 
  

  

  


  

    
Frees a linked list of memory blocks of structure type type.


The memory blocks must be equal-sized, allocated via
g_slice_alloc() or g_slice_alloc0() and linked together by a
next pointer (similar to #GSList). The offset of the next
field in each block is passed as third argument.
Note that the exact release behaviour can be changed with the
[G_DEBUG=gc-friendly][G_DEBUG] environment variable.


If mem_chain is nil, this function does nothing.


Since GLib 2.76 this always uses the system free_sized() implementation
internally.



  





  
Parameters:


    
  
    
  • 
      
        block_size
      
      
        (Integer)
      
      
      
        —
        
    the size of the blocks
    

    
      
    
    • 
  
    
  • 
      
        mem_chain
      
      
        (GObject)
      
      
      
        —
        
    a pointer to the first block of the chain
    

    
      
    
    • 
  
    
  • 
      
        next_offset
      
      
        (Integer)
      
      
      
        —
        
    the offset of the next field in the blocks
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #slice_get_config(ckey)  ⇒ Integer 
  

  

  


  

    

  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
    
    • 
  







    
      

  

  
    #slice_get_config_state(ckey, address, n_values)  ⇒ Integer 
  

  

  


  

    

  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
    
    • 
  







    
      

  

  
    #slice_set_config(ckey, value)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #slist_pop_allocator  ⇒ nil 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #slist_push_allocator(allocator)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        allocator
      
      
        (GLib::Allocator)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #snprintf(string, n, format, array)  ⇒ Integer 
  

  

  


  

    
A safer form of the standard sprintf() function. The output is guaranteed
to not exceed n characters (including the terminating nul character), so
it is easy to ensure that a buffer overflow cannot occur.


See also [funcGLib.strdup_printf].


In versions of GLib prior to 1.2.3, this function may return -1 if the
output was truncated, and the truncated string may not be nul-terminated.
In versions prior to 1.3.12, this function returns the length of the output
string.


The return value of g_snprintf() conforms to the snprintf()
function as standardized in ISO C99. Note that this is different from
traditional snprintf(), which returns the length of the output string.


The format string may contain positional parameters, as specified in
the Single Unix Specification.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the buffer to hold the output
    

    
      
    
    • 
  
    
  • 
      
        n
      
      
        (GLib::gulong)
      
      
      
        —
        
    the maximum number of bytes to produce (including the
terminating nul character)
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes which would be produced if the buffer
was large enough
    

    
      
    
    • 
  







    
      

  

  
    #source_remove(tag)  ⇒ Boolean 
  

  

  


  

    
Removes the source with the given ID from the default main context. You must
use g_source_destroy() for sources added to a non-default main context.


The ID of a #GSource is given by g_source_get_id(), or will be
returned by the functions g_source_attach(), g_idle_add(),
g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
g_io_add_watch_full().


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



  





  
Parameters:


    
  
    
  • 
      
        tag
      
      
        (Integer)
      
      
      
        —
        
    the ID of the source to remove.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the source was found and removed.
    

    
      
    
    • 
  







    
      

  

  
    #source_remove_by_funcs_user_data(funcs, user_data)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        funcs
      
      
        (GLib::SourceFuncs)
      
      
      
        —
        
    The source_funcs passed to g_source_new()
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    the user data for the callback
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if a source was found and removed.
    

    
      
    
    • 
  







    
      

  

  
    #source_remove_by_user_data(user_data)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    the user_data for the callback.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if a source was found and removed.
    

    
      
    
    • 
  







    
      

  

  
    #source_set_name_by_id(tag, name)  ⇒ nil 
  

  

  


  

    
Sets the name of a source using its ID.


This is a convenience utility to set source names from the return
value of g_idle_add(), g_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 g_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.



  





  
Parameters:


    
  
    
  • 
      
        tag
      
      
        (Integer)
      
      
      
        —
        
    a #GSource ID
    

    
      
    
    • 
  
    
  • 
      
        name
      
      
        (String)
      
      
      
        —
        
    debug name for the source
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #spaced_primes_closest(num)  ⇒ Integer 
  

  

  


  

    
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 GHash::Table.


The built-in array of primes ranges from 11 to 13845163 such that
each prime is approximately 1.5-2 times the previous prime.



  





  
Parameters:


    
  
    
  • 
      
        num
      
      
        (Integer)
      
      
      
        —
        
    a #guint
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the smallest prime number from a built-in array of primes
which is larger than num
    

    
      
    
    • 
  







    
      

  

  
    #spawn_async(working_directory, argv, envp, flags, child_setup, user_data, child_pid)  ⇒ Boolean 
  

  

  


  

    
Executes a child program asynchronously.


See g_spawn_async_with_pipes() for a full description; this function
simply calls the g_spawn_async_with_pipes() without any pipes.


You should call g_spawn_close_pid() on the returned child process
reference when you don't need it any more.


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 Gdk::AppLaunchContext,
GApp::LaunchContext, or set the %DISPLAY environment variable.


Note that the returned child_pid on Windows is a handle to the child
process and not its identifier. Process handles and process identifiers
are different concepts on Windows.



  





  
Parameters:


    
  
    
  • 
      
        working_directory
      
      
        (GLib::filename)
      
      
      
        —
        
    child's current working
directory, or nil to inherit parent's
    

    
      
    
    • 
  
    
  • 
      
        argv
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    child's argument vector
    

    
      
    
    • 
  
    
  • 
      
        envp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    child's environment, or nil to inherit parent's
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::SpawnFlags)
      
      
      
        —
        
    flags from GSpawn::Flags
    

    
      
    
    • 
  
    
  • 
      
        child_setup
      
      
        (GLib::SpawnChildSetupFunc)
      
      
      
        —
        
    function to run
in the child just before exec()
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data for child_setup
    

    
      
    
    • 
  
    
  • 
      
        child_pid
      
      
        (GLib::Pid)
      
      
      
        —
        
    return location for child process reference, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if error is set
    

    
      
    
    • 
  







    
      

  

  
    #spawn_async_with_fds(working_directory, argv, envp, flags, child_setup, user_data, child_pid, stdin_fd, stdout_fd, stderr_fd)  ⇒ Boolean 
  

  

  


  

    
Executes a child program asynchronously.


Identical to g_spawn_async_with_pipes_and_fds() but with n_fds set to zero,
so no FD assignments are used.



  





  
Parameters:


    
  
    
  • 
      
        working_directory
      
      
        (GLib::filename)
      
      
      
        —
        
    child's current working directory, or nil to inherit parent's, in the GLib file name encoding
    

    
      
    
    • 
  
    
  • 
      
        argv
      
      
        (Array<String>)
      
      
      
        —
        
    child's argument vector, in the GLib file name encoding;
it must be non-empty and nil-terminated
    

    
      
    
    • 
  
    
  • 
      
        envp
      
      
        (Array<String>)
      
      
      
        —
        
    child's environment, or nil to inherit parent's, in the GLib file name encoding
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::SpawnFlags)
      
      
      
        —
        
    flags from GSpawn::Flags
    

    
      
    
    • 
  
    
  • 
      
        child_setup
      
      
        (GLib::SpawnChildSetupFunc)
      
      
      
        —
        
    function to run
in the child just before exec()
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data for child_setup
    

    
      
    
    • 
  
    
  • 
      
        child_pid
      
      
        (GLib::Pid)
      
      
      
        —
        
    return location for child process ID, or nil
    

    
      
    
    • 
  
    
  • 
      
        stdin_fd
      
      
        (Integer)
      
      
      
        —
        
    file descriptor to use for child's stdin, or -1
    

    
      
    
    • 
  
    
  • 
      
        stdout_fd
      
      
        (Integer)
      
      
      
        —
        
    file descriptor to use for child's stdout, or -1
    

    
      
    
    • 
  
    
  • 
      
        stderr_fd
      
      
        (Integer)
      
      
      
        —
        
    file descriptor to use for child's stderr, or -1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if an error was set
    

    
      
    
    • 
  







    
      

  

  
    #spawn_async_with_pipes(working_directory, argv, envp, flags, child_setup, user_data, child_pid, standard_input, standard_output, standard_error)  ⇒ Boolean 
  

  

  


  

    
Identical to g_spawn_async_with_pipes_and_fds() but with n_fds set to zero,
so no FD assignments are used.



  





  
Parameters:


    
  
    
  • 
      
        working_directory
      
      
        (GLib::filename)
      
      
      
        —
        
    child's current working
directory, or nil to inherit parent's, in the GLib file name encoding
    

    
      
    
    • 
  
    
  • 
      
        argv
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    child's argument
vector, in the GLib file name encoding; it must be non-empty and nil-terminated
    

    
      
    
    • 
  
    
  • 
      
        envp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    child's environment, or nil to inherit parent's, in the GLib file
name encoding
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::SpawnFlags)
      
      
      
        —
        
    flags from GSpawn::Flags
    

    
      
    
    • 
  
    
  • 
      
        child_setup
      
      
        (GLib::SpawnChildSetupFunc)
      
      
      
        —
        
    function to run
in the child just before exec()
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data for child_setup
    

    
      
    
    • 
  
    
  • 
      
        child_pid
      
      
        (GLib::Pid)
      
      
      
        —
        
    return location for child process ID, or nil
    

    
      
    
    • 
  
    
  • 
      
        standard_input
      
      
        (Integer)
      
      
      
        —
        
    return location for file descriptor to write to child's stdin, or nil
    

    
      
    
    • 
  
    
  • 
      
        standard_output
      
      
        (Integer)
      
      
      
        —
        
    return location for file descriptor to read child's stdout, or nil
    

    
      
    
    • 
  
    
  • 
      
        standard_error
      
      
        (Integer)
      
      
      
        —
        
    return location for file descriptor to read child's stderr, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if an error was set
    

    
      
    
    • 
  







    
      

  

  
    #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, n_fds, child_pid_out, stdin_pipe_out, stdout_pipe_out, stderr_pipe_out)  ⇒ Boolean 
  

  

  


  

    
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 an 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
%G_SPAWN_SEARCH_PATH flag, the PATH environment variable is used to
search for the executable. If flags contains the
%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the PATH variable from envp
is used to search for the executable. If both the
%G_SPAWN_SEARCH_PATH and %G_SPAWN_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 %G_SPAWN_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 g_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, g_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 an array of strings, where each string
has the form KEY=VALUE. This will become the child's environment.
If envp is nil, 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 %G_SPAWN_DO_NOT_REAP_CHILD means that the
child will not automatically be reaped; you must use a child watch
(g_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 g_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 g_spawn_close_pid()
is equivalent to calling CloseHandle() on the process handle returned
in child_pid). See g_child_watch_add().


Open UNIX file descriptors marked as FD_CLOEXEC will be automatically
closed in the child process. %G_SPAWN_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. %G_SPAWN_SEARCH_PATH means that argv[0] need not be an
absolute path, it will be looked for in the PATH environment
variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
absolute path, it will be looked for in the PATH variable from
envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
are used, the value from envp takes precedence over the environment.


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


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


%G_SPAWN_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). %G_SPAWN_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-nil 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.


%G_SPAWN_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 g_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-nil, 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 g_child_watch_add() (or waitpid()) if you specified the
%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child_pid will be
filled with a handle to the child process only if you specified the
%G_SPAWN_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 g_spawn_close_pid() when you no longer need it.


If non-nil, 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 g_spawn_async_with_pipes() must close these file descriptors
when they are no longer in use. If these parameters are nil, the
corresponding pipe won't be created.


If stdin_pipe_out is nil, the child's standard input is attached to
/dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.


If stderr_pipe_out is NULL, the child's standard error goes to the same
location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
is set.


If stdout_pipe_out is NULL, the child's standard output goes to the same
location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL
is set.


error can be nil to ignore errors, or non-nil 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
<b>argv</b>[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 nil and an error does not occur then the returned
process reference must be closed using g_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:


    

  1. %G_SPAWN_DO_NOT_REAP_CHILD is set
    2. 

  2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set
    3. 

  3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set
    4. 

  4. working_directory is nil
    5. 

  5. child_setup is nil
    6. 

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



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 Gdk::AppLaunchContext,
GApp::LaunchContext, or set the DISPLAY environment variable.



  





  
Parameters:


    
  
    
  • 
      
        working_directory
      
      
        (GLib::filename)
      
      
      
        —
        
    child's current working
directory, or nil to inherit parent's, in the GLib file name encoding
    

    
      
    
    • 
  
    
  • 
      
        argv
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    child's argument
vector, in the GLib file name encoding; it must be non-empty and nil-terminated
    

    
      
    
    • 
  
    
  • 
      
        envp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    child's environment, or nil to inherit parent's, in the GLib file
name encoding
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::SpawnFlags)
      
      
      
        —
        
    flags from GSpawn::Flags
    

    
      
    
    • 
  
    
  • 
      
        child_setup
      
      
        (GLib::SpawnChildSetupFunc)
      
      
      
        —
        
    function to run
in the child just before exec()
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data for child_setup
    

    
      
    
    • 
  
    
  • 
      
        stdin_fd
      
      
        (Integer)
      
      
      
        —
        
    file descriptor to use for child's stdin, or -1
    

    
      
    
    • 
  
    
  • 
      
        stdout_fd
      
      
        (Integer)
      
      
      
        —
        
    file descriptor to use for child's stdout, or -1
    

    
      
    
    • 
  
    
  • 
      
        stderr_fd
      
      
        (Integer)
      
      
      
        —
        
    file descriptor to use for child's stderr, or -1
    

    
      
    
    • 
  
    
  • 
      
        source_fds
      
      
        (Array<Integer>)
      
      
      
        —
        
    array of FDs from the parent
process to make available in the child process
    

    
      
    
    • 
  
    
  • 
      
        target_fds
      
      
        (Array<Integer>)
      
      
      
        —
        
    array of FDs to remap
source_fds to in the child process
    

    
      
    
    • 
  
    
  • 
      
        n_fds
      
      
        (Integer)
      
      
      
        —
        
    number of FDs in source_fds and target_fds
    

    
      
    
    • 
  
    
  • 
      
        child_pid_out
      
      
        (GLib::Pid)
      
      
      
        —
        
    return location for child process ID, or nil
    

    
      
    
    • 
  
    
  • 
      
        stdin_pipe_out
      
      
        (Integer)
      
      
      
        —
        
    return location for file descriptor to write to child's stdin, or nil
    

    
      
    
    • 
  
    
  • 
      
        stdout_pipe_out
      
      
        (Integer)
      
      
      
        —
        
    return location for file descriptor to read child's stdout, or nil
    

    
      
    
    • 
  
    
  • 
      
        stderr_pipe_out
      
      
        (Integer)
      
      
      
        —
        
    return location for file descriptor to read child's stderr, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if an error was set
    

    
      
    
    • 
  







    
      

  

  
    #spawn_check_exit_status(wait_status)  ⇒ Boolean 
  

  

  


  

    
An old name for g_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 g_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().



  





  
Parameters:


    
  
    
  • 
      
        wait_status
      
      
        (Integer)
      
      
      
        —
        
    A status as returned from g_spawn_sync()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if child exited successfully, false otherwise (and
error will be set)
    

    
      
    
    • 
  







    
      

  

  
    #spawn_check_wait_status(wait_status)  ⇒ Boolean 
  

  

  


  

    
Set error if wait_status indicates the child exited abnormally
(e.g. with a nonzero exit code, or via a fatal signal).


The g_spawn_sync() and g_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 #GError 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 %G_SPAWN_ERROR_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, g_spawn_check_exit_status() provides the same
functionality, although under a misleading name.



  





  
Parameters:


    
  
    
  • 
      
        wait_status
      
      
        (Integer)
      
      
      
        —
        
    A platform-specific wait status as returned from g_spawn_sync()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if child exited successfully, false otherwise (and
error will be set)
    

    
      
    
    • 
  







    
      

  

  
    #spawn_close_pid(pid)  ⇒ nil 
  

  

  


  

    
On some platforms, notably Windows, the #GPid type represents a resource
which must be closed to prevent resource leaking. g_spawn_close_pid()
is provided for this purpose. It should be used on all platforms, even
though it doesn't do anything under UNIX.



  





  
Parameters:


    
  
    
  • 
      
        pid
      
      
        (GLib::Pid)
      
      
      
        —
        
    The process reference to close
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #spawn_command_line_async(command_line)  ⇒ Boolean 
  

  

  


  

    
A simple version of g_spawn_async() that parses a command line with
g_shell_parse_argv() and passes it to g_spawn_async().


Runs a command line in the background. Unlike g_spawn_async(), the
%G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
that %G_SPAWN_SEARCH_PATH can have security implications, so
consider using g_spawn_async() directly if appropriate. Possible
errors are those from g_shell_parse_argv() and g_spawn_async().


The same concerns on Windows apply as for g_spawn_command_line_sync().



  





  
Parameters:


    
  
    
  • 
      
        command_line
      
      
        (GLib::filename)
      
      
      
        —
        
    a command line
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if error is set
    

    
      
    
    • 
  







    
      

  

  
    #spawn_command_line_sync(command_line, standard_output, standard_error, wait_status)  ⇒ Boolean 
  

  

  


  

    
A simple version of g_spawn_sync() with little-used parameters
removed, taking a command line instead of an argument vector.


See g_spawn_sync() for full details.


The command_line argument will be parsed by g_shell_parse_argv().


Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled.
Note that %G_SPAWN_SEARCH_PATH can have security implications, so
consider using g_spawn_sync() directly if appropriate.


Possible errors are those from g_spawn_sync() and those
from g_shell_parse_argv().


If wait_status is non-nil, the platform-specific status of
the child is stored there; see the documentation of
g_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 g_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'".



  





  
Parameters:


    
  
    
  • 
      
        command_line
      
      
        (GLib::filename)
      
      
      
        —
        
    a command line
    

    
      
    
    • 
  
    
  • 
      
        standard_output
      
      
        (Array<Integer>)
      
      
      
        —
        
    return location for child output
    

    
      
    
    • 
  
    
  • 
      
        standard_error
      
      
        (Array<Integer>)
      
      
      
        —
        
    return location for child errors
    

    
      
    
    • 
  
    
  • 
      
        wait_status
      
      
        (Integer)
      
      
      
        —
        
    return location for child wait status, as returned by waitpid()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if an error was set
    

    
      
    
    • 
  







    
      

  

  
    #spawn_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #spawn_exit_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #spawn_sync(working_directory, argv, envp, flags, child_setup, user_data, standard_output, standard_error, wait_status)  ⇒ Boolean 
  

  

  


  

    
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-nil. Note that you must set the
%G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
passing nil for standard_output and standard_error.


If wait_status is non-nil, the platform-specific status of
the child is stored there; see the documentation of
g_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 %G_SPAWN_DO_NOT_REAP_CHILD in
flags, and on POSIX platforms, the same restrictions as for
g_child_watch_source_new() apply.


If an error occurs, no data is returned in standard_output,
standard_error, or wait_status.


This function calls g_spawn_async_with_pipes() internally; see that
function for full details on the other parameters and details on
how these functions work on Windows.



  





  
Parameters:


    
  
    
  • 
      
        working_directory
      
      
        (GLib::filename)
      
      
      
        —
        
    child's current working
directory, or nil to inherit parent's
    

    
      
    
    • 
  
    
  • 
      
        argv
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    child's argument vector, which must be non-empty and nil-terminated
    

    
      
    
    • 
  
    
  • 
      
        envp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    child's environment, or nil to inherit parent's
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::SpawnFlags)
      
      
      
        —
        
    flags from GSpawn::Flags
    

    
      
    
    • 
  
    
  • 
      
        child_setup
      
      
        (GLib::SpawnChildSetupFunc)
      
      
      
        —
        
    function to run
in the child just before exec()
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    user data for child_setup
    

    
      
    
    • 
  
    
  • 
      
        standard_output
      
      
        (Array<Integer>)
      
      
      
        —
        
    return location for child output, or nil
    

    
      
    
    • 
  
    
  • 
      
        standard_error
      
      
        (Array<Integer>)
      
      
      
        —
        
    return location for child error messages, or nil
    

    
      
    
    • 
  
    
  • 
      
        wait_status
      
      
        (Integer)
      
      
      
        —
        
    return location for child wait status, as returned by waitpid(), or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if an error was set
    

    
      
    
    • 
  







    
      

  

  
    #sprintf(string, format, array)  ⇒ Integer 
  

  

  


  

    
An implementation of the standard sprintf() function which supports
positional parameters, as specified in the Single Unix Specification.


Note that it is usually better to use [funcGLib.snprintf], to avoid the
risk of buffer overflow.


glib/gprintf.h must be explicitly included in order to use this function.


See also [funcGLib.strdup_printf].



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    A pointer to a memory buffer to contain the resulting string. It
is up to the caller to ensure that the allocated buffer is large
enough to hold the formatted result.
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes printed
    

    
      
    
    • 
  







    
      

  

  
    #stat(filename, buf)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX stat() function. The stat() function
returns information about a file. On Windows the stat() function in
the C library checks only the FAT-style READONLY attribute and does
not look at the ACL at all. Thus on Windows the protection bits in
the st_mode field are a fabrication of little use.


On Windows the Microsoft C libraries have several variants of the
stat struct and stat() function with names like _stat(), _stat32(),
_stat32i64() and _stat64i32(). The one used here is for 32-bit code
the one with 32-bit size and time fields, specifically called _stat32().


In Microsoft's compiler, by default struct stat means one with
64-bit time fields while in MinGW struct stat is the legacy one
with 32-bit fields. To hopefully clear up this messs, the gstdio.h
header defines a type GStat::Buf which is the appropriate struct type
depending on the platform and/or compiler being used. On POSIX it
is just struct stat, but note that even on POSIX platforms, stat()
might be a macro.


See your C library manual for more details about stat().



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        buf
      
      
        (GLib::StatBuf)
      
      
      
        —
        
    a pointer to a stat struct, which will be filled with the file
information
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the information was successfully retrieved,
-1 if an error occurred
    

    
      
    
    • 
  







    
      

  

  
    #stpcpy(dest, src)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        dest
      
      
        (String)
      
      
      
        —
        
    destination buffer
    

    
      
    
    • 
  
    
  • 
      
        src
      
      
        (String)
      
      
      
        —
        
    source string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to the trailing nul byte in dest
    

    
      
    
    • 
  







    
      

  

  
    #str_equal(v1, v2)  ⇒ Boolean 
  

  

  


  

    
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-nil strings as keys in a
GHash::Table.


This function is typically used for hash table comparisons, but can be used
for general purpose comparisons of non-nil strings. For a nil-safe string
comparison function, see g_strcmp0().



  





  
Parameters:


    
  
    
  • 
      
        v1
      
      
        (GObject)
      
      
      
        —
        
    a key
    

    
      
    
    • 
  
    
  • 
      
        v2
      
      
        (GObject)
      
      
      
        —
        
    a key to compare with v1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the two keys match
    

    
      
    
    • 
  







    
      

  

  
    #str_has_prefix(str, prefix)  ⇒ Boolean 
  

  

  


  

    
Looks whether the string str begins with prefix.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string to look in
    

    
      
    
    • 
  
    
  • 
      
        prefix
      
      
        (String)
      
      
      
        —
        
    the prefix to look for
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if str begins with prefix, false otherwise
    

    
      
    
    • 
  







    
      

  

  
    #str_has_suffix(str, suffix)  ⇒ Boolean 
  

  

  


  

    
Looks whether a string ends with suffix.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string to look in
    

    
      
    
    • 
  
    
  • 
      
        suffix
      
      
        (String)
      
      
      
        —
        
    the suffix to look for
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if str ends with suffix, false otherwise
    

    
      
    
    • 
  







    
      

  

  
    #str_hash(v)  ⇒ Integer 
  

  

  


  

    
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-nil strings as keys in a GHash::Table.


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.



  





  
Parameters:


    
  
    
  • 
      
        v
      
      
        (GObject)
      
      
      
        —
        
    a string key
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a hash value corresponding to the key
    

    
      
    
    • 
  







    
      

  

  
    #str_is_ascii(str)  ⇒ Boolean 
  

  

  


  

    
Determines if a string is pure ASCII. A string is pure ASCII if it
contains no bytes with the high bit set.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if str is ASCII
    

    
      
    
    • 
  







    
      

  

  
    #str_match_string(search_term, potential_hit, accept_alternates)  ⇒ Boolean 
  

  

  


  

    
Checks if a search conducted for search_term should match
potential_hit.


This function calls [funcGLib.str_tokenize_and_fold] on both
search_term and potential_hit. ASCII alternates are never taken
for search_term but will be taken for potential_hit according to
the value of accept_alternates.


A hit occurs when each folded token in search_term is a prefix of a
folded token from potential_hit.


Depending on how you're performing the search, it will typically be
faster to call g_str_tokenize_and_fold() on each string in
your corpus and build an index on the returned folded tokens, then
call g_str_tokenize_and_fold() on the search term and
perform lookups into that index.


As some examples, searching for ‘fred’ would match the potential hit
‘Smith, Fred’ and also ‘Frédéric’.  Searching for ‘Fréd’ would match
‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of
accent matching).  Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo
Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix).



  





  
Parameters:


    
  
    
  • 
      
        search_term
      
      
        (String)
      
      
      
        —
        
    the search term from the user
    

    
      
    
    • 
  
    
  • 
      
        potential_hit
      
      
        (String)
      
      
      
        —
        
    the text that may be a hit
    

    
      
    
    • 
  
    
  • 
      
        accept_alternates
      
      
        (Boolean)
      
      
      
        —
        
    if true, ASCII alternates are accepted
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if potential_hit is a hit
    

    
      
    
    • 
  







    
      

  

  
    #str_to_ascii(str, from_locale)  ⇒ String 
  

  

  


  

    
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][<b>modifier</b>]).


If from_locale is nil 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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string, in UTF-8
    

    
      
    
    • 
  
    
  • 
      
        from_locale
      
      
        (String)
      
      
      
        —
        
    the source locale, if known
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a string in plain ASCII
    

    
      
    
    • 
  







    
      

  

  
    #str_tokenize_and_fold(string, translit_locale, ascii_alternates)  ⇒ Array<String> 
  

  

  


  

    
Tokenizes string and performs folding on each token.


A token is a non-empty sequence of alphanumeric characters in the
source string, separated by non-alphanumeric characters.  An
"alphanumeric" character for this purpose is one that matches
[funcGLib.unichar_isalnum] or [funcGLib.unichar_ismark].


Each token is then (Unicode) normalised and case-folded.  If
ascii_alternates is non-NULL and some of the returned tokens
contain non-ASCII characters, ASCII alternatives will be generated.


The number of ASCII alternatives that are generated and the method
for doing so is unspecified, but translit_locale (if specified) may
improve the transliteration if the language of the source string is
known.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string to tokenize
    

    
      
    
    • 
  
    
  • 
      
        translit_locale
      
      
        (String)
      
      
      
        —
        
    the language code (like 'de' or
'en_GB') from which string originates
    

    
      
    
    • 
  
    
  • 
      
        ascii_alternates
      
      
        (Array<String>)
      
      
      
        —
        
    a return location for ASCII alternates
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    the folded tokens
    

    
      
    
    • 
  







    
      

  

  
    #strcanon(string, valid_chars, substitutor)  ⇒ String 
  

  

  


  

    
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 [funcGLib.strdup]:


reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
…
g_free (reformatted);




  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a nul-terminated array of bytes
    

    
      
    
    • 
  
    
  • 
      
        valid_chars
      
      
        (String)
      
      
      
        —
        
    bytes permitted in string
    

    
      
    
    • 
  
    
  • 
      
        substitutor
      
      
        (GLib::gchar)
      
      
      
        —
        
    replacement character for disallowed bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the modified string
    

    
      
    
    • 
  







    
      

  

  
    #strcasecmp(s1, s2)  ⇒ Integer 
  

  

  


  

    
A case-insensitive string comparison, corresponding to the standard
strcasecmp() function on platforms which support it.



  





  
Parameters:


    
  
    
  • 
      
        s1
      
      
        (String)
      
      
      
        —
        
    string to compare with s2
    

    
      
    
    • 
  
    
  • 
      
        s2
      
      
        (String)
      
      
      
        —
        
    string to compare with s1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the strings match, a negative value if s1 < s2,
or a positive value if s1 > s2
    

    
      
    
    • 
  







    
      

  

  
    #strchomp(string)  ⇒ String 
  

  

  


  

    
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 [funcGLib.strchug] and [funcGLib.strstrip].



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string to remove the trailing whitespace from
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the modified string
    

    
      
    
    • 
  







    
      

  

  
    #strchug(string)  ⇒ String 
  

  

  


  

    
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 [funcGLib.strchomp] and [funcGLib.strstrip].



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string to remove the leading whitespace from
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the modified string
    

    
      
    
    • 
  







    
      

  

  
    #strcmp0(str1, str2)  ⇒ Integer 
  

  

  


  

    
Compares str1 and str2 like strcmp(). Handles nil
gracefully by sorting it before non-nil strings.
Comparing two nil pointers returns 0.



  





  
Parameters:


    
  
    
  • 
      
        str1
      
      
        (String)
      
      
      
        —
        
    a C string or nil
    

    
      
    
    • 
  
    
  • 
      
        str2
      
      
        (String)
      
      
      
        —
        
    another C string or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    an integer less than, equal to, or greater than zero, if str1 is <, == or > than str2.
    

    
      
    
    • 
  







    
      

  

  
    #strcompress(source)  ⇒ String 
  

  

  


  

    
Replaces all escaped characters with their one byte equivalent.


This function does the reverse conversion of [funcGLib.strescape].



  





  
Parameters:


    
  
    
  • 
      
        source
      
      
        (String)
      
      
      
        —
        
    a string to compress
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated copy of source with all escaped
character compressed
    

    
      
    
    • 
  







    
      

  

  
    #strconcat(string1, array)  ⇒ String 
  

  

  


  

    
Concatenates all of the given strings into one long string.


The variable argument list must end with NULL. If you forget the NULL,
g_strconcat() will start appending random memory junk to your string.


Note that this function is usually not the right function to use to
assemble a translated message from pieces, since proper translation
often requires the pieces to be reordered.



  





  
Parameters:


    
  
    
  • 
      
        string1
      
      
        (String)
      
      
      
        —
        
    the first string to add, which must not be NULL
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    a NULL-terminated list of strings to append to the string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string containing all the string arguments
    

    
      
    
    • 
  







    
      

  

  
    #strdelimit(string, delimiters, new_delimiter)  ⇒ String 
  

  

  


  

    
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 [funcGLib.strdup]:


reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
…
g_free (reformatted);




  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the string to convert
    

    
      
    
    • 
  
    
  • 
      
        delimiters
      
      
        (String)
      
      
      
        —
        
    a string containing the current delimiters, or
NULL to use the standard delimiters defined in [constGLib.STR_DELIMITERS]
    

    
      
    
    • 
  
    
  • 
      
        new_delimiter
      
      
        (GLib::gchar)
      
      
      
        —
        
    the new delimiter character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the modified string
    

    
      
    
    • 
  







    
      

  

  
    #strdown(string)  ⇒ String 
  

  

  


  

    
Converts a string to lower case.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the string to convert
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the string
    

    
      
    
    • 
  







    
      

  

  
    #strdup(str)  ⇒ String 
  

  

  


  

    
Duplicates a string. If str is NULL it returns NULL.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    the string to duplicate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated copy of str
    

    
      
    
    • 
  







    
      

  

  
    #strdup_printf(format, array)  ⇒ String 
  

  

  


  

    
Similar to the standard C sprintf() function but safer, since it
calculates the maximum space required and allocates memory to hold
the result.


The returned string is guaranteed to be non-NULL, unless format
contains %lc or %ls conversions, which can fail if no multibyte
representation is available for the given character.



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    the parameters to insert into the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string holding the
result
    

    
      
    
    • 
  







    
      

  

  
    #strdup_vprintf(format, args)  ⇒ String 
  

  

  


  

    
Similar to the standard C vsprintf() function but safer, since it
calculates the maximum space required and allocates memory to hold
the result.


The returned string is guaranteed to be non-NULL, unless format
contains %lc or %ls conversions, which can fail if no multibyte
representation is available for the given character.


See also [funcGLib.vasprintf], which offers the same functionality, but
additionally returns the length of the allocated string.



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    the list of parameters to insert into the format string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string holding the
result
    

    
      
    
    • 
  







    
      

  

  
    #strdupv(str_array)  ⇒ Array<String> 
  

  

  


  

    
Copies an array of strings. The copy is a deep copy; each string is also
copied.


If called on a NULL value, g_strdupv() simply returns NULL.



  





  
Parameters:


    
  
    
  • 
      
        str_array
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings to copy
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    a
newly-allocated array of strings. Use [funcGLib.strfreev] to free it.
    

    
      
    
    • 
  







    
      

  

  
    #strerror(errnum)  ⇒ String 
  

  

  


  

    
Returns a string corresponding to the given error code, e.g. "no
such process".


Unlike strerror(), this always returns a string in
UTF-8 encoding, and the pointer is guaranteed to remain valid for
the lifetime of the process. If the error code is unknown, it returns a
string like “Unknown error <code>”.


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




  





  
Parameters:


    
  
    
  • 
      
        errnum
      
      
        (Integer)
      
      
      
        —
        
    the system error number. See the standard C errno documentation
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the string describing the error code
    

    
      
    
    • 
  







    
      

  

  
    #strescape(source, exceptions)  ⇒ String 
  

  

  


  

    
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.


[funcGLib.strcompress] does the reverse conversion.



  





  
Parameters:


    
  
    
  • 
      
        source
      
      
        (String)
      
      
      
        —
        
    a string to escape
    

    
      
    
    • 
  
    
  • 
      
        exceptions
      
      
        (String)
      
      
      
        —
        
    a string of characters not to escape in source
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated copy of source with special characters escaped
    

    
      
    
    • 
  







    
      

  

  
    #strfreev(str_array)  ⇒ nil 
  

  

  


  

    
Frees an array of strings, as well as each string it contains.


If str_array is NULL, this function simply returns.



  





  
Parameters:


    
  
    
  • 
      
        str_array
      
      
        (Array<String>)
      
      
      
        —
        
    an
array of strings to free
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #strip_context(msgid, msgval)  ⇒ String 
  

  

  


  

    
An auxiliary function for gettext() support (see Q_()).



  





  
Parameters:


    
  
    
  • 
      
        msgid
      
      
        (String)
      
      
      
        —
        
    a string
    

    
      
    
    • 
  
    
  • 
      
        msgval
      
      
        (String)
      
      
      
        —
        
    another string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    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.
    

    
      
    
    • 
  







    
      

  

  
    #strjoin(separator, array)  ⇒ String 
  

  

  


  

    
Joins a number of strings together to form one long string, with the
optional separator inserted between each of them.



  





  
Parameters:


    
  
    
  • 
      
        separator
      
      
        (String)
      
      
      
        —
        
    a string to insert between each of the strings
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    a NULL-terminated list of strings to join
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string containing all of the strings joined
together, with separator between them
    

    
      
    
    • 
  







    
      

  

  
    #strjoinv(separator, str_array)  ⇒ String 
  

  

  


  

    
Joins an array of strings together to form one long string, with the
optional separator inserted between each of them.


If str_array has no items, the return value will be an
empty string. If str_array contains a single item, separator will not
appear in the resulting string.



  





  
Parameters:


    
  
    
  • 
      
        separator
      
      
        (String)
      
      
      
        —
        
    a string to insert between each of the strings
    

    
      
    
    • 
  
    
  • 
      
        str_array
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings to join
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string containing all of the strings joined
together, with separator between them
    

    
      
    
    • 
  







    
      

  

  
    #strlcat(dest, src, dest_size)  ⇒ Integer 
  

  

  


  

    
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 [funcGLib.strconcat] is harder to mess up.



  





  
Parameters:


    
  
    
  • 
      
        dest
      
      
        (String)
      
      
      
        —
        
    destination buffer, already containing one nul-terminated string
    

    
      
    
    • 
  
    
  • 
      
        src
      
      
        (String)
      
      
      
        —
        
    source buffer
    

    
      
    
    • 
  
    
  • 
      
        dest_size
      
      
        (Integer)
      
      
      
        —
        
    length of dest buffer in bytes (not length of existing string
inside dest)
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    size of attempted result, which is MIN (dest_size, strlen (original dest)) + strlen (src), so if retval >= dest_size,
truncation occurred
    

    
      
    
    • 
  







    
      

  

  
    #strlcpy(dest, src, dest_size)  ⇒ Integer 
  

  

  


  

    
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, [funcGLib.strdup] is an even better
idea.



  





  
Parameters:


    
  
    
  • 
      
        dest
      
      
        (String)
      
      
      
        —
        
    destination buffer
    

    
      
    
    • 
  
    
  • 
      
        src
      
      
        (String)
      
      
      
        —
        
    source buffer
    

    
      
    
    • 
  
    
  • 
      
        dest_size
      
      
        (Integer)
      
      
      
        —
        
    length of dest in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    length of src
    

    
      
    
    • 
  







    
      

  

  
    #strncasecmp(s1, s2, n)  ⇒ Integer 
  

  

  


  

    
A case-insensitive string comparison, corresponding to the standard
strncasecmp() function on platforms which support it. It is similar
to [funcGLib.strcasecmp] except it only compares the first n characters of
the strings.



  





  
Parameters:


    
  
    
  • 
      
        s1
      
      
        (String)
      
      
      
        —
        
    string to compare with s2
    

    
      
    
    • 
  
    
  • 
      
        s2
      
      
        (String)
      
      
      
        —
        
    string to compare with s1
    

    
      
    
    • 
  
    
  • 
      
        n
      
      
        (Integer)
      
      
      
        —
        
    the maximum number of characters to compare
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the strings match, a negative value if s1 < s2,
or a positive value if s1 > s2
    

    
      
    
    • 
  







    
      

  

  
    #strndup(str, n)  ⇒ String 
  

  

  


  

    
Duplicates the first n bytes of a string, returning a newly-allocated
buffer n + 1 bytes long which will always be nul-terminated. If str
is less than n bytes long the buffer is padded with nuls. If str is
NULL it returns NULL.


To copy a number of characters from a UTF-8 encoded string,
use [funcGLib.utf8_strncpy] instead.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    the string to duplicate
    

    
      
    
    • 
  
    
  • 
      
        n
      
      
        (Integer)
      
      
      
        —
        
    the maximum number of bytes to copy from str
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated buffer containing the first
n bytes of str
    

    
      
    
    • 
  







    
      

  

  
    #strnfill(length, fill_char)  ⇒ String 
  

  

  


  

    
Creates a new string length bytes long filled with fill_char.



  





  
Parameters:


    
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    the length of the new string
    

    
      
    
    • 
  
    
  • 
      
        fill_char
      
      
        (GLib::gchar)
      
      
      
        —
        
    the byte to fill the string with
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string filled with fill_char
    

    
      
    
    • 
  







    
      

  

  
    #strreverse(string)  ⇒ String 
  

  

  


  

    
Reverses all of the bytes in a string. For example,
g_strreverse ("abcdef") will result in "fedcba".


Note that g_strreverse() doesn't work on UTF-8 strings
containing multibyte characters. For that purpose, use
[funcGLib.utf8_strreverse].



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the string to reverse
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the string, reversed in place
    

    
      
    
    • 
  







    
      

  

  
    #strrstr(haystack, needle)  ⇒ String 
  

  

  


  

    
Searches the string haystack for the last occurrence
of the string needle.



  





  
Parameters:


    
  
    
  • 
      
        haystack
      
      
        (String)
      
      
      
        —
        
    a string to search in
    

    
      
    
    • 
  
    
  • 
      
        needle
      
      
        (String)
      
      
      
        —
        
    the string to search for
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to the found occurrence, or NULL if not found
    

    
      
    
    • 
  







    
      

  

  
    #strrstr_len(haystack, haystack_len, needle)  ⇒ String 
  

  

  


  

    
Searches the string haystack for the last occurrence
of the string needle, limiting the length of the search
to haystack_len.



  





  
Parameters:


    
  
    
  • 
      
        haystack
      
      
        (String)
      
      
      
        —
        
    a string to search in
    

    
      
    
    • 
  
    
  • 
      
        haystack_len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the maximum length of haystack in bytes. A length of -1
can be used to mean "search the entire string", like [funcGLib.strrstr]
    

    
      
    
    • 
  
    
  • 
      
        needle
      
      
        (String)
      
      
      
        —
        
    the string to search for
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to the found occurrence, or NULL if not found
    

    
      
    
    • 
  







    
      

  

  
    #strsignal(signum)  ⇒ String 
  

  

  


  

    
Returns a string describing the given signal, e.g. "Segmentation fault".
If the signal is unknown, it returns “unknown signal (<signum>)”.


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.



  





  
Parameters:


    
  
    
  • 
      
        signum
      
      
        (Integer)
      
      
      
        —
        
    the signal number. See the signal documentation
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the string describing the signal
    

    
      
    
    • 
  







    
      

  

  
    #strsplit(string, delimiter, max_tokens)  ⇒ Array<String> 
  

  

  


  

    
Splits a string into a maximum of max_tokens pieces, using the given
delimiter. If max_tokens is reached, the remainder of string is
appended to the last token.


As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is an array
containing the six strings "", "a", "bc", "", "d" and "".


As a special case, the result of splitting the empty string "" is an empty
array, not an array containing a single string. The reason for this
special case is that being able to represent an empty array is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you'll need to check for the empty string
before calling g_strsplit().



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string to split
    

    
      
    
    • 
  
    
  • 
      
        delimiter
      
      
        (String)
      
      
      
        —
        
    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
      
      
        (Integer)
      
      
      
        —
        
    the maximum number of pieces to split string into
If this is less than 1, the string is split completely
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    a newly-allocated array of strings, freed with
[funcGLib.strfreev]
    

    
      
    
    • 
  







    
      

  

  
    #strsplit_set(string, delimiters, max_tokens)  ⇒ Array<String> 
  

  

  


  

    
Splits string into a number of tokens not containing any of the characters
in delimiters. A token is the (possibly empty) longest string that does not
contain any of the characters in delimiters. If max_tokens is reached, the
remainder is appended to the last token.


For example, the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is an
array containing the three strings "abc", "def", and "ghi".


The result of g_strsplit_set (":def/ghi:", ":/", -1) is an array containing
the four strings "", "def", "ghi", and "".


As a special case, the result of splitting the empty string "" is an empty
array, not an array containing a single string. The reason for this
special case is that being able to represent an empty array is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you'll need to check for the empty string
before calling g_strsplit_set().


Note that this function works on bytes not characters, so it can't be used
to delimit UTF-8 strings for anything but ASCII characters.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a string to split
    

    
      
    
    • 
  
    
  • 
      
        delimiters
      
      
        (String)
      
      
      
        —
        
    a string containing characters that are used to split the
string. Can be empty, which will result in no string splitting
    

    
      
    
    • 
  
    
  • 
      
        max_tokens
      
      
        (Integer)
      
      
      
        —
        
    the maximum number of tokens to split string into.
If this is less than 1, the string is split completely
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    a newly-allocated array of strings. Use
[funcGLib.strfreev] to free it.
    

    
      
    
    • 
  







    
      

  

  
    #strstr_len(haystack, haystack_len, needle)  ⇒ String 
  

  

  


  

    
Searches the string haystack for the first occurrence
of the string needle, limiting the length of the search
to haystack_len or a nul terminator byte (whichever is reached first).


A length of -1 can be used to mean “search the entire string”, like
strstr().



  





  
Parameters:


    
  
    
  • 
      
        haystack
      
      
        (String)
      
      
      
        —
        
    a string to search in
    

    
      
    
    • 
  
    
  • 
      
        haystack_len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the maximum length of haystack in bytes, or -1 to
search it entirely
    

    
      
    
    • 
  
    
  • 
      
        needle
      
      
        (String)
      
      
      
        —
        
    the string to search for
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to the found occurrence, or NULL if not found
    

    
      
    
    • 
  







    
      

  

  
    #strtod(nptr, endptr)  ⇒ Float 
  

  

  


  

    
Converts a string to a floating point value.


It calls the standard strtod() function to handle the conversion, but
if the string is not completely converted it attempts the conversion
again with [funcGLib.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 [funcGLib.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.



  





  
Parameters:


    
  
    
  • 
      
        nptr
      
      
        (String)
      
      
      
        —
        
    the string to convert to a numeric value
    

    
      
    
    • 
  
    
  • 
      
        endptr
      
      
        (String)
      
      
      
        —
        
    if non-NULL, it returns the
character after the last character used in the conversion
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Float)
      
      
      
        —
        
    the converted value
    

    
      
    
    • 
  







    
      

  

  
    #strup(string)  ⇒ String 
  

  

  


  

    
Converts a string to upper case.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the string to convert
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the string
    

    
      
    
    • 
  







    
      

  

  
    #strv_contains(strv, str)  ⇒ Boolean 
  

  

  


  

    
Checks if an array of strings contains the string str according to
[funcGLib.str_equal]. strv must not be NULL.



  





  
Parameters:


    
  
    
  • 
      
        strv
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings to search in
    

    
      
    
    • 
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    the string to search for
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if str is an element of strv
    

    
      
    
    • 
  







    
      

  

  
    #strv_equal(strv1, strv2)  ⇒ Boolean 
  

  

  


  

    
Checks if two arrays of strings contain exactly the same elements in
exactly the same order.


Elements are compared using [funcGLib.str_equal]. To match independently
of order, sort the arrays first (using [funcGLib.qsort_with_data]
or similar).


Elements are compared using [funcGLib.str_equal]. To match independently
of order, sort the arrays first (using [funcGLib.qsort_with_data]
or similar).


Two empty arrays are considered equal. Neither strv1 nor strv2 may be
NULL.



  





  
Parameters:


    
  
    
  • 
      
        strv1
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings to compare to strv2
    

    
      
    
    • 
  
    
  • 
      
        strv2
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings to compare to strv1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if strv1 and strv2 are equal
    

    
      
    
    • 
  







    
      

  

  
    #strv_get_type  ⇒ GLib::Type 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Type)
      
      
      
    
    • 
  







    
      

  

  
    #strv_length(str_array)  ⇒ Integer 
  

  

  


  

    
Returns the length of an array of strings. str_array must not be NULL.



  





  
Parameters:


    
  
    
  • 
      
        str_array
      
      
        (Array<String>)
      
      
      
        —
        
    an array of strings
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    length of str_array
    

    
      
    
    • 
  







    
      

  

  
    #system_config_dirs  ⇒ Array<GLib::filename> 
  

  

  


  

    
Returns an ordered list of base directories in which to access
system-wide configuration information.


On UNIX platforms this is determined using the mechanisms described
in the
XDG Base Directory Specification.
In this case the list of directories retrieved will be XDG_CONFIG_DIRS.


On Windows it follows XDG Base Directory Specification if XDG_CONFIG_DIRS is defined.
If XDG_CONFIG_DIRS is undefined, the directory that contains application
data for all users is used instead. A typical path is
C:\Documents and Settings\All Users\Application Data.
This folder is used for application data
that is not user specific. For example, an application can store
a spell-check dictionary, a database of clip art, or a log file in the
FOLDERID_ProgramData folder. This information will not roam and is available
to anyone using the computer.


The return value is cached and modifying it at runtime is not supported, as
it’s not thread-safe to modify environment variables at runtime.



  





  

Returns:


    
  
    
  • 
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    an array of strings owned by GLib that must not be
modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #system_data_dirs  ⇒ Array<GLib::filename> 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    an array of strings owned by GLib that must not be
modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #test_add_data_func(testpath, test_data, test_func)  ⇒ nil 
  

  

  


  

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


No component of testpath may start with a dot (.) if the
%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
do so even if it isn’t.



  





  
Parameters:


    
  
    
  • 
      
        testpath
      
      
        (String)
      
      
      
        —
        
    /-separated test case path name for the test.
    

    
      
    
    • 
  
    
  • 
      
        test_data
      
      
        (GObject)
      
      
      
        —
        
    Test data argument for the test function.
    

    
      
    
    • 
  
    
  • 
      
        test_func
      
      
        (GLib::TestDataFunc)
      
      
      
        —
        
    The test function to invoke for this test.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_add_data_func_full(testpath, test_data, test_func, data_free_func)  ⇒ nil 
  

  

  


  

    
Create a new test case, as with g_test_add_data_func(), but freeing
test_data after the test run is complete.



  





  
Parameters:


    
  
    
  • 
      
        testpath
      
      
        (String)
      
      
      
        —
        
    /-separated test case path name for the test.
    

    
      
    
    • 
  
    
  • 
      
        test_data
      
      
        (GObject)
      
      
      
        —
        
    Test data argument for the test function.
    

    
      
    
    • 
  
    
  • 
      
        test_func
      
      
        (GLib::TestDataFunc)
      
      
      
        —
        
    The test function to invoke for this test.
    

    
      
    
    • 
  
    
  • 
      
        data_free_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    GDestroy::Notify for test_data.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_add_func(testpath, test_func)  ⇒ nil 
  

  

  


  

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


No component of testpath may start with a dot (.) if the
%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
do so even if it isn’t.



  





  
Parameters:


    
  
    
  • 
      
        testpath
      
      
        (String)
      
      
      
        —
        
    /-separated test case path name for the test.
    

    
      
    
    • 
  
    
  • 
      
        test_func
      
      
        (GLib::TestFunc)
      
      
      
        —
        
    The test function to invoke for this test.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_add_vtable(testpath, data_size, test_data, data_setup, data_test, data_teardown)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        testpath
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        data_size
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        test_data
      
      
        (GObject)
      
      
      
    
    • 
  
    
  • 
      
        data_setup
      
      
        (GLib::TestFixtureFunc)
      
      
      
    
    • 
  
    
  • 
      
        data_test
      
      
        (GLib::TestFixtureFunc)
      
      
      
    
    • 
  
    
  • 
      
        data_teardown
      
      
        (GLib::TestFixtureFunc)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_assert_expected_messages_internal(domain, file, line, func)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_bug(bug_uri_snippet)  ⇒ nil 
  

  

  


  

    
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 g_test_bug_base()
and bug_uri_snippet. If g_test_bug_base() has not been called, it is
assumed to be the empty string, so a full URI can be provided to
g_test_bug() instead.


Since GLib 2.70, the base URI is not prepended to bug_uri_snippet if it
is already a valid URI.



  





  
Parameters:


    
  
    
  • 
      
        bug_uri_snippet
      
      
        (String)
      
      
      
        —
        
    Bug specific bug tracker URI or URI portion.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_bug_base(uri_pattern)  ⇒ nil 
  

  

  


  

    
Specify the base URI for bug reports.


The base URI is used to construct bug report messages for
g_test_message() when g_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 g_test_bug_base() is not called, bug URIs are formed solely
from the value provided by g_test_bug().



  





  
Parameters:


    
  
    
  • 
      
        uri_pattern
      
      
        (String)
      
      
      
        —
        
    the base pattern for bug URIs
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_build_filename(file_type, first_path, array)  ⇒ String 
  

  

  


  

    
Creates the pathname to a data file that is required for a test.


This function is conceptually similar to g_build_filename() except
that the first argument has been replaced with a GTest::FileType
argument.


The data file should either have been distributed with the module
containing the test (%G_TEST_DIST) or built as part of the build
system of that module (%G_TEST_BUILT).


In order for this function to work in srcdir != builddir situations,
the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to
have been defined.  As of 2.38, this is done by the glib.mk
included in GLib.  Please ensure that your copy is up to date before
using this function.


In case neither variable is set, this function will fall back to
using the dirname portion of argv[0], possibly removing ".libs".
This allows for casual running of tests directly from the commandline
in the srcdir == builddir case and should also support running of
installed tests, assuming the data files have been installed in the
same relative path as the test binary.



  





  
Parameters:


    
  
    
  • 
      
        file_type
      
      
        (GLib::TestFileType)
      
      
      
        —
        
    the type of file (built vs. distributed)
    

    
      
    
    • 
  
    
  • 
      
        first_path
      
      
        (String)
      
      
      
        —
        
    the first segment of the pathname
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    nil-terminated additional path segments
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the path of the file, to be freed using g_free()
    

    
      
    
    • 
  







    
      

  

  
    #test_create_case(test_name, data_size, test_data, data_setup, data_test, data_teardown)  ⇒ GLib::TestCase 
  

  

  


  

    
Create a new GTest::Case, named test_name.


This API is fairly low level, and calling g_test_add() or g_test_add_func()
is preferable.


When this test is executed, a fixture structure of size data_size
will be automatically allocated and filled with zeros. Then data_setup is
called to initialize the fixture. After fixture setup, the actual test
function data_test is called. Once the test run completes, the
fixture structure is torn down by calling data_teardown and
after that the memory is automatically released by the test framework.


Splitting up a test run into fixture setup, test function and
fixture teardown is most useful if the same fixture type is used for
multiple tests. In this cases, g_test_create_case() will be
called with the same type of fixture (the data_size argument), but varying
test_name and data_test arguments.



  





  
Parameters:


    
  
    
  • 
      
        test_name
      
      
        (String)
      
      
      
        —
        
    the name for the test case
    

    
      
    
    • 
  
    
  • 
      
        data_size
      
      
        (Integer)
      
      
      
        —
        
    the size of the fixture data structure
    

    
      
    
    • 
  
    
  • 
      
        test_data
      
      
        (GObject)
      
      
      
        —
        
    test data argument for the test functions
    

    
      
    
    • 
  
    
  • 
      
        data_setup
      
      
        (GLib::TestFixtureFunc)
      
      
      
        —
        
    the function to set up the fixture data
    

    
      
    
    • 
  
    
  • 
      
        data_test
      
      
        (GLib::TestFixtureFunc)
      
      
      
        —
        
    the actual test function
    

    
      
    
    • 
  
    
  • 
      
        data_teardown
      
      
        (GLib::TestFixtureFunc)
      
      
      
        —
        
    the function to teardown the fixture data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::TestCase)
      
      
      
        —
        
    a newly allocated GTest::Case.
    

    
      
    
    • 
  







    
      

  

  
    #test_create_suite(suite_name)  ⇒ GLib::TestSuite 
  

  

  


  

    
Create a new test suite with the name suite_name.



  





  
Parameters:


    
  
    
  • 
      
        suite_name
      
      
        (String)
      
      
      
        —
        
    a name for the suite
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::TestSuite)
      
      
      
        —
        
    A newly allocated GTest::Suite instance.
    

    
      
    
    • 
  







    
      

  

  
    #test_disable_crash_reporting  ⇒ nil 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_expect_message(log_domain, log_level, pattern)  ⇒ nil 
  

  

  


  

    
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 ([funcGLib.log] without
G_LOG_USE_STRUCTURED defined). It will not work with the structured logging
API. See Testing for Messages.


Use [funcGLib.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 [funcGLib.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 [funcGLib.error] messages, since
[funcGLib.error] intentionally never returns even if the program doesn’t
abort; use [funcGLib.test_trap_subprocess] in this case.


If messages at [flagsGLib.LogLevelFlags.LEVEL_DEBUG] are emitted, but not explicitly
expected via [funcGLib.test_expect_message] then they will be ignored.



  





  
Parameters:


    
  
    
  • 
      
        log_domain
      
      
        (String)
      
      
      
        —
        
    the log domain of the message
    

    
      
    
    • 
  
    
  • 
      
        log_level
      
      
        (GLib::LogLevelFlags)
      
      
      
        —
        
    the log level of the message
    

    
      
    
    • 
  
    
  • 
      
        pattern
      
      
        (String)
      
      
      
        —
        
    a glob-style pattern (see [typeGLib.PatternSpec])
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_fail  ⇒ nil 
  

  

  


  

    
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 g_test_skip() and g_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 g_test_fail(), or use g_test_fail_printf()
instead.



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_fail_printf(format, array)  ⇒ nil 
  

  

  


  

    
Equivalent to g_test_fail(), but also record a message like
g_test_skip_printf().



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the format string
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    printf-like arguments to format
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_failed  ⇒ Boolean 
  

  

  


  

    
Returns whether a test has already failed. This will
be the case when g_test_fail(), g_test_incomplete()
or g_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.



  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the test has failed
    

    
      
    
    • 
  







    
      

  

  
    #test_get_dir(file_type)  ⇒ GLib::filename 
  

  

  


  

    
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.



  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the path of the directory, owned by GLib
    

    
      
    
    • 
  







    
      

  

  
    #test_get_filename(file_type, first_path, array)  ⇒ String 
  

  

  


  

    
Gets the pathname to a data file that is required for a test.


This is the same as g_test_build_filename() with two differences.
The first difference is that you must only use this function from within
a testcase function.  The second difference is that you need not free
the return value — it will be automatically freed when the testcase
finishes running.


It is safe to use this function from a thread inside of a testcase
but you must ensure that all such uses occur before the main testcase
function returns (ie: it is best to ensure that all threads have been
joined).



  





  
Parameters:


    
  
    
  • 
      
        file_type
      
      
        (GLib::TestFileType)
      
      
      
        —
        
    the type of file (built vs. distributed)
    

    
      
    
    • 
  
    
  • 
      
        first_path
      
      
        (String)
      
      
      
        —
        
    the first segment of the pathname
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    nil-terminated additional path segments
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the path, automatically freed at the end of the testcase
    

    
      
    
    • 
  







    
      

  

  
    #test_get_path  ⇒ String 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the test path for the test currently being run
    

    
      
    
    • 
  







    
      

  

  
    #test_get_root  ⇒ GLib::TestSuite 
  

  

  


  

    
Get the toplevel test suite for the test path API.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::TestSuite)
      
      
      
        —
        
    the toplevel GTest::Suite
    

    
      
    
    • 
  







    
      

  

  
    #test_incomplete(msg)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        msg
      
      
        (String)
      
      
      
        —
        
    explanation
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_incomplete_printf(format, array)  ⇒ nil 
  

  

  


  

    
Equivalent to g_test_incomplete(), but the explanation is formatted
as if by g_strdup_printf().



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the format string
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    printf-like arguments to format
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_init(argc, argv, array)  ⇒ nil 
  

  

  


  

    
Initialize the GLib testing framework, e.g. by seeding the
test random number generator, the name for g_get_prgname()
and parsing test related command line args.


This should be called before calling any other g_test_*() functions.


So far, the following arguments are understood:


    

  • 

    -l: List test cases available in a test executable.
    

    • 

  • 

    --seed=SEED: Provide a random seed to reproduce test
runs using random numbers.
    

    • 

  • 

    --verbose: Run tests verbosely.
    

    • 

  • 

    -q, --quiet: Run tests quietly.
    

    • 

  • 

    -p PATH: Execute all tests matching the given path.
    

    • 

  • 

    -s PATH: Skip all tests matching the given path.
This can also be used to force a test to run that would otherwise
be skipped (ie, a test whose name contains "/subprocess").
    

    • 

  • 

    -m {perf|slow|thorough|quick|undefined|no-undefined}: Execute tests according to these test modes:
    

    perf: Performance tests, may take long and report results (off by default).
    

    slow, thorough: Slow and thorough tests, may take quite long and maximize coverage
(off by default).
    

    quick: Quick tests, should run really quickly and give good coverage (the default).
    

    undefined: Tests for undefined behaviour, may provoke programming errors
under g_test_trap_subprocess() or g_test_expect_message() to check
that appropriate assertions or warnings are given (the default).
    

    no-undefined: Avoid tests for undefined behaviour
    

    • 

  • 

    --debug-log: Debug test logging output.
    

    • 



Options which can be passed to @... are:


    

  • "no_g_set_prgname": Causes g_test_init() to not call g_set_prgname().
    • 

  • %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each
unit test and uses g_set_user_dirs() to set XDG directories to point into
that temporary directory for the duration of the unit test. See the
documentation for %G_TEST_OPTION_ISOLATE_DIRS.
    • 



Since 2.58, if tests are compiled with G_DISABLE_ASSERT defined,
g_test_init() will print an error and exit. This is to prevent no-op tests
from being executed, as g_assert() is commonly (erroneously) used in unit
tests, and is a no-op when compiled with G_DISABLE_ASSERT. Ensure your
tests are compiled without G_DISABLE_ASSERT defined.



  





  
Parameters:


    
  
    
  • 
      
        argc
      
      
        (Integer)
      
      
      
        —
        
    Address of the argc parameter of the main() function.
Changed if any arguments were handled.
    

    
      
    
    • 
  
    
  • 
      
        argv
      
      
        (String)
      
      
      
        —
        
    Address of the argv parameter of main().
Any parameters understood by g_test_init() stripped before return.
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    nil-terminated list of special options, documented below.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_log_set_fatal_handler(log_func, user_data)  ⇒ nil 
  

  

  


  

    
Installs a non-error fatal log handler which can be
used to decide whether log messages which are counted
as fatal abort the program.


The use case here is that you are running a test case
that depends on particular libraries or circumstances
and cannot prevent certain known critical or warning
messages. So you install a handler that compares the
domain and message to precisely not abort in such a case.


Note that the handler is reset at the beginning of
any test case, so you have to set it inside each test
function which needs the special behavior.


This handler has no effect on g_error messages.


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



  





  
Parameters:


    
  
    
  • 
      
        log_func
      
      
        (GLib::TestLogFatalFunc)
      
      
      
        —
        
    the log handler function.
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    data passed to the log handler.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_log_type_name(log_type)  ⇒ String 
  

  

  


  

    

  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
    
    • 
  







    
      

  

  
    #test_maximized_result(maximized_quantity, format, array)  ⇒ nil 
  

  

  


  

    
Report the result of a performance or measurement test.
The test should generally strive to maximize the reported
quantities (larger values are better than smaller ones),
this and maximized_quantity can determine sorting
order for test result reports.



  





  
Parameters:


    
  
    
  • 
      
        maximized_quantity
      
      
        (Float)
      
      
      
        —
        
    the reported value
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the format string of the report message
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    arguments to pass to the printf() function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_message(format, array)  ⇒ nil 
  

  

  


  

    
Add a message to the test report.



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the format string
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    printf-like arguments to format
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_minimized_result(minimized_quantity, format, array)  ⇒ nil 
  

  

  


  

    
Report the result of a performance or measurement test.
The test should generally strive to minimize the reported
quantities (smaller values are better than larger ones),
this and minimized_quantity can determine sorting
order for test result reports.



  





  
Parameters:


    
  
    
  • 
      
        minimized_quantity
      
      
        (Float)
      
      
      
        —
        
    the reported value
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the format string of the report message
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    arguments to pass to the printf() function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_queue_destroy(destroy_func, destroy_data)  ⇒ nil 
  

  

  


  

    
Enqueues a callback destroy_func to be executed during the next test case
teardown phase.


This is most useful to auto destroy allocated test resources at the end of a
test run. Resources are released in reverse queue order, that means
enqueueing callback A before callback B will cause B() to be called
before A() during teardown.



  





  
Parameters:


    
  
    
  • 
      
        destroy_func
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    Destroy callback for teardown phase.
    

    
      
    
    • 
  
    
  • 
      
        destroy_data
      
      
        (GObject)
      
      
      
        —
        
    Destroy callback data.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_queue_free(gfree_pointer)  ⇒ nil 
  

  

  


  

    
Enqueue a pointer to be released with g_free() during the next
teardown phase. This is equivalent to calling g_test_queue_destroy()
with a destroy callback of g_free().



  





  
Parameters:


    
  
    
  • 
      
        gfree_pointer
      
      
        (GObject)
      
      
      
        —
        
    the pointer to be stored.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_rand_double  ⇒ Float 
  

  

  


  

    
Get a reproducible random floating point number,
see g_test_rand_int() for details on test case random numbers.



  





  

Returns:


    
  
    
  • 
      
      
        (Float)
      
      
      
        —
        
    a random number from the seeded random number generator.
    

    
      
    
    • 
  







    
      

  

  
    #test_rand_double_range(range_start, range_end)  ⇒ Float 
  

  

  


  

    
Get a reproducible random floating pointer number out of a specified range,
see g_test_rand_int() for details on test case random numbers.



  





  
Parameters:


    
  
    
  • 
      
        range_start
      
      
        (Float)
      
      
      
        —
        
    the minimum value returned by this function
    

    
      
    
    • 
  
    
  • 
      
        range_end
      
      
        (Float)
      
      
      
        —
        
    the minimum value not returned by this function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Float)
      
      
      
        —
        
    a number with range_start <= number < range_end.
    

    
      
    
    • 
  







    
      

  

  
    #test_rand_int  ⇒ Integer 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a random number from the seeded random number generator.
    

    
      
    
    • 
  







    
      

  

  
    #test_rand_int_range(begin, end)  ⇒ Integer 
  

  

  


  

    
Get a reproducible random integer number out of a specified range,
see g_test_rand_int() for details on test case random numbers.



  





  
Parameters:


    
  
    
  • 
      
        begin
      
      
        (Integer)
      
      
      
        —
        
    the minimum value returned by this function
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (Integer)
      
      
      
        —
        
    the smallest value not to be returned by this function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a number with begin <= number < end.
    

    
      
    
    • 
  







    
      

  

  
    #test_run  ⇒ Integer 
  

  

  


  

    
Runs all tests under the toplevel suite which can be retrieved
with g_test_get_root(). Similar to g_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().
g_test_run_suite() or g_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 g_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.



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 on success, 1 on failure (assuming it returns at all),
0 or 77 if all tests were skipped with g_test_skip() and/or
g_test_incomplete()
    

    
      
    
    • 
  







    
      

  

  
    #test_run_suite(suite)  ⇒ Integer 
  

  

  


  

    
Execute the tests within suite and all nested GTest::Suites.
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 g_test_run() documentation for more
information on the order that tests are run in.


g_test_run_suite() or g_test_run() may only be called once
in a program.



  





  
Parameters:


    
  
    
  • 
      
        suite
      
      
        (GLib::TestSuite)
      
      
      
        —
        
    a GTest::Suite
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 on success
    

    
      
    
    • 
  







    
      

  

  
    #test_set_nonfatal_assertions  ⇒ nil 
  

  

  


  

    
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 g_test_fail() and continue. (This also changes the behavior of
g_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().



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_skip(msg)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        msg
      
      
        (String)
      
      
      
        —
        
    explanation
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_skip_printf(format, array)  ⇒ nil 
  

  

  


  

    
Equivalent to g_test_skip(), but the explanation is formatted
as if by g_strdup_printf().



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    the format string
    

    
      
    
    • 
  
    
  • 
      
        array
      
      
        (Array)
      
      
      
        —
        
    printf-like arguments to format
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_subprocess  ⇒ Boolean 
  

  

  


  

    
Returns true (after g_test_init() has been called) if the test
program is running under g_test_trap_subprocess().
g_test_trap_subprocess().



  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the test program is running under
    

    
      
    
    • 
  







    
      

  

  
    #test_summary(summary)  ⇒ nil 
  

  

  


  

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

  …
}




  





  
Parameters:


    
  
    
  • 
      
        summary
      
      
        (String)
      
      
      
        —
        
    One or two sentences summarising what the test checks, and how it
checks it.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_timer_elapsed  ⇒ Float 
  

  

  


  

    
Get the number of seconds since the last start of the timer with
g_test_timer_start().



  





  

Returns:


    
  
    
  • 
      
      
        (Float)
      
      
      
        —
        
    the time since the last start of the timer in seconds, as a double
    

    
      
    
    • 
  







    
      

  

  
    #test_timer_last  ⇒ Float 
  

  

  


  

    
Report the last result of g_test_timer_elapsed().



  





  

Returns:


    
  
    
  • 
      
      
        (Float)
      
      
      
        —
        
    the last result of g_test_timer_elapsed(), as a double
    

    
      
    
    • 
  







    
      

  

  
    #test_timer_start  ⇒ nil 
  

  

  


  

    
Start a timing test. Call g_test_timer_elapsed() when the task is supposed
to be done. Call this function again to restart the timer.



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_trap_assertions(domain, file, line, func, assertion_flags, pattern)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        assertion_flags
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        pattern
      
      
        (String)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_trap_fork(usec_timeout, test_trap_flags)  ⇒ Boolean 
  

  

  


  

    
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 GTest::TrapFlags 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*");
  }




  





  
Parameters:


    
  
    
  • 
      
        usec_timeout
      
      
        (Integer)
      
      
      
        —
        
    Timeout for the forked test in micro seconds.
    

    
      
    
    • 
  
    
  • 
      
        test_trap_flags
      
      
        (GLib::TestTrapFlags)
      
      
      
        —
        
    Flags to modify forking behaviour.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true for the forked child and false for the executing parent process.
    

    
      
    
    • 
  







    
      

  

  
    #test_trap_has_passed  ⇒ Boolean 
  

  

  


  

    
Check the result of the last g_test_trap_subprocess() call.



  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the last test subprocess terminated successfully.
    

    
      
    
    • 
  







    
      

  

  
    #test_trap_reached_timeout  ⇒ Boolean 
  

  

  


  

    
Check the result of the last g_test_trap_subprocess() call.



  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the last test subprocess got killed due to a timeout.
    

    
      
    
    • 
  







    
      

  

  
    #test_trap_subprocess(test_path, usec_timeout, test_flags)  ⇒ nil 
  

  

  


  

    
Respawns the test program to run only test_path in a subprocess.


This is equivalent to calling g_test_trap_subprocess_with_envp() with envp
set to nil. See the documentation for that function for full details.



  





  
Parameters:


    
  
    
  • 
      
        test_path
      
      
        (String)
      
      
      
        —
        
    Test to run in a subprocess
    

    
      
    
    • 
  
    
  • 
      
        usec_timeout
      
      
        (Integer)
      
      
      
        —
        
    Timeout for the subprocess test in micro seconds.
    

    
      
    
    • 
  
    
  • 
      
        test_flags
      
      
        (GLib::TestSubprocessFlags)
      
      
      
        —
        
    Flags to modify subprocess behaviour.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #test_trap_subprocess_with_envp(test_path, envp, usec_timeout, test_flags)  ⇒ nil 
  

  

  


  

    
Respawns the test program to run only test_path in a subprocess with the
given envp environment.


This can be used for a test case that might not return, or that
might abort.


If test_path is nil then the same test is re-run in a subprocess.
You can use g_test_subprocess() to determine whether the test is in
a subprocess or not.


test_path can also be the name of the parent test, followed by
"/subprocess/" and then a name for the specific subtest (or just
ending with "/subprocess" if the test only has one child test);
tests with names of this form will automatically be skipped in the
parent process.


If envp is nil, the parent process’ environment will be inherited.


If usec_timeout is non-0, the test subprocess is aborted and
considered failing if its run time exceeds it.


The subprocess behavior can be configured with the
GTest::SubprocessFlags 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 g_test_subprocess() (after calling
g_test_init()) to see whether you are in a subprocess.


Internally, this function tracks the child process using
g_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*");
  }

  static void
  test_different_username (void)
  {
    if (g_test_subprocess ())
      {
        // Code under test goes here
        g_message ("Username is now simulated as %s", g_getenv ("USER"));
        return;
      }

    // Reruns this same test in a subprocess
    g_autoptr(GStrv) envp = g_get_environ ();
    envp = g_environ_setenv (g_steal_pointer (&envp), "USER", "charlie", TRUE);
    g_test_trap_subprocess_with_envp (NULL, envp, 0, G_TEST_SUBPROCESS_DEFAULT);
    g_test_trap_assert_passed ();
    g_test_trap_assert_stdout ("Username is now simulated as charlie");
  }

  int
  main (int argc, char **argv)
  {
    g_test_init (&argc, &argv, NULL);

    g_test_add_func ("/myobject/create-large-object",
                     test_create_large_object);
    g_test_add_func ("/myobject/different-username",
                     test_different_username);
    return g_test_run ();
  }




  





  
Parameters:


    
  
    
  • 
      
        test_path
      
      
        (String)
      
      
      
        —
        
    Test to run in a subprocess
    

    
      
    
    • 
  
    
  • 
      
        envp
      
      
        (Array<GLib::filename>)
      
      
      
        —
        
    Environment
to run the test in, or nil to inherit the parent’s environment. This must
be in the GLib filename encoding.
    

    
      
    
    • 
  
    
  • 
      
        usec_timeout
      
      
        (Integer)
      
      
      
        —
        
    Timeout for the subprocess test in micro seconds.
    

    
      
    
    • 
  
    
  • 
      
        test_flags
      
      
        (GLib::TestSubprocessFlags)
      
      
      
        —
        
    Flags to modify subprocess behaviour.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #thread_create(func, data, joinable)  ⇒ GLib::Thread 
  

  

  


  

    
This function creates a new thread.


The new thread executes the function func with the argument data.
If the thread was created successfully, it is returned.


error can be nil to ignore errors, or non-nil to report errors.
The error is set, if and only if the function returns nil.


This function returns a reference to the created thread only if
joinable is true.  In that case, you must free this reference by
calling g_thread_unref() or g_thread_join().  If joinable is false
then you should probably not touch the return value.



  





  
Parameters:


    
  
    
  • 
      
        func
      
      
        (GLib::ThreadFunc)
      
      
      
        —
        
    a function to execute in the new thread
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    an argument to supply to the new thread
    

    
      
    
    • 
  
    
  • 
      
        joinable
      
      
        (Boolean)
      
      
      
        —
        
    should this thread be joinable?
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Thread)
      
      
      
        —
        
    the new #GThread on success
    

    
      
    
    • 
  







    
      

  

  
    #thread_create_full(func, data, stack_size, joinable, bound, priority)  ⇒ GLib::Thread 
  

  

  


  

    
This function creates a new thread.



  





  
Parameters:


    
  
    
  • 
      
        func
      
      
        (GLib::ThreadFunc)
      
      
      
        —
        
    a function to execute in the new thread.
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    an argument to supply to the new thread.
    

    
      
    
    • 
  
    
  • 
      
        stack_size
      
      
        (GLib::gulong)
      
      
      
        —
        
    a stack size for the new thread.
    

    
      
    
    • 
  
    
  • 
      
        joinable
      
      
        (Boolean)
      
      
      
        —
        
    should this thread be joinable?
    

    
      
    
    • 
  
    
  • 
      
        bound
      
      
        (Boolean)
      
      
      
        —
        
    ignored
    

    
      
    
    • 
  
    
  • 
      
        priority
      
      
        (GLib::ThreadPriority)
      
      
      
        —
        
    ignored
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Thread)
      
      
      
        —
        
    the new #GThread on success.
    

    
      
    
    • 
  







    
      

  

  
    #thread_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #thread_exit(retval)  ⇒ nil 
  

  

  


  

    
Terminates the current thread.


If another thread is waiting for us using g_thread_join() then the
waiting thread will be woken up and get retval as the return value
of g_thread_join().


Calling g_thread_exit() with a parameter retval is equivalent to
returning retval from the function func, as given to g_thread_new().


You must only call g_thread_exit() from a thread that you created
yourself with g_thread_new() or related APIs. You must not call
this function from a thread created with another threading library
or or from within a GThread::Pool.



  





  
Parameters:


    
  
    
  • 
      
        retval
      
      
        (GObject)
      
      
      
        —
        
    the return value of this thread
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #thread_foreach(thread_func, user_data)  ⇒ nil 
  

  

  


  

    
Call thread_func on all #GThreads that have been
created with g_thread_create().


Note that threads may decide to exit while thread_func is
running, so without intimate knowledge about the lifetime of
foreign threads, thread_func shouldn't access the GThread*
pointer passed in as first argument. However, thread_func will
not be called for threads which are known to have exited already.


Due to thread lifetime checks, this function has an execution complexity
which is quadratic in the number of existing threads.



  





  
Parameters:


    
  
    
  • 
      
        thread_func
      
      
        (GLib::Func)
      
      
      
        —
        
    function to call for all #GThread structures
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    second argument to thread_func
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #thread_get_initialized  ⇒ Boolean 
  

  

  


  

    
Indicates if g_thread_init() has been called.



  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if threads have been initialized.
    

    
      
    
    • 
  







    
      

  

  
    #thread_init(vtable)  ⇒ nil 
  

  

  


  

    
If you use GLib from more than one thread, you must initialize the
thread system by calling g_thread_init().


Since version 2.24, calling g_thread_init() multiple times is allowed,
but nothing happens except for the first call.


Since version 2.32, GLib does not support custom thread implementations
anymore and the vtable parameter is ignored and you should pass nil.


g_thread_init() must not be called directly or indirectly
in a callback from GLib. Also no mutexes may be currently locked while
calling g_thread_init().


To use g_thread_init() in your program, you have to link
with the libraries that the command pkg-config --libs
gthread-2.0 outputs. This is not the case for all the
other thread-related functions of GLib. Those can be used without
having to link with the thread libraries.



  





  
Parameters:


    
  
    
  • 
      
        vtable
      
      
        (GObject)
      
      
      
        —
        
    a function table of type GThread::Functions, that provides
the entry points to the thread system to be used. Since 2.32,
this parameter is ignored and should always be nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #thread_init_with_errorcheck_mutexes(vtable)  ⇒ nil 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        vtable
      
      
        (GObject)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #thread_pool_get_max_idle_time  ⇒ Integer 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the maximum interval (milliseconds) to wait
for new tasks in the thread pool before stopping the
thread
    

    
      
    
    • 
  







    
      

  

  
    #thread_pool_get_max_unused_threads  ⇒ Integer 
  

  

  


  

    
Returns the maximal allowed number of unused threads.



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the maximal number of unused threads
    

    
      
    
    • 
  







    
      

  

  
    #thread_pool_get_num_unused_threads  ⇒ Integer 
  

  

  


  

    
Returns the number of currently unused threads.



  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of currently unused threads
    

    
      
    
    • 
  







    
      

  

  
    #thread_pool_set_max_idle_time(interval)  ⇒ nil 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the maximum interval (in milliseconds)
a thread can be idle
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #thread_pool_set_max_unused_threads(max_threads)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        max_threads
      
      
        (Integer)
      
      
      
        —
        
    maximal number of unused threads
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #thread_pool_stop_unused_threads  ⇒ nil 
  

  

  


  

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



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #thread_self  ⇒ GLib::Thread 
  

  

  


  

    
This function returns the #GThread corresponding to the
current thread. Note that this function does not increase
the reference count of the returned struct.


This function will return a #GThread 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 g_thread_join()) on these threads.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Thread)
      
      
      
        —
        
    the #GThread representing the current thread
    

    
      
    
    • 
  







    
      

  

  
    #thread_yield  ⇒ nil 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #time_val_from_iso8601(iso_date, time_)  ⇒ Boolean 
  

  

  


  

    
Converts a string containing an ISO 8601 encoded date and time
to a GTime::Val 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 GTime::Val 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);
]|



  





  
Parameters:


    
  
    
  • 
      
        iso_date
      
      
        (String)
      
      
      
        —
        
    an ISO 8601 encoded date string
    

    
      
    
    • 
  
    
  • 
      
        time_
      
      
        (GLib::TimeVal)
      
      
      
        —
        
    a GTime::Val
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the conversion was successful.
    

    
      
    
    • 
  







    
      

  

  
    #timeout_add(interval, function, data)  ⇒ Integer 
  

  

  


  

    
Sets a function to be called at regular intervals, with the default
priority, %G_PRIORITY_DEFAULT.


The given function is called repeatedly until it returns %G_SOURCE_REMOVE
or false, at which point the timeout is automatically destroyed and the
function will not be called again. The first call to the function will be
at the end of the first interval.


Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to 'catch up' time lost in delays).


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


If you want to have a timer in the "seconds" range and do not care
about the exact time of the first call of the timer, use the
g_timeout_add_seconds() function; this function allows for more
optimizations and more efficient system power usage.


This internally creates a main loop source using g_timeout_source_new()
and attaches it to the global GMain::Context using g_source_attach(), so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.


It is safe to call this function from any thread.


The interval given is in terms of monotonic time, not wall clock
time.  See g_get_monotonic_time().



  





  
Parameters:


    
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the time between calls to the function, in milliseconds
(1/1000ths of a second)
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::SourceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source.
    

    
      
    
    • 
  







    
      

  

  
    #timeout_add_full(priority, interval, function, data, notify)  ⇒ Integer 
  

  

  


  

    
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][mainloop-memory-management] for details
on how to handle the return value and memory management of data.


This internally creates a main loop source using g_timeout_source_new()
and attaches it to the global GMain::Context using g_source_attach(), so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.


The interval given is in terms of monotonic time, not wall clock time.
See g_get_monotonic_time().



  





  
Parameters:


    
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
        —
        
    the priority of the timeout source. Typically this will be in
the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
    

    
      
    
    • 
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the time between calls to the function, in milliseconds
(1/1000ths of a second)
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::SourceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  
    
  • 
      
        notify
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    function to call when the timeout is removed, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source.
    

    
      
    
    • 
  







    
      

  

  
    #timeout_add_once(interval, function, data)  ⇒ Integer 
  

  

  


  

    
Sets a function to be called after interval milliseconds have elapsed,
with the default priority, %G_PRIORITY_DEFAULT.


The given function is called once and then the source will be automatically
removed from the main context.


This function otherwise behaves like g_timeout_add().



  





  
Parameters:


    
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the time after which the function will be called, in
milliseconds (1/1000ths of a second)
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::SourceOnceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source
    

    
      
    
    • 
  







    
      

  

  
    #timeout_add_seconds(interval, function, data)  ⇒ Integer 
  

  

  


  

    
Sets a function to be called at regular intervals with the default
priority, %G_PRIORITY_DEFAULT.


The function is called repeatedly until it returns %G_SOURCE_REMOVE
or false, at which point the timeout is automatically destroyed
and the function will not be called again.


This internally creates a main loop source using
g_timeout_source_new_seconds() and attaches it to the main loop context
using g_source_attach(). You can do these steps manually if you need
greater control. Also see g_timeout_add_seconds_full().


It is safe to call this function from any thread.


Note that the first call of the timer may not be precise for timeouts
of one second. If you need finer precision and have such a timeout,
you may want to use g_timeout_add() instead.


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


The interval given is in terms of monotonic time, not wall clock
time.  See g_get_monotonic_time().



  





  
Parameters:


    
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the time between calls to the function, in seconds
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::SourceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source.
    

    
      
    
    • 
  







    
      

  

  
    #timeout_add_seconds_full(priority, interval, function, data, notify)  ⇒ Integer 
  

  

  


  

    
Sets a function to be called at regular intervals, with priority.


The function is called repeatedly until it returns %G_SOURCE_REMOVE
or false, at which point the timeout is automatically destroyed and
the function will not be called again.


Unlike g_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][mainloop-memory-management] for details
on how to handle the return value and memory management of data.


If you want timing more precise than whole seconds, use g_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 g_timeout_add_seconds() is preferred over g_timeout_add().


This internally creates a main loop source using
g_timeout_source_new_seconds() and attaches it to the main loop context
using g_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 g_get_monotonic_time().



  





  
Parameters:


    
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
        —
        
    the priority of the timeout source. Typically this will be in
the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
    

    
      
    
    • 
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the time between calls to the function, in seconds
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::SourceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  
    
  • 
      
        notify
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    function to call when the timeout is removed, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source.
    

    
      
    
    • 
  







    
      

  

  
    #timeout_add_seconds_once(interval, function, data)  ⇒ Integer 
  

  

  


  

    
This function behaves like g_timeout_add_once() but with a range in seconds.



  





  
Parameters:


    
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the time after which the function will be called, in seconds
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::SourceOnceFunc)
      
      
      
        —
        
    function to call
    

    
      
    
    • 
  
    
  • 
      
        data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source
    

    
      
    
    • 
  







    
      

  

  
    #timeout_source_new(interval)  ⇒ GLib::Source 
  

  

  


  

    
Creates a new timeout source.


The source will not initially be associated with any GMain::Context
and must be added to one with g_source_attach() before it will be
executed.


The interval given is in terms of monotonic time, not wall clock
time.  See g_get_monotonic_time().



  





  
Parameters:


    
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the timeout interval in milliseconds.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Source)
      
      
      
        —
        
    the newly-created timeout source
    

    
      
    
    • 
  







    
      

  

  
    #timeout_source_new_seconds(interval)  ⇒ GLib::Source 
  

  

  


  

    
Creates a new timeout source.


The source will not initially be associated with any GMain::Context
and must be added to one with g_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 g_get_monotonic_time().



  





  
Parameters:


    
  
    
  • 
      
        interval
      
      
        (Integer)
      
      
      
        —
        
    the timeout interval in seconds
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Source)
      
      
      
        —
        
    the newly-created timeout source
    

    
      
    
    • 
  







    
      

  

  
    #tmp_dir  ⇒ GLib::filename 
  

  

  


  

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



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the directory to use for temporary files.
    

    
      
    
    • 
  







    
      

  

  
    #trash_stack_height(stack_p)  ⇒ Integer 
  

  

  


  

    
Returns the height of a GTrash::Stack.


Note that execution of this function is of O(N) complexity
where N denotes the number of items on the stack.



  





  
Parameters:


    
  
    
  • 
      
        stack_p
      
      
        (GLib::TrashStack)
      
      
      
        —
        
    a GTrash::Stack
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the height of the stack
    

    
      
    
    • 
  







    
      

  

  
    #trash_stack_peek(stack_p)  ⇒ GObject 
  

  

  


  

    
Returns the element at the top of a GTrash::Stack
which may be nil.



  





  
Parameters:


    
  
    
  • 
      
        stack_p
      
      
        (GLib::TrashStack)
      
      
      
        —
        
    a GTrash::Stack
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the element at the top of the stack
    

    
      
    
    • 
  







    
      

  

  
    #trash_stack_pop(stack_p)  ⇒ GObject 
  

  

  


  

    
Pops a piece of memory off a GTrash::Stack.



  





  
Parameters:


    
  
    
  • 
      
        stack_p
      
      
        (GLib::TrashStack)
      
      
      
        —
        
    a GTrash::Stack
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the element at the top of the stack
    

    
      
    
    • 
  







    
      

  

  
    #trash_stack_push(stack_p, data_p)  ⇒ nil 
  

  

  


  

    
Pushes a piece of memory onto a GTrash::Stack.



  





  
Parameters:


    
  
    
  • 
      
        stack_p
      
      
        (GLib::TrashStack)
      
      
      
        —
        
    a GTrash::Stack
    

    
      
    
    • 
  
    
  • 
      
        data_p
      
      
        (GObject)
      
      
      
        —
        
    the piece of memory to push on the stack
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #try_malloc(n_bytes)  ⇒ GObject 
  

  

  


  

    
Attempts to allocate n_bytes, and returns nil on failure.
Contrast with g_malloc(), which aborts the program on failure.



  





  
Parameters:


    
  
    
  • 
      
        n_bytes
      
      
        (Integer)
      
      
      
        —
        
    number of bytes to allocate.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the allocated memory, or nil.
    

    
      
    
    • 
  







    
      

  

  
    #try_malloc0(n_bytes)  ⇒ GObject 
  

  

  


  

    
Attempts to allocate n_bytes, initialized to 0's, and returns nil on
failure. Contrast with g_malloc0(), which aborts the program on failure.



  





  
Parameters:


    
  
    
  • 
      
        n_bytes
      
      
        (Integer)
      
      
      
        —
        
    number of bytes to allocate
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the allocated memory, or nil
    

    
      
    
    • 
  







    
      

  

  
    #try_malloc0_n(n_blocks, n_block_bytes)  ⇒ GObject 
  

  

  


  

    
This function is similar to g_try_malloc0(), allocating (n_blocks * n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.



  





  
Parameters:


    
  
    
  • 
      
        n_blocks
      
      
        (Integer)
      
      
      
        —
        
    the number of blocks to allocate
    

    
      
    
    • 
  
    
  • 
      
        n_block_bytes
      
      
        (Integer)
      
      
      
        —
        
    the size of each block in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the allocated memory, or nil
    

    
      
    
    • 
  







    
      

  

  
    #try_malloc_n(n_blocks, n_block_bytes)  ⇒ GObject 
  

  

  


  

    
This function is similar to g_try_malloc(), allocating (n_blocks * n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.



  





  
Parameters:


    
  
    
  • 
      
        n_blocks
      
      
        (Integer)
      
      
      
        —
        
    the number of blocks to allocate
    

    
      
    
    • 
  
    
  • 
      
        n_block_bytes
      
      
        (Integer)
      
      
      
        —
        
    the size of each block in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the allocated memory, or nil.
    

    
      
    
    • 
  







    
      

  

  
    #try_realloc(mem, n_bytes)  ⇒ GObject 
  

  

  


  

    
Attempts to realloc mem to a new size, n_bytes, and returns nil
on failure. Contrast with g_realloc(), which aborts the program
on failure.


If mem is nil, behaves the same as g_try_malloc().



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    previously-allocated memory, or nil.
    

    
      
    
    • 
  
    
  • 
      
        n_bytes
      
      
        (Integer)
      
      
      
        —
        
    number of bytes to allocate.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the allocated memory, or nil.
    

    
      
    
    • 
  







    
      

  

  
    #try_realloc_n(mem, n_blocks, n_block_bytes)  ⇒ GObject 
  

  

  


  

    
This function is similar to g_try_realloc(), allocating (n_blocks * n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.



  





  
Parameters:


    
  
    
  • 
      
        mem
      
      
        (GObject)
      
      
      
        —
        
    previously-allocated memory, or nil.
    

    
      
    
    • 
  
    
  • 
      
        n_blocks
      
      
        (Integer)
      
      
      
        —
        
    the number of blocks to allocate
    

    
      
    
    • 
  
    
  • 
      
        n_block_bytes
      
      
        (Integer)
      
      
      
        —
        
    the size of each block in bytes
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    the allocated memory, or nil.
    

    
      
    
    • 
  







    
      

  

  
    #ucs4_to_utf16(str, len, items_read, items_written)  ⇒ Integer 
  

  

  


  

    
Convert a string from UCS-4 to UTF-16. A 0 character will be
added to the result after the converted text.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<String>)
      
      
      
        —
        
    a UCS-4 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::glong)
      
      
      
        —
        
    the maximum length (number of characters) of str to use.
If len < 0, then the string is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        items_read
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number of
bytes read, or nil. If an error occurs then the index of the invalid
input is stored here.
    

    
      
    
    • 
  
    
  • 
      
        items_written
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number
of #gunichar2  written, or nil. The value stored here does not include
the trailing 0.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a newly allocated UTF-16 string.
This value must be freed with g_free(). If an error occurs,
nil will be returned and error set.
    

    
      
    
    • 
  







    
      

  

  
    #ucs4_to_utf8(str, len, items_read, items_written)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<String>)
      
      
      
        —
        
    a UCS-4 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::glong)
      
      
      
        —
        
    the maximum length (number of characters) of str to use.
If len < 0, then the string is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        items_read
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number of
characters read, or nil.
    

    
      
    
    • 
  
    
  • 
      
        items_written
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number
of bytes written or nil. The value here stored does not include the
trailing 0 byte.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to a newly allocated UTF-8 string.
This value must be freed with g_free(). If an error occurs,
nil will be returned and error set. In that case, items_read
will be set to the position of the first invalid input character.
    

    
      
    
    • 
  







    
      

  

  
    #unichar_break_type(c)  ⇒ GLib::UnicodeBreakType 
  

  

  


  

    
Determines the break type of c. c should be a Unicode character
(to derive a character from UTF-8 encoded text, use
g_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.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:







    
      

  

  
    #unichar_combining_class(uc)  ⇒ Integer 
  

  

  


  

    
Determines the canonical combining class of a Unicode character.



  





  
Parameters:


    
  
    
  • 
      
        uc
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the combining class of the character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_compose(a, b, ch)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        a
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  
    
  • 
      
        b
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  
    
  • 
      
        ch
      
      
        (String)
      
      
      
        —
        
    return location for the composed character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the characters could be composed
    

    
      
    
    • 
  







    
      

  

  
    #unichar_decompose(ch, a, b)  ⇒ Boolean 
  

  

  


  

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


See
UAX#15
for details.



  





  
Parameters:


    
  
    
  • 
      
        ch
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  
    
  • 
      
        a
      
      
        (String)
      
      
      
        —
        
    return location for the first component of ch
    

    
      
    
    • 
  
    
  • 
      
        b
      
      
        (String)
      
      
      
        —
        
    return location for the second component of ch
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the character could be decomposed
    

    
      
    
    • 
  







    
      

  

  
    #unichar_digit_value(c)  ⇒ Integer 
  

  

  


  

    
Determines the numeric value of a character as a decimal
digit.
g_unichar_isdigit()), its numeric value. Otherwise, -1.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    If c is a decimal digit (according to
    

    
      
    
    • 
  







    
      

  

  
    #unichar_fully_decompose(ch, compat, result, result_len)  ⇒ Integer 
  

  

  


  

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


See
UAX#15
for details.



  





  
Parameters:


    
  
    
  • 
      
        ch
      
      
        (String)
      
      
      
        —
        
    a Unicode character.
    

    
      
    
    • 
  
    
  • 
      
        compat
      
      
        (Boolean)
      
      
      
        —
        
    whether perform canonical or compatibility decomposition
    

    
      
    
    • 
  
    
  • 
      
        result
      
      
        (String)
      
      
      
        —
        
    location to store decomposed result, or nil
    

    
      
    
    • 
  
    
  • 
      
        result_len
      
      
        (Integer)
      
      
      
        —
        
    length of result
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the length of the full decomposition.
    

    
      
    
    • 
  







    
      

  

  
    #unichar_get_mirror_char(ch, mirrored_ch)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        ch
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  
    
  • 
      
        mirrored_ch
      
      
        (String)
      
      
      
        —
        
    location to store the mirrored character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if ch has a mirrored character, false otherwise
    

    
      
    
    • 
  







    
      

  

  
    #unichar_get_script(ch)  ⇒ GLib::UnicodeScript 
  

  

  


  

    
Looks up the GUnicode::Script 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.



  





  
Parameters:


    
  
    
  • 
      
        ch
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:







    
      

  

  
    #unichar_isalnum(c)  ⇒ Boolean 
  

  

  


  

    
Determines whether a character is alphanumeric.
Given some UTF-8 text, obtain a character value
with g_utf8_get_char().



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is an alphanumeric character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_isalpha(c)  ⇒ Boolean 
  

  

  


  

    
Determines whether a character is alphabetic (i.e. a letter).
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is an alphabetic character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_iscntrl(c)  ⇒ Boolean 
  

  

  


  

    
Determines whether a character is a control character.
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is a control character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_isdefined(c)  ⇒ Boolean 
  

  

  


  

    
Determines if a given character is assigned in the Unicode
standard.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the character has an assigned value
    

    
      
    
    • 
  







    
      

  

  
    #unichar_isdigit(c)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is a digit
    

    
      
    
    • 
  







    
      

  

  
    #unichar_isgraph(c)  ⇒ Boolean 
  

  

  


  

    
Determines whether a character is printable and not a space
(returns false for control characters, format characters, and
spaces). g_unichar_isprint() is similar, but returns true for
spaces. Given some UTF-8 text, obtain a character value with
g_utf8_get_char().



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is printable unless it's a space
    

    
      
    
    • 
  







    
      

  

  
    #unichar_islower(c)  ⇒ Boolean 
  

  

  


  

    
Determines whether a character is a lowercase letter.
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is a lowercase letter
    

    
      
    
    • 
  







    
      

  

  
    #unichar_ismark(c)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is a mark character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_isprint(c)  ⇒ Boolean 
  

  

  


  

    
Determines whether a character is printable.
Unlike g_unichar_isgraph(), returns true for spaces.
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is printable
    

    
      
    
    • 
  







    
      

  

  
    #unichar_ispunct(c)  ⇒ Boolean 
  

  

  


  

    
Determines whether a character is punctuation or a symbol.
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is a punctuation or symbol character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_isspace(c)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is a space character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_istitle(c)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the character is titlecase
    

    
      
    
    • 
  







    
      

  

  
    #unichar_isupper(c)  ⇒ Boolean 
  

  

  


  

    
Determines if a character is uppercase.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if c is an uppercase character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_iswide(c)  ⇒ Boolean 
  

  

  


  

    
Determines if a character is typically rendered in a double-width
cell.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the character is wide
    

    
      
    
    • 
  







    
      

  

  
    #unichar_iswide_cjk(c)  ⇒ Boolean 
  

  

  


  

    
Determines if a character is typically rendered in a double-width
cell under legacy East Asian locales.  If a character is wide according to
g_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 g_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 g_unichar_iszerowidth().



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the character is wide in legacy East Asian locales
    

    
      
    
    • 
  







    
      

  

  
    #unichar_isxdigit(c)  ⇒ Boolean 
  

  

  


  

    
Determines if a character is a hexadecimal digit.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the character is a hexadecimal digit
    

    
      
    
    • 
  







    
      

  

  
    #unichar_iszerowidth(c)  ⇒ Boolean 
  

  

  


  

    
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 g_unichar_iswide() or
g_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.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the character has zero width
    

    
      
    
    • 
  







    
      

  

  
    #unichar_to_utf8(c, outbuf)  ⇒ Integer 
  

  

  


  

    
Converts a single character to UTF-8.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character code
    

    
      
    
    • 
  
    
  • 
      
        outbuf
      
      
        (String)
      
      
      
        —
        
    output buffer, must have at
least 6 bytes of space. If nil, the length will be computed and
returned and nothing will be written to outbuf.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    number of bytes written
    

    
      
    
    • 
  







    
      

  

  
    #unichar_tolower(c)  ⇒ String 
  

  

  


  

    
Converts a character to lower case.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    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.
    

    
      
    
    • 
  







    
      

  

  
    #unichar_totitle(c)  ⇒ String 
  

  

  


  

    
Converts a character to the titlecase.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the result of converting c to titlecase.
If c is not an uppercase or lowercase character,
c is returned unchanged.
    

    
      
    
    • 
  







    
      

  

  
    #unichar_toupper(c)  ⇒ String 
  

  

  


  

    
Converts a character to uppercase.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    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.
    

    
      
    
    • 
  







    
      

  

  
    #unichar_type(c)  ⇒ GLib::UnicodeType 
  

  

  


  

    
Classifies a Unicode character by type.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:







    
      

  

  
    #unichar_validate(ch)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        ch
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if ch is a valid Unicode character
    

    
      
    
    • 
  







    
      

  

  
    #unichar_xdigit_value(c)  ⇒ Integer 
  

  

  


  

    
Determines the numeric value of a character as a hexadecimal
digit.
g_unichar_isxdigit()), its numeric value. Otherwise, -1.



  





  
Parameters:


    
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    If c is a hex digit (according to
    

    
      
    
    • 
  







    
      

  

  
    #unicode_canonical_decomposition(ch, result_len)  ⇒ String 
  

  

  


  

    
Computes the canonical decomposition of a Unicode character.



  





  
Parameters:


    
  
    
  • 
      
        ch
      
      
        (String)
      
      
      
        —
        
    a Unicode character.
    

    
      
    
    • 
  
    
  • 
      
        result_len
      
      
        (Integer)
      
      
      
        —
        
    location to store the length of the return value.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string of Unicode characters.
result_len is set to the resulting length of the string.
    

    
      
    
    • 
  







    
      

  

  
    #unicode_canonical_ordering(string, len)  ⇒ nil 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (Array<String>)
      
      
      
        —
        
    a UCS-4 encoded string.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (Integer)
      
      
      
        —
        
    the maximum length of string to use.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #unicode_script_from_iso15924(iso15924)  ⇒ 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.



  





  
Parameters:


    
  
    
  • 
      
        iso15924
      
      
        (Integer)
      
      
      
        —
        
    a Unicode script
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::UnicodeScript)
      
      
      
        —
        
    the Unicode script for iso15924, or
of %G_UNICODE_SCRIPT_INVALID_CODE if iso15924 is zero and
%G_UNICODE_SCRIPT_UNKNOWN if iso15924 is unknown.
    

    
      
    
    • 
  







    
      

  

  
    #unicode_script_to_iso15924(script)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ISO 15924 code for script, encoded as an integer,
of zero if script is %G_UNICODE_SCRIPT_INVALID_CODE or
ISO 15924 code 'Zzzz' (script code for UNKNOWN) if script is not understood.
    

    
      
    
    • 
  







    
      

  

  
    #unix_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #unix_fd_add(fd, condition, function, user_data)  ⇒ Integer 
  

  

  


  

    
Sets a function to be called when the IO condition, as specified by
condition becomes true for fd.


function will be called when the specified IO condition becomes
true.  The function is expected to clear whatever event caused the
IO condition to become true and return true in order to be notified
when it happens again.  If function returns false then the watch
will be cancelled.


The return value of this function can be passed to g_source_remove()
to cancel the watch at any time that it exists.


The source will never close the fd -- you must do it yourself.



  





  
Parameters:


    
  
    
  • 
      
        fd
      
      
        (Integer)
      
      
      
        —
        
    a file descriptor
    

    
      
    
    • 
  
    
  • 
      
        condition
      
      
        (GLib::IOCondition)
      
      
      
        —
        
    IO conditions to watch for on fd
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::UnixFDSourceFunc)
      
      
      
        —
        
    a GUnix::FDSourceFunc
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source
    

    
      
    
    • 
  







    
      

  

  
    #unix_fd_add_full(priority, fd, condition, function, user_data, notify)  ⇒ Integer 
  

  

  


  

    
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 GDestroy::Notify for
user_data.



  





  
Parameters:


    
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
        —
        
    the priority of the source
    

    
      
    
    • 
  
    
  • 
      
        fd
      
      
        (Integer)
      
      
      
        —
        
    a file descriptor
    

    
      
    
    • 
  
    
  • 
      
        condition
      
      
        (GLib::IOCondition)
      
      
      
        —
        
    IO conditions to watch for on fd
    

    
      
    
    • 
  
    
  • 
      
        function
      
      
        (GLib::UnixFDSourceFunc)
      
      
      
        —
        
    a GUnix::FDSourceFunc
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    data to pass to function
    

    
      
    
    • 
  
    
  • 
      
        notify
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    function to call when the idle is removed, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the ID (greater than 0) of the event source
    

    
      
    
    • 
  







    
      

  

  
    #unix_fd_source_new(fd, condition)  ⇒ GLib::Source 
  

  

  


  

    
Creates a #GSource 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 #GSource must have type
GUnix::FDSourceFunc.



  





  
Parameters:


    
  
    
  • 
      
        fd
      
      
        (Integer)
      
      
      
        —
        
    a file descriptor
    

    
      
    
    • 
  
    
  • 
      
        condition
      
      
        (GLib::IOCondition)
      
      
      
        —
        
    I/O conditions to watch for on fd
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Source)
      
      
      
        —
        
    the newly created #GSource
    

    
      
    
    • 
  







    
      

  

  
    #unix_get_passwd_entry(user_name)  ⇒ GObject 
  

  

  


  

    
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 g_malloc() and should
be freed using g_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.



  





  
Parameters:


    
  
    
  • 
      
        user_name
      
      
        (String)
      
      
      
        —
        
    the username to get the passwd file entry for
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GObject)
      
      
      
        —
        
    passwd entry, or nil on error; free the returned
value with g_free()
    

    
      
    
    • 
  







    
      

  

  
    #unix_open_pipe(fds, flags)  ⇒ Boolean 
  

  

  


  

    
Similar to the UNIX pipe() call, but on modern systems like Linux
uses the pipe2() system call, which atomically creates a pipe with
the configured flags.


As of GLib 2.78, the supported flags are O_CLOEXEC/FD_CLOEXEC (see below)
and O_NONBLOCK. Prior to GLib 2.78, only FD_CLOEXEC was supported — if
you wanted to configure O_NONBLOCK then that had to be done separately with
fcntl().


Since GLib 2.80, the constants %G_UNIX_PIPE_END_READ and
%G_UNIX_PIPE_END_WRITE can be used as mnemonic indexes in fds.


It is a programmer error to call this function with unsupported flags, and a
critical warning will be raised.


As of GLib 2.78, it is preferred to pass O_CLOEXEC in, rather than
FD_CLOEXEC, as that matches the underlying pipe() API more closely. Prior
to 2.78, only FD_CLOEXEC was supported. Support for FD_CLOEXEC may be
deprecated and removed in future.



  





  
Parameters:


    
  
    
  • 
      
        fds
      
      
        (Array<Integer>)
      
      
      
        —
        
    Array of two integers
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (Integer)
      
      
      
        —
        
    Bitfield of file descriptor flags, as for fcntl()
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true on success, false if not (and errno will be set).
    

    
      
    
    • 
  







    
      

  

  
    #unix_set_fd_nonblocking(fd, nonblock)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        fd
      
      
        (Integer)
      
      
      
        —
        
    A file descriptor
    

    
      
    
    • 
  
    
  • 
      
        nonblock
      
      
        (Boolean)
      
      
      
        —
        
    If true, set the descriptor to be non-blocking
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if successful
    

    
      
    
    • 
  







    
      

  

  
    #unix_signal_add(signum, handler, user_data)  ⇒ Integer 
  

  

  


  

    
A convenience function for g_unix_signal_source_new(), which
attaches to the default GMain::Context.  You can remove the watch
using g_source_remove().



  





  
Parameters:


    
  
    
  • 
      
        signum
      
      
        (Integer)
      
      
      
        —
        
    Signal number
    

    
      
    
    • 
  
    
  • 
      
        handler
      
      
        (GLib::SourceFunc)
      
      
      
        —
        
    Callback
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    Data for handler
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    An ID (greater than 0) for the event source
    

    
      
    
    • 
  







    
      

  

  
    #unix_signal_add_full(priority, signum, handler, user_data, notify)  ⇒ Integer 
  

  

  


  

    
A convenience function for g_unix_signal_source_new(), which
attaches to the default GMain::Context.  You can remove the watch
using g_source_remove().



  





  
Parameters:


    
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
        —
        
    the priority of the signal source. Typically this will be in
the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
    

    
      
    
    • 
  
    
  • 
      
        signum
      
      
        (Integer)
      
      
      
        —
        
    Signal number
    

    
      
    
    • 
  
    
  • 
      
        handler
      
      
        (GLib::SourceFunc)
      
      
      
        —
        
    Callback
    

    
      
    
    • 
  
    
  • 
      
        user_data
      
      
        (GObject)
      
      
      
        —
        
    Data for handler
    

    
      
    
    • 
  
    
  • 
      
        notify
      
      
        (GLib::DestroyNotify)
      
      
      
        —
        
    GDestroy::Notify for handler
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    An ID (greater than 0) for the event source
    

    
      
    
    • 
  







    
      

  

  
    #unix_signal_source_new(signum)  ⇒ GLib::Source 
  

  

  


  

    
Create a #GSource 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 g_unix_signal_source_new().


For example, an effective use of this function is to handle SIGTERM
cleanly; flushing any outstanding files, and then calling
g_main_loop_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 GMain::Context
and must be added to one with g_source_attach() before it will be
executed.



  





  
Parameters:


    
  
    
  • 
      
        signum
      
      
        (Integer)
      
      
      
        —
        
    A signal number
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Source)
      
      
      
        —
        
    A newly created #GSource
    

    
      
    
    • 
  







    
      

  

  
    #unlink(filename)  ⇒ Integer 
  

  

  


  

    
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.



  





  
Parameters:


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

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the name was successfully deleted, -1 if an error
occurred
    

    
      
    
    • 
  







    
      

  

  
    #unsetenv(variable)  ⇒ nil 
  

  

  


  

    
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 g_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 g_get_environ() to get an environment array, modify that with
g_environ_setenv() and g_environ_unsetenv(), and then pass that
array directly to execvpe(), g_spawn_async(), or the like.



  





  
Parameters:


    
  
    
  • 
      
        variable
      
      
        (GLib::filename)
      
      
      
        —
        
    the environment variable to remove, must
not contain '='
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #uri_build(flags, scheme, userinfo, host, port, path, query, fragment)  ⇒ GLib::Uri 
  

  

  


  

    
Creates a new #GUri from the given components according to flags.


See also g_uri_build_with_user(), which allows specifying the
components of the "userinfo" separately.



  





  
Parameters:


    
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags describing how to build the #GUri
    

    
      
    
    • 
  
    
  • 
      
        scheme
      
      
        (String)
      
      
      
        —
        
    the URI scheme
    

    
      
    
    • 
  
    
  • 
      
        userinfo
      
      
        (String)
      
      
      
        —
        
    the userinfo component, or nil
    

    
      
    
    • 
  
    
  • 
      
        host
      
      
        (String)
      
      
      
        —
        
    the host component, or nil
    

    
      
    
    • 
  
    
  • 
      
        port
      
      
        (Integer)
      
      
      
        —
        
    the port, or -1
    

    
      
    
    • 
  
    
  • 
      
        path
      
      
        (String)
      
      
      
        —
        
    the path component
    

    
      
    
    • 
  
    
  • 
      
        query
      
      
        (String)
      
      
      
        —
        
    the query component, or nil
    

    
      
    
    • 
  
    
  • 
      
        fragment
      
      
        (String)
      
      
      
        —
        
    the fragment, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Uri)
      
      
      
        —
        
    a new #GUri
    

    
      
    
    • 
  







    
      

  

  
    #uri_build_with_user(flags, scheme, user, password, auth_params, host, port, path, query, fragment)  ⇒ GLib::Uri 
  

  

  


  

    
Creates a new #GUri from the given components according to flags
(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The flags must be
coherent with the passed values, in particular use %-encoded values with
%G_URI_FLAGS_ENCODED.


In contrast to g_uri_build(), this allows specifying the components
of the ‘userinfo’ field separately. Note that user must be non-nil
if either password or auth_params is non-nil.



  





  
Parameters:


    
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags describing how to build the #GUri
    

    
      
    
    • 
  
    
  • 
      
        scheme
      
      
        (String)
      
      
      
        —
        
    the URI scheme
    

    
      
    
    • 
  
    
  • 
      
        user
      
      
        (String)
      
      
      
        —
        
    the user component of the userinfo, or nil
    

    
      
    
    • 
  
    
  • 
      
        password
      
      
        (String)
      
      
      
        —
        
    the password component of the userinfo, or nil
    

    
      
    
    • 
  
    
  • 
      
        auth_params
      
      
        (String)
      
      
      
        —
        
    the auth params of the userinfo, or nil
    

    
      
    
    • 
  
    
  • 
      
        host
      
      
        (String)
      
      
      
        —
        
    the host component, or nil
    

    
      
    
    • 
  
    
  • 
      
        port
      
      
        (Integer)
      
      
      
        —
        
    the port, or -1
    

    
      
    
    • 
  
    
  • 
      
        path
      
      
        (String)
      
      
      
        —
        
    the path component
    

    
      
    
    • 
  
    
  • 
      
        query
      
      
        (String)
      
      
      
        —
        
    the query component, or nil
    

    
      
    
    • 
  
    
  • 
      
        fragment
      
      
        (String)
      
      
      
        —
        
    the fragment, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Uri)
      
      
      
        —
        
    a new #GUri
    

    
      
    
    • 
  







    
      

  

  
    #uri_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #uri_escape_bytes(unescaped, length, reserved_chars_allowed)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        unescaped
      
      
        (Array<Integer>)
      
      
      
        —
        
    the unescaped input data.
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (Integer)
      
      
      
        —
        
    the length of unescaped
    

    
      
    
    • 
  
    
  • 
      
        reserved_chars_allowed
      
      
        (String)
      
      
      
        —
        
    a string of reserved
characters that are allowed to be used, or nil.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    an escaped version of unescaped.
The returned string should be freed when no longer needed.
    

    
      
    
    • 
  







    
      

  

  
    #uri_escape_string(unescaped, reserved_chars_allowed, allow_utf8)  ⇒ String 
  

  

  


  

    
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.
returned string should be freed when no longer needed.



  





  
Parameters:


    
  
    
  • 
      
        unescaped
      
      
        (String)
      
      
      
        —
        
    the unescaped input string.
    

    
      
    
    • 
  
    
  • 
      
        reserved_chars_allowed
      
      
        (String)
      
      
      
        —
        
    a string of reserved
characters that are allowed to be used, or nil.
    

    
      
    
    • 
  
    
  • 
      
        allow_utf8
      
      
        (Boolean)
      
      
      
        —
        
    true if the result can include UTF-8 characters.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    an escaped version of unescaped. The
    

    
      
    
    • 
  







    
      

  

  
    #uri_is_valid(uri_string, flags)  ⇒ Boolean 
  

  

  


  

    
Parses uri_string according to flags, to determine whether it is a valid
absolute URI, i.e. it does not need to be resolved
relative to another URI using g_uri_parse_relative().


If it’s not a valid URI, an error is returned explaining how it’s invalid.


See g_uri_split(), and the definition of GUri::Flags, for more
information on the effect of flags.



  





  
Parameters:


    
  
    
  • 
      
        uri_string
      
      
        (String)
      
      
      
        —
        
    a string containing an absolute URI
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags for parsing uri_string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if uri_string is a valid absolute URI, false on error.
    

    
      
    
    • 
  







    
      

  

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

  

  


  

    
Joins the given components together according to flags to create
an absolute URI string. path may not be nil (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 g_uri_join_with_user(), which allows specifying the
components of the ‘userinfo’ separately.


%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
in flags.



  





  
Parameters:


    
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags describing how to build the URI string
    

    
      
    
    • 
  
    
  • 
      
        scheme
      
      
        (String)
      
      
      
        —
        
    the URI scheme, or nil
    

    
      
    
    • 
  
    
  • 
      
        userinfo
      
      
        (String)
      
      
      
        —
        
    the userinfo component, or nil
    

    
      
    
    • 
  
    
  • 
      
        host
      
      
        (String)
      
      
      
        —
        
    the host component, or nil
    

    
      
    
    • 
  
    
  • 
      
        port
      
      
        (Integer)
      
      
      
        —
        
    the port, or -1
    

    
      
    
    • 
  
    
  • 
      
        path
      
      
        (String)
      
      
      
        —
        
    the path component
    

    
      
    
    • 
  
    
  • 
      
        query
      
      
        (String)
      
      
      
        —
        
    the query component, or nil
    

    
      
    
    • 
  
    
  • 
      
        fragment
      
      
        (String)
      
      
      
        —
        
    the fragment, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    an absolute URI string
    

    
      
    
    • 
  







    
      

  

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

  

  


  

    
Joins the given components together according to flags to create
an absolute URI string. path may not be nil (though it may be the empty
string).


In contrast to g_uri_join(), this allows specifying the components
of the ‘userinfo’ separately. It otherwise behaves the same.


%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
in flags.



  





  
Parameters:


    
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags describing how to build the URI string
    

    
      
    
    • 
  
    
  • 
      
        scheme
      
      
        (String)
      
      
      
        —
        
    the URI scheme, or nil
    

    
      
    
    • 
  
    
  • 
      
        user
      
      
        (String)
      
      
      
        —
        
    the user component of the userinfo, or nil
    

    
      
    
    • 
  
    
  • 
      
        password
      
      
        (String)
      
      
      
        —
        
    the password component of the userinfo, or
nil
    

    
      
    
    • 
  
    
  • 
      
        auth_params
      
      
        (String)
      
      
      
        —
        
    the auth params of the userinfo, or
nil
    

    
      
    
    • 
  
    
  • 
      
        host
      
      
        (String)
      
      
      
        —
        
    the host component, or nil
    

    
      
    
    • 
  
    
  • 
      
        port
      
      
        (Integer)
      
      
      
        —
        
    the port, or -1
    

    
      
    
    • 
  
    
  • 
      
        path
      
      
        (String)
      
      
      
        —
        
    the path component
    

    
      
    
    • 
  
    
  • 
      
        query
      
      
        (String)
      
      
      
        —
        
    the query component, or nil
    

    
      
    
    • 
  
    
  • 
      
        fragment
      
      
        (String)
      
      
      
        —
        
    the fragment, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    an absolute URI string
    

    
      
    
    • 
  







    
      

  

  
    #uri_list_extract_uris(uri_list)  ⇒ Array<String> 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        uri_list
      
      
        (String)
      
      
      
        —
        
    an URI list
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
        —
        
    a newly allocated nil-terminated list
of strings holding the individual URIs. The array should be freed
with g_strfreev().
    

    
      
    
    • 
  







    
      

  

  
    #uri_parse(uri_string, flags)  ⇒ GLib::Uri 
  

  

  


  

    
Parses uri_string according to flags. If the result is not a
valid absolute URI, it will be discarded, and an
error returned.



  





  
Parameters:


    
  
    
  • 
      
        uri_string
      
      
        (String)
      
      
      
        —
        
    a string representing an absolute URI
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags describing how to parse uri_string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Uri)
      
      
      
        —
        
    a new #GUri, or NULL on error.
    

    
      
    
    • 
  







    
      

  

  
    #uri_parse_params(params, length, separators, flags)  ⇒ GLib::HashTable<String> 
  

  

  


  

    
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
GUri::ParamsIter.


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 %G_URI_FLAGS_PARSE_RELAXED
rules for g_uri_parse(). (However, if params is the path or query string
from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and
%G_URI_FLAGS_ENCODED, then you already know that it does not contain any
invalid encoding.)


%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init().


If %G_URI_PARAMS_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 nil is returned.



  





  
Parameters:


    
  
    
  • 
      
        params
      
      
        (String)
      
      
      
        —
        
    a %-encoded string containing attribute=value
parameters
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length of params, or -1 if it is nul-terminated
    

    
      
    
    • 
  
    
  • 
      
        separators
      
      
        (String)
      
      
      
        —
        
    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.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::HashTable<String>)
      
      
      
        —
        
    A hash table of attribute/value pairs, with both names and values
fully-decoded; or nil on error.
    

    
      
    
    • 
  







    
      

  

  
    #uri_parse_scheme(uri)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        uri
      
      
        (String)
      
      
      
        —
        
    a valid URI.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The ‘scheme’ component of the URI, or
nil on error. The returned string should be freed when no longer needed.
    

    
      
    
    • 
  







    
      

  

  
    #uri_peek_scheme(uri)  ⇒ String 
  

  

  


  

    
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 g_uri_parse_scheme(), the returned scheme is normalized to
all-lowercase and does not need to be freed.



  





  
Parameters:


    
  
    
  • 
      
        uri
      
      
        (String)
      
      
      
        —
        
    a valid URI.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    The ‘scheme’ component of the URI, or
nil on error. The returned string is normalized to all-lowercase, and
interned via g_intern_string(), so it does not need to be freed.
    

    
      
    
    • 
  







    
      

  

  
    #uri_resolve_relative(base_uri_string, uri_ref, flags)  ⇒ String 
  

  

  


  

    
Parses uri_ref according to flags and, if it is a
relative URI, 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 nil, this just returns uri_ref, or
nil if uri_ref is invalid or not absolute.)
or NULL on error.



  





  
Parameters:


    
  
    
  • 
      
        base_uri_string
      
      
        (String)
      
      
      
        —
        
    a string representing a base URI
    

    
      
    
    • 
  
    
  • 
      
        uri_ref
      
      
        (String)
      
      
      
        —
        
    a string representing a relative or absolute URI
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags describing how to parse uri_ref
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the resolved URI string,
    

    
      
    
    • 
  







    
      

  

  
    #uri_split(uri_ref, flags, scheme, userinfo, host, port, path, query, fragment)  ⇒ Boolean 
  

  

  


  

    
Parses uri_ref (which can be an
absolute or relative URI) according to flags, and
returns the pieces. Any component that doesn't appear in uri_ref will be
returned as nil (but note that all URIs always have a path component,
though it may be the empty string).


If flags contains %G_URI_FLAGS_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 %G_URI_FLAGS_ENCODED if they are not.


Note that the %G_URI_FLAGS_HAS_PASSWORD and
%G_URI_FLAGS_HAS_AUTH_PARAMS flags are ignored by g_uri_split(),
since it always returns only the full userinfo; use
g_uri_split_with_user() if you want it split up.



  





  
Parameters:


    
  
    
  • 
      
        uri_ref
      
      
        (String)
      
      
      
        —
        
    a string containing a relative or absolute URI
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags for parsing uri_ref
    

    
      
    
    • 
  
    
  • 
      
        scheme
      
      
        (String)
      
      
      
        —
        
    on return, contains
the scheme (converted to lowercase), or nil
    

    
      
    
    • 
  
    
  • 
      
        userinfo
      
      
        (String)
      
      
      
        —
        
    on return, contains
the userinfo, or nil
    

    
      
    
    • 
  
    
  • 
      
        host
      
      
        (String)
      
      
      
        —
        
    on return, contains the
host, or nil
    

    
      
    
    • 
  
    
  • 
      
        port
      
      
        (Integer)
      
      
      
        —
        
    on return, contains the
port, or -1
    

    
      
    
    • 
  
    
  • 
      
        path
      
      
        (String)
      
      
      
        —
        
    on return, contains the
path
    

    
      
    
    • 
  
    
  • 
      
        query
      
      
        (String)
      
      
      
        —
        
    on return, contains the
query, or nil
    

    
      
    
    • 
  
    
  • 
      
        fragment
      
      
        (String)
      
      
      
        —
        
    on return, contains
the fragment, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if uri_ref parsed successfully, false
on error.
    

    
      
    
    • 
  







    
      

  

  
    #uri_split_network(uri_string, flags, scheme, host, port)  ⇒ Boolean 
  

  

  


  

    
Parses uri_string (which must be an absolute URI)
according to flags, and returns the pieces relevant to connecting to a host.
See the documentation for g_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.



  





  
Parameters:


    
  
    
  • 
      
        uri_string
      
      
        (String)
      
      
      
        —
        
    a string containing an absolute URI
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags for parsing uri_string
    

    
      
    
    • 
  
    
  • 
      
        scheme
      
      
        (String)
      
      
      
        —
        
    on return, contains
the scheme (converted to lowercase), or nil
    

    
      
    
    • 
  
    
  • 
      
        host
      
      
        (String)
      
      
      
        —
        
    on return, contains the
host, or nil
    

    
      
    
    • 
  
    
  • 
      
        port
      
      
        (Integer)
      
      
      
        —
        
    on return, contains the
port, or -1
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if uri_string parsed successfully,
false on error.
    

    
      
    
    • 
  







    
      

  

  
    #uri_split_with_user(uri_ref, flags, scheme, user, password, auth_params, host, port, path, query, fragment)  ⇒ Boolean 
  

  

  


  

    
Parses uri_ref (which can be an
absolute or relative URI) according to flags, and
returns the pieces. Any component that doesn't appear in uri_ref will be
returned as nil (but note that all URIs always have a path component,
though it may be the empty string).


See g_uri_split(), and the definition of GUri::Flags, for more
information on the effect of flags. Note that password will only
be parsed out if flags contains %G_URI_FLAGS_HAS_PASSWORD, and
auth_params will only be parsed out if flags contains
%G_URI_FLAGS_HAS_AUTH_PARAMS.



  





  
Parameters:


    
  
    
  • 
      
        uri_ref
      
      
        (String)
      
      
      
        —
        
    a string containing a relative or absolute URI
    

    
      
    
    • 
  
    
  • 
      
        flags
      
      
        (GLib::UriFlags)
      
      
      
        —
        
    flags for parsing uri_ref
    

    
      
    
    • 
  
    
  • 
      
        scheme
      
      
        (String)
      
      
      
        —
        
    on return, contains
the scheme (converted to lowercase), or nil
    

    
      
    
    • 
  
    
  • 
      
        user
      
      
        (String)
      
      
      
        —
        
    on return, contains
the user, or nil
    

    
      
    
    • 
  
    
  • 
      
        password
      
      
        (String)
      
      
      
        —
        
    on return, contains
the password, or nil
    

    
      
    
    • 
  
    
  • 
      
        auth_params
      
      
        (String)
      
      
      
        —
        
    on return, contains
the auth_params, or nil
    

    
      
    
    • 
  
    
  • 
      
        host
      
      
        (String)
      
      
      
        —
        
    on return, contains the
host, or nil
    

    
      
    
    • 
  
    
  • 
      
        port
      
      
        (Integer)
      
      
      
        —
        
    on return, contains the
port, or -1
    

    
      
    
    • 
  
    
  • 
      
        path
      
      
        (String)
      
      
      
        —
        
    on return, contains the
path
    

    
      
    
    • 
  
    
  • 
      
        query
      
      
        (String)
      
      
      
        —
        
    on return, contains the
query, or nil
    

    
      
    
    • 
  
    
  • 
      
        fragment
      
      
        (String)
      
      
      
        —
        
    on return, contains
the fragment, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if uri_ref parsed successfully, false
on error.
    

    
      
    
    • 
  







    
      

  

  
    #uri_unescape_bytes(escaped_string, length, illegal_characters)  ⇒ GLib::Bytes 
  

  

  


  

    
Unescapes a segment of an escaped string as binary data.


Note that in contrast to g_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 nil 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.



  





  
Parameters:


    
  
    
  • 
      
        escaped_string
      
      
        (String)
      
      
      
        —
        
    A URI-escaped string
    

    
      
    
    • 
  
    
  • 
      
        length
      
      
        (GLib::gssize)
      
      
      
        —
        
    the length (in bytes) of escaped_string to escape, or -1 if it
is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        illegal_characters
      
      
        (String)
      
      
      
        —
        
    a string of illegal characters
not to be allowed, or nil.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Bytes)
      
      
      
        —
        
    an unescaped version of escaped_string
or nil on error (if decoding failed, using %G_URI_ERROR_FAILED error
code). The returned #GBytes should be unreffed when no longer needed.
    

    
      
    
    • 
  







    
      

  

  
    #uri_unescape_segment(escaped_string, escaped_string_end, illegal_characters)  ⇒ String 
  

  

  


  

    
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 nil 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
g_uri_unescape_bytes().
or nil on error. The returned string should be freed when no longer
needed.  As a special case if nil is given for escaped_string, this
function will return nil.



  





  
Parameters:


    
  
    
  • 
      
        escaped_string
      
      
        (String)
      
      
      
        —
        
    A string, may be nil
    

    
      
    
    • 
  
    
  • 
      
        escaped_string_end
      
      
        (String)
      
      
      
        —
        
    Pointer to end of escaped_string,
may be nil
    

    
      
    
    • 
  
    
  • 
      
        illegal_characters
      
      
        (String)
      
      
      
        —
        
    An optional string of illegal
characters not to be allowed, may be nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    an unescaped version of escaped_string,
    

    
      
    
    • 
  







    
      

  

  
    #uri_unescape_string(escaped_string, illegal_characters)  ⇒ String 
  

  

  


  

    
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 nil 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.
The returned string should be freed when no longer needed.



  





  
Parameters:


    
  
    
  • 
      
        escaped_string
      
      
        (String)
      
      
      
        —
        
    an escaped string to be unescaped.
    

    
      
    
    • 
  
    
  • 
      
        illegal_characters
      
      
        (String)
      
      
      
        —
        
    a string of illegal characters
not to be allowed, or nil.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    an unescaped version of escaped_string.
    

    
      
    
    • 
  







    
      

  

  
    #user_cache_dir  ⇒ GLib::filename 
  

  

  


  

    
Returns a base directory in which to store non-essential, cached
data specific to particular user.


On UNIX platforms this is determined using the mechanisms described
in the
XDG Base Directory Specification.
In this case the directory retrieved will be XDG_CACHE_HOME.


On Windows it follows XDG Base Directory Specification if XDG_CACHE_HOME is defined.
If XDG_CACHE_HOME is undefined, the directory that serves as a common
repository for temporary Internet files is used instead. A typical path is
C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
See the documentation for FOLDERID_InternetCache.


The return value is cached and modifying it at runtime is not supported, as
it’s not thread-safe to modify environment variables at runtime.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a string owned by GLib that
must not be modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #user_config_dir  ⇒ GLib::filename 
  

  

  


  

    
Returns a base directory in which to store user-specific application
configuration information such as user preferences and settings.


On UNIX platforms this is determined using the mechanisms described
in the
XDG Base Directory Specification.
In this case the directory retrieved will be XDG_CONFIG_HOME.


On Windows it follows XDG Base Directory Specification if XDG_CONFIG_HOME is defined.
If XDG_CONFIG_HOME is undefined, the folder to use for local (as opposed
to roaming) application data is used instead. See the
documentation for FOLDERID_LocalAppData.
Note that in this case on Windows it will be  the same
as what g_get_user_data_dir() returns.


The return value is cached and modifying it at runtime is not supported, as
it’s not thread-safe to modify environment variables at runtime.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a string owned by GLib that
must not be modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #user_data_dir  ⇒ GLib::filename 
  

  

  


  

    
Returns a base directory in which to access application data such
as icons that is customized for a particular user.


On UNIX platforms this is determined using the mechanisms described
in the
XDG Base Directory Specification.
In this case the directory retrieved will be XDG_DATA_HOME.


On Windows it follows XDG Base Directory Specification if XDG_DATA_HOME
is defined. If XDG_DATA_HOME is undefined, the folder to use for local (as
opposed to roaming) application data is used instead. See the
documentation for FOLDERID_LocalAppData.
Note that in this case on Windows it will be the same
as what g_get_user_config_dir() returns.


The return value is cached and modifying it at runtime is not supported, as
it’s not thread-safe to modify environment variables at runtime.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a string owned by GLib that must
not be modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #user_name  ⇒ GLib::filename 
  

  

  


  

    
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:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    the user name of the current user.
    

    
      
    
    • 
  







    
      

  

  
    #user_runtime_dir  ⇒ GLib::filename 
  

  

  


  

    
Returns a directory that is unique to the current user on the local
system.


This is determined using the mechanisms described
in the
XDG Base Directory Specification.
This is the directory
specified in the XDG_RUNTIME_DIR environment variable.
In the case that this variable is not set, we return the value of
g_get_user_cache_dir(), after verifying that it exists.


The return value is cached and modifying it at runtime is not supported, as
it’s not thread-safe to modify environment variables at runtime.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a string owned by GLib that must not be
modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #user_state_dir  ⇒ GLib::filename 
  

  

  


  

    
Returns a base directory in which to store state files specific to
particular user.


On UNIX platforms this is determined using the mechanisms described
in the
XDG Base Directory Specification.
In this case the directory retrieved will be XDG_STATE_HOME.


On Windows it follows XDG Base Directory Specification if XDG_STATE_HOME is defined.
If XDG_STATE_HOME is undefined, the folder to use for local (as opposed
to roaming) application data is used instead. See the
documentation for FOLDERID_LocalAppData.
Note that in this case on Windows it will be the same
as what g_get_user_data_dir() returns.


The return value is cached and modifying it at runtime is not supported, as
it’s not thread-safe to modify environment variables at runtime.



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::filename)
      
      
      
        —
        
    a string owned by GLib that
must not be modified or freed.
    

    
      
    
    • 
  







    
      

  

  
    #usleep(microseconds)  ⇒ nil 
  

  

  


  

    
Pauses the current thread for the given number of microseconds.


There are 1 million microseconds per second (represented by the
%G_USEC_PER_SEC macro). g_usleep() may have limited precision,
depending on hardware and operating system; don't rely on the exact
length of the sleep.



  





  
Parameters:


    
  
    
  • 
      
        microseconds
      
      
        (GLib::gulong)
      
      
      
        —
        
    number of microseconds to pause
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    • 
  







    
      

  

  
    #utf16_to_ucs4(str, len, items_read, items_written)  ⇒ String 
  

  

  


  

    
Convert a string from UTF-16 to UCS-4. The result will be
nul-terminated.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<Integer>)
      
      
      
        —
        
    a UTF-16 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::glong)
      
      
      
        —
        
    the maximum length (number of #gunichar2) of str to use.
If len < 0, then the string is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        items_read
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number of
words read, or nil. If nil, then %G_CONVERT_ERROR_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
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number
of characters written, or nil. The value stored here does not include
the trailing 0 character.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to a newly allocated UCS-4 string.
This value must be freed with g_free(). If an error occurs,
nil will be returned and error set.
    

    
      
    
    • 
  







    
      

  

  
    #utf16_to_utf8(str, len, items_read, items_written)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<Integer>)
      
      
      
        —
        
    a UTF-16 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::glong)
      
      
      
        —
        
    the maximum length (number of #gunichar2) of str to use.
If len < 0, then the string is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        items_read
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number of
words read, or nil. If nil, then %G_CONVERT_ERROR_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
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number
of bytes written, or nil. The value stored here does not include the
trailing 0 byte. It’s guaranteed to be non-negative.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to a newly allocated UTF-8 string.
This value must be freed with g_free(). If an error occurs,
nil will be returned and error set.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_casefold(str, len)  ⇒ String 
  

  

  


  

    
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
g_utf8_casefold() on other strings.


Note that calling g_utf8_casefold() followed by g_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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str, in bytes, or -1 if str is nul-terminated.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string, that is a
case independent form of str.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_collate(str1, str2)  ⇒ Integer 
  

  

  


  

    
Compares two strings for ordering using the linguistically
correct rules for the [current locale][setlocale].
When sorting a large number of strings, it will be significantly
faster to obtain collation keys with g_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.



  





  
Parameters:


    
  
    
  • 
      
        str1
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        str2
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    < 0 if str1 compares before str2,
0 if they compare equal, > 0 if str1 compares after str2.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_collate_key(str, len)  ⇒ String 
  

  

  


  

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


Note that this function depends on the [current locale][setlocale].



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str, in bytes, or -1 if str is nul-terminated.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string. This string should
be freed with g_free() when you are done with it.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_collate_key_for_filename(str, len)  ⇒ String 
  

  

  


  

    
Converts a string into a collation key that can be compared
with other collation keys produced by the same function using strcmp().


In order to sort filenames correctly, this function treats the dot '.'
as a special case. Most dictionary orderings seem to consider it
insignificant, thus producing the ordering "event.c" "eventgenerator.c"
"event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we
would like to treat numbers intelligently so that "file1" "file10" "file5"
is sorted as "file1" "file5" "file10".


Note that this function depends on the [current locale][setlocale].



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str, in bytes, or -1 if str is nul-terminated.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string. This string should
be freed with g_free() when you are done with it.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_find_next_char(p, end)  ⇒ String 
  

  

  


  

    
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 nil, the return value will never be nil: if the end of the
string is reached, a pointer to the terminating nul byte is returned. If
end is non-nil, the return value will be nil if the end of the string
is reached.



  





  
Parameters:


    
  
    
  • 
      
        p
      
      
        (String)
      
      
      
        —
        
    a pointer to a position within a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (String)
      
      
      
        —
        
    a pointer to the byte following the end of the string,
or nil to indicate that the string is nul-terminated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to the found character or nil if end is
set and is reached
    

    
      
    
    • 
  







    
      

  

  
    #utf8_find_prev_char(str, p)  ⇒ String 
  

  

  


  

    
Given a position p with a UTF-8 encoded string str, find the start
of the previous UTF-8 character starting before p. Returns nil 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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    pointer to the beginning of a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        p
      
      
        (String)
      
      
      
        —
        
    pointer to some position within str
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to the found character or nil.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_get_char(p)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        p
      
      
        (String)
      
      
      
        —
        
    a pointer to Unicode character encoded as UTF-8
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the resulting character
    

    
      
    
    • 
  







    
      

  

  
    #utf8_get_char_validated(p, max_len)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        p
      
      
        (String)
      
      
      
        —
        
    a pointer to Unicode character encoded as UTF-8
    

    
      
    
    • 
  
    
  • 
      
        max_len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the maximum number of bytes to read, or -1 if p is nul-terminated
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    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.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_make_valid(str, len)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    string to coerce into UTF-8
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the maximum length of str to use, in bytes. If len < 0,
then the string is nul-terminated.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a valid UTF-8 string whose content resembles str
    

    
      
    
    • 
  







    
      

  

  
    #utf8_normalize(str, len, mode)  ⇒ String 
  

  

  


  

    
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 nil is
returned. You should generally call g_utf8_normalize()
before comparing two Unicode strings.


The normalization mode %G_NORMALIZE_DEFAULT only
standardizes differences that do not affect the
text content, such as the above-mentioned accent
representation. %G_NORMALIZE_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.


%G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string.
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str, in bytes, or -1 if str is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        mode
      
      
        (GLib::NormalizeMode)
      
      
      
        —
        
    the type of normalization to perform.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string, that
is the normalized form of str, or nil if str
is not valid UTF-8.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_offset_to_pointer(str, offset)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        offset
      
      
        (GLib::glong)
      
      
      
        —
        
    a character offset within str
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the resulting pointer
    

    
      
    
    • 
  







    
      

  

  
    #utf8_pointer_to_offset(str, pos)  ⇒ GLib::glong 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        pos
      
      
        (String)
      
      
      
        —
        
    a pointer to a position within str
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::glong)
      
      
      
        —
        
    the resulting character offset
    

    
      
    
    • 
  







    
      

  

  
    #utf8_prev_char(p)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        p
      
      
        (String)
      
      
      
        —
        
    a pointer to a position within a UTF-8 encoded string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to the found character
    

    
      
    
    • 
  







    
      

  

  
    #utf8_strchr(p, len, c)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        p
      
      
        (String)
      
      
      
        —
        
    a nul-terminated UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the maximum length of p
    

    
      
    
    • 
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    nil if the string does not contain the character,
otherwise, a pointer to the start of the leftmost occurrence
of the character in the string.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_strdown(str, len)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str, in bytes, or -1 if str is nul-terminated.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string, with all characters
converted to lowercase.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_strlen(p, max)  ⇒ GLib::glong 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        p
      
      
        (String)
      
      
      
        —
        
    pointer to the start of a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        max
      
      
        (GLib::gssize)
      
      
      
        —
        
    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 nil. If max is greater than 0, up to max
bytes are examined
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::glong)
      
      
      
        —
        
    the length of the string in characters
    

    
      
    
    • 
  







    
      

  

  
    #utf8_strncpy(dest, src, n)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        dest
      
      
        (String)
      
      
      
        —
        
    buffer to fill with characters from src
    

    
      
    
    • 
  
    
  • 
      
        src
      
      
        (String)
      
      
      
        —
        
    UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        n
      
      
        (Integer)
      
      
      
        —
        
    character count
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    dest
    

    
      
    
    • 
  







    
      

  

  
    #utf8_strrchr(p, len, c)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        p
      
      
        (String)
      
      
      
        —
        
    a nul-terminated UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the maximum length of p
    

    
      
    
    • 
  
    
  • 
      
        c
      
      
        (String)
      
      
      
        —
        
    a Unicode character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    nil if the string does not contain the character,
otherwise, a pointer to the start of the rightmost occurrence
of the character in the string.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_strreverse(str, len)  ⇒ String 
  

  

  


  

    
Reverses a UTF-8 string. str must be valid UTF-8 encoded text.
(Use g_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 g_strreverse(), this function returns
newly-allocated memory, which should be freed with g_free() when
no longer needed.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    the maximum length of str to use, in bytes. If len < 0,
then the string is nul-terminated.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated string which is the reverse of str
    

    
      
    
    • 
  







    
      

  

  
    #utf8_strup(str, len)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::gssize)
      
      
      
        —
        
    length of str, in bytes, or -1 if str is nul-terminated.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated string, with all characters
converted to uppercase.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_substring(str, start_pos, end_pos)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        start_pos
      
      
        (GLib::glong)
      
      
      
        —
        
    a character offset within str
    

    
      
    
    • 
  
    
  • 
      
        end_pos
      
      
        (GLib::glong)
      
      
      
        —
        
    another character offset within str,
or -1 to indicate the end of the string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly allocated copy of the requested
substring. Free with g_free() when no longer needed.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_to_ucs4(str, len, items_read, items_written)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::glong)
      
      
      
        —
        
    the maximum length of str to use, in bytes. If len < 0,
then the string is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        items_read
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number of
bytes read, or nil.
If nil, then %G_CONVERT_ERROR_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
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number
of characters written or nil. The value here stored does not include
the trailing 0 character.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to a newly allocated UCS-4 string.
This value must be freed with g_free(). If an error occurs,
nil will be returned and error set.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_to_ucs4_fast(str, len, items_written)  ⇒ String 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::glong)
      
      
      
        —
        
    the maximum length of str to use, in bytes. If len < 0,
then the string is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        items_written
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store the
number of characters in the result, or nil.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a pointer to a newly allocated UCS-4 string.
This value must be freed with g_free().
    

    
      
    
    • 
  







    
      

  

  
    #utf8_to_utf16(str, len, items_read, items_written)  ⇒ Integer 
  

  

  


  

    
Convert a string from UTF-8 to UTF-16. A 0 character will be
added to the result after the converted text.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        len
      
      
        (GLib::glong)
      
      
      
        —
        
    the maximum length (number of bytes) of str to use.
If len < 0, then the string is nul-terminated.
    

    
      
    
    • 
  
    
  • 
      
        items_read
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number of
bytes read, or nil. If nil, then %G_CONVERT_ERROR_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
      
      
        (GLib::glong)
      
      
      
        —
        
    location to store number
of #gunichar2 written, or nil. The value stored here does not include
the trailing 0.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    a pointer to a newly allocated UTF-16 string.
This value must be freed with g_free(). If an error occurs,
nil will be returned and error set.
    

    
      
    
    • 
  







    
      

  

  
    #utf8_truncate_middle(string, truncate_length)  ⇒ String 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a nul-terminated UTF-8 encoded string
    

    
      
    
    • 
  
    
  • 
      
        truncate_length
      
      
        (Integer)
      
      
      
        —
        
    the new size of string, in characters, including the ellipsis character
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    a newly-allocated copy of string ellipsized in the middle
    

    
      
    
    • 
  







    
      

  

  
    #utf8_validate(str, max_len, end)  ⇒ Boolean 
  

  

  


  

    
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-nil, 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 g_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 g_utf8_validate() before
doing anything else with it.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<Integer>)
      
      
      
        —
        
    a pointer to character data
    

    
      
    
    • 
  
    
  • 
      
        max_len
      
      
        (GLib::gssize)
      
      
      
        —
        
    max bytes to validate, or -1 to go until NUL
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (String)
      
      
      
        —
        
    return location for end of valid data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the text was valid UTF-8
    

    
      
    
    • 
  







    
      

  

  
    #utf8_validate_len(str, max_len, end)  ⇒ Boolean 
  

  

  


  

    
Validates UTF-8 encoded text.


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



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (Array<Integer>)
      
      
      
        —
        
    a pointer to character data
    

    
      
    
    • 
  
    
  • 
      
        max_len
      
      
        (Integer)
      
      
      
        —
        
    max bytes to validate
    

    
      
    
    • 
  
    
  • 
      
        end
      
      
        (String)
      
      
      
        —
        
    return location for end of valid data
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if the text was valid UTF-8
    

    
      
    
    • 
  







    
      

  

  
    #utime(filename, utb)  ⇒ Integer 
  

  

  


  

    
A wrapper for the POSIX utime() function. The utime() function
sets the access and modification timestamps of a file.


See your C library manual for more details about how utime() works
on your system.



  





  
Parameters:


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

    
      
    
    • 
  
    
  • 
      
        utb
      
      
        (GObject)
      
      
      
        —
        
    a pointer to a struct utimbuf.
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    0 if the operation was successful, -1 if an error occurred
    

    
      
    
    • 
  







    
      

  

  
    #uuid_string_is_valid(str)  ⇒ Boolean 
  

  

  


  

    
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.



  





  
Parameters:


    
  
    
  • 
      
        str
      
      
        (String)
      
      
      
        —
        
    a string representing a UUID
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if str is a valid UUID, false otherwise.
    

    
      
    
    • 
  







    
      

  

  
    #uuid_string_random  ⇒ String 
  

  

  


  

    
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.



  





  

Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    A string that should be freed with g_free().
    

    
      
    
    • 
  







    
      

  

  
    #variant_get_gtype  ⇒ GLib::Type 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Type)
      
      
      
    
    • 
  







    
      

  

  
    #variant_is_object_path(string)  ⇒ Boolean 
  

  

  


  

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



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a normal C nul-terminated string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if string is a D-Bus object path
    

    
      
    
    • 
  







    
      

  

  
    #variant_is_signature(string)  ⇒ Boolean 
  

  

  


  

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


D-Bus type signatures consist of zero or more definite GVariant::Type
strings in sequence.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a normal C nul-terminated string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if string is a D-Bus type signature
    

    
      
    
    • 
  







    
      

  

  
    #variant_parse(type, text, limit, endptr)  ⇒ GLib::Variant 
  

  

  


  

    
Parses a #GVariant from a text representation.


A single #GVariant 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-nil 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 nil and there is extra data
then an error is returned.


If type is non-nil 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 #GVariant
is returned. It is never floating, and must be freed with
[methodGLib.Variant.unref].


In case of any error, nil will be returned.  If error is non-nil
then it will be set to reflect the error that occurred.


Officially, the language understood by the parser is “any string
produced by [methodGLib.Variant.print]”. This explicitly includes
g_variant_print()’s annotated types like int64 -1000.


There may be implementation specific restrictions on deeply nested values,
which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is
guaranteed to handle nesting up to at least 64 levels.



  





  
Parameters:


    
  
    
  • 
      
        type
      
      
        (GLib::VariantType)
      
      
      
        —
        
    a GVariant::Type, or nil
    

    
      
    
    • 
  
    
  • 
      
        text
      
      
        (String)
      
      
      
        —
        
    a string containing a GVariant in text form
    

    
      
    
    • 
  
    
  • 
      
        limit
      
      
        (String)
      
      
      
        —
        
    a pointer to the end of text, or nil
    

    
      
    
    • 
  
    
  • 
      
        endptr
      
      
        (String)
      
      
      
        —
        
    a location to store the end pointer, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::Variant)
      
      
      
        —
        
    a non-floating reference to a #GVariant, or nil
    

    
      
    
    • 
  







    
      

  

  
    #variant_parse_error_print_context(error, source_str)  ⇒ String 
  

  

  


  

    
Pretty-prints a message showing the context of a #GVariant 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 g_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
g_variant_parse() then you must add nul termination before using this
function.



  





  
Parameters:


    
  
    
  • 
      
        error
      
      
        (GLib::Error)
      
      
      
        —
        
    a #GError from the GVariant::ParseError domain
    

    
      
    
    • 
  
    
  • 
      
        source_str
      
      
        (String)
      
      
      
        —
        
    the string that was given to the parser
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    the printed message
    

    
      
    
    • 
  







    
      

  

  
    #variant_parse_error_quark  ⇒ GLib::Quark 
  

  

  


  

    

  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #variant_parser_get_error_quark  ⇒ GLib::Quark 
  

  

  


  

    
Same as g_variant_error_quark().



  





  

Returns:


    
  
    
  • 
      
      
        (GLib::Quark)
      
      
      
    
    • 
  







    
      

  

  
    #variant_type_checked_(type_string)  ⇒ GLib::VariantType 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        type_string
      
      
        (String)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (GLib::VariantType)
      
      
      
    
    • 
  







    
      

  

  
    #variant_type_string_get_depth_(type_string)  ⇒ Integer 
  

  

  


  

    

  





  
Parameters:


    
  
    
  • 
      
        type_string
      
      
        (String)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
    
    • 
  







    
      

  

  
    #variant_type_string_is_valid(type_string)  ⇒ Boolean 
  

  

  


  

    
Checks if type_string is a valid GVariant type string.  This call is
equivalent to calling g_variant_type_string_scan() and confirming
that the following character is a nul terminator.
Since 2.24



  





  
Parameters:


    
  
    
  • 
      
        type_string
      
      
        (String)
      
      
      
        —
        
    a pointer to any string
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if type_string is exactly one valid type string
    

    
      
    
    • 
  







    
      

  

  
    #variant_type_string_scan(string, limit, endptr)  ⇒ Boolean 
  

  

  


  

    
Scan for a single complete and valid GVariant 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 g_variant_type_string_is_valid().



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    a pointer to any string
    

    
      
    
    • 
  
    
  • 
      
        limit
      
      
        (String)
      
      
      
        —
        
    the end of string, or nil
    

    
      
    
    • 
  
    
  • 
      
        endptr
      
      
        (String)
      
      
      
        —
        
    location to store the end pointer, or nil
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
        —
        
    true if a valid type string was found
    

    
      
    
    • 
  







    
      

  

  
    #vasprintf(string, format, args)  ⇒ Integer 
  

  

  


  

    
An implementation of the GNU vasprintf() function which supports
positional parameters, as specified in the Single Unix Specification.
This function is similar to [funcGLib.vsprintf], except that it allocates a
string to hold the output, instead of putting the output in a buffer
you allocate in advance.


The returned value in string is guaranteed to be non-NULL, unless
format contains %lc or %ls conversions, which can fail if no
multibyte representation is available for the given character.


glib/gprintf.h must be explicitly included in order to use this function.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the return location for the
newly-allocated string, which will be NULL if (and only if)
this function fails
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    the list of arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes printed, or -1 on failure
    

    
      
    
    • 
  







    
      

  

  
    #vfprintf(file, format, args)  ⇒ Integer 
  

  

  


  

    
An implementation of the standard fprintf() function which supports
positional parameters, as specified in the Single Unix Specification.


glib/gprintf.h must be explicitly included in order to use this function.



  





  
Parameters:


    
  
    
  • 
      
        file
      
      
        (GObject)
      
      
      
        —
        
    the stream to write to
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    the list of arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes printed
    

    
      
    
    • 
  







    
      

  

  
    #vprintf(format, args)  ⇒ Integer 
  

  

  


  

    
An implementation of the standard vprintf() function which supports
positional parameters, as specified in the Single Unix Specification.


glib/gprintf.h must be explicitly included in order to use this function.



  





  
Parameters:


    
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    the list of arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes printed
    

    
      
    
    • 
  







    
      

  

  
    #vsnprintf(string, n, format, args)  ⇒ Integer 
  

  

  


  

    
A safer form of the standard vsprintf() function. The output is guaranteed
to not exceed n characters (including the terminating nul character), so
it is easy to ensure that a buffer overflow cannot occur.


See also [funcGLib.strdup_vprintf].


In versions of GLib prior to 1.2.3, this function may return -1 if the
output was truncated, and the truncated string may not be nul-terminated.
In versions prior to 1.3.12, this function returns the length of the output
string.


The return value of g_vsnprintf() conforms to the vsnprintf() function
as standardized in ISO C99. Note that this is different from traditional
vsnprintf(), which returns the length of the output string.


The format string may contain positional parameters, as specified in
the Single Unix Specification.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the buffer to hold the output
    

    
      
    
    • 
  
    
  • 
      
        n
      
      
        (GLib::gulong)
      
      
      
        —
        
    the maximum number of bytes to produce (including the
terminating nul character)
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    the list of arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes which would be produced if the buffer
was large enough
    

    
      
    
    • 
  







    
      

  

  
    #vsprintf(string, format, args)  ⇒ Integer 
  

  

  


  

    
An implementation of the standard vsprintf() function which supports
positional parameters, as specified in the Single Unix Specification.


glib/gprintf.h must be explicitly included in order to use this function.



  





  
Parameters:


    
  
    
  • 
      
        string
      
      
        (String)
      
      
      
        —
        
    the buffer to hold the output
    

    
      
    
    • 
  
    
  • 
      
        format
      
      
        (String)
      
      
      
        —
        
    a standard printf() format string, but notice
string precision pitfalls
    

    
      
    
    • 
  
    
  • 
      
        args
      
      
        (GLib::va_list)
      
      
      
        —
        
    the list of arguments to insert in the output
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
        —
        
    the number of bytes printed
    

    
      
    
    • 
  







    
      

  

  
    #warn_message(domain, file, line, func, warnexpr)  ⇒ nil 
  

  

  


  

    
Internal function used to print messages from the public [funcGLib.warn_if_reached]
and [funcGLib.warn_if_fail] macros.



  





  
Parameters:


    
  
    
  • 
      
        domain
      
      
        (String)
      
      
      
        —
        
    log domain
    

    
      
    
    • 
  
    
  • 
      
        file
      
      
        (String)
      
      
      
        —
        
    file containing the warning
    

    
      
    
    • 
  
    
  • 
      
        line
      
      
        (Integer)
      
      
      
        —
        
    line number of the warning
    

    
      
    
    • 
  
    
  • 
      
        func
      
      
        (String)
      
      
      
        —
        
    function containing the warning
    

    
      
    
    • 
  
    
  • 
      
        warnexpr
      
      
        (String)
      
      
      
        —
        
    expression which failed
    

    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (nil)
      
      
      
    
    •