Версия для печати

Архив документации на OpenNet.ru / Раздел "Программирование, языки" (Многостраничная версия)

Версия GLib 2.13.0

Замечания по поводу перевода присылать sergeyvp@gmail.com


Table of Contents

GLib Overview
Compiling the GLib package - Как самостоятельно скомпилировать GLib
Cross-compiling the GLib package - Как скомпилировать пакет GLib для разных архитектур
Compiling GLib Applications - Как скомпилировать ваше GLib приложение
Running GLib Applications - Как выполнять и отлаживать GLib приложение
Changes to GLib - Несовместимые изменения сделанные между разными версиями GLib
Mailing lists and bug reports - Получение помощи по GLib
GLib Fundamentals
Version Information - Переменные и функции для проверки версии GLib
Basic Types - Стандартные типы GLib, определяемые для простоты использования и переносимости.
Limits of Basic Types - Переносимый метод определения лимитов стандартных типов.
Standard Macros - Обычно используемые макросы.
Type Conversion Macros - Переносимый способ хранения целочисленных в указателях переменных.
Byte Order Macros - Переносимый способ преобразования между разными последовательностями байт.
Numerical Definitions - Математические константы и разбиение плавающей точкой.
Miscellaneous Macros - Редко используемые специализированные макросы.
Atomic Operations - основные атомарные операции с целочисленными и указателями
GLib Core Application Support
The Main Event Loop - Управление всеми доступными источниками событий.
Threads - Абстракция потока; включает потоки, различные взаимоисключения (mutexes), условия и поток закрытых данных.
Thread Pools - Пулы потоков для одновременного выполнения работы.
Asynchronous Queues - Асинхронное взаимодействие между потоками.
Dynamic Loading of Modules - Переносимый способ для динамической загрузки 'plug-ins'.
Memory Allocation - Основная обработка памяти.
IO Channels - Переносимая поддержка использования файлов, каналов и сокетов.
Error Reporting - Система для сообщения об ошибках.
Message Output and Debugging Functions - Функции для вывода сообщений и помощь отладки приложений.
Message Logging - Универсальная поддержка для регистрации сообщений с разным уровнем важности.
GLib Utilities
String Utility Functions - Варианты строковых функций.
Character Set Conversion - конвертирование строк между разными наборами символов используя iconv().
Unicode Manipulation - Функции оперирующие на Unicode символах и UTF-8 строках.
Base64 Encoding - Кодирование и декодирование данных в формат Base64
Internationalization - Макросы поддерживающие gettext.
Date and Time Functions - Календарные вычисления и различный временной материал.
Random Numbers - Генератор псевдо-случайных чисел.
Hook Functions - Поддержка для манипулирования списками hook-функций.
Miscellaneous Utility Functions - Набор портируемых сервисных функций.
Lexical Scanner - Универсальный лексический сканер.
Automatic String Completion - Поддержка автоматичекого завершения строк используя наборы целевых строк.
Timers - Отслеживание прошедшего времени.
Spawning Processes - Порождение процессов с помощью fork()/exec().
File Utilities - Варианты функций связанных с файлами.
Shell-related Utilities - shell-подобная обработка командной строки.
Commandline option parser - Анализатор опций командной строки
Glob-style pattern matching - Сравнение строк с шаблонами содержащими '*' (wildcard) и '?' (joker).
Simple XML Subset Parser - Синтаксический анализатор подмножества XML.
Key-value file parser - Анализ .ini-подобных конфигурационных файлов
Bookmark file parser - Анализ файлов содержащих закладки
Windows Compatibility Functions - Эмуляция UNIX в Windows.
GLib Data Types
Memory Slices - Эффективный способ распределения групп эквивалентных по размеру участков памяти.
Memory Chunks - Устаревший способ распределения групп эквивалентных по размеру участков памяти.
Doubly-Linked Lists - Связанные списки содержащие целочисленные значения или указатели на данные, с возможностью итерации по списку в обоих направлениях.
Singly-Linked Lists - Связанные списки содержащие целочисленные значения или указатели на данные, с ограничением итерации только в одном направлении.
Double-ended Queues - Двусторонняя очередь структур данных.
Trash Stacks - Поддержка стека неиспользуемых распределённых участков памяти.
Hash Tables - Связь между ключами и значениями для быстрого поиска.
Strings - Текстовые буферы которые автоматически увеличиваются при добавлении текста.
String Chunks - Эффективное хранение групп строк.
Arrays - Массивы произвольных элементов, которые автоматически увеличиваются при добавлении элементов.
Pointer Arrays - Массив указателей для любого типа данных, который увеличивается автоматически при добавлении элементов.
Byte Arrays - Массив байт, который автоматически увеличивается при добавлении элементов.
Balanced Binary Trees - Отсортированная коллекция пар ключ/значение оптимизированная для поиска и пересечения в определённом порядке.
N-ary Trees - Деревья данных с любым количеством ответвлений.
Quarks - Два способа связать строку и уникальный целочисленный идентификатор.
Keyed Data Lists - Списки элементов данных которые являются доступными при помощи строки или GQuark идентификатора.
Datasets - Связь групп элементов данных со специфическим расположением памяти.
Relations and Tuples - Таблицы данных которые могут быть проиндексированы любым количеством полей.
Caches - Кеши позволяют объединять комплекс структур данных для сохранения ресурсов.
Memory Allocators - Устаревший способ распределения участков памяти для GList, GSList и GNode.
GLib Tools
glib-gettextize - Утилита интернационализации gettext
Index
Index of deprecated symbols
Index of new symbols in 2.2
Index of new symbols in 2.4
Index of new symbols in 2.6
Index of new symbols in 2.8
Index of new symbols in 2.10
Index of new symbols in 2.12

Arrays

Arrays — Массивы произвольных элементов, которые автоматически увеличиваются при добавлении элементов.

Краткое описание


#include <glib.h>


            GArray;
GArray*     g_array_new                     (gboolean zero_terminated,
                                             gboolean clear_,
                                             guint element_size);
GArray*     g_array_sized_new               (gboolean zero_terminated,
                                             gboolean clear_,
                                             guint element_size,
                                             guint reserved_size);
#define     g_array_append_val              (a,v)
GArray*     g_array_append_vals             (GArray *array,
                                             gconstpointer data,
                                             guint len);
#define     g_array_prepend_val             (a,v)
GArray*     g_array_prepend_vals            (GArray *array,
                                             gconstpointer data,
                                             guint len);
#define     g_array_insert_val              (a,i,v)
GArray*     g_array_insert_vals             (GArray *array,
                                             guint index_,
                                             gconstpointer data,
                                             guint len);
GArray*     g_array_remove_index            (GArray *array,
                                             guint index_);
GArray*     g_array_remove_index_fast       (GArray *array,
                                             guint index_);
GArray*     g_array_remove_range            (GArray *array,
                                             guint index_,
                                             guint length);
void        g_array_sort                    (GArray *array,
                                             GCompareFunc compare_func);
void        g_array_sort_with_data          (GArray *array,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);
#define     g_array_index                   (a,t,i)
GArray*     g_array_set_size                (GArray *array,
                                             guint length);
gchar*      g_array_free                    (GArray *array,
                                             gboolean free_segment);

Описание

Массивы подобные стандартным массивам C, за исключением того, что автоматически увеличиваются при добавлении элементов.

Массив элементов может быть любого размера (однако все элементы в пределах одного массива равны) и массив может автоматически очищаться до '0' и завершаться нулём.

Для создания нового массива используйте g_array_new().

Для добавления элементов в массив, используйте g_array_append_val(), g_array_append_vals(), g_array_prepend_val() и g_array_prepend_vals().

Для доступа к элементам массива, используйте g_array_index().

Для установки размера массива, используйте g_array_set_size().

Для освобождения массива, используйте g_array_free().

Пример 5. Using a GArray to store gint values

  GArray *garray;
  gint i;

  /* Мы создаём новый массив для хранения значений gint.
     Мы не хотим его завершать нулём или очищать до 0. */
  garray = g_array_new (FALSE, FALSE, sizeof (gint));
  for (i = 0; i < 10000; i++)
    g_array_append_val (garray, i);

  for (i = 0; i < 10000; i++)
    if (g_array_index (garray, gint, i) != i)
      g_print ("ERROR: got %d instead of %d\n",
               g_array_index (garray, gint, i), i);

  g_array_free (garray, TRUE);

Детали

GArray

typedef struct {
  gchar *data;
  guint len;
} GArray;

Содержит общедоступные поля массива.

gchar *data; указатель на элемент данных. Данные могут быть перемещены при добавлении элементов в GArray.
guint len; количество элементов в GArray.

g_array_new ()

GArray*     g_array_new                     (gboolean zero_terminated,
                                             gboolean clear_,
                                             guint element_size);

Создаёт новый GArray.

zero_terminated : TRUE если массив должен иметь в конце дополнительный элемент который установлен в 0.
clear_ : TRUE если элементы GArray должны автоматически очищаться до 0 при распределении.
element_size : размер каждого элемента в байтах.
Возвращает : новый GArray.

g_array_sized_new ()

GArray*     g_array_sized_new               (gboolean zero_terminated,
                                             gboolean clear_,
                                             guint element_size,
                                             guint reserved_size);

Создаёт новый GArray с предварительно распределёнными элементами reserved_size. Это помогает избежать частых перераспределений, если вы добавляете много элементов в массив. Однако помните, что размер массива остаётся 0.

zero_terminated : TRUE если массив должен иметь в конце дополнительный элемент с полностью чистыми битами.
clear_ : TRUE если все биты в массиве должны быть очищены до 0 при распределении.
element_size : размер каждого элемента в массиве.
reserved_size : количество предварительно распределённых элементов.
Возвращает : новый GArray.

g_array_append_val()

#define     g_array_append_val(a,v)

Добавляет значение в конец массива. Массив будет увеличивать размер автоматически, если необходимо.

Примечание

g_array_append_val() это макрос который использует ссылку на значение параметра v. Это значит что вы не можете использовать его с литеральными значениями, такими как "27". Вы должны использовать переменные.

a : GArray.
v : значение для добавления в GArray.
Возвращает : GArray.

g_array_append_vals ()

GArray*     g_array_append_vals             (GArray *array,
                                             gconstpointer data,
                                             guint len);

Добавляет len элементов в конец массива.

array : GArray.
data : указатель на элементы добавляемые в конец массива.
len : количество элементов для добавления.
Возвращает : GArray.

g_array_prepend_val()

#define     g_array_prepend_val(a,v)

Добавляет значение в начало массива. Массив будет автоматически увеличиваться, если необходимо.

Эта операция медленнее чем g_array_append_val() так как существующие элементы в массиве будут перемещаться освобождая пространство для нового элемента.

Примечание

g_array_prepend_val() это макрос который использует ссылку на значение параметра v. Это значит вы не можете использовать его с литеральными значениями, такими как "27". Вы должны использовать переменные.

a : GArray.
v : значение для подстановки в GArray.
Возвращает : GArray.

g_array_prepend_vals ()

GArray*     g_array_prepend_vals            (GArray *array,
                                             gconstpointer data,
                                             guint len);

Добавляет len элементов в начало массива.

Эта операция медленнее чем g_array_append_vals(), так как существующие элементы в массиве будут перемещаться освобождая пространство для новых элементов.

array : GArray.
data : указатель на элементы вставляемые в начало массива.
len : количество вставляемых элементов.
Возвращает : GArray.

g_array_insert_val()

#define     g_array_insert_val(a,i,v)

Вставляет элемент в массив в указанную позицию.

Примечание

g_array_insert_val() это макрос который использует ссылку на значение параметра v. Это значит что вы не можете использовать его с литеральными значениями такими как "27". Вы должны использовать переменные.

a : GArray.
i : позиция для помещения элемента.
v : значение вставляемое в массив.
Возвращает : GArray.

g_array_insert_vals ()

GArray*     g_array_insert_vals             (GArray *array,
                                             guint index_,
                                             gconstpointer data,
                                             guint len);

Вставляет len элементов в GArray в указанную позицию.

array : GArray.
index_ : позиция для помещения элементов.
data : указатель на вставляемые элементы.
len : количество вставляемых элементов.
Возвращает : GArray.

g_array_remove_index ()

GArray*     g_array_remove_index            (GArray *array,
                                             guint index_);

Удаляет элемент из указанной позиции в GArray. Следующие элементы перемещаются на одну позицию вниз.

array : GArray.
index_ : позиция удаляемого элемента.
Возвращает : GArray.

g_array_remove_index_fast ()

GArray*     g_array_remove_index_fast       (GArray *array,
                                             guint index_);

Удаляет элемент из указанной позиции в GArray. Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок GArray. Но она быстрее чем g_array_remove_index().

array : GArray.
index_ : позиция удаляемого элемента.
Возвращает : GArray.

g_array_remove_range ()

GArray*     g_array_remove_range            (GArray *array,
                                             guint index_,
                                             guint length);

Удаляет полученное количество элементов начиная с указанной позиции GArray. Следующие элементы перемещаются заполняя пустоту.

array : GArray.
index_ : позиция первого удаляемого элемента.
length : количество удаляемых элементов.
Возвращает : GArray.

Начиная с версии 2.4


g_array_sort ()

void        g_array_sort                    (GArray *array,
                                             GCompareFunc compare_func);

Сортирует GArray используя compare_func которая должна быть в стиле функции сравнения qsort() (возвращает значение меньше нуля если первый arg меньше чем второй arg, ноль если они равны, больше нуля если первый arg больше чем второй arg).

Если два сравниваемых элемента массива равны, их порядок сортировки в массиве неопределён.

array : GArray.
compare_func : функция сравнения.

g_array_sort_with_data ()

void        g_array_sort_with_data          (GArray *array,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

Похожа на g_array_sort(), но функция сравнения получает дополнительный аргумент пользовательских данных.

array : GArray.
compare_func : функция сравнения.
user_data : данные помещаемые в compare_func.

g_array_index()

#define     g_array_index(a,t,i)

Возвращает элемент GArray в указанной позиции. Возвращаемое значение приводится к указанному типу.

Пример 6. Getting указатель на element in a GArray

  EDayViewEvent *event;

  /* Возвращает указатель на третий элемент в массиве структур EDayViewEvent. */
  event = &g_array_index (events, EDayViewEvent, 3);

a : GArray.
t : тип элементов.
i : позиция возвращаемого элемента.
Возвращает : элемент GArray в позиции i.

g_array_set_size ()

GArray*     g_array_set_size                (GArray *array,
                                             guint length);

Устанавливает размер массива, расширяя его если необходимо. Если массив создаётся с clear_ установленным в TRUE, новые элементы устанавливаются в 0.

array : GArray.
length : новый размер GArray.
Возвращает : GArray.

g_array_free ()

gchar*      g_array_free                    (GArray *array,
                                             gboolean free_segment);

Освобождает память распределённую для GArray. Если free_segment это TRUE она также освобождает блок памяти содержащей элементы. Поместите FALSE если вы хотите освободить оболочку GArray, но тем ни менее сохранить для использования основной массив.

Примечание

Если массив элементов содержит динамически распределённую память, она должна освобождаться первой.

array : GArray.
free_segment : если TRUE фактические элементы данных также освобождаются.
Возвращает : элементы данных если free_segment это FALSE, иначе NULL

Asynchronous Queues

Asynchronous Queues — Асинхронное взаимодействие между потоками.

Краткое описание


#include <glib.h>


            GAsyncQueue;
GAsyncQueue* g_async_queue_new              (void);
GAsyncQueue* g_async_queue_ref              (GAsyncQueue *queue);
void        g_async_queue_unref             (GAsyncQueue *queue);
void        g_async_queue_push              (GAsyncQueue *queue,
                                             gpointer data);
void        g_async_queue_push_sorted       (GAsyncQueue *queue,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);
gpointer    g_async_queue_pop               (GAsyncQueue *queue);
gpointer    g_async_queue_try_pop           (GAsyncQueue *queue);
gpointer    g_async_queue_timed_pop         (GAsyncQueue *queue,
                                             GTimeVal *end_time);
gint        g_async_queue_length            (GAsyncQueue *queue);
void        g_async_queue_sort              (GAsyncQueue *queue,
                                             GCompareDataFunc func,
                                             gpointer user_data);

void        g_async_queue_lock              (GAsyncQueue *queue);
void        g_async_queue_unlock            (GAsyncQueue *queue);
void        g_async_queue_ref_unlocked      (GAsyncQueue *queue);
void        g_async_queue_unref_and_unlock  (GAsyncQueue *queue);
void        g_async_queue_push_unlocked     (GAsyncQueue *queue,
                                             gpointer data);
void        g_async_queue_push_sorted_unlocked
                                            (GAsyncQueue *queue,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);
gpointer    g_async_queue_pop_unlocked      (GAsyncQueue *queue);
gpointer    g_async_queue_try_pop_unlocked  (GAsyncQueue *queue);
gpointer    g_async_queue_timed_pop_unlocked
                                            (GAsyncQueue *queue,
                                             GTimeVal *end_time);
gint        g_async_queue_length_unlocked   (GAsyncQueue *queue);
void        g_async_queue_sort_unlocked     (GAsyncQueue *queue,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Описание

Часто вам нужна взаимосвязь между разными потоками. В общем более безопасно делать это не с помощью общей памяти, а явно передавать сообщения. Эти сообщения имеют смысл только если они асинхронны для много-поточных приложений, однако, синхронные операции могут также выполняться в тех же потоках.

Асинхронные структуры данных являются исключением из большинства других структур данных GLib, поскольку они могут использоваться одновременно в множестве потоков без явной блокировки и они имеют свой собственный встроенный подсчет ссылок. Так как асинхронные структуры данных будут всегда использоваться как минимум двумя параллельными потоками.

Для использования асинхронной структуры сначала нужно её создать с помощью g_async_queue_new(). Вновь созданная структура имеет количество ссылок равное 1. Каждый раз, когда другой поток создаёт новую ссылку на (то есть указатель на) структуру, количество её ссылок увеличивается (используется g_async_queue_ref()). Также, перед удаление этой ссылки, количество ссылок уменьшается (используется g_async_queue_unref()). После этого структура не может больше существовать, поэтому вы не должны обращаться к ней.

Поток который хочет отправить сообщение в эту структуру просто вызывает g_async_queue_push() для помещения сообщения в очередь.

Поток который ожидает сообщение из асинхронной структуры просто вызывает g_async_queue_pop() для этой очереди. Если нет доступных сообщений в указанной очереди, поток засыпает пока не появится сообщение. Сообщение удаляется из очереди и возвращается. Функции g_async_queue_try_pop() и g_async_queue_timed_pop() могут использоваться только для проверки присутствия сообщений или ожидания определенное время сообщений соответственно.

Почти для каждой функции существует два варианта, первый блокирует очередь, а второй не делает этого. Таким образом вы можете удерживать блокировку очереди (блокировать с помощью href="glib-Asynchronous-Queues.html#g-async-queue-lock">g_async_queue_lock() и освобождать с помощью g_async_queue_unlock()) через множественные инструкции доступа к очереди. Это может быть необходимо для гарантирования целостности очереди, но должно использоваться только когда это действительно необходимо, так как может усложнить вам жизнь при неблагоразумном использовании. Обычно вы должны использовать только варианты функции блокировки (то есть без суффикса _unlocked)

Детали

GAsyncQueue

typedef struct _GAsyncQueue GAsyncQueue;

Структура GAsyncQueue - это закрытая структура данных, которые представляют асинхронную очередь. Доступ к этим данным должен осуществляться только с помощью функций g_async_queue_*.


g_async_queue_new ()

GAsyncQueue* g_async_queue_new              (void);

Создаёт новую асинхронную структуру с начальным количеством ссылок равным 1.

Возвращает : новая GAsyncQueue.

g_async_queue_ref ()

GAsyncQueue* g_async_queue_ref              (GAsyncQueue *queue);

Увеличивает количество ссылок асинхронной queue на 1. Вы не должны удерживать блокировку для вызова этой функции.

queue : GAsyncQueue.
Возвращает : queue которую помещали (Начиная с версии 2.6)

g_async_queue_unref ()

void        g_async_queue_unref             (GAsyncQueue *queue);

Уменьшает количество ссылок асинхронной queue на 1. Если количество ссылок дошло до 0, queue уничтожается и память распределённая для неё освобождается. Таким образом вам нельзя использовать queue впоследствии. Вам не нужно удерживать блокировку для вызова этой функции.

queue : GAsyncQueue.

g_async_queue_push ()

void        g_async_queue_push              (GAsyncQueue *queue,
                                             gpointer data);

Помещает data в queue. data должен быть не NULL.

queue : GAsyncQueue.
data : data помещаемые в queue.

g_async_queue_push_sorted ()

void        g_async_queue_push_sorted       (GAsyncQueue *queue,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Вставляет data в queue используя func для определения новой позиции.

Перед использованием функции для вставки нового элемента, queue должна быть отсортирована.

Эта функция блокирует queue перед сортировкой и разблокирует после завершения работы.

Для примера func смотрите g_async_queue_sort().

queue : GAsyncQueue
data : data помещаемые в queue
func : GCompareDataFunc используемая для сортировки queue. Помещая в эту функцию два элемента queue, функция возвращает 0 если они эквивалентны, отрицательное если первый элемент должен быть выше в queue или положительное значение, если первый элемент должен быть ниже в queue чем второй элемент.
user_data : пользовательские данные помещаемые в func.

Начиная с версии 2.10


g_async_queue_pop ()

gpointer    g_async_queue_pop               (GAsyncQueue *queue);

Выталкивает данные из queue. Эта функция блокируется пока данные доступны.

queue : GAsyncQueue.
Возвращает : данные из очереди.

g_async_queue_try_pop ()

gpointer    g_async_queue_try_pop           (GAsyncQueue *queue);

Пытается вытолкнуть данные из очереди queue. Если данные не доступны, возвращает NULL.

queue : GAsyncQueue.
Возвращает : данные из очереди или NULL, если нет немедленно доступных данных.

g_async_queue_timed_pop ()

gpointer    g_async_queue_timed_pop         (GAsyncQueue *queue,
                                             GTimeVal *end_time);

Выталкивает данные из очереди queue. Если данные получены перед end_time, возвращает NULL.

Для простоты расчёта параметра end_time можно использовать комбинацию g_get_current_time() и g_time_val_add().

queue : GAsyncQueue.
end_time : GTimeVal, определяющая время завершения.
Возвращает : данные из очереди или NULL, если данные получены раньше end_time.

g_async_queue_length ()

gint        g_async_queue_length            (GAsyncQueue *queue);

Возвращает длину очереди, отрицательное значение означает ожидание потоков, положительное значение означает доступность ввода в queue. Фактически эта функция возвращает количество элементов данных в очереди минус количество ожидающих потоков. Таким образом возвращаемое значение 0 может означать 'n' входов в очередь и 'n' потоков ожидания. Это может произойти или из-за блокировки очереди или из-за планирования.

queue : GAsyncQueue.
Возвращает : длина queue.

g_async_queue_sort ()

void        g_async_queue_sort              (GAsyncQueue *queue,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Сортирует queue используя func.

Эта функция блокирует queue перед сортировкой и разблокирует после завершения.

Если вам нужно отсортировать список по приоритету, чтобы убедиться что низший приоритет будет сверху очереди, вы должны использовать:

 
 gint32 id1;
 gint32 id2;
  
 id1 = GPOINTER_TO_INT (element1);
 id2 = GPOINTER_TO_INT (element2);
  
 return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);

queue : GAsyncQueue
func : GCompareDataFunc используемая для сортировки queue. Помещая в эту функцию два элемента queue, функция возвращает 0 если они эквивалентны, отрицательное если первый элемент должен быть выше в queue или положительное значение, если первый элемент должен быть ниже в queue чем второй элемент.
user_data : пользовательские данные помещаемые в func

Начиная с версии 2.10


g_async_queue_lock ()

void        g_async_queue_lock              (GAsyncQueue *queue);

Блокирует queue's. После этого вы можете вызвать только g_async_queue_*_unlocked() вариант функции для этой queue. Иначе она зависнет (deadlock).

queue : GAsyncQueue.

g_async_queue_unlock ()

void        g_async_queue_unlock            (GAsyncQueue *queue);

Снимает блокировку queue's.

queue : GAsyncQueue.

g_async_queue_ref_unlocked ()

void        g_async_queue_ref_unlocked      (GAsyncQueue *queue);

Внимание

g_async_queue_ref_unlocked устарела и не должна использоваться во вновь создаваемом коде.

Увеличивает количество ссылок асинхронной queue на 1.

Устарела: Начиная с версии 2.8, подсчёт ссылок сделан атомарным, поэтому g_async_queue_ref() может использоваться независимо от блокировки queue's.

queue : GAsyncQueue.

g_async_queue_unref_and_unlock ()

void        g_async_queue_unref_and_unlock  (GAsyncQueue *queue);

Внимание

g_async_queue_unref_and_unlock устарела и не должна использоваться во вновь создаваемом коде.

Уменьшает количество ссылок асинхронной queue на 1 и отменяет блокировку. Эта функция должна вызываться во время удержания блокировки queue's. Если количество ссылок достигло 0, queue будет уничтожена и память распределённая для неё будет освобождена.

Устарела: Начиная с версии 2.8, подсчёт ссылок выполняется атомарно, поэтому g_async_queue_unref() может использоваться независимо от блокировки queue's.

queue : GAsyncQueue.

g_async_queue_push_unlocked ()

void        g_async_queue_push_unlocked     (GAsyncQueue *queue,
                                             gpointer data);

Помещает data в queue. data должен быть не NULL. Эта функция должна вызываться в течении блокировки queue's.

queue : GAsyncQueue.
data : данные для помещения в queue.

g_async_queue_push_sorted_unlocked ()

void        g_async_queue_push_sorted_unlocked
                                            (GAsyncQueue *queue,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Вставляет data в queue используя func для определения новой позиции.

Перед использованием этой функции для вставки нового элемента queue должна быть отсортирована.

Эта функция вызывается в течении блокировки queue's.

В качестве примера func смотрите g_async_queue_sort().

queue : GAsyncQueue
data : данные для помещения в queue
func : GCompareDataFunc используемая для сортировки queue. Помещая в эту функцию два элемента queue, функция возвращает 0 если они эквивалентны, отрицательное если первый элемент должен быть выше в queue или положительное значение, если первый элемент должен быть ниже в queue чем второй элемент.
user_data : пользовательские данные помещаемые в func.

Начиная с версии 2.10


g_async_queue_pop_unlocked ()

gpointer    g_async_queue_pop_unlocked      (GAsyncQueue *queue);

Выталкивает данные из queue. Функция блокируется пока данные доступны. Должна вызываться во время блокировки queue's.

queue : GAsyncQueue.
Возвращает : данные из очереди.

g_async_queue_try_pop_unlocked ()

gpointer    g_async_queue_try_pop_unlocked  (GAsyncQueue *queue);

Пытается вытолкнуть данные из queue. Если данные не доступны, возвращается NULL. Функция должна вызываться во время блокировки queue's.

queue : GAsyncQueue.
Возвращает : данные из очереди или NULL, если нет немедленно доступных данных.

g_async_queue_timed_pop_unlocked ()

gpointer    g_async_queue_timed_pop_unlocked
                                            (GAsyncQueue *queue,
                                             GTimeVal *end_time);

Выталкивает данные из queue. Если данные получены раньше end_time, возвращает NULL. Эта функция должна вызываться во время блокировки queue's.

Для простоты расчета end_time можно использовать комбинацию g_get_current_time() и g_time_val_add().

queue : GAsyncQueue.
end_time : GTimeVal, определяющая время завершения.
Возвращает : данные из очереди или NULL, если нет данных полученных раньше end_time.

g_async_queue_length_unlocked ()

gint        g_async_queue_length_unlocked   (GAsyncQueue *queue);

Возвращает длину очереди, отрицательное значение означает ожидание потоков, положительное значение означает доступность ввода в queue. Фактически эта функция возвращает количество элементов данных в очереди минус количество ожидающих потоков. Таким образом возвращаемое значение 0 может означать 'n' входов в очередь и 'n' потоков ожидания. Это может произойти или из-за блокировки очереди или из-за планирования. Функция должна вызываться во время блокировки очереди.

queue : GAsyncQueue.
Возвращает : длина очереди queue.

g_async_queue_sort_unlocked ()

void        g_async_queue_sort_unlocked     (GAsyncQueue *queue,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Сортирует queue используя func.

Эта функция вызывается во время блокировки queue's.

queue : GAsyncQueue
func : GCompareDataFunc используемая для сортировки queue. Помещая в эту функцию два элемента queue, функция возвращает 0 если они эквивалентны, отрицательное если первый элемент должен быть выше в queue или положительное значение, если первый элемент должен быть ниже в queue чем второй элемент.
user_data : пользовательские данные для func

Начиная с версии 2.10


Атомарные операции

Atomic Operations — основные атомарные операции с целочисленными и указателями

Краткое описание


#include <glib.h>


gint        g_atomic_int_get                (volatile gint *atomic);
void        g_atomic_int_set                (volatile gint *atomic,
                                             gint newval);
void        g_atomic_int_add                (volatile gint *atomic,
                                             gint val);
gint        g_atomic_int_exchange_and_add   (volatile gint *atomic,
                                             gint val);
gboolean    g_atomic_int_compare_and_exchange
                                            (volatile gint *atomic,
                                             gint oldval,
                                             gint newval);
gpointer    g_atomic_pointer_get            (volatile gpointer *atomic);
void        g_atomic_pointer_set            (volatile gpointer *atomic,
                                             gpointer newval);
gboolean    g_atomic_pointer_compare_and_exchange
                                            (volatile gpointer *atomic,
                                             gpointer oldval,
                                             gpointer newval);
void        g_atomic_int_inc                (gint *atomic);
gboolean    g_atomic_int_dec_and_test       (gint *atomic);

Описание

Следующие функции могут использоваться для атомарного доступа к целочисленным и указателям. Иначе они реализуются как действующие ассемблерные функции на большинстве платформ и используют медленный переход в аварийный режим (fall-backs). Их использование может иногда уберечь вас от использования расточительной работы GMutex для защиты целочисленных и указателей.

Самое важное использование - это подсчёт ссылок. Используя g_atomic_int_inc() и g_atomic_int_dec_and_test() выполняется очень быстрая операция подсчёта ссылок.

Примечание

Вы не должны непосредственно читать целочисленные или указатели с одновременным многопоточным доступом, а использовать вместо этого функции атомарного доступа. Таким образом, всегда используйте g_atomic_int_get() и g_atomic_pointer_get() для чтения извне. Они обеспечивают необходимый механизм синхронизации как границы памяти для одновременного обращения к распределённой памяти.

Примечание

Если вы используете эти функции для чего то кроме простого подсчета ссылок, вы должны знать реальную реализацию этого. Существует буквально тысячи способов навредить себе. Поэтому если вы сомневаетесь, используйте GMutex. Если вы не знаете что такое границы памяти не используйте ничего кроме g_atomic_int_inc() и g_atomic_int_dec_and_test().

Примечание

Не безопасно устанавливать целочисленное или указатель простым назначением, когда к ним параллельно обращаются другие нити (threads) со следующими функциями. Используйте g_atomic_int_compare_and_exchange() или g_atomic_pointer_compare_and_exchange() соответственно.

Детали

g_atomic_int_get ()

gint        g_atomic_int_get                (volatile gint *atomic);

Читает значение целочисленного на которое указывает atomic. Также действует как граница памяти.

atomic : указатель на целочисленное
Возвращает : значение *atomic

Начиная с версии 2.4


g_atomic_int_set ()

void        g_atomic_int_set                (volatile gint *atomic,
                                             gint newval);

Устанавливает значение целочисленного указанного atomic. Также действует как граница памяти.

atomic : указатель на целочисленное
newval : новое значение

Начиная с версии 2.10


g_atomic_int_add ()

void        g_atomic_int_add                (volatile gint *atomic,
                                             gint val);

Атомарно добавляет val к целочисленному указанному atomic. Также действует как граница памяти.

atomic : указатель на целочисленное.
val : значение добавляемое к *atomic.

Начиная с версии 2.4


g_atomic_int_exchange_and_add ()

gint        g_atomic_int_exchange_and_add   (volatile gint *atomic,
                                             gint val);

Атомарно добавляет val к целочисленному указанному atomic. Возвращает значение *atomic непосредственно перед добавлением. Также действует как граница памяти.

atomic : указатель на целочисленное.
val : значение добавляемое к *atomic.
Возвращает : значение *atomic перед добавлением.

Начиная с версии 2.4


g_atomic_int_compare_and_exchange ()

gboolean    g_atomic_int_compare_and_exchange
                                            (volatile gint *atomic,
                                             gint oldval,
                                             gint newval);

Сравнивает oldval с целочисленным указанным atomic и если они равны, атомарно обменивает *atomic с newval. Также действует как граница памяти.

atomic : указатель на целочисленное.
oldval : принятое старое значение *atomic.
newval : новое значение *atomic.
Возвращает : TRUE, если *atomic был равен oldval. Иначе FALSE.

Начиная с версии 2.4


g_atomic_pointer_get ()

gpointer    g_atomic_pointer_get            (volatile gpointer *atomic);

Читает значение указателя на который указывает atomic. Также действует как граница памяти.

atomic : указатель на gpointer.
Возвращает : значение добавляемое к *atomic.

Начиная с версии 2.4


g_atomic_pointer_set ()

void        g_atomic_pointer_set            (volatile gpointer *atomic,
                                             gpointer newval);

Устанавливает значение указателя на который указывает atomic. Также действует как граница памяти.

atomic : указатель на gpointer
newval : новое значение

Начиная с версии 2.10


g_atomic_pointer_compare_and_exchange ()

gboolean    g_atomic_pointer_compare_and_exchange
                                            (volatile gpointer *atomic,
                                             gpointer oldval,
                                             gpointer newval);

Сравнивает oldval с указателем на который указывает atomic и если они равны, атомарно обменивает *atomic с newval. Также действует как граница памяти.

atomic : указатель на gpointer.
oldval : принятое старое значение *atomic.
newval : новое значение *atomic.
Возвращает : TRUE, если *atomic был равен oldval. Иначе FALSE.

Начиная с версии 2.4


g_atomic_int_inc ()

void        g_atomic_int_inc                (gint *atomic);

Атомарно увеличивает указатель на который указывает atomic на 1.

atomic : указатель на целочисленное.

Начиная с версии 2.4


g_atomic_int_dec_and_test ()

gboolean    g_atomic_int_dec_and_test       (gint *atomic);

Атомарно уменьшает указатель на который указывает atomic на 1.

atomic : указатель на целочисленное.
Возвращает : TRUE, если целочисленное на которое указывает atomic после уменьшения равно 0.

Начиная с версии 2.4

Смотрите также

GMutex

GLib взаимные исключения.


Automatic String Completion

Automatic String Completion — Поддержка для автоматического завершения используя группу целевых строк.

Краткое описание


#include <glib.h>


            GCompletion;
GCompletion* g_completion_new               (GCompletionFunc func);
gchar*      (*GCompletionFunc)              (gpointer );
void        g_completion_add_items          (GCompletion *cmp,
                                             GList *items);
void        g_completion_remove_items       (GCompletion *cmp,
                                             GList *items);
void        g_completion_clear_items        (GCompletion *cmp);
GList*      g_completion_complete           (GCompletion *cmp,
                                             const gchar *prefix,
                                             gchar **new_prefix);
GList*      g_completion_complete_utf8      (GCompletion *cmp,
                                             const gchar *prefix,
                                             gchar **new_prefix);
void        g_completion_set_compare        (GCompletion *cmp,
                                             GCompletionStrncmpFunc strncmp_func);
gint        (*GCompletionStrncmpFunc)       (const gchar *s1,
                                             const gchar *s2,
                                             gsize n);
void        g_completion_free               (GCompletion *cmp);

Описание

GCompletion обеспечивает поддержку автоматического завершения строки используя любую группу целевых строк. Это обычно используется для завершения имён файлов как в обычных оболочках UNIX.

GCompletion создаётся используя g_completion_new(). Целевые элементы добавляются и удаляются с помощью g_completion_add_items(), g_completion_remove_items() и g_completion_clear_items(). Попытка завершения запрашивается с помощью g_completion_complete() или g_completion_complete_utf8(). GCompletion освобождается с помощью g_completion_free() когда больше не нужна.

Завершающими элементами могут быть просто строки (например имена файлов), или указателями на произвольные структуры данных. Если используются структуры данных вы должны обеспечить GCompletionFunc в g_completion_new(), которая находит элементы строк в структуре данных. Вы можете изменять способ сравнения строк устанавливая разные GCompletionStrncmpFunc в g_completion_set_compare().

Детали

GCompletion

typedef struct {
  GList* items;
  GCompletionFunc func;
 
  gchar* prefix;
  GList* cache;
  GCompletionStrncmpFunc strncmp_func;
} GCompletion;

Структура данных используемая для автоматического завершения.

GList *items; список целевых элементов (строки или структуры данных).
GCompletionFunc func; функция вызываемая для получения строки связанной с целевым элементом. Может быть NULL если целевые элементы являются строками.
gchar *prefix; последний префикс помещаемый в g_completion_complete() или g_completion_complete_utf8().
GList *cache; список элементов который начинается с prefix.
GCompletionStrncmpFunc strncmp_func; функция используемая для сравнения строк. Используйте g_completion_set_compare() для изменения этой функции.

g_completion_new ()

GCompletion* g_completion_new               (GCompletionFunc func);

Создаёт новую GCompletion.

func : функция вызываемая для возврата строки представляющей элемент в GCompletion, или NULL если строки будут использоваться как элементы GCompletion.
Возвращает : новая структура GCompletion.

GCompletionFunc ()

gchar*      (*GCompletionFunc)              (gpointer );

Определяет тип функции помещаемой в g_completion_new(). Она должна возвращать строку соответствующую полученному целевому элементу. Используется когда вы используете структуры данных как элементы GCompletion.

Param1 : завершающий элемент.
Возвращает : строка соответствующая элементу.

g_completion_add_items ()

void        g_completion_add_items          (GCompletion *cmp,
                                             GList *items);

Добавляет элементы в GCompletion.

cmp : GCompletion.
items : список добавляемых элементов.

g_completion_remove_items ()

void        g_completion_remove_items       (GCompletion *cmp,
                                             GList *items);

Удаляет элементы из GCompletion.

cmp : GCompletion.
items : элементы для удаления.

g_completion_clear_items ()

void        g_completion_clear_items        (GCompletion *cmp);

Удаляет все элементы для удаления GCompletion.

cmp : GCompletion.

g_completion_complete ()

GList*      g_completion_complete           (GCompletion *cmp,
                                             const gchar *prefix,
                                             gchar **new_prefix);

Пытается завершить строку prefix используя целевые элементы GCompletion.

cmp : GCompletion.
prefix : строковый префикс, обычно печатается пользователем, который сравнивается с каждым элементом структуры.
new_prefix : если не-NULL, возвращает самый длинный префикс который является основой для всех элементов соответствующих prefix, или NULL если нет элементов соответствующих prefix. Эта строка должна освобождаться когда больше не нужна.
Возвращает : список элементов строки которых начинаются с prefix. Не должно изменяться.

g_completion_complete_utf8 ()

GList*      g_completion_complete_utf8      (GCompletion *cmp,
                                             const gchar *prefix,
                                             gchar **new_prefix);

Пытается завершить строку prefix используя целевые элементы GCompletion. В отличие от g_completion_complete(), эта функция возвращает самый длинный prefix который является допустимой строкой UTF-8, опуская возможные общие части символа.

Вы должны использовать эту функцию вместо g_completion_complete() если ваши элементы являются строками UTF-8.

cmp : the GCompletion
prefix : строка префикс, обычно используется пользователем, которая сравнивается с каждым элементом
new_prefix : если не-NULL, возвращает самый длинный префикс который является основой для всех элементов соответствующих prefix, или NULL если нет элементов соответствующих prefix. Эта строка должна освобождаться когда больше не нужна.
Возвращает : список элементов строки которых начинаются с prefix. Не должен меняться.

Начиная с версии 2.4


g_completion_set_compare ()

void        g_completion_set_compare        (GCompletion *cmp,
                                             GCompletionStrncmpFunc strncmp_func);

Устанавливает функцию используемую для сравнения строк. По умолчанию строки сравниваются функцией strncmp().

cmp : GCompletion.
strncmp_func : функция сравнения строк.

GCompletionStrncmpFunc ()

gint        (*GCompletionStrncmpFunc)       (const gchar *s1,
                                             const gchar *s2,
                                             gsize n);

Определяет тип функции помещаемой в g_completion_set_compare(). Используется когда вы используете строки как элементы GCompletion.

s1 : строка для сравнения с s2.
s2 : строка для сравнения с s1.
n : максимальное количество байт для сравнения.
Возвращает : целочисленное меньше, равное, или больше нуля если первые найденные n байт s1, соответственно меньше, равны, или больше чем первые n байт s2.

g_completion_free ()

void        g_completion_free               (GCompletion *cmp);

Освобождает всю память используемую для GCompletion.

cmp : GCompletion.

Balanced Binary Trees

Balanced Binary Trees — Отсортированная коллекция пар ключ/значение оптимизированная для поиска и пересечения в определённом порядке.

Краткое описание


#include <glib.h>


            GTree;
GTree*      g_tree_new                      (GCompareFunc key_compare_func);
GTree*      g_tree_new_with_data            (GCompareDataFunc key_compare_func,
                                             gpointer key_compare_data);
GTree*      g_tree_new_full                 (GCompareDataFunc key_compare_func,
                                             gpointer key_compare_data,
                                             GDestroyNotify key_destroy_func,
                                             GDestroyNotify value_destroy_func);
void        g_tree_insert                   (GTree *tree,
                                             gpointer key,
                                             gpointer value);
void        g_tree_replace                  (GTree *tree,
                                             gpointer key,
                                             gpointer value);
gint        g_tree_nnodes                   (GTree *tree);
gint        g_tree_height                   (GTree *tree);
gpointer    g_tree_lookup                   (GTree *tree,
                                             gconstpointer key);
gboolean    g_tree_lookup_extended          (GTree *tree,
                                             gconstpointer lookup_key,
                                             gpointer *orig_key,
                                             gpointer *value);
void        g_tree_foreach                  (GTree *tree,
                                             GTraverseFunc func,
                                             gpointer user_data);
void        g_tree_traverse                 (GTree *tree,
                                             GTraverseFunc traverse_func,
                                             GTraverseType traverse_type,
                                             gpointer user_data);
gboolean    (*GTraverseFunc)                (gpointer key,
                                             gpointer value,
                                             gpointer data);
enum        GTraverseType;
gpointer    g_tree_search                   (GTree *tree,
                                             GCompareFunc search_func,
                                             gconstpointer user_data);
gboolean    g_tree_remove                   (GTree *tree,
                                             gconstpointer key);
gboolean    g_tree_steal                    (GTree *tree,
                                             gconstpointer key);
void        g_tree_destroy                  (GTree *tree);

Описание

Структура GTree и связанные с ней функции обеспечивают отсортированную коллекцию пар ключ/значение оптимизированную для поиска и пересечения в определённом порядке.

Для создания новой GTree используйте g_tree_new().

Для вставки пары ключ/значение в GTree используйте g_tree_insert().

Для поиска значения соответствующего полученному ключу, используйте g_tree_lookup() и g_tree_lookup_extended().

Для определения количества ветвей в GTree, используйте g_tree_nnodes(). Для определения высоты GTree, используйте g_tree_height().

Для пересечения GTree, вызывая функцию для каждой ветви посещаемой при пересечении, используйте g_tree_foreach().

Для удаления пар ключ/значение используйте g_tree_remove().

Для уничтожения GTree, используйте g_tree_destroy().

Детали

GTree

typedef struct _GTree GTree;

Структура GTree это непрозрачная структура данных представляющая Balanced Binary Tree. Доступ к ней разрешён только функциям перечисленным ниже.


g_tree_new ()

GTree*      g_tree_new                      (GCompareFunc key_compare_func);

Создаёт новую GTree.

key_compare_func : функция используемая для упорядочивания ветвей в GTree. Она должна возвращать значения подобно стандартной функции strcmp() - 0 если два аргумента равны, отрицательное значение если первый аргумент располагается перед вторым, или положительное значение если первый аргумент располагается после второго.
Возвращает : новая GTree.

g_tree_new_with_data ()

GTree*      g_tree_new_with_data            (GCompareDataFunc key_compare_func,
                                             gpointer key_compare_data);

Создаёт новую GTree при помощи функции сравнения которая принимает пользовательские данные. Смотрите g_tree_new() для подробностей.

key_compare_func : функция сравнения в стиле qsort().
key_compare_data : данные помещаемые в функцию сравнения.
Возвращает : новая GTree.

g_tree_new_full ()

GTree*      g_tree_new_full                 (GCompareDataFunc key_compare_func,
                                             gpointer key_compare_data,
                                             GDestroyNotify key_destroy_func,
                                             GDestroyNotify value_destroy_func);

Создаёт новую GTree подобно g_tree_new() и позволяет указать функцию освобождающую память распределяемую для ключей и значений которые получены при удалении элементов из GTree.

key_compare_func : функция сравнения в стиле qsort().
key_compare_data : данные помещаемые в функцию сравнения.
key_destroy_func : функция освобождающая память распределённую для ключей используемых при удалении элементов из GTree или NULL если вы не хотите указывать такую функцию.
value_destroy_func : функция освобождающая память распределённую для значений используемых при удалении элементов из GTree или NULL если вы не хотите использовать такую функцию.
Возвращает : новая GTree.

g_tree_insert ()

void        g_tree_insert                   (GTree *tree,
                                             gpointer key,
                                             gpointer value);

Вставляет пару ключ/значение в GTree. Если полученный ключ уже существует в GTree соответствующее ему значение устанавливается в новое значение. Если вы указали value_destroy_func при создании GTree, старое значение освободится с помощью этой функции. Если вы указали key_destroy_func при создании GTree, помещаемый ключ освобождается с помощью этой функции.

Дерево автоматически сбалансировано, так как новые пары ключ/значение добавляются таким образом, чтобы расстояние от корня до листьев было минимальным на сколько это возможно.

tree : GTree.
key : вставляемый ключ.
value : значение соответствующее ключу.

g_tree_replace ()

void        g_tree_replace                  (GTree *tree,
                                             gpointer key,
                                             gpointer value);

Вставляет новый ключ и значение в GTree подобно g_tree_insert(). Отличие в том, что если ключ уже существует в GTree, он переписывается новым ключом. Если вы указали value_destroy_func при создании GTree, старое значение освобождается с помощью этой функции. Если вы указали key_destroy_func при создании GTree, старый ключ освобождается при помощи этой функции.

Дерево автоматически сбалансировано, так как новые пары ключ/значение добавляются таким образом, чтобы расстояние между корнем и листьями было минимально возможным.

tree : GTree.
key : ключ для вставки.
value : значение соответствующее ключу.

g_tree_nnodes ()

gint        g_tree_nnodes                   (GTree *tree);

Определяет номер узла в GTree.

tree : GTree.
Возвращает : номер узла в GTree.

g_tree_height ()

gint        g_tree_height                   (GTree *tree);

Определяет высоту GTree.

Если GTree не содержит ветвей, высота равна 0. Если GTree содержит только корневую ветвь, высота равна 1. Если корневая ветвь имеет дочернюю, высота равна 2, и т.д..

tree : GTree.
Возвращает : высота GTree.

g_tree_lookup ()

gpointer    g_tree_lookup                   (GTree *tree,
                                             gconstpointer key);

Определяет значение соответствующее полученному ключу. Так как GTree автоматически балансируется при добавлении пар ключ/значение, ключ находится очень быстро.

tree : GTree.
key : ключ для поиска.
Возвращает : значение соответствующее ключу, или NULL если ключ был найден.

g_tree_lookup_extended ()

gboolean    g_tree_lookup_extended          (GTree *tree,
                                             gconstpointer lookup_key,
                                             gpointer *orig_key,
                                             gpointer *value);

Находит ключ в GTree, возвращает оригинальный ключ, связанное с ним значение и gboolean которое TRUE если ключ был найден. Это полезно если вам необходимо освободить память связанную с оригинальным ключом, например перед вызовом g_tree_remove().

tree : GTree.
lookup_key : разыскиваемый ключ.
orig_key : возвращаемый оригинальный ключ.
value : возвращает значение связанное с ключом.
Возвращает : TRUE если ключ найден в GTree.

g_tree_foreach ()

void        g_tree_foreach                  (GTree *tree,
                                             GTraverseFunc func,
                                             gpointer user_data);

Вызывает указанную функцию для каждой пары ключ/значение в GTree. В функцию помещаются ключ и значение для каждой пары, а также полученный параметр data. Дерево пересекается в порядке сортировки.

Дерево не может быть изменено в процессе итерации через него (вы не можете добавлять/удалять элементы). Для удаления всех элементов соответствующих предикате, вам необходимо добавить каждый элемент в список в вашу GTraverseFunc, так как вы проходите по дереву, затем проходите через список и удаляете каждый элемент.

tree : GTree.
func : функция вызываемая для каждой посещаемой ветви. Если эта функция возвращает TRUE, пересечение останавливается.
user_data : пользовательские данные помещаемые в функцию.

g_tree_traverse ()

void        g_tree_traverse                 (GTree *tree,
                                             GTraverseFunc traverse_func,
                                             GTraverseType traverse_type,
                                             gpointer user_data);

Внимание

g_tree_traverse устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Порядок сбалансированного дерева несколько произволен. Если вы просто хотите посетить все ветви в сортировочном порядке, используйте g_tree_foreach(). Если вы действительно нуждаетесь в посещении ветвей в другом порядке, рассмотрите использование N-ary Tree.

Вызывает полученную функцию для каждой ветви в GTree.

tree : GTree.
traverse_func : функция вызываемая для каждой посещаемой ветви. Если эта функция возвращает TRUE, пересечение прекращается.
traverse_type : порядок в котором посещаются ветви, один из G_IN_ORDER, G_PRE_ORDER и G_POST_ORDER.
user_data : пользовательские данные помещаемые в функцию.

GTraverseFunc ()

gboolean    (*GTraverseFunc)                (gpointer key,
                                             gpointer value,
                                             gpointer data);

Определяет тип функции помещаемой в g_tree_traverse(). Она помещает пару ключ/значение для каждой ветви, вместе с параметром user_data помещаемым в g_tree_traverse(). Если функция вернула TRUE, пересечение прекращается.

key : ключ GTree ветви.
value : значение соответствующее ключу.
data : пользовательские данные помещаемые в g_tree_traverse().
Возвращает : TRUE для остановки пересечения.

enum GTraverseType

typedef enum
{
  G_IN_ORDER,
  G_PRE_ORDER,
  G_POST_ORDER,
  G_LEVEL_ORDER
} GTraverseType;

Определяет тип функции пересечения g_tree_traverse(), g_node_traverse() и g_node_find().

G_IN_ORDER сначала посещает левую дочернюю ветвь, затем саму ветвь, затем правую дочернюю ветвь. Используйте это если вам нужен вывод сортированный согласно функции сравнения.
G_PRE_ORDER посещает ветвь, затем дочерние.
G_POST_ORDER посещает дочерние ветви, затем саму ветвь.
G_LEVEL_ORDER не реализовано для Balanced Binary Trees. Для N-ary Trees, первой посещается корневая ветвь, затем её дочерние ветви, затем их дочерние, и так далее. Помните что это менее эффективно чем другие порядки.

g_tree_search ()

gpointer    g_tree_search                   (GTree *tree,
                                             GCompareFunc search_func,
                                             gconstpointer user_data);

Находит GTree используя search_func.

search_func вызывается с указателем на ключ пары ключ/значение в дереве, переданном в user_data. Если search_func возвращает 0 для пары ключ/значение, то g_tree_search_func() вернёт значение этой пары. Если search_func возвращает -1, то поиск продолжается среди пар ключ/значение, которые имеют меньший ключ; если search_func возвращает 1, поиск продолжается среди пар ключ/значение которые имеют больший ключ.

tree : GTree.
search_func : функция используемая для поиска GTree.
user_data : данные помещаемые как второй аргумент в функцию search_func.
Возвращает : значение соответствующее найденному ключу, или NULL если ключ был найден.

g_tree_remove ()

gboolean    g_tree_remove                   (GTree *tree,
                                             gconstpointer key);

Удаляет пару ключ/значение из GTree.

Если GTree создана с использованием g_tree_new_full(), ключ и значение освобождаются используя указанную функцию уничтожения, иначе вы должны убедиться что освободили все динамически распределённые значения самостоятельно. Если ключ не существует в GTree, функция ничего не делает.

tree : GTree.
key : удаляемый ключ.
Возвращает : TRUE если ключ найден (до версии 2.8, эта функция ничего не возвращала)

g_tree_steal ()

gboolean    g_tree_steal                    (GTree *tree,
                                             gconstpointer key);

Удаляет ключ со связанным с ним значением из GTree без вызова функции уничтожения ключа и значения.

Если ключ не существует в GTree, функция ничего не делает.

tree : GTree.
key : удаляемый ключ.
Возвращает : TRUE если ключ найден (до версии 2.8, эта функция ничего не возвращала)

g_tree_destroy ()

void        g_tree_destroy                  (GTree *tree);

Уничтожает GTree. Если ключ и/или значение распределены динамически, вы должны либо освобождать их первыми либо создать GTree используя g_tree_new_full(). В последнем случае функция уничтожения указанная вами будет вызвана для всех ключей и значений перед уничтожением GTree.

tree : GTree.

Кодировка Base64

Base64 Encoding — кодирование и декодирование данных в формат Base64

Краткое описание


#include <glib.h>


gsize       g_base64_encode_step            (const guchar *in,
                                             gsize len,
                                             gboolean break_lines,
                                             gchar *out,
                                             gint *state,
                                             gint *save);
gsize       g_base64_encode_close           (gboolean break_lines,
                                             gchar *out,
                                             gint *state,
                                             gint *save);
gchar*      g_base64_encode                 (const guchar *data,
                                             gsize len);
gsize       g_base64_decode_step            (const gchar *in,
                                             gsize len,
                                             guchar *out,
                                             gint *state,
                                             guint *save);
guchar*     g_base64_decode                 (const gchar *text,
                                             gsize *out_len);

Описание

Base64 это кодировка которая позволяет кодировать последовательность произвольных байт в последовательность печатных ASCII символов. Для определения Base64, смотрите RFC 1421 или RFC 2045. Base64 в основном используется как кодировка передачи MIME для email.

GLib поддерживает возрастающую кодировку используя g_base64_encode_step() и g_base64_encode_close(). Возрастающее декодирование может быть выполнено с помощью g_base64_decode_step(). Для кодировки или декодирования данных в одном направлении, используйте g_base64_encode() или g_base64_decode().

Поддержка кодировки Base64 была добавлена в GLib 2.12.

Детали

g_base64_encode_step ()

gsize       g_base64_encode_step            (const guchar *in,
                                             gsize len,
                                             gboolean break_lines,
                                             gchar *out,
                                             gint *state,
                                             gint *save);

Возрастающее кодирование двоичных данных в строковое представление Base-64. Вызывая эту функцию многократно вы можете конвертировать данные в части избегая необходимости иметь полностью закодированные данные в памяти.

Когда все данные конвертированы вы должны вызвать g_base64_encode_close() для сброса на диск сохранённого состояния.

Буфер вывода должен быть достаточно большим чтобы вместить все данные которые будут в него записаны. Из=за способа кодирования base64 вам потребуется по крайней мере: len * 4 / 3 + 6 байт. Если вы включили прерывание строк (line-breaking) вам потребуется как минимум: len * 4 / 3 + len * 4 / (3 * 72) + 7 байт.

break_lines обычно используются когда данные закодированные в base64-кодировку помещаются в письма (emails). Это распределяет строки в 72 столбца, вместо помещения всего текста в одну строку, что позволяет избежать проблем с длинными строками в почтовой системе.

in : двоичные данные для кодирования.
len : длина in.
break_lines : прерываются ли длинные строки
out : указатель на буфер назначения
state : Сохраняемое состояние между этапами, начиная с 0
save : Сохраняемое состояние между этапами, начиная с 0
Возвращает : Количество записанных байт вывода

Начиная с версии 2.12


g_base64_encode_close ()

gsize       g_base64_encode_close           (gboolean break_lines,
                                             gchar *out,
                                             gint *state,
                                             gint *save);

Сбрасывает на диск состояние из последовательных вызовов g_base64_encode_step().

break_lines : прерываются ли длинные строки
out : указатель на буфер назначения
state : Сохраняемое состояние из g_base64_encode_step()
save : Сохраняемое состояние из g_base64_encode_step()
Возвращает : Количество записанных байт

Начиная с версии 2.12


g_base64_encode ()

gchar*      g_base64_encode                 (const guchar *data,
                                             gsize len);

Кодирует последовательность двоичных данных в текстовое представление Base-64.

data : двоичные данные для кодирования.
len : длина data.
Возвращает : вновь распределённая, zero-завершённая строка в кодировке Base-64 представляющая данные data.

Начиная с версии 2.12


g_base64_decode_step ()

gsize       g_base64_decode_step            (const gchar *in,
                                             gsize len,
                                             guchar *out,
                                             gint *state,
                                             guint *save);

Возрастающее кодирование последовательности двоичных данных в текстовое представление Base-64. Вызывая эту функцию многократно вы можете конвертировать данные частями избегая необходимость иметь полностью закодированные данные в памяти.

Буфер вывода должен быть достаточно большим чтобы вместить все записываемые в него данные. Так как base64 кодирует 3 байта в 4 символа вам необходимо по крайней мере: len * 3 / 4 bytes.

in : двоичный ввод данных
len : максимальная длина данных in для декодирования
out : буфер вывода
state : Сохраняемое состояние между этапами, начиная с 0
save : Сохраняемое состояние между этапами, начиная с 0
Возвращает : Количество записанных байт вывода

Начиная с версии 2.12


g_base64_decode ()

guchar*     g_base64_decode                 (const gchar *text,
                                             gsize *out_len);

Декодирует последовательность текстовой кодировки Base-64 в двоичные данные

text : zero-завершённая строка с текстом в кодировке base64 для декодирования.
out_len : здесь записывается длина декодированных данных.
Возвращает : вновь распределённый буфер который содержит двоичные данные представленные text

Начиная с версии 2.12


Основные типы

Basic Types — Стандартные типы GLib, определяемые для простоты использования и переносимости.

Краткое описание


#include <glib.h>


typedef     gboolean;
typedef     gpointer;
typedef     gconstpointer;
typedef     gchar;
typedef     guchar;

typedef     gint;
typedef     guint;
typedef     gshort;
typedef     gushort;
typedef     glong;
typedef     gulong;

typedef     gint8;
typedef     guint8;
typedef     gint16;
typedef     guint16;
typedef     gint32;
typedef     guint32;

#define     G_HAVE_GINT64
typedef     gint64;
typedef     guint64;
#define     G_GINT64_CONSTANT               (val)
#define     G_GUINT64_CONSTANT              (val)

typedef     gfloat;
typedef     gdouble;

typedef     gsize;
typedef     gssize;

Описание

GLib определяет большое число основных используемых типов, которые можно разделить на 4 группы:

Детали

gboolean

typedef gint   gboolean;

Стандартный логический тип. Переменные этого типа содержат логическое значение TRUE или FALSE.


gpointer

typedef void* gpointer;

Указывает отсутствие типа. gpointer лучше выглядит и удобней в использовании чем void*.


gconstpointer

typedef const void *gconstpointer;

Указывает отсутствие типа константных данных. Указанные данные не должны изменяться.

Это обычно используется в прототипах функций для указания что данные не меняются функцией.


gchar

typedef char   gchar;

Соответствует стандартному типу char.


guchar

typedef unsigned char   guchar;

Соответствует стандартному типу unsigned char.


gint

typedef int    gint;

Соответствует стандартному типу int. Значение этого типа может быть в диапазоне от G_MININT до G_MAXINT.


guint

typedef unsigned int    guint;

Соответствует стандартному типу unsigned int. Значение этого типа может быть в диапазоне от 0 до G_MAXUINT.


gshort

typedef short  gshort;

Соответствует стандартному типу short. Значение этого типа может быть в диапазоне от G_MINSHORT до G_MAXSHORT.


gushort

typedef unsigned short  gushort;

Соответствует стандартному типу unsigned short. Значение этого типа может быть в диапазоне от 0 до G_MAXUSHORT.


glong

typedef long   glong;

Соответствует стандартному типу long. Значение этого типа может быть в диапазоне от G_MINLONG до G_MAXLONG.


gulong

typedef unsigned long   gulong;

Соответствует стандартному типу unsigned long. Значение этого типа может быть в диапазоне от 0 до G_MAXULONG.


gint8

typedef signed char gint8;

Целочисленное со знаком гарантировано равно 8 битам на всех платформах. Значение этого типа может быть в диапазоне от -128 до 127.


guint8

typedef unsigned char guint8;

Целочисленное без знака гарантировано равно 8 битам на всех платформах. Значение этого типа может быть в диапазоне от 0 до 255.


gint16

typedef signed short gint16;

Целочисленное со знаком гарантировано равно 16 битам на всех платформах. Значение этого типа может быть в диапазоне от -32,768 до 32,767.


guint16

typedef unsigned short guint16;

Целочисленное без знака гарантировано равно 16 битам на всех платформах. Значение этого типа может быть в диапазоне от 0 до 65,535.


gint32

typedef signed int gint32;

Целочисленное со знаком гарантировано равно 32 битам на всех платформах. Значение этого типа может быть в диапазоне от -2,147,483,648 до 2,147,483,647.


guint32

typedef unsigned int guint32;

Целочисленное без знака гарантировано равно 32 битам на всех платформах. Значение этого типа может быть в диапазоне от 0 до 4,294,967,295.


G_HAVE_GINT64

#define G_HAVE_GINT64 1          /* устаревшее, всегда верно */

Внимание

G_HAVE_GINT64 устарела и не должна использоваться во вновь создаваемом коде. GLib нуждается в поддержке 64-bit целых начиная с версии 2.0, поэтому G_HAVE_GINT64 всегда определено.

Этот макрос определяется если 64-битные целочисленные со знаком и без поддерживаются этой платформой.


gint64

G_GNUC_EXTENSION typedef signed long long gint64;

Целочисленное со знаком гарантировано равно 64 битам на всех платформах. Значение этого типа может быть в диапазоне от -9,223,372,036,854,775,808 до 9,223,372,036,854,775,807.


guint64

G_GNUC_EXTENSION typedef unsigned long long guint64;

Целочисленное без знака гарантировано равно 64 битам на всех платформах. Значение этого типа может быть в диапазоне от 0 до 18,446,744,073,709,551,615.


G_GINT64_CONSTANT()

#define G_GINT64_CONSTANT(val)	(G_GNUC_EXTENSION (val##LL))

Этот макрос используется для вставки буквальных 64-bit целочисленных в исходный код.

val : буквальное целочисленное значение, например 0x1d636b02300a7aa7U.

G_GUINT64_CONSTANT()

#define G_GUINT64_CONSTANT(val)	(G_GNUC_EXTENSION (val##ULL))

Этот макрос используется для вставки буквальных 64-bit целочисленных без знака в исходный код.

val : буквальное значение целочисленного, например 0x1d636b02300a7aa7U.

Начиная с версии 2.10


gfloat

typedef float   gfloat;

Соответствует стандартному типу float. Значение этого типа может быть в диапазоне от -G_MAXFLOAT to G_MAXFLOAT.


gdouble

typedef double  gdouble;

Соответствует стандартному типу double. Значение этого типа может быть в диапазоне от -G_MAXDOUBLE to G_MAXDOUBLE.


gsize

typedef unsigned int gsize;

Целочисленное 32-bit без знака, предназначенное представлять размер данных структур.


gssize

typedef signed int gssize;

Целочисленное 32-bit со знаком, предназначенное представлять размер данных структур.



Bookmark file parser

Bookmark file parser — Анализ файлов содержащих закладки

Краткое описание


#include <glib.h>


            GBookmarkFile;
#define     G_BOOKMARK_FILE_ERROR
enum        GBookmarkFileError;
GBookmarkFile* g_bookmark_file_new          (void);
void        g_bookmark_file_free            (GBookmarkFile *bookmark);
gboolean    g_bookmark_file_load_from_file  (GBookmarkFile *bookmark,
                                             const gchar *filename,
                                             GError **error);
gboolean    g_bookmark_file_load_from_data  (GBookmarkFile *bookmark,
                                             const gchar *data,
                                             gsize length,
                                             GError **error);
gboolean    g_bookmark_file_load_from_data_dirs
                                            (GBookmarkFile *bookmark,
                                             const gchar *file,
                                             gchar **full_path,
                                             GError **error);
gchar*      g_bookmark_file_to_data         (GBookmarkFile *bookmark,
                                             gsize *length,
                                             GError **error);
gboolean    g_bookmark_file_to_file         (GBookmarkFile *bookmark,
                                             const gchar *filename,
                                             GError **error);
gboolean    g_bookmark_file_has_item        (GBookmarkFile *bookmark,
                                             const gchar *uri);
gboolean    g_bookmark_file_has_group       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group,
                                             GError **error);
gboolean    g_bookmark_file_has_application (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             GError **error);
gint        g_bookmark_file_get_size        (GBookmarkFile *bookmark);
gchar**     g_bookmark_file_get_uris        (GBookmarkFile *bookmark,
                                             gsize *length);

gchar*      g_bookmark_file_get_title       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gchar*      g_bookmark_file_get_description (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gchar*      g_bookmark_file_get_mime_type   (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gboolean    g_bookmark_file_get_is_private  (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gboolean    g_bookmark_file_get_icon        (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gchar **href,
                                             gchar **mime_type,
                                             GError **error);
time_t      g_bookmark_file_get_added       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
time_t      g_bookmark_file_get_modified    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
time_t      g_bookmark_file_get_visited     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gchar**     g_bookmark_file_get_groups      (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gsize *length,
                                             GError **error);
gchar**     g_bookmark_file_get_applications
                                            (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gsize *length,
                                             GError **error);
gboolean    g_bookmark_file_get_app_info    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             gchar **exec,
                                             guint *count,
                                             time_t *stamp,
                                             GError **error);

void        g_bookmark_file_set_title       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *title);
void        g_bookmark_file_set_description (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *description);
void        g_bookmark_file_set_mime_type   (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *mime_type);
void        g_bookmark_file_set_is_private  (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gboolean is_private);
void        g_bookmark_file_set_icon        (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *href,
                                             const gchar *mime_type);
void        g_bookmark_file_set_added       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t added);
void        g_bookmark_file_set_groups      (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar **groups,
                                             gsize length);
void        g_bookmark_file_set_modified    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t modified);
void        g_bookmark_file_set_visited     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t visited);
gboolean    g_bookmark_file_set_app_info    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             const gchar *exec,
                                             gint count,
                                             time_t stamp,
                                             GError **error);
void        g_bookmark_file_add_group       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group);
void        g_bookmark_file_add_application (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             const gchar *exec);
gboolean    g_bookmark_file_remove_group    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group,
                                             GError **error);
gboolean    g_bookmark_file_remove_application
                                            (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             GError **error);
gboolean    g_bookmark_file_remove_item     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gboolean    g_bookmark_file_move_item       (GBookmarkFile *bookmark,
                                             const gchar *old_uri,
                                             const gchar *new_uri,
                                             GError **error);

Описание

GBookmarkFile позволяет вам анализировать, редактировать или создавать файлы содержащие закладки на URI, вместе с некоторыми meta-данными о ресурсе на который указывает URI, например его MIME тип, приложение которое зарегистрировало закладку и значок который должен использоваться для отображения закладки. Данные хранятся согласно Desktop Bookmark Specification.

Синтаксис файлов закладок детально описан в Desktop Bookmark Specification, здесь приведено краткое описание: файлы закладок используют подкласс спецификации XML Bookmark Exchange Language, состоят из XML в правильной кодировке UTF-8, под корневым элементом xbel; каждая закладка сохраняется в элементе bookmark, используя её URI: относительные пути не могут использоваться в файле закладок. Закладка может иметь заголовок и описание определённые пользователем, используемые вместо URI. Под элементом metadata, с его набором атрибутов owner в http://freedesktop.org, хранятся meta-данные о ресурсе указанном URI. Мета-данные состоят из MIME типа ресурса; приложения которое зарегистрировало закладку; группы к которой принадлежит закладка; флага видимости, используемом для установки закладки как "private" для приложений и групп которые имеют регистрацию; URI и MIME тип значка, для изображения закладки внутри GUI.


<?xml version="1.0"?>
<!DOCTYPE xbel PUBLIC 
  "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML"
  "http://www.python.org/topics/xml/dtds/xbel-1.0.dtd">
<xbel version="1.0"
      xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info"
      xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks">
  <bookmark href="file:///home/ebassi/bookmark-spec/bookmark-spec.xml">
    <title>Desktop Bookmarks Spec</title>
    <info>
      <metadata owner="http://freedesktop.org">
        <mime:mime-type>text/xml</mime:mime-type>
	<bookmark:applications>
          <bookmark:application name="GEdit" count="2" exec="gedit <link linkend="u"><literal>u</literal></link>" timestamp="1115726763"/>
          <bookmark:application name="GViM" count="7" exec="gvim <link linkend="f"><literal>f</literal></link>" timestamp="1115726812"/>
	</bookmark:applications>
	<bookmark:groups>
	  <bookmark:group>Editors</bookmark:group>
	</bookmark:groups>
      </metadata>
    </info>
  </bookmark>
</xbel>

Файл закладок может содержать больше одной закладки; к каждой закладке обращаются через её URI.

Важное замечание для файлов закладок в том, что когда вы добавляете закладку вы должны также добавить приложение которое зарегистрировало её, используя g_bookmark_file_add_application() или g_bookmark_file_set_app_info(). Если закладка не имеет приложений, то она будет сброшена при записи на диск, используя g_bookmark_file_to_data() или g_bookmark_file_to_file().

Анализатор GBookmarkFile добавлен в версии GLib 2.12.

Детали

GBookmarkFile

typedef struct _GBookmarkFile GBookmarkFile;

Структура GBookmarkFile содержит только закрытые данные к которым нет прямого доступа.


G_BOOKMARK_FILE_ERROR

#define G_BOOKMARK_FILE_ERROR	(g_bookmark_file_error_quark ())

Домен ошибки для анализатора файла закладок. Ошибки в этом домене из перечисления GBookmarkFileError. Смотрите GError для информации о доменах ошибки.


enum GBookmarkFileError

typedef enum
{
  G_BOOKMARK_FILE_ERROR_INVALID_URI,
  G_BOOKMARK_FILE_ERROR_INVALID_VALUE,
  G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED,
  G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND,
  G_BOOKMARK_FILE_ERROR_READ,
  G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING,
  G_BOOKMARK_FILE_ERROR_WRITE,
  G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND
} GBookmarkFileError;

Коды ошибок возвращаемые анализатором файла закладок.

G_BOOKMARK_FILE_ERROR_INVALID_URI URI был не правильно сформирован
G_BOOKMARK_FILE_ERROR_INVALID_VALUE запрашиваемое поле не найдено
G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED запрошенное приложение не зарегистрировано
G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND запрашиваемый URI не найден
G_BOOKMARK_FILE_ERROR_READ документ был не правильно сформирован
G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING анализируемый текст находится в неизвестной кодировке
G_BOOKMARK_FILE_ERROR_WRITE в процессе записи произошла ошибка
G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND запрашиваемый файл не найден

g_bookmark_file_new ()

GBookmarkFile* g_bookmark_file_new          (void);

Создаёт новый пустой объект GBookmarkFile.

Используйте g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data() или g_bookmark_file_load_from_data_dirs() для чтения существующего файла закладок.

Возвращает : пустой GBookmarkFile

Начиная с версии 2.12


g_bookmark_file_free ()

void        g_bookmark_file_free            (GBookmarkFile *bookmark);

Освобождает GBookmarkFile.

bookmark : GBookmarkFile

Начиная с версии 2.12


g_bookmark_file_load_from_file ()

gboolean    g_bookmark_file_load_from_file  (GBookmarkFile *bookmark,
                                             const gchar *filename,
                                             GError **error);

Загружает desktop bookmark file в пустую структуру GBookmarkFile. Если файл не загружен, то устанавливается error в GFileError или GBookmarkFileError.

bookmark : пустая структура GBookmarkFile
filename : путь к имени файла для загрузки, в кодировке имён файлов GLib
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если desktop bookmark file не загружен

Начиная с версии 2.12


g_bookmark_file_load_from_data ()

gboolean    g_bookmark_file_load_from_data  (GBookmarkFile *bookmark,
                                             const gchar *data,
                                             gsize length,
                                             GError **error);

Загружает файл закладок из памяти в пустую структуру GBookmarkFile. Если объект не создан, то устанавливается error в GBookmarkFileError.

bookmark : пустая структура GBookmarkFile
data : desktop закладки загруженные в память
length : размер data в байтах
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если desktop закладка не загружена.

Начиная с версии 2.12


g_bookmark_file_load_from_data_dirs ()

gboolean    g_bookmark_file_load_from_data_dirs
                                            (GBookmarkFile *bookmark,
                                             const gchar *file,
                                             gchar **full_path,
                                             GError **error);

Эта функция находит desktop bookmark file с именем file в пути который возвращает g_get_user_data_dir() и g_get_system_data_dirs(), загружает в файл bookmark и возвращает полный путь файла в full_path. Если файл не загружен, то error устанавливается либо в GFileError, либо в GBookmarkFileError.

bookmark : GBookmarkFile
file : относительный путь имени файла для открытия и анализа
full_path : расположение для возвращаемой строки содержащей полный путь файла, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если файл загружен, иначе FALSE

Начиная с версии 2.12


g_bookmark_file_to_data ()

gchar*      g_bookmark_file_to_data         (GBookmarkFile *bookmark,
                                             gsize *length,
                                             GError **error);

Эта функция выводит bookmark как строку.

bookmark : GBookmarkFile
length : расположение для длины возвращаемой строки, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённая строка содержащая GBookmarkFile

Начиная с версии 2.12


g_bookmark_file_to_file ()

gboolean    g_bookmark_file_to_file         (GBookmarkFile *bookmark,
                                             const gchar *filename,
                                             GError **error);

Эта функция выводит bookmark в файл. Пишущий процесс будет гарантировано атомарным при внутреннем использовании g_file_set_contents().

bookmark : GBookmarkFile
filename : путь к файлу для записи
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если файл полностью записан.

Начиная с версии 2.12


g_bookmark_file_has_item ()

gboolean    g_bookmark_file_has_item        (GBookmarkFile *bookmark,
                                             const gchar *uri);

Находит имеет ли desktop закладка элемент URI установленный в uri.

bookmark : GBookmarkFile
uri : правильный URI
Возвращает : TRUE если uri находится внутри bookmark, иначе FALSE

Начиная с версии 2.12


g_bookmark_file_has_group ()

gboolean    g_bookmark_file_has_group       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group,
                                             GError **error);

Проверяет относится ли group к списку групп к которым принадлежит закладка для uri.

В случае когда URI не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI
group : имя группы для поиска
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если group найдена.

Начиная с версии 2.12


g_bookmark_file_has_application ()

gboolean    g_bookmark_file_has_application (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             GError **error);

Проверяет имеет ли закладка для uri внутри bookmark регистрацию приложения name.

В случае когда URI не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI
name : имя приложения
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если приложение name найдено

Начиная с версии 2.12


g_bookmark_file_get_size ()

gint        g_bookmark_file_get_size        (GBookmarkFile *bookmark);

Определяет количество закладок в bookmark.

bookmark : GBookmarkFile
Возвращает : количество закладок

Начиная с версии 2.12


g_bookmark_file_get_uris ()

gchar**     g_bookmark_file_get_uris        (GBookmarkFile *bookmark,
                                             gsize *length);

Возвращает все URIs закладок в файле bookmark. Массив возвращаемых URIs будет NULL-завершённый, поэтому length может опционально быть NULL.

bookmark : GBookmarkFile
length : расположение для количества возвращаемых URIs, или NULL
Возвращает : вновь распределённый NULL-завершённый массив строк. Используйте g_strfreev() для его освобождения.

Начиная с версии 2.12


g_bookmark_file_get_title ()

gchar*      g_bookmark_file_get_title       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);

Возвращает заголовок закладки для uri.

Если uri это NULL, возвращает заголовок bookmark.

В случае когда URI не найден, возвращает NULL и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённая строка или NULL если определённый URI не найден.

Начиная с версии 2.12


g_bookmark_file_get_description ()

gchar*      g_bookmark_file_get_description (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);

Находит описание закладки для uri.

В случае когда URI не найден, возвращает NULL и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённая строка или NULL если определённый URI не найден.

Начиная с версии 2.12


g_bookmark_file_get_mime_type ()

gchar*      g_bookmark_file_get_mime_type   (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);

Находит MIME тип источника на который указывает uri.

В случае когда URI не найден, возвращает NULL и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. В случае когда MIME тип не найден, возвращает NULL и устанавливает error в G_BOOKMARK_FILE_ERROR_INVALID_VALUE.

bookmark : GBookmarkFile
uri : правильный URI
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённая строка или NULL если определённый URI не найден.

Начиная с версии 2.12


g_bookmark_file_get_is_private ()

gboolean    g_bookmark_file_get_is_private  (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);

Определяет установлен ли приватный флаг закладки для uri.

В случае когда URI не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. В случае когда приватный флаг не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_INVALID_VALUE.

bookmark : GBookmarkFile
uri : правильный URI
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если приватный флаг установлен, иначе FALSE.

Начиная с версии 2.12


g_bookmark_file_get_icon ()

gboolean    g_bookmark_file_get_icon        (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gchar **href,
                                             gchar **mime_type,
                                             GError **error);

Определяет значок закладки для uri.

В случае когда URI не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI
href : расположение для возвращаемого местонахождения значка или NULL
mime_type : расположение для возвращаемого MIME типа значка или NULL
error : расположение для возвращаемого GError или NULL
Возвращает : TRUE если значок закладки для URI найден. Вы должны освободить возвращаемые строки.

Начиная с версии 2.12


g_bookmark_file_get_added ()

time_t      g_bookmark_file_get_added       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);

Определяет время добавления закладки для uri в bookmark

В случае когда URI не найден, возвращает -1 и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI
error : расположение для возвращаемой GError, или NULL
Возвращает : время добавления закладки (timestamp)

Начиная с версии 2.12


g_bookmark_file_get_modified ()

time_t      g_bookmark_file_get_modified    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);

Определяет время последней модификации закладки для uri.

В случае когда URI не найден, возвращает -1 и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI
error : расположение для возвращаемой GError, или NULL
Возвращает : Время последней модификации закладки (timestamp)

Начиная с версии 2.12


g_bookmark_file_get_visited ()

time_t      g_bookmark_file_get_visited     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);

Определяет время последнего посещения закладки для uri was last visited.

В случае когда URI не найден, возвращает -1 и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI
error : расположение для возвращаемой GError, или NULL
Возвращает : Время последнего посещения (timestamp).

Начиная с версии 2.12


g_bookmark_file_get_groups ()

gchar**     g_bookmark_file_get_groups      (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gsize *length,
                                             GError **error);

Находит имена групп к которым принадлежит закладка для uri.

В случае когда URI не найден, возвращает NULL и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Возвращаемый массив является NULL-завершённым, поэтому length может опционально быть NULL.

bookmark : GBookmarkFile
uri : правильный URI
length : расположение длины возвращаемой строки, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённый NULL-завершённый массив имён групп. Используйте g_strfreev() для его освобождения.

Начиная с версии 2.12


g_bookmark_file_get_applications ()

gchar**     g_bookmark_file_get_applications
                                            (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gsize *length,
                                             GError **error);

Находит имена приложений которые зарегистрированы закладкой для uri.

В случае когда URI не найден, возвращает NULL и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
uri : правильный URI
length : расположение длины возвращаемого списка, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённый NULL-завершённый массив строк. Используйте g_strfreev() для его освобождения.

Начиная с версии 2.12


g_bookmark_file_get_app_info ()

gboolean    g_bookmark_file_get_app_info    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             gchar **exec,
                                             guint *count,
                                             time_t *stamp,
                                             GError **error);

Получает регистрационную информацию app_name закладки для uri. Смотрите g_bookmark_file_set_app_info() для получения информации о возвращаемых данных.

Строка возвращаемая в app_exec должна быть освобождена.

В случае когда URI не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. В случае когда нет приложения с именем app_name зарегистрированного закладкой для uri, возвращает FALSE и устанавливает ошибку в G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.

bookmark : GBookmarkFile
uri : правильный URI
name : имя приложения
exec : расположение для командной строки приложения, или NULL
count : расположение для возвращаемого количества регистраций, или NULL
stamp : расположение для возвращаемого времени последней регистрации, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE при успешном выполнении.

Начиная с версии 2.12


g_bookmark_file_set_title ()

void        g_bookmark_file_set_title       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *title);

Устанавливает title как заголовок закладки для uri внутри файла закладок bookmark.

Если uri это NULL, устанавливает заголовок bookmark.

Если закладка для uri не найдена, то она создаётся.

bookmark : GBookmarkFile
uri : правильный URI или NULL
title : строка в кодировке UTF-8

Начиная с версии 2.12


g_bookmark_file_set_description ()

void        g_bookmark_file_set_description (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *description);

Устанавливает description как описание закладки для uri.

Если uri это NULL, устанавливает описание bookmark.

Если закладка для uri не найдена, то она создаётся.

bookmark : GBookmarkFile
uri : правильный URI или NULL
description : строка

Начиная с версии 2.12


g_bookmark_file_set_mime_type ()

void        g_bookmark_file_set_mime_type   (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *mime_type);

Устанавливает mime_type как MIME тип закладки для uri.

Если закладка для uri не найдена, то она создаётся.

bookmark : GBookmarkFile
uri : правильный URI
mime_type : MIME тип

Начиная с версии 2.12


g_bookmark_file_set_is_private ()

void        g_bookmark_file_set_is_private  (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gboolean is_private);

Устанавливает приватный флаг закладки для uri.

Если закладка для uri не найдена, то она создаётся.

bookmark : GBookmarkFile
uri : правильный URI
is_private : TRUE если закладка должна быть помечена как закрытая

Начиная с версии 2.12


g_bookmark_file_set_icon ()

void        g_bookmark_file_set_icon        (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *href,
                                             const gchar *mime_type);

Устанавливает значок закладки для uri. Если href это NULL, сбрасывает установленный в текущий момент значок.

Если нет найденной закладки для uri, она создаётся.

bookmark : GBookmarkFile
uri : правильный URI
href : URI значка для закладки, или NULL
mime_type : MIME тип значка для закладки

Начиная с версии 2.12


g_bookmark_file_set_added ()

void        g_bookmark_file_set_added       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t added);

Устанавливает время добавления закладки для uri в bookmark.

Если нет найденной закладки для uri, то она создаётся.

bookmark : GBookmarkFile
uri : правильный URI
added : временная отметка или -1 для использования текущего времени

Начиная с версии 2.12


g_bookmark_file_set_groups ()

void        g_bookmark_file_set_groups      (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar **groups,
                                             gsize length);

Устанавливает список имён групп для элементов с uri. Каждое предварительно установленное имя группы списка удаляется.

Если uri не найден, то элементы для него создаются.

bookmark : GBookmarkFile
uri : URI элемент
groups : массив имён групп, или NULL для удаления всех групп
length : количество имен групп в groups

Начиная с версии 2.12


g_bookmark_file_set_modified ()

void        g_bookmark_file_set_modified    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t modified);

Устанавливает время последнего изменения закладки для uri.

Если закладка для uri не найдена, то она создаётся.

Время изменения закладки должно устанавливаться только когда meta-данные были фактически изменены. Все функции GBookmarkFile которые изменяют закладку также изменяют время модификации, за исключением g_bookmark_file_set_visited().

bookmark : GBookmarkFile
uri : правильный URI
modified : временная отметка или -1 для использования текущего времени

Начиная с версии 2.12


g_bookmark_file_set_visited ()

void        g_bookmark_file_set_visited     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t visited);

Устанавливает время последнего посещения закладки для uri.

Если закладка для uri не найдена, то она создаётся.

Время посещения должно устанавливаться только если закладка была задействована, любое использование командной строки найденное с помощью g_bookmark_file_get_app_info() или приложение по умолчанию для закладки MIME типа найденное с использованием g_bookmark_file_get_mime_type(). Изменение времени "посещения" не влияет на время "модификации".

bookmark : GBookmarkFile
uri : правильный URI
visited : временная метка или -1 для использования текущего времени

Начиная с версии 2.12


g_bookmark_file_set_app_info ()

gboolean    g_bookmark_file_set_app_info    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             const gchar *exec,
                                             gint count,
                                             time_t stamp,
                                             GError **error);

Устанавливает meta-данные приложения name в список приложений которые были зарегистрированы закладкой для uri внутри bookmark.

Вы должны редко использовать эту функцию; вместо неё используйте g_bookmark_file_add_application() и g_bookmark_file_remove_application().

name может быть любой строкой в кодировке UTF-8 используемой для идентификации приложения. exec может иметь один из двух модификаторов: "f", который будет расшифрован как локальное имя файла полученное из URI закладки; "u", который будет расшифрован как закладка URI. Расшифровка выполняется автоматически когда находится сохранённая командная строка используя функцию g_bookmark_file_get_app_info(). count это количество регистраций приложения закладкой; если < 0, текущее количество регистраций будет увеличено на одну, если 0, приложение с именем name будет удалено из списка зарегистрированных приложений. stamp Unix время последней регистрации; если -1, используется текущее время.

Если вы попытаетесь удалить приложение установив количество его регистраций в ноль, а закладка для uri не найдена, то вернётся FALSE и установится error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; точно так же, в случае когда нет приложения с именем name зарегистрированного закладкой для uri, то возвращается FALSE и устанавливается ошибка в G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Иначе, если закладка для uri не найдена, то она создаётся.

bookmark : GBookmarkFile
uri : правильный URI
name : имя приложения
exec : командная строка приложения
count : количество выполненных регистраций для приложения
stamp : время последней регистрации для приложения
error : расположение для возвращаемой GError или NULL
Возвращает : TRUE если meta-данные приложения полностью изменены.

Начиная с версии 2.12


g_bookmark_file_add_group ()

void        g_bookmark_file_add_group       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group);

Добавляет group в список групп к которым принадлежит закладка для uri.

Если закладка для uri не найдена, то она создаётся.

bookmark : GBookmarkFile
uri : правильный URI
group : имя добавляемой группы

Начиная с версии 2.12


g_bookmark_file_add_application ()

void        g_bookmark_file_add_application (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             const gchar *exec);

Добавляет приложение с именем name и exec в список приложений, которые зарегистрированы закладкой для uri, в bookmark.

Все закладки внутри GBookmarkFile должны иметь по меньшей мере одно зарегистрированное приложение. Каждое приложение должно иметь имя, командная строка полезна для запуска закладки, количество регистраций закладкой приложения и время последней регистрации приложения этой закладкой.

Если name это NULL, имя приложения будет тем что возвращает функция g_get_application(); если exec это NULL, командная строка будет состоять из имени программы которое возвращает g_get_prgname() и модификатора "u", который будет расшифрован как URI закладки.

Эта функция автоматически обновляет количество регистраций и timestamping в случае когда приложение с именем name уже зарегистрировано закладкой для uri внутри bookmark.

Если закладка для uri не найдена, то она создаётся.

bookmark : GBookmarkFile
uri : правильный URI
name : имя приложения зарегистрированное закладкой, или NULL
exec : командная строка используемая для активации закладки, или NULL

Начиная с версии 2.12


g_bookmark_file_remove_group ()

gboolean    g_bookmark_file_remove_group    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group,
                                             GError **error);

Удаляет group из списка групп к которым принадлежит закладка для uri.

В случае когда URI не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. В случае когда группа не определена, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_INVALID_VALUE.

bookmark : GBookmarkFile
uri : правильный URI
group : имя группы для удаления
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если group была полностью удалена.

Начиная с версии 2.12


g_bookmark_file_remove_application ()

gboolean    g_bookmark_file_remove_application
                                            (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             GError **error);

Удаляет регистрацию приложения с именем name из списка приложений которые зарегистрированы закладкой для uri внутри bookmark.

В случае когда URI не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. В случае когда приложение с именем app_name не зарегистрировано закладкой для uri, возвращает FALSE и устанавливает ошибку в G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.

bookmark : GBookmarkFile
uri : правильный URI
name : имя приложения
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если приложение полностью удалено.

Начиная с версии 2.12


g_bookmark_file_remove_item ()

gboolean    g_bookmark_file_remove_item     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);

Удаляет закладку для uri из файла закладок bookmark.

bookmark : GBookmarkFile
uri : правильный URI
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если закладка была полностью удалена.

Начиная с версии 2.12


g_bookmark_file_move_item ()

gboolean    g_bookmark_file_move_item       (GBookmarkFile *bookmark,
                                             const gchar *old_uri,
                                             const gchar *new_uri,
                                             GError **error);

Изменяет URI закладки из параметра old_uri на new_uri. Любые существующие закладки для new_uri будут переписаны. Если new_uri это NULL, тогда закладка удаляется.

В случае когда URI не найден, возвращает FALSE и устанавливает error в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

bookmark : GBookmarkFile
old_uri : правильный URI
new_uri : правильный URI, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если URI полностью изменён

Начиная с версии 2.12


Byte Arrays

Byte Arrays — Массив байт, который автоматически увеличивается при добавлении элементов.

Краткое описание


#include <glib.h>


            GByteArray;
GByteArray* g_byte_array_new                (void);
GByteArray* g_byte_array_sized_new          (guint reserved_size);
GByteArray* g_byte_array_append             (GByteArray *array,
                                             const guint8 *data,
                                             guint len);
GByteArray* g_byte_array_prepend            (GByteArray *array,
                                             const guint8 *data,
                                             guint len);
GByteArray* g_byte_array_remove_index       (GByteArray *array,
                                             guint index_);
GByteArray* g_byte_array_remove_index_fast  (GByteArray *array,
                                             guint index_);
GByteArray* g_byte_array_remove_range       (GByteArray *array,
                                             guint index_,
                                             guint length);
void        g_byte_array_sort               (GByteArray *array,
                                             GCompareFunc compare_func);
void        g_byte_array_sort_with_data     (GByteArray *array,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);
GByteArray* g_byte_array_set_size           (GByteArray *array,
                                             guint length);
guint8*     g_byte_array_free               (GByteArray *array,
                                             gboolean free_segment);

Описание

GByteArray основан на GArray, для обеспечения массива байт который автоматически увеличивается при добавлении элементов.

Для создания нового GByteArray используйте g_byte_array_new().

Для добавления элементов в GByteArray, используйте g_byte_array_append() и g_byte_array_prepend().

Для установки размера GByteArray, используйте g_byte_array_set_size().

Для освобождения GByteArray, используйте g_byte_array_free().

Пример 8. Using a GByteArray

  GByteArray *gbarray;
  gint i;

  gbarray = g_byte_array_new ();
  for (i = 0; i < 10000; i++)
    g_byte_array_append (gbarray, (guint8*) "abcd", 4);

  for (i = 0; i < 10000; i++)
    {
      g_assert (gbarray->data[4*i] == 'a');
      g_assert (gbarray->data[4*i+1] == 'b');
      g_assert (gbarray->data[4*i+2] == 'c');
      g_assert (gbarray->data[4*i+3] == 'd');
    }

  g_byte_array_free (gbarray, TRUE);

Детали

GByteArray

typedef struct {
  guint8 *data;
  guint	  len;
} GByteArray;

Структура GByteArray позволяет доступ к общедоступным полям GByteArray.

guint8 *data; указатель на элемент данных. Данные могут перемещаться когда добавляются элементы в GByteArray.
guint len; количество элементов в GByteArray.

g_byte_array_new ()

GByteArray* g_byte_array_new                (void);

Создаёт новый GByteArray.

Возвращает : новый GByteArray.

g_byte_array_sized_new ()

GByteArray* g_byte_array_sized_new          (guint reserved_size);

Создаёт новый GByteArray с reserved_size предварительно распределённых байт. Это позволяет избегать частых перераспределений, если вы добавляете много байт в массив. Однако помните что размер массива остаётся 0.

reserved_size : количество предварительно распределённых байт.
Возвращает : новый GByteArray.

g_byte_array_append ()

GByteArray* g_byte_array_append             (GByteArray *array,
                                             const guint8 *data,
                                             guint len);

Добавляет полученные байты в конец GByteArray. Массив автоматически увеличивает размер, если необходимо.

array : GByteArray.
data : байты данных для добавления.
len : количество добавляемых байт.
Возвращает : GByteArray.

g_byte_array_prepend ()

GByteArray* g_byte_array_prepend            (GByteArray *array,
                                             const guint8 *data,
                                             guint len);

Добавляет полученные данные в начало GByteArray. Массив будет увеличиваться автоматически, если необходимо.

array : GByteArray.
data : байты данных для добавления.
len : количество добавляемых байт.
Возвращает : GByteArray.

g_byte_array_remove_index ()

GByteArray* g_byte_array_remove_index       (GByteArray *array,
                                             guint index_);

Удаляет байт с полученным номером из GByteArray. Следующие байты перемещаются вниз на одну позицию.

array : GByteArray.
index_ : номер байта для удаления.
Возвращает : GByteArray.

g_byte_array_remove_index_fast ()

GByteArray* g_byte_array_remove_index_fast  (GByteArray *array,
                                             guint index_);

Удаляет байт в полученной позиции GByteArray. Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок GByteArray. Но она быстрее чем g_byte_array_remove_index().

array : GByteArray.
index_ : номер байта для удаления.
Возвращает : GByteArray.

g_byte_array_remove_range ()

GByteArray* g_byte_array_remove_range       (GByteArray *array,
                                             guint index_,
                                             guint length);

Удаляет полученное количество байт на начиная с указанной позиции GByteArray. Следующие элементы перемещаются закрывая пустоту.

array : GByteArray.
index_ : номер первого байта для удаления.
length : количество байт для удаления.
Возвращает : GByteArray.

Начиная с версии 2.4


g_byte_array_sort ()

void        g_byte_array_sort               (GByteArray *array,
                                             GCompareFunc compare_func);

Сортирует массив байт, используя compare_func которая должна быть в стиле функции сравнения qsort() (возвращать отрицательное значение если первый arg меньше чем второй arg, ноль если они равны, положительное значение если первый arg больше чем второй arg).

Если два сравниваемых массива элементов равны, их порядок в сортируемом массиве не определён.

array : GByteArray.
compare_func : функция сравнения.

g_byte_array_sort_with_data ()

void        g_byte_array_sort_with_data     (GByteArray *array,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

Похожа на g_byte_array_sort(), но функция сравнения принимает дополнительный аргумент пользовательских данных.

array : GByteArray.
compare_func : функция сравнения.
user_data : данные помещаемые в compare_func.

g_byte_array_set_size ()

GByteArray* g_byte_array_set_size           (GByteArray *array,
                                             guint length);

Устанавливает размер GByteArray, расширяя если необходимо.

array : GByteArray.
length : новый размер GByteArray.
Возвращает : GByteArray.

g_byte_array_free ()

guint8*     g_byte_array_free               (GByteArray *array,
                                             gboolean free_segment);

Освобождает память распределённую для GByteArray. Если free_segment это TRUE, она освобождает фактические байты данных.

array : GByteArray.
free_segment : если TRUE фактические байты данных так же освобождаются.
Возвращает : элемент данных если free_segment это FALSE, иначе NULL

Макроопределения последовательности байт

Byte Order Macros — портируемый способ преобразования между разными последовательностями байт.

Краткое описание


#include <glib.h>


#define     G_BYTE_ORDER
#define     G_LITTLE_ENDIAN
#define     G_BIG_ENDIAN
#define     G_PDP_ENDIAN

#define     g_htonl                         (val)
#define     g_htons                         (val)
#define     g_ntohl                         (val)
#define     g_ntohs                         (val)

#define     GINT_FROM_BE                    (val)
#define     GINT_FROM_LE                    (val)
#define     GINT_TO_BE                      (val)
#define     GINT_TO_LE                      (val)

#define     GUINT_FROM_BE                   (val)
#define     GUINT_FROM_LE                   (val)
#define     GUINT_TO_BE                     (val)
#define     GUINT_TO_LE                     (val)

#define     GLONG_FROM_BE                   (val)
#define     GLONG_FROM_LE                   (val)
#define     GLONG_TO_BE                     (val)
#define     GLONG_TO_LE                     (val)

#define     GULONG_FROM_BE                  (val)
#define     GULONG_FROM_LE                  (val)
#define     GULONG_TO_BE                    (val)
#define     GULONG_TO_LE                    (val)

#define     GINT16_FROM_BE                  (val)
#define     GINT16_FROM_LE                  (val)
#define     GINT16_TO_BE                    (val)
#define     GINT16_TO_LE                    (val)

#define     GUINT16_FROM_BE                 (val)
#define     GUINT16_FROM_LE                 (val)
#define     GUINT16_TO_BE                   (val)
#define     GUINT16_TO_LE                   (val)

#define     GINT32_FROM_BE                  (val)
#define     GINT32_FROM_LE                  (val)
#define     GINT32_TO_BE                    (val)
#define     GINT32_TO_LE                    (val)

#define     GUINT32_FROM_BE                 (val)
#define     GUINT32_FROM_LE                 (val)
#define     GUINT32_TO_BE                   (val)
#define     GUINT32_TO_LE                   (val)

#define     GINT64_FROM_BE                  (val)
#define     GINT64_FROM_LE                  (val)
#define     GINT64_TO_BE                    (val)
#define     GINT64_TO_LE                    (val)

#define     GUINT64_FROM_BE                 (val)
#define     GUINT64_FROM_LE                 (val)
#define     GUINT64_TO_BE                   (val)
#define     GUINT64_TO_LE                   (val)

#define     GUINT16_SWAP_BE_PDP             (val)
#define     GUINT16_SWAP_LE_BE              (val)
#define     GUINT16_SWAP_LE_PDP             (val)

#define     GUINT32_SWAP_BE_PDP             (val)
#define     GUINT32_SWAP_LE_BE              (val)
#define     GUINT32_SWAP_LE_PDP             (val)

#define     GUINT64_SWAP_LE_BE              (val)

Описание

Эти макросы обеспечивают переносимый способ определения машинной последовательности байт и преобразование значений между различными последовательностями байт.

Последовательность байт это порядок в котором байты сохраняются для создания больших типов данных таких как значения gint и glong. Машинная последовательность байт это порядок байт используемый на текущей машине.

Некоторые процессоры сохраняют самые важные байты (то есть байты которые содержат большую часть значения) первыми. Они известны как big-endian процессоры.

Другие процессоры (особенно семейство x86) сохраняют самые важные байты последними. Они известны как little-endian процессоры.

В завершение, для полного усложнения, некоторые процессоры сохраняют байты в довольно любопытном порядке известном как PDP-endian. Для 4-байтного слова, 3-ий самый важный байт сохраняется первым, затем 4-ый, затем 1-ый и в конце 2-ой.

Очевидно есть проблемы когда эти разные процессоры взаимодействуют между собой, например через сеть или при использовании бинарных форматов файлов. Вот тут необходимы данные макроопределения. Они обычно используются для конвертации значений в последовательность байт которая подходит для использования при взаимодействии разных процессоров. Интернет использует известный как 'network byte order' (сетевая последовательность байт) стандарт последовательности байт (который фактически является big-endian последовательностью байт).

Помните что макросы преобразования последовательности байт могут вычислять аргументы несколько раз, поэтому вы не должны использовать их с аргументами имеющими побочные эффекты.

Детали

G_BYTE_ORDER

#define G_BYTE_ORDER G_LITTLE_ENDIAN

Машинная последовательность байт. Это может быть или G_LITTLE_ENDIAN или G_BIG_ENDIAN (поддержка для G_PDP_ENDIAN может быть добавлена в будущем.)


G_LITTLE_ENDIAN

#define G_LITTLE_ENDIAN 1234

Определяет одну из возможных последовательностей байт. Смотрите G_BYTE_ORDER.


G_BIG_ENDIAN

#define G_BIG_ENDIAN    4321

Определяет один из возможных типов последовательности байт. Смотрите G_BYTE_ORDER.


G_PDP_ENDIAN

#define G_PDP_ENDIAN    3412		/* неиспользуется, нуждается в определённой проверке PDP */	

Определяет один из возможных типов последовательности байт (в настоящее время не используется). Смотрите G_BYTE_ORDER.


g_htonl()

#define     g_htonl(val)

Конвертирует 32-битное целочисленное значение из машинной в сетевую последовательность байт.

val : 32-битное целочисленное значение в машинной последовательности байт.
Возвращает : val конвертированное в сетевую последовательность байт.

g_htons()

#define     g_htons(val)

Конвертирует 16-битное целочисленное значение из машинной в сетевую последовательность байт.

val : 16-битное целочисленное значение в машинной последовательности байт.
Возвращает : val конвертированное в сетевую последовательность байт.

g_ntohl()

#define     g_ntohl(val)

Конвертирует 32-битное целочисленное значение из сетевой в машинную последовательность байт.

val : 32-битное целочисленное значение в сетевой последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

g_ntohs()

#define     g_ntohs(val)

Конвертирует 16-битное целочисленное значение из сетевой в машинную последовательность байт.

val : 16-битное целочисленное значение в сетевой последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT_FROM_BE()

#define GINT_FROM_BE(val)	(GINT_TO_BE (val))

Конвертирует gint значение из big-endian в машинную последовательность байт.

val : gint значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT_FROM_LE()

#define GINT_FROM_LE(val)	(GINT_TO_LE (val))

Конвертирует gint значение из little-endian в машинную последовательность байт.

val : gint значение в little-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT_TO_BE()

#define GINT_TO_BE(val)		((gint) GINT32_TO_BE (val))

Конвертирует gint значение из машинной последовательности байт в big-endian.

val : gint значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian последовательностью байт.

GINT_TO_LE()

#define GINT_TO_LE(val)		((gint) GINT32_TO_LE (val))

Конвертирует gint значение из машинной последовательности байт в little-endian.

val : gint значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian последовательность байт.

GUINT_FROM_BE()

#define GUINT_FROM_BE(val)	(GUINT_TO_BE (val))

Конвертирует guint значение из big-endian в машинную последовательность байт.

val : guint значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GUINT_FROM_LE()

#define GUINT_FROM_LE(val)	(GUINT_TO_LE (val))

Конвертирует guint значение из little-endian в машинную последовательность байт.

val : guint значение в little-endian последовательностью байт.
Возвращает : val конвертированное в машинную последовательность байт.

GUINT_TO_BE()

#define GUINT_TO_BE(val)	((guint) GUINT32_TO_BE (val))

Конвертирует guint значение из машинной последовательности байт в big-endian.

val : guint значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian последовательность байт.

GUINT_TO_LE()

#define GUINT_TO_LE(val)	((guint) GUINT32_TO_LE (val))

Конвертирует guint значение из машинной последовательности байт в little-endian.

val : guint значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian последовательность байт.

GLONG_FROM_BE()

#define GLONG_FROM_BE(val)	(GLONG_TO_BE (val))

Конвертирует glong значение из big-endian to the host последовательность байт.

val : glong значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GLONG_FROM_LE()

#define GLONG_FROM_LE(val)	(GLONG_TO_LE (val))

Конвертирует glong значение из little-endian в машинную последовательность байт.

val : glong значение в little-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GLONG_TO_BE()

#define GLONG_TO_BE(val)	((glong) GINT32_TO_BE (val))

Конвертирует glong значение из машинной последовательности байт в big-endian.

val : glong значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian последовательность байт.

GLONG_TO_LE()

#define GLONG_TO_LE(val)	((glong) GINT32_TO_LE (val))

Конвертирует glong значение из машинной последовательности байт в little-endian.

val : glong значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian.

GULONG_FROM_BE()

#define GULONG_FROM_BE(val)	(GULONG_TO_BE (val))

Конвертирует gulong значение из big-endian в машинную последовательность байт.

val : gulong значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GULONG_FROM_LE()

#define GULONG_FROM_LE(val)	(GULONG_TO_LE (val))

Конвертирует gulong значение из little-endian в машинную последовательность байт.

val : gulong значение в little-endian последовательность байт.
Возвращает : val конвертированное в машинную последовательность байт.

GULONG_TO_BE()

#define GULONG_TO_BE(val)	((gulong) GUINT32_TO_BE (val))

Конвертирует gulong значение из машинной последовательности байт в big-endian.

val : gulong значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian.

GULONG_TO_LE()

#define GULONG_TO_LE(val)	((gulong) GUINT32_TO_LE (val))

Конвертирует gulong значение из машинной последовательности байт в little-endian.

val : gulong значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian.

GINT16_FROM_BE()

#define GINT16_FROM_BE(val)	(GINT16_TO_BE (val))

Конвертирует gint16 значение из big-endian в машинную последовательность байт.

val : gint16 значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT16_FROM_LE()

#define GINT16_FROM_LE(val)	(GINT16_TO_LE (val))

Конвертирует gint16 значение из little-endian в машинную последовательность байт.

val : gint16 значение в little-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT16_TO_BE()

#define GINT16_TO_BE(val)	((gint16) GUINT16_SWAP_LE_BE (val))

Конвертирует gint16 значение из машинной последовательности байт в big-endian.

val : gint16 значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian.

GINT16_TO_LE()

#define GINT16_TO_LE(val)	((gint16) (val))

Конвертирует gint16 значение из машинной последовательности байт в little-endian.

val : gint16 значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian.

GUINT16_FROM_BE()

#define GUINT16_FROM_BE(val)	(GUINT16_TO_BE (val))

Конвертирует guint16 значение из big-endian в машинную последовательность байт.

val : guint16 значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GUINT16_FROM_LE()

#define GUINT16_FROM_LE(val)	(GUINT16_TO_LE (val))

Конвертирует guint16 значение из little-endian в машинную последовательность байт.

val : guint16 значение в little-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GUINT16_TO_BE()

#define GUINT16_TO_BE(val)	(GUINT16_SWAP_LE_BE (val))

Конвертирует guint16 значение из машинной последовательности байт в big-endian.

val : guint16 значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian.

GUINT16_TO_LE()

#define GUINT16_TO_LE(val)	((guint16) (val))

Конвертирует guint16 значение из машинной последовательности байт в little-endian.

val : guint16 значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian.

GINT32_FROM_BE()

#define GINT32_FROM_BE(val)	(GINT32_TO_BE (val))

Конвертирует gint32 значение из big-endian в машинную последовательность байт.

val : gint32 значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT32_FROM_LE()

#define GINT32_FROM_LE(val)	(GINT32_TO_LE (val))

Конвертирует gint32 значение из little-endian в машинную последовательность байт.

val : gint32 значение в little-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT32_TO_BE()

#define GINT32_TO_BE(val)	((gint32) GUINT32_SWAP_LE_BE (val))

Конвертирует gint32 значение из машинной последовательности байт в big-endian.

val : gint32 значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian.

GINT32_TO_LE()

#define GINT32_TO_LE(val)	((gint32) (val))

Конвертирует gint32 значение из машинной последовательности байт в little-endian.

val : gint32 значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian.

GUINT32_FROM_BE()

#define GUINT32_FROM_BE(val)	(GUINT32_TO_BE (val))

Конвертирует guint32 значение из big-endian в машинную последовательность байт.

val : guint32 значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GUINT32_FROM_LE()

#define GUINT32_FROM_LE(val)	(GUINT32_TO_LE (val))

Конвертирует guint32 значение из little-endian в машинную последовательность байт.

val : guint32 значение в little-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GUINT32_TO_BE()

#define GUINT32_TO_BE(val)	(GUINT32_SWAP_LE_BE (val))

Конвертирует guint32 значение из машинной последовательности байт в big-endian.

val : guint32 значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian.

GUINT32_TO_LE()

#define GUINT32_TO_LE(val)	((guint32) (val))

Конвертирует guint32 значение из машинной последовательности байт в little-endian.

val : guint32 значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian.

GINT64_FROM_BE()

#define GINT64_FROM_BE(val)	(GINT64_TO_BE (val))

Конвертирует gint64 значение из big-endian в машинную последовательность байт.

val : gint64 значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT64_FROM_LE()

#define GINT64_FROM_LE(val)	(GINT64_TO_LE (val))

Конвертирует gint64 значение из little-endian в машинную последовательность байт.

val : gint64 значение в little-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GINT64_TO_BE()

#define GINT64_TO_BE(val)	((gint64) GUINT64_SWAP_LE_BE (val))

Конвертирует gint64 значение из машинной последовательности байт в big-endian.

val : gint64 значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian.

GINT64_TO_LE()

#define GINT64_TO_LE(val)	((gint64) (val))

Конвертирует gint64 значение из машинной последовательности байт в little-endian.

val : gint64 значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian.

GUINT64_FROM_BE()

#define GUINT64_FROM_BE(val)	(GUINT64_TO_BE (val))

Конвертирует guint64 значение из big-endian в машинную последовательность байт.

val : guint64 значение в big-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GUINT64_FROM_LE()

#define GUINT64_FROM_LE(val)	(GUINT64_TO_LE (val))

Конвертирует guint64 значение из little-endian в машинную последовательность байт.

val : guint64 значение в little-endian последовательности байт.
Возвращает : val конвертированное в машинную последовательность байт.

GUINT64_TO_BE()

#define GUINT64_TO_BE(val)	(GUINT64_SWAP_LE_BE (val))

Конвертирует guint64 значение из машинной последовательности байт в big-endian.

val : guint64 значение в машинной последовательности байт.
Возвращает : val конвертированное в big-endian.

GUINT64_TO_LE()

#define GUINT64_TO_LE(val)	((guint64) (val))

Конвертирует guint64 значение из машинной последовательности байт в little-endian.

val : guint64 значение в машинной последовательности байт.
Возвращает : val конвертированное в little-endian.

GUINT16_SWAP_BE_PDP()

#define GUINT16_SWAP_BE_PDP(val)	(GUINT16_SWAP_LE_BE (val))

Конвертирует guint16 значение между big-endian и pdp-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.

val : guint16 значение в big-endian или pdp-endian последовательности байт.
Возвращает : val конвертированное в противоположную последовательность байт.

GUINT16_SWAP_LE_BE()

#define     GUINT16_SWAP_LE_BE(val)

Конвертирует guint16 значение между little-endian и big-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.

val : guint16 значение в little-endian или big-endian последовательности байт.
Возвращает : val конвертированное в противоположную последовательность байт.

GUINT16_SWAP_LE_PDP()

#define GUINT16_SWAP_LE_PDP(val)	((guint16) (val))

Конвертирует guint16 значение между little-endian и pdp-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.

val : guint16 значение в little-endian или pdp-endian последовательности байт.
Возвращает : val конвертированное в противоположную последовательность байт.

GUINT32_SWAP_BE_PDP()

#define     GUINT32_SWAP_BE_PDP(val)

Конвертирует guint32 значение между big-endian и pdp-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.

val : guint32 значение в big-endian или pdp-endian последовательности байт.
Возвращает : val конвертированное в противоположную последовательность байт.

GUINT32_SWAP_LE_BE()

#define     GUINT32_SWAP_LE_BE(val)

Конвертирует guint32 значение между little-endian и big-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.

val : guint32 значение в little-endian или big-endian последовательности байт.
Возвращает : val конвертированное в противоположную последовательность байт.

GUINT32_SWAP_LE_PDP()

#define     GUINT32_SWAP_LE_PDP(val)

Конвертирует guint32 значение между little-endian и pdp-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.

val : guint32 значение в little-endian или pdp-endian последовательности байт.
Возвращает : val конвертированное в противоположную последовательность байт.

GUINT64_SWAP_LE_BE()

#define     GUINT64_SWAP_LE_BE(val)

Конвертирует guint64 значение между little-endian и big-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.

val : guint64 значение в little-endian или big-endian последовательности байт.
Возвращает : val конвертированное в противоположную последовательность байт.

Caches

Caches — Кеши позволяют объединять комплекс структур данных для сохранения ресурсов.

Краткое описание


#include <glib.h>


            GCache;
GCache*     g_cache_new                     (GCacheNewFunc value_new_func,
                                             GCacheDestroyFunc value_destroy_func,
                                             GCacheDupFunc key_dup_func,
                                             GCacheDestroyFunc key_destroy_func,
                                             GHashFunc hash_key_func,
                                             GHashFunc hash_value_func,
                                             GEqualFunc key_equal_func);
gpointer    g_cache_insert                  (GCache *cache,
                                             gpointer key);
void        g_cache_remove                  (GCache *cache,
                                             gconstpointer value);
void        g_cache_destroy                 (GCache *cache);

void        g_cache_key_foreach             (GCache *cache,
                                             GHFunc func,
                                             gpointer user_data);
void        g_cache_value_foreach           (GCache *cache,
                                             GHFunc func,
                                             gpointer user_data);

void        (*GCacheDestroyFunc)            (gpointer value);
gpointer    (*GCacheDupFunc)                (gpointer value);
gpointer    (*GCacheNewFunc)                (gpointer key);

Описание

GCache позволяет объединить комплекс структур данных, в порядке сохранения системных ресурсов.

GTK+ использует кеши для GtkStyles и GdkGCs. Они потребляют много ресурсов, поэтому GCache используется для отслеживания ситуации когда GtkStyle или GdkGC запрашивают уже существующие свойства. Если это выполнено, то используются существующие объекты вместо создания новых.

GCache использует ключи и значения. GCache ключ описывает свойство специального ресурса. GCache значение - это фактический ресурс.

Детали

GCache

typedef struct _GCache GCache;

Структура GCache является непрозрачной структурой данных содержащей информацию о GCache. Доступ к ней должен осуществляться только через следующие функции.


g_cache_new ()

GCache*     g_cache_new                     (GCacheNewFunc value_new_func,
                                             GCacheDestroyFunc value_destroy_func,
                                             GCacheDupFunc key_dup_func,
                                             GCacheDestroyFunc key_destroy_func,
                                             GHashFunc hash_key_func,
                                             GHashFunc hash_value_func,
                                             GEqualFunc key_equal_func);

Создаёт новую GCache.

value_new_func : функция для создания нового объекта данного ключа. Она вызывается функцией g_cache_insert() если объект с данным ключом ещё не существует.
value_destroy_func : функция для уничтожения объекта. Она вызывается с помощью g_cache_remove() когда объект больше не нужен (то есть количество его ссылок сброшено в 0).
key_dup_func : функция для копирования ключа. Она вызывается функцией g_cache_insert() если ключ ещё не существует в GCache.
key_destroy_func : функция для уничтожения ключа. Она вызывается функцией g_cache_remove() когда объект больше не нужен (то есть количество его ссылок сброшено в 0).
hash_key_func : функция создаёт хеш значение из ключа.
hash_value_func : функция создаёт хеш значение из значения.
key_equal_func : функция для сравнения двух ключей. Она должна вернуть TRUE если два ключа равны.
Возвращает : новая GCache.

g_cache_insert ()

gpointer    g_cache_insert                  (GCache *cache,
                                             gpointer key);

Определяет значение соответствующее полученному ключу, создаёт если необходимо. Она сначала проверяет существует ли значение в GCache, используя key_equal_func функцию помещённую в g_cache_new(). Если существует, возвращает это значение и увеличивает количество ссылок на одну. Если значение не существует в текущий момент, оно создаётся вызовом value_new_func. Ключ дублируется вызовом key_dup_func и дубликат ключа и значения вставляется в GCache.

cache : GCache.
key : ключ описывающий GCache объект.
Возвращает : указатель на GCache значение.

g_cache_remove ()

void        g_cache_remove                  (GCache *cache,
                                             gconstpointer value);

Уменьшает количество ссылок на указанное значение. Если сброшено в 0, то значение и соответствующий ключ уничтожаются, используя value_destroy_func и key_destroy_func помещённые в g_cache_new().

cache : GCache.
value : значение для удаления.

g_cache_destroy ()

void        g_cache_destroy                 (GCache *cache);

Освобождает память распределённую для GCache.

Помните что она не уничтожает ключи и значения которые содержит GCache.

cache : GCache.

g_cache_key_foreach ()

void        g_cache_key_foreach             (GCache *cache,
                                             GHFunc func,
                                             gpointer user_data);

Вызывает указанную функцию для каждого ключа в GCache.

Примечание

func принимает три параметра, значение и ключ кеш элемента и user_data. Порядок значение и ключ отличается от порядка в котором g_hash_table_foreach() проходит пары ключ/значение в callback-функцию!

cache : GCache.
func : функция вызываемая с каждым элементом GCache key.
user_data : пользовательские данные помещаемые в функцию.

g_cache_value_foreach ()

void        g_cache_value_foreach           (GCache *cache,
                                             GHFunc func,
                                             gpointer user_data);

Внимание

g_cache_value_foreach устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде. Благоразумней поместить указатели для внутренних структур данных в func; используя g_cache_key_foreach()

Вызывает указанную функцию для каждого значения в GCache.

cache : GCache.
func : функция вызываемая с каждым значением GCache.
user_data : пользовательские данные помещаемые в функцию.

GCacheDestroyFunc ()

void        (*GCacheDestroyFunc)            (gpointer value);

Определяет тип value_destroy_func и key_destroy_func функций помещаемых в g_cache_new(). В функции помещаются указатели на GCache ключ или GCache значение и она должна освободить любую память и другие ресурсы связанные с ними.

value : GCache значение для уничтожения.

GCacheDupFunc ()

gpointer    (*GCacheDupFunc)                (gpointer value);

Определяет тип key_dup_func функции помещаемой в g_cache_new(). В функцию помещается ключ (не значение, поскольку подразумевается образец) и она должна вернуть копию ключа.

value : GCache ключ для уничтожения (не GCache значение).
Возвращает : копия GCache ключа.

GCacheNewFunc ()

gpointer    (*GCacheNewFunc)                (gpointer key);

Определяет тип value_new_func функции помещаемой в g_cache_new(). Она берёт GCache ключ и должна создать значение соответствующее ключу.

key : GCache key.
Возвращает : новое GCache значение соответствующее ключу.

Character Set Conversion

Character Set Conversion — конвертирование строк между разными наборами символов используя iconv().

Краткое описание


#include <glib.h>


gchar*      g_convert                       (const gchar *str,
                                             gssize len,
                                             const gchar *to_codeset,
                                             const gchar *from_codeset,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);
gchar*      g_convert_with_fallback         (const gchar *str,
                                             gssize len,
                                             const gchar *to_codeset,
                                             const gchar *from_codeset,
                                             gchar *fallback,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);
            GIConv;
gchar*      g_convert_with_iconv            (const gchar *str,
                                             gssize len,
                                             GIConv converter,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);
#define     G_CONVERT_ERROR
GIConv      g_iconv_open                    (const gchar *to_codeset,
                                             const gchar *from_codeset);
size_t      g_iconv                         (GIConv converter,
                                             gchar **inbuf,
                                             gsize *inbytes_left,
                                             gchar **outbuf,
                                             gsize *outbytes_left);
gint        g_iconv_close                   (GIConv converter);
gchar*      g_locale_to_utf8                (const gchar *opsysstring,
                                             gssize len,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);
gchar*      g_filename_to_utf8              (const gchar *opsysstring,
                                             gssize len,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);
gchar*      g_filename_from_utf8            (const gchar *utf8string,
                                             gssize len,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);
gchar*      g_filename_from_uri             (const gchar *uri,
                                             gchar **hostname,
                                             GError **error);
gchar*      g_filename_to_uri               (const gchar *filename,
                                             const gchar *hostname,
                                             GError **error);
gboolean    g_get_filename_charsets         (G_CONST_RETURN gchar ***charsets);
gchar*      g_filename_display_name         (const gchar *filename);
gchar*      g_filename_display_basename     (const gchar *filename);
gchar**     g_uri_list_extract_uris         (const gchar *uri_list);
gchar*      g_locale_from_utf8              (const gchar *utf8string,
                                             gssize len,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);
enum        GConvertError;

gboolean    g_get_charset                   (G_CONST_RETURN char **charset);

Описание

Кодировка имени файла

Исторически, Unix не имел определённой кодировки для имен файла: имя файла допустимо пока в нём нет разделителей пути ("/"). Однако, отображение имён файла может требовать преобразования: из набора символа в котором оно создавалось, в набор символов с которым оперирует приложение. Рассмотрим Испанское имя файла "Presentación.sxi". Если приложение которое создавало его использует ISO-8859-1 для его кодировки, то фактическое имя файла на диске должно выглядеть так:

Character:  P  r  e  s  e  n  t  a  c  i  ó  n  .  s  x  i
Hex code:   50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
      

Однако, если приложение использует UTF-8, фактическое имя файла на диске будет выглядеть так:

Character:  P  r  e  s  e  n  t  a  c  i  ó     n  .  s  x  i
Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
      

Glib использует UTF-8 для строк, и GUI toolkits такой как GTK+ который использует Glib делает тоже самое. Если вы получили имя файла из файловой системы, например, из readdir(3) или из g_dir_read_name(), и желаете отобразить имя файла пользователю, вы будете должны конвертировать его в UTF-8. Противоположный случай когда пользователь печатает имя файла и хочет его сохранить: инструментарий (toolkit) выдаст вам что строка в кодировке UTF-8, и вам необходимо конвертировать её в набор символов используемый файловой системой перед тем как вы сможете создать файл с помощью open(2) или fopen(3).

По умолчанию, Glib предполагает что имена файлов на диске находятся в кодировке UTF-8. Это правильное предположение для файловых систем которые были созданы относительно недавно: большинство приложений используют UTF-8 кодировку для их строк, а так же для имён файлов которые они создают. Однако, более старые файловые системы могут по прежнему создавать имена файлов в "старых" кодировках, таких как ISO-8859-1. В этом случае, по причинам совместимости, вы можете инструктировать Glib использовать эту специальную кодировки для имен файлов а не UTF-8. Вы можете выполнить это определив кодировку для имён файлов в переменной окружения G_FILENAME_ENCODING. Например, если ваша инсталяция использует ISO-8859-1 для имен файлов, вы можете поместить следующее в свой ~/.profile:

export G_FILENAME_ENCODING=ISO-8859-1
      

Glib обеспечивает функции g_filename_to_utf8() и g_filename_from_utf8() для выполнения необходимых преобразований. Эти функции конвертируют имена файлов из кодировки определённой в G_FILENAME_ENCODING в кодировку UTF-8 и наоборот. Схема 1, “Конвертация между кодировками имён файлов” иллюстрирует как эти функции используются для конвертации между UTF-8 и кодировкой имён файлов в файловой системе.

Схема 1. Конвертация между кодировками имён файлов

Conversion between File Name Encodings

Контрольный список для записывающего приложения

Эта секция суммирует детали описанные выше. Вы можете использовать это как контрольный список необходимых вещей выполняемых для того чтобы удостоверится что ваше приложение выполняет перекодировку имён файлов корректно.

  1. Если вы получаете имя файла из файловой системы с помощью функций таких как readdir(3) или gtk_file_chooser_get_filename(), вы не должны выполнять никаких конвертаций для помещения этого имени файла в функции такие как open(2), rename(2), или fopen(3) — изначальные имена файлов которые понимает файловая система.

  2. Если вам нужно отобразить имя файла, конвертируйте его в UTF-8 перед использованием g_filename_to_utf8(). Если конвертация не удалась, отображается строка как "Unknown file name". Не конвертируйте эту строку обратно в кодировку используемую для имён файла если вы хотите поместить её в файловую систему; используйте оригинальное имя файла вместо этого. Например, окно документа в текстовом процессоре может отобразить "Unknown file name" в своём заголовке, но при этом всё ещё позволяет пользователю сохранить файл, так как это сохранит исходное имя внутренне. Это может произойти если пользователь не имеет установленной переменной окружения G_FILENAME_ENCODING даже если у него есть файлы имена которых не закодированы в UTF-8.

  3. Если ваш пользовательский интерфейс позволяет пользователю печатать имя файла для сохранения или переименования, конвертируйте его в кодировку используемую для имен файлов файловой системы используя g_filename_from_utf8(). Поместите конвертированное имя файла в функции такие как fopen(3). Если конверсия неудалась, у пользователя запрашивается другое имя файла. Это может произойти если пользователь печатает Японскими символами когда G_FILENAME_ENCODING установлена в ISO-8859-1, например.

Детали

g_convert ()

gchar*      g_convert                       (const gchar *str,
                                             gssize len,
                                             const gchar *to_codeset,
                                             const gchar *from_codeset,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);

Конвертирует строку из одного символьного набора в другой.

Помните что вы должны использовать g_iconv() для поточных конвертаций[2].

str : строка для конвертации
len : длина строки, или -1 если строка это nul-завершённый[1].
to_codeset : имя набора символов в который конвертируется str
from_codeset : набор символов str.
bytes_read : Размещение для хранения количества байт во входной строке которые были успешно конвертированы, или NULL. Даже если конвертация полностью удалась, это значение может быть меньше чем len если были частичные символы в конце ввода. Если произошла ошибка G_CONVERT_ERROR_ILLEGAL_SEQUENCE, значение хранит смещение байт после последней допустимой последовательности ввода.
bytes_written : количество байт сохраняемое в буфере вывода (не включая завершающий nul).
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Любая из ошибок в GConvertError может произойти.
Возвращает : Если конвертация выполнена, вновь распределённую nul-завершённую строку, которая должна быть освобождена g_free(). Иначе устанавливается NULL и error.

g_convert_with_fallback ()

gchar*      g_convert_with_fallback         (const gchar *str,
                                             gssize len,
                                             const gchar *to_codeset,
                                             const gchar *from_codeset,
                                             gchar *fallback,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);

Конвертирует строку из одного набора символов в другой, возможно включая последовательности перехода в аварийный режим для символов не подходящих для вывода. Помните что это не гарантирует что спецификация для последовательности аварийного режима в fallback будет учтена. Некоторые системы могут выполнять приблизительную конвертацию из from_codeset в to_codeset в их iconv() функциях, в этом случае GLib будет просто возвращать эту приблизительную конвертацию.

Помните что вы должны использовать g_iconv() для конвертации строк[2].

str : строка для конвертации
len : длина строки, или -1 если строка это nul-terminated[1].
to_codeset : имя набора символов в который конвертируется строка str
from_codeset : набор символов str.
fallback : UTF-8 строка для использования вместо символа не представленного в целевой кодировке. (Строка должна быть доступна для представления в целевой кодировке). Если NULL, символы не в целевой кодировке будут представлены как Unicode escapes \uxxxx или \Uxxxxyyyy.
bytes_read : Расположение для хранения количества байт во входной строке которые были успешно конвертированы, или NULL. Даже если конвертация была полностью выполнена, это значение может быть меньше чем len если есть частичные символы завершающие ввод.
bytes_written : количество байт сохранённых в буфер вывода (не включая завершающий nul).
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Любые ошибки в GConvertError могут произойти.
Возвращает : Если конвертация была полностью выполнена, вновь распределёная nul-завершённая строка, которая может быть освобождена с помощью g_free(). Иначе NULL и error будут установлены.

GIConv

typedef struct _GIConv GIConv;

GIConv структура оболочка iconv() дескриптора конвертации. Она содержит закрытые данные и доступ к ней должен осуществляться с помощью функций описанных ниже.


g_convert_with_iconv ()

gchar*      g_convert_with_iconv            (const gchar *str,
                                             gssize len,
                                             GIConv converter,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);

Конвертирует строку из одного набора символов в другой.

Помните что вы должны использовать g_iconv() для поточных конвертаций[2].

str : строка для конвертации
len : длина строки, или -1 если строка это nul-terminated[1].
converter : дескриптор конвертации из g_iconv_open()
bytes_read : размещение для хранения количества байт во входной строке которые были успешно конвертированы, или NULL. Даже если конвертация полностью выполнена, это значение может быть меньше чем len, если были частичные символы в конце ввода. Если произошла ошибка G_CONVERT_ERROR_ILLEGAL_SEQUENCE, будет сохранено значение смещения байт после последней допустимой последовательности ввода.
bytes_written : количество байт сохраняемых в буфере вывода (не включая завершающий nul).
error : размещение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки указанные в GConvertError.
Возвращает : если конвертация полностью выполнена, вновь распределённую nul-завершённую строку, которая может быть освобождена g_free(). Иначе NULL и error будут установлены.

G_CONVERT_ERROR

#define G_CONVERT_ERROR g_convert_error_quark()

Домен ошибки (Error domain) для конвертации набора символов. Ошибки в этом домене будут из перечисления GConvertError. Смотрите GError для детальной информации об ошибках.


g_iconv_open ()

GIConv      g_iconv_open                    (const gchar *to_codeset,
                                             const gchar *from_codeset);

То же самое что и стандартная подпрограмма UNIX iconv_open(), но может быть реализована через libiconv на разновидностях UNIX где имеется недостаток в родной реализации.

GLib обеспечивает g_convert() и g_locale_to_utf8() которые вероятно являются более удобными чем исходные оболочки iconv.

to_codeset : определяет устанавливаемую кодировку
from_codeset : из какой кодировки перекодируется
Возвращает : "дескриптор конвертора", или (GIConv)-1 если открываемый конвертер недоступен.

g_iconv ()

size_t      g_iconv                         (GIConv converter,
                                             gchar **inbuf,
                                             gsize *inbytes_left,
                                             gchar **outbuf,
                                             gsize *outbytes_left);

Тоже самое как стандартная подпрограмма UNIX iconv(), но может быть реализована через libiconv на разновидностях UNIX в которых нет родной реализации.

GLib обеспечивает g_convert() и g_locale_to_utf8() которые намного удобнее чем исходные оболочки iconv.

converter : дескриптор конвертации из g_iconv_open()
inbuf : байты для конвертации
inbytes_left : входной параметр, байты остаются для конвертации в inbuf
outbuf : конвертирует вывод байт
outbytes_left : параметр ввода-вывода, байты доступные для заполнения в outbuf
Возвращает : подсчёт необратимый преобразований, или -1 при возникновении ошибки error

g_iconv_close ()

gint        g_iconv_close                   (GIConv converter);

Тоже самое что стандартная подпрограмма UNIX iconv_close(), но может быть реализована через libiconv на разновидностях UNIX где нет родной реализации. Должна вызываться для очистки дескриптора конвертации из g_iconv_open() когда вы выполняете конвертационные действия.

GLib обеспечивает g_convert() и g_locale_to_utf8() которые намного удобнее чем исходные оболочки iconv.

converter : дескриптор конвертации из g_iconv_open()
Возвращает : -1 при ошибке, 0 при удачном выполнении

g_locale_to_utf8 ()

gchar*      g_locale_to_utf8                (const gchar *opsysstring,
                                             gssize len,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);

Конвертирует строку которая находится в кодировке используемой для строк C runtime (обычно тоже самое что используется операционной системой) в текущей локали в строку UTF-8.

opsysstring : строка в кодировке текущей локали. В Windows это означает system codepage.
len : длина строки, или -1 если строка это завершающий ноль (nul-terminated)[1].
bytes_read : размещение для хранения количества байт во входной строке когда конвертация полностью выполнена, или NULL. Даже если конвертация выполнена, этот параметр может быть меньше чем len если есть части символов в конце ввода. Если произошла ошибка G_CONVERT_ERROR_ILLEGAL_SEQUENCE, будет сохранено значение смещения байт после последней допустимой цепочки ввода.
bytes_written : количество байт сохранённых в буфере вывода (не включая завершающий nul).
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки в GConvertError.
Возвращает : Конвертируемая строка, или NULL при ошибке.

g_filename_to_utf8 ()

gchar*      g_filename_to_utf8              (const gchar *opsysstring,
                                             gssize len,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);

Конвертирует строку которая в кодировке используемой GLib для имён файлов в строку UTF-8. Помните что в Windows GLib использует UTF-8 для имён файлов.

opsysstring : строка в кодировке для имён файлов
len : длина строки, или -1 если строка это завершающий ноль (nul-terminated)[1].
bytes_read : расположение для хранения количества байт во входной строке когда конвертация полностью выполнена, или NULL. Даже если конвертация удалась, это значение может быть меньше чем len если есть части символов в конце ввода. Если произошла ошибка G_CONVERT_ERROR_ILLEGAL_SEQUENCE, будет сохранено смещение байт после последней допустимой цепочки ввода.
bytes_written : количество байт сохранённых в буфере вывода (не включая завершающий ноль).
error : размещение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки в GConvertError.
Возвращает : Конвертированная строка, или NULL при ошибке.

g_filename_from_utf8 ()

gchar*      g_filename_from_utf8            (const gchar *utf8string,
                                             gssize len,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);

Конвертирует строку из UTF-8 в кодировку GLib используемую для имен файлов. Помните что в Windows GLib использует UTF-8 для имён файлов.

utf8string : строка в кодировке UTF-8.
len : длина строки, или -1 если строка это завершающий ноль (nul-terminated).
bytes_read : расположение для хранения количества байт во входной строке при удачном выполнении конвертации, или NULL. Даже если конвертация выполнена, это значение может быть меньше чем len если есть части символов в конце ввода. Если произошла ошибка G_CONVERT_ERROR_ILLEGAL_SEQUENCE, сохраняется значение смещения байт после последней допустимой цепочки ввода.
bytes_written : количество байт сохранённых в буфере вывода (не включая завершающий ноль).
error : размещение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки в GConvertError.
Возвращает : Конвертируемая строка, или NULL при ошибке.

g_filename_from_uri ()

gchar*      g_filename_from_uri             (const gchar *uri,
                                             gchar **hostname,
                                             GError **error);

Конвертирует ASCII-кодировку URI в локальное имя файла в кодировке используемой для имён файлов.

uri : uri описывающий имя файла (escaped, encoded in ASCII).
hostname : расположение для хранения имени узла (hostname) для URI, или NULL. Если нет имени узла (hostname) в URI, то в этом расположении сохраняется NULL.
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут происходить любые ошибки в GConvertError.
Возвращает : результат в виде вновь распределённой строки содержащей имя файла, или NULL при ошибке.

g_filename_to_uri ()

gchar*      g_filename_to_uri               (const gchar *filename,
                                             const gchar *hostname,
                                             GError **error);

Конвертирует абсолютное имя файла в управляющие символы ASCII-кодировки URI, с компонентом пути упоминаемым далее в Разделе 3.3. RFC 2396.

filename : абсолютное имя файла определённое в GLib кодировке имён файлов, которое является дисковыми байтами имени файла в Unix, и UTF-8 в Windows
hostname : Имя узла в кодировке UTF-8, или NULL если нет.
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут происходить любые ошибки в GConvertError.
Возвращает : вновь распределённая строка содержащая результат URI, или NULL при ошибке.

g_get_filename_charsets ()

gboolean    g_get_filename_charsets         (G_CONST_RETURN gchar ***charsets);

Определяет привилегированные наборы символов используемые для имён файлов. Первый набор символов из charsets это кодировка имени файла, последующие наборы символов используются когда происходят попытки сгенерировать отображаемое представление имени файла, смотрите g_filename_display_name().

В Unix, набор символов определяются с помощью переменных окружения G_FILENAME_ENCODING и G_BROKEN_FILENAMES. В Windows, набор символов используемый в GLib API всегда UTF-8, а переменные окружения не имеют никакого эффекта.

G_FILENAME_ENCODING может быть установлен для разделённого запятыми списка набора символов имён. Специальная лексема "locale" применяется для обозначения набора символов для текущей локали. Если G_FILENAME_ENCODING не установлена, но установлена G_BROKEN_FILENAMES, набор символов текущей локали применяется как кодировка имени файла. Если переменные окружения не установлены совсем, в качестве кодировки имени файла применяется UTF-8, но набор символов текущей локали также помещается в список кодировок.

Возвращаемые charsets принадлежат GLib и не должны освобождаться.

Помните что в Unix, независимо от локального набора символов или значения G_FILENAME_ENCODING, фактические имена файлов представленные в системе могут быть в любой произвольной кодировке или просто тарабарщиной (gibberish).

charsets : расположение возвращаемого NULL-завершённого списка кодировок имён
Возвращает : TRUE если кодировка имени файла UTF-8.

Начиная с версии 2.6


g_filename_display_name ()

gchar*      g_filename_display_name         (const gchar *filename);

Конвертирует имя файла в допустимую UTF-8 строку. Конвертация необязательно обратима, поэтому вы должны иметь оригинал и использовать возвращаемое значение этой функции только непосредственно для отображения. В отличие от g_filename_to_utf8(), результатом гарантировано будет не-NULL даже если имя файла фактически не находится в кодировке имени файла GLib.

Если GLib не может понять кодировку filename, как последний способ она заменяет неизвестные символы с помощью U+FFFD, символом замены Unicode. Вы можете искать результат кодировки UTF-8 этого символа (который находится в восьмеричной записи "\357\277\275") для поиска вывода если filename был в недопустимой кодировке.

Если вы знаете полное имя пути файла вы должны использовать g_filename_display_basename(), так как она позволяет перекодировку имён файлов на основе их расположения.

filename : имя пути предположительно в GLib кодировке имени файла
Возвращает : вновь распределённая строка содержащая перевод имени файла в правильной UTF-8

Начиная с версии 2.6


g_filename_display_basename ()

gchar*      g_filename_display_basename     (const gchar *filename);

Возвращает отображаемое базовое имя для специфического имени файла, гарантировано в правильной UTF-8. Отображаемое имя может быть не идентично имени файла, например могут быть проблемы конвертации в UTF-8, а некоторые файлы могут быть оттранслированы в отображении.

Если GLib не может понять кодировку filename, как последний вариант она заменяет неизвестные символы с помощью U+FFFD, символ замены Unicode. Вы можете найти результат для UTF-8 кодировки этого символа (который находится в восьмеричном представлении "\357\277\275") для поиска вывода если filename был в недопустимой кодировке.

Вы должны поместить полное имя пути файла в функцию чтобы можно было выполнить трансляцию известных расположений.

Эта функция предпочтительней чем g_filename_display_name() если вам известен полный путь, так как это позволяет трансляцию.

filename : полное имя пути в кодировке имени файла GLib
Возвращает : вновь распределённая строка содержащая представление базового имени файла в допустимой UTF-8

Начиная с версии 2.6


g_uri_list_extract_uris ()

gchar**     g_uri_list_extract_uris         (const gchar *uri_list);

Разбирает URI список соответствующий text/uri-списку mime type, определённого в RFC 2483, в индивидуальные URIs, отменяя любые коментарии. URIs являются не утверждёнными.

uri_list : URI список
Возвращает : вновь распределённый NULL-завершённый список строк содержащих индивидуальные URIs. Массив должен быть освобождён с помощью g_strfreev().

Начиная с версии 2.6


g_locale_from_utf8 ()

gchar*      g_locale_from_utf8              (const gchar *utf8string,
                                             gssize len,
                                             gsize *bytes_read,
                                             gsize *bytes_written,
                                             GError **error);

Конвертирует строку из UTF-8 в кодировку используемую для строк C runtime (обычно тоже самое что используется операционной системой) в текущей локали.

utf8string : строка в кодировке UTF-8
len : длина строки, или -1 если строка завершающий ноль[1].
bytes_read : расположение для хранения количества байт во входной строке когда конвертация полностью выполнена, или NULL. Даже если конвертация завершилась успешно, это значение может быть меньше чем len если есть части символов в конце ввода. Если произошла ошибка G_CONVERT_ERROR_ILLEGAL_SEQUENCE, сохраняется значение смещения байт после последней удачной цепочки ввода.
bytes_written : количество байт сохранённых в буфере вывода (не включая завершающий ноль).
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки в GConvertError.
Возвращает : конвертированная строка, или NULL при ошибке.

enum GConvertError

typedef enum 
{
  G_CONVERT_ERROR_NO_CONVERSION,
  G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
  G_CONVERT_ERROR_FAILED,
  G_CONVERT_ERROR_PARTIAL_INPUT,
  G_CONVERT_ERROR_BAD_URI,
  G_CONVERT_ERROR_NOT_ABSOLUTE_PATH
} GConvertError;

Коды ошибок возвращаемые подпрограммами конвертации наборов символов.

G_CONVERT_ERROR_NO_CONVERSION Конвертация между запрошенными наборами символов не поддерживается.
G_CONVERT_ERROR_ILLEGAL_SEQUENCE Неправильная последовательность байт в конвертируемом вводе.
G_CONVERT_ERROR_FAILED Конвертация не удалась по некоторым причинам.
G_CONVERT_ERROR_PARTIAL_INPUT Частичная символьная последовательность в конце ввода.
G_CONVERT_ERROR_BAD_URI недопустимый URI.
G_CONVERT_ERROR_NOT_ABSOLUTE_PATH Имя пути не является абсолютным путём.

g_get_charset ()

gboolean    g_get_charset                   (G_CONST_RETURN char **charset);

Получает набор символов для текущей локали; вы можете использовать этот набор символов как аргумент для g_convert(), для конвертации из текущей локальной кодировки в некоторую другую кодировку. (Часто g_locale_to_utf8() и g_locale_from_utf8() являются хорошими shortcuts, всё же.)

Возвращаемое значение равно TRUE если локальной кодировкой является UTF-8, в этом случае вы можете избежать вызова g_convert().

Возвращаемая строка в charset не распределяется, и не должна освобождаться.

charset : расположение возвращаемого имени набора символов
Возвращает : TRUE если возвращаемый набор символов UTF-8


[1] Помните что некоторые кодировки могут позволять nul байтам находится в строках. В этом случае, использовать -1 для параметра len опасно.

[2] Несмотря на то, что byes_read может возвращать информацию о частичных символах, функции g_convert_... являются в основном неподходящими для потоков. Если основной конвертер поддерживает внутреннее состояние, то это не сохраняется через последовательность вызовов g_convert(), g_convert_with_iconv() или g_convert_with_fallback(). (Примером этому является GNU C конвертер для CP1255 который не выдаст основной символ пока он знает что следующий символ не знак который можно совместить с основным символом.)


Commandline option parser

Commandline option parser — Анализатор опций командной строки

Краткое описание


#include <glib.h>


enum        GOptionError;
#define     G_OPTION_ERROR
gboolean    (*GOptionArgFunc)               (const gchar *option_name,
                                             const gchar *value,
                                             gpointer data,
                                             GError **error);
            GOptionContext;
GOptionContext* g_option_context_new        (const gchar *parameter_string);
void        g_option_context_set_summary    (GOptionContext *context,
                                             const gchar *summary);
const gchar* g_option_context_get_summary   (GOptionContext *context);
void        g_option_context_set_description
                                            (GOptionContext *context,
                                             const gchar *description);
const gchar* g_option_context_get_description
                                            (GOptionContext *context);
const gchar* (*GTranslateFunc)              (const gchar *str,
                                             gpointer data);
void        g_option_context_set_translate_func
                                            (GOptionContext *context,
                                             GTranslateFunc func,
                                             gpointer data,
                                             GDestroyNotify destroy_notify);
void        g_option_context_set_translation_domain
                                            (GOptionContext *context,
                                             const gchar *domain);
void        g_option_context_free           (GOptionContext *context);
gboolean    g_option_context_parse          (GOptionContext *context,
                                             gint *argc,
                                             gchar ***argv,
                                             GError **error);
void        g_option_context_set_help_enabled
                                            (GOptionContext *context,
                                             gboolean help_enabled);
gboolean    g_option_context_get_help_enabled
                                            (GOptionContext *context);
void        g_option_context_set_ignore_unknown_options
                                            (GOptionContext *context,
                                             gboolean ignore_unknown);
gboolean    g_option_context_get_ignore_unknown_options
                                            (GOptionContext *context);
enum        GOptionArg;
enum        GOptionFlags;
#define     G_OPTION_REMAINING
            GOptionEntry;
void        g_option_context_add_main_entries
                                            (GOptionContext *context,
                                             const GOptionEntry *entries,
                                             const gchar *translation_domain);
            GOptionGroup;
void        g_option_context_add_group      (GOptionContext *context,
                                             GOptionGroup *group);
void        g_option_context_set_main_group (GOptionContext *context,
                                             GOptionGroup *group);
GOptionGroup* g_option_context_get_main_group
                                            (GOptionContext *context);
GOptionGroup* g_option_group_new            (const gchar *name,
                                             const gchar *description,
                                             const gchar *help_description,
                                             gpointer user_data,
                                             GDestroyNotify destroy);
void        g_option_group_free             (GOptionGroup *group);
void        g_option_group_add_entries      (GOptionGroup *group,
                                             const GOptionEntry *entries);
gboolean    (*GOptionParseFunc)             (GOptionContext *context,
                                             GOptionGroup *group,
                                             gpointer data,
                                             GError **error);
void        g_option_group_set_parse_hooks  (GOptionGroup *group,
                                             GOptionParseFunc pre_parse_func,
                                             GOptionParseFunc post_parse_func);
void        (*GOptionErrorFunc)             (GOptionContext *context,
                                             GOptionGroup *group,
                                             gpointer data,
                                             GError **error);
void        g_option_group_set_error_hook   (GOptionGroup *group,
                                             GOptionErrorFunc error_func);
void        g_option_group_set_translate_func
                                            (GOptionGroup *group,
                                             GTranslateFunc func,
                                             gpointer data,
                                             GDestroyNotify destroy_notify);
void        g_option_group_set_translation_domain
                                            (GOptionGroup *group,
                                             const gchar *domain);

Описание

Анализатор командной строки GOption предназначен для более простой замены библиотеки popt. Он поддерживает короткие и длинные опции командной строки, как показано в следующем примере:

testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2

Пример демонстрирует множество особенностей синтаксического анализатора командной строки GOption

  • Опции могут быть одиночной буквой с предустановленным одиночным тире. Множество коротких опций могут быть сгруппированы за одним тире.

  • Длинные опцией предустанавливаются двумя последовательными тире.

  • Опции могут иметь дополнительный аргумент, который может быть числом, строкой или именем файла. Для длинных опций, дополнительный аргумент может быть присоединён с помощью знака равенства сразу после названия опции.

  • Неопциональные аргументы возвращаются как сброшенные аргументы.

  • Аргумент состоящий исключительно из двух тире предотвращает дальнейший анализ, любые аргументы (даже которые начинаются с тире) возвращаются как сброшенные аргументы.

Другая важная особенность GOption в автоматической генерации приятно оформленного вывода справки. Если это явно не выключено с помощью функции g_option_context_set_help_enabled(), GOption распознаёт --help, -?, --help-all и --help-groupname опции (где groupname это имя GOptionGroup) и пишет текст, подобный показанному в следующем примере, в stdout.

Usage:
  testtreemodel [OPTION...] - test tree model performance

Help Options:
  -?, --help               Показать опции справки
  --help-all               Показать все опции справки
  --help-gtk               Показать опции GTK+

Application Options:
  -r, --repeats=N          Среднее число повторений N
  -m, --max-size=M         Проверить до 2^M элементов
  --display=DISPLAY        X display для использования
  -v, --verbose            Подробности
  -b, --beep               Сигнал при выполнении   
  --rand                   Произвольные данные

Группы опций GOption находятся в GOptionGroups, которые облегчают включение опций из многочисленных источников. Они позволяют приложениям собирать группы опций из используемых библиотек, добавляя их к своему GOptionContext, и анализируя все опции одним вызовом g_option_context_parse(). Смотрите gtk_get_option_group() для примера.

Если задекларированная опция является печатной строкой или именем файла, GOption позаботится о преобразовании в правильную кодировку; строки возвращаются в кодировке UTF-8, имена файлов в кодировке имён файлов GLib.

Вот полный пример настроек GOption для анализа командной строки приведенной в примере выше и выполнение вывода примера справки.

static gint repeats = 2;
static gint max_size = 8;
static gboolean verbose = FALSE;
static gboolean beep = FALSE;
static gboolean rand = FALSE;

static GOptionEntry entries[] = 
{
  { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Среднее число повторений N", "N" },
  { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Проверка до 2^M элементов", "M" },
  { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Подробности", NULL },
  { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Сигнал при выполнениии", NULL },
  { "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Произовольные данные", NULL },
  { NULL }
};

int 
main (int argc, char *argv[])
{
  GError *error = NULL;
  GOptionContext *context;

  context = g_option_context_new ("- test tree model performance");
  g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
  g_option_context_add_group (context, gtk_get_option_group (TRUE));
  g_option_context_parse (context, &argc, &argv, &error);
  
  /* ... */

}

Детали

enum GOptionError

typedef enum
{
  G_OPTION_ERROR_UNKNOWN_OPTION,
  G_OPTION_ERROR_BAD_VALUE,
  G_OPTION_ERROR_FAILED
} GOptionError;

Коды ошибок возвращаемые анализатором опций.

G_OPTION_ERROR_UNKNOWN_OPTION Опция неизвестна анализатору. Эта ошибка будет сообщена только если анализатор небыл проинструктирован игнорировать неизвестные опции, смотрите g_option_context_set_ignore_unknown_options().
G_OPTION_ERROR_BAD_VALUE Значение небыло проанализировано.
G_OPTION_ERROR_FAILED Функция GOptionArgFunc завершилась неудачно.

G_OPTION_ERROR

#define G_OPTION_ERROR (g_option_error_quark ())

Домен ошибки для анализатора опций. Ошибки в этом домене из перечисления GOptionError. Смотрите GError для информации о доменах ошибок.


GOptionArgFunc ()

gboolean    (*GOptionArgFunc)               (const gchar *option_name,
                                             const gchar *value,
                                             gpointer data,
                                             GError **error);

Тип функции для анализа как callback-функция для опции G_OPTION_ARG_CALLBACK.

option_name : Имя анализируемой опции. Это может быть любая буква с предустановленным одиночным тире (для коротких имён) или два последовательных тире перед длинным именем.
value : Значение для анализа.
data : Пользовательские данные добавляемые в GOptionGroup содержащую опции, которая была создана с помощью g_option_group_new()
error : Расположение для возвращаемых ошибок. Коды ошибок G_OPTION_ERROR_FAILED предназначены для использования в GOptionArgFunc.
Возвращает : TRUE если опция была полностью проанализирована, FALSE если произошла ошибка, в этом случае error должна быть установлена с помощью g_set_error()

GOptionContext

typedef struct _GOptionContext GOptionContext;

Структура GOptionContext определяет какие опции применяются анализатором опций командной строки. Структура содержит только закрытые поля и не должна использоваться непосредственно.


g_option_context_new ()

GOptionContext* g_option_context_new        (const gchar *parameter_string);

Создаёт новый опциональный контекст.

parameter_string может служить для множества целей. Он может служить для добавления описания сброшенных аргументов, которые не проанализированы GOptionContext, обычно что-то вроде "FILES" или "FILE1 FILE2...". Если вы используете G_OPTION_REMAINING для сбора сброшенных параметров, GLib обработает это автоматически используя arg_description соответсвующий GOptionEntry в суммарном использовании.

Другое назначение может дать короткое описание функциональности программы, например " - frob strings", которое отобразится в той же строке где и "использование". Для длинных описаний функциональности программы, которые должны отображаться как параграф ниже линии описывающей использование программы, используйте g_option_context_set_summary().

Помните что parameter_string переводится (смотрите g_option_context_set_translate_func()).

parameter_string : строка которая отображается в первой линии вывода --help, после короткого описания использования programname [OPTION...]
Возвращает : вновь созданная GOptionContext, которая должна быть освобождена с помощью g_option_context_free() после использования.

Начиная с версии 2.6


g_option_context_set_summary ()

void        g_option_context_set_summary    (GOptionContext *context,
                                             const gchar *summary);

Добавляет строку в отображаемый вывод --help перед списком опций. Обычно это короткое описание функциональности программы.

Помните что короткое описание переводится (смотрите g_option_context_set_translate_func()).

context : GOptionContext
summary : строка для отображения в выводе --help перед списком опций, или NULL

Начиная с версии 2.12


g_option_context_get_summary ()

const gchar* g_option_context_get_summary   (GOptionContext *context);

Возвращает короткое описание. Смотрите g_option_context_set_summary().

context : GOptionContext
Возвращает : короткое описание

Начиная с версии 2.12


g_option_context_set_description ()

void        g_option_context_set_description
                                            (GOptionContext *context,
                                             const gchar *description);

Добавляет строку для отображения в выводе --help после списка опций. Этот текст часто включает адрес для сообщения об ошибках.

Помните что краткое описание переводится (смотрите g_option_context_set_translate_func()).

context : GOptionContext
description : строка для отображения в выводе --help после списка опций, или NULL

Начиная с версии 2.12


g_option_context_get_description ()

const gchar* g_option_context_get_description
                                            (GOptionContext *context);

Возвращает описание. Смотрите g_option_context_set_description().

context : GOptionContext
Возвращает : описание

Начиная с версии 2.12


GTranslateFunc ()

const gchar* (*GTranslateFunc)              (const gchar *str,
                                             gpointer data);

Тип функции которая используется для перевода видимых пользователем строк, для вывода --help.

str : непереведённая строка
data : пользовательские данные определяемые при установке функции, например g_option_group_set_translate_func()
Возвращает : переведённую строку для текущей локализации. Возвращаемой строкой владеет GLib и она не должна освобождаться.

g_option_context_set_translate_func ()

void        g_option_context_set_translate_func
                                            (GOptionContext *context,
                                             GTranslateFunc func,
                                             gpointer data,
                                             GDestroyNotify destroy_notify);

Устанавливает функцию которая используется для перевода содержимого строк видимых пользователем, для вывода --help. Если func равен NULL, строки не переводятся.

Помните что группы опций имеют собственные функции перевода, эта функция затрагивает только parameter_string (смотрите g_option_context_nex()), краткое описание (смотрите g_option_context_set_summary()) и описание (смотрите g_option_context_set_description()).

Если вы используете gettext(), вам нужно только установить область перевода, смотрите g_context_group_set_translation_domain().

context : GOptionContext
func : GTranslateFunc, или NULL
data : пользовательские данные помещаемые в func, или NULL
destroy_notify : функция которая вызывается для освобождения data, или NULL

Начиная с версии 2.12


g_option_context_set_translation_domain ()

void        g_option_context_set_translation_domain
                                            (GOptionContext *context,
                                             const gchar *domain);

Удобная функция использующая gettext() для перевода видимых пользователем строк.

context : GOptionContext
domain : используемая область

Начиная с версии 2.12


g_option_context_free ()

void        g_option_context_free           (GOptionContext *context);

Освобождает контекст и все добавленные в него группы.

context : GOptionContext

Начиная с версии 2.6


g_option_context_parse ()

gboolean    g_option_context_parse          (GOptionContext *context,
                                             gint *argc,
                                             gchar ***argv,
                                             GError **error);

Анализирует аргументы командной строки, распознавая опции которые были добавлены в context. Побочный эффект вызова этой функции в том, что будет вызвана g_set_prgname().

Если анализ полностью выполнен, любые анализируемые аргументы будут удалены из массива, а argc и argv соответственно обновятся. Опция '--' удаляется из argv нет не анализируемых опций перед ней и после неё, или некоторые опции после неё начинаются с '-'. В этом случае происходит ошибка, argc и argv остаются неизменёнными.

Если включена автоматическая поддержка --help (смотрите g_option_context_set_help_enabled()), а массив argv содержит одну из распознаваемых опций справки, эта функция выполнит вывод справки на stdout и вызовет exit (0).

context : GOptionContext
argc : указатель на номер аргумента командной строки.
argv : указатель на массив аргументов командной строки.
error : расположение для возвращаемой ошибки
Возвращает : TRUE если анализ полностью выполнен, FALSE если произошла ошибка

Начиная с версии 2.6


g_option_context_set_help_enabled ()

void        g_option_context_set_help_enabled
                                            (GOptionContext *context,
                                             gboolean help_enabled);

Включает или выключает автоматическую генерацию вывода --help. По умолчанию, g_option_context_parse() распознаёт --help, -?, --help-all и --help-groupname и создаёт подходящий вывод на stdout.

context : GOptionContext
help_enabled : TRUE для включения --help, FALSE для отключения

Начиная с версии 2.6


g_option_context_get_help_enabled ()

gboolean    g_option_context_get_help_enabled
                                            (GOptionContext *context);

Определяет включена ли автоматическая генерация --help для context. Смотрите g_option_context_set_help_enabled().

context : GOptionContext
Возвращает : TRUE если автоматическая генерация справки включена.

Начиная с версии 2.6


g_option_context_set_ignore_unknown_options ()

void        g_option_context_set_ignore_unknown_options
                                            (GOptionContext *context,
                                             gboolean ignore_unknown);

Устанавливает игнорировать неизвестные опции или нет. Если опция игнорируется, то она сбрасывается в массив argv после анализа. По умолчанию, g_option_context_parse() воспринимает неизвестные опции как ошибки.

Эти настройки не затрагивают не опциональные аргументы (то есть аргументы которые начинаются не с тире). Но помните что GOption не может надёжно определить принадлежит ли не-опция к предыдущей неизвестной опции.

context : GOptionContext
ignore_unknown : TRUE для игнорирования неизвестных опций, FALSE для производства ошибки при встрече неизвестной опции

Начиная с версии 2.6


g_option_context_get_ignore_unknown_options ()

gboolean    g_option_context_get_ignore_unknown_options
                                            (GOptionContext *context);

Определяет игнорируются неизвестные опции или нет. Смотрите g_option_context_set_ignore_unknown_options().

context : GOptionContext
Возвращает : TRUE если неизвестные опции игнорируются.

Начиная с версии 2.6


enum GOptionArg

typedef enum
{
  G_OPTION_ARG_NONE,
  G_OPTION_ARG_STRING,
  G_OPTION_ARG_INT,
  G_OPTION_ARG_CALLBACK,
  G_OPTION_ARG_FILENAME,
  G_OPTION_ARG_STRING_ARRAY,
  G_OPTION_ARG_FILENAME_ARRAY,
  G_OPTION_ARG_DOUBLE,
  G_OPTION_ARG_INT64
} GOptionArg;

GOptionArg перечисляет значения определяющие какой тип дополнительного параметра опции ожидается обнаружить. Если опции ожидает дополнительный параметр, он может быть определён несколькими способами; с короткими опциями: -x arg, с длинными опциями: --name arg или комбинировано в одном аргументе: --name=arg.

G_OPTION_ARG_NONE Нет дополнительного параметра. Это полезно для простых флагов.
G_OPTION_ARG_STRING Опция принимает строковый параметр.
G_OPTION_ARG_INT Опция принимает целочисленный параметр.
G_OPTION_ARG_CALLBACK Опция обеспечивает callback-функцию для анализа дополнительного параметра.
G_OPTION_ARG_FILENAME Опция принимает имя файла как параметр.
G_OPTION_ARG_STRING_ARRAY Опция принимает строковый параметр, многократное использование опции собирается в строковый массив.
G_OPTION_ARG_FILENAME_ARRAY Опция принимает имя файла как параметр, многократное использование опции собирается в строковый массив.
G_OPTION_ARG_DOUBLE Опция принимает двойной параметр. Параметр может быть в формате пользовательской локализации или в "C" locale. Начиная с версии 2.12
G_OPTION_ARG_INT64 Опция принимает 64-битное целочисленное. Как G_OPTION_ARG_INT но для большего числа. Число может быть десятичным, шестнадцатиричным (когда префикс 0x, например, 0xffffffff). Начиная с версии 2.12

enum GOptionFlags

typedef enum
{
  G_OPTION_FLAG_HIDDEN		= 1 << 0,
  G_OPTION_FLAG_IN_MAIN		= 1 << 1,
  G_OPTION_FLAG_REVERSE		= 1 << 2,
  G_OPTION_FLAG_NO_ARG		= 1 << 3,
  G_OPTION_FLAG_FILENAME	= 1 << 4,
  G_OPTION_FLAG_OPTIONAL_ARG    = 1 << 5,
  G_OPTION_FLAG_NOALIAS	        = 1 << 6
} GOptionFlags;

Флаги которые модифицируют отдельные опции.

G_OPTION_FLAG_HIDDEN Опция не появляется в выводе --help.
G_OPTION_FLAG_IN_MAIN Опция появляется в основном разделе вывода --help, даже если она определена в группе.
G_OPTION_FLAG_REVERSE Для опции вида G_OPTION_ARG_NONE, этот флаг указывает что опция имеет обратный смысл.
G_OPTION_FLAG_NO_ARG Для опции вида G_OPTION_ARG_CALLBACK, этот флаг указывает что callback-функция не принимает аргументов (как опция G_OPTION_ARG_NONE). Начиная с версии 2.8
G_OPTION_FLAG_FILENAME Для опции вида G_OPTION_ARG_CALLBACK, этот флаг указывает что аргумент должен быть помещён в callback-функцию в кодировке имён файлов GLib, а не в UTF-8. Начиная с версии 2.8
G_OPTION_FLAG_OPTIONAL_ARG Для опции вида G_OPTION_ARG_CALLBACK, этот флаг указывает что аргумент является опциональным. Если нет аргумента, то данные для GOptionParseFunc будут установлены в значение NULL. Начиная с версии 2.8
G_OPTION_FLAG_NOALIAS Этот флаг выключает автоматическое разрешение противоречий префиксов имён длинных опций с groupname-, если есть конфликты. Эта опция должна использоваться только в ситуациях где псевдоним необходим для некоторого устаревшего интерфейса командной строки. Использование этой опции небезопасно, если все все группы опций не находятся под вашим прямым контролем. Начиная с версии 2.8.

G_OPTION_REMAINING

#define G_OPTION_REMAINING ""

Если длинная опция в основной группе имеет это имя, она не обрабатывается как обычная опция. Вместо этого она собирает все неопциональные аргументы которые в противном случае будут сброшены в argv. Опция должна быть типа G_OPTION_ARG_STRING_ARRAY или G_OPTION_ARG_FILENAME_ARRAY.

Использование G_OPTION_REMAINING, вместо простого сканирования argv для просмотра оставшихся параметров, имеет преимущество, так как GOption заботится о необходимом перекодировании строк или имён файлов.

Начиная с версии 2.6


GOptionEntry

typedef struct {
  const gchar *long_name;
  gchar        short_name;
  gint         flags;

  GOptionArg   arg;
  gpointer     arg_data;
  
  const gchar *description;
  const gchar *arg_description;
} GOptionEntry;

GOptionEntry определяет единственную опцию. Для эффективности, она должна быть добавлена в GOptionGroup с помощью g_option_context_add_main_entries() или g_option_group_add_entries().

const gchar *long_name; Длинное имя опции может использоваться для определения в командной строке как --long_name. Все опции должны иметь длинные имена. Для решения конфликтов, если множество групп опций содержат одинаковое длинное имя, опцию также возможно определить как --groupname-long_name.
gchar short_name; Если опция имеет короткое имя, она может быть определена в командной строке как -short_name. short_name должен быть печатным ASCII символом не тире '-', или нулём если опция не имеет короткого имени.
gint flags; Флаги из GOptionFlags.
GOptionArg arg; Тип опции, как GOptionArg.
gpointer arg_data; Если тип arg это G_OPTION_ARG_CALLBACK, тогда arg_data должен указывать на GOptionArgFunc callback-функцию, которая будет вызвана для обработки дополнительных параметров. Иначе, arg_data это указатель на расположение для сохраняемого значения, требуемый тип расположения зависит от типа arg:
const gchar *description; описание для опции в выводе --help. description переводится с помощью translate_func группы, смотрите g_option_group_set_translation_domain().
const gchar *arg_description; метка-заполнитель для используемого дополнительного параметра анализируемой опции в выводе --help. arg_description переводится используя translate_func группы, смотрите g_option_group_set_translation_domain().

g_option_context_add_main_entries ()

void        g_option_context_add_main_entries
                                            (GOptionContext *context,
                                             const GOptionEntry *entries,
                                             const gchar *translation_domain);

Удобная функция которая создаёт основную группу если она не существует, добавляет в неё entries и устанавливает область перевода.

context : GOptionContext
entries : NULL-завершённый массив GOptionEntrys
translation_domain : область перевода используемая для перевода вывода --help опций в entries с помощью gettext(), или NULL

Начиная с версии 2.6


GOptionGroup

typedef struct _GOptionGroup GOptionGroup;

Структура GOptionGroup определяет опции в единственной группе. Структура имеет только закрытые поля и не должна использоваться непосредственно.

Все опции в группе используют совместно одну функцию перевода. Библиотеки которые необходимы для анализа опций командной строки обеспечат функцию для получения GOptionGroup содержащую эти опции, которую приложение может добавить в свой GOptionContext.


g_option_context_add_group ()

void        g_option_context_add_group      (GOptionContext *context,
                                             GOptionGroup *group);

Добавляет GOptionGroup в context, так чтобы анализ context распознал опции в группе. Помните что группа будет освобождена вместе с контекстом когда будет вызвана g_option_context_free(), поэтому вы не должны освобождать группу самостоятельно после добавления её в контекст.

context : GOptionContext
group : добавляемая группа

Начиная с версии 2.6


g_option_context_set_main_group ()

void        g_option_context_set_main_group (GOptionContext *context,
                                             GOptionGroup *group);

Устанавливает GOptionGroup как основную группу context. Это имеет тот же эффект как вызов g_option_context_add_group(), только разница в том, что опции в основной группе обрабатываются по другому когда генерируется вывод --help.

context : GOptionContext
group : группа для установки в качестве основной

Начиная с версии 2.6


g_option_context_get_main_group ()

GOptionGroup* g_option_context_get_main_group
                                            (GOptionContext *context);

Возвращает указатель на основную группу которая принадлежит к context.

context : GOptionContext
Возвращает : основная группа для context, или NULL если context не имеет основной группы. Помните что группа принадлежит context и не должна изменяться или освобождаться.

Начиная с версии 2.6


g_option_group_new ()

GOptionGroup* g_option_group_new            (const gchar *name,
                                             const gchar *description,
                                             const gchar *help_description,
                                             gpointer user_data,
                                             GDestroyNotify destroy);

Создаёт новую GOptionGroup.

name : имя для группы опции, оно используется для получения справки об опциях в этой группе с помощью --help-name
description : описание для этой группы которое должно показываться в выводе --help. Эта строка переводится используя область перевода или функцию перевода в группе.
help_description : описание для --help-name опции. Эта строка переводится используя область перевода или функцию перевода в группе.
user_data : пользовательские данные которые будут помещены в обработчик перед и после анализа, обработчик ошибок и callbacks-функции G_OPTION_ARG_CALLBACK опций, или NULL
destroy : функция для освобождения user_data, или NULL
Возвращает : вновь созданная группа опций. Она должна быть добавлена в GOptionContext или освобождена с помощью g_option_group_free().

Начиная с версии 2.6


g_option_group_free ()

void        g_option_group_free             (GOptionGroup *group);

Освобождает GOptionGroup. Помните что вы не должны освобождать группы добавленные в GOptionContext.

group : GOptionGroup

Начиная с версии 2.6


g_option_group_add_entries ()

void        g_option_group_add_entries      (GOptionGroup *group,
                                             const GOptionEntry *entries);

Добавляет опцию определённую в entries к group.

group : GOptionGroup
entries : NULL-завершённый массив GOptionEntrys

Начиная с версии 2.6


GOptionParseFunc ()

gboolean    (*GOptionParseFunc)             (GOptionContext *context,
                                             GOptionGroup *group,
                                             gpointer data,
                                             GError **error);

Тип функции которая может быть вызвана перед и после анализа.

context : Активный GOptionContext
group : группа с которой связана функция
data : пользовательские данные добавляемые в GOptionGroup содержащую опцию где она была создана с помощью g_option_group_new()
error : расположение для возвращаемой ошибки
Возвращает : TRUE если функция полностью выполнена, FALSE если произошла ошибка, в этом случае должна быть установлена error с помощью g_set_error()

g_option_group_set_parse_hooks ()

void        g_option_group_set_parse_hooks  (GOptionGroup *group,
                                             GOptionParseFunc pre_parse_func,
                                             GOptionParseFunc post_parse_func);

Связывает две функции с group которые будут вызваны из g_option_context_parse() перед анализом первой опции и после анализа последней опции соответственно.

Помните что пользовательские данные помещаемые в pre_parse_func и post_parse_func могут быть определены при создании группы с помощью g_option_group_new().

group : GOptionGroup
pre_parse_func : функция вызываемая перед анализом, или NULL
post_parse_func : функция вызываемая после анализа, или NULL

Начиная с версии 2.6


GOptionErrorFunc ()

void        (*GOptionErrorFunc)             (GOptionContext *context,
                                             GOptionGroup *group,
                                             gpointer data,
                                             GError **error);

Тип функции используемая как callback-функция когда происходит ошибка анализа.

context : Активный GOptionContext
group : группа с которой связана функция
data : пользовательские данные добавляемые в GOptionGroup содержащую опцию где она была создана с помощью g_option_group_new()
error : GError содержащая детали произошедшей ошибки анализа

g_option_group_set_error_hook ()

void        g_option_group_set_error_hook   (GOptionGroup *group,
                                             GOptionErrorFunc error_func);

Связывает функцию с group которая будет вызвана из g_option_context_parse() когда произойдёт ошибка.

Помните что пользовательские данные помещаемые в pre_parse_func и post_parse_func могут быть определены при создании группы с помощью g_option_group_new().

group : GOptionGroup
error_func : функция вызываемая при возникновении ошибки

Начиная с версии 2.6


g_option_group_set_translate_func ()

void        g_option_group_set_translate_func
                                            (GOptionGroup *group,
                                             GTranslateFunc func,
                                             gpointer data,
                                             GDestroyNotify destroy_notify);

Устанавливает функцию которая используется для перевода строк видимых пользователем, для вывода --help. Разные группы могут использовать разные GTranslateFuncs. Если func это NULL, строки не переводятся.

Если вы используете gettext() , вам нужно только установить область перевода, смотрите g_option_group_set_translation_domain().

group : GOptionGroup
func : GTranslateFunc, или NULL
data : пользовательские данные помещаемые в func, или NULL
destroy_notify : функция которая вызывается для освобождения data, или NULL

Начиная с версии 2.6


g_option_group_set_translation_domain ()

void        g_option_group_set_translation_domain
                                            (GOptionGroup *group,
                                             const gchar *domain);

Удобная функция использующая gettext() для перевода видимых пользователем строк.

group : GOptionGroup
domain : используемая область

Начиная с версии 2.6


Datasets

Datasets — Связь групп элементов данных со специфическим расположением памяти.

Краткое описание


#include <glib.h>


#define     g_dataset_id_set_data           (l, k, d)
void        g_dataset_id_set_data_full      (gconstpointer dataset_location,
                                             GQuark key_id,
                                             gpointer data,
                                             GDestroyNotify destroy_func);
void        (*GDestroyNotify)               (gpointer data);
gpointer    g_dataset_id_get_data           (gconstpointer dataset_location,
                                             GQuark key_id);
#define     g_dataset_id_remove_data        (l, k)
gpointer    g_dataset_id_remove_no_notify   (gconstpointer dataset_location,
                                             GQuark key_id);

#define     g_dataset_set_data              (l, k, d)
#define     g_dataset_set_data_full         (l, k, d, f)
#define     g_dataset_get_data              (l, k)
#define     g_dataset_remove_data           (l, k)
#define     g_dataset_remove_no_notify      (l, k)

void        g_dataset_foreach               (gconstpointer dataset_location,
                                             GDataForeachFunc func,
                                             gpointer user_data);
void        (*GDataForeachFunc)             (GQuark key_id,
                                             gpointer data,
                                             gpointer user_data);
void        g_dataset_destroy               (gconstpointer dataset_location);

Описание

Наборы данных связывают группы элементов данных со специфическим расположением памяти. Это полезно если вам необходимо связать данные со структурами возвращаемыми из внешних библиотек. Так как вы не изменяете структуру, вы используете её расположение в памяти как ключ в наборе данных, в котором вы можете связать любое количество элементов данных.

Есть две формы большинства функций набора данных. Первая форма использовать строки для идентификации элементов данных связанных с расположением. Вторая форма использует идентификаторы GQuark, которые создаются с помощью вызова g_quark_from_string() или g_quark_from_static_string(). Вторая форма быстрее, так как она не требует поиска строки в хеш таблице идентификаторов GQuark.

Нет функции для создания набора данных. Он автоматически создаётся когда вы добавляете элемент в него.

Для добавления элемента в набор данных используйте g_dataset_id_set_data(), g_dataset_id_set_data_full(), g_dataset_set_data() and g_dataset_set_data_full().

Для получения элемента данных из набора данных используйте g_dataset_id_get_data() и g_dataset_get_data().

Для перемещения по всем элементам данных в наборе данных используйте g_dataset_foreach() (not thread-safe).

Для удаления элементов данных из набора данных используйте g_dataset_id_remove_data() и g_dataset_remove_data().

Для уничтожения набора данных, используйте g_dataset_destroy().

Детали

g_dataset_id_set_data()

#define     g_dataset_id_set_data(l, k, d)

Устанавливает элемент данных связанный с указанным GQuark идентификатором. Любые предыдущие данные с тем же ключом удаляются и вызывается функция их уничтожения.

l : расположение идентифицирующее набор данных.
k : GQuark для идентификации элемента данных.
d : элемент данных.

g_dataset_id_set_data_full ()

void        g_dataset_id_set_data_full      (gconstpointer dataset_location,
                                             GQuark key_id,
                                             gpointer data,
                                             GDestroyNotify destroy_func);

Устанавливает элемент данных связанный с указанным GQuark, а также функцию вызываемую для разрушения элемента данных. Любые предыдущие данные с тем же ключом удаляются и вызывается функция их уничтожения.

dataset_location : расположение идентифицирующее набор данных.
key_id : GQuark идентифицирующий элемент данных.
data : элемент данных.
destroy_func : функция вызываемая при удалении элемента данных. Эта функция вызывается с элементом данных и может использоваться для освобождения любой памяти распределённой для него.

GDestroyNotify ()

void        (*GDestroyNotify)               (gpointer data);

Определяет тип функции которая вызывается когда элемент уничтожается. В неё помещается указатель на элемент данных и она должна освободить всю память и все ресурсы распределённые для этого элемента.

data : элемент данных.

g_dataset_id_get_data ()

gpointer    g_dataset_id_get_data           (gconstpointer dataset_location,
                                             GQuark key_id);

Выдает элемент данных соответствующий GQuark.

dataset_location : расположение идентифицирующее набор данных.
key_id : GQuark идентифицирующий элемент данных.
Возвращает : элемент данных соответствующий GQuark, или NULL если он не найден.

g_dataset_id_remove_data()

#define     g_dataset_id_remove_data(l, k)

Удаляет элемент данных из набора данных. Функция уничтожения элемента данных вызывается если была установлена.

l : расположение идентифицирующее набор данных.
k : GQuark идентифицирующий элемент данных.

g_dataset_id_remove_no_notify ()

gpointer    g_dataset_id_remove_no_notify   (gconstpointer dataset_location,
                                             GQuark key_id);

Удаляет элемент, не вызывая разрушающую функцию для него.

dataset_location : расположение идентифицирующее набор данных.
key_id : GQuark ID идентифицирующий элемент данных.
Возвращает : предыдущие данные с key_id, или NULL если нет.

g_dataset_set_data()

#define     g_dataset_set_data(l, k, d)

Устанавливает данные соответствующие указанному строковому идентификатору.

l : расположение идентифицирующее набор данных.
k : строка строка идентифицирующая элемент данных.
d : элемент данных.

g_dataset_set_data_full()

#define     g_dataset_set_data_full(l, k, d, f)

Устанавливает данные соответствующие указанному строковому идентификатору, и функцию уничтожающую элемент данных.

l : расположение идентифицирующее набор данных.
k : строка строка идентифицирующая элемент данных.
d : элемент данных.
f : функция вызываемая когда удаляется элемент данных. Эта функция вызывается с элементом данных и может использоваться для освобождения любой памяти и ресурсов распределённых для него.

g_dataset_get_data()

#define     g_dataset_get_data(l, k)

Выдаёт элемент данных соответствующий строке.

l : расположение идентифицирующее набор данных.
k : строка идентифицирующая элемент данных.
Возвращает : элемент данных соответствующий строке, или NULL если он не найден.

g_dataset_remove_data()

#define     g_dataset_remove_data(l, k)

Удаляет элемент данных соответствующий строке. Она вызывает функцию уничтожения если та установлена.

l : расположение идентифицирующее набор данных.
k : строка identifying элемент данных.

g_dataset_remove_no_notify()

#define     g_dataset_remove_no_notify(l, k)

Удаляет элемент, без вызова функции уничтожения.

l : расположение идентифицирующее набор данных.
k : строка идентифицирующая элемент данных.

g_dataset_foreach ()

void        g_dataset_foreach               (gconstpointer dataset_location,
                                             GDataForeachFunc func,
                                             gpointer user_data);

Вызывает указанную функцию для каждого элемента данных который связан с указанным расположением. Помните что эта функция потоко-небезопасна. Поэтому если datalist не может быть защищен от любых изменений в течении вызова этой функции, она не должна вызываться.

dataset_location : расположение идентифицирующее набор данных.
func : функция вызываемая для каждого элемента данных.
user_data : пользовательские данные помещаемые в функцию.

GDataForeachFunc ()

void        (*GDataForeachFunc)             (GQuark key_id,
                                             gpointer data,
                                             gpointer user_data);

Определяет тип функции помещаемой в g_dataset_foreach(). Она вызывается с каждым GQuark id и связывает элемент днных, вместе с параметром user_data поставляемым в g_dataset_foreach().

key_id : GQuark идентифицирующий элемент данных.
data : элемент данных.
user_data : пользовательские данные для g_dataset_foreach().

g_dataset_destroy ()

void        g_dataset_destroy               (gconstpointer dataset_location);

Уничтожает набор данных, освобождая всю распределённую память и вызывая любую функцию уничтожения установленную для элементов данных.

dataset_location : расположение идентифицирующее набор данных.

Функции даты и времени

Date and Time Functions — календарные вычисления и различный материал времени.

Краткое описание


#include <glib.h>


#define     G_USEC_PER_SEC
            GTimeVal;
void        g_get_current_time              (GTimeVal *result);
void        g_usleep                        (gulong microseconds);
void        g_time_val_add                  (GTimeVal *time_,
                                             glong microseconds);
gboolean    g_time_val_from_iso8601         (const gchar *iso_date,
                                             GTimeVal *time_);
gchar*      g_time_val_to_iso8601           (GTimeVal *time_);

            GDate;
typedef     GTime;
enum        GDateDMY;
typedef     GDateDay;
enum        GDateMonth;
typedef     GDateYear;
enum        GDateWeekday;

#define     G_DATE_BAD_DAY
#define     G_DATE_BAD_JULIAN
#define     G_DATE_BAD_YEAR

GDate*      g_date_new                      (void);
GDate*      g_date_new_dmy                  (GDateDay day,
                                             GDateMonth month,
                                             GDateYear year);
GDate*      g_date_new_julian               (guint32 julian_day);
void        g_date_clear                    (GDate *date,
                                             guint n_dates);
void        g_date_free                     (GDate *date);

void        g_date_set_day                  (GDate *date,
                                             GDateDay day);
void        g_date_set_month                (GDate *date,
                                             GDateMonth month);
void        g_date_set_year                 (GDate *date,
                                             GDateYear year);
void        g_date_set_dmy                  (GDate *date,
                                             GDateDay day,
                                             GDateMonth month,
                                             GDateYear y);
void        g_date_set_julian               (GDate *date,
                                             guint32 julian_date);
void        g_date_set_time                 (GDate *date,
                                             GTime time_);
void        g_date_set_time_t               (GDate *date,
                                             time_t timet);
void        g_date_set_time_val             (GDate *date,
                                             GTimeVal *timeval);
void        g_date_set_parse                (GDate *date,
                                             const gchar *str);

void        g_date_add_days                 (GDate *date,
                                             guint n_days);
void        g_date_subtract_days            (GDate *date,
                                             guint n_days);
void        g_date_add_months               (GDate *date,
                                             guint n_months);
void        g_date_subtract_months          (GDate *date,
                                             guint n_months);
void        g_date_add_years                (GDate *date,
                                             guint n_years);
void        g_date_subtract_years           (GDate *date,
                                             guint n_years);
gint        g_date_days_between             (const GDate *date1,
                                             const GDate *date2);
gint        g_date_compare                  (const GDate *lhs,
                                             const GDate *rhs);
void        g_date_clamp                    (GDate *date,
                                             const GDate *min_date,
                                             const GDate *max_date);
void        g_date_order                    (GDate *date1,
                                             GDate *date2);

GDateDay    g_date_get_day                  (const GDate *date);
GDateMonth  g_date_get_month                (const GDate *date);
GDateYear   g_date_get_year                 (const GDate *date);
guint32     g_date_get_julian               (const GDate *date);
GDateWeekday g_date_get_weekday             (const GDate *date);
guint       g_date_get_day_of_year          (const GDate *date);

guint8      g_date_get_days_in_month        (GDateMonth month,
                                             GDateYear year);
gboolean    g_date_is_first_of_month        (const GDate *date);
gboolean    g_date_is_last_of_month         (const GDate *date);
gboolean    g_date_is_leap_year             (GDateYear year);
guint       g_date_get_monday_week_of_year  (const GDate *date);
guint8      g_date_get_monday_weeks_in_year (GDateYear year);
guint       g_date_get_sunday_week_of_year  (const GDate *date);
guint8      g_date_get_sunday_weeks_in_year (GDateYear year);
guint       g_date_get_iso8601_week_of_year (const GDate *date);

gsize       g_date_strftime                 (gchar *s,
                                             gsize slen,
                                             const gchar *format,
                                             const GDate *date);
void        g_date_to_struct_tm             (const GDate *date,
                                             struct tm *tm);

gboolean    g_date_valid                    (const GDate *date);
gboolean    g_date_valid_day                (GDateDay day);
gboolean    g_date_valid_month              (GDateMonth month);
gboolean    g_date_valid_year               (GDateYear year);
gboolean    g_date_valid_dmy                (GDateDay day,
                                             GDateMonth month,
                                             GDateYear year);
gboolean    g_date_valid_julian             (guint32 julian_date);
gboolean    g_date_valid_weekday            (GDateWeekday weekday);

Описание

Структура данных GDate представляет день между 1 Января (January 1), 1 Года (Year 1), и несколькими тысячами лет в будущем (в данный момент это составляет приблизительно 65535 лет, но g_date_set_parse() анализирует только до 8000 года приблизительно - простой счёт в "несколько тысяч"). GDate предназначена для представления ежедневных дат, не астрономических дат, не исторических дат, не ISO временных интервалов (timestamps) и не подобных им. Она экстраполирует текущий Григорианский календарь вперёд и назад во времени; не производится никаких попыток изменить календарь для соответствия временным периодам или месту расположения. GDate не хранит информацию о времени; она представляет day.

GDate реализация имеет несколько прекрасных особенностей; она является 64-битной структурой, поэтому хранение большого количества дат очень эффективно. Она может принимать оба вида представления даты и Юлианское и день-месяц-год, так как некоторые расчёты более просты либо с одним представлением даты либо с другим. Юлианское представление - это просто подсчёт дней с некоторой фиксированной даты в прошлом; для GDate фиксированным днём является 1 Января, 1 года нашей эры (1 AD). ("Юлианские" даты в GDate API не являются фактическими Юлианскими датами в техническом смысле; технически, Юлианские даты подсчитываются начиная с Юлианского периода, 1 Января 4713 год до нашей эры (Julian period, Jan 1, 4713 BC)).

GDate проста в использовании. Сначала вам потребуется пустая дата ("blank" date); вы можете получить динамически распределяемую дату из g_date_new(), или вы можете объявить автоматическую переменную или массив и инициализировать его в нормальное состояние вызвав g_date_clear(). Очищенная дата это нормально; это безопасно для вызова g_date_set_dmy() и других функций мутаторов для инициализации значения очищенной даты. Однако, очищенная дата первоначально недоступна, это значит что она представляет день которого не существует. Она не определена для вызова любых подпрограмм расчёта даты. Если вы определяете дату от пользователя или другого непредсказуемого источника, вы должны проверять правильность даты с помощью g_date_valid(). g_date_valid() также используется для проверки ошибок g_date_set_parse() и других функций которые могут завершиться неудачно. Даты могут быть очищены снова с помощью вызова g_date_clear().

Очень важно использовать API для доступа к GDatestruct. Зачастую правильным является только представление день-месяц-год (day-month-year) или Юлианское. Иногда не одно из этих представлений неправильно. Используйте API.

GLib не содержит функций манипулирования временем; однако, есть GTime typedef и GTimeVal структура которые представляют более точное время (в микросекундах). Вы можете запросить текущее время как GTimeVal с помощью g_get_current_time().

Детали

G_USEC_PER_SEC

#define G_USEC_PER_SEC 1000000

Количество микросекунд в одной секунде (1 миллион). Этот макрос обеспечивает удобочитаемость кода.


GTimeVal

typedef struct {
  glong tv_sec;
  glong tv_usec;
} GTimeVal;

Представляет точное время, с секундами и микросекундами. Похоже на возврат struct timeval вызова the gettimeofday() UNIX.

glong tv_sec; секунды.
glong tv_usec; микросекунды.

g_get_current_time ()

void        g_get_current_time              (GTimeVal *result);

Аналог UNIX функции gettimeofday(), но переносимый.

result : GTimeVal структура в которой хранится текущее время.

g_usleep ()

void        g_usleep                        (gulong microseconds);

Приостанавливает текущий поток на определённое количество микросекунд. В секунде есть 1 миллион микросекунд (представляется с помощью макроса G_USEC_PER_SEC). g_usleep() может иметь ограниченную точность, зависит от аппаратуры и операционной системы; не полагайтесь на точную длину паузы.

microseconds : количество микросекунд для паузы.

g_time_val_add ()

void        g_time_val_add                  (GTimeVal *time_,
                                             glong microseconds);

Добавляет полученное количество микросекунд к time_. microseconds может быть также отрицательным для уменьшения значения time_.

time_ : GTimeVal
microseconds : количество микросекунд для добавления к time

g_time_val_from_iso8601 ()

gboolean    g_time_val_from_iso8601         (const gchar *iso_date,
                                             GTimeVal *time_);

Конвертирует строку содержащую код даты и времени ISO 8601 в GTimeVal и помещает её в time_.

iso_date : строка кода даты ISO 8601
time_ : GTimeVal
Возвращает : TRUE если конвертация прошла успешно.

Начиная с версии 2.12


g_time_val_to_iso8601 ()

gchar*      g_time_val_to_iso8601           (GTimeVal *time_);

Конвертирует time_ в строку кода ISO 8601, относительно Coordinated Universal Time (UTC).

time_ : GTimeVal
Возвращает : вновь распределённая строка содержащая дату ISO 8601

Начиная с версии 2.12


GDate

typedef struct {
  guint julian_days : 32; /* julian days representation - we use a
                           *  bitfield hoping that 64 bit platforms
                           *  will pack this whole struct in one big
                           *  int
                           */

  guint julian : 1;    /* julian is valid */
  guint dmy    : 1;    /* dmy is valid */

  /* DMY representation */
  guint day    : 6;
  guint month  : 4;
  guint year   : 16;
} GDate;

Представляет день между 1 Января 1 Года и и несколькими тысячами лет будущего. Ни к одному из членов не нужно обращаться непосредственно. Если GDate определена из g_date_new(), она будет безопасна для изменений, но недоступна и поэтому не безопасна для календарных расчётов. Если это объявить в стеке, он будет содержать мусор поэтому должен быть инициализирован с помощью g_date_clear(). g_date_clear() делает дату недопустимой но нормальной. Недопустимая дата не представляет день, она "пустая". Дата становится допустимой после того, как вы установите её в Юлианский день или день, месяц и год.

guint julian_days : 32; Юлианское представление даты
guint julian : 1; этот бит устанавливается если julian_days допустим
guint dmy : 1; это устанавливается если day, month и year являются допустимыми
guint day : 6; день в преставлении даты в виде день-месяц-год, как число между 1 и 31
guint month : 4; месяц в представлении даты в виде день-месяц-год, как число между 1 и 12
guint year : 16; год в представлении даты как день-месяц-год

GTime

typedef gint32  GTime;

Просто замена для time_t. Она устарела так как не является эквивалентом для time_t на 64-битных платформах с 64-битной time_t. Несвязана с GTimer.

Помните что GTime определяется всегда как 32bit целочисленное, в отличие от time_t которая может быть 64bit на некоторых системах. Поэтому, GTime переполнится в 2038 году, и вы не сможете использовать адрес переменной GTime как аргумент для UNIX функции time(). Вместо этого сделайте следующее:

time_t ttime;
GTime gtime;

time (&ttime);
gtime = (GTime)ttime;


enum GDateDMY

typedef enum
{
  G_DATE_DAY   = 0,
  G_DATE_MONTH = 1,
  G_DATE_YEAR  = 2
} GDateDMY;

Это перечисление не используется в API, но может быть полезно если вам необходимо маркировать номер как день, месяц, или год.

G_DATE_DAY день
G_DATE_MONTH месяц
G_DATE_YEAR год

GDateDay

typedef guint8  GDateDay;   /* day of the month */

Целочисленное представляющее день в месяце; между 1 и 31. G_DATE_BAD_DAY представляет недопустимый день в месяце.


enum GDateMonth

typedef enum
{
  G_DATE_BAD_MONTH = 0,
  G_DATE_JANUARY   = 1,
  G_DATE_FEBRUARY  = 2,
  G_DATE_MARCH     = 3,
  G_DATE_APRIL     = 4,
  G_DATE_MAY       = 5,
  G_DATE_JUNE      = 6,
  G_DATE_JULY      = 7,
  G_DATE_AUGUST    = 8,
  G_DATE_SEPTEMBER = 9,
  G_DATE_OCTOBER   = 10,
  G_DATE_NOVEMBER  = 11,
  G_DATE_DECEMBER  = 12
} GDateMonth;

Перечисление представляющее месяц; значениями являются G_DATE_JANUARY, G_DATE_FEBRUARY, и т.д.. G_DATE_BAD_MONTH представляет недопустимое значение.

G_DATE_BAD_MONTH недопустимое значение.
G_DATE_JANUARY Январь (January).
G_DATE_FEBRUARY Февраль (February).
G_DATE_MARCH Март (March).
G_DATE_APRIL Апрель (April).
G_DATE_MAY Май (May).
G_DATE_JUNE Июнь (June).
G_DATE_JULY Июль (July).
G_DATE_AUGUST Август (August).
G_DATE_SEPTEMBER Сентябрь (September).
G_DATE_OCTOBER Октябрь (October).
G_DATE_NOVEMBER Ноябрь (November).
G_DATE_DECEMBER Декабрь (December).

GDateYear

typedef guint16 GDateYear;

Целочисленное представляющее год; G_DATE_BAD_YEAR представляет недопустимое значение. Год должен быть 1 или больше; отрицательное значение недопустимо. Год представляется четырьмя цифрами.


enum GDateWeekday

typedef enum
{
  G_DATE_BAD_WEEKDAY  = 0,
  G_DATE_MONDAY       = 1,
  G_DATE_TUESDAY      = 2,
  G_DATE_WEDNESDAY    = 3,
  G_DATE_THURSDAY     = 4,
  G_DATE_FRIDAY       = 5,
  G_DATE_SATURDAY     = 6,
  G_DATE_SUNDAY       = 7
} GDateWeekday;

Перечисление представляющее день в неделе; G_DATE_MONDAY, G_DATE_TUESDAY, и т.д.. G_DATE_BAD_WEEKDAY недопустимый день недели.

G_DATE_BAD_WEEKDAY недопустимое значение.
G_DATE_MONDAY Понедельник (Monday).
G_DATE_TUESDAY Вторник (Tuesday).
G_DATE_WEDNESDAY Среда (Wednesday).
G_DATE_THURSDAY Четверг (Thursday).
G_DATE_FRIDAY Пятница (Friday).
G_DATE_SATURDAY Суббота (Saturday).
G_DATE_SUNDAY Воскресенье (Sunday).

G_DATE_BAD_DAY

#define G_DATE_BAD_DAY    0U

Представляет недопустимую GDateDay.


G_DATE_BAD_JULIAN

#define G_DATE_BAD_JULIAN 0U

Представляет недопустимый номер дня в Юлианском представлении.


G_DATE_BAD_YEAR

#define G_DATE_BAD_YEAR   0U

Представляет недопустимый год.


g_date_new ()

GDate*      g_date_new                      (void);

Распределяет GDate и инициализирует её до нормального сотсояния. Новая дата будет очищена (как если бы вы вызвали g_date_clear()) но недопустима (она не будет представлять существующий день). Возвращаемое значение освобождается с помощью g_date_free().

Возвращает : вновь распределённая GDate.

g_date_new_dmy ()

GDate*      g_date_new_dmy                  (GDateDay day,
                                             GDateMonth month,
                                             GDateYear year);

Аналогична g_date_new(), но также устанавливает значение даты. Допустим вы помещаете в тройку день-месяц-год существующий день, тогда возвращаемая дата будет допустимой.

day : день месяца.
month : месяц в году.
year : год
Возвращает : вновь распределённая GDate инициализированная с помощью дня, месяца и года.

g_date_new_julian ()

GDate*      g_date_new_julian               (guint32 julian_day);

Аналогична g_date_new(), но так же устанавливает значение даты. Допустим вы поместили допустимый Юлианский номер дня (больше чем 0, меньше чем разумно большое число), возвращаемая дата будет допустимой.

julian_day : день начиная с 1 Января 1 Года (January 1, Year 1).
Возвращает : вновь распределённая GDate инициализированная julian_day.

g_date_clear ()

void        g_date_clear                    (GDate *date,
                                             guint n_dates);

Инициализирует одну или больше структур GDate до нормального, но недопустимого состояния. Очищенные даты не будут представлять существующие даты, но не будут содержать мусор. Полезно для инициализации дат объявленных в стеке. Допустимость может быть проверена с помощью g_date_valid().

date : указатель на одну или более дат для очистки.
n_dates : количество дат для очистки.

g_date_free ()

void        g_date_free                     (GDate *date);

Освобождает GDate возвращаемую из g_date_new().

date : GDate.

g_date_set_day ()

void        g_date_set_day                  (GDate *date,
                                             GDateDay day);

Устанавливает день месяца для GDate. Если результат тройки день-месяц-год недопустим, дата будет недопустимой.

date : GDate.
day : день для установки.

g_date_set_month ()

void        g_date_set_month                (GDate *date,
                                             GDateMonth month);

Устанавливает месяц в году для GDate. Если результат тройки день-месяц-год недопустим, дата будет недопустимой.

date : GDate.
month : месяц для установки.

g_date_set_year ()

void        g_date_set_year                 (GDate *date,
                                             GDateYear year);

Устанавливает год для GDate. Если результат тройки день-месяц-год недопустим, дата будет недопустимой.

date : GDate.
year : год для установки.

g_date_set_dmy ()

void        g_date_set_dmy                  (GDate *date,
                                             GDateDay day,
                                             GDateMonth month,
                                             GDateYear y);

Устанавливает значение GDate из дня, месяца и года. Тройка день-месяц-год должна быть допустимой; если вы не уверены в этом, вызовите g_date_valid_dmy() для проверки перед установкой.

date : GDate.
day : день.
month : месяц.
y : год.

g_date_set_julian ()

void        g_date_set_julian               (GDate *date,
                                             guint32 julian_date);

Устанавливает значение GDate от Юлианского номера дня.

date : GDate.
julian_date : Юлианский номер дня (день начиная с 1 Января 1 Года).

g_date_set_time ()

void        g_date_set_time                 (GDate *date,
                                             GTime time_);

Внимание

g_date_set_time устарела и не должна использоваться во вновь создаваемом коде.

Устанавливает значение даты из значения GTime.

Устаревшее:2.10: Вместо неё используйте g_date_set_time_t().

date : GDate.
time_ : GTime значение для установки.

g_date_set_time_t ()

void        g_date_set_time_t               (GDate *date,
                                             time_t timet);

Устанавливает значение даты из значения time_t.

Для установки значения даты текущего дня, вы должны написать:

 
 g_date_set_time_t (date, time (NULL)); 

date : GDate
timet : time_t значение для установки

Начиная с версии 2.10


g_date_set_time_val ()

void        g_date_set_time_val             (GDate *date,
                                             GTimeVal *timeval);

Устанавливает значение даты из значения GTimeVal. Помните что tv_usec член игнорируется, потомучто GDate не может использовать дополнительную точность.

date : GDate
timeval : GTimeVal значение для установки

Начиная с версии 2.10


g_date_set_parse ()

void        g_date_set_parse                (GDate *date,
                                             const gchar *str);

Анализирует строку пользовательского ввода str, и пытается выяснить какую дату она представляет, принимая во внимание текущую локаль. Если строка полностью проанализирована, дата будет доступна после вызова. Иначе, она будет недоступна. С помощью g_date_valid() вы должны проверить выполнен ли анализ строки успешно.

Эта функция не является соответствующей для форматированных файлов и т.п.; она не очень точна и точность её поведения изменяется в зависимости от локали. Она предназначена для эвристической подпрограммы которая предполагает что пользователь подразумевает данной строкой (в этом смысле она работает вполне прилично).

date : GDate для заполнения.
str : строка для анализа.

g_date_add_days ()

void        g_date_add_days                 (GDate *date,
                                             guint n_days);

Увеличивает дату некоторым количеством дней. Для перемещения понедельно, добавьте weeks*7 days. Дата должна быть допустимой.

date : GDate для увеличения.
n_days : количество дней для перемещения даты вперёд.

g_date_subtract_days ()

void        g_date_subtract_days            (GDate *date,
                                             guint n_days);

Перемещение даты на некоторое количество дней в прошлое. Для понедельного перемещения, просто используйте weeks*7 days. Дата должна быть допустимой.

date : GDate для уменьшения.
n_days : количество дней для перемещения.

g_date_add_months ()

void        g_date_add_months               (GDate *date,
                                             guint n_months);

Увеличивает дату на некоторое количество месяцев. Если день месяца больше чем 28, эта подпрограмма может изменить день месяца (потомучто месяц назначения может не иметь такого текущего дня). Дата должна быть допустимой.

date : GDate для увеличения.
n_months : количество месяцев для перемещения вперёд.

g_date_subtract_months ()

void        g_date_subtract_months          (GDate *date,
                                             guint n_months);

Перемещает дату на некоторое количество месяцев в прошлое. Если текущий день месяца не существует в месяце назначения, день месяца может быть изменён. Дата должна быть допустимой.

date : GDate для уменьшения.
n_months : количество месяцев для перемещения.

g_date_add_years ()

void        g_date_add_years                (GDate *date,
                                             guint n_years);

Увеличивает дату некоторым количеством лет. Если датой является 29 Февраля, а год назначения не является високосным, дата будет изменена на 28 Февраля. Дата должна быть допустимой.

date : GDate для увеличения.
n_years : количество лет для перемещения вперёд.

g_date_subtract_years ()

void        g_date_subtract_years           (GDate *date,
                                             guint n_years);

Перемещает дату на некоторое число лет в прощлое. Если текущий день не существует в году назначения (то есть это 29 Февраля и вы перемещаетесь не в високосный год) то день изменяется на 28 Февраля. Дата должна быть допустимой.

date : GDate для уменьшения.
n_years : число лет для перемещения.

g_date_days_between ()

gint        g_date_days_between             (const GDate *date1,
                                             const GDate *date2);

Расчитывает число дней между двумя датами. Если date2 находится перед date1, возвращается негативное значение. Обе даты должны быть допустимыми.

date1 : первая дата.
date2 : вторая дата.
Возвращает : количество дней между date1 и date2.

g_date_compare ()

gint        g_date_compare                  (const GDate *lhs,
                                             const GDate *rhs);

qsort()-style функции для сравнения дат. Обе даты должны быть допустимыми.

lhs : первая дата для сравнения.
rhs : вторая дата для сравнения.
Возвращает : 0 если даты равны, меньше нуля если lhs меньше чем rhs, больше нуля если lhs больше чем rhs.

g_date_clamp ()

void        g_date_clamp                    (GDate *date,
                                             const GDate *min_date,
                                             const GDate *max_date);

Если date находится перед min_date, устанавливает date как эквивалент min_date. Если date расположена после max_date, устанавливает date как эквивалент max_date. Любой параметр min_date и max_date может быть NULL. Все не-NULL даты должны быть допустимыми.

date : GDate для сопоставления.
min_date : минимально применимое значение для date.
max_date : максимально применимое значение для date.

g_date_order ()

void        g_date_order                    (GDate *date1,
                                             GDate *date2);

Проверяет меньше ли date1 или эквивалентна date2, и сбрасывает значение если это не так.

date1 : первая дата.
date2 : вторая дата.

g_date_get_day ()

GDateDay    g_date_get_day                  (const GDate *date);

Возвращает день месяца. Дата должна быть допустимой.

date : GDate для извлечения дня месяца.
Возвращает : день месяца.

g_date_get_month ()

GDateMonth  g_date_get_month                (const GDate *date);

Возвращает месяц в году. Дата должна быть допустимой.

date : GDate для извлечения месяца.
Возвращает : месяц в году как GDateMonth.

g_date_get_year ()

GDateYear   g_date_get_year                 (const GDate *date);

Возвращает год из GDate. Дата должна быть допустимой.

date : GDate.
Возвращает : год на который выпадает дата.

g_date_get_julian ()

guint32     g_date_get_julian               (const GDate *date);

Возвращает Юлианский день или "серийный номер" из GDate. Юлианский день - это просто номер дня начиная с 1 Января 1 Года; то есть, 1 Января 1 Года является 1 Юлианским днём; 2 Января 2 Года является 2 Юлианским днём, и т.д.. Дата должна быть допустимой.

date : GDate для извлечения Юлианского дня.
Возвращает : Юлианский день.

g_date_get_weekday ()

GDateWeekday g_date_get_weekday             (const GDate *date);

Возвращает день недели для GDate. Дата должна быть допустимой.

date : GDate.
Возвращает : день недели как GDateWeekday.

g_date_get_day_of_year ()

guint       g_date_get_day_of_year          (const GDate *date);

Возвращаемый день в году, где 1 Января является первым днём года. Дата должна быть допустимой.

date : GDate для извлечения дня в году.
Возвращает : день в году.

g_date_get_days_in_month ()

guint8      g_date_get_days_in_month        (GDateMonth month,
                                             GDateYear year);

Возвращает число дней в месяце, принимая во внимание високосные годы.

month : месяц.
year : год.
Возвращает : количество дней в month в течении year.

g_date_is_first_of_month ()

gboolean    g_date_is_first_of_month        (const GDate *date);

Возвращает TRUE если дата является первым днём месяца. Дата должна быть допустимой.

date : GDate для проверки.
Возвращает : TRUE если дата является первым днём месяца.

g_date_is_last_of_month ()

gboolean    g_date_is_last_of_month         (const GDate *date);

Возвращает TRUE если дата является последним днём месяца. Дата должна быть допустимой.

date : GDate для проверки.
Возвращает : TRUE если дата является последним днём месяца.

g_date_is_leap_year ()

gboolean    g_date_is_leap_year             (GDateYear year);

Возвращает TRUE если год является високосным.

year : год для проверки.
Возвращает : TRUE если год високосный.

g_date_get_monday_week_of_year ()

guint       g_date_get_monday_week_of_year  (const GDate *date);

Возвращает неделю в году, где недели начинаются с понедельника. Если дата перед первым понедельником в году, возвращается 0. Дата должна быть допустимой.

date : GDate.
Возвращает : неделя в году.

g_date_get_monday_weeks_in_year ()

guint8      g_date_get_monday_weeks_in_year (GDateYear year);

Возвращает количество недель в году, где недели начинаются с понедельника. Будет либо 52 либо 53. Дата должна быть допустимой. (Года всегда имеют 52 периода по 7-дней, плюс 1 или 2 дополнительных дня в зависимости от того, является ли год високосным. Эта функция в основном сообщает сколько понедельников находится в году, то есть 53 понедельника будет если один из дополнительных дней окажется понедельником.)

year : год.
Возвращает : количество понедельников в году.

g_date_get_sunday_week_of_year ()

guint       g_date_get_sunday_week_of_year  (const GDate *date);

Возвращает неделю года на которую выпадает дата, если недели начинаются с воскресенья. Дата должна быть допустимой. Может вернуть 0 если день находится перед первым воскресеньем в году.

date : GDate.
Возвращает : номер недели.

g_date_get_sunday_weeks_in_year ()

guint8      g_date_get_sunday_weeks_in_year (GDateYear year);

Возвращает количество недель в году, где недели начинаются с воскресенья. Будет либо 52 либо 53. Дата должна быть допустимой. (Годы всегда имеют 52 периода по 7-дней, плюс 1 или 2 дополнительных дня в зависимости от того, является ли год високосным. Эта функция в основном сообщает вам сколько воскресений в году, то есть является ли 53 воскресенье дополнительным днём года.)

year : год для подсчёта недель.
Возвращает : количество недель.

g_date_get_iso8601_week_of_year ()

guint       g_date_get_iso8601_week_of_year (const GDate *date);

Возвращает неделю года, где недели интерпретируются согласно ISO 8601.

date : допустимая GDate
Возвращает : ISO 8601 число недель в году.

Начиная с версии 2.6


g_date_strftime ()

gsize       g_date_strftime                 (gchar *s,
                                             gsize slen,
                                             const gchar *format,
                                             const GDate *date);

Генерирует печатное представление даты, локале-зависимым способом. Работает просто как платформенная C библиотечная функция strftime(), но принимает только дата-зависимые форматы; время-зависимые форматы выдают неопределённый результат. Дата должна быть допустимой. В отличие от strftime() (которая использует локальную кодировку), эта функция работает со строками в кодировке UTF-8 и сохраняет результат в кодировке UTF-8.

Эта функция не обеспечивает никаких дополнительных спецификаторов конвертирования для платформенной реализации библиотеки C. Например, не ждите что использование g_date_strftime() сделает F обеспечив C99 strftime() работая на Windows где библиотека C скомпилирована только для C89.

s : буфер назначения.
slen : размер буфера.
format : строка формата.
date : допустимая GDate.
Возвращает : количество символов записанных в буфер, или 0 если буфер слишком маленький.

g_date_to_struct_tm ()

void        g_date_to_struct_tm             (const GDate *date,
                                             struct tm *tm);

Заполняет дата-зависимый бит в struct tm используя значение date. Инициализирует non-date пары с чем то нормальным но бессмысленным.

date : GDate для установки struct tm.
tm : struct tm для заполнения.

g_date_valid ()

gboolean    g_date_valid                    (const GDate *date);

Возвращает TRUE если GDate представляет существующий день. Дата не должна содержать мусор; она должна быть инициализирована с помощью g_date_clear() если она не была распределена одним из вариантов g_date_new().

date : GDate для проверки.
Возвращает : является ли дата допустимой.

g_date_valid_day ()

gboolean    g_date_valid_day                (GDateDay day);

Возвращает TRUE если день месяца допустим (день допустим если он находится в промежутке чисел от 1 до 31 включительно).

day : день для проверки.
Возвращает : TRUE если день допустим.

g_date_valid_month ()

gboolean    g_date_valid_month              (GDateMonth month);

Возвращает TRUE если значение месяца допустимо. Только 12 значений в перечислении GDateMonth являются допустимыми.

month : месяц.
Возвращает : TRUE если месяц допустим.

g_date_valid_year ()

gboolean    g_date_valid_year               (GDateYear year);

Возвращает TRUE если год допустим. Допустимым является год только больше 0, однако есть 16-битный предел того что может понять GDate.

year : год.
Возвращает : TRUE если год допустим.

g_date_valid_dmy ()

gboolean    g_date_valid_dmy                (GDateDay day,
                                             GDateMonth month,
                                             GDateYear year);

Возвращает TRUE если форма триплёта день-месяц-год допустима, существует понятный день в диапазоне дней GDate (1 год или больше, но не больше нескольких тысяч лет в будущее).

day : день.
month : месяц.
year : год.
Возвращает : TRUE если дата допустима.

g_date_valid_julian ()

gboolean    g_date_valid_julian             (guint32 julian_date);

Возвращает TRUE ели Юлианский день допустим. Число больше нуля в основном является допустимым Юлианским днём, однако есть 32-битный предел.

julian_date : Юлианский день для проверки.
Возвращает : TRUE если Юлианский день допустим.

g_date_valid_weekday ()

gboolean    g_date_valid_weekday            (GDateWeekday weekday);

Возвращает TRUE если день недели допустим. Только 7 значений в перечислении GDateWeekday являются допустимыми.

weekday : день недели.
Возвращает : TRUE если день недели допустим.

Double-ended Queues

Double-ended Queues — Двусторонняя очередь структур данных.

Краткое описание


#include <glib.h>


            GQueue;
GQueue*     g_queue_new                     (void);
void        g_queue_free                    (GQueue *queue);
gboolean    g_queue_is_empty                (GQueue *queue);
guint       g_queue_get_length              (GQueue *queue);
void        g_queue_reverse                 (GQueue *queue);
GQueue*     g_queue_copy                    (GQueue *queue);
void        g_queue_foreach                 (GQueue *queue,
                                             GFunc func,
                                             gpointer user_data);
GList*      g_queue_find                    (GQueue *queue,
                                             gconstpointer data);
GList*      g_queue_find_custom             (GQueue *queue,
                                             gconstpointer data,
                                             GCompareFunc func);
void        g_queue_sort                    (GQueue *queue,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);
void        g_queue_push_head               (GQueue *queue,
                                             gpointer data);
void        g_queue_push_tail               (GQueue *queue,
                                             gpointer data);
void        g_queue_push_nth                (GQueue *queue,
                                             gpointer data,
                                             gint n);
gpointer    g_queue_pop_head                (GQueue *queue);
gpointer    g_queue_pop_tail                (GQueue *queue);
gpointer    g_queue_pop_nth                 (GQueue *queue,
                                             guint n);
gpointer    g_queue_peek_head               (GQueue *queue);
gpointer    g_queue_peek_tail               (GQueue *queue);
gpointer    g_queue_peek_nth                (GQueue *queue,
                                             guint n);
gint        g_queue_index                   (GQueue *queue,
                                             gconstpointer data);
void        g_queue_remove                  (GQueue *queue,
                                             gconstpointer data);
void        g_queue_remove_all              (GQueue *queue,
                                             gconstpointer data);
void        g_queue_insert_before           (GQueue *queue,
                                             GList *sibling,
                                             gpointer data);
void        g_queue_insert_after            (GQueue *queue,
                                             GList *sibling,
                                             gpointer data);
void        g_queue_insert_sorted           (GQueue *queue,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);
void        g_queue_push_head_link          (GQueue *queue,
                                             GList *link_);
void        g_queue_push_tail_link          (GQueue *queue,
                                             GList *link_);
void        g_queue_push_nth_link           (GQueue *queue,
                                             gint n,
                                             GList *link_);
GList*      g_queue_pop_head_link           (GQueue *queue);
GList*      g_queue_pop_tail_link           (GQueue *queue);
GList*      g_queue_pop_nth_link            (GQueue *queue,
                                             guint n);
GList*      g_queue_peek_head_link          (GQueue *queue);
GList*      g_queue_peek_tail_link          (GQueue *queue);
GList*      g_queue_peek_nth_link           (GQueue *queue,
                                             guint n);
gint        g_queue_link_index              (GQueue *queue,
                                             GList *link_);
void        g_queue_unlink                  (GQueue *queue,
                                             GList *link_);
void        g_queue_delete_link             (GQueue *queue,
                                             GList *link_);

Описание

Структура GQueue и связанные с ней функции обеспечивают стандартную очередь структур данных. Внутренне, GQueue использует для хранения элементов те же структуры что и GList.

Данные содержащиеся в каждом элементе могут быть либо целочисленными значениями, используя Type Conversion Macros, или просто указатели на любой тип данных.

Для создания новой GQueue, используйте g_queue_new().

Для добавления элементов, используйте g_queue_push_head(), g_queue_push_head_link(), g_queue_push_tail() and g_queue_push_tail_link().

Для удаления элементов, используйте g_queue_pop_head() и g_queue_pop_tail().

Для освобождения элементов очереди, используйте g_queue_free().

Детали

GQueue

typedef struct {
  GList *head;
  GList *tail;
  guint  length;
} GQueue;

Содержит общедоступные поля Queue.

GList *head; указатель на первый элемент в очереди.
GList *tail; указатель на последний элемент в очереди.
guint length; количество элементов в очереди.

g_queue_new ()

GQueue*     g_queue_new                     (void);

Создаёт новую GQueue.

Возвращает : новая GQueue.

g_queue_free ()

void        g_queue_free                    (GQueue *queue);

Освобождает память распределённую для GQueue.

queue : GQueue.

g_queue_is_empty ()

gboolean    g_queue_is_empty                (GQueue *queue);

Возвращает TRUE очередь пустая.

queue : GQueue.
Возвращает : TRUE если очередь пустая.

g_queue_get_length ()

guint       g_queue_get_length              (GQueue *queue);

Возвращает количество элементов в queue.

queue : GQueue
Возвращает : Количество элементов в queue.

Начиная с версии 2.4


g_queue_reverse ()

void        g_queue_reverse                 (GQueue *queue);

Переворачивает направление элементов в queue.

queue : GQueue

Начиная с версии 2.4


g_queue_copy ()

GQueue*     g_queue_copy                    (GQueue *queue);

Копирует queue. Помните что это поверхностная копия. Если очередь содержит указатели на данные, то указатели копируются, а фактические данные нет.

queue : GQueue
Возвращает : копия queue

Начиная с версии 2.4


g_queue_foreach ()

void        g_queue_foreach                 (GQueue *queue,
                                             GFunc func,
                                             gpointer user_data);

Вызывает функцию func для каждого элемента в очереди помещая user_data в функцию.

queue : GQueue
func : функция вызываемая для каждого элемента данных
user_data : пользовательские данные помещаемые в func

Начиная с версии 2.4


g_queue_find ()

GList*      g_queue_find                    (GQueue *queue,
                                             gconstpointer data);

Находит первую связь в queue которая содержит data.

queue : GQueue
data : данные для поиска
Возвращает : Первая связь в queue которая содержит data.

Начиная с версии 2.4


g_queue_find_custom ()

GList*      g_queue_find_custom             (GQueue *queue,
                                             gconstpointer data,
                                             GCompareFunc func);

Находит элемент в GQueue, используя полученную функцию для поиска желаемого элемента. Она передвигается через очередь, вызывая полученную функцию которая должна вернуть 0 когда желаемый элемент найден. Функция принимает два аргумента gconstpointer, элементы данных GQueue как первый аргумент и полученные пользовательские данные как второй аргумент.

queue : GQueue
data : пользовательские данные помещаемые в func
func : GCompareFunc вызываемая для каждого элемента. Она должна вернуть 0 когда желаемый элемент найден.
Возвращает : Найденный элемент, или NULL если не найден.

Начиная с версии 2.4


g_queue_sort ()

void        g_queue_sort                    (GQueue *queue,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

Сортирует queue используя compare_func.

queue : GQueue
compare_func : GCompareDataFunc используемая для сортировки queue. В эту функцию помещаются два элемента очереди и она должна вернуть 0 если они равны, отрицательное значение если первый располагается перед вторым, а положительное если второй располагается перед первым.
user_data : пользовательские данные помещаемые в compare_func

Начиная с версии 2.4


g_queue_push_head ()

void        g_queue_push_head               (GQueue *queue,
                                             gpointer data);

Добавляет новый элемент первым в очередь.

queue : GQueue.
data : данные для нового элемента.

g_queue_push_tail ()

void        g_queue_push_tail               (GQueue *queue,
                                             gpointer data);

Добавляет новый элемент в конец очереди.

queue : GQueue.
data : данные для нового элемента.

g_queue_push_nth ()

void        g_queue_push_nth                (GQueue *queue,
                                             gpointer data,
                                             gint n);

Вставляет новый элемент в queue в указанную позицию.

queue : GQueue
data : данные для нового элемента
n : позиция расположения нового элемента. Если n отрицательное или больше чем число элементов в queue, элемент добавляемый в конец очереди.

Начиная с версии 2.4


g_queue_pop_head ()

gpointer    g_queue_pop_head                (GQueue *queue);

Удаляет первый элемент в очереди.

queue : GQueue.
Возвращает : данные первого элемента в очереди, или NULL если очередь пустая.

g_queue_pop_tail ()

gpointer    g_queue_pop_tail                (GQueue *queue);

Удаляет последний элемент из очереди.

queue : GQueue.
Возвращает : данные последнего элемента в очереди, или NULL если очередь пустая.

g_queue_pop_nth ()

gpointer    g_queue_pop_nth                 (GQueue *queue,
                                             guint n);

Удаляет n элемент в queue.

queue : GQueue
n : позиция элемента.
Возвращает : данные элемента, или NULL если n выходит за пределы queue.

Начиная с версии 2.4


g_queue_peek_head ()

gpointer    g_queue_peek_head               (GQueue *queue);

Возвращает первый элемент в queue.

queue : GQueue.
Возвращает : данные первого элемента в очереди, или NULL если очередь пустая.

g_queue_peek_tail ()

gpointer    g_queue_peek_tail               (GQueue *queue);

Возвращает последний элемент в очереди.

queue : GQueue.
Возвращает : данные последнего элемента в очереди, или NULL если очередь пустая.

g_queue_peek_nth ()

gpointer    g_queue_peek_nth                (GQueue *queue,
                                             guint n);

Возвращает n элемент в queue.

queue : GQueue
n : позиция элемента.
Возвращает : Данные для n элемента в queue, или NULL если n выходит за пределы queue.

Начиная с версии 2.4


g_queue_index ()

gint        g_queue_index                   (GQueue *queue,
                                             gconstpointer data);

Возвращает позицию первого элемента в queue который содержит data.

queue : GQueue
data : данные для поиска.
Возвращает : Позиция первого элемента в queue который содержит data, или -1 если нет элемента в queue содержащего data.

Начиная с версии 2.4


g_queue_remove ()

void        g_queue_remove                  (GQueue *queue,
                                             gconstpointer data);

Удаляет первый элемент в queue который содержит data.

queue : GQueue
data : удаляемые данные.

Начиная с версии 2.4


g_queue_remove_all ()

void        g_queue_remove_all              (GQueue *queue,
                                             gconstpointer data);

Удаляет все элементы в queue которые содержат data.

queue : GQueue
data : данные для удаления

Начиная с версии 2.4


g_queue_insert_before ()

void        g_queue_insert_before           (GQueue *queue,
                                             GList *sibling,
                                             gpointer data);

Вставляет data в queue перед sibling.

sibling должен быть частью queue.

queue : GQueue
sibling : GList узел, который должен быть частью queue
data : данные для вставки

Начиная с версии 2.4


g_queue_insert_after ()

void        g_queue_insert_after            (GQueue *queue,
                                             GList *sibling,
                                             gpointer data);

Вставляет data в queue после sibling

sibling должен быть частью queue

queue : GQueue
sibling : GList узел, который должен быть частью queue
data : вставляемые данные

Начиная с версии 2.4


g_queue_insert_sorted ()

void        g_queue_insert_sorted           (GQueue *queue,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Вставляет data в queue используя func для определения новой позиции.

queue : GQueue
data : вставляемые данные
func : GCompareDataFunc используется для сравнения элементов в очереди. Она вызывается с двумя элементами, queue и user_data. Должна вернуть 0 если элементы равны, отрицательное значение если первый элемент располагается перед вторым, а положительное значение если второй элемент располагается перед первым.
user_data : пользовательские данные помещаемые в func.

Начиная с версии 2.4


g_queue_push_head_link ()

void        g_queue_push_head_link          (GQueue *queue,
                                             GList *link_);

Добавляет новый элемент первым в очередь.

queue : GQueue.
link_ : одиночный элемент GList, не список с множеством элементов.

g_queue_push_tail_link ()

void        g_queue_push_tail_link          (GQueue *queue,
                                             GList *link_);

Добавляет новый элемент в конец очереди.

queue : GQueue.
link_ : одиночный элемент GList, не список с множеством элементов.

g_queue_push_nth_link ()

void        g_queue_push_nth_link           (GQueue *queue,
                                             gint n,
                                             GList *link_);

Вставляет link в полученную позицию queue.

queue : GQueue
n : позиция для вставки узла. Если отрицательное или больше чем количество элементов в queue, узел добавляется в конец queue.
link_ : узел добавляемый в queue

Начиная с версии 2.4


g_queue_pop_head_link ()

GList*      g_queue_pop_head_link           (GQueue *queue);

Удаляет первый элемент в очереди.

queue : GQueue.
Возвращает : Первый GList элемент в очереди, или NULL если очередь пустая.

g_queue_pop_tail_link ()

GList*      g_queue_pop_tail_link           (GQueue *queue);

Удаляет последний элемент в очереди.

queue : GQueue.
Возвращает : Элемент GList в конце очереди, или NULL если очередь пустая.

g_queue_pop_nth_link ()

GList*      g_queue_pop_nth_link            (GQueue *queue,
                                             guint n);

Удаляет и возвращает узел в полученной позиции.

queue : GQueue
n : позиция узла
Возвращает : n-ный узел, или NULL если n выходит за пределы queue.

Начиная с версии 2.4


g_queue_peek_head_link ()

GList*      g_queue_peek_head_link          (GQueue *queue);

Возвращает первый узел в queue

queue : GQueue
Возвращает : первый узел в queue, или NULL если queue пустая

Начиная с версии 2.4


g_queue_peek_tail_link ()

GList*      g_queue_peek_tail_link          (GQueue *queue);

Возвращает последний узел queue.

queue : GQueue
Возвращает : последний узел в queue, или NULL если queue пустая

Начиная с версии 2.4


g_queue_peek_nth_link ()

GList*      g_queue_peek_nth_link           (GQueue *queue,
                                             guint n);

Возвращает узел из полученной позиции

queue : GQueue
n : позиция узла
Возвращает : узел из n-ной позиции, или NULL если n выходит за пределы очереди

Начиная с версии 2.4


g_queue_link_index ()

gint        g_queue_link_index              (GQueue *queue,
                                             GList *link_);

Возвращает позицию link_ в queue.

queue : Gqueue
link_ : элемент GList
Возвращает : позиция link_, или -1 если узел не часть queue

Начиная с версии 2.4


g_queue_unlink ()

void        g_queue_unlink                  (GQueue *queue,
                                             GList *link_);

Сбрасывает link_ так чтобы он не был больше частью queue. Узел не освобождается.

link_ должен быть частью queue,

queue : GQueue
link_ : GList элемент который должен быть частью queue

Начиная с версии 2.4


g_queue_delete_link ()

void        g_queue_delete_link             (GQueue *queue,
                                             GList *link_);

Удаляет link_ из queue и освобождает его.

link_ должен быть частью queue.

queue : GQueue
link_ : GList элемент который должен быть частью queue

Начиная с версии 2.4


Doubly-Linked Lists

Doubly-Linked Lists — Связанные списки содержащие целочисленные значения или указатели на данные, с возможностью выполнения итерации по списку в обоих направлениях.

Краткое описание


#include <glib.h>


            GList;

GList*      g_list_append                   (GList *list,
                                             gpointer data);
GList*      g_list_prepend                  (GList *list,
                                             gpointer data);
GList*      g_list_insert                   (GList *list,
                                             gpointer data,
                                             gint position);
GList*      g_list_insert_before            (GList *list,
                                             GList *sibling,
                                             gpointer data);
GList*      g_list_insert_sorted            (GList *list,
                                             gpointer data,
                                             GCompareFunc func);
GList*      g_list_remove                   (GList *list,
                                             gconstpointer data);
GList*      g_list_remove_link              (GList *list,
                                             GList *llink);
GList*      g_list_delete_link              (GList *list,
                                             GList *link_);
GList*      g_list_remove_all               (GList *list,
                                             gconstpointer data);
void        g_list_free                     (GList *list);

GList*      g_list_alloc                    (void);
void        g_list_free_1                   (GList *list);
#define     g_list_free1

guint       g_list_length                   (GList *list);
GList*      g_list_copy                     (GList *list);
GList*      g_list_reverse                  (GList *list);
GList*      g_list_sort                     (GList *list,
                                             GCompareFunc compare_func);
gint        (*GCompareFunc)                 (gconstpointer a,
                                             gconstpointer b);
GList*      g_list_insert_sorted_with_data  (GList *list,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);
GList*      g_list_sort_with_data           (GList *list,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);
gint        (*GCompareDataFunc)             (gconstpointer a,
                                             gconstpointer b,
                                             gpointer user_data);
GList*      g_list_concat                   (GList *list1,
                                             GList *list2);
void        g_list_foreach                  (GList *list,
                                             GFunc func,
                                             gpointer user_data);
void        (*GFunc)                        (gpointer data,
                                             gpointer user_data);

GList*      g_list_first                    (GList *list);
GList*      g_list_last                     (GList *list);
#define     g_list_previous                 (list)
#define     g_list_next                     (list)
GList*      g_list_nth                      (GList *list,
                                             guint n);
gpointer    g_list_nth_data                 (GList *list,
                                             guint n);
GList*      g_list_nth_prev                 (GList *list,
                                             guint n);

GList*      g_list_find                     (GList *list,
                                             gconstpointer data);
GList*      g_list_find_custom              (GList *list,
                                             gconstpointer data,
                                             GCompareFunc func);
gint        g_list_position                 (GList *list,
                                             GList *llink);
gint        g_list_index                    (GList *list,
                                             gconstpointer data);

void        g_list_push_allocator           (gpointer allocator);
void        g_list_pop_allocator            (void);

Описание

Структура GList и связанные с ней функции обеспечивают стандартный двусвязный список структур данных.

Каждый элемент в списке содержит часть данных, вместе с указателями которые связаны с предыдущим и следующим элементом списка. Использование этих указателей позволяет элементам перемещаться через список в обоих направлениях (в отличие от односвязных списков, которые позволяют перемещение по списку только вперёд).

Данные содержащиеся в каждом элементе могут быть либо целочисленными значениями, при использовании одного из Type Conversion Macros, либо простыми указателями на любой тип данных.

Список элементов распределяется с помощью slice allocator, что более эффективно чем индивидуальное распределение элементов.

Помите что большинство функций GList предполагают помещение указателя на первый элемент в списке. Функции которые вставляют элементы, возвращают новое начало списка, которое может быть изменено.

Нет функции для создания GList. NULL рассматривается как пустой список, поэтому вы можете просто установить GList* в значение NULL.

Для добавления элементов используйте g_list_append(), g_list_prepend(), g_list_insert() и g_list_insert_sorted().

Для удаления элементов используйте g_list_remove().

Для поиска элементов в списке используйте g_list_first(), g_list_last(), g_list_next(), g_list_previous(), g_list_nth(), g_list_nth_data(), g_list_find() и g_list_find_custom().

Для поиска номера элемента используйте g_list_position() и g_list_index().

Для вызова функции для каждого элемента в списке используйте g_list_foreach().

Для освобождения полей списка используйте g_list_free().

Детали

GList

typedef struct {
  gpointer data;
  GList *next;
  GList *prev;
} GList;

Структура GList используется для каждого элемента двусвязного списка.

gpointer data; содержит элементы данных, которые могут быть указателем на любой вид данных, или любым целочисленным значением используя Type Conversion Macros.
GList *next; содержит ссылку на следующий элемент в списке.
GList *prev; содержит ссылку на предыдущий элемент в списке.

g_list_append ()

GList*      g_list_append                   (GList *list,
                                             gpointer data);

Добавляет новый элемент в конец списка.

Примечание

Возвращаемое значение является новым началом списка, которое может быть изменено, поэтому убедитесь что вы сохранили новое значение.

Примечание

Помните что g_list_append() должен пересечь все поля списка для нахождения конца, это не эффективно при добавлении множества элементов. Основная идиома в исключении неэффективности в том, чтобы приставлять элементы а затем перевернуть список, когда все элементы будут добавлены.

  /* Помните что это инициализирует пустой список. */
  GList *list = NULL, *number_list = NULL;

  /* Это список строк. */
  list = g_list_append (list, "first");
  list = g_list_append (list, "second");

  /* Это список целочисленных. */
  number_list = g_list_append (number_list, GINT_TO_POINTER (27));
  number_list = g_list_append (number_list, GINT_TO_POINTER (14));
list : указатель на GList.
data : данные для нового элемента.
Возвращает : новое начало GList.

g_list_prepend ()

GList*      g_list_prepend                  (GList *list,
                                             gpointer data);

Добавляет новый элемент в начало списка.

Примечание

Возвращаемое значение является новым началом списка, которое может изменится, поэтому убедитесь что вы сохранили новое значение.

  /* Помните что это инициализирует пустой список. */
  GList *list = NULL;
  list = g_list_prepend (list, "last");
  list = g_list_prepend (list, "first");
list : указатель на GList.
data : данные для нового элемента.
Возвращает : новое начало GList.

g_list_insert ()

GList*      g_list_insert                   (GList *list,
                                             gpointer data,
                                             gint position);

Вставляет новый элемент в список в полученную позицию.

list : указатель на GList.
data : данные для нового элемента.
position : позиция для вставки элемента. Если отрицательное, или меньше чем количество элементов в списке, новый элемент добавляется в конец списка.
Возвращает : новое начало GList.

g_list_insert_before ()

GList*      g_list_insert_before            (GList *list,
                                             GList *sibling,
                                             gpointer data);

Вставляет новый элемент в список перед полученной позицией.

list : указатель на GList.
sibling : номер элемента перед которым вставляется новый элемент,или NULL для вставки в конец списка.
data : данные для нового элемента.
Возвращает : новое начало GList.

g_list_insert_sorted ()

GList*      g_list_insert_sorted            (GList *list,
                                             gpointer data,
                                             GCompareFunc func);

Вставляет новый элемент в список, использует полученную функцию сравнения для определения позиции.

list : указатель на GList.
data : данные для нового элемента.
func : функция для сравнения элементов в списке. Она должна возвращать число > 0 если первый параметр расположен после второго в порядке сортировки.
Возвращает : новое начало GList.

g_list_remove ()

GList*      g_list_remove                   (GList *list,
                                             gconstpointer data);

Удаляет элемент из GList. Если два элемента содержат одинаковые данные, удаляется только первый. Если нет элементов содержащих данные, GList не изменяется.

list : GList.
data : данные удаляемого элемента.
Возвращает : новое начало GList.

g_list_remove_link ()

GList*      g_list_remove_link              (GList *list,
                                             GList *llink);

Удаляет элемент из GList, без освобождения элемента. У удалённого элемента ссылки на предыдущий и следующий устанавливаются в NULL, так чтобы он стал списком с единственным элементом.

list : GList.
llink : элемент в GList.
Возвращает : новое начало GList, без элемента.

g_list_delete_link ()

GList*      g_list_delete_link              (GList *list,
                                             GList *link_);

Удаляет узел link_ из list.

list : GList.
link_ : узел для удаления из list.
Возвращает : новый первый элемент list.

g_list_remove_all ()

GList*      g_list_remove_all               (GList *list,
                                             gconstpointer data);

Удаляет все узлы списка с данными равными data. Возвращает новый первый элемент списка. В отличие от g_list_remove(), которая удаляет только первый узел соответствующий полученным данным.

list : GList.
data : удаляемые данные.
Возвращает : новый первый элемент list.

g_list_free ()

void        g_list_free                     (GList *list);

Освобождает всю память используемую GList. Освобождает элементы возвращаемые распределителем слайсов.

Примечание

Если первый элемент содержит динамически-распределённую память, он должен быть освобождён первым.

list : GList.

g_list_alloc ()

GList*      g_list_alloc                    (void);

Распределяет пространство для одного элемента GList. Она вызывается с помощью g_list_append(), g_list_prepend(), g_list_insert() и g_list_insert_sorted() и очень редко используется самостоятельно.

Возвращает : указатель для вновь распределённого элемента GList.

g_list_free_1 ()

void        g_list_free_1                   (GList *list);

Освобождает один элемент GList. Она в основном используется после g_list_remove_link().

list : элемент GList.

g_list_free1

#define     g_list_free1

Другое имя для g_list_free_1().


g_list_length ()

guint       g_list_length                   (GList *list);

Определяет количество элементов в GList.

list : GList.
Возвращает : количество элементов в GList.

g_list_copy ()

GList*      g_list_copy                     (GList *list);

Копирует GList.

Помните что это "пустая" копия. Если список элементов содержит указатели на данные, указатели копируются, а реальные данные нет.

list : GList.
Возвращает : копия list.

g_list_reverse ()

GList*      g_list_reverse                  (GList *list);

Переворачивает GList. Она просто переключает предыдущие и следующие указатели в каждом элементе.

list : GList.
Возвращает : начало перевернутой GList.

g_list_sort ()

GList*      g_list_sort                     (GList *list,
                                             GCompareFunc compare_func);

Сортирует GList используя полученную функцию для сравнения.

list : GList.
compare_func : функция сравнения используемая для сортировки GList. Функция принимает данные из двух элементов GList и должна вернуть 0 если они равны, отрицательное значение если первый элемент помещается перед вторым, или положительное значение если первый элемент помещается после второго.
Возвращает : начало отсортированной GList.

GCompareFunc ()

gint        (*GCompareFunc)                 (gconstpointer a,
                                             gconstpointer b);

Определяет тип сравнивающей функции используемой для сравнения двух значений. Функция должна возвращать отрицательное целочисленное если первое значение расположено перед вторым, 0 если они равны, или положительное целочисленное если первое значение расположено после второго.

a : первое значение.
b : значение для сравнения.
Возвращает : отрицательное значение если a < b; ноль если a = b; положительное значение если a > b.

g_list_insert_sorted_with_data ()

GList*      g_list_insert_sorted_with_data  (GList *list,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Вставляет новый элемент в список, используя полученную функцию сравнения для определения их положения.

list : указатель на GList.
data : данные для нового элемента.
func : функция для сравнения элементов всписке. Она должна вернуть число > 0 если первый параметр расположен после второго параметра в порядке сортировки.
user_data : данные помещаемые в функцию сравнения.
Возвращает : новое начало GList. Начиная с версии 2.10

g_list_sort_with_data ()

GList*      g_list_sort_with_data           (GList *list,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

Похожа на g_list_sort(), но функция сравнения принимает параметр пользовательских данных.

list : GList.
compare_func : функция сравнения.
user_data : пользовательские данные помещаемые в функцию сравнения.
Возвращает : новый первый элемент list.

GCompareDataFunc ()

gint        (*GCompareDataFunc)             (gconstpointer a,
                                             gconstpointer b,
                                             gpointer user_data);

Определяет тип функции сравнения используемой для сравнения двух значений. Функция должна возвращать отрицательное целочисленное если первое значение располагается перед вторым, 0 если они равны, или положительное целочисленное если первое значение располагается после второго.

a : первое значение.
b : значение для сравнения.
user_data : данные помещаемые в функцию сравнения.
Возвращает : отрицательное значение если a < b; ноль если a = b; положительное значение если a > b.

g_list_concat ()

GList*      g_list_concat                   (GList *list1,
                                             GList *list2);

Добавляет второй GList в конец первого GList. Помните что элементы второго GList не копируются. Они используются на прямую.

list1 : GList.
list2 : GList добавляемый в конец первого GList.
Возвращает : начало нового GList.

g_list_foreach ()

void        g_list_foreach                  (GList *list,
                                             GFunc func,
                                             gpointer user_data);

Вызывает функцию для каждого элемента GList.

list : GList.
func : функция вызываемая для каждого элемента данных.
user_data : данные помещаемые в функцию.

GFunc ()

void        (*GFunc)                        (gpointer data,
                                             gpointer user_data);

Определяет тип функции помещаемой в g_list_foreach() и g_slist_foreach().

data : элементы данных.
user_data : данные помещаемые в g_list_foreach() или g_slist_foreach().

g_list_first ()

GList*      g_list_first                    (GList *list);

Выдаёт первый элемент в GList.

list : GList.
Возвращает : первый элемент в GList, или NULL если GList не имеет элементов.

g_list_last ()

GList*      g_list_last                     (GList *list);

Выдаёт последний элемент в GList.

list : GList.
Возвращает : последний элемент в GList, или NULL если GList не имеет элементов.

g_list_previous()

#define     g_list_previous(list)

Удобный макрос для получения предыдущего элемента в GList.

list : элемент в GList.
Возвращает : предыдущий элемент, или NULL если нет предыдущих элементов.

g_list_next()

#define     g_list_next(list)

Удобный макрос для получения следующего элемента в GList.

list : элемент в GList.
Возвращает : следующий элемент, или NULL если нет больше элементов.

g_list_nth ()

GList*      g_list_nth                      (GList *list,
                                             guint n);

Определяет элемент в данной позиции GList.

list : GList.
n : позиция элемента, подсчёт с 0.
Возвращает : элемент, или NULL если позиция выходит за пределы GList.

g_list_nth_data ()

gpointer    g_list_nth_data                 (GList *list,
                                             guint n);

Определяет данные элемента в указанной позиции.

list : GList.
n : позиция элемента.
Возвращает : данные элемента, или NULL если позиция выходит за пределы GList.

g_list_nth_prev ()

GList*      g_list_nth_prev                 (GList *list,
                                             guint n);

Определяет элемент n помещаемый перед list.

list : GList.
n : позиция элемента, подсчёт с 0.
Возвращает : элемент, или NULL если позиция выходит за пределы GList.

g_list_find ()

GList*      g_list_find                     (GList *list,
                                             gconstpointer data);

Находит элемент в GList который содержит полученные данные.

list : GList.
data : данные элемента для поиска.
Возвращает : найденный элемент GList, или NULL если он не найден.

g_list_find_custom ()

GList*      g_list_find_custom              (GList *list,
                                             gconstpointer data,
                                             GCompareFunc func);

Ищет элемент в GList, используя предоставленную функцию для поиска желаемого элемента. Она перемещается по списку, вызывая полученную функцию которая должна вернуть 0 когда желаемый элемент найден. Функция принимает два аргумента gconstpointer, элемент данных GList как первый аргумент и полученные пользовательские данные.

list : GList.
data : пользовательские данные помещаемые в функцию.
func : функция вызываемая для каждого элемента. Она должна вернуть 0 когда желаемый элемент найден.
Возвращает : искомый элемент GList, или NULL если он не найден.

g_list_position ()

gint        g_list_position                 (GList *list,
                                             GList *llink);

Определяет позицию полученного элемента в GList (начиная с 0).

list : GList.
llink : элемент в GList.
Возвращает : позиция элемента в GList, или -1 если элемент не найден.

g_list_index ()

gint        g_list_index                    (GList *list,
                                             gconstpointer data);

Определяет позицию элемента содержащего полученные данные (начиная с 0).

list : GList.
data : искомые данные.
Возвращает : перечень элементов содержащих данные, или -1 если данные не найдены.

g_list_push_allocator ()

void        g_list_push_allocator           (gpointer allocator);

Внимание

g_list_push_allocator устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде. Она ничего не делает, так как GList был конвертирован в slice allocator

Заставляет использовать распределитель для распределения элементов GList. Использует g_list_pop_allocator() для восстановления предыдущего распределения.

Помните что эта функция не доступна если GLib скомпилирована с опцией --disable-mem-pools

allocator : GAllocator используемый для распределения элементов GList.

g_list_pop_allocator ()

void        g_list_pop_allocator            (void);

Внимание

g_list_pop_allocator устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде. Она ничего не делает, так как GList был конвертирован в slice allocator

Восстанавливает предыдущий GAllocator, используемый для распределения элементов GList.

Помните что эта функция недоступна если GLib скомпилирована с опцией --disable-mem-pools


Dynamic Loading of Modules

Dynamic Loading of Modules — Переносимый способ для динамической загрузки 'plug-ins'.

Краткое описание


#include <gmodule.h>


            GModule;
gboolean    g_module_supported              (void);
gchar*      g_module_build_path             (const gchar *directory,
                                             const gchar *module_name);
GModule*    g_module_open                   (const gchar *file_name,
                                             GModuleFlags flags);
enum        GModuleFlags;
gboolean    g_module_symbol                 (GModule *module,
                                             const gchar *symbol_name,
                                             gpointer *symbol);
const gchar* g_module_name                  (GModule *module);
void        g_module_make_resident          (GModule *module);
gboolean    g_module_close                  (GModule *module);
const gchar* g_module_error                 (void);

const gchar* (*GModuleCheckInit)            (GModule *module);
void        (*GModuleUnload)                (GModule *module);
#define     G_MODULE_SUFFIX
#define     G_MODULE_EXPORT
#define     G_MODULE_IMPORT

Описание

Эти функции обеспечивают переносимый способ динамической загрузки объектных файлов (известны как 'plug-ins'). Текущая реализация поддерживает все системы которые обеспечивают выполнение dlopen() (например Linux/Sun), а также HP-UX через механизм shl_load() и Windows через DLLs.

Программы которые предполагается использовать с этими функциями должны быть слинкованы с библиотеками вывода (output) с помощью команды pkg-config --libs gmodule-2.0.

Для их использования вы сначала должны определить поддерживается ли динамическая загрузка на используемой платформе с помощью вызова g_module_supported(). Если поддерживается, то вы можете открывать модули с помощью g_module_open(), искать модульные идентификаторы (например имена функций) с помощью g_module_symbol(), а затем закрывать модули с помощью g_module_close(). g_module_name() возвращает имя файла текущего открытого модуля.

Если любая из описанных выше функций завершается неудачей, описание ошибки можно найти с помощью g_module_error().

GModule реализует особенность подсчета ссылок для открытых модулей и поддержку функций обработки прерываний в модуле, которая вызывается когда модуль загружается и выгружается (смотрите GModuleCheckInit и GModuleUnload).

Если ваш модуль вводит статические данные для общих подсистем в выполняемой программе, например через вызов g_quark_from_static_string ("my-module-stuff"), он должен быть уверен что никогда не выгрузится с помощью вызова g_module_make_resident().

Пример 12. Calling a function defined in a GModule

/* Подпись функции для 'say_hello' */
typedef void (* SayHelloFunc) (const char *message);

gboolean
just_say_hello (const char *filename, GError **error)
{
  SayHelloFunc  say_hello;
  GModule      *module;

  module = g_module_open (filename, G_MODULE_BIND_LAZY);
  if (!module)
    {
      g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
		   "%s", g_module_error ());
      return FALSE;
    }

  if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
    {
      g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
		   "%s: %s", filename, g_module_error ());
      if (!g_module_close (module))
	g_warning ("%s: %s", filename, g_module_error ());
      return FALSE;
    }

  /* вызываем нашу функцию в модуле */
  say_hello ("Hello world!");

  if (!g_module_close (module))
    g_warning ("%s: %s", filename, g_module_error ());

  return TRUE;
}

Детали

GModule

typedef struct _GModule GModule;

Непрозрачная структура данных GModule представляет Dynamically-Loaded Module. Доступ к ней должен осуществляться только с помощью функций описанных ниже.


g_module_supported ()

gboolean    g_module_supported              (void);

Проверяет поддерживается ли модуль текущей платформой.

Возвращает : TRUE если модуль поддерживается.

g_module_build_path ()

gchar*      g_module_build_path             (const gchar *directory,
                                             const gchar *module_name);

Переносимый способ создания имени файла модуля. Платформо-специфичные префикс и суффикс добавляются для имени файла, если необходимо и результат добавляется в каталог, используя правильный символьный разделитель.

Параметр directory должен определять каталог где где может быть найден модуль. Он может быть NULL или пустой строкой указывая что модуль находится в стандартном платформо-зависимом каталоге, хотя это не рекомендуется, так как может быть найден неправильный модуль.

Например, вызов g_module_build_path() в системе Linux с параметром directory равным значению /lib и параметром module_name равным значению "mylibrary" вернёт /lib/libmylibrary.so. В системе Windows, использование \Windows как значение параметра directory вернёт \Windows\mylibrary.dll.

directory : каталог где находится модуль. Может быть NULL или пустой строкой указывая что используется стандартный платформо-зависимый каталог, хотя это не рекомендуется.
module_name : имя модуля.
Возвращает : абсолютный путь модуля, включая стандартный библиотечный префикс и суффикс. Должен освобождаться когда больше не нужен.

g_module_open ()

GModule*    g_module_open                   (const gchar *file_name,
                                             GModuleFlags flags);

Открывает модуль. Если модуль уже открыт, то увеличивает количество ссылок.

Прежде всего g_module_open() пытается открыть file_name как модуль. Если это не удаётся и file_name имеет суффикс ".la" (и есть архив libtool), она пробует открыть соответствующий модуль. Если терпит неудачу и он не имеет надлежащего суффикса модуля для платформы (G_MODULE_SUFFIX), этот суффикс будет приставлен и соответствующий модуль будет открыт. Если это не удаётся и file_name не имеет суффикса ".la", этот суффикс подставляется и g_module_open() пытается открыть соответствующий модуль. Если и это не удаётся, то возвращается NULL.

file_name : имя файла содержащего модуль, или NULL для получения GModule представляющую непосредственно основную программу.
flags : флаги используемые для открытия модуля. Это может быть логическое ИЛИ любого из GModuleFlags.
Возвращает : GModule если выполнено удачно, или NULL если неудачно.

enum GModuleFlags

typedef enum
{
  G_MODULE_BIND_LAZY	= 1 << 0,
  G_MODULE_BIND_LOCAL	= 1 << 1,
  G_MODULE_BIND_MASK	= 0x03
} GModuleFlags;

Флаги помещаемые в g_module_open(). Помните что эти флаги поддерживаются на всех платформах.

G_MODULE_BIND_LAZY определяет что обозначения разрешены только при необходимости. Действие по умолчанию связывает все символы при загрузке модуля.
G_MODULE_BIND_LOCAL определяет что обозначения модуля не должны добавляться к глобальному пространству имён. Действие по умолчанию на большинстве платформ помещает обозначения в модуле в глобальное пространство имён, что может вызвать конфликт с существующими обозначениями.
G_MODULE_BIND_MASK маска для всех флагов.

g_module_symbol ()

gboolean    g_module_symbol                 (GModule *module,
                                             const gchar *symbol_name,
                                             gpointer *symbol);

Получает указатель символа из модуля.

module : GModule.
symbol_name : символьное имя для поиска.
symbol : возвращает указатель для символьного значения.
Возвращает : TRUE если выполнено.

g_module_name ()

const gchar* g_module_name                  (GModule *module);

Получает имя файла из GModule.

module : GModule.
Возвращает : имя файла модуля, или "main" если модуль непосредственно основная программа.

g_module_make_resident ()

void        g_module_make_resident          (GModule *module);

Гарантирует что модуль не будет выгружен. Любые вызовы g_module_close() для модуля будут игнорироваться в последствии.

module : GModule для постоянного нахождения в памяти.

g_module_close ()

gboolean    g_module_close                  (GModule *module);

Закрывает модуль.

module : GModule для закрытия.
Возвращает : TRUE при удачном выполнении.

g_module_error ()

const gchar* g_module_error                 (void);

Получает строку описывающую последнюю ошибку модуля.

Возвращает : строка описывающая последнюю ошибку модуля.

GModuleCheckInit ()

const gchar* (*GModuleCheckInit)            (GModule *module);

Определяет тип функции инициализации модуля. Если модуль содержит функцию с именем g_module_check_init() она вызывается автоматически при загрузке модуля. В неё помещается структура GModule и она должна вернуть NULL при успешном выполнении инициализации, или строку описывающую ошибку.

module : GModule соответствующая только что загруженному модулю.
Возвращает : NULL при успешном выполнении, или строку описывающую ошибку инициализации.

GModuleUnload ()

void        (*GModuleUnload)                (GModule *module);

Определяет тип модульной функции вызываемой при выгрузке. Если модуль содержит функцию с именем g_module_unload() она вызывается автоматически при выгрузке модуля. В неё помещается структура GModule.

module : GModule который выгружается.

G_MODULE_SUFFIX

#define G_MODULE_SUFFIX "so"

Расширение для надлежащего обще-библиотечного суффикса текущей платформы, без точки. Для большинства версий Uniх и Linux это "so", для некоторых версий HP-UX это "sl", а для Windows это "dll".


G_MODULE_EXPORT

#define     G_MODULE_EXPORT

Используется для декларации функций экспортируемых модулями.


G_MODULE_IMPORT

#define	G_MODULE_IMPORT		extern

Используется для декларации функций импортируемых из модулей.


Сообщения об ошибках

Error Reporting — система для сообщения об ошибках.

Краткое описание


#include <glib.h>


            GError;
GError*     g_error_new                     (GQuark domain,
                                             gint code,
                                             const gchar *format,
                                             ...);
GError*     g_error_new_literal             (GQuark domain,
                                             gint code,
                                             const gchar *message);
void        g_error_free                    (GError *error);
GError*     g_error_copy                    (const GError *error);
gboolean    g_error_matches                 (const GError *error,
                                             GQuark domain,
                                             gint code);
void        g_set_error                     (GError **err,
                                             GQuark domain,
                                             gint code,
                                             const gchar *format,
                                             ...);
void        g_propagate_error               (GError **dest,
                                             GError *src);
void        g_clear_error                   (GError **err);

Описание

GLib обеспечивает стандартный метод сообщения об ошибках из вызванной функции в вызываемом коде. (Это также решает проблему исключительной ситуации в других языках). Важно понять что это метод - data type (GError объект) и набора правил. Если вы используете GError неправильно, то ваш код не будет правильно взаимодействовать с другим кодом использующим GError, а пользователи вашего API вероятно запутаются.

Прежде всего: GError должен использоваться только для сообщения о восстанавливаемых ошибках в процессе выполнения. Обычно вы должны использовать g_warning(), g_return_if_fail(), g_assert(), g_error(), или похожее средство. (помните что функция g_error() должна использоваться только для программных ошибок, она не должна использоваться для печати любой ошибки о которой сообщено через GError.)

Примером восстанавливаемых ошибок во время выполнения программы являются "file not found" (файл не найден) или "failed to parse input" (не удаётся проанализировать ввод). Примером программных ошибок являются "NULL passed to strcmp()" или "attempted to free the same pointer twice". Эти два вида ошибок существенно отличаются: ошибки во время выполнения должны обрабатываться или о них должно быть сообщено пользователю, програмные ошибки должны ликвидироваться исправлением в программе. Поэтому большинство функций в GLib и GTK+ не используют GError.

Функции которые могут завершиться неудачно принимают в качестве последнего параметра место расположения возвращаемой GError. Например:

gboolean g_file_get_contents (const gchar *filename, 
	                      gchar      **contents,
                              gsize       *length,
                              GError     **error);

Если вы поместили не-NULL значение в параметр error, он должен указывать на место куда может быть помещена ошибка. Например:

gchar *contents;
GError *err = NULL;
g_file_get_contents ("foo.txt", &contents, NULL, &err);
g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
if (err != NULL)
  {
    /* Сообщаем об ошибке пользователю, и освобождаем ошибку */
    g_assert (contents == NULL);
    fprintf (stderr, "Unable to read file: %s\n", err->message);
    g_error_free (err);
  } 
else
  {
    /* Используем содержимое файла */
    g_assert (contents != NULL);
  }

Помните что err != NULL в этом примере надежно проверяет не закончилась ли неудачей g_file_get_contents(). Дополнительно, g_file_get_contents() возвращает логическое которое указывает была ли она завершена удачно.

Поскольку g_file_get_contents() возвращает FALSE при неудаче, если вы интересуетесь только статусом завершения и не нуждаетесь в отображении сообщения об ошибке, вы можете поместить NULL в параметр error:

if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* игнорирование ошибок */
  /* нет произошедших ошибок */ ;
else
  /* ошибка */ ;

Объект GError содержит три поля: domain указывает функцию сообщения об ошибках, code указывает произошедшую специфическую ошибку, а message читабельное для пользователя сообщение которое более детально описывает ошибку насколько это возможно. Некоторые функции предназначены для связи с ошибкой полученной из вызываемой функции: g_error_matches() возвращает TRUE если ошибка соответствует данной domain и code, g_propagate_error() копирует ошибку в место хранения ошибки (таким образом вызываемая функция получает её), а g_clear_error() очищает место расположения ошибки освобождая ошибку и переустанавливая место хранения ошибки в NULL. Для отображения ошибки пользователю, просто отобразите error->message, возможно наряду с дополнительным контекстом известным только вызываемой функции (открываемый файл, или любой -- хотя в случае g_file_get_contents(), error->message уже содержит имя файла).

При реализации функций способных сообщать об ошибках основной инструмент g_set_error(). Обычно, если происходит фатальная ошибка вам необходима g_set_error(), затем немедленное возвращение. g_set_error() ничего не делает если расположение ошибки помещённое в неё NULL. Например:

gint
foo_open_file (GError **error)
{
  gint fd;

  fd = open ("file.txt", O_RDONLY);

  if (fd < 0)
    {
      g_set_error (error,
                   FOO_ERROR,                 /* область ошибки (error domain) */
                   FOO_ERROR_BLAH,            /* код ошибки (error code) */
                   "Failed to open file: %s", /* форматированная строка сообщения об ошибке */
                   g_strerror (errno));
      return -1;
    }
  else
    return fd;
}

Немного сложнее если вы самостоятельно вызываете функцию которая может сообщить GError. Если подчинённая функция указывает на неисправимые ошибки некоторым способом отличающимся от сообщения GError, таким как возвращение TRUE при удачном исполнении, вы можете просто сделать следующее:

gboolean
my_function_that_can_fail (GError **err)
{
  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);

  if (!sub_function_that_can_fail (err))
    {
       /* предполагается что ошибка была установлена с помощью подчинённой функции (sub-function) */
       g_assert (err == NULL || *err != NULL);  
       return FALSE;
    }

  /* иначе продолжаем, ошибка не происходит */
  g_assert (err == NULL || *err == NULL);
}

Если подчинённая функция не указывает о других ошибках кроме как сообщения GError, вы должны создать временную GError та как помещаемая в неё может быть NULL. g_propagate_error() предназначена для использования в этом случае.

gboolean
my_function_that_can_fail (GError **err)
{
  GError *tmp_error;

  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);

  tmp_error = NULL;
  sub_function_that_can_fail (&tmp_error);

  if (tmp_error != NULL)
    {
       /* сохраняем tmp_error в err, если err != NULL,
        * иначе вызываем g_error_free() для tmp_error 
        */
       g_propagate_error (err, tmp_error);
       return FALSE;
    }

  /* иначе продолжаем, ошибка не происходит */
}

Error pileups являются всегда ошибкой. Например, этот код неправильный:

gboolean
my_function_that_can_fail (GError **err)
{
  GError *tmp_error;

  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);

  tmp_error = NULL;
  sub_function_that_can_fail (&tmp_error);
  other_function_that_can_fail (&tmp_error);

  if (tmp_error != NULL)
    {
       g_propagate_error (err, tmp_error);
       return FALSE;
    }
}

tmp_error должна быть проверена немедленно после sub_function_that_can_fail(), и либо очищена либо распространена на верх. Правило: после каждой ошибки, вы должны либо обработать ошибку, либо вернуть её в вызываемую функцию. Помните что NULL для параметра расположения ошибки эквивалентно обработке ошибки ничего не делая с ней. Таким образом следующий код является хорошим примером, предполагается что ошибки в sub_function_that_can_fail() являются не фатальными для my_function_that_can_fail():

gboolean
my_function_that_can_fail (GError **err)
{
  GError *tmp_error;

  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);

  sub_function_that_can_fail (NULL); /* игнорирование ошибок */

  tmp_error = NULL;
  other_function_that_can_fail (&tmp_error);

  if (tmp_error != NULL)
    {
       g_propagate_error (err, tmp_error);
       return FALSE;
    }
}

Помните что помещаемый NULL в параметр размещения ошибки означает игнорирование ошибок; это эквивалентно try { sub_function_that_can_fail(); } catch (...) {} в C++. Это не значит оставить ошибки не обработанными; это значит обработать ошибки ничего не делая.

Области и коды ошибки традиционно именуются следующим образом:

  • Область ошибки называют согласно шаблона <NAMESPACE>_<MODULE>_ERROR, например G_EXEC_ERROR или G_THREAD_ERROR.

  • Коды ошибки находятся в перечислении называемом согласно шаблона <Namespace><Module>Error; например, GThreadError или GSpawnError.

  • Элементы перечисления кодов ошибки называются согласно шаблона <NAMESPACE>_<MODULE>_ERROR_<CODE>, например G_SPAWN_ERROR_FORK или G_THREAD_ERROR_AGAIN.

  • Если есть "generic" или "unknown" коды ошибки для неисправимых ошибок нет смысла различать их другими специфическими кодами, они должны быть названы по шаблону <NAMESPACE>_<MODULE>_ERROR_FAILED, например G_SPAWN_ERROR_FAILED or G_THREAD_ERROR_FAILED.

Сводные правила использования GError:

  • Не сообщайте о программных ошибках через GError.

  • Последним параметром функции возвращающей ошибку должно быть место размещения GError (то есть "GError ** error"). Если GError используется с переменным количеством аргументов, то GError** должна быть последним аргументом перед "...".

  • Вызывающий может помещать NULL для GError** если его не интересуют подробности произошедшей ошибки.

  • Если NULL помещён для GError** аргумента, тогда ошибка не должна возвращаться к вызывающей функции, но ваша функция всё же должна прерываться и возвращаться если произошла ошибка. Таким образом, на управление потоком не должно влиять получение или неполучение вызывающей функцией GError.

  • Если о GError сообщено, то ваша функция по определению имеет фатальную ошибку и не закончила то что должна была сделать. Если произошла не фатальная ошибка, то вы обрабатываете её и не должны сообщать о ней. Если она была фатальной, то вы должны сообщить о ней и прекратить выполнение немедленно.

  • GError* должна быть инициализирована в значение NULL перед помещением её адреса в функцию которая может сообщать об ошибках.

  • "Накопление" ошибок - всегда ошибка. Таким образом, если вы назначили новую GError для GError* которая не-NULL, переписывая таким образом предыдущую ошибку, она указывает вам что нужно прервать операцию вместо продолжения. Вы можете продолжать если очистите предыдущую ошибку с помощью g_clear_error(). g_set_error() будет предупреждать если вы накапливаете ошибки.

  • В соответствие с соглашением, если вы возвращаете логическое значение, то TRUE означает успешное выполнение, а FALSE означает неудачу. Если возвращено значение FALSE, ошибка должна быть установлена в значение не-NULL.

  • Возвращённое значение NULL часто также означает что произошла ошибка. Вы должны разъяснить в вашей документации означает ли NULL допустимое возвращаемое значение в случае безошибочного выполнения; если NULL допустимое значение, то пользователи должны проверить была ли возвращена ошибка, чтобы увидеть выполнена ли функция успешно.

  • Когда реализуется функция которая может сообщать об ошибках, вы можете добавить проверку в начале вашей функции является ли место расположения ошибки значением NULL или используется ли значение NULL в качестве указателя ошибки (например g_return_if_fail (error == NULL || *error == NULL);).

Детали

GError

typedef struct {
  GQuark       domain;
  gint         code;
  gchar       *message;
} GError;

Структура GError содержит информацию о произошедшей ошибке.

GQuark domain; область ошибки, например G_FILE_ERROR.
gint code; код ошибки, например G_FILE_ERROR_NOENT.
gchar *message; удобное для чтения пользователем информационное сообщение об ошибке.

g_error_new ()

GError*     g_error_new                     (GQuark domain,
                                             gint code,
                                             const gchar *format,
                                             ...);

Создаёт новую GError с полученными domain и code, а сообщение форматируется с помощью format.

domain : область ошибки
code : код ошибки
format : printf()-стиль форматирования для сообщения об ошибке
... : параметры для форматирования сообщения
Возвращает : новая GError

g_error_new_literal ()

GError*     g_error_new_literal             (GQuark domain,
                                             gint code,
                                             const gchar *message);

Создаёт новую GError; в отличие от g_error_new(), message является строкой не в printf()-стиле форматирования. Используйте эту функцию если message содержит текст не контролируемый вами, который мог бы включать printf() escape-последовательность.

domain : область ошибки
code : код ошибки
message : сообщение об ошибке
Возвращает : новая GError

g_error_free ()

void        g_error_free                    (GError *error);

Освобождает GError и связанные с ней ресурсы.

error : GError

g_error_copy ()

GError*     g_error_copy                    (const GError *error);

Создаёт копию error.

error : GError
Возвращает : новую GError

g_error_matches ()

gboolean    g_error_matches                 (const GError *error,
                                             GQuark domain,
                                             gint code);

Возвращает TRUE если error соответствует domain и code, FALSE в любом другом случае.

error : GError
domain : область ошибки
code : код ошибки
Возвращает : соответствует ли error domain и code

g_set_error ()

void        g_set_error                     (GError **err,
                                             GQuark domain,
                                             gint code,
                                             const gchar *format,
                                             ...);

Ничего не делает если err имеет значение NULL; если err не-NULL, то *err должна быть NULL. Новая GError создаётся привязанной к *err.

err : расположение для возвращаемой GError, или NULL
domain : область ошибки
code : код ошибки
format : printf()-стиль форматирования
... : аргументы для format

g_propagate_error ()

void        g_propagate_error               (GError **dest,
                                             GError *src);

Если dest имеет значение NULL, освобождает src; иначе, перемещает src в *dest. *dest должен быть NULL.

dest : расположение возвращаемой ошибки
src : ошибка для перемещения в расположение указанное параметром dest 

g_clear_error ()

void        g_clear_error                   (GError **err);

Если err имеет значение NULL, ничего не делает. Если err не-NULL, вызывает g_error_free() для *err и устанавливает *err в значение NULL.

err : расположение возвращаемой GError

File Utilities

File Utilities — Варианты функций связанных с файлами.

Краткое описание


#include <glib.h>
#include <glib/gstdio.h>


enum        GFileError;
#define     G_FILE_ERROR
enum        GFileTest;
GFileError  g_file_error_from_errno         (gint err_no);
gboolean    g_file_get_contents             (const gchar *filename,
                                             gchar **contents,
                                             gsize *length,
                                             GError **error);
gboolean    g_file_set_contents             (const gchar *filename,
                                             const gchar *contents,
                                             gssize length,
                                             GError **error);
gboolean    g_file_test                     (const gchar *filename,
                                             GFileTest test);
gint        g_mkstemp                       (gchar *tmpl);
gint        g_file_open_tmp                 (const gchar *tmpl,
                                             gchar **name_used,
                                             GError **error);
gchar*      g_file_read_link                (const gchar *filename,
                                             GError **error);
int         g_mkdir_with_parents            (const gchar *pathname,
                                             int mode);

            GDir;
GDir*       g_dir_open                      (const gchar *path,
                                             guint flags,
                                             GError **error);
const gchar* g_dir_read_name                (GDir *dir);
void        g_dir_rewind                    (GDir *dir);
void        g_dir_close                     (GDir *dir);

            GMappedFile;
GMappedFile* g_mapped_file_new              (const gchar *filename,
                                             gboolean writable,
                                             GError **error);
void        g_mapped_file_free              (GMappedFile *file);
gsize       g_mapped_file_get_length        (GMappedFile *file);
gchar*      g_mapped_file_get_contents      (GMappedFile *file);

int         g_open                          (const gchar *filename,
                                             int flags,
                                             int mode);
int         g_rename                        (const gchar *oldfilename,
                                             const gchar *newfilename);
int         g_mkdir                         (const gchar *filename,
                                             int mode);
int         g_stat                          (const gchar *filename,
                                             struct stat *buf);
int         g_lstat                         (const gchar *filename,
                                             struct stat *buf);
int         g_unlink                        (const gchar *filename);
int         g_remove                        (const gchar *filename);
int         g_rmdir                         (const gchar *filename);
FILE*       g_fopen                         (const gchar *filename,
                                             const gchar *mode);
FILE*       g_freopen                       (const gchar *filename,
                                             const gchar *mode,
                                             FILE *stream);
int         g_chmod                         (const gchar *filename,
                                             int mode);
int         g_access                        (const gchar *filename,
                                             int mode);
int         g_creat                         (const gchar *filename,
                                             int mode);
int         g_chdir                         (const gchar *path);

Описание

Есть группа функций которые являются оболочками для основных POSIX функций имеющих дело с именами файлов (g_open(), g_rename(), g_mkdir(), g_stat(), g_unlink(), g_remove(), g_fopen(), g_freopen()). Указанные оболочки позволяют обрабатывать имена файлов с любыми Unicode символами в Windows без необходимости использования ifdefs и расширенного API символов в коде приложения.

Аргумент pathname должен быть в кодировке имён файлов GLib. В POSIX это фактическая кодировка на диске которая может соответствовать установкам locale процесса (или переменной окружения G_FILENAME_ENCODING), или нет.

В Windows кодировкой имён файлов GLib является UTF-8. Помните что Microsoft C library не использует UTF-8, но имеет раздельный APIs для текущей системной кодовой страницы и расширенных символов (UTF-16). Оболочки GLib вызывают расширенный символьный API, если представлен (на современных системах Windows), иначе конвертируют в/из системной кодовой страницы.

Другая группа функций позволяет открывать и читать каталоги в кодировке имён файлов GLib. Такие как g_dir_open(), g_dir_read_name(), g_dir_rewind(), g_dir_close().

Детали

enum GFileError

typedef enum
{
  G_FILE_ERROR_EXIST,
  G_FILE_ERROR_ISDIR,
  G_FILE_ERROR_ACCES,
  G_FILE_ERROR_NAMETOOLONG,
  G_FILE_ERROR_NOENT,
  G_FILE_ERROR_NOTDIR,
  G_FILE_ERROR_NXIO,
  G_FILE_ERROR_NODEV,
  G_FILE_ERROR_ROFS,
  G_FILE_ERROR_TXTBSY,
  G_FILE_ERROR_FAULT,
  G_FILE_ERROR_LOOP,
  G_FILE_ERROR_NOSPC,
  G_FILE_ERROR_NOMEM,
  G_FILE_ERROR_MFILE,
  G_FILE_ERROR_NFILE,
  G_FILE_ERROR_BADF,
  G_FILE_ERROR_INVAL,
  G_FILE_ERROR_PIPE,
  G_FILE_ERROR_AGAIN,
  G_FILE_ERROR_INTR,
  G_FILE_ERROR_IO,
  G_FILE_ERROR_PERM,
  G_FILE_ERROR_NOSYS,
  G_FILE_ERROR_FAILED
} GFileError;

Значения соответствующие errno кодам возвращаемым из файловых операций в UNIX. В отличие от errno кодов, GFileError значения доступны во всех системах, даже в Windows. Точное значение каждого кода зависит от выполняемой вами опреции; UNIX документация даёт больше деталей. Следующие описания error кодов взяты из руководства GNU C Library и находятся под действие копирайта этого руководства.

Это не очень переносимо для создания подробного предположения о точных ошибках которые будут возвращены из полученной операции. Некоторые ошибки не происходят в некоторых системах и т.д., иногда есть тонкое различие в том когда система сообщит о полученной ошибке и т.д..

G_FILE_ERROR_EXIST Операция не разрешена; только владелец файла (или другого ресурса) или процесс со специальными привилегиями может выполнить операцию.
G_FILE_ERROR_ISDIR Файл является каталогом; вы не можете открыть каталог для записи, или создать/удалить жесткую ссылку в нём.
G_FILE_ERROR_ACCES Запрещённое действие; права на файл не позволяют произвести операцию.
G_FILE_ERROR_NAMETOOLONG Слишком длинное имя файла.
G_FILE_ERROR_NOENT Нет такого файла или каталога. Это ошибка "file doesn't exist" для обычных файлов на которые ссылаются в контекстах ожидая что они уже существуют.
G_FILE_ERROR_NOTDIR Файл который не является каталогом, был запрошен как каталог.
G_FILE_ERROR_NXIO Нет такого устройства или адреса. Система попыталась использовать устройство представленное файлом который вы определили и не смогла найти устройство. Это может означать что файл устройства было неправильно установлено, или физическое устройство отсутствует или неправильно подключено к компьютеру.
G_FILE_ERROR_NODEV Файл имеет тип который не поддерживает отображение.
G_FILE_ERROR_ROFS Каталог не может быть изменён потому, что он находится на файловой системе только для чтения.
G_FILE_ERROR_TXTBSY Текстовый файл занят.
G_FILE_ERROR_FAULT Вы перешли в указатель на испорченную память. (GLib не гарантирует возврат этого, не перемещайтесь в указатели на испорченную память.)
G_FILE_ERROR_LOOP Слишкрм много уровней символических ссылок при поиске имени файла. Это часто указывает на циклические символические ссылки.
G_FILE_ERROR_NOSPC Нет свободного пространства на устройстве; запись файла на устройство не удалась, так как диск заполнен.
G_FILE_ERROR_NOMEM Нет доступной памяти. Система не может распределить виртуальную память, так как она полная.
G_FILE_ERROR_MFILE Текущий процесс имеет слишком много открытых файлов и не может больше открыть ни одного. Двойные дескрипторы действительно рассчитывают до этого предела.
G_FILE_ERROR_NFILE Во системе слишком много разных открытых файлов.
G_FILE_ERROR_BADF Плохой дескриптор файла; например, I/O в дескриптор который был закрыт или прочитан из дескриптора открытого только для записи (или наоборот).
G_FILE_ERROR_INVAL Недопустимый параметр. Используется для указания на различного рода проблемы связанные с указанием неправильных параметров библиотечных функций.
G_FILE_ERROR_PIPE Испорченный канал; нет процесса читающего на другом конце канала. Все библиотечные функции, которые возвращают этот код ошибки, также генерируют сигнал `SIGPIPE'; этот сигнал закрывает программу если обработан или не заблокирован. Поэтому ваша программа фактически никогда не увидит этот код пока она обрабатывает или не блокирует `SIGPIPE'.
G_FILE_ERROR_AGAIN Ресурс временно не доступен; повторите запрос немного позже.
G_FILE_ERROR_INTR Прерванный вызов функции; произошёл асинхронный сигнал и предотвратил завершение вызова. Когда это происходит вы должны повторить вызов снова.
G_FILE_ERROR_IO Ошибка ввода/вывода; обычно используется для физических ошибок чтения или записи. То есть диск или другое физическое устройство вернуло ошибку.
G_FILE_ERROR_PERM Опереция не разрешена; только владелец файла (или другого ресурса) или процесс со специальными правами может выполнить операцию.
G_FILE_ERROR_NOSYS Функция не реализована; это указывает что в системе отсутствует некоторая функциональность.
G_FILE_ERROR_FAILED Не соответствует ошибочному коду UNIX; это стандартный код ошибки "failed for unspecified reason" представленный во всех перечислениях GError ошибочных кодов. Возвращается если нет определённого кода.

G_FILE_ERROR

#define G_FILE_ERROR g_file_error_quark ()

Домен ошибки для файловых операций. Ошибки в этом домене из перечисления GFileError. Смотрите GError для информации о доменах ошибки.


enum GFileTest

typedef enum
{
  G_FILE_TEST_IS_REGULAR    = 1 << 0,
  G_FILE_TEST_IS_SYMLINK    = 1 << 1,
  G_FILE_TEST_IS_DIR        = 1 << 2,
  G_FILE_TEST_IS_EXECUTABLE = 1 << 3,
  G_FILE_TEST_EXISTS        = 1 << 4
} GFileTest;

Перечисление для тестирования файла используя g_file_test().

G_FILE_TEST_IS_REGULAR TRUE если файл обычный (не ссылка или каталог)
G_FILE_TEST_IS_SYMLINK TRUE если файл является символической ссылкой.
G_FILE_TEST_IS_DIR TRUE если файл является каталогом.
G_FILE_TEST_IS_EXECUTABLE TRUE если файл исполняемый.
G_FILE_TEST_EXISTS TRUE если файл существует. Может быть или не быть обычным файлом.

g_file_error_from_errno ()

GFileError  g_file_error_from_errno         (gint err_no);

Получает константу GFileError основанную на помещённой errno. Например, если вы поместили EEXIST эта функция вернёт G_FILE_ERROR_EXIST. В отличие от значений errno, вы можете предполагать что все значения GFileError будут существовать при портировании.

Обычно значение GFileError происходит из GError возвращаемой из функций манипулирования файлами. Поэтому вы должны использовать g_file_error_from_errno() при создании GError.

err_no : значение "errno"
Возвращает : GFileError соответствующую полученной errno

g_file_get_contents ()

gboolean    g_file_get_contents             (const gchar *filename,
                                             gchar **contents,
                                             gsize *length,
                                             GError **error);

Читает весь файл в распределённую память, с хорошей проверкой ошибок.

Если вызов был выполнен успешно, то возвращает TRUE и устанавливает contents в файловый контекст, а length в длину файлового контекста в байтах. Строка сохраняемая в contents будет nul-завершённой, таким образом для текстового файла вы можете поместить NULL для аргумента length. Если вызов не выполнен, то возвращает FALSE и устанавливает error. Домен ошибки это G_FILE_ERROR. Возможные коды ошибок берутся в перечислении GFileError. В случае ошибки, contents устанавливается в значение NULL, а length в нулевое значение.

filename : имя файла из которого читается содержимое, в кодировке имён файлов GLib
contents : расположение для хранения распределённой строки
length : расположение для хранения длины содержимого в байтах, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE при успешном выполнении, FALSE если произошла ошибка

g_file_set_contents ()

gboolean    g_file_set_contents             (const gchar *filename,
                                             const gchar *contents,
                                             gssize length,
                                             GError **error);

Записывает весь contents в файл с именем filename, с хорошим контролем ошибок. Если файл с именем filename уже существует он будет переписан.

Эта запись атомарная в том смысле что сначала записывается в во временный файл который затем переименовывается в конечное имя. Помните:

  • В Unix, если filename уже является жёсткой ссылкой, то связь с filename будет сломана. А также, так как файл перезаписан, существующие права доступа, метаданные и т.д. могут быть утеряны. Если filename символическая ссылка, то сама связь будет заменена на не связанный файл.
  • В Windows переименованный файл не удаляет существующий файл, поэтому в Windows есть условие "гонки" между существующим удаляемым файлом и временным переименовываемым файлом.
  • В Windows нет способа удаления файла который открыт другим процессом, или отображён в память. Поэтому, эта функция терпит неудачу если filename уже существует и открыт.

Если вызов был успешен, возвращает TRUE. Если вызов неудался, возвращает FALSE и устанавливает error. Домен ошибки - G_FILE_ERROR. Возможные коды ошибок берутся из перечисления GFileError enumeration.

filename : имя файла для записи контекста contents, в кодировке имён файлов GLib
contents : строка для записи в файл
length : длина contents, или -1 если contents является nul-завершённой строкой
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE при успешном выполнении, FALSE если произошла ошибка

Начиная с версии 2.8


g_file_test ()

gboolean    g_file_test                     (const gchar *filename,
                                             GFileTest test);

Возвращает TRUE если любой из тестов в битовом поле test является TRUE. Например, (G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR) вернёт TRUE если файл существует; проверка является ли он каталогом не имеет значения, так как тест существования имеет значение TRUE. С текущем набором доступных тестов, нет никакого смысла помещать больше чем один тест одновременно.

Помимо G_FILE_TEST_IS_SYMLINK все тесты поддерживают символические тесты, поэтому для символической ссылки на обычный файл g_file_test() вернёт TRUE и для G_FILE_TEST_IS_SYMLINK и для G_FILE_TEST_IS_REGULAR.

Помните, для висящей символической ссылки g_file_test() вернёт TRUE для G_FILE_TEST_IS_SYMLINK и FALSE для других флагов.

Вы никогда не должны использовать g_file_test() для тестирования безопасности операции, потомучто всегда есть возможность условия изменяющегося прежде чем вы фактически выполнили операцию. Например, вы можете подумать что можно использовать G_FILE_TEST_IS_SYMLINK, чтобы определить можно ли безопасно записать в файл не опасаясь что он находится в другом месте. Это не работает!

/* Не делайте это */
 if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) {
   fd = g_open (filename, O_WRONLY);
   /* запись в fd */
 }

Также помните что G_FILE_TEST_EXISTS и G_FILE_TEST_IS_EXECUTABLE реализованы с использованием системного вызова access(). Это обычно не имеет значения, но если ваша программа имеет setuid или setgid это значит что эти тесты дадут вам ответ для реального user ID и group ID, а не действующего user ID и group ID.

В Windows, нет символических ссылок, поэтому тест для G_FILE_TEST_IS_SYMLINK будет всегда возвращать FALSE. Тест для G_FILE_TEST_IS_EXECUTABLE будет просто проверять что файл существует и его имя указывает что он исполняемый, проверяя известные расширения и их список в переменной окружения PATHEXT.

filename : имя проверяемого файла в кодировке имён файлов GLib
test : логическое поле флагов GFileTest
Возвращает : был ли тест TRUE

g_mkstemp ()

gint        g_mkstemp                       (gchar *tmpl);

Открывает временный файл. Смотрите документацию mkstemp() в большинстве UNIX-подобных системах.

В качестве параметра используется строка которая должна соответствовать правилам шаблонов mkstemp(), то есть содержать строку "XXXXXX". g_mkstemp() более гибкая чем mkstemp() в которой последовательность не должна находится в самом конце шаблона. Строка X изменяется для формирования имени не существующего файла. Строка должна быть в кодировке имён файлов GLib. Наиболее важно что в Windows она должна быть в UTF-8.

tmpl : шаблон имени файла
Возвращает : Дескриптор файла (как из open()) для файла открытого для записи и чтения. Файл открывается в двоичном режиме на платформах где есть различия. Дескриптор файла должен быть закрыт с помощью close(). В случае ошибки, возвращается -1.

g_file_open_tmp ()

gint        g_file_open_tmp                 (const gchar *tmpl,
                                             gchar **name_used,
                                             GError **error);

Открывает файл для записи в привилегированный каталог временных файлов (который возвращается из g_get_tmp_dir()).

tmpl должен быть строкой в кодировке имён файлов GLib содержащей последовательность шести символов 'X', также как параметр в g_mkstemp(). Однако в отличие от этой функции, шаблон должен быть только базовым именем, ни какие компоненты каталога не допускаются. Если шаблон NULL, используется шаблон по умолчанию.

Помните что в отличие от g_mkstemp()mkstemp()) tmpl не изменяется, и может таким образом быть буквенной строкой только для чтения.

Фактически используется имя возвращаемое в name_used если не-NULL. Эта строка должна быть освобождена с помощью g_free() когда больше не нужна. Возвращаемое имя находится в кодировке имён файлов GLib.

tmpl : Шаблон для имени файла, как в g_mkstemp(), только базовое имя, или NULL, для использования шаблона по умолчанию.
name_used : расположение для хранения фактически используемого имени
error : расположение для возвращаемой GError
Возвращает : Дескриптор файла (как из open()) открытого для чтения и записи. Файл открывается в двоичном режиме на платформах где есть разница. Дескриптор файла должен быть закрыт с помощью close(). В случае ошибки, возвращает -1 и устанавливает error.

g_file_read_link ()

gchar*      g_file_read_link                (const gchar *filename,
                                             GError **error);

Читает содержимое символической ссылки filename также как POSIX функция readlink(). Возвращаемая строка находится в кодировке используемой для имён файлов. Использует g_filename_to_utf8() для конвертации в UTF-8.

filename : символическая ссылка
error : размещение для возвращаемой GError
Возвращает : Вновь распределённая строка с содержимым символической ссылки, или NULL если произошла ошибка.

Начиная с версии 2.4


g_mkdir_with_parents ()

int         g_mkdir_with_parents            (const gchar *pathname,
                                             int mode);

Создаёт каталог если он ещё не существует. Также создаёт необходимые промежуточные родительские каталоги.

pathname : имя пути в кодировке имён файлов GLib
mode : права доступа для вновь созданных каталогов
Возвращает : 0 если каталог существует, или был полностью создан. Возвращает -1 если произошла ошибка, с установкой errno.

Начиная с версии 2.8


GDir

typedef struct _GDir GDir;

Непрозрачная структура представляющая открытый каталог.


g_dir_open ()

GDir*       g_dir_open                      (const gchar *path,
                                             guint flags,
                                             GError **error);

Открывает каталог для чтения. Имена файлов в каталоге могут быть найдены с помощью g_dir_read_name().

path : путь к интересующему вас каталогу. В Unix в дисковой кодировке (on-disk encoding). В Windows в UTF-8
flags : В текущее время должен быть установлен в 0. Зарезервирован для использования в будующем.
error : расположение для возвращаемой GError, или NULL. Если не-NULL, будет установлена ошибка если и только если g_dir_open() закончилась неудачей.
Возвращает : вновь распределённая GDir при успешном выполнении, NULL при неудаче. Если не-NULL, вы должны освободить результат с помощью g_dir_close() когда вы закончите.

g_dir_read_name ()

const gchar* g_dir_read_name                (GDir *dir);

Находит имя следующего входа в каталоге. Входы '.' и '..' пропускаются. В Windows, возвращаемое имя находится в кодировке UTF-8. В Unix, она находится в дисковой кодировке (on-disk encoding).

dir : GDir* созданная с помощью g_dir_open()
Возвращает : Имя входа или NULL если нет больше входов. Возвращаемым значением владеет GLib и оно не должно модифицироваться или освобождаться.

g_dir_rewind ()

void        g_dir_rewind                    (GDir *dir);

Сбрасывает полученный каталог до первой записи. Следующий вызов g_dir_read_name() снова вернёт первый вход.

dir : GDir* созданная с помощью g_dir_open()

g_dir_close ()

void        g_dir_close                     (GDir *dir);

Закрывает каталоги и освобождает все связанные с ними ресурсы.

dir : GDir* созданная с помощью g_dir_open()

GMappedFile

typedef struct _GMappedFile GMappedFile;

GMappedFile представляет отображение файла созданное с помощью g_mapped_file_new(). Она имеет только закрытые элементы и не должна использоваться непосредственно.


g_mapped_file_new ()

GMappedFile* g_mapped_file_new              (const gchar *filename,
                                             gboolean writable,
                                             GError **error);

Отображает файл в памяти. В UNIX, она использует функцию mmap().

Если writable равна TRUE, буфер отображения может модифицироваться, иначе она представляет ошибку для изменения отображённого буфера. Модификации буфера невидимы для других процессов отображающих тот же файл и не записываются обратно в файл.

Помните что модификации основного файла могут затронуть содержимое GMappedFile. Поэтому отображение должно использоваться только если файл не будет изменён, или все модификации файла сделаны атомарно (например используя g_file_set_contents()).

filename : путь файла для загрузки, в кодировке имён файлов GLib
writable : если отображение должно быть изменяемым
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённая GMappedFile которая должна освобождаться с помощью g_mapped_file_free(), или NULL если отображение не удалось.

Начиная с версии 2.8


g_mapped_file_free ()

void        g_mapped_file_free              (GMappedFile *file);

Сбрасывает буфер отображения для file и освобождает его.

file : GMappedFile

Начиная с версии 2.8


g_mapped_file_get_length ()

gsize       g_mapped_file_get_length        (GMappedFile *file);

Возвращает размер содержимого GMappedFile.

file : GMappedFile
Возвращает : размер содержимого file.

Начиная с версии 2.8


g_mapped_file_get_contents ()

gchar*      g_mapped_file_get_contents      (GMappedFile *file);

Returns the contents of a GMappedFile.

Помните что содержимое может быть не ноль-завершённым (zero-terminated), даже если GMappedFile поддерживается текстовым файлом.

file : GMappedFile
Возвращает : содержимое file.

Начиная с версии 2.8


g_open ()

int         g_open                          (const gchar *filename,
                                             int flags,
                                             int mode);

Оболочка для POSIX функции open(). Функция open() используется для конвертации имени пути в дескриптор файла. Помните что в POSIX системах дескриптор файла реализуется системной операцией. В Windows, это C библиотека которая реализует open() и дескриптор файла. Фактическое Windows API для открытия файлов является другим.

Смотрите руководство C library для детальной информации о open().

filename : имя пути в кодировке имён файлов GLib (UTF-8 в Windows)
flags : как в open()
mode : как в open()
Возвращает : новый дескриптор файла, или -1 если произошла ошибка. Возвращаемое значение может быть использовано точно также как значение из open().

Начиная с версии 2.6


g_rename ()

int         g_rename                        (const gchar *oldfilename,
                                             const gchar *newfilename);

Оболочка для POSIX функции rename(). Функция rename() переименовывает файл, перемещая его между каталогами если необходимо.

Смотрите руководство для вашей C библиотеки для получения деталей о том как работает rename() в вашей системе. Помните что в Win9x не возможно переименовать файл если файл с новым именем уже существует. Также это не возможно вообще в Windows для открытых файлов.

oldfilename : имя пути в кодировке имён файлов GLib (UTF-8 в Windows)
newfilename : имя пути в кодировке имён файлов GLib
Возвращает : 0 если переименование выполнено, -1 если произошла ошибка

Начиная с версии 2.6


g_mkdir ()

int         g_mkdir                         (const gchar *filename,
                                             int mode);

Оболочка для POSIX функции mkdir(). Функция mkdir() пытается создать каталог с полученным именем и правами доступа.

Смотрите руководство C библиотеки для больших деталей о mkdir().

filename : имя пути в кодировке имён файлов GLib (UTF-8 в Windows)
mode : права доступа для использования вновь созданного каталога
Возвращает : 0 если каталог был полностью создан, -1 если произошла ошибка

Начиная с версии 2.6


g_stat ()

int         g_stat                          (const gchar *filename,
                                             struct stat *buf);

Оболочка для POSIX функции stat(). Функция stat() возвращает информацию о файле.

Смотрите руководство C библиотеки для больших деталей о stat().

filename : имя пути в кодировке имён файлов GLib (UTF-8 в Windows)
buf : указатель на структуру stat, которая заполнена информацией о файле.
Возвращает : 0 если информация полностью получена, -1 если произошла ошибка

Начиная с версии 2.6


g_lstat ()

int         g_lstat                         (const gchar *filename,
                                             struct stat *buf);

Оболочка для POSIX функции lstat(). Функция lstat() похожа на stat() за исключением того что в случае символической ссылки она возвращает информацию о символической ссылке непосредственно, а не о файле на который она ссылается. Если система не поддерживает символических ссылок g_lstat() идентична g_stat().

Смотрите руководство C библиотеки для больших деталей о lstat().

filename : имя пути в кодировке имён файлов GLib (UTF-8 в Windows)
buf : указатель на структуру stat, которая заполняется информацией о файле
Возвращает : 0 если информация была полностью получена, -1 если произошла ошибка

Начиная с версии 2.6


g_unlink ()

int         g_unlink                        (const gchar *filename);

Оболочка для POSIX функции unlink(). Функция unlink() удаляет имя из файловой системы. Если оно было последней ссылкой на файл и нет процессов открывших его, дисковое пространство освобождается от файла.

Смотрите руководство C библиотеки для больших деталей о unlink(). Помните что в Windows, она не может удалить файлы которые открыты каким нибудь процессом, или отображены в памяти.

filename : имя пути в кодировке имён файлов GLib (UTF-8 в Windows)
Возвращает : 0 если имя полностью удалено, -1 если произошла ошибка

Начиная с версии 2.6


g_remove ()

int         g_remove                        (const gchar *filename);

Оболочка для POSIX функции remove(). Функция remove() удаляет имя файла из файловой системы.

Смотрите руководство C библиотеки для больших деталей о том как работает remove() в вашей системе. В Unix, remove() удаляет также каталоги, так как она вызывает unlink() для файлов и rmdir() для каталогов. В Windows, хотя remove() в C библиотеке работает только для файлов, эта функция вызовет сначала remove() а затем если это не удалось rmdir(), поэтому работает и для файлов и для каталогов. Помните однако, что в Windows, она не сможет удалить файл который открыт каким нибудь процессом, или отображён в память.

Если эта функция закончилась неудачно в Windows вы не можете получить слишком много из значения ошибки. rmdir() пробует выполниться не зависимо от того что remove() завершилась неудачно. Любое значение errno установленное remove() будет переписано rmdir().

filename : имя пути в кодировке имён файлов GLib (UTF-8 в Windows)
Возвращает : 0 если файл был полностью удалён, -1 если произошла ошибка

Начиная с версии 2.6


g_rmdir ()

int         g_rmdir                         (const gchar *filename);

Оболочка для POSIX функции rmdir(). Функция rmdir() каталог из файловой системы.

Смотрите руководство C библиотеки для больших деталей о том как работает rmdir() в вашей системе.

filename : имя пути в кодировке имён файлов GLib (UTF-8 в Windows)
Возвращает : 0 если каталог был полностью удалён, -1 если произошла ошибка

Начиная с версии 2.6


g_fopen ()

FILE*       g_fopen                         (const gchar *filename,
                                             const gchar *mode);

Оболочка для POSIX функции fopen(). Функция fopen() открывает файл и связывает его с новым потоком.

Смотрите руководство C библиотеки для деталей о fopen().

filename : имя пути в кодировке имён файлов GLib (UTF8 в Windows)
mode : строка describing the mode in which the file should be opened
Возвращает : A FILE pointer if the file was successfully opened, or NULL if an error occurred

Начиная с версии 2.6


g_freopen ()

FILE*       g_freopen                       (const gchar *filename,
                                             const gchar *mode,
                                             FILE *stream);

A wrapper for the POSIX freopen() function. The freopen() function opens a file and associates it with an existing stream.

Смотрите руководство С библиотеки для больших деталей о freopen().

filename : имя пути в кодировке имён файлов GLib (UTF8 в Windows)
mode : строка describing the mode in which the file should be opened
stream : an existing stream which will be reused, or NULL
Возвращает : A FILE pointer if the file was successfully opened, or NULL if an error occurred.

Начиная с версии 2.6


g_chmod ()

int         g_chmod                         (const gchar *filename,
                                             int mode);

A wrapper for the POSIX chmod() function. The chmod() function is used to set the permissions of a file system object. Note that 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 READONLY attribute. It does not touch any ACL. Software that needs to manage file permissions on Windows exactly should use the Win32 API.

Смотрите руководство С библиотеки для больших деталей о chmod().

filename : имя пути в кодировке имён файлов GLib (UTF8 в Windows)
mode : как в chmod()
Возвращает : ноль если операция полностью выполнена, -1 при ошибке.

Начиная с версии 2.8


g_access ()

int         g_access                        (const gchar *filename,
                                             int mode);

Оболочка для POSIX функции access(). Эта функция используется для тестирования имени пути на доступ чтения, записи или исполнения, или просто существование. В Windows, основная функция access() в C библиотеке только проверяет параметр READONLY, и не смотрите остальные ACL. Программное обеспечение, которое должно более точно обрабатывать права доступа в Windows, должно использовать Win32 API.

Смотрите руководство С библиотеки для больших деталей о access().

filename : имя пути в кодировке имён файлов GLib (UTF8 в Windows)
mode : как в access()
Возвращает : ноль если имя пути ссылается на существующий объект в файловой системе который прошёл все тесты доступа, или -1 если произошла ошибка.

Начиная с версии 2.8


g_creat ()

int         g_creat                         (const gchar *filename,
                                             int mode);

Оболочка для POSIX функции creat(). Функция creat() используется для конвертации имени пути в дескриптор файла, создавая файл если необходимо. Помните что в POSIX системах дескриптор файла реализуется операционной системой. В Windows, это выполняет C библиотека которая реализует creat() и дескриптор файла. Фактически Windows API для открытия файлов несколько другое.

Смотрите руководство С библиотеки для больших деталей о creat().

filename : имя пути в кодировке имён файлов GLib (UTF8 в Windows)
mode : как в creat()
Возвращает : новый дескриптор файла, или -1 если произошла ошибка. Возвращаемое значение может использоваться точно также как значение из creat().

Начиная с версии 2.8


g_chdir ()

int         g_chdir                         (const gchar *path);

Оболочка для POSIX функции chdir(). Функция изменяет текущий каталог процесса на path.

Смотрите руководство вашей C библиотеки для больших деталей о chdir().

path : имя пути в кодировке имён файлов GLib (UTF8 в Windows)
Возвращает : 0 при успешном выполнении, -1 если произошла ошибка.

Начиная с версии 2.8


Glob-style pattern matching

Glob-style pattern matching — Сравнение строк с шаблонами содержащими '*' (wildcard) and '?' (joker).

Краткое описание


#include <glib.h>


            GPatternSpec;
GPatternSpec* g_pattern_spec_new            (const gchar *pattern);
void        g_pattern_spec_free             (GPatternSpec *pspec);
gboolean    g_pattern_spec_equal            (GPatternSpec *pspec1,
                                             GPatternSpec *pspec2);
gboolean    g_pattern_match                 (GPatternSpec *pspec,
                                             guint string_length,
                                             const gchar *string,
                                             const gchar *string_reversed);
gboolean    g_pattern_match_string          (GPatternSpec *pspec,
                                             const gchar *string);
gboolean    g_pattern_match_simple          (const gchar *pattern,
                                             const gchar *string);

Описание

Функции g_pattern_match* сравнивают строки с шаблонами содержащими '*' и '?' символы с семантикой похожей на стандартную функцию glob(): '*' соответствует произвольной, возможно пустой, строке, '?' соответствует произвольному символу.

Помните что в отличие от glob(), символ '/' может соответствовать символу подстановки, диапазон символов '[...]', '*' , '?' не может быть отброшен для включения как литеры в шаблон.

Когда множество строк должны быть сопоставлены с одним и тем же шаблоном, лучше собрать шаблон в GPatternSpec используя g_pattern_spec_new() и используя g_pattern_match_string() вместо g_pattern_match_simple(). Это избавляет от лишних перекомпиляций шаблона.

Детали

GPatternSpec

typedef struct _GPatternSpec GPatternSpec;

GPatternSpec это 'скомпилированная' форма шаблона. Эта структура непрозрачна и её поля не должны использоваться непосредственно.


g_pattern_spec_new ()

GPatternSpec* g_pattern_spec_new            (const gchar *pattern);

Компилирует шаблон в GPatternSpec.

pattern : строка в кодировке UTF-8 завершённая нулём.
Возвращает : вновь распределённая GPatternSpec.

g_pattern_spec_free ()

void        g_pattern_spec_free             (GPatternSpec *pspec);

Освобождает память распределённую для GPatternSpec.

pspec : GPatternSpec.

g_pattern_spec_equal ()

gboolean    g_pattern_spec_equal            (GPatternSpec *pspec1,
                                             GPatternSpec *pspec2);

Сравнивает две скомпилированных спецификации шаблона и возвращает соответствуют ли они одному набору строк.

pspec1 : GPatternSpec.
pspec2 : другая GPatternSpec.
Возвращает : Эквивалентны ли скомпилированные шаблоны.

g_pattern_match ()

gboolean    g_pattern_match                 (GPatternSpec *pspec,
                                             guint string_length,
                                             const gchar *string,
                                             const gchar *string_reversed);

Сопоставляет строку с скомпилированным шаблоном. Помещение правильной длины данной строки обязательно. Переворачивание строки может быть пропущено помещением NULL, это более эффективно если перевёрнутая версия строки для соответствия не под рукой, та как g_pattern_match() создаст её только если скомпилированный шаблон запросит обратное соответсвие.

Помните что, если код пользователя будет (возможно) соответствовать строке с множеством шаблонов содержащих символы подстановки, очень высока вероятность что некоторые шаблоны затребуют перевернутую строку. В этом случае, более эффективно обеспечить перевёрнутую строку для исключения множественного создания этого в разных вызовах g_pattern_match().

Помните так же что перевёрнутая строка в кодировке UTF-8 не может быть получена из g_strreverse(). Она работает только для строк не содержащих многобайтные символы. Glib предлагает функцию g_utf_strreverse() для переворачивания строк в кодировке UTF-8.

pspec : GPatternSpec.
string_length : длина string.
string : строка в кодировке UTF-8 для сопоставления.
string_reversed : перевёрнутая строка string или NULL.
Возвращает : TRUE если string соответствует pspec.

g_pattern_match_string ()

gboolean    g_pattern_match_string          (GPatternSpec *pspec,
                                             const gchar *string);

Сопоставляет строку с скомпилированным шаблоном. Если строка может соответствовать больше чем одному шаблону, рассмотрите использование g_pattern_match() вместо этой функции подставляя полностью перевёрнутую строку.

pspec : GPatternSpec.
string : строка в кодировке UTF-8 для сопоставления.
Возвращает : TRUE если string соответствует pspec.

g_pattern_match_simple ()

gboolean    g_pattern_match_simple          (const gchar *pattern,
                                             const gchar *string);

Сопоставляет строку с шаблоном полученным как строка. Если эта функция вызывается в цикле, более эффективно скомпилировать шаблон один раз с помощью g_pattern_spec_new() и вызвать g_pattern_match_string().

pattern : шаблон в кодировке UTF-8.
string : строка в кодировке UTF-8 для сопоставления.
Возвращает : TRUE если string соответствует pspec.

Hash Tables

Hash Tables — Связь между ключами и значениями для быстрого поиска.

Краткое описание


#include <glib.h>


            GHashTable;
GHashTable* g_hash_table_new                (GHashFunc hash_func,
                                             GEqualFunc key_equal_func);
GHashTable* g_hash_table_new_full           (GHashFunc hash_func,
                                             GEqualFunc key_equal_func,
                                             GDestroyNotify key_destroy_func,
                                             GDestroyNotify value_destroy_func);
guint       (*GHashFunc)                    (gconstpointer key);
gboolean    (*GEqualFunc)                   (gconstpointer a,
                                             gconstpointer b);
void        g_hash_table_insert             (GHashTable *hash_table,
                                             gpointer key,
                                             gpointer value);
void        g_hash_table_replace            (GHashTable *hash_table,
                                             gpointer key,
                                             gpointer value);
guint       g_hash_table_size               (GHashTable *hash_table);
gpointer    g_hash_table_lookup             (GHashTable *hash_table,
                                             gconstpointer key);
gboolean    g_hash_table_lookup_extended    (GHashTable *hash_table,
                                             gconstpointer lookup_key,
                                             gpointer *orig_key,
                                             gpointer *value);
void        g_hash_table_foreach            (GHashTable *hash_table,
                                             GHFunc func,
                                             gpointer user_data);
gpointer    g_hash_table_find               (GHashTable *hash_table,
                                             GHRFunc predicate,
                                             gpointer user_data);
void        (*GHFunc)                       (gpointer key,
                                             gpointer value,
                                             gpointer user_data);
gboolean    g_hash_table_remove             (GHashTable *hash_table,
                                             gconstpointer key);
gboolean    g_hash_table_steal              (GHashTable *hash_table,
                                             gconstpointer key);
guint       g_hash_table_foreach_remove     (GHashTable *hash_table,
                                             GHRFunc func,
                                             gpointer user_data);
guint       g_hash_table_foreach_steal      (GHashTable *hash_table,
                                             GHRFunc func,
                                             gpointer user_data);
void        g_hash_table_remove_all         (GHashTable *hash_table);
void        g_hash_table_steal_all          (GHashTable *hash_table);
gboolean    (*GHRFunc)                      (gpointer key,
                                             gpointer value,
                                             gpointer user_data);
#define     g_hash_table_freeze             (hash_table)
#define     g_hash_table_thaw               (hash_table)
void        g_hash_table_destroy            (GHashTable *hash_table);
GHashTable* g_hash_table_ref                (GHashTable *hash_table);
void        g_hash_table_unref              (GHashTable *hash_table);

gboolean    g_direct_equal                  (gconstpointer v1,
                                             gconstpointer v2);
guint       g_direct_hash                   (gconstpointer v);
gboolean    g_int_equal                     (gconstpointer v1,
                                             gconstpointer v2);
guint       g_int_hash                      (gconstpointer v);
gboolean    g_str_equal                     (gconstpointer v1,
                                             gconstpointer v2);
guint       g_str_hash                      (gconstpointer v);

Описание

GHashTable обеспечивает связь между ключами и значениями для наиболее быстрого поиска значения полученного ключа.

Помните что не ключи не их значения не копируются при помещении в GHashTable, поэтому они должны существовать для жизнеспособности GHashTable. Это значит использование статических строк допустимо, а временные строки (например создаваемые в буферах и возвращаемые GTK+ виджетами) должны быть скопированы с помощью g_strdup() перед вставкой в таблицу.

Если ключи и значения распределяются динамически, вы должны обязательно убедиться в их освобождении после удаления из GHashTable, а также когда они перезаписываются при новой вставке в GHashTable. Также не желательно смешивать статические строки и динамически-распределённые строки в GHashTable, потомучто тогда трудно определить должна ли строка освобождаться.

Для создания GHashTable, используйте g_hash_table_new().

Для вставки ключа и значения в GHashTable, используйте g_hash_table_insert().

Для поиска значения соответствующего полученному ключу используйте g_hash_table_lookup() и g_hash_table_lookup_extended().

Для удаления ключа и значения, используйте g_hash_table_remove().

Для вызова функции для каждой пары ключа и значения используйте g_hash_table_foreach().

Для уничтожения GHashTable используйте g_hash_table_destroy().

Детали

GHashTable

typedef struct _GHashTable GHashTable;

Структура GHashTable является непрозрачной структурой данных представляющей Hash Table. Доступ к ней может осуществляться только функциями описанными ниже.


g_hash_table_new ()

GHashTable* g_hash_table_new                (GHashFunc hash_func,
                                             GEqualFunc key_equal_func);

Создаёт новую GHashTable с количеством ссылок равным 1.

hash_func : функция для создания хэш значения из ключа. Хеш значения используются для определения места хранения ключей внутри структуры данных GHashTable. Функции g_direct_hash(), g_int_hash() и g_str_hash() обеспечивают некоторые основные типы ключей. Если hash_func это NULL, то используется g_direct_hash().
key_equal_func : функция проверяющая эквивалентность двух ключей. Используется при поиске ключа в GHashTable. Функции g_direct_equal(), g_int_equal() и g_str_equal() обеспечивают основные типы ключей. Если key_equal_func это NULL, ключи сравниваются непосредственно в стиле g_direct_equal(), но без накладных расходов вызова функции.
Возвращает : новая GHashTable.

g_hash_table_new_full ()

GHashTable* g_hash_table_new_full           (GHashFunc hash_func,
                                             GEqualFunc key_equal_func,
                                             GDestroyNotify key_destroy_func,
                                             GDestroyNotify value_destroy_func);

Создаёт новую GHashTable, похожа на g_hash_table_new() с количеством ссылок равным 1 и позволяет определять функции для освобождения памяти распределённой для ключа и значения которые получит вызов когда удалит элементы из GHashTable.

hash_func : функция для создания хеш значения из ключа.
key_equal_func : функция для проверки эквивалентности двух ключей.
key_destroy_func : функция освобождающая распределённую память для ключа используемая при удалении элемента из GHashTable или NULL если вам не нужно выполнять такую функцию.
value_destroy_func : функция освобождающая память, распределённую для значения, используемую при удалении элемента из GHashTable или NULL если вам не нужно выполнять такую функцию.
Возвращает : новая GHashTable.

GHashFunc ()

guint       (*GHashFunc)                    (gconstpointer key);

Специальный тип хеш функции которая помещается в g_hash_table_new() когда создаётся GHashTable.

В функцию помещается ключ и она должна вернуть хеш значение guint. Функции g_direct_hash(), g_int_hash() и g_str_hash() обеспечивают хеш-функции которые могут использоваться когда ключ gpointer, gint и gchar* соответственно.

ПОПРАВЬТЕ МЕНЯ: Здесь необходимо больше подробностей. Хеш-значения должны быть равномерно распределены по довольно большому диапазону? Модуль берётся с размером хеш таблицы (простое число) для поиска области памяти в которую помещается ключ. Функция должна быть очень быстрой, так как вызывается для каждого разыскиваемого ключа.

key : ключ.
Возвращает : хеш значение соответствующее ключу.

GEqualFunc ()

gboolean    (*GEqualFunc)                   (gconstpointer a,
                                             gconstpointer b);

Определяет тип функции используемой для проверки эквивалентности двух значений. Функция должна возвращать TRUE если оба значения эквивалентны или иначе FALSE.

a : первое значение.
b : значение для сравнения.
Возвращает : TRUE если a = b; иначе FALSE.

g_hash_table_insert ()

void        g_hash_table_insert             (GHashTable *hash_table,
                                             gpointer key,
                                             gpointer value);

Вставляет новый ключ и значение в GHashTable.

Если ключ уже существует в GHashTable его текущее значение переписывается новым. Если вы поместите value_destroy_func когда создаёте GHashTable, старое значение освобождается с помощью этой функции. Если вы поместите key_destroy_func когда создаёте GHashTable, помещаемый ключ освобождается с помощью этой функции.

hash_table : GHashTable.
key : вставляемый ключ.
value : значение связанное с ключом.

g_hash_table_replace ()

void        g_hash_table_replace            (GHashTable *hash_table,
                                             gpointer key,
                                             gpointer value);

Вставляет новый ключ и значение в GHashTable аналогично g_hash_table_insert(). Разница в том, что если ключ уже существует в GHashTable, он переписывается новым значением. Если вы поместили value_destroy_func когда создавали GHashTable, старое значение освобождается с помощью этой функции. Если вы поместили key_destroy_func когда создавали GHashTable, старый ключ освобождается с помощью этой функции.

hash_table : GHashTable.
key : ключ для вставки.
value : значение связываемое с ключом.

g_hash_table_size ()

guint       g_hash_table_size               (GHashTable *hash_table);

Возвращает количество элементов находящихся в GHashTable.

hash_table : GHashTable.
Возвращает : количество пар ключ/значение в GHashTable.

g_hash_table_lookup ()

gpointer    g_hash_table_lookup             (GHashTable *hash_table,
                                             gconstpointer key);

Находит ключ в GHashTable. Помните что эта функция не может отличить ключ который не представлен от ключа который представлен но имеет значение NULL. Если вам нужно знать о таком различии, используйте g_hash_table_lookup_extended().

hash_table : GHashTable.
key : ключ для поиска.
Возвращает : связанное значение, или NULL если ключ не найден.

g_hash_table_lookup_extended ()

gboolean    g_hash_table_lookup_extended    (GHashTable *hash_table,
                                             gconstpointer lookup_key,
                                             gpointer *orig_key,
                                             gpointer *value);

Находит ключ в GHashTable, возвращает оригинальный ключ и связанное значение gboolean которое TRUE если ключ был найден. Это полезно если вам нужно освободить память распределённую для оригинального ключа, например перед вызовом g_hash_table_remove().

hash_table : GHashTable.
lookup_key : ключ для поиска.
orig_key : возвращает оригинальный ключ.
value : возвращает значение связанное с ключом.
Возвращает : TRUE если ключ был найден в GHashTable.

g_hash_table_foreach ()

void        g_hash_table_foreach            (GHashTable *hash_table,
                                             GHFunc func,
                                             gpointer user_data);

Вызывает полученную функцию для каждой пары ключ/значение в GHashTable. В функцию помещается ключ и значение каждой пары, а также параметр user_data. Хеш таблица не может меняться пока функция перемещается через неё (вы не можете добавлять/удалять элементы). Для удаления всех элементов соответствующих предикату, используйте g_hash_table_foreach_remove().

hash_table : GHashTable.
func : функция вызываемая для каждой пары ключ/значение.
user_data : пользовательские данные помещаемые в функцию.

g_hash_table_find ()

gpointer    g_hash_table_find               (GHashTable *hash_table,
                                             GHRFunc predicate,
                                             gpointer user_data);

Вызывает полученную функцию для пар клю/значение в GHashTable, пока predicate не вернёт TRUE. В функцию помещается ключ и значение каждой пары, и полученный параметр user_data. Хеш таблица не может изменяться пока функция перемещается через неё (вы не можете добавлять/удалять элементы).

hash_table : GHashTable.
predicate : функция для проверки каждой пары ключ/значение на определённое свойство.
user_data : пользовательские данные помещаемые в функцию.
Возвращает : Значение первой возвращаемой пары ключ/значение, для которой функция вычислила TRUE. Если пара с требуемым свойством не найдена, возвращается NULL.

Начиная с версии 2.4


GHFunc ()

void        (*GHFunc)                       (gpointer key,
                                             gpointer value,
                                             gpointer user_data);

Определяет тип функции помещаемойв g_hash_table_foreach(). Она вызывается с каждой парой ключ/значение, вместе с параметром user_data который помещается в g_hash_table_foreach().

key : ключ.
value : значение соответствующее ключу.
user_data : пользовательские данные помещаемые в g_hash_table_foreach().

g_hash_table_remove ()

gboolean    g_hash_table_remove             (GHashTable *hash_table,
                                             gconstpointer key);

Удаляет ключ и связанное с ним значение из GHashTable.

Если GHashTable был создан используя g_hash_table_new_full(), ключ и значение освобождаются используя вставленную функцию уничтожения, иначе вы должны убедиться что освободили все динамически распределённые значения самостоятельно.

hash_table : GHashTable.
key : удаляемый ключ.
Возвращает : TRUE если ключ был найден и удалён из GHashTable.

g_hash_table_steal ()

gboolean    g_hash_table_steal              (GHashTable *hash_table,
                                             gconstpointer key);

Удаляет ключ и связанное с ним значение из GHashTable, без вызова функции уничтожения ключа и значения.

hash_table : GHashTable.
key : ключ для удаления.
Возвращает : TRUE если ключ был найден и удалён из GHashTable.

g_hash_table_foreach_remove ()

guint       g_hash_table_foreach_remove     (GHashTable *hash_table,
                                             GHRFunc func,
                                             gpointer user_data);

Вызывает полученную функцию для каждой пары ключ/значение в GHashTable. Если функция вернула TRUE, то ключ/значение удаляется из GHashTable. Если ключ или значение помещаются в функцию уничтожения при создании GHashTable, она используется для освобождения распределённой памяти удаляемых ключей и значений.

hash_table : GHashTable.
func : функция вызываемая для каждой пары ключ/значение.
user_data : пользовательские данные помещаемые в функцию.
Возвращает : количество удаляемых пар ключ/значение.

g_hash_table_foreach_steal ()

guint       g_hash_table_foreach_steal      (GHashTable *hash_table,
                                             GHRFunc func,
                                             gpointer user_data);

Вызывает полученную функцию для каждой пары ключ/значение в GHashTable. Если функция вернула TRUE, то пара ключ/значение удаляется из GHashTable, но функция уничтожения ключа или значения не вызывается.

hash_table : GHashTable.
func : функция вызываемая для каждой пары ключ/значение.
user_data : пользовательские данные помещаемые в функцию.
Возвращает : количество удаляемых пар ключ/значение.

g_hash_table_remove_all ()

void        g_hash_table_remove_all         (GHashTable *hash_table);

Удаляет все ключи и связанные с ними значения из GHashTable.

Если GHashTable была создана с использованием g_hash_table_new_full(), ключи и значения освобождаются используя помещённую функцию уничтожения, иначе вы должны убедиться что любые динамически распределённые значения освободили самостоятельно.

hash_table : GHashTable

Начиная с версии 2.12


g_hash_table_steal_all ()

void        g_hash_table_steal_all          (GHashTable *hash_table);

Удаляет все ключи и связанные с ними значения из GHashTable без вызова функции уничтожения ключа и значения.

hash_table : GHashTable.

Начиная с версии 2.12


GHRFunc ()

gboolean    (*GHRFunc)                      (gpointer key,
                                             gpointer value,
                                             gpointer user_data);

Определяет тип функции помещаемой в g_hash_table_foreach_remove(). Она вызывается с каждой парой ключ/значение, вместе с параметром user_data помещённым в g_hash_table_foreach_remove(). Она должна вернуть TRUE если пара ключ/значение должна быть удалена из GHashTable.

key : ключ.
value : значение связанное с ключом.
user_data : пользовательские данные помещаемые в g_hash_table_remove().
Возвращает : TRUE если пара ключ/значение должна быть удалена из GHashTable.

g_hash_table_freeze()

#define     g_hash_table_freeze(hash_table)

Внимание

g_hash_table_freeze устарела и не должна использоваться во вновь создаваемом коде.

Эта функция устарела и будет удалена в следующих релизах GLib. Она ничего не делает.

hash_table : GHashTable

g_hash_table_thaw()

#define     g_hash_table_thaw(hash_table)

Внимание

g_hash_table_thaw устарела и не должна использоваться во вновь создаваемом коде.

Эта функция устарела и будет удалена в следующих релизах GLib. Она ничего не делает.

hash_table : GHashTable

g_hash_table_destroy ()

void        g_hash_table_destroy            (GHashTable *hash_table);

Уничтожает все ключи и значения в GHashTable и уменьшает количество её ссылок на 1. Если ключи и/или значения распределены динамически, вы должны либо освободить сначала их или создать GHashTable с уничтожающим уведомлением используя g_hash_table_new_full(). В последнем случае функция уничтожения, помещённая вами, будет вызвана для всех ключей и значений в течении фазы разрушения.

hash_table : GHashTable.

g_hash_table_ref ()

GHashTable* g_hash_table_ref                (GHashTable *hash_table);

Автоматически увеличивает количество ссылок hash_table на одну. Эта функция MT-безопасна и может быть вызвана из любого потока.

hash_table : правильная GHashTable.
Возвращает : передачу в GHashTable.

Начиная с версии 2.10


g_hash_table_unref ()

void        g_hash_table_unref              (GHashTable *hash_table);

Автоматически уменьшает количество ссылок hash_table на одну. Если количество ссылок сброшено до 0, все ключи и значения будут уничтожены, а вся память, распределённая для хеш таблицы, освобождена. Эта функция MT-безопасна и может быть вызвана из любого потока.

hash_table : правильная GHashTable.

Начиная с версии 2.10


g_direct_equal ()

gboolean    g_direct_equal                  (gconstpointer v1,
                                             gconstpointer v2);

Сравнивает два аргумента gpointer и возвращает TRUE если они равны. Она может быть помещена в g_hash_table_new() как параметр key_equal_func, используя в качестве указателя ключ в GHashTable.

v1 : ключ.
v2 : ключ для сравнения с v1.
Возвращает : TRUE если два ключа равны.

g_direct_hash ()

guint       g_direct_hash                   (gconstpointer v);

Конвертирует gpointer в хеш значение. Она может быть помещена в g_hash_table_new() как параметр hash_func, используя в качестве указателя ключ в GHashTable.

v : gpointer key
Возвращает : хеш значение соответствующее ключу.

g_int_equal ()

gboolean    g_int_equal                     (gconstpointer v1,
                                             gconstpointer v2);

Сравнивает два значения gint и возвращает TRUE если они равны. Она может быть помещена в g_hash_table_new() как параметр key_equal_func, используя в качестве указателей на целочисленные ключи в GHashTable.

v1 : указатель на gint ключ.
v2 : указатель на gint ключ для сравнения с v1.
Возвращает : TRUE если оба ключа равны.

g_int_hash ()

guint       g_int_hash                      (gconstpointer v);

Конвертирует указатель на gint в хеш значение. Она может быть помещена в g_hash_table_new() как параметр hash_func, используя в качестве указателей на целочисленные значения ключи в GHashTable.

v : указатель на gint ключ
Возвращает : хеш значение соответствующее ключу.

g_str_equal ()

gboolean    g_str_equal                     (gconstpointer v1,
                                             gconstpointer v2);

Сравнивает две строки и возвращает TRUE если они равны. Она может быть помещена в g_hash_table_new() как параметр key_equal_func, используя в качестве строк ключи в GHashTable.

v1 : ключ.
v2 : ключ для сравнения с v1.
Возвращает : TRUE если два ключа равны.

g_str_hash ()

guint       g_str_hash                      (gconstpointer v);

Конвертирует строку в хеш значение. Она может помещаться в g_hash_table_new() как параметр hash_func, используя в качестве строки ключ в GHashTable.

v : строка ключ.
Возвращает : хеш значение соответствующее ключу.

Hook Functions

Hook Functions — поддержка для манипулирования списками hook-функций.

Краткое описание


#include <glib.h>


            GHookList;
void        (*GHookFinalizeFunc)            (GHookList *hook_list,
                                             GHook *hook);
            GHook;
void        (*GHookFunc)                    (gpointer data);
gboolean    (*GHookCheckFunc)               (gpointer data);

void        g_hook_list_init                (GHookList *hook_list,
                                             guint hook_size);
void        g_hook_list_invoke              (GHookList *hook_list,
                                             gboolean may_recurse);
void        g_hook_list_invoke_check        (GHookList *hook_list,
                                             gboolean may_recurse);
void        g_hook_list_marshal             (GHookList *hook_list,
                                             gboolean may_recurse,
                                             GHookMarshaller marshaller,
                                             gpointer marshal_data);
void        (*GHookMarshaller)              (GHook *hook,
                                             gpointer marshal_data);
void        g_hook_list_marshal_check       (GHookList *hook_list,
                                             gboolean may_recurse,
                                             GHookCheckMarshaller marshaller,
                                             gpointer marshal_data);
gboolean    (*GHookCheckMarshaller)         (GHook *hook,
                                             gpointer marshal_data);
void        g_hook_list_clear               (GHookList *hook_list);

GHook*      g_hook_alloc                    (GHookList *hook_list);
#define     g_hook_append                   ( hook_list, hook )
void        g_hook_prepend                  (GHookList *hook_list,
                                             GHook *hook);
void        g_hook_insert_before            (GHookList *hook_list,
                                             GHook *sibling,
                                             GHook *hook);
void        g_hook_insert_sorted            (GHookList *hook_list,
                                             GHook *hook,
                                             GHookCompareFunc func);
gint        (*GHookCompareFunc)             (GHook *new_hook,
                                             GHook *sibling);
gint        g_hook_compare_ids              (GHook *new_hook,
                                             GHook *sibling);

GHook*      g_hook_get                      (GHookList *hook_list,
                                             gulong hook_id);
GHook*      g_hook_find                     (GHookList *hook_list,
                                             gboolean need_valids,
                                             GHookFindFunc func,
                                             gpointer data);
gboolean    (*GHookFindFunc)                (GHook *hook,
                                             gpointer data);
GHook*      g_hook_find_data                (GHookList *hook_list,
                                             gboolean need_valids,
                                             gpointer data);
GHook*      g_hook_find_func                (GHookList *hook_list,
                                             gboolean need_valids,
                                             gpointer func);
GHook*      g_hook_find_func_data           (GHookList *hook_list,
                                             gboolean need_valids,
                                             gpointer func,
                                             gpointer data);

GHook*      g_hook_first_valid              (GHookList *hook_list,
                                             gboolean may_be_in_call);
GHook*      g_hook_next_valid               (GHookList *hook_list,
                                             GHook *hook,
                                             gboolean may_be_in_call);
enum        GHookFlagMask;
#define     G_HOOK_FLAGS                    (hook)
#define     G_HOOK_FLAG_USER_SHIFT

#define     G_HOOK                          (hook)
#define     G_HOOK_IS_VALID                 (hook)
#define     G_HOOK_ACTIVE                   (hook)
#define     G_HOOK_IN_CALL                  (hook)
#define     G_HOOK_IS_UNLINKED              (hook)

GHook*      g_hook_ref                      (GHookList *hook_list,
                                             GHook *hook);
void        g_hook_unref                    (GHookList *hook_list,
                                             GHook *hook);
void        g_hook_free                     (GHookList *hook_list,
                                             GHook *hook);
gboolean    g_hook_destroy                  (GHookList *hook_list,
                                             gulong hook_id);
void        g_hook_destroy_link             (GHookList *hook_list,
                                             GHook *hook);

Описание

GHookList, GHook и связанные с ними функции обеспечивают поддержку для списков hook-функций. Функции могут быть добавлены и удалены из списков, а список hook-функций может быть вызван.

Детали

GHookList

typedef struct {
  gulong	    seq_id;
  guint		    hook_size : 16;
  guint		    is_setup : 1;
  GHook		   *hooks;
  gpointer	    dummy3;
  GHookFinalizeFunc finalize_hook;
  gpointer	    dummy[2];
} GHookList;

Структура GHookList представляет список hook-функций.

gulong seq_id; следующий свободный GHook id.
guint hook_size : 16; размер элементов GHookList, в байтах.
guint is_setup : 1; 1 если GHookList была инициализирована.
GHook *hooks; первый элемент GHook в списке.
gpointer dummy3;
GHookFinalizeFunc finalize_hook; функция вызываемая для завершающего элемента GHook. По умолчанию вызывается разрушающая функция обработчика прерывания.
gpointer dummy[2];

GHookFinalizeFunc ()

void        (*GHookFinalizeFunc)            (GHookList *hook_list,
                                             GHook *hook);

Определяет тип функции вызываемой для завершающего прерывания в списке прерываний.

hook_list : GHookList.
hook : завершающее прерывание в hook_list.

GHook

typedef struct {
  gpointer	 data;
  GHook		*next;
  GHook		*prev;
  guint		 ref_count;
  gulong	 hook_id;
  guint		 flags;
  gpointer	 func;
  GDestroyNotify destroy;
} GHook;

Структура GHook представляет единственную hook-функцию в GHookList.

gpointer data; данные помещаемые в функцию когда вызвано прерывание.
GHook *next; указатель на следующее прерывание в списке.
GHook *prev; указатель на предыдущее прерывание в списке.
guint ref_count; количество ссылок на это прерывание.
gulong hook_id; id этого прерывания, который уникален внутри этого списка.
guint flags; флаги устанавливаемые для этого прерывания. Смотрите предопределённые флаги в GHookFlagMask.
gpointer func; функция вызываемая при возникновении этого прерывания. Возможными сигнатурами для этой функции являются GHookFunc и GHookCheckFunc.
GDestroyNotify destroy; по умолчанию finalize_hook функция GHookList вызывает этот элемент прерывания для завершения.

GHookFunc ()

void        (*GHookFunc)                    (gpointer data);

Определяет тип hook-функции которую может вызвать g_hook_list_invoke().

data : поле данных GHook помещаемых в hook-функцию.

GHookCheckFunc ()

gboolean    (*GHookCheckFunc)               (gpointer data);

Определяет тип функции которая может быть вызвана g_hook_list_invoke_check().

data : поле данных GHook помещаемых в hook-функцию.
Возвращает : FALSE если GHook должен быть разрушен.

g_hook_list_init ()

void        g_hook_list_init                (GHookList *hook_list,
                                             guint hook_size);

Инициализирует GHookList. Должна вызываться после использования GHookList.

hook_list : GHookList.
hook_size : размер каждого элемента в GHookList, обычно sizeof (GHook).

g_hook_list_invoke ()

void        g_hook_list_invoke              (GHookList *hook_list,
                                             gboolean may_recurse);

Вызывает все функции GHook в GHookList.

hook_list : GHookList.
may_recurse : TRUE если функции уже запущенные (например в другом потоке) могут быть вызваны. Если установить в FALSE, они пропускаются.

g_hook_list_invoke_check ()

void        g_hook_list_invoke_check        (GHookList *hook_list,
                                             gboolean may_recurse);

Вызывает все GHook функции в GHookList. Любая функция которая возвращает TRUE удаляется из GHookList.

hook_list : GHookList.
may_recurse : TRUE если функции которые уже выполняются (например в другом потоке) могут быть вызваны. Если установлено в FALSE, они пропускаются.

g_hook_list_marshal ()

void        g_hook_list_marshal             (GHookList *hook_list,
                                             gboolean may_recurse,
                                             GHookMarshaller marshaller,
                                             gpointer marshal_data);

Вызывает функцию в каждом допустимом GHook.

hook_list : GHookList.
may_recurse : TRUE если текущие выполняемые hooks (например в другом потоке) рассматриваются как допустимые. Если установлено в FALSE, они пропускаются.
marshaller : функция вызываемая для каждого элемента GHook.
marshal_data : данные для помещения в marshaller.

GHookMarshaller ()

void        (*GHookMarshaller)              (GHook *hook,
                                             gpointer marshal_data);

Определяет тип функции используемой в g_hook_list_marshal().

hook : GHook.
marshal_data : пользовательские данные.

g_hook_list_marshal_check ()

void        g_hook_list_marshal_check       (GHookList *hook_list,
                                             gboolean may_recurse,
                                             GHookCheckMarshaller marshaller,
                                             gpointer marshal_data);

Вызывает функцию для каждого допустимого GHook и уничтожает его если функция возвращает FALSE.

hook_list : GHookList.
may_recurse : TRUE если hooks выполняемые в текущий момент (например в другом потоке) рассматриваются как допустимые. Если установлено в FALSE, они пропускаются.
marshaller : функция вызываемая для каждого элемента GHook.
marshal_data : данные помещаемые в marshaller.

GHookCheckMarshaller ()

gboolean    (*GHookCheckMarshaller)         (GHook *hook,
                                             gpointer marshal_data);

Определяет тип функции используемой в g_hook_list_marshal_check().

hook : GHook.
marshal_data : пользовательские данные.
Возвращает : FALSE если hook должен быть уничтожен.

g_hook_list_clear ()

void        g_hook_list_clear               (GHookList *hook_list);

Удаляет все GHook элементы из GHookList.

hook_list : GHookList.

g_hook_alloc ()

GHook*      g_hook_alloc                    (GHookList *hook_list);

Распределяет место для GHook и инициализирует его.

hook_list : GHookList.
Возвращает : новый GHook.

g_hook_append()

#define     g_hook_append( hook_list, hook )

Добавляет GHook в конец GHookList.

hook_list : GHookList.
hook : GHook для добавления в конец hook_list.

g_hook_prepend ()

void        g_hook_prepend                  (GHookList *hook_list,
                                             GHook *hook);

Добавляет GHook в начало GHookList.

hook_list : GHookList.
hook : GHook для добавления в начало hook_list.

g_hook_insert_before ()

void        g_hook_insert_before            (GHookList *hook_list,
                                             GHook *sibling,
                                             GHook *hook);

Вставляет GHook в GHookList, перед полученным GHook.

hook_list : GHookList.
sibling : GHook перед которым вставляется новый GHook.
hook : the GHook для вставки.

g_hook_insert_sorted ()

void        g_hook_insert_sorted            (GHookList *hook_list,
                                             GHook *hook,
                                             GHookCompareFunc func);

Вставляет GHook в GHookList, сортируя полученной функцией.

hook_list : GHookList.
hook : GHook для вставки.
func : функция сравнения используемая для сортировки элементов GHook.

GHookCompareFunc ()

gint        (*GHookCompareFunc)             (GHook *new_hook,
                                             GHook *sibling);

Определяет тип функции используемой для сравнения GHook элементов в g_hook_insert_sorted().

new_hook : GHook для вставки.
sibling : GHook для сравнения с new_hook.
Возвращает : значение <= 0 если new_hook должен быть перед sibling.

g_hook_compare_ids ()

gint        g_hook_compare_ids              (GHook *new_hook,
                                             GHook *sibling);

Сравнивает ids двух GHook элементов, возвращает отрицательное значение если второй id больше первого.

new_hook : GHook.
sibling : GHook для сравнения с new_hook.
Возвращает : значение <= 0 если id sibling >= id new_hook.

g_hook_get ()

GHook*      g_hook_get                      (GHookList *hook_list,
                                             gulong hook_id);

Возвращает GHook с полученным id, или NULL если он не найден.

hook_list : GHookList.
hook_id : hook id.
Возвращает : GHook с полученным id, или NULL если он не найден.

g_hook_find ()

GHook*      g_hook_find                     (GHookList *hook_list,
                                             gboolean need_valids,
                                             GHookFindFunc func,
                                             gpointer data);

Ищет GHook в GHookList используя функцию для проверочного сравнения.

hook_list : GHookList.
need_valids : TRUE если GHook которые были разрушены должны быть пропущены.
func : функция вызываемая для каждого GHook, которая должна возвращать TRUE когда GHook найден.
data : данные помещаемые в func.
Возвращает : найденый GHook или NULL если соответствующий GHook не найден.

GHookFindFunc ()

gboolean    (*GHookFindFunc)                (GHook *hook,
                                             gpointer data);

Определяет тип функции помещаемой в g_hook_find().

hook : GHook.
data : пользовательские данные помещаемые в g_hook_find_func().
Возвращает : TRUE если требуемый GHook был найден.

g_hook_find_data ()

GHook*      g_hook_find_data                (GHookList *hook_list,
                                             gboolean need_valids,
                                             gpointer data);

Находит GHook в GHookList с полученными данными.

hook_list : GHookList.
need_valids : TRUE если GHook элементы которые были разрушены должны быть пропущены.
data : данные для поиска.
Возвращает : GHook с полученными data или NULL если нет соответсвующего GHook.

g_hook_find_func ()

GHook*      g_hook_find_func                (GHookList *hook_list,
                                             gboolean need_valids,
                                             gpointer func);

Находит GHook в GHookList с полученной функцией.

hook_list : GHookList.
need_valids : TRUE если GHook элементы которые были разрушены должны быть пропущены.
func : функция для поиска.
Возвращает : GHook с полученной func или NULL если соответсвующий GHook не найден.

g_hook_find_func_data ()

GHook*      g_hook_find_func_data           (GHookList *hook_list,
                                             gboolean need_valids,
                                             gpointer func,
                                             gpointer data);

Находит GHook в GHookList с полученной функцией и данными.

hook_list : GHookList.
need_valids : TRUE если GHook элементы которые были разрушены должны быть пропущены.
func : искомая функция.
data : искомые данные.
Возвращает : GHook с полученной func и data или NULL если соответствующий GHook не найден.

g_hook_first_valid ()

GHook*      g_hook_first_valid              (GHookList *hook_list,
                                             gboolean may_be_in_call);

Возвращает первый GHook в GHookList который небыл разрушен. Количество ссылок для GHook увеличивается, поэтому вы должны вызвать g_hook_unref() для его восстановления когда он больше не нужен. (Или вызвать g_hook_next_valid() если вы двигаетесь через GHookList.)

hook_list : GHookList.
may_be_in_call : TRUE если выполняемые в данный момент hooks (например в другом потоке) рассматриваются как допустимые. Если установить в FALSE, они пропускаются.
Возвращает : первый допустимый GHook, или NULL если нет допустимых.

g_hook_next_valid ()

GHook*      g_hook_next_valid               (GHookList *hook_list,
                                             GHook *hook,
                                             gboolean may_be_in_call);

Возвращает следующий GHook в GHookList который небыл разрушен. Количество ссылок для GHook уменьшается, поэтому вы должны вызвать g_hook_unref() для восстановления когда он больше не нужен. (Или вызывать g_hook_next_valid() пока не вернётся NULL.)

hook_list : GHookList.
hook : текущий GHook.
may_be_in_call : TRUE если hooks выполняемые в текущий момент (например в другом потоке) рассматриваются как допустимые. Если установить в FALSE, они пропускаются.
Возвращает : следующий допустимый GHook, или NULL если нет допустимых.

enum GHookFlagMask

typedef enum
{
  G_HOOK_FLAG_ACTIVE	    = 1 << 0,
  G_HOOK_FLAG_IN_CALL	    = 1 << 1,
  G_HOOK_FLAG_MASK	    = 0x0f
} GHookFlagMask;

Флаги используемые внутренней реализацией GHook.

G_HOOK_FLAG_ACTIVE устанавливается если hook небыл разрушен.
G_HOOK_FLAG_IN_CALL устанавливается если hook выполняется в текущий момент.
G_HOOK_FLAG_MASK Маска покрывающая все биты зарезервированные для hook флагов; смотрите G_HOOK_FLAGS_USER_SHIFT

G_HOOK_FLAGS()

#define	G_HOOK_FLAGS(hook)		(G_HOOK (hook)->flags)

Возвращает флаги hook.

hook : GHook.

G_HOOK_FLAG_USER_SHIFT

#define G_HOOK_FLAG_USER_SHIFT	(4)

Позиция первого бита который не зарезервирован для внутреннего использования реализацией GHook, то есть 1 << G_HOOK_FLAG_USER_SHIFT это первый бит который может использоваться для определённых приложением флагов.


G_HOOK()

#define	G_HOOK(hook)			((GHook*) (hook))

Приводит указатель на GHook*.

hook : указатель.

G_HOOK_IS_VALID()

#define     G_HOOK_IS_VALID(hook)

Возвращает TRUE если GHook допустим, то есть он в GHookList, он активен и он был разрушен.

hook : GHook.
Возвращает : TRUE если GHook допустим.

G_HOOK_ACTIVE()

#define     G_HOOK_ACTIVE(hook)

Возвращает TRUE если GHook активен, который обычно TRUE пока GHook разрушен.

hook : GHook.
Возвращает : TRUE если GHook активен.

G_HOOK_IN_CALL()

#define     G_HOOK_IN_CALL(hook)

Возвращает TRUE если GHook функция в текущий момент выполняется.

hook : GHook.
Возвращает : TRUE если GHook функция в текущий момент выполняется.

G_HOOK_IS_UNLINKED()

#define     G_HOOK_IS_UNLINKED(hook)

Возвращает TRUE если GHook не находится в GHookList.

hook : GHook.
Возвращает : TRUE если GHook не находится в GHookList.

g_hook_ref ()

GHook*      g_hook_ref                      (GHookList *hook_list,
                                             GHook *hook);

Увеличивает количество ссылок для GHook.

hook_list : GHookList.
hook : GHook для увеличения количества ссылок.
Возвращает : помещённый hook (Начиная с версии 2.6)

g_hook_unref ()

void        g_hook_unref                    (GHookList *hook_list,
                                             GHook *hook);

Уменьшает количество ссылок GHook. Если количество ссылок равно 0, GHook удаляется из GHookList и вызывается g_hook_free() для его освобождения.

hook_list : GHookList.
hook : GHook для отмены ссылки.

g_hook_free ()

void        g_hook_free                     (GHookList *hook_list,
                                             GHook *hook);

Вызывает GHookList hook_free функцию если она существует и освобождает память распределённую для GHook.

hook_list : GHookList.
hook : освобождаемая GHook.

g_hook_destroy ()

gboolean    g_hook_destroy                  (GHookList *hook_list,
                                             gulong hook_id);

Разрушает GHook, получая его ID.

hook_list : GHookList.
hook_id : hook ID.
Возвращает : TRUE если GHook был найден в GHookList и разрушен.

g_hook_destroy_link ()

void        g_hook_destroy_link             (GHookList *hook_list,
                                             GHook *hook);

Удаляет один GHook из GHookList, маркируя его как неактивный и вызывая для него g_hook_unref().

hook_list : GHookList.
hook : GHook для удаления.

Интернационализация

Internationalization — макросы поддерживающие gettext.

Краткое описание


#include <glib.h>
#include <glib/gi18n.h>


#define     _                               (String)
#define     Q_                              (String)
#define     N_                              (String)
const gchar* g_strip_context                (const gchar *msgid,
                                             const gchar *msgval);

const gchar* const * g_get_language_names   (void);

Описание

GLib не требует от пользователей использовать специальный метод интернационализации. А так как GLib сама локализована с использованием механизма gettext(), является естественным предложение фактического стандарта gettext() поддерживающего макросы в простой для использования форме.

Для использования этих макросов в приложениях, вы должны включить glib/gi18n.h. Для использования в библиотеке, вы должны включить glib/gi18n-lib.h после определения макроса GETTEXT_PACKAGE соответственно для вашей библиотеки:

#define GETTEXT_PACKAGE "gtk20"
#include <glib/gi18n-lib.h>

Детали

_()

#define     _(String)

Маркирует строку для перевода, заменяется переведённой строкой во время выполнения.

String : строка для перевода

Начиная с версии 2.4


Q_()

#define     Q_(String)

Аналогично _(), но применяет g_strip_context() для перевода. Это имеет преимущество, потомучто строка может быть дополнена префиксом для гарантии уникальности и обеспечения содержимого для перевода.

Один случай использования приведён в руководстве gettext - это перевод GUI, где можно снять неоднозначность двух меню "Open" как "File|Open" и "Printer|Open". Другой способ использования - это строка "Russian" которая может иметь разный перевод в зависимости от того является ли она названием набора символов или языка. Это может быть решено при помощи "charset|Russian" и "language|Russian".

String : строка для перевода, с префиксом отделённым знаком '|', который не должен транслироваться

Начиная с версии 2.4


N_()

#define     N_(String)

Маркирует строку для перевода, заменяется не переведённой строкой во время выполнения. Это полезно в ситуациях где переведённые строки не могут быть использованы напрямую, например в инициализаторах строковых массивов.

     {
       static const char *messages[] = {
         N_("некоторое очень значимое сообщение"),
         N_("и ещё одно")
       };
       const char *string;
       ...
       string
         = index > 1 ? _("сообщение по умолчанию") : gettext (messages[index]);
     
       fputs (string);
       ...
     }
String : строка для перевода

Начиная с версии 2.4


g_strip_context ()

const gchar* g_strip_context                (const gchar *msgid,
                                             const gchar *msgval);

Вспомогательная функция для поддержки gettext() (смотрите Q_()).

msgid : строка
msgval : другая строка
Возвращает : msgval, если msgval не идентичен msgid и содержит символ '|', в этом случае возвращается указатель на подстроку msgid после первого символа '|'.

Начиная с версии 2.4


g_get_language_names ()

const gchar* const * g_get_language_names   (void);

Вычисляет список применимых имён локалей, которые могут быть использованы например для конструирования locale-зависимых имён файлов или поиска путей. Возвращаемый список сортируется от самого желательного до менее желательного и всегда содержит локаль по умолчанию "C".

Например, если LANGUAGE=de:en_US, то возвращаемый список будет "de", "en_US", "en", "C".

Эта функция консультируется с переменными окружения LANGUAGE, LC_ALL, LC_MESSAGES и LANG для поиска списка локалей определённых пользователем.

Возвращает : NULL-завершённый массив строк которыми владеет GLib и они не должны освобождаться или изменяться.

Начиная с версии 2.6

Смотрите также

Руководство gettext.


IO Channels

IO Channels — Переносимая поддержка использования файлов, каналов и сокетов.

Краткое описание


#include <glib.h>


            GIOChannel;

GIOChannel* g_io_channel_unix_new           (int fd);
gint        g_io_channel_unix_get_fd        (GIOChannel *channel);
GIOChannel* g_io_channel_win32_new_fd       (gint fd);
GIOChannel* g_io_channel_win32_new_socket   (gint socket);
GIOChannel* g_io_channel_win32_new_messages (guint hwnd);

void        g_io_channel_init               (GIOChannel *channel);

GIOChannel* g_io_channel_new_file           (const gchar *filename,
                                             const gchar *mode,
                                             GError **error);
GIOStatus   g_io_channel_read_chars         (GIOChannel *channel,
                                             gchar *buf,
                                             gsize count,
                                             gsize *bytes_read,
                                             GError **error);
GIOStatus   g_io_channel_read_unichar       (GIOChannel *channel,
                                             gunichar *thechar,
                                             GError **error);
GIOStatus   g_io_channel_read_line          (GIOChannel *channel,
                                             gchar **str_return,
                                             gsize *length,
                                             gsize *terminator_pos,
                                             GError **error);
GIOStatus   g_io_channel_read_line_string   (GIOChannel *channel,
                                             GString *buffer,
                                             gsize *terminator_pos,
                                             GError **error);
GIOStatus   g_io_channel_read_to_end        (GIOChannel *channel,
                                             gchar **str_return,
                                             gsize *length,
                                             GError **error);
GIOStatus   g_io_channel_write_chars        (GIOChannel *channel,
                                             const gchar *buf,
                                             gssize count,
                                             gsize *bytes_written,
                                             GError **error);
GIOStatus   g_io_channel_write_unichar      (GIOChannel *channel,
                                             gunichar thechar,
                                             GError **error);
GIOStatus   g_io_channel_flush              (GIOChannel *channel,
                                             GError **error);
GIOStatus   g_io_channel_seek_position      (GIOChannel *channel,
                                             gint64 offset,
                                             GSeekType type,
                                             GError **error);
enum        GSeekType;
GIOStatus   g_io_channel_shutdown           (GIOChannel *channel,
                                             gboolean flush,
                                             GError **err);

enum        GIOStatus;
enum        GIOChannelError;
#define     G_IO_CHANNEL_ERROR
GIOChannelError g_io_channel_error_from_errno
                                            (gint en);

GIOChannel* g_io_channel_ref                (GIOChannel *channel);
void        g_io_channel_unref              (GIOChannel *channel);

GSource*    g_io_create_watch               (GIOChannel *channel,
                                             GIOCondition condition);
guint       g_io_add_watch                  (GIOChannel *channel,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data);
guint       g_io_add_watch_full             (GIOChannel *channel,
                                             gint priority,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data,
                                             GDestroyNotify notify);
enum        GIOCondition;
gboolean    (*GIOFunc)                      (GIOChannel *source,
                                             GIOCondition condition,
                                             gpointer data);

            GIOFuncs;

gsize       g_io_channel_get_buffer_size    (GIOChannel *channel);
void        g_io_channel_set_buffer_size    (GIOChannel *channel,
                                             gsize size);
GIOCondition g_io_channel_get_buffer_condition
                                            (GIOChannel *channel);
GIOFlags    g_io_channel_get_flags          (GIOChannel *channel);
GIOStatus   g_io_channel_set_flags          (GIOChannel *channel,
                                             GIOFlags flags,
                                             GError **error);
enum        GIOFlags;
const gchar* g_io_channel_get_line_term     (GIOChannel *channel,
                                             gint *length);
void        g_io_channel_set_line_term      (GIOChannel *channel,
                                             const gchar *line_term,
                                             gint length);
gboolean    g_io_channel_get_buffered       (GIOChannel *channel);
void        g_io_channel_set_buffered       (GIOChannel *channel,
                                             gboolean buffered);
const gchar* g_io_channel_get_encoding      (GIOChannel *channel);
GIOStatus   g_io_channel_set_encoding       (GIOChannel *channel,
                                             const gchar *encoding,
                                             GError **error);
gboolean    g_io_channel_get_close_on_unref (GIOChannel *channel);
void        g_io_channel_set_close_on_unref (GIOChannel *channel,
                                             gboolean do_close);


GIOError    g_io_channel_read               (GIOChannel *channel,
                                             gchar *buf,
                                             gsize count,
                                             gsize *bytes_read);
enum        GIOError;
GIOError    g_io_channel_write              (GIOChannel *channel,
                                             const gchar *buf,
                                             gsize count,
                                             gsize *bytes_written);
GIOError    g_io_channel_seek               (GIOChannel *channel,
                                             gint64 offset,
                                             GSeekType type);
void        g_io_channel_close              (GIOChannel *channel);

Описание

Тип данных GIOChannel предназначен для обеспечения переносимого метода использования файловых дескрипторов, каналов и сокетов, интегрируя их в main event loop. В настоящий момент доступна полная поддержка на UNIX платформах, поддержка для Windows выполнена только частично.

Для создания новой GIOChannel в UNIX системах используйте g_io_channel_unix_new(). Это работает для простых дескрипторов файла, каналов и сокетов. Альтернативно, канал может быть создан для файла независимым от системы способом используя g_io_channel_new_file().

Как только GIOChannel создана, она может использоваться обычным способом в функциях g_io_channel_read_chars(), g_io_channel_write_chars(), g_io_channel_seek_position() и g_io_channel_shutdown().

Для добавления GIOChannel в основной цикл событий используйте g_io_add_watch() или g_io_add_watch_full(). Так определяется какие события вас интересуют в GIOChannel и обеспечивается функция которая будет вызываться каждый раз когда происходит это событие.

GIOChannel создаётся с начальным количеством ссылок равным 1. Функции g_io_channel_ref() и g_io_channel_unref() могут использоваться для увеличения и уменьшения количества ссылок соответственно. Когда количество ссылок достигло 0, GIOChannel освобождается (хотя она не закрывается автоматически, если не создана с использованием g_io_channel_new_from_file()). Использование g_io_add_watch() или g_io_add_watch_full() увеличивает количество ссылок каналов.

Новые функции g_io_channel_read_chars(), g_io_channel_read_line(), g_io_channel_read_line_string(), g_io_channel_read_to_end(), g_io_channel_write_chars(), g_io_channel_seek_position(), и g_io_channel_flush() не должны использоваться совместно с устаревшими функциями g_io_channel_read(), g_io_channel_write(), и g_io_channel_seek() в одном и том же канале.

Детали

GIOChannel

typedef struct {
} GIOChannel;

Структура данных представляющая IO Channel (канал ввода-вывода). Поля этой структуры должны рассматриваться как закрытые и могут использоваться только следующими функциями.


g_io_channel_unix_new ()

GIOChannel* g_io_channel_unix_new           (int fd);

Создаёт новую GIOChannel полученного дескриптора файла. В UNIX системах это работает для простых файлов, каналов и сокетов.

Возвращаемая GIOChannel имеет количество ссылок равное 1.

Кодировкой по умолчанию для GIOChannel является UTF-8. Если ваша программа читает вывод из команд используя via pipe, вам может понадобиться установить кодировку в текущую кодировку локали (смотрите g_get_charset()) с помощью функции g_io_channel_set_encoding().

Если вы хотите читать исходные двоичные данные без интерпретации, то вызовите g_io_channel_set_encoding() функцию с параметром кодировки равным NULL.

Эта функция GLib доступна также в Windows, но вы должны избегать использования её в Windows. Область дескрипторов файла и сокетов перекрывается. Здесь нет способа для GLib узнать что вы подразумеваете в случае помещения в качестве аргументов в эту функцию и правильного дескриптора файла и сокета. Если это происходит то выдаётся предупреждение, а GLib предполагает что это дескриптор файла который вы подразумевали.

fd : дескриптор файла.
Возвращает : новая GIOChannel.

g_io_channel_unix_get_fd ()

gint        g_io_channel_unix_get_fd        (GIOChannel *channel);

Возвращает дескриптор файла GIOChannel.

В Windows эта функция вернёт дескриптор файла или сокет GIOChannel.

channel : GIOChannel, созданная с помощью g_io_channel_unix_new().
Возвращает : дескриптор файла GIOChannel.

g_io_channel_win32_new_fd ()

GIOChannel* g_io_channel_win32_new_fd       (gint fd);

Создаёт новую GIOChannel получая дескриптор файла в Windows. Работает для дескрипторов файлов из C runtime.

Эта функция работает для дескрипторов файлов которые возвращают open(), creat(), pipe() и fileno() вызовы в Microsoft C runtime. Для обоснованного использования этой функции ваш код должен использовать туже C runtime которую использует GLib, которой является msvcrt.dll. Помните что текущий компилятор Microsoft не подходит для сборки кода который использует msvcrt.dll. Последняя версия компилятора Microsoft которая поддерживала использование msvcrt.dll как C runtime была версия 6. Компилятор GNU и инструменты для Windows, также известные как Mingw, полностью поддерживают msvcrt.dll.

Если вы создали GIOChannel для дескриптора файла и запустили её просмотр (опрос), вы не должны вызывать read() для дескриптора файла. Это потому, что добавление опроса для дескриптора файла реализовано в GLib на платформе Windows с помощью запуска потока который остаётся блокированным в read() из дескриптора файла больше времени. Все читатели дескриптора файла должны быть выполнены этим внутренним потоком GLib. Ваш код должен вызывать только g_io_channel_read().

Эта функция доступна только в GLib для Windows.

fd : дескриптор файла библиотеки C.
Возвращает : новая GIOChannel.

g_io_channel_win32_new_socket ()

GIOChannel* g_io_channel_win32_new_socket   (gint socket);

Создаёт новую GIOChannel получая сокет в Windows.

Эта функция работает для сокетов созданных при помощи Winsock. Она доступна только в GLib для Windows.

Опрос GSource создаёт канал просмотра для сокета помещая сокет в не блокированный режим. Это неизбежный побочный эффект реализации.

socket :
Возвращает : новая GIOChannel.

g_io_channel_win32_new_messages ()

GIOChannel* g_io_channel_win32_new_messages (guint hwnd);

Создаёт новую GIOChannel получая обработку окна в Windows.

Эта функция создаёт GIOChannel которая может использоваться для опроса сообщений Windows запрашиваемого окна.

hwnd : обрабатываемое окно.
Возвращает : новая GIOChannel.

g_io_channel_init ()

void        g_io_channel_init               (GIOChannel *channel);

Инициализирует структуру GIOChannel. Вызывается каждой из вышеупомянутых функций когда создаётся GIOChannel, а также часто необходима для разработчиков приложений (если вы создаёте новый тип GIOChannel).

channel : GIOChannel.

g_io_channel_new_file ()

GIOChannel* g_io_channel_new_file           (const gchar *filename,
                                             const gchar *mode,
                                             GError **error);

Открывает файл filename как GIOChannel используя режим mode. Этот канал будет закрыт при сбросе последней ссылки на него, поэтому нет необходимости вызывать g_io_channel_close() (такое выполнение не вызовет никаких проблем, пока не попытается обратиться к уже закрытому каналу).

filename : строка содержащая имя файла.
mode : Один из режимов "r", "w", "a", "r+", "w+", "a+". Тоже самое как в fopen().
error : расположение возвращаемой ошибки типа G_FILE_ERROR.
Возвращает : GIOChannel при успешном выполнении, NULL при неудаче.

g_io_channel_read_chars ()

GIOStatus   g_io_channel_read_chars         (GIOChannel *channel,
                                             gchar *buf,
                                             gsize count,
                                             gsize *bytes_read,
                                             GError **error);

Замена для g_io_channel_read() с новым API.

channel : GIOChannel
buf : буфер из которого читаются данные
count : размер буфера. Помните что буфер может быть заполнен не полностью если оставшиеся данные не полный символ.
bytes_read : количество читаемых байт. Может быть ноль даже при удаче, если количество < 6 а кодировка каналов не-NULL. Это указывает что следующий символ UTF-8 слишком большой для буфера.
error : расположение возвращаемой ошибки типа GConvertError или GIOChannelError.
Возвращает : состояние операции.

g_io_channel_read_unichar ()

GIOStatus   g_io_channel_read_unichar       (GIOChannel *channel,
                                             gunichar *thechar,
                                             GError **error);

Эта функция не может быть вызвана для канала с NULL кодировкой.

channel : GIOChannel
thechar : расположение возвращаемого символа
error : расположение возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : GIOStatus

g_io_channel_read_line ()

GIOStatus   g_io_channel_read_line          (GIOChannel *channel,
                                             gchar **str_return,
                                             gsize *length,
                                             gsize *terminator_pos,
                                             GError **error);

Читает строку, включая завершающий символ(ы), из GIOChannel во вновь распределённой строке. str_return будет содержать распределённую память если возвращаемое значение G_IO_STATUS_NORMAL.

channel : GIOChannel
str_return : Читаемая строка из GIOChannel, включая завершающий символ. Эти данные должны освобождаться с помощью g_free() когда больше не нужны. Это nul-terminated строка. Если возвращаемая length равна нулю, то вместо этого она будет NULL.
length : размещение для сохранения длины читаемых данных, или NULL
terminator_pos : размещение для сохранения позиции завершающей строку, или NULL
error : расположение для возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : статус операции.

g_io_channel_read_line_string ()

GIOStatus   g_io_channel_read_line_string   (GIOChannel *channel,
                                             GString *buffer,
                                             gsize *terminator_pos,
                                             GError **error);

Читает строку из GIOChannel, используя GString как буфер.

channel : GIOChannel
buffer : GString в который записывается строка. Если buffer уже содержит данные, они будут перезаписаны.
terminator_pos : расположение для сохранения позиции завершения строки, или NULL
error : расположение для сохранения ошибки типа GConvertError или GIOChannelError
Возвращает : состояние операции.

g_io_channel_read_to_end ()

GIOStatus   g_io_channel_read_to_end        (GIOChannel *channel,
                                             gchar **str_return,
                                             gsize *length,
                                             GError **error);

Читает все оставшиеся данные из файла.

channel : GIOChannel
str_return : расположение для хранения указателя на строку содержащую оставшиеся данные в GIOChannel. Эти данные должны освобождаться с помощью g_free() когда больше не нужны. Эти данные завершаются дополнительным символом nul, но могут быть другие nuls в предыдущих данных.
length : расположение для хранения длины данных
error : расположение для возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : G_IO_STATUS_NORMAL при успешном выполнении. Эта функция никогда не возвращает G_IO_STATUS_EOF.

g_io_channel_write_chars ()

GIOStatus   g_io_channel_write_chars        (GIOChannel *channel,
                                             const gchar *buf,
                                             gssize count,
                                             gsize *bytes_written,
                                             GError **error);

Замена для g_io_channel_write() с новым API.

В seekable каналах с кодировкой отличающейся от NULL или UTF-8, смешивание чтения и записи недопустимо. Вызов g_io_channel_write_chars() может быть сделан только в канале из которого данные были прочитаны в случае описанном в документации для g_io_channel_set_encoding().

channel : GIOChannel
buf : буфер из которого записываются данные
count : размер буфера. Если -1, буфер применяется для nul-terminated строки.
bytes_written : количество записываемых байт. Может быть не нулевым даже если возвращаемое значение не G_IO_STATUS_NORMAL. Если возвращаемое значение G_IO_STATUS_NORMAL и канал заблокирован, значение всегда эквивалентно count если count >= 0.
error : Расположение возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : статус операции.

g_io_channel_write_unichar ()

GIOStatus   g_io_channel_write_unichar      (GIOChannel *channel,
                                             gunichar thechar,
                                             GError **error);

Эта функция не должна вызываться в канале с NULL кодировкой.

channel : GIOChannel
thechar : символ
error : расположение возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : GIOStatus

g_io_channel_flush ()

GIOStatus   g_io_channel_flush              (GIOChannel *channel,
                                             GError **error);

Синхронизирует данные буфера записанные в памяти и на диске для GIOChannel.

channel : GIOChannel
error : расположение возвращаемой ошибки типа GIOChannelError
Возвращает : статус операции: G_IO_CHANNEL_NORMAL, G_IO_CHANNEL_AGAIN, или G_IO_CHANNEL_ERROR.

g_io_channel_seek_position ()

GIOStatus   g_io_channel_seek_position      (GIOChannel *channel,
                                             gint64 offset,
                                             GSeekType type,
                                             GError **error);

Замена для g_io_channel_seek() с новым API.

channel : GIOChannel
offset : смещение в байтах из позиции определённой с помощью type
type : GSeekType. Тип G_SEEK_CUR допустим только когда допустим вызов g_io_channel_set_encoding(). Смотрите документацию для g_io_channel_set_encoding() для детального изучения.
error : расположение возвращаемой ошибки типа GIOChannelError
Возвращает : статус операции.

enum GSeekType

typedef enum
{
  G_SEEK_CUR,
  G_SEEK_SET,
  G_SEEK_END
} GSeekType;

Перечисление определяющее начальную позицию для g_io_channel_seek_position() операции.

G_SEEK_CUR текущая позиция в файле.
G_SEEK_SET начало файла.
G_SEEK_END конец файла.

g_io_channel_shutdown ()

GIOStatus   g_io_channel_shutdown           (GIOChannel *channel,
                                             gboolean flush,
                                             GError **err);

Закрывает IO канал. Любые данные ждущие обработки будут записаны на диск если параметр flush равен TRUE. Канал не освобождается пока последняя ссылка не сброшена с помощью g_io_channel_unref().

channel : GIOChannel
flush : если TRUE, ожидающие обработки данные записываются на диск синхронизируя содержимое памяти и диска
err : расположение для хранения GIOChannelError
Возвращает : статус операции.

enum GIOStatus

typedef enum
{
  G_IO_STATUS_ERROR,
  G_IO_STATUS_NORMAL,
  G_IO_STATUS_EOF,
  G_IO_STATUS_AGAIN
} GIOStatus;

Статусы возвращаемые большинством GIOFuncs функций.

G_IO_STATUS_ERROR произошла ошибка.
G_IO_STATUS_NORMAL удачное завершение операции.
G_IO_STATUS_EOF конец файла.
G_IO_STATUS_AGAIN ресурсы временно недоступны.

enum GIOChannelError

typedef enum
{
  /* Derived from errno */
  G_IO_CHANNEL_ERROR_FBIG,
  G_IO_CHANNEL_ERROR_INVAL,
  G_IO_CHANNEL_ERROR_IO,
  G_IO_CHANNEL_ERROR_ISDIR,
  G_IO_CHANNEL_ERROR_NOSPC,
  G_IO_CHANNEL_ERROR_NXIO,
  G_IO_CHANNEL_ERROR_OVERFLOW,
  G_IO_CHANNEL_ERROR_PIPE,
  /* Other */
  G_IO_CHANNEL_ERROR_FAILED
} GIOChannelError;

Коды ошибок возвращаемые GIOChannel операциями.

G_IO_CHANNEL_ERROR_FBIG файл слишком большой.
G_IO_CHANNEL_ERROR_INVAL недопустимый аргумент.
G_IO_CHANNEL_ERROR_IO ошибка IO.
G_IO_CHANNEL_ERROR_ISDIR файл является каталогом.
G_IO_CHANNEL_ERROR_NOSPC нет свободного пространства на диске.
G_IO_CHANNEL_ERROR_NXIO нет такого устройства или адреса.
G_IO_CHANNEL_ERROR_OVERFLOW значение слишком большое для определения типа данных.
G_IO_CHANNEL_ERROR_PIPE испорченный канал.
G_IO_CHANNEL_ERROR_FAILED какая то другая ошибка.

G_IO_CHANNEL_ERROR

#define G_IO_CHANNEL_ERROR g_io_channel_error_quark()

Ошибочная область для GIOChannel операций. Ошибки в этой области будут из GIOChannelError перечисления. Смотрите GError для информации об ошибочных областях.


g_io_channel_error_from_errno ()

GIOChannelError g_io_channel_error_from_errno
                                            (gint en);

Конвертирует номер ошибки errno в GIOChannelError.

en : номер ошибки errno, например EINVAL.
Возвращает : GIOChannelError номер ошибки, например G_IO_CHANNEL_ERROR_INVAL.

g_io_channel_ref ()

GIOChannel* g_io_channel_ref                (GIOChannel *channel);

Увеличивает количество ссылок GIOChannel.

channel : GIOChannel.
Возвращает : channel в который был помещён (Начиная с версии 2.6)

g_io_channel_unref ()

void        g_io_channel_unref              (GIOChannel *channel);

Уменьшает количество ссылок GIOChannel.

channel : GIOChannel.

g_io_create_watch ()

GSource*    g_io_create_watch               (GIOChannel *channel,
                                             GIOCondition condition);

Создаёт GSource которая отправляется когда встретилось condition для данного channel. Например, если условие G_IO_IN, источник будет отправлен когда появятся данные доступные для чтения. g_io_add_watch() - это более простой интерфейс для тех же самых функциональных возможностей, в случае когда вы хотите добавить в основной цикл по умолчанию приоритет по умолчанию.

В Windows, опрос GSource создаётся для просматриваемого канала для сокета, помещая сокет в деблокированный режим. Этот побочный эффект реализации неизбежен.

channel : GIOChannel to watch
condition : прсматриваемое условие
Возвращает : новая GSource

g_io_add_watch ()

guint       g_io_add_watch                  (GIOChannel *channel,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data);

Добавляет GIOChannel в основной цикл собития с приоритетом по умолчанию.

channel : GIOChannel.
condition : условие для просмотра.
func : функция вызываемая когда условие удовлетворено.
user_data : пользовательские данные помещаемые в func.
Возвращает : id источника события.

g_io_add_watch_full ()

guint       g_io_add_watch_full             (GIOChannel *channel,
                                             gint priority,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data,
                                             GDestroyNotify notify);

Добавляет GIOChannel в основной цикл события с полученным приоритетом.

channel : GIOChannel.
priority : приоритет GIOChannel источника.
condition : рассматриваемое условие.
func : функция вызываемая при удовлетворении условия.
user_data : пользовательские данные помещаемые в func.
notify : функция вызываемая при удалении источника.
Возвращает : id источника события.

enum GIOCondition

typedef enum
{
  G_IO_IN	GLIB_SYSDEF_POLLIN,
  G_IO_OUT	GLIB_SYSDEF_POLLOUT,
  G_IO_PRI	GLIB_SYSDEF_POLLPRI,
  G_IO_ERR	GLIB_SYSDEF_POLLERR,
  G_IO_HUP	GLIB_SYSDEF_POLLHUP,
  G_IO_NVAL	GLIB_SYSDEF_POLLNVAL
} GIOCondition;

Побитовые комбинации представляющие рассматриваемые условия для источника события.

G_IO_IN есть данные для чтения.
G_IO_OUT данные могут быть записаны (без блокировки).
G_IO_PRI есть неотложные данные для чтения.
G_IO_ERR ошибочное условие.
G_IO_HUP зависание (соединение прервано, обычно для каналов и сокетов).
G_IO_NVAL неправильный запрос. Дескриптор файла не открыт.

GIOFunc ()

gboolean    (*GIOFunc)                      (GIOChannel *source,
                                             GIOCondition condition,
                                             gpointer data);

Определяет тип функции помещаемой в g_io_add_watch() или g_io_add_watch_full(), которая вызывается когда запрашиваемое условие в GIOChannel удовлетворено.

source : источник события GIOChannel.
condition : условие которое должно удовлетворяться.
data : пользовательские данные устанавливаемые в g_io_add_watch() или g_io_add_watch_full().
Возвращает : функция должна вернуть FALSE если источник события должен быть удалён.

GIOFuncs

typedef struct {
  GIOStatus (*io_read)           (GIOChannel   *channel, 
			          gchar        *buf, 
				  gsize         count,
				  gsize        *bytes_read,
				  GError      **err);
  GIOStatus (*io_write)          (GIOChannel   *channel, 
				  const gchar  *buf, 
				  gsize         count,
				  gsize        *bytes_written,
				  GError      **err);
  GIOStatus (*io_seek)           (GIOChannel   *channel, 
				  gint64        offset, 
				  GSeekType     type,
				  GError      **err);
  GIOStatus  (*io_close)         (GIOChannel   *channel,
				  GError      **err);
  GSource*   (*io_create_watch)  (GIOChannel   *channel,
				  GIOCondition  condition);
  void       (*io_free)          (GIOChannel   *channel);
  GIOStatus  (*io_set_flags)     (GIOChannel   *channel,
                                  GIOFlags      flags,
				  GError      **err);
  GIOFlags   (*io_get_flags)     (GIOChannel   *channel);
} GIOFuncs;

Таблица функций используемых для обработки разных типов GIOChannel обычным способом.


g_io_channel_get_buffer_size ()

gsize       g_io_channel_get_buffer_size    (GIOChannel *channel);

Получает размер буфера.

channel : GIOChannel
Возвращает : размер буфера.

g_io_channel_set_buffer_size ()

void        g_io_channel_set_buffer_size    (GIOChannel *channel,
                                             gsize size);

Устанавливает размер буфера.

channel : GIOChannel
size : размер буфера. 0 == подобрать наилучший размер

g_io_channel_get_buffer_condition ()

GIOCondition g_io_channel_get_buffer_condition
                                            (GIOChannel *channel);

Эта функция возвращает GIOCondition в зависимости от того, есть ли данные для чтения или свободное пространство для записи данных во внутренние буферы GIOChannel. Могут устанавливаться только флаги G_IO_IN и G_IO_OUT.

channel : GIOChannel
Возвращает : GIOCondition

g_io_channel_get_flags ()

GIOFlags    g_io_channel_get_flags          (GIOChannel *channel);

Получает текущие флаги для GIOChannel, включая флаги только для чтения такие как G_IO_FLAG_IS_READABLE.

Значения флажков G_IO_FLAG_IS_READABLE и G_IO_FLAG_IS_WRITEABLE кэшируются для внутреннего использования каналом при его создании. Если они позже должны измениться (например частичное завершение сокета с помощью UNIX функции shutdown()), пользователь должен немедленно вызвать g_io_channel_get_flags() для обновления внутренних значений этих флажков.

channel : GIOChannel
Возвращает : флаги которые устанавливаются в канале

g_io_channel_set_flags ()

GIOStatus   g_io_channel_set_flags          (GIOChannel *channel,
                                             GIOFlags flags,
                                             GError **error);

Устанавливает (записываемые) флаги в channel (flags & G_IO_CHANNEL_SET_MASK).

channel : GIOChannel.
flags : флаги для установки в канал IO.
error : расположение возвращаемой ошибки типа GIOChannelError.
Возвращает : статус операции.

enum GIOFlags

typedef enum
{
  G_IO_FLAG_APPEND = 1 << 0,
  G_IO_FLAG_NONBLOCK = 1 << 1,
  G_IO_FLAG_IS_READABLE = 1 << 2,	/* флаг доступный только для чтения */
  G_IO_FLAG_IS_WRITEABLE = 1 << 3,	/* флаг доступный только для чтения */
  G_IO_FLAG_IS_SEEKABLE = 1 << 4,	/* флаг доступный только для чтения */
  G_IO_FLAG_MASK = (1 << 5) - 1,
  G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK,
  G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK
} GIOFlags;

Определяет свойства GIOChannel. Некоторые флаги можно только читать с помощью g_io_channel_get_flags(), но нельзя изменять с помощью g_io_channel_set_flags().

G_IO_FLAG_APPEND включает режим предварительной перемотки файла в конец (append mode), соответствует O_APPEND (смотрите документацию системного вызова UNIX open()).
G_IO_FLAG_NONBLOCK включает не блокируемый режим, соответствует O_NONBLOCK/O_NDELAY (смотрите документацию системного вызова UNIX open()).
G_IO_FLAG_IS_READABLE указывает что канал читаемый. Этот флаг не может изменяться.
G_IO_FLAG_IS_WRITEABLE указывает что канал записываемый. Этот флаг не может изменяться.
G_IO_FLAG_IS_SEEKABLE указывает что io канал может изменять позицию доступа (seekable), то есть что в нём может использоваться функция g_io_channel_seek_position(). Этот флаг не может изменяться.
G_IO_FLAG_MASK
G_IO_FLAG_GET_MASK
G_IO_FLAG_SET_MASK

g_io_channel_get_line_term ()

const gchar* g_io_channel_get_line_term     (GIOChannel *channel,
                                             gint *length);

Возвращает строку которую GIOChannel использует для определения где в файле происходит прерывание линии. Значение NULL указывает автоматическое определение.

channel : GIOChannel
length : расположение для возвращаемой длины завершающего строку символа
Возвращает : Строка завершения линии. Этим значением владеет GLib и оно не должно освобождаться.

g_io_channel_set_line_term ()

void        g_io_channel_set_line_term      (GIOChannel *channel,
                                             const gchar *line_term,
                                             gint length);

Устанавливает строку которую GIOChannel использует для определения где в файле происходит прерывание линии.

channel : GIOChannel
line_term : Строка прерывания линии. Используйте NULL для автоматического определения. Автоматическое определение прерывается на "\n", "\r\n", "\r", "\0", и разделителе параграфов Unicode. Автоматическое определение не должно использоваться ни для чего кроме каналов основанных на файлах.
length : Длина прерываемой строки. Если помещено значение -1, строка будет как предполагается nul-terminated. Эта опция позволяет прерывать строки с встроенным nuls.

g_io_channel_get_buffered ()

gboolean    g_io_channel_get_buffered       (GIOChannel *channel);

Определяет буферизуется ли channel.

channel : GIOChannel.
Возвращает : TRUE если channel буферизуется.

g_io_channel_set_buffered ()

void        g_io_channel_set_buffered       (GIOChannel *channel,
                                             gboolean buffered);

Состояние буферизации может быть установлено только если кодировка канала NULL. Для любых других кодировок, канал должен буферизироваться.

Буферизированный канал может быть установлен не буферизированным только если внутренние буферы канала были записаны на диск. Вновь созданные каналы или каналы вернувшие G_IO_STATUS_EOF не требуют производить такую запись. Для каналов только для записи, вызов g_io_channel_flush() достаточен. Для всех других каналов, буфер может быть синхронизирован с диском с помощью вызова g_io_channel_seek_position(). Это включает возможность перемещения позиции типа G_SEEK_CUR и нулевое смещение. Отметьте, это значит что каналы на основе сокетов не могут быть установлены не буферизированными как только из них начнётся чтение данных.

В небуферизованных каналах, безопасно смешивать вызовы чтения и записи из новых и старых APIs, если это необходимо для поддержки старого кода.

По умолчанию канал имеет буферизованное состояние.

channel : GIOChannel
buffered : является ли канал буферизированным или нет

g_io_channel_get_encoding ()

const gchar* g_io_channel_get_encoding      (GIOChannel *channel);

Получает кодировку для ввода/вывода канала. Внутренняя кодировка всегда UTF-8. Кодировка NULL делает канал безопасным для двоичных данных.

channel : GIOChannel
Возвращает : строка содержащая кодировку, строкой владеет GLib и она не должна освобождаться.

g_io_channel_set_encoding ()

GIOStatus   g_io_channel_set_encoding       (GIOChannel *channel,
                                             const gchar *encoding,
                                             GError **error);

Устанавливает кодировку для ввода/вывода канала. Внутренняя кодировка всегда UTF-8. Кодировка по умолчанию для внешних файлов UTF-8.

Кодировка NULL безопасна для использования двоичных данных.

Кодировка может быть установлена только если выполняются следующие условия:

1. Канал был только что создан и операции чтения или записи не проводились.

2. Канал только для записи.

3. Канал это файл, а указатель файла был только что установлен с помощью вызова g_io_channel_seek_position(). (Это записывает все внутренние буферы на диск.)

4. Текущая кодировка NULL или UTF-8.

5. Одна из функций (новый API) чтения возвратила G_IO_STATUS_EOF (или, в случае g_io_channel_read_to_end(), G_IO_STATUS_NORMAL).

6. Одна из функций g_io_channel_read_chars() или g_io_channel_read_unichar() вернула G_IO_STATUS_AGAIN или G_IO_STATUS_ERROR. Это может быть полезно в случае G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Возвращение одного из этих статусов из g_io_channel_read_line(), g_io_channel_read_line_string(), или g_io_channel_read_to_end() не гарантирует что кодировка может быть изменена.

Каналы которые не соответствуют одному из выше упомянутых условий не могут вызывать g_io_channel_seek_position() со смещением G_SEEK_CUR, и если они "seekable", не могут вызывать g_io_channel_write_chars() после вызова одной из функций API "read".

channel : GIOChannel
encoding : тип кодировки
error : размещение для хранения ошибки типа GConvertError.
Возвращает : G_IO_STATUS_NORMAL если кодировка была полностью установлена.

g_io_channel_get_close_on_unref ()

gboolean    g_io_channel_get_close_on_unref (GIOChannel *channel);

Определяет будет ли закрыт любой файл/сокет связанный с каналом channel когда channel будет разрушен при удалении последней ссылки на него. По умолчанию значение TRUE для каналов созданных с помощью g_io_channel_new_file(), а FALSE для всех других каналов.

channel : GIOChannel.
Возвращает : будет ли закрыт канал при удалении последней ссылки на структуру данных GIOChannel.

g_io_channel_set_close_on_unref ()

void        g_io_channel_set_close_on_unref (GIOChannel *channel,
                                             gboolean do_close);

Установка этого флажка в TRUE для канала который уже закрыт может вызвать проблемы.

channel : GIOChannel
do_close : закрывается ли канал при удалении последней ссылки на структуру данных GIOChannel. Значение по умолчанию TRUE для каналов созданных с помощью g_io_channel_new_file(), а FALSE для всех других каналов.

g_io_channel_read ()

GIOError    g_io_channel_read               (GIOChannel *channel,
                                             gchar *buf,
                                             gsize count,
                                             gsize *bytes_read);

Внимание

g_io_channel_read устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_read_chars() вместо неё.

Читает данные из GIOChannel.

channel : GIOChannel.
buf : буфер из которого читаются данные (which should be at least count bytes long).
count : количество байт читаемых из GIOChannel.
bytes_read : возвращает фактическое количество прочтенных байт.
Возвращает : G_IO_ERROR_NONE если операция была успешно выполнена.

enum GIOError

typedef enum
{
  G_IO_ERROR_NONE,
  G_IO_ERROR_AGAIN,
  G_IO_ERROR_INVAL,
  G_IO_ERROR_UNKNOWN
} GIOError;

GIOError используется только устаревшими функциями g_io_channel_read(), g_io_channel_write(), и g_io_channel_seek().

G_IO_ERROR_NONE нет ошибки
G_IO_ERROR_AGAIN произошла ошибка EAGAIN
G_IO_ERROR_INVAL произошла ошибка EINVAL
G_IO_ERROR_UNKNOWN произошла другая ошибка

g_io_channel_write ()

GIOError    g_io_channel_write              (GIOChannel *channel,
                                             const gchar *buf,
                                             gsize count,
                                             gsize *bytes_written);

Внимание

g_io_channel_write устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_write_chars() вместо неё.

Записывает данные в GIOChannel.

channel : a GIOChannel.
buf : буфер содержащий данные для записи.
count : количество байт для записи.
bytes_written : количество фактически записанных байт.
Возвращает : G_IO_ERROR_NONE если операция полностью выполнена.

g_io_channel_seek ()

GIOError    g_io_channel_seek               (GIOChannel *channel,
                                             gint64 offset,
                                             GSeekType type);

Внимание

g_io_channel_seek устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_seek_position() вместо неё.

Устанавливает текущую позицию в GIOChannel, подобна стандартной библиотечной функции fseek().

channel : GIOChannel.
offset : смещение в байтах, которое добавляется в позицию определённую type
type : позиция в файе, которая может быть G_SEEK_CUR (текущая позиция), G_SEEK_SET (начало файла), или G_SEEK_END (конец файла).
Возвращает : G_IO_ERROR_NONE если операция выполнена успешно.

g_io_channel_close ()

void        g_io_channel_close              (GIOChannel *channel);

Внимание

g_io_channel_close устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_shutdown() вместо неё.

Закрывает IO канал. Любые данные ожидающие обработки записываются на диск, игнорируя ошибки. Канал не будет освобождён пока не сброшена последняя ссылка с помощью g_io_channel_unref().

channel : GIOChannel

Смотрите также

gtk_input_add_full(), gtk_input_remove(), gdk_input_add(), gdk_input_add_full(), gdk_input_remove()

Удобные функции для создания GIOChannel и добавления его в основной цикл события.


GLib Core Application Support

The Main Event Loop - Управление всеми доступными источниками событий.
Threads - Абстракция потока; включает потоки, различные взаимоисключения (mutexes), условия и поток закрытых данных.
Thread Pools - Пулы потоков для одновременного выполнения работы.
Asynchronous Queues - Асинхронное взаимодействие между потоками.
Dynamic Loading of Modules - Переносимый способ для динамической загрузки 'plug-ins'.
Memory Allocation - Основная обработка памяти.
IO Channels - Переносимая поддержка использования файлов, каналов и сокетов.
Error Reporting - Система для сообщения об ошибках.
Message Output and Debugging Functions - Функции для вывода сообщений и помощь отладки приложений.
Message Logging - Универсальная поддержка для регистрации сообщений с разным уровнем важности.

Key-value file parser

Key-value file parser — Анализ .ini-подобных конфигурационных файлов

Краткое описание


#include <glib.h>


            GKeyFile;
#define     G_KEY_FILE_ERROR
enum        GKeyFileError;
enum        GKeyFileFlags;
GKeyFile*   g_key_file_new                  (void);
void        g_key_file_free                 (GKeyFile *key_file);
void        g_key_file_set_list_separator   (GKeyFile *key_file,
                                             gchar separator);
gboolean    g_key_file_load_from_file       (GKeyFile *key_file,
                                             const gchar *file,
                                             GKeyFileFlags flags,
                                             GError **error);
gboolean    g_key_file_load_from_data       (GKeyFile *key_file,
                                             const gchar *data,
                                             gsize length,
                                             GKeyFileFlags flags,
                                             GError **error);
gboolean    g_key_file_load_from_data_dirs  (GKeyFile *key_file,
                                             const gchar *file,
                                             gchar **full_path,
                                             GKeyFileFlags flags,
                                             GError **error);
gchar*      g_key_file_to_data              (GKeyFile *key_file,
                                             gsize *length,
                                             GError **error);
gchar*      g_key_file_get_start_group      (GKeyFile *key_file);
gchar**     g_key_file_get_groups           (GKeyFile *key_file,
                                             gsize *length);
gchar**     g_key_file_get_keys             (GKeyFile *key_file,
                                             const gchar *group_name,
                                             gsize *length,
                                             GError **error);
gboolean    g_key_file_has_group            (GKeyFile *key_file,
                                             const gchar *group_name);
gboolean    g_key_file_has_key              (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

gchar*      g_key_file_get_value            (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);
gchar*      g_key_file_get_string           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);
gchar*      g_key_file_get_locale_string    (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *locale,
                                             GError **error);
gboolean    g_key_file_get_boolean          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);
gint        g_key_file_get_integer          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);
gdouble     g_key_file_get_double           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);
gchar**     g_key_file_get_string_list      (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gsize *length,
                                             GError **error);
gchar**     g_key_file_get_locale_string_list
                                            (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *locale,
                                             gsize *length,
                                             GError **error);
gboolean*   g_key_file_get_boolean_list     (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gsize *length,
                                             GError **error);
gint*       g_key_file_get_integer_list     (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gsize *length,
                                             GError **error);
gdouble*    g_key_file_get_double_list      (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gsize *length,
                                             GError **error);
gchar*      g_key_file_get_comment          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

void        g_key_file_set_value            (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *value);
void        g_key_file_set_string           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *string);
void        g_key_file_set_locale_string    (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *locale,
                                             const gchar *string);
void        g_key_file_set_boolean          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gboolean value);
void        g_key_file_set_integer          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gint value);
void        g_key_file_set_double           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gdouble value);
void        g_key_file_set_string_list      (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key);
void        g_key_file_set_locale_string_list
                                            (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *locale);
void        g_key_file_set_boolean_list     (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gboolean list[],
                                             gsize length);
void        g_key_file_set_integer_list     (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gint list[],
                                             gsize length);
void        g_key_file_set_double_list      (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gdouble list[],
                                             gsize length);
void        g_key_file_set_comment          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *comment,
                                             GError **error);
void        g_key_file_remove_group         (GKeyFile *key_file,
                                             const gchar *group_name,
                                             GError **error);
void        g_key_file_remove_key           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);
void        g_key_file_remove_comment       (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Описание

GKeyFile позволяет вам анализировать, редактировать или создавать файлы содержащие группы пар ключ-значение, которые мы называем key files за неимением лучшего названия. Несколько спецификаций freedesktop.org используют ключевые фйлы, например Desktop Entry Specification и Icon Theme Specification.

Синтаксис ключевых файлов детально описан в Desktop Entry Specification, вот короткое описание: Ключевые файлы содержат группы пар ключ-значение, сопровождаемые коментариями.

# это простой пример
# здесь мог бы быть комментарий для первой группы

[Первая группа]

Name=Key File Example\tthis value shows\nescaping

# Локализованные строки хранятся в нескольких парах ключ-значение
Welcome=Hello
Welcome[de]=Hallo
Welcome[fr]=Bonjour
Welcome[it]=Ciao

[Другая группа]

Numbers=2;20;-200;0

Booleans=true;false;true;true

Строки начинающиеся со знака '#' и пустые строки рассматриваются как комментарии.

Группы начинаются заглавными строками содержащими имя группы заключённое в '[' и ']', а заканчиваются началом следующей группы или концом файла. Каждая пара ключ-значение должна находится в группе.

Пары ключевых значений в основном имеют форму key=value, за исключением локализованных строк, которые имеют форму key[locale]=value. Пробелы после или до знака '=' игнорируются. Символ новый строки, табуляции, перевод каретки или обратный слэш обозначаются как \n, \t, \r, и \\, соответственно. Для сохранения начальных и завершающих пробелов, их можно обозначить как \s.

Ключи файла могут хранить строки (возможно с локализованными вариантами), целочисленные, логические значения и их списки. Списки разделяются символом разделителя, обычно ';' или ','. Для использования символа разделителя списка в значениях списка, его нужно обозначить предустановленным обратным слэшем.

Этот синтаксис подобен .ini файлам обычно встречающимся в Windows, но есть некоторые важные различия:

  • .ini файлы используют символ ';' для начала комментариев, ключевые файлы используют символ '#'.

  • Ключевые файлы допускают только комментарии перед первой группой.

  • Ключевые файлы всегда в кодировке UTF-8.

  • Имена Ключей и Групп чувствительны к регистру, например группа с именем [GROUP] отличается от группы [group].

Детали

GKeyFile

typedef struct _GKeyFile GKeyFile;

Структура GKeyFile содержит только закрытые поля и не должна использоваться непосредственно.


G_KEY_FILE_ERROR

#define G_KEY_FILE_ERROR g_key_file_error_quark()

Домен ошибки для анализатора ключевых файлов. Ошибки в этом домене из перечисления GKeyFileError. Смотрите GError для информации о доменах ошибки.


enum GKeyFileError

typedef enum
{
  G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
  G_KEY_FILE_ERROR_PARSE,
  G_KEY_FILE_ERROR_NOT_FOUND,
  G_KEY_FILE_ERROR_KEY_NOT_FOUND,
  G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
  G_KEY_FILE_ERROR_INVALID_VALUE
} GKeyFileError;

Коды ошибок возвращаемые анализатором ключевых файлов.

G_KEY_FILE_ERROR_UNKNOWN_ENCODING анализируемый текст был в неизвестной кодировке
G_KEY_FILE_ERROR_PARSE документ был плохо сформирован
G_KEY_FILE_ERROR_NOT_FOUND файл не найден
G_KEY_FILE_ERROR_KEY_NOT_FOUND требуемый ключ не найден
G_KEY_FILE_ERROR_GROUP_NOT_FOUND требуемая группа не найдена
G_KEY_FILE_ERROR_INVALID_VALUE значение не может быть проанализировано

enum GKeyFileFlags

typedef enum
{
  G_KEY_FILE_NONE              = 0,
  G_KEY_FILE_KEEP_COMMENTS     = 1 << 0,
  G_KEY_FILE_KEEP_TRANSLATIONS = 1 << 1
} GKeyFileFlags;

Флаги влияющие на анализ.

G_KEY_FILE_NONE Нет флагов, поведение по умолчанию
G_KEY_FILE_KEEP_COMMENTS Используйте этот флаг если вы планируете записать (возможно изменённое) содержимое ключевого файла обратно в файл; иначе все комментарии будут потеряны после записи ключевого файла обратно.
G_KEY_FILE_KEEP_TRANSLATIONS Используйте этот флаг если вы планируете записать (возможно изменённое) содержимое ключевого файла в файл; иначе будет записан только перевод для текущего языка.

g_key_file_new ()

GKeyFile*   g_key_file_new                  (void);

Создаёт новый пустой объект GKeyFile. Используйте g_key_file_load_from_file(), g_key_file_load_from_data() или g_key_file_load_from_data_dirs() для чтения существующего ключевого файла.

Возвращает : пустой GKeyFile.

Начиная с версии 2.6


g_key_file_free ()

void        g_key_file_free                 (GKeyFile *key_file);

Освобождает GKeyFile.

key_file : GKeyFile

Начиная с версии 2.6


g_key_file_set_list_separator ()

void        g_key_file_set_list_separator   (GKeyFile *key_file,
                                             gchar separator);

Устанавливает символ используемый для разделения значений в списках. Обычно ';' или ',' используются в качестве разделителя. По умолчанию разделителем списков является ';'.

key_file : GKeyFile
separator : разделитель

Начиная с версии 2.6


g_key_file_load_from_file ()

gboolean    g_key_file_load_from_file       (GKeyFile *key_file,
                                             const gchar *file,
                                             GKeyFileFlags flags,
                                             GError **error);

Загружает ключевой файл в пустую структуру GKeyFile. Если файл не загружен, то устанавливается error в GFileError или GKeyFileError.

key_file : пустая структура GKeyFile
file : путь имени файла для загрузки, в кодировке имён файлов GLib
flags : флаги из GKeyFileFlags
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если ключевой файл был загружен, FALSE если нет.

Начиная с версии 2.6


g_key_file_load_from_data ()

gboolean    g_key_file_load_from_data       (GKeyFile *key_file,
                                             const gchar *data,
                                             gsize length,
                                             GKeyFileFlags flags,
                                             GError **error);

Загружает ключевой файл из памяти в пустую структуру GKeyFile. Если объект не создан, то устанавливается error в GKeyFileError.

key_file : пустая структура GKeyFile
data : ключевой файл загружаемый из памяти.
length : длина data в байтах
flags : флаги из GKeyFileFlags
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если ключевой файл был загружен, FALSE если нет.

Начиная с версии 2.6


g_key_file_load_from_data_dirs ()

gboolean    g_key_file_load_from_data_dirs  (GKeyFile *key_file,
                                             const gchar *file,
                                             gchar **full_path,
                                             GKeyFileFlags flags,
                                             GError **error);

Эта функция находит ключевой файл с именем file в путях возвращаемых из g_get_user_data_dir() и g_get_system_data_dirs(), загружает файл в key_file и возвращает полный путь файла в full_path. Если файл не загружен то устанавливается error в GFileError или GKeyFileError.

key_file : пустая структура GKeyFile
file : относительный путь к фалу для анализа
full_path : расположение для возвращаемой строки содержащей полный путь файла, или NULL
flags : флаги из GKeyFileFlags
error : расположение для возвращаемой GError, или NULL
Возвращает : TRUE если ключевой файл был загружен, FALSE если нет

Начиная с версии 2.6


g_key_file_to_data ()

gchar*      g_key_file_to_data              (GKeyFile *key_file,
                                             gsize *length,
                                             GError **error);

Эта функция выводит key_file как строку.

key_file : GKeyFile
length : расположение для длины возвращаемой строки, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённая строка содержащая контекст GKeyFile

Начиная с версии 2.6


g_key_file_get_start_group ()

gchar*      g_key_file_get_start_group      (GKeyFile *key_file);

Возвращает имя начальной группы файла.

key_file : GKeyFile
Возвращает : Начальная группа ключевого файла.

Начиная с версии 2.6


g_key_file_get_groups ()

gchar**     g_key_file_get_groups           (GKeyFile *key_file,
                                             gsize *length);

Возвращает все группы ключевого файла загруженного из key_file. Массив возвращаемых групп будет NULL-завершённым, поэтому length опционально может быть NULL.

key_file : GKeyFile
length : расположение для количества возвращаемых групп, или NULL
Возвращает : вновь распределённый NULL-завершённый массив строк. Используйте g_strfreev() для его освобождения.

Начиная с версии 2.6


g_key_file_get_keys ()

gchar**     g_key_file_get_keys             (GKeyFile *key_file,
                                             const gchar *group_name,
                                             gsize *length,
                                             GError **error);

Возвращает все ключи для группы с именем group_name. Массив возвращаемых ключей будет NULL-завершённым, поэтому length опционально может быть NULL. Даже если group_name не найдена, возвращается NULL и устанавливается error в G_KEY_FILE_ERROR_GROUP_NOT_FOUND.

key_file : GKeyFile
group_name : имя группы
length : расположение для возвращаемого количества возвращённых ключей, или NULL
error : расположение для GError, или NULL
Возвращает : вновь распределённый NULL-завершённый массив строк. Используйте g_strfreev() для его освобождения.

Начиная с версии 2.6


g_key_file_has_group ()

gboolean    g_key_file_has_group            (GKeyFile *key_file,
                                             const gchar *group_name);

Определяет имеет ли ключевой файл группу group_name.

key_file : GKeyFile
group_name : имя группы
Возвращает : TRUE если group_name часть key_file, иначе FALSE.

Начиная с версии 2.6


g_key_file_has_key ()

gboolean    g_key_file_has_key              (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Определяет имеет ли ключевой файл ключ key в группе group_name.

key_file : GKeyFile
group_name : имя группы
key : имя ключа
error : расположение для возвращаемой GError
Возвращает : TRUE если key часть group_name, иначе FALSE.

Начиная с версии 2.6


g_key_file_get_value ()

gchar*      g_key_file_get_value            (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Возвращает значение связанное с key в group_name.

В случае когда ключ не найден, возвращает NULL и устанавливает error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. В случае когда group_name не найдена, возвращает NULL и устанавливает error в G_KEY_FILE_ERROR_GROUP_NOT_FOUND.

key_file : GKeyFile
group_name : имя группы
key : ключ
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённая строка, или NULL если определённый ключ не найден.

Начиная с версии 2.6


g_key_file_get_string ()

gchar*      g_key_file_get_string           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Возвращает значение связанное с key в group_name.

Когда ключ не найден, возвращает NULL и устанавливает error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. В случае если group_name не найдена, возвращает NULL и устанавливает error в G_KEY_FILE_ERROR_GROUP_NOT_FOUND.

key_file : GKeyFile
group_name : имя группы
key : ключ
error : расположение возвращаемой GError, или NULL
Возвращает : вновь распределённая строка или NULL если определённый ключ не найден.

Начиная с версии 2.6


g_key_file_get_locale_string ()

gchar*      g_key_file_get_locale_string    (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *locale,
                                             GError **error);

Возвращает значение связанное с key в group_name переведённое в полученную locale если возможно. Если locale это NULL, то используется текущая локаль.

Если key не найден, то возвращает NULL и устанавливает error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Если значение связанное с key не может интерпретироваться или не найден подходящий перевод, то возвращается не переведённое значение.

key_file : GKeyFile
group_name : имя группы
key : ключ
locale : локаль или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : вновь распределённая строка или NULL если определённый ключ не найден.

Начиная с версии 2.6


g_key_file_get_boolean ()

gboolean    g_key_file_get_boolean          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Возвращает значение связанное с key в group_name как логическое.

Если key не найден то возвращаемое значение не определено и устанавливается error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значение связанное с key не интерпретируется как логическое, то возвращаемое значение также не определено и устанавливается error в G_KEY_FILE_ERROR_INVALID_VALUE.

key_file : GKeyFile
group_name : имя группы
key : ключ
error : расположение для возвращаемой GError
Возвращает : логическое значение связанное с ключом

Начиная с версии 2.6


g_key_file_get_integer ()

gint        g_key_file_get_integer          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Возвращает значение связанное с key в group_name как целочисленное. Если group_name это NULL, то используется начальная группа (start_group).

Если key не найден, то возвращаемое значение не определено и устанавливается error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значение связанное с key не интерпретируется как целочисленное, то возвращаемое значение также не определено и устанавливается error в G_KEY_FILE_ERROR_INVALID_VALUE.

key_file : GKeyFile
group_name : имя группы
key : ключ
error : расположение для возвращаемой GError
Возвращает : целочисленное значение связанное с ключом.

Начиная с версии 2.6


g_key_file_get_double ()

gdouble     g_key_file_get_double           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Возвращает значение связанное с key в group_name как double. Если group_name это NULL, используется начальная группа (start_group).

Если key не найден, то возвращаемое значение не определено и устанавливается error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значение связанное с key не интерпретируется как double, то возвращаемое значение также не определено и устанавливается error в G_KEY_FILE_ERROR_INVALID_VALUE.

key_file : GKeyFile
group_name : имя группы
key : ключ
error : расположение для возвращаемой GError
Возвращает : double значение связанное с ключом.

Начиная с версии 2.12


g_key_file_get_string_list ()

gchar**     g_key_file_get_string_list      (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gsize *length,
                                             GError **error);

Возвращает значение связанное с key в group_name.

В случае когда ключ не найден, возвращает NULL и устанавливает error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Если group_name не найдена, возвращает NULL и устанавливает error в G_KEY_FILE_ERROR_GROUP_NOT_FOUND.

key_file : GKeyFile
group_name : имя группы
key : ключ
length : расположение для количества возвращаемых строк, или NULL
error : расположение для возвращаемой GError, или NULL
Возвращает : NULL-завершённый строковый массив или NULL если определённый ключ не найден. Массив должен освобождаться с помощью g_strfreev().

Начиная с версии 2.6


g_key_file_get_locale_string_list ()

gchar**     g_key_file_get_locale_string_list
                                            (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *locale,
                                             gsize *length,
                                             GError **error);

Возвращает значение связанное с key в group_name переводя в полученную locale если возможно. Если locale это NULL, то используется текущая локаль.

Если key не найден, то возвращает NULL и устанавливает error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Если значения связанные с key не могут интерпретироваться или не подлежат переводу, то возвращает не переведённые значения. Возвращённый массив NULL-завершённый, поэтому length может опционально быть NULL.

key_file : GKeyFile
group_name : имя группы
key : ключ
locale : локаль
length : расположение для количества возвращаемых строк или NULL
error : расположение для возвращаемой GError или NULL
Возвращает : вновь распределённый NULL-завершённый массив строк или NULL если ключ не найден. Строковый массив должен освобождаться с помощью g_strfreev().

Начиная с версии 2.6


g_key_file_get_boolean_list ()

gboolean*   g_key_file_get_boolean_list     (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gsize *length,
                                             GError **error);

Возвращает значение связанное с key в group_name как список логических. Если group_name это NULL, используется начальная группа (start_group).

Если key не найден, то возвращаемое значение не определено и устанавливается error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значения связанные с key не интерпретируются как логические, то возвращаемое значение также не определено и устанавливается error в G_KEY_FILE_ERROR_INVALID_VALUE.

key_file : GKeyFile
group_name : имя группы
key : ключ
length : количество возвращаемых логических
error : расположение для возвращаемой GError
Возвращает : логические значения связанные с ключом

Начиная с версии 2.6


g_key_file_get_integer_list ()

gint*       g_key_file_get_integer_list     (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gsize *length,
                                             GError **error);

Возвращает значения связанные с key в group_name как список целочисленных.

Если key не найден, то возвращаемое значение не определено и устанавливается error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значения связанные с key не интерпретируются как целочисленные, то возвращаемое значение также не определено и устанавливается error в G_KEY_FILE_ERROR_INVALID_VALUE.

key_file : GKeyFile
group_name : имя группы
key : ключ
length : количество возвращаемых целочисленных
error : расположение для возвращаемой GError
Возвращает : целочисленные значения связанные с ключом

Начиная с версии 2.6


g_key_file_get_double_list ()

gdouble*    g_key_file_get_double_list      (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gsize *length,
                                             GError **error);

Возвращает значение связанное с key в group_name как doubles. Если group_name это NULL, используется начальная группа.

Если key не найден, то возвращаемое значение не определено и устанавливается error в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значения связанные с key не интерпретируются как doubles, то возвращаемое значение также не определено и error устанавливается в G_KEY_FILE_ERROR_INVALID_VALUE.

key_file : GKeyFile
group_name : имя группы
key : ключ
length : количество возвращаемых doubles
error : расположение для возвращаемой GError
Возвращает : значения связанные с key как double

Начиная с версии 2.12


g_key_file_get_comment ()

gchar*      g_key_file_get_comment          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Находит комментарий выше key из group_name. Если key это NULL, то comment будет прочитан сверху group_name. Если и key и group_name являются NULL, то comment будет прочитан сверху первой группы в файле.

key_file : GKeyFile
group_name : имя группы, или NULL
key : ключ
error : расположение для возвращаемой GError
Возвращает : комментарий который должен быть освобождён с помощью g_free()

Начиная с версии 2.6


g_key_file_set_value ()

void        g_key_file_set_value            (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *value);

Связывает новое значение с key в group_name. Если key не найден, то он создаётся. Если group_name не найдена, то она создаётся.

key_file : GKeyFile
group_name : имя группы
key : ключ
value : строка

Начиная с версии 2.6


g_key_file_set_string ()

void        g_key_file_set_string           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *string);

Связывает новое строковое значение с key в group_name. Если key не найден, то он создаётся. Если group_name не найдена, то она создаётся.

key_file : GKeyFile
group_name : имя группы
key : ключ
string : строка

Начиная с версии 2.6


g_key_file_set_locale_string ()

void        g_key_file_set_locale_string    (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *locale,
                                             const gchar *string);

Связывает строковое значение с key и locale в group_name. Если перевод для key не найден, то он создаётся.

key_file : GKeyFile
group_name : имя группы
key : ключ
locale : локаль
string : строка

Начиная с версии 2.6


g_key_file_set_boolean ()

void        g_key_file_set_boolean          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gboolean value);

Связывает новое логическое значение с key в group_name. Если key не найден, он создаётся.

key_file : GKeyFile
group_name : имя группы
key : ключ
value : TRUE или FALSE

Начиная с версии 2.6


g_key_file_set_integer ()

void        g_key_file_set_integer          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gint value);

Связывает новое целочисленное значение с key в group_name. Если key не найден, то он создаётся.

key_file : GKeyFile
group_name : имя группы
key : ключ
value : целочисленное значение

Начиная с версии 2.6


g_key_file_set_double ()

void        g_key_file_set_double           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gdouble value);

Связывает новое значение double с key в group_name. Если key не найден, он создаётся. Если group_name это NULL, используется начальная группа.

key_file : GKeyFile
group_name : имя группы
key : ключ
value : значение double

Начиная с версии 2.12


g_key_file_set_string_list ()

void        g_key_file_set_string_list      (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key);

Связывает список строковых значений с key в group_name. Если key не найден, то он создаётся. Если group_name не найдена, то она создаётся.

key_file : GKeyFile
group_name : имя группы
key : ключ

Начиная с версии 2.6


g_key_file_set_locale_string_list ()

void        g_key_file_set_locale_string_list
                                            (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *locale);

Связывает список строковых значений с key и locale в group_name. Если перевод для key не найден, то он создаётся.

key_file : GKeyFile
group_name : имя группы
key : ключ
locale : локаль

Начиная с версии 2.6


g_key_file_set_boolean_list ()

void        g_key_file_set_boolean_list     (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gboolean list[],
                                             gsize length);

Связывает список логических значений с key в group_name. Если key не найден, то он создаётся. Если group_name это NULL, то используется начальная группа (start_group).

key_file : GKeyFile
group_name : имя группы
key : ключ
list : массив логических значений
length : длина list

Начиная с версии 2.6


g_key_file_set_integer_list ()

void        g_key_file_set_integer_list     (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gint list[],
                                             gsize length);

Связывает список целочисленных значений с key в group_name. Если key не найден, то он создаётся.

key_file : GKeyFile
group_name : имя группы
key : ключ
list : массив целочисленных значений
length : количество целочисленных значений в list

Начиная с версии 2.6


g_key_file_set_double_list ()

void        g_key_file_set_double_list      (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             gdouble list[],
                                             gsize length);

Связывает список значений double с key в group_name. Если key не найден, то он создаётся. Если group_name это NULL, то используется начальная группа.

key_file : GKeyFile
group_name : имя группы
key : ключ
list : массив double значений
length : количество double значений в list

Начиная с версии 2.12


g_key_file_set_comment ()

void        g_key_file_set_comment          (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             const gchar *comment,
                                             GError **error);

Размещает комментарий выше key из group_name. Если key это NULL, то comment будет записан вверху group_name. Если и key и group_name являются NULL, то comment будет записан сверху первой группы в файле.

key_file : GKeyFile
group_name : имя группы, или NULL
key : ключ
comment : комментарий
error : расположение для возвращаемой GError

Начиная с версии 2.6


g_key_file_remove_group ()

void        g_key_file_remove_group         (GKeyFile *key_file,
                                             const gchar *group_name,
                                             GError **error);

Удаляет определённую группу, group_name, из ключевого файла.

key_file : GKeyFile
group_name : имя группы
error : расположение для возвращаемой GError или NULL

Начиная с версии 2.6


g_key_file_remove_key ()

void        g_key_file_remove_key           (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Удаляет key в group_name из ключевого файла.

key_file : GKeyFile
group_name : имя группы
key : имя ключа для удаления
error : расположение для возвращаемой GError или NULL

Начиная с версии 2.6


g_key_file_remove_comment ()

void        g_key_file_remove_comment       (GKeyFile *key_file,
                                             const gchar *group_name,
                                             const gchar *key,
                                             GError **error);

Удаляет комментарий выше key из group_name.

key_file : GKeyFile
group_name : имя группы, или NULL
key : ключ
error : расположение для возвращаемой GError

Начиная с версии 2.6


Keyed Data Lists

Keyed Data Lists — Списки элементов данных которые являются доступными при помощи строки или GQuark идентификатора.

Краткое описание


#include <glib.h>


            GData;
void        g_datalist_init                 (GData **datalist);

#define     g_datalist_id_set_data          (dl, q, d)
void        g_datalist_id_set_data_full     (GData **datalist,
                                             GQuark key_id,
                                             gpointer data,
                                             GDestroyNotify destroy_func);
gpointer    g_datalist_id_get_data          (GData **datalist,
                                             GQuark key_id);
#define     g_datalist_id_remove_data       (dl, q)
gpointer    g_datalist_id_remove_no_notify  (GData **datalist,
                                             GQuark key_id);

#define     g_datalist_set_data             (dl, k, d)
#define     g_datalist_set_data_full        (dl, k, d, f)
#define     g_datalist_get_data             (dl, k)
#define     g_datalist_remove_data          (dl, k)
#define     g_datalist_remove_no_notify     (dl, k)

void        g_datalist_foreach              (GData **datalist,
                                             GDataForeachFunc func,
                                             gpointer user_data);
void        g_datalist_clear                (GData **datalist);
void        g_datalist_set_flags            (GData **datalist,
                                             guint flags);
void        g_datalist_unset_flags          (GData **datalist,
                                             guint flags);
guint       g_datalist_get_flags            (GData **datalist);
#define     G_DATALIST_FLAGS_MASK

Описание

Списки ключевых данных обеспечивают списки произвольных элементов данных к которым можно обратиться либо с помощью строки, либо с помощью GQuark соответствующим строке.

GQuark метод быстрее, так как строки всё равно конвертируются в GQuarks.

Списки данных используются для связи произвольных данных с GObjects, используя g_object_set_data() и родственные функции.

Для создания списка данных, используйте g_datalist_init().

Для добавления элементов данных в список данных используйте g_datalist_id_set_data(), g_datalist_id_set_data_full(), g_datalist_set_data() и g_datalist_set_data_full().

Для получения элементов данных из списка данных используйте g_datalist_id_get_data() и g_datalist_get_data().

Для итерации через все элементы в списке данных используйте g_datalist_foreach() (not thread-safe).

Для удаления элементов данных из списка данных используйте g_datalist_id_remove_data() и g_datalist_remove_data().

Для удаления всех элементов из списка данных, используйте g_datalist_clear().

Детали

GData

typedef struct _GData GData;

Структура GData - это непрозрачная структура данных представляющая Keyed Data List. доступ к ней должен осуществляться только с помощью следующих функций.


g_datalist_init ()

void        g_datalist_init                 (GData **datalist);

Сбрасывает список данных в NULL. Она не освобождает память и не вызывает функции уничтожения.

datalist : указатель на указатель в списке данных.

g_datalist_id_set_data()

#define     g_datalist_id_set_data(dl, q, d)

Устанавливает данные соответствующие указанному GQuark идентификатору. Любые предыдущие данные с тем же ключом - удаляются, и это вызывает функцию уничтожения.

dl : список данных.
q : GQuark для идентификации элемента данных.
d : элемент данных, или NULL для удаления любых предыдущих элементов соответствующих q.

g_datalist_id_set_data_full ()

void        g_datalist_id_set_data_full     (GData **datalist,
                                             GQuark key_id,
                                             gpointer data,
                                             GDestroyNotify destroy_func);

Устанавливает данные соответствующие указанному GQuark идентификатору, и вызывает функцию когда элемент удаляется из списка данных. Любые предыдущие данные с тем же ключом удаляются и вызывается функция уничтожения.

datalist : список данных.
key_id : GQuark для идентификации элемента данных.
data : элемент данных или NULL для удаления любых предыдущих элементов соответствующих key_id.
destroy_func : функция вызываемая когда удаляется элемент данных. Эта функция вызывается с элементом данных и может использоваться для освобождения любой распределённой памяти для него. Если data это NULL, то destroy_func должен также быть NULL.

g_datalist_id_get_data ()

gpointer    g_datalist_id_get_data          (GData **datalist,
                                             GQuark key_id);

Находит элемент данных соответствующий key_id.

datalist : список данных.
key_id : GQuark идентификатор элемента данных.
Возвращает : элемент данных, или NULL если он не найден.

g_datalist_id_remove_data()

#define     g_datalist_id_remove_data(dl, q)

Удаляет элемент, используя его GQuark идентификатор.

dl : список данных.
q : GQuark идентификатор элемента данных.

g_datalist_id_remove_no_notify ()

gpointer    g_datalist_id_remove_no_notify  (GData **datalist,
                                             GQuark key_id);

Удаляет элемент, без вызова функции уничтожения.

datalist : список данных.
key_id : GQuark идентификатор элемента данных.
Возвращает : предыдущие данные key_id, или NULL ели нет.

g_datalist_set_data()

#define     g_datalist_set_data(dl, k, d)

Устанавливает элемент данных соответствующий указанному строковому идентификатору.

dl : список данных.
k : строка для идентификации элемента данных.
d : элемент данных, или NULL для удаления любых предыдущих элементов соответствующих k.

g_datalist_set_data_full()

#define     g_datalist_set_data_full(dl, k, d, f)

Устанавливает элемент данных соответствующий указанной строке идентификатору, и функцию вызываемую при удалении элемента данных.

dl : список данных.
k : строка для идентификации элемента данных.
d : элемент данных, или NULL для удаления любых предыдущих элементов соответствующих k.
f : Функция вызываемая при удалении элемента данных. Эта функция вызывается с элементом данных и может использоваться для освобождения любой распределённой для него памяти. Если d это NULL, то f должен также быть NULL.

g_datalist_get_data()

#define     g_datalist_get_data(dl, k)

Выдаёт элемент данных, используя его строку идентификатор. Это медленнее чем g_datalist_id_get_data() потомучто строка сначала конвертируется в GQuark.

dl : список данных.
k : строка идентификатор элемента данных.
Возвращает : элемент данных, или NULL если он не найден.

g_datalist_remove_data()

#define     g_datalist_remove_data(dl, k)

Удаляет элемент используя его строковый идентификатор. Элемент данных уничтожается функцией если она была установлена.

dl : список данных.
k : строка идентификатор элемента данных.

g_datalist_remove_no_notify()

#define     g_datalist_remove_no_notify(dl, k)

Удаляет элемент, без вызова уничтожающей функции.

dl : список данных.
k : строка идентификатор элемента данных.

g_datalist_foreach ()

void        g_datalist_foreach              (GData **datalist,
                                             GDataForeachFunc func,
                                             gpointer user_data);

Вызывает указанную функцию для каждого элемента данных в списке данных. Функция вызывается на каждым элементом данных с GQuark идентификатором и данными, вместе с параметром user_data. Помните что эта функция потоко-небезопасна. Поэтому если datalist не может быть защищён от любых изменений в течении выполнения этой функции, она не должна вызываться.

datalist : список данных.
func : функция вызываемая для каждого элемента данных.
user_data : пользовательские данные помещаемые в функцию.

g_datalist_clear ()

void        g_datalist_clear                (GData **datalist);

Освобождает все элементы данных в списке данных. Элементы данных уничтожаются функциями вызываемыми если она была установлена.

datalist : список данных.

g_datalist_set_flags ()

void        g_datalist_set_flags            (GData **datalist,
                                             guint flags);

Включает значение флажка для списка данных. Эта функция используется для хранения небольшого числа логических флажков в объекте со списком данных без использования любого дополнительного пространства. Она в основном бесполезна, кроме ситуаций когда пространство сильно уплотнено. (Она в основном типе GObject, например.)

datalist : указатель на расположение которое содержит список
flags : флажки для включения. Значения флажков ограничены G_DATALIST_FLAGS_MASK (в настоящее время 3; представляя два возможных логических флажка). Значение для flags которое не соответствует маске - ошибика.

Начиная с версии 2.8


g_datalist_unset_flags ()

void        g_datalist_unset_flags          (GData **datalist,
                                             guint flags);

Выключает значения флажка для списка данных. Смотрите g_datalist_unset_flags()

datalist : указатель на расположение которое содержит список
flags : флажки для выключения. Значения флажков ограничены G_DATALIST_FLAGS_MASK (в настоящее время 3: представляя два возможных логических флажка). Значение для flags которое не соответствует маске - ошибка.

Начиная с версии 2.8


g_datalist_get_flags ()

guint       g_datalist_get_flags            (GData **datalist);

Определяет значения флажков упакованных вместе со списком данных. Смотрите g_datalist_set_flags().

datalist : указатель на расположение которое содержит список
Возвращает : флажки списка данных

Начиная с версии 2.8


G_DATALIST_FLAGS_MASK

#define G_DATALIST_FLAGS_MASK 0x3

Битовая маска которая ограничивает возможные флажки помещаемые в g_datalist_set_flags(). Помещаемые значения флажков где флажки & ~G_DATALIST_FLAGS_MASK != 0 - это ошибка.


Lexical Scanner

Lexical Scanner — универсальный лексический сканер.

Краткое описание


#include <glib.h>


            GScanner;
GScanner*   g_scanner_new                   (const GScannerConfig *config_templ);
            GScannerConfig;

void        g_scanner_input_file            (GScanner *scanner,
                                             gint input_fd);
void        g_scanner_sync_file_offset      (GScanner *scanner);
void        g_scanner_input_text            (GScanner *scanner,
                                             const gchar *text,
                                             guint text_len);
GTokenType  g_scanner_peek_next_token       (GScanner *scanner);
GTokenType  g_scanner_get_next_token        (GScanner *scanner);

guint       g_scanner_cur_line              (GScanner *scanner);
guint       g_scanner_cur_position          (GScanner *scanner);
GTokenType  g_scanner_cur_token             (GScanner *scanner);
GTokenValue g_scanner_cur_value             (GScanner *scanner);
gboolean    g_scanner_eof                   (GScanner *scanner);

guint       g_scanner_set_scope             (GScanner *scanner,
                                             guint scope_id);
void        g_scanner_scope_add_symbol      (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol,
                                             gpointer value);
void        g_scanner_scope_foreach_symbol  (GScanner *scanner,
                                             guint scope_id,
                                             GHFunc func,
                                             gpointer user_data);
gpointer    g_scanner_scope_lookup_symbol   (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol);
void        g_scanner_scope_remove_symbol   (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol);

#define     g_scanner_freeze_symbol_table   (scanner)
#define     g_scanner_thaw_symbol_table     (scanner)
gpointer    g_scanner_lookup_symbol         (GScanner *scanner,
                                             const gchar *symbol);

void        g_scanner_warn                  (GScanner *scanner,
                                             const gchar *format,
                                             ...);
void        g_scanner_error                 (GScanner *scanner,
                                             const gchar *format,
                                             ...);
void        g_scanner_unexp_token           (GScanner *scanner,
                                             GTokenType expected_token,
                                             const gchar *identifier_spec,
                                             const gchar *symbol_spec,
                                             const gchar *symbol_name,
                                             const gchar *message,
                                             gint is_error);
void        (*GScannerMsgFunc)              (GScanner *scanner,
                                             gchar *message,
                                             gboolean error);

void        g_scanner_destroy               (GScanner *scanner);

enum        GTokenType;
union       GTokenValue;
enum        GErrorType;
#define     G_CSET_a_2_z
#define     G_CSET_A_2_Z
#define     G_CSET_DIGITS
#define     G_CSET_LATINC
#define     G_CSET_LATINS

#define     g_scanner_add_symbol            ( scanner, symbol, value )
#define     g_scanner_remove_symbol         ( scanner, symbol )
#define     g_scanner_foreach_symbol        ( scanner, func, data )

Описание

GScanner и связанные с ней функции обеспечивают универсальный лексический сканер.

Детали

GScanner

typedef struct {
  /* неиспользуемые поля */
  gpointer		user_data;
  guint			max_parse_errors;
  
  /* g_scanner_error() инкрементирует это поле */
  guint			parse_errors;
  
  /* имя входного потока, показываемое обработчиком сообщения по умолчанию */
  const gchar		*input_name;
  
  /* quarked data */
  GData			*qdata;
  
  /* ссылка на конфигурацию сканера */
  GScannerConfig	*config;
  
  /* поля заполняемые после g_scanner_get_next_token() */
  GTokenType		token;
  GTokenValue		value;
  guint			line;
  guint			position;
  
  /* поля заполняемые после g_scanner_peek_next_token() */
  GTokenType		next_token;
  GTokenValue		next_value;
  guint			next_line;
  guint			next_position;
  
  /* рассматриваются как закрытые */
  GHashTable		*symbol_table;
  gint			input_fd;
  const gchar		*text;
  const gchar		*text_end;
  gchar			*buffer;
  guint			scope_id;
  
  /* функция обработчик для _warn и _error */
  GScannerMsgFunc	msg_handler;
} GScanner;

Структура данных представляющая лексический сканер.

Вы должны установить input_name после создания сканера, та как оно используется обработчиком сообщений по умолчанию когда отображаются предупреждения и ошибки Если вы сканируете файл, имя файла будет хорошим выбором для этого.

Поля user_data и max_parse_errors неиспользуются. Если вам нужно связать дополнительные данные со сканером вы можете поместить их сюда.

Если вам нужно использовать собственный обработчик сообщений вы можете установить его в поле msg_handler. Тип функции обработки сообщений определяет GScannerMsgFunc.


g_scanner_new ()

GScanner*   g_scanner_new                   (const GScannerConfig *config_templ);

Создаёт новую GScanner. Структура config_templ определяет начальные установки сканера, которые копируются в структуру GScanner поле config. Для использования настроек по умолчанию вы можете поместить NULL.

config_templ : начальные настройки сканера.
Возвращает : новая GScanner.

GScannerConfig

typedef struct {
  /* Наборы символов
   */
  gchar		*cset_skip_characters;		/* по умолчанию: " \t\n" */
  gchar		*cset_identifier_first;
  gchar		*cset_identifier_nth;
  gchar		*cpair_comment_single;		/* по умолчанию: "#\n" */
  
  /* Чувствителен ли поиск символа к регистру?
   */
  guint		case_sensitive : 1;
  
  /* Логическое значение для настройки "на лету"
   * конфигурации правил сканирования.
   */
  guint		skip_comment_multi : 1;		/* C подобный комментарий */
  guint		skip_comment_single : 1;	/* единственная строка комментария */
  guint		scan_comment_multi : 1;		/* сканировать множество строк коментария? */
  guint		scan_identifier : 1;
  guint		scan_identifier_1char : 1;
  guint		scan_identifier_NULL : 1;
  guint		scan_symbols : 1;
  guint		scan_binary : 1;
  guint		scan_octal : 1;
  guint		scan_float : 1;
  guint		scan_hex : 1;			/* `0x0ff0' */
  guint		scan_hex_dollar : 1;		/* `$0ff0' */
  guint		scan_string_sq : 1;		/* string: 'anything' */
  guint		scan_string_dq : 1;		/* string: "\\-escapes!\n" */
  guint		numbers_2_int : 1;		/* bin, octal, hex => int */
  guint		int_2_float : 1;		/* int => G_TOKEN_FLOAT? */
  guint		identifier_2_string : 1;
  guint		char_2_token : 1;		/* возвращать G_TOKEN_CHAR? */
  guint		symbol_2_token : 1;
  guint		scope_0_fallback : 1;		/* позволить 0 контекст поиска? */
  guint		store_int64 : 1; 		/* использовать значение.v_int64 вместо v_int */
  guint		padding_dummy;
} GScannerConfig;

Определяет настройки GScanner.

cset_skip_characters определяет символы которые сканер должен пропускать (по умолчанию символы пробелов: пробел, табуляцию, перевод каретки и перевод строки).

cset_identifier_first определяет символы которые могут начинать идентификаторы (по умолчанию это G_CSET_a_2_z, "_", и G_CSET_A_2_Z).

cset_identifier_nth определяет символы которые могут использоваться в идентификаторах после первого символа (по умолчанию это G_CSET_a_2_z, "_0123456789", G_CSET_A_2_Z, G_CSET_LATINS, G_CSET_LATINC).

cpair_comment_single определяет символы начала и конца единственной строки коментария. По умолчанию это "#\n" который означает что единственная строка комментария начинается с '#' и продолжается до '\n' (конец строки).

case_sensitive определяет чувствительность символов к регистру (по умолчанию FALSE).

skip_comment_multi определяет пропускать ли многострочные комментарии и не возвращать как лексемы (по умолчанию TRUE).

skip_comment_single определяет пропускать ли однострочные комментарии и не возвращать как лексемы (по умолчанию TRUE).

scan_comment_multi определяет распознавать ли многострочные комментарии (по умолчанию TRUE).

scan_identifier определяет распознавать ли идентификатор (по умолчанию TRUE).

scan_identifier_1char определяет распознавать ли единственный символ идентификатора (по умолчанию FALSE).

scan_identifier_NULL определяет возвращать ли NULL как G_TOKEN_IDENTIFIER_NULL. (по умолчанию FALSE).

scan_symbols определяет распознавать ли символы (по умолчанию TRUE).

scan_binary определяет распознавать ли двоичные числа (по умолчанию FALSE).

scan_octal определяет распознавать ли восьмеричные числа (по умолчанию TRUE).

scan_float определяет распознавать ли числа с плавающей точкой (по умолчанию TRUE).

scan_hex определяет распознавать ли шестнадцатеричные числа (по умолчанию TRUE).

scan_hex_dollar определяет распознавать ли '$' как префикс для шестнадцатеричных чисел (по умолчанию FALSE).

scan_string_sq определяет заключена ли строка в одиночные кавычки (по умолчанию TRUE).

scan_string_dq определяет заключена ли строка в двойные кавычки (по умолчанию TRUE).

numbers_2_int определяет должны ли двоичные, восьмеричные и шестнадцатеричные числа передаваться как G_TOKEN_INT (по умолчанию TRUE).

int_2_float определяет передаются ли все числа как G_TOKEN_FLOAT (по умолчанию FALSE).

identifier_2_string определяет передаётся ли идентификатор как строка (по умолчанию FALSE).

char_2_token определяет передаются символы устанавливая token = ch или как G_TOKEN_CHAR (по умолчанию TRUE).

symbol_2_token определяет передаются ли символы установленными как token = v_symbol или как G_TOKEN_SYMBOL (по умолчанию FALSE).

scope_0_fallback определяет разыскивается ли символ для контекста по умолчанию в дополнение к текущему контексту (по умолчанию FALSE).


g_scanner_input_file ()

void        g_scanner_input_file            (GScanner *scanner,
                                             gint input_fd);

Подготавливает файл для сканирования.

scanner : GScanner.
input_fd : дискриптор файла.

g_scanner_sync_file_offset ()

void        g_scanner_sync_file_offset      (GScanner *scanner);

Перематывает файловый дескриптор в текущую позицию буфера и позволяет читать файл с начала буфера. Это полезно когда используется третичный сканер файлового дескриптора, который прикрепляется к текущей позиции сканера.

scanner : GScanner.

g_scanner_input_text ()

void        g_scanner_input_text            (GScanner *scanner,
                                             const gchar *text,
                                             guint text_len);

Подготавливает для сканирования текстовый буфер.

scanner : GScanner.
text : текстовый буфер для сканирования.
text_len : длина текстового буфера.

g_scanner_peek_next_token ()

GTokenType  g_scanner_peek_next_token       (GScanner *scanner);

Получает следующую лексему, не удаляя её из потока ввода. Символьные данные помещаются в next_token, next_value, next_line, и next_position поля структуры GScanner.

Помните что пока лексема не удалена из входного потока (то есть следующий вызов g_scanner_get_next_token() будет возвращать туже лексему), она не будет переоценена. Это может привести к удивительным результатам когда изменяется контекст заглядывания за следующую лексему. Получение следующей лексемы после переключения контекста вернёт то что рассматривалось ранее, независимо от любых символов которые могут быть добавлены или удалены в новом контексте.

scanner : GScanner.
Возвращает : тип лексемы.

g_scanner_get_next_token ()

GTokenType  g_scanner_get_next_token        (GScanner *scanner);

Получает следующую лексему удаляя её из входного потока. Символьные данные помещаются в token, value, line, и position поля структуры GScanner.

scanner : GScanner.
Возвращает : тип лексемы.

g_scanner_cur_line ()

guint       g_scanner_cur_line              (GScanner *scanner);

Получает текущую строку во входном потоке (подсчёт начинается с 1).

scanner : GScanner.
Возвращает : текущая строка.

g_scanner_cur_position ()

guint       g_scanner_cur_position          (GScanner *scanner);

Получает текущую позицию в текущей строке (подсчёт начинается с 0).

scanner : GScanner.
Возвращает : текущая позиция в строке.

g_scanner_cur_token ()

GTokenType  g_scanner_cur_token             (GScanner *scanner);

Получает текущий тип лексемы. Это просто поле token в структуре GScanner.

scanner : GScanner.
Возвращает : текущий тип лексемы.

g_scanner_cur_value ()

GTokenValue g_scanner_cur_value             (GScanner *scanner);

Получает текущее значение лексемы. Это просто поле value в структуре GScanner.

scanner : GScanner.
Возвращает : текущее значение лексемы.

g_scanner_eof ()

gboolean    g_scanner_eof                   (GScanner *scanner);

Возвращает TRUE если сканер достиг конца файла или текстового буфера.

scanner : GScanner.
Возвращает : TRUE если сканер достиг конца файла или текстового буфера.

g_scanner_set_scope ()

guint       g_scanner_set_scope             (GScanner *scanner,
                                             guint scope_id);

Устанавливает текущий контекст.

scanner : GScanner.
scope_id : новый id контекста.
Возвращает : старый id контекста.

g_scanner_scope_add_symbol ()

void        g_scanner_scope_add_symbol      (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol,
                                             gpointer value);

Добавляет символ в полученный контекст.

scanner : GScanner.
scope_id : id контектса.
symbol : добавляемый символ.
value : значение символа.

g_scanner_scope_foreach_symbol ()

void        g_scanner_scope_foreach_symbol  (GScanner *scanner,
                                             guint scope_id,
                                             GHFunc func,
                                             gpointer user_data);

Вызывает полученную функцию для каждой пары символ/значение в полученном контексте GScanner. Функция помещает символ и значение каждой пары и полученный параметр user_data.

scanner : GScanner.
scope_id : id контекста.
func : функция вызываемая для каждой пары символ/значение.
user_data : пользовательские данные помещаемые в функцию.

g_scanner_scope_lookup_symbol ()

gpointer    g_scanner_scope_lookup_symbol   (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol);

Находит символ в контексте и возвращает его значение. Если символа нет в контексте, возвращает NULL.

scanner : GScanner.
scope_id : id контекста.
symbol : разыскиваемый символ.
Возвращает : значение symbol в полученном контексте, или NULL если symbol не находится в полученном контексте.

g_scanner_scope_remove_symbol ()

void        g_scanner_scope_remove_symbol   (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol);

Удаляет символ из контекста.

scanner : GScanner.
scope_id : id контекста.
symbol : символ для удаления.

g_scanner_freeze_symbol_table()

#define     g_scanner_freeze_symbol_table(scanner)

Внимание

g_scanner_freeze_symbol_table устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Этот макрос ничего не делает.

scanner : GScanner.

g_scanner_thaw_symbol_table()

#define     g_scanner_thaw_symbol_table(scanner)

Внимание

g_scanner_thaw_symbol_table устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Этот макрос ничего не делает.

scanner : GScanner.

g_scanner_lookup_symbol ()

gpointer    g_scanner_lookup_symbol         (GScanner *scanner,
                                             const gchar *symbol);

Находит символ в текущем контексте и возвращает его значение. Если символ не находится в текущем контексте, то возвращает NULL.

scanner : GScanner.
symbol : символ для поиска.
Возвращает : значение symbol в текущем контексте, или NULL если symbol не находится в текущем контексте.

g_scanner_warn ()

void        g_scanner_warn                  (GScanner *scanner,
                                             const gchar *format,
                                             ...);

Выводит предупреждающее сообщение через обработчик сообщений GScanner.

scanner : GScanner.
format : формат сообщения. Смотрите документацию для printf().
... : параметры вставляемые в строку формата.

g_scanner_error ()

void        g_scanner_error                 (GScanner *scanner,
                                             const gchar *format,
                                             ...);

Выводит сообщение об ошибке через обработчик сообщений GScanner.

scanner : GScanner.
format : формат сообщения. Смотрите документацию для printf().
... : параметры вставляемые в строку формата.

g_scanner_unexp_token ()

void        g_scanner_unexp_token           (GScanner *scanner,
                                             GTokenType expected_token,
                                             const gchar *identifier_spec,
                                             const gchar *symbol_spec,
                                             const gchar *symbol_name,
                                             const gchar *message,
                                             gint is_error);

Выводит сообщение через msg_handler сканера, реагируя на неожиданную лексему во входном потоке. Помните что вы не должны вызывать g_scanner_peek_next_token() сопровождаемый g_scanner_unexp_token() без промежуточного вызова g_scanner_get_next_token(), поскольку g_scanner_unexp_token() оценивает текущую лексему (не просматриваемую лексему) для создания части сообщения.

scanner : GScanner.
expected_token : ожидаемая лексема.
identifier_spec : строка описывающая как пользователю сканера обращаться к идентификаторам (NULL для идентификатора по умолчанию). Это используется если expected_token равен G_TOKEN_IDENTIFIER или G_TOKEN_IDENTIFIER_NULL.
symbol_spec : строка описывающая как пользователь сканера обращается к символам (NULL по умолчанию к "symbol"). Это используется если expected_token равен G_TOKEN_SYMBOL или какому нибудь символьному значению больше чем G_TOKEN_LAST.
symbol_name : имя символа, если текущая сканируемая лексема является символом.
message : строка сообщения выводимая в конце предупреждения/ошибки, или NULL.
is_error : если TRUE выводится как ошибка. Если FALSE выводится как предупреждение.

GScannerMsgFunc ()

void        (*GScannerMsgFunc)              (GScanner *scanner,
                                             gchar *message,
                                             gboolean error);

Определяет тип функции обработчика сообщений.

scanner : GScanner.
message : сообщение.
error : TRUE если сообщение означает ошибку, FALSE если оно обозначает предупреждение.

g_scanner_destroy ()

void        g_scanner_destroy               (GScanner *scanner);

Освобождает всю память используемую GScanner.

scanner : GScanner.

enum GTokenType

typedef enum
{
  G_TOKEN_EOF			=   0,
  
  G_TOKEN_LEFT_PAREN		= '(',
  G_TOKEN_RIGHT_PAREN		= ')',
  G_TOKEN_LEFT_CURLY		= '{',
  G_TOKEN_RIGHT_CURLY		= '}',
  G_TOKEN_LEFT_BRACE		= '[',
  G_TOKEN_RIGHT_BRACE		= ']',
  G_TOKEN_EQUAL_SIGN		= '=',
  G_TOKEN_COMMA			= ',',
  
  G_TOKEN_NONE			= 256,
  
  G_TOKEN_ERROR,
  
  G_TOKEN_CHAR,
  G_TOKEN_BINARY,
  G_TOKEN_OCTAL,
  G_TOKEN_INT,
  G_TOKEN_HEX,
  G_TOKEN_FLOAT,
  G_TOKEN_STRING,
  
  G_TOKEN_SYMBOL,
  G_TOKEN_IDENTIFIER,
  G_TOKEN_IDENTIFIER_NULL,
  
  G_TOKEN_COMMENT_SINGLE,
  G_TOKEN_COMMENT_MULTI,
  G_TOKEN_LAST
} GTokenType;

Возможные типы лексем возвращаемые из каждого вызова g_scanner_get_next_token().

G_TOKEN_EOF конец файла.
G_TOKEN_LEFT_PAREN символ '('.
G_TOKEN_LEFT_CURLY символ '{'.
G_TOKEN_RIGHT_CURLY символ '}'.

union GTokenValue

union GTokenValue
{
  gpointer	v_symbol;
  gchar		*v_identifier;
  gulong	v_binary;
  gulong	v_octal;
  gulong	v_int;
  guint64       v_int64;
  gdouble	v_float;
  gulong	v_hex;
  gchar		*v_string;
  gchar		*v_comment;
  guchar	v_char;
  guint		v_error;
};

Объединение содержащее значения лексем.


enum GErrorType

typedef enum
{
  G_ERR_UNKNOWN,
  G_ERR_UNEXP_EOF,
  G_ERR_UNEXP_EOF_IN_STRING,
  G_ERR_UNEXP_EOF_IN_COMMENT,
  G_ERR_NON_DIGIT_IN_CONST,
  G_ERR_DIGIT_RADIX,
  G_ERR_FLOAT_RADIX,
  G_ERR_FLOAT_MALFORMED
} GErrorType;

Возможные ошибки, используются в поле v_error GTokenValue, когда лексема равна G_TOKEN_ERROR.

G_ERR_UNKNOWN неизвестная ошибка.
G_ERR_UNEXP_EOF неопределённый конец файла.
G_ERR_UNEXP_EOF_IN_STRING незаконченная строковая константа.
G_ERR_UNEXP_EOF_IN_COMMENT незаконченный коментарий.
G_ERR_NON_DIGIT_IN_CONST не цифровой символ в номере.
G_ERR_DIGIT_RADIX цифра выходящая за рамки счисления числа.
G_ERR_FLOAT_RADIX не десятичная плавающая точка числа.
G_ERR_FLOAT_MALFORMED некорректное число с плавающей точкой.

G_CSET_a_2_z

#define G_CSET_a_2_z	"abcdefghijklmnopqrstuvwxyz"

Набор алфавитных символов ASCII в нижнем регистре. Используется для определения допустимых идентификаторов символов в GScannerConfig.


G_CSET_A_2_Z

#define G_CSET_A_2_Z	"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Набор алфавитных символов ASCII в верхнем регистре. Используется для определения допустимых идентификаторов символов в GScannerConfig.


G_CSET_DIGITS

#define G_CSET_DIGITS	"0123456789"

Набор цифр. Используется для определения допустимых идентификаторов символов в GScannerConfig.


G_CSET_LATINC

#define     G_CSET_LATINC

Набор алфавитных символов ISO 8859-1 в верхнем регистре которые не являются символами ASCII. Используется для определения допустимых идентификаторов символов в GScannerConfig.


G_CSET_LATINS

#define     G_CSET_LATINS

Набор алфавитных символов ISO 8859-1 в нижнем регистре которые не являются символами ASCII. Используется для определения допустимых идентификаторов символов в GScannerConfig.


g_scanner_add_symbol()

#define     g_scanner_add_symbol( scanner, symbol, value )

Внимание

g_scanner_add_symbol устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте вместо неё g_scanner_scope_add_symbol().

Добавляет символ к контексту по умолчанию.

scanner : GScanner.
symbol : добавляемый символ.
value : значение символа.

g_scanner_remove_symbol()

#define     g_scanner_remove_symbol( scanner, symbol )

Внимание

g_scanner_remove_symbol устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте вместо неё g_scanner_scope_remove_symbol().

Удаляет символ из контекста по умолчанию.

scanner : GScanner.
symbol : удаляемый символ.

g_scanner_foreach_symbol()

#define     g_scanner_foreach_symbol( scanner, func, data )

Внимание

g_scanner_foreach_symbol устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте вместо неё g_scanner_scope_foreach_symbol().

Вызываемая функция для каждого символа в контексте по умолчанию.

scanner : GScanner.
func : функция вызываемая для каждого символа.
data : данные помещаемые в функцию.

Limits of Basic Types

Limits of Basic Types — Переносимый метод определения лимитов стандартных типов.

Краткое описание


#include <glib.h>


#define     G_MININT
#define     G_MAXINT
#define     G_MAXUINT

#define     G_MINSHORT
#define     G_MAXSHORT
#define     G_MAXUSHORT

#define     G_MINLONG
#define     G_MAXLONG
#define     G_MAXULONG

#define     G_MININT8
#define     G_MAXINT8
#define     G_MAXUINT8

#define     G_MININT16
#define     G_MAXINT16
#define     G_MAXUINT16

#define     G_MININT32
#define     G_MAXINT32
#define     G_MAXUINT32

#define     G_MININT64
#define     G_MAXINT64
#define     G_MAXUINT64

#define     G_MAXSIZE

#define     G_MINFLOAT
#define     G_MAXFLOAT

#define     G_MINDOUBLE
#define     G_MAXDOUBLE

Описание

Эти макросы обеспечивают переносимый метод определения лимитов типов одинаковых стандартных целочисленных и чисел с плавающей точкой.

Детали

G_MININT

#define G_MININT	INT_MIN

Минимальное значение которое может содержать gint.


G_MAXINT

#define G_MAXINT	INT_MAX

Максимальное значение которое может содержать gint.


G_MAXUINT

#define G_MAXUINT	UINT_MAX

Максимальное значение которое может содержать guint.


G_MINSHORT

#define G_MINSHORT	SHRT_MIN

Минимальное значение которое может содержать gshort.


G_MAXSHORT

#define G_MAXSHORT	SHRT_MAX

Максимальное значение которое может содержать gshort.


G_MAXUSHORT

#define G_MAXUSHORT	USHRT_MAX

Максимальное значение которое может содержать gushort.


G_MINLONG

#define G_MINLONG	LONG_MIN

Минимальное значение которое может содержать glong.


G_MAXLONG

#define G_MAXLONG	LONG_MAX

Максимальное значение которое может содержать glong.


G_MAXULONG

#define G_MAXULONG	ULONG_MAX

Максимальное значение которое может содержать gulong.


G_MININT8

#define G_MININT8	((gint8)  0x80)

Минимальное значение которое может содержать gint8.

Начиная с версии 2.4


G_MAXINT8

#define G_MAXINT8	((gint8)  0x7f)

Максимальное значение которое может содержать gint8.

Начиная с версии 2.4


G_MAXUINT8

#define G_MAXUINT8	((guint8) 0xff)

Максимальное значение которое может содержать guint8.

Начиная с версии 2.4


G_MININT16

#define G_MININT16	((gint16)  0x8000)

Минимальное значение которое может содержать gint16.

Начиная с версии 2.4


G_MAXINT16

#define G_MAXINT16	((gint16)  0x7fff)

Максимальное значение которое может содержать gint16.

Начиная с версии 2.4


G_MAXUINT16

#define G_MAXUINT16	((guint16) 0xffff)

Максимальное значение которое может содержать guint16.

Начиная с версии 2.4


G_MININT32

#define G_MININT32	((gint32)  0x80000000)

Минимальное значение которое может содержать gint32.

Начиная с версии 2.4


G_MAXINT32

#define G_MAXINT32	((gint32)  0x7fffffff)

Максимальное значение которое может содержать gint32.

Начиная с версии 2.4


G_MAXUINT32

#define G_MAXUINT32	((guint32) 0xffffffff)

Максимальное значение которое может содержать guint32.

Начиная с версии 2.4


G_MININT64

#define G_MININT64	((gint64) G_GINT64_CONSTANT(0x8000000000000000))

Минимальное значение которое может содержать gint64.


G_MAXINT64

#define G_MAXINT64	G_GINT64_CONSTANT(0x7fffffffffffffff)

Максимальное значение которое может содержать gint64.


G_MAXUINT64

#define G_MAXUINT64	G_GINT64_CONSTANT(0xffffffffffffffffU)

Максимальное значение которое может содержать guint64.


G_MAXSIZE

#define G_MAXSIZE	G_MAXUINT

Максимальное значение которое может содержать gsize.

Начиная с версии 2.4


G_MINFLOAT

#define G_MINFLOAT	FLT_MIN

Минимальное положительное значение которое может содержать gfloat.

Если вас интересует наименьшее значение которое может содержать gfloat, используйте -G_MAX_FLOAT.


G_MAXFLOAT

#define G_MAXFLOAT	FLT_MAX

Максимальное значение которое может содержать gfloat.


G_MINDOUBLE

#define G_MINDOUBLE	DBL_MIN

Минимальное положительное значение которое может содержать gdouble.

Если вас интересует наименьшее значение которое может содержать gdouble, используйте -G_MAXDOUBLE.


G_MAXDOUBLE

#define G_MAXDOUBLE	DBL_MAX

Максимальное значение которое может содержать gdouble.


Memory Allocation

Memory Allocation — Основная обработка памяти.

Краткое описание


#include <glib.h>


#define     g_new                           (struct_type, n_structs)
#define     g_new0                          (struct_type, n_structs)
#define     g_renew                         (struct_type, mem, n_structs)
#define     g_try_new                       (struct_type, n_structs)
#define     g_try_new0                      (struct_type, n_structs)
#define     g_try_renew                     (struct_type, mem, n_structs)

gpointer    g_malloc                        (gulong n_bytes);
gpointer    g_malloc0                       (gulong n_bytes);
gpointer    g_realloc                       (gpointer mem,
                                             gulong n_bytes);
gpointer    g_try_malloc                    (gulong n_bytes);
gpointer    g_try_malloc0                   (gulong n_bytes);
gpointer    g_try_realloc                   (gpointer mem,
                                             gulong n_bytes);

void        g_free                          (gpointer mem);
extern      gboolean g_mem_gc_friendly;

#define     g_alloca                        (size)
#define     g_newa                          (struct_type, n_structs)

#define     g_memmove                       (dest,src,len)
gpointer    g_memdup                        (gconstpointer mem,
                                             guint byte_size);

            GMemVTable;
void        g_mem_set_vtable                (GMemVTable *vtable);
gboolean    g_mem_is_system_malloc          (void);

extern      GMemVTable	*glib_mem_profiler_table;
void        g_mem_profile                   (void);

Описание

Эти функции обеспечивают поддержку распределения и освобождения памяти.

Примечание

Если любой вызов распределения памяти завершается неудачно, приложение закрывается. Это означает что нет необходимости проверять успешность выполнения вызова.

Детали

g_new()

#define     g_new(struct_type, n_structs)

Распределяет n_structs элементов типа struct_type. Возвращаемый указатель приводится к указателю для данного типа. Если n_structs равен 0, то возвращается NULL.

Так как возвращаемый указатель уже приведён к правильному типу, обычно не требуется явное приведение, это может скрыть ошибки распределения памяти.

struct_type : тип элементов для распределения.
n_structs : количество элементов для распределения.
Возвращает : указатель для распределенной памяти, приведённый к указателю типа struct_type.

g_new0()

#define     g_new0(struct_type, n_structs)

Распределяет n_structs элементов типа struct_type, инициализирует в 0's. Возвращаемый указатель приведён к указателю полученного типа. Если n_structs равен 0 возвращается NULL.

Так как возвращаемый указатель уже приведён к правильному типу, обычно не требуется явное приведение, это может скрыть ошибки распределения памяти.

struct_type : тип элементов для распределения.
n_structs : количество элементов для распределения.
Возвращает : указатель для распределённой памяти, приведённый к указателю типа struct_type.

g_renew()

#define     g_renew(struct_type, mem, n_structs)

Перераспределяет память указанную параметром mem, так чтобы она имела свободное пространство для n_structs элементов типа struct_type. Возвращает новый адрес памяти, которая возможно была перемещена.

struct_type : тип элементов для распределения.
mem : текущая распределённая память.
n_structs : количество элементов для распределения.
Возвращает : указатель на вновь распределенную память, приведен к указателю типа struct_type.

g_try_new()

#define     g_try_new(struct_type, n_structs)

Пытается распределить n_structs элементов типа struct_type и возвращает NULL если неудаётся. В отличие от g_new(), которая закрывает программу при неудаче. Возвращаемый указатель приведён к указателю полученного типа. Если n_structs равен 0 возвращается NULL.

struct_type : тип элементов для распределения.
n_structs : количество элементов для рапределения.
Возвращает : указатель на распределенную память, приведённый к указателю типа struct_type.

Начиная с версии 2.8


g_try_new0()

#define     g_try_new0(struct_type, n_structs)

Пытается распределить n_structs элементов типа struct_type, инициализируя 0 и возвращает NULL при неудаче. В отличие от g_new0(), которая закрывает программу при неудаче. Возвращаемый указатель приводится к указателю полученного типа. Если n_counts равен 0, то возвращается NULL.

struct_type : тип элементов для распределения.
n_structs : количество элементов для рапределения.
Возвращает : указатель на распределенную память, приведённый к указателю типа struct_type.

Начиная с версии 2.8


g_try_renew()

#define     g_try_renew(struct_type, mem, n_structs)

Пытается перераспределить память указанную параметром mem, так чтобы появилось пространство для n_structs элементов типа struct_type и возвращает NULL при неудаче. В отличие от g_renew(), которая закрывает программу при неудаче. Возвращает новый адрес памяти, которая могла быть перемещена.

struct_type : тип элементов для распределения.
mem : текущее распределение памяти.
n_structs : количество элементов для рапределения.
Возвращает : указатель на вновь распределённую память, приведённый к указателю типа struct_type.

Начиная с версии 2.8


g_malloc ()

gpointer    g_malloc                        (gulong n_bytes);

Распределяет n_bytes байт памяти. Если n_bytes равен 0, возвращает NULL.

n_bytes : количество байт для распределения.
Возвращает : указатель на распределённую память.

g_malloc0 ()

gpointer    g_malloc0                       (gulong n_bytes);

Распределяет n_bytes байт памяти, инициализируя 0's. Если n_bytes равен 0, возвращает NULL.

n_bytes : количество байт для распределения.
Возвращает : указатель на распределённую память.

g_realloc ()

gpointer    g_realloc                       (gpointer mem,
                                             gulong n_bytes);

Перераспределяет память указанную параметром mem, так чтобы было свободное пространство для n_bytes байт памяти. Возвращает новый адрес памяти, которая могла быть перемещена. mem может быть NULL, в этом случае предполагается нулевая длина. n_bytes может быть 0, в этом случае возвращается NULL.

mem : память для перераспределения.
n_bytes : новый размер памяти в байтах.
Возвращает : новый адрес распределённой памяти.

g_try_malloc ()

gpointer    g_try_malloc                    (gulong n_bytes);

Пытается распределить n_bytes, и возвращает NULL при неудаче. В отличие от g_malloc(), которая закрывает программу при неудаче.

n_bytes : количество байт для распределения.
Возвращает : распределённую память или NULL.

g_try_malloc0 ()

gpointer    g_try_malloc0                   (gulong n_bytes);

Пытается распределить n_bytes, инициализируя 0's, и возвращает NULL при неудаче. В отличие от g_malloc0(), которая закрывает программу при неудаче.

n_bytes : количество байт для распределения.
Возвращает : распределённую память или NULL.

Начиная с версии 2.8


g_try_realloc ()

gpointer    g_try_realloc                   (gpointer mem,
                                             gulong n_bytes);

Пытается перераспределить mem в новый размер n_bytes, и возвращает NULL при неудаче. В отличие от g_realloc(), которая закрывает программу при неудаче. Если mem равен NULL, работает также как g_try_malloc().

mem : предварительно распределённая память, или NULL.
n_bytes : количество байт для распределения.
Возвращает : распределённую память или NULL.

g_free ()

void        g_free                          (gpointer mem);

Освобождает память указанную параметром mem. Если mem равен NULL, то функция ничего не делает.

mem : память для освобождения.

g_mem_gc_friendly

extern gboolean g_mem_gc_friendly;

Эта переменная равна TRUE если переменная окружения G_DEBUG включает ключ gc-friendly.


g_alloca()

#define     g_alloca(size)

Распределяет size байт в стек; эти байты освобождаются когда текущий кадр стека очищается. Этот макрос по существу просто оболочка функции alloca() предоставляемой в большинстве вариантов UNIX. Поэтому он обеспечивает те же самые преимущества и ловушки как alloca():

+ alloca() очень быстрая, так как на большинстве систем она выполняет просто регулировку регистра указателей стека.

+ она не вызывает фрагментации памяти, в пределах её области, разделяемые alloca() блоки просто увеличиваются и освобождаются одновременно с завершением функции.

- распределяемый размер должен вписываться в текущий кадр стека. Например в потоковом окружении Linux, размер стека посредством потока ограничен 2 мегабайтами, поэтому разряжен при использовании alloca().

- неудачное распределение из-за недостатка пространства в стеке не указывается возвращением NULL как например это происходит при использовании malloc(). Вместо этого, большинство систем вероятно обработает это так же как отсутствие свободного пространства стека из бесконечной рекурсивной функции, то есть произойдет ошибка сегментации (segmentation fault).

- особое внимание должно быть уделено при смешивании alloca() с массивами переменного размера GNU C. Распределённое пространство стека с помощью alloca() в той же области где массив переменного размера, будет освобождено вместе с массивом переменного размера при выходе из этой области, а не на выходе внешней области функции.

size : количество байт для распределения.
Возвращает : пространство для size байт, распределяемое в стеке

g_newa()

#define     g_newa(struct_type, n_structs)

Оболочка g_alloca() в более типо-безопасной манере.

struct_type : тип участка памяти для распределения
n_structs : Количество участков для распределения
Возвращает : указатель на пространство стека для n_structs участков типа struct_type

g_memmove()

#define     g_memmove(dest,src,len)

Копирует блок памяти длиной len байт, из src в dest. Источник и адресат могут перекрываться.

Для использования этой функции вы должны самостоятельно включить string.h, потому что этот макрос обычно простое решение для memmove() и GLib не будет включать string.h за вас.

dest : адресат для копируемых байт.
src : источник копируемых байт.
len : количество копируемых байт.

g_memdup ()

gpointer    g_memdup                        (gconstpointer mem,
                                             guint byte_size);

Распределяет byte_size байт памяти и копирует byte_size байт из mem. Если mem равен NULL возвращается NULL.

mem : память для копирования.
byte_size : количество копируемых байт.
Возвращает : указатель на вновь распределенную копию памяти, или NULL если параметр mem равен NULL.

GMemVTable

typedef struct {
  gpointer (*malloc)      (gsize    n_bytes);
  gpointer (*realloc)     (gpointer mem,
			   gsize    n_bytes);
  void     (*free)        (gpointer mem);
  /* опционально; устанавливается в NULL если не используется! */
  gpointer (*calloc)      (gsize    n_blocks,
			   gsize    n_block_bytes);
  gpointer (*try_malloc)  (gsize    n_bytes);
  gpointer (*try_realloc) (gpointer mem,
			   gsize    n_bytes);
} GMemVTable;

Устанавливает функцию используемую для распределения памяти. Также GMemVTable может использоваться для всех распределений в той же самой программе; вызов g_mem_set_vtable(), если он существует, должен быть приоритетным для любого использования GLib.

malloc () функция используемая для распределения памяти.
realloc () функция используемая для перераспределения памяти.
free () функция используемая для освобождения памяти.
calloc () функция используемая для распределения памяти заполняемой нулями (allocating zero-filled memory).
try_malloc () функция используемая для распределения памяти без обработки ошибок по умолчанию.
try_realloc () функция используемая для перераспределения памяти без обработки ошибок по умолчанию.

g_mem_set_vtable ()

void        g_mem_set_vtable                (GMemVTable *vtable);

Заставляет GMemVTable использовать для распределения памяти. Вы можете это использовать для обеспечения выбора функций распределения памяти. Эти функции должны вызываться перед использованием любых других функций GLib. Параметр vtable нужен только для обеспечения malloc(), realloc(), и free() функций; GLib может по умолчанию обеспечить реализацию других. Реализации malloc() и realloc() должны возвращать NULL при неудаче, GLib обрабатывает контроль ошибок за вас. vtable копируется, поэтому не сохраняется после вызова этой функции.

vtable : таблица функций распределения памяти.

g_mem_is_system_malloc ()

gboolean    g_mem_is_system_malloc          (void);

Проверяет использует ли программа распределения памяти g_malloc() системную реализацию malloc. Если возвращает TRUE память распределяемая с помощью malloc() взаимозаменяема памятью распределяемой с использованием g_malloc(). Эта функция полезна для избежания дополнительных копий распределения памяти возвращаемой с помощью не-GLib-based API.

Разные функции распределения могут быть установлены с помощью g_mem_set_vtable().

Возвращает : если TRUE, malloc() и g_malloc() могут использоваться совместно.

glib_mem_profiler_table

extern GMemVTable	*glib_mem_profiler_table;

GMemVTable содержит профилированные варианты функций распределения памяти. Используйте их вместе с g_mem_profile() для получения информации об образце распределения памяти вашей программой.


g_mem_profile ()

void        g_mem_profile                   (void);

Определяет суммарное использование памяти.

Она выдаёт частоту распределений различных размеров, общее количество распределённых байт, общее количество освобождённых байт и разницу между двумя предыдущими значениями, то есть количество всё ещё используемых байт.

Помните что эта функция не определит ничего пока вы предварительно не установите glib_mem_profiler_table с помощью g_mem_set_vtable().


Memory Allocators

Memory Allocators — deprecated way to allocate chunks of memory for GList, GSList and GNode.

Краткое описание


#include <glib.h>


            GAllocator;
GAllocator* g_allocator_new                 (const gchar *name,
                                             guint n_preallocs);
void        g_allocator_free                (GAllocator *allocator);

Описание

Prior to 2.10, GAllocator was used as an efficient way to allocate small pieces of memory for use with the GList, GSList and GNode data structures. Начиная с версии 2.10, it has been completely replaced by the slice allocator and deprecated.

Детали

GAllocator

typedef struct _GAllocator GAllocator;

Внимание

GAllocator устарела и не должна использоваться во вновь создаваемом коде.

The GAllocator struct contains private data. and should only be accessed using the following functions.


g_allocator_new ()

GAllocator* g_allocator_new                 (const gchar *name,
                                             guint n_preallocs);

Внимание

g_allocator_new has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Creates a new GAllocator.

name : the name of the GAllocator. This name is used to set the name of the GMemChunk used by the GAllocator, and is only used for debugging.
n_preallocs : the number of elements in each block of memory allocated. Larger blocks mean less calls to g_malloc(), but some memory may be wasted. (GLib uses 128 elements per block by default.) The value must be between 1 and 65535.
Возвращает : a new GAllocator.

g_allocator_free ()

void        g_allocator_free                (GAllocator *allocator);

Внимание

g_allocator_free has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Frees all of the memory allocated by the GAllocator.

allocator : GAllocator.

Memory Chunks

Memory Chunks — deprecated way to allocate groups of equal-sized chunks of memory.

Краткое описание


#include <glib.h>


            GMemChunk;
#define     G_ALLOC_AND_FREE
#define     G_ALLOC_ONLY

GMemChunk*  g_mem_chunk_new                 (const gchar *name,
                                             gint atom_size,
                                             gulong area_size,
                                             gint type);
gpointer    g_mem_chunk_alloc               (GMemChunk *mem_chunk);
gpointer    g_mem_chunk_alloc0              (GMemChunk *mem_chunk);
void        g_mem_chunk_free                (GMemChunk *mem_chunk,
                                             gpointer mem);
void        g_mem_chunk_destroy             (GMemChunk *mem_chunk);

#define     g_mem_chunk_create              (type, pre_alloc, alloc_type)
#define     g_chunk_new                     (type, chunk)
#define     g_chunk_new0                    (type, chunk)
#define     g_chunk_free                    (mem, mem_chunk)

void        g_mem_chunk_reset               (GMemChunk *mem_chunk);
void        g_mem_chunk_clean               (GMemChunk *mem_chunk);
void        g_blow_chunks                   (void);

void        g_mem_chunk_info                (void);
void        g_mem_chunk_print               (GMemChunk *mem_chunk);

Описание

Memory chunks provide an space-efficient way to allocate equal-sized pieces of memory, called atoms. However, due to the administrative overhead (in particular for G_ALLOC_AND_FREE, and when used from multiple threads), they are in practise often slower than direct use of g_malloc(). Therefore, memory chunks have been deprecated in favor of the slice allocator, which has been added in 2.10. All internal uses of memory chunks in GLib have been converted to the g_slice API.

There are two types of memory chunks, G_ALLOC_ONLY, and G_ALLOC_AND_FREE.

  • G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never be freed individually. The memory chunk can only be free in its entirety.

  • G_ALLOC_AND_FREE chunks do allow atoms to be freed individually. The disadvantage of this is that the memory chunk has to keep track of which atoms have been freed. This results in more memory being used and a slight degradation in performance.

To create a memory chunk use g_mem_chunk_new() or the convenience macro g_mem_chunk_create().

To allocate a new atom use g_mem_chunk_alloc(), g_mem_chunk_alloc0(), or the convenience macros g_chunk_new() or g_chunk_new0().

To free an atom use g_mem_chunk_free(), or the convenience macro g_chunk_free(). (Atoms can only be freed if the memory chunk is created with the type set to G_ALLOC_AND_FREE.)

To free any blocks of memory which are no longer being used, use g_mem_chunk_clean(). To clean all memory chunks, use g_blow_chunks().

To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset().

To destroy a memory chunk, use g_mem_chunk_destroy().

To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print().

Пример 3. Using a GMemChunk

  GMemChunk *mem_chunk;
  gchar *mem[10000];
  gint i;

  /* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding
     100 bytes. Note that this means that only 2 atoms fit into each memory
     block and so isn't very efficient. */
  mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE);

  /* Now allocate 10000 atoms. */
  for (i = 0; i < 10000; i++)
    {
      mem[i] = g_chunk_new (gchar, mem_chunk);

      /* Fill in the atom memory with some junk. */
      for (j = 0; j < 50; j++)
	mem[i][j] = i * j;
    }

  /* Now free all of the atoms. Note that since we are going to destroy the
     GMemChunk, this wouldn't normally be used. */
  for (i = 0; i < 10000; i++)
    {
      g_mem_chunk_free (mem_chunk, mem[i]);
    }

  /* We are finished with the GMemChunk, so we destroy it. */
  g_mem_chunk_destroy (mem_chunk);

Пример 4. Using a GMemChunk with data structures

  GMemChunk *array_mem_chunk;
  GRealArray *array;

  /* Create a GMemChunk to hold GRealArray structures, using the
     g_mem_chunk_create() convenience macro. We want 1024 atoms in each
     memory block, and we want to be able to free individual atoms. */
  array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE);

  /* Allocate one atom, using the g_chunk_new() convenience macro. */
  array = g_chunk_new (GRealArray, array_mem_chunk);

  /* We can now use array just like a normal pointer to a structure. */
  array->data            = NULL;
  array->len             = 0;
  array->alloc           = 0;
  array->zero_terminated = (zero_terminated ? 1 : 0);
  array->clear           = (clear ? 1 : 0);
  array->elt_size        = elt_size;

  /* We can free the element, so it can be reused. */
  g_chunk_free (array, array_mem_chunk);

  /* We destroy the GMemChunk when we are finished with it. */
  g_mem_chunk_destroy (array_mem_chunk);

Детали

GMemChunk

typedef struct _GMemChunk GMemChunk;

Внимание

GMemChunk устарела и не должна использоваться во вновь создаваемом коде.

The GMemChunk struct is an opaque data structure representing a memory chunk. It should be accessed only through the use of the following functions.


G_ALLOC_AND_FREE

#define G_ALLOC_AND_FREE  2

Внимание

G_ALLOC_AND_FREE устарела и не должна использоваться во вновь создаваемом коде.

Specifies the type of a GMemChunk. Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms will be freed individually.


G_ALLOC_ONLY

#define G_ALLOC_ONLY	  1

Внимание

G_ALLOC_ONLY устарела и не должна использоваться во вновь создаваемом коде.

Specifies the type of a GMemChunk. Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms will never be freed individually.


g_mem_chunk_new ()

GMemChunk*  g_mem_chunk_new                 (const gchar *name,
                                             gint atom_size,
                                             gulong area_size,
                                             gint type);

Внимание

g_mem_chunk_new has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Creates a new GMemChunk.

name : строка to identify the GMemChunk. It is not copied so it should be valid for the lifetime of the GMemChunk. It is only used in g_mem_chunk_print(), which is used for debugging.
atom_size : the size, in bytes, of each element in the GMemChunk.
area_size : the size, in bytes, of each block of memory allocated to contain the atoms.
type : the type of the GMemChunk. G_ALLOC_AND_FREE is used if the atoms will be freed individually. G_ALLOC_ONLY should be used if atoms will never be freed individually. G_ALLOC_ONLY is quicker, since it does not need to track free atoms, but it obviously wastes memory if you no longer need many of the atoms.
Возвращает : the new GMemChunk.

g_mem_chunk_alloc ()

gpointer    g_mem_chunk_alloc               (GMemChunk *mem_chunk);

Внимание

g_mem_chunk_alloc has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_alloc() instead

Allocates an atom of memory from a GMemChunk.

mem_chunk : GMemChunk.
Возвращает : a pointer to the allocated atom.

g_mem_chunk_alloc0 ()

gpointer    g_mem_chunk_alloc0              (GMemChunk *mem_chunk);

Внимание

g_mem_chunk_alloc0 has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_alloc0() instead

Allocates an atom of memory from a GMemChunk, setting the memory to 0.

mem_chunk : GMemChunk.
Возвращает : a pointer to the allocated atom.

g_mem_chunk_free ()

void        g_mem_chunk_free                (GMemChunk *mem_chunk,
                                             gpointer mem);

Внимание

g_mem_chunk_free has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_free1() instead

Frees an atom in a GMemChunk. This should only be called if the GMemChunk was created with G_ALLOC_AND_FREE. Otherwise it will simply return.

mem_chunk : GMemChunk.
mem : a pointer to the atom to free.

g_mem_chunk_destroy ()

void        g_mem_chunk_destroy             (GMemChunk *mem_chunk);

Внимание

g_mem_chunk_destroy has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Frees all of the memory allocated for a GMemChunk.

mem_chunk : GMemChunk.

g_mem_chunk_create()

#define     g_mem_chunk_create(type, pre_alloc, alloc_type)

Внимание

g_mem_chunk_create has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

A convenience macro for creating a new GMemChunk. It calls g_mem_chunk_new(), using the given type to create the GMemChunk name. The atom size is determined using sizeof(), and the area size is calculated by multiplying the pre_alloc parameter with the atom size.

type : the type of the atoms, typically a structure name.
pre_alloc : the number of atoms to store in each block of memory.
alloc_type : the type of the GMemChunk. G_ALLOC_AND_FREE is used if the atoms will be freed individually. G_ALLOC_ONLY should be used if atoms will never be freed individually. G_ALLOC_ONLY is quicker, since it does not need to track free atoms, but it obviously wastes memory if you no longer need many of the atoms.
Возвращает : the new GMemChunk.

g_chunk_new()

#define     g_chunk_new(type, chunk)

Внимание

g_chunk_new has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_new() instead

A convenience macro to allocate an atom of memory from a GMemChunk. It calls g_mem_chunk_alloc() and casts the returned atom to a pointer to the given type, avoiding a type cast in the source code.

type : the type of the GMemChunk atoms, typically a structure name.
chunk : GMemChunk.
Возвращает : a pointer to the allocated atom, cast to a pointer to type.

g_chunk_new0()

#define     g_chunk_new0(type, chunk)

Внимание

g_chunk_new0 has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_new0() instead

A convenience macro to allocate an atom of memory from a GMemChunk. It calls g_mem_chunk_alloc0() and casts the returned atom to a pointer to the given type, avoiding a type cast in the source code.

type : the type of the GMemChunk atoms, typically a structure name.
chunk : GMemChunk.
Возвращает : a pointer to the allocated atom, cast to a pointer to type.

g_chunk_free()

#define     g_chunk_free(mem, mem_chunk)

Внимание

g_chunk_free has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_free() instead

A convenience macro to free an atom of memory from a GMemChunk. It simply switches the arguments and calls g_mem_chunk_free() It is included simply to complement the other convenience macros, g_chunk_new() and g_chunk_new0().

mem : a pointer to the atom to be freed.
mem_chunk : GMemChunk.

g_mem_chunk_reset ()

void        g_mem_chunk_reset               (GMemChunk *mem_chunk);

Внимание

g_mem_chunk_reset has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Resets a GMemChunk to its initial state. It frees all of the currently allocated blocks of memory.

mem_chunk : GMemChunk.

g_mem_chunk_clean ()

void        g_mem_chunk_clean               (GMemChunk *mem_chunk);

Внимание

g_mem_chunk_clean has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Frees any blocks in a GMemChunk which are no longer being used.

mem_chunk : GMemChunk.

g_blow_chunks ()

void        g_blow_chunks                   (void);

Внимание

g_blow_chunks has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Calls g_mem_chunk_clean() on all GMemChunk objects.


g_mem_chunk_info ()

void        g_mem_chunk_info                (void);

Внимание

g_mem_chunk_info has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Outputs debugging information for all GMemChunk objects currently in use. It outputs the number of GMemChunk objects currently allocated, and calls g_mem_chunk_print() to output information on each one.


g_mem_chunk_print ()

void        g_mem_chunk_print               (GMemChunk *mem_chunk);

Внимание

g_mem_chunk_print has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator instead

Outputs debugging information for a GMemChunk. It outputs the name of the GMemChunk (set with g_mem_chunk_new()), the number of bytes used, and the number of blocks of memory allocated.

mem_chunk : GMemChunk.

Memory Slices

Memory Slices — Эффективный способ распределения групп эквивалентных по размеру участков памяти.

Краткое описание


#include <glib.h>


gpointer    g_slice_alloc                   (gsize block_size);
gpointer    g_slice_alloc0                  (gsize block_size);
void        g_slice_free1                   (gsize block_size,
                                             gpointer mem_block);
void        g_slice_free_chain_with_offset  (gsize block_size,
                                             gpointer mem_chain,
                                             gsize next_offset);

#define     g_slice_new                     (type)
#define     g_slice_new0                    (type)
#define     g_slice_free                    (type, mem)
#define     g_slice_free_chain              (type, mem_chain, next)

Описание

Слайсы памяти обеспечивают пространственно-эффективный и многопроцессорно-масштабируемый путь для распределения равных по размеру частей памяти, так же как оригинальный GMemChunks (from GLib <= 2.8), избегая чрезмерной траты памяти, потери масштабируемости и проблем выполнения.

Для достижения этих целей, распределитель слайсов использует сложный, многоуровневый дизайн который был создан благодаря распределителю слайсов Bonwick's [5]. Он использует posix_memalign() для оптимизированного распределения множества участков одинакового размера и имеет посредством потока свободные списки (так называемый уровень журналирования) для быстрого удовлетворения запросов распределения уже известных размеров структур. Это сопровождается дополнительным логическим кэшированием, чтобы иметь свободную память в течении некоторого времени перед возвращением в систему. Память которая не используется из-за ограничений выравнивания, используется для колоризации кэша (произвольное распределение адресов участка) для улучшенного использования кэша CPU. Кэширующий уровень распределителя слайсов самостоятельно адаптируется к высокой конкуренции блокирования для улучшения масштабируемости.

Распределитель слайсов может распределять небольшие блоки в два указателя, и в отличие от malloc(), он не резервирует дополнительное пространство в блоке. Для блоков большого размера, g_slice_new() и g_slice_alloc() автоматически делегируют к системной реализации malloc(). Для вновь создаваемого кода рекомендуется использовать новый g_slice API вместо g_malloc() и подобных, пока объекты не изменяют размер в течении их жизненного цикла и размер объекта используемый во время распределения остаётся доступным когда освобождается.

Пример 1. Использование распределителя слайсов

  gchar *mem[10000];
  gint i;

  /* Распределяем 10000 блоков. */
  for (i = 0; i < 10000; i++)
    {
      mem[i] = g_slice_alloc (50);

      /* Fill in the memory with some junk. */
      for (j = 0; j < 50; j++)
	mem[i][j] = i * j;
    }

  /* Освобождаем все блоки. */
  for (i = 0; i < 10000; i++)
    {
      g_slice_free1 (50, mem[i]);
    }

Пример 2. Использование распределителя слайсов со структурами данных

  GRealArray *array;

  /* Распределяем один блок, используя макрос g_slice_new(). */
  array = g_slice_new (GRealArray);

  /* Теперь мы можем использовать массив как обычный указатель на структуру. */
  array->data            = NULL;
  array->len             = 0;
  array->alloc           = 0;
  array->zero_terminated = (zero_terminated ? 1 : 0);
  array->clear           = (clear ? 1 : 0);
  array->elt_size        = elt_size;

  /* Мы можем освобождать блок, поэтому он может использоваться многократно. */
  g_slice_free (GRealArray, array);

Детали

g_slice_alloc ()

gpointer    g_slice_alloc                   (gsize block_size);

Распределяет блок памяти из распределителя слайсов. Адрес полученного блока, как гарантируется, будет выравнен по крайней мере 2 * sizeof (void*). Помните что основной механизм распределения слайсов может быть изменён с помощью переменной окружения G_SLICE=always-malloc.

block_size : количество байт для распределения
Возвращает : указатель на распределённую память block

Начиная с версии 2.10


g_slice_alloc0 ()

gpointer    g_slice_alloc0                  (gsize block_size);

Распределяет блок памяти через g_slice_alloc() и инициализирует возвращаемую память 0. Помните что основной механизм распределения слайсов может быть изменён с помощью переменной окружения G_SLICE=always-malloc.

block_size : количество байт для распределения
Возвращает : указатель на распределённый блок

Начиная с версии 2.10


g_slice_free1 ()

void        g_slice_free1                   (gsize block_size,
                                             gpointer mem_block);

Освобождает блок памяти. Память должна быть распределена через g_slice_alloc() или g_slice_alloc0(), а block_size должен соответствовать размеру определённому при распределении. Помните что существующее поведение может быть изменено с помощью переменной окружения G_DEBUG=gc-friendly.

block_size : размер блока
mem_block : указатель на блок для освобождения

Начиная с версии 2.10


g_slice_free_chain_with_offset ()

void        g_slice_free_chain_with_offset  (gsize block_size,
                                             gpointer mem_chain,
                                             gsize next_offset);

Освобождает связанный список блоков памяти структуры имеющей тип type. Блоки памяти должны быть одинакового размера, распределённые через g_slice_alloc() или g_slice_alloc0() и связаны вместе указателем next (также как в GSList). Смещение поля next передаётся в каждый блок как третий аргумент. Помните что существующее поведение может быть изменено с помощью переменной окружения G_DEBUG=gc-friendly.

block_size : размер блоков
mem_chain : указатель на первый блок в цепочке
next_offset : поле смещения next в блоках

Начиная с версии 2.10


g_slice_new()

#define     g_slice_new(type)

Удобный макрос для распределения блоков памяти из распределителя слайсов. Он вызывает g_slice_alloc() с sizeof (type) и приводит возвращаемый указатель к указателю данного типа, избегая приведения типа в исходном коде. Помните что основной механизм распределения слайсов может быть изменён с помощью переменной окружения G_SLICE=always-malloc.

type : тип для распределения, обычно имя структуры
Возвращает : указатель на распределённый блок, приведённый к указателю type.

Начиная с версии 2.10


g_slice_new0()

#define     g_slice_new0(type)

Удобный макрос для распределения блока памяти из распределителя слайсов и установки памяти в 0. Он вызывает g_slice_alloc0() с sizeof (type) и приводит возвращаемый указатель к указателю полученного типа, избегая приведения указателя в исходном коде. Помните что основной механизм распределения слайсов может быть изменён с помощью переменной окружения G_SLICE=always-malloc.

type : тип для распределения, обычно имя структуры
Возвращает : указатель на распределённый блок, приведённый к указателю type.

Начиная с версии 2.10


g_slice_free()

#define     g_slice_free(type, mem)

Удобный макрос для освобождения блока памяти который был распределён из распределителя слайсов. Он вызывает g_slice_free1() используя sizeof (type) как размер блока. Помните что существующее поведение может быть изменено с помощью переменной окружения G_DEBUG=gc-friendly.

type : тип блока для освобождения, обычно имя структуры
mem : указатель на блок для освобождения

Начиная с версии 2.10


g_slice_free_chain()

#define     g_slice_free_chain(type, mem_chain, next)

Освобождает связанный список блоков памяти структуры имеющей тип type. Блоки памяти должны быть одинакового размера, распределены через g_slice_alloc() или g_slice_alloc0() и связаны вместе указателем next (так же как в GSList). Имя поля next в type помещают как третий аргумент. Помните что существующее поведение может быть изменено с помощью переменной окружения G_DEBUG=gc-friendly.

type : тип mem_chain блоков
mem_chain : указатель на первый блок цепочки
next : имя поля следующего указателя в type

Начиная с версии 2.10



[5] [Bonwick94] Jeff Bonwick, The slab allocator: Кэширующий объекты распределитель памяти ядра. USENIX 1994, и [Bonwick01] Bonwick and Jonathan Adams, Magazines and vmem: Расширенное распределение слайсов для множества процессоров и произвольных ресурсов. USENIX 2001


Регистрация сообщений

Message Logging — Универсальная поддержка для регистрации сообщений с разным уровнем важности.

Краткое описание


#include <glib.h>


#define     G_LOG_DOMAIN
#define     G_LOG_FATAL_MASK
#define     G_LOG_LEVEL_USER_SHIFT
void        (*GLogFunc)                     (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *message,
                                             gpointer user_data);
enum        GLogLevelFlags;

void        g_log                           (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *format,
                                             ...);
void        g_logv                          (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *format,
                                             va_list args);
#define     g_message                       (...)
#define     g_warning                       (...)
#define     g_critical                      (...)
#define     g_error                         (...)
#define     g_debug                         (...)

guint       g_log_set_handler               (const gchar *log_domain,
                                             GLogLevelFlags log_levels,
                                             GLogFunc log_func,
                                             gpointer user_data);
void        g_log_remove_handler            (const gchar *log_domain,
                                             guint handler_id);
GLogLevelFlags g_log_set_always_fatal       (GLogLevelFlags fatal_mask);
GLogLevelFlags g_log_set_fatal_mask         (const gchar *log_domain,
                                             GLogLevelFlags fatal_mask);
void        g_log_default_handler           (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *message,
                                             gpointer unused_data);
GLogFunc    g_log_set_default_handler       (GLogFunc log_func,
                                             gpointer user_data);

Описание

Эти функции обеспечивают поддержку для регистрации сообщений об ошибках или отладочных сообщений.

Есть несколько встроенных уровней сообщений определённых в GLogLevelFlags. Они могут быть дополнены определёнными пользователем уровнями.

Детали

G_LOG_DOMAIN

#define G_LOG_DOMAIN    ((gchar*) 0)

Определяет область регистрации. Для приложений обычно используется по умолчанию NULL (или "") область. Библиотеки должны определять это так, чтобы любые сообщения которые они регистрируют можно было отличить от сообщений из других библиотек или кода приложений. Но избегайте определения их в общих заголовочных файлах.

Например, GTK+ использует это в своём Makefile.am:

INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"

G_LOG_FATAL_MASK

#define G_LOG_FATAL_MASK        (G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR)

Регистрационные уровни GLib которые рассматриваются фатальными по умолчанию.


G_LOG_LEVEL_USER_SHIFT

#define G_LOG_LEVEL_USER_SHIFT  (8)

Смещение регистрационного уровня для определения пользователем уровней регистрации (0-7 использует GLib).


GLogFunc ()

void        (*GLogFunc)                     (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *message,
                                             gpointer user_data);

Определяет прототип функции обработчика журнала регистрации.

log_domain : область регистрации сообщения.
log_level : регистрационный уровень сообщения (включая фатальный и рекурсивный флаги).
message : сообщение для обработки.
user_data : пользовательские данные, устанавливаемые в g_log_set_handler().

enum GLogLevelFlags

typedef enum
{
  /* регистрационные флаги */
  G_LOG_FLAG_RECURSION          = 1 << 0,
  G_LOG_FLAG_FATAL              = 1 << 1,

  /* уровни регистрации GLib */
  G_LOG_LEVEL_ERROR             = 1 << 2,       /* всегда фатально */
  G_LOG_LEVEL_CRITICAL          = 1 << 3,
  G_LOG_LEVEL_WARNING           = 1 << 4,
  G_LOG_LEVEL_MESSAGE           = 1 << 5,
  G_LOG_LEVEL_INFO              = 1 << 6,
  G_LOG_LEVEL_DEBUG             = 1 << 7,

  G_LOG_LEVEL_MASK              = ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL)
} GLogLevelFlags;

Флаги определяющие уровень регистрации сообщений.


g_log ()

void        g_log                           (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *format,
                                             ...);

Регистрирует ошибку или отладочное сообщение. Если уровень регистрации фатальный, вызывается функция abort() для завершения программы.

log_domain : область регистрации, обычно G_LOG_DOMAIN.
log_level : уровень регистрации, или из GLogLevelFlags или уровень определённый пользователем.
format : форматированное сообщение. Смотрите документацию printf().
... : параметры вставляемые в форматированную строку.

g_logv ()

void        g_logv                          (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *format,
                                             va_list args);

Регистрирует ошибку или отладочное сообщение. Если уровень регистрации установлен фатальный, вызывается функция abort() для завершения программы.

log_domain : область регистрации.
log_level : уровень регистрации.
format : форматированная строка. Смотрите документацию printf().
args : параметры вставляемые в форматированную строку.

g_message()

#define     g_message(...)

Удобная функция/макрокоманда для регистрации обычных сообщений.

... : форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf())
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :

g_warning()

#define     g_warning(...)

Удобная функция/макрокоманда для регистрации предупреждающих сообщений.

Вы можете создать фатальное предупреждение во время выполнения установив переменную окружения G_DEBUG (смотрите Running GLib Applications).

... : форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf())
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :

g_critical()

#define     g_critical(...)

Регистрирует критическое предупреждение "critical warning" (G_LOG_LEVEL_CRITICAL). Определяется приложением чем отличается критическое от обычного предупреждения. Вы можете вызвать g_log_set_always_fatal() чтобы выйти из программы при критическом предупреждении, затем использовать g_critical() для фатальных ошибок, например.

Вы также можете сделать критическое предупреждение фатальным установив во время выполнения переменную окружения G_DEBUG (смотрите Running GLib Applications).

... : форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf())
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :

g_error()

#define     g_error(...)

Удобная функция/макрокоманда для регистрации сообщения об ошибке. Сообщение об ошибке всегда фатально, приводит к вызову функции abort() для завершения приложения. Эта функция приводит к дампу ядра (core dump); не используйте её для ошибок о которых вы знаете. Использование этой функции указывает ошибку в вашей программе, то есть на ошибочное условие выполнения.

... : форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf())
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :

g_debug()

#define     g_debug(...)

Удобная функция/макрокоманда для регистрации отладочных сообщений.

... : форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf())
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :
... :

Начиная с версии 2.6


g_log_set_handler ()

guint       g_log_set_handler               (const gchar *log_domain,
                                             GLogLevelFlags log_levels,
                                             GLogFunc log_func,
                                             gpointer user_data);

Устанавливает обработчик журналов регистрации для области установленного уровня регистрации. Для обработки фатальных и рекурсивных сообщений параметр log_levels должен комбинироваться с битовыми флагами G_LOG_FLAG_FATAL и G_LOG_FLAG_RECURSION.

Помните, что, так как уровень регистрации G_LOG_LEVEL_ERROR всегда фатальный, чтобы установить обработчик для этого уровня регистрации вы должны скомбинировать его с G_LOG_FLAG_FATAL.

Пример 13. Добавление обработчика журнала регистрации для всех предупреждающих сообщений в области (приложении) по умолчанию

  g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
                     | G_LOG_FLAG_RECURSION, my_log_handler, NULL);

Пример 14. Добавление обработчика журнала регистрации для всех критических сообщений из GTK+

  g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
                     | G_LOG_FLAG_RECURSION, my_log_handler, NULL);

Пример 15. Добавление обработчика журнала регистраций для всех сообщений из GLib

  g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
                     | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
log_domain : область регистрации, или NULL для области приложения по умолчанию "".
log_levels : уровень регистрации для применения обработчика. Для обработки фатальных и рекурсивных сообщений скомбинируйте регистрационные уровни с битовыми флагами G_LOG_FLAG_FATAL и G_LOG_FLAG_RECURSION.
log_func : функция обработки регистрации.
user_data : данные помещаемые в обработчик регистрации.
Возвращает : id нового обработчика.

g_log_remove_handler ()

void        g_log_remove_handler            (const gchar *log_domain,
                                             guint handler_id);

Удаляет обработчик регистрации.

log_domain : область регистрации.
handler_id : id обработчика, который возвращает g_log_set_handler().

g_log_set_always_fatal ()

GLogLevelFlags g_log_set_always_fatal       (GLogLevelFlags fatal_mask);

Устанавливает сообщение уровень которого всегда является фатальным, в любой области регистрации. Когда сообщение с этим уровнем зарегистрировано приложение закрывается. Вы можете только установить фатальные уровни определенные в GLib. G_LOG_LEVEL_ERROR всегда фатально.

Вы можете также сделать некоторое сообщение фатальным установив во время выполнения переменную окружения G_DEBUG (смотрите Running GLib Applications).

fatal_mask : маска содержащая биты установленные для каждого уровня ошибки которая будет фатальной.
Возвращает : старая фатальная маска.

g_log_set_fatal_mask ()

GLogLevelFlags g_log_set_fatal_mask         (const gchar *log_domain,
                                             GLogLevelFlags fatal_mask);

Устанавливает регистрационный уровень который является фатальным в полученной области. G_LOG_LEVEL_ERROR всегда фатально.

log_domain : регистрационная область.
fatal_mask : новая фатальная маска.
Возвращает : старая фатальная маска для области регистрации.

g_log_default_handler ()

void        g_log_default_handler           (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *message,
                                             gpointer unused_data);

Обработчик регистрации по умолчанию устанавливается GLib; g_log_set_default_handler() позволяет установить альтернативу обработчика регистрации по умолчанию. Эта функция используется если нет обработчика регистраций установленного для специальной области и комбинации регистрационного уровня. Она выводит сообщения в stderr или stdout и если регистрационный уровень фатальный она вызывает abort().

stderr используется для уровней G_LOG_LEVEL_ERROR, G_LOG_LEVEL_CRITICAL, G_LOG_LEVEL_WARNING и G_LOG_LEVEL_MESSAGE. stdout используется для остальных.

log_domain : регистрационная область сообщения.
log_level : уровень сообщения.
message : сообщение.
unused_data : данные помещённые из g_log() которые не использованы.

g_log_set_default_handler ()

GLogFunc    g_log_set_default_handler       (GLogFunc log_func,
                                             gpointer user_data);

Устанавливает обработчик журнала регистраций по умолчанию если нет обработчика установленного для специальной области регистрации и комбинации уровня регистрации. По умолчанию, GLib использует g_log_default_handler() как обработчик журнала регистрации.

log_func : функция обработчика регистрации.
user_data : данные помещаемые в обработчик регистрации.
Возвращает : предыдущий обработчик регистрации по умолчанию

Начиная с версии 2.6


Разные макросы

Miscellaneous Macros — Специфичные макросы которые используются не часто.

Краткое описание


#include <glib.h>


#define     G_INLINE_FUNC

#define     G_STMT_START
#define     G_STMT_END

#define     G_BEGIN_DECLS
#define     G_END_DECLS

#define     G_N_ELEMENTS                    (arr)

#define     G_VA_COPY                       (ap1,ap2)

#define     G_STRINGIFY                     (macro_or_string)

#define     G_GNUC_EXTENSION
#define     G_GNUC_CONST
#define     G_GNUC_PURE
#define     G_GNUC_MALLOC
#define     G_GNUC_DEPRECATED
#define     G_GNUC_NORETURN
#define     G_GNUC_UNUSED
#define     G_GNUC_PRINTF                   ( format_idx, arg_idx )
#define     G_GNUC_SCANF                    ( format_idx, arg_idx )
#define     G_GNUC_FORMAT                   ( arg_idx )
#define     G_GNUC_NULL_TERMINATED
#define     G_GNUC_WARN_UNUSED_RESULT
#define     G_GNUC_FUNCTION
#define     G_GNUC_PRETTY_FUNCTION
#define     G_GNUC_NO_INSTRUMENT
#define     G_HAVE_GNUC_VISIBILITY
#define     G_GNUC_INTERNAL

#define     G_LIKELY                        (expr)
#define     G_UNLIKELY                      (expr)

#define     G_STRLOC
#define     G_STRFUNC

#define     G_GINT16_MODIFIER
#define     G_GINT16_FORMAT
#define     G_GUINT16_FORMAT
#define     G_GINT32_MODIFIER
#define     G_GINT32_FORMAT
#define     G_GUINT32_FORMAT
#define     G_GINT64_MODIFIER
#define     G_GINT64_FORMAT
#define     G_GUINT64_FORMAT
#define     G_GSIZE_MODIFIER
#define     G_GSIZE_FORMAT
#define     G_GSSIZE_FORMAT

Описание

Эти макросы обеспечивают много специфичных улучшений которые не часто нужны разработчикам программ.

Детали

G_INLINE_FUNC

#define     G_INLINE_FUNC

Этот макрос используется для экспорта прототипов функций, таким образом они могут быть связаны с внешними версиями когда включение в заголовок (inlining) не выполнено. Файл который реализует функции должен определить G_IMPLEMENTS_INLINES перед включением заголовков которые содержат G_INLINE_FUNC деклорации. Так как inlining очень зависит от компилятора, правильно использовать этот макрос очень сложно.

Этот макрос часто принимается для замены ключевого слова; ключевое слово уже объявлено переносимым способом в glib заголовках и может использоваться обычно.


G_STMT_START

#define     G_STMT_START

Используется внутри многооператорного макроса так чтобы он мог быть использован в местах, где компилятором ожидается только один оператор.


G_STMT_END

#define     G_STMT_END

Используется внутри многооператорного макроса так чтобы он мог быть использован в местах, где компилятором ожидается только один оператор.


G_BEGIN_DECLS

#define     G_BEGIN_DECLS

Используется (наряду с G_END_DECLS) для ограничения (bracket) заголовочных файлов. Если используемый компилятор это C++ компилятор, добавляется extern "C" рядом с заголовком.


G_END_DECLS

#define     G_END_DECLS

Используется (наряду с G_BEGIN_DECLS) для ограничения заголовочных файлов. Если используемый компилятор это C++ компилятор, добавляется extern "C" рядом с заголовком.


G_N_ELEMENTS()

#define G_N_ELEMENTS(arr)		(sizeof (arr) / sizeof ((arr)[0]))

Определяет количество элементов в массиве. Массив должен быть объявлен чтобы компилятор знал его размер во время компиляции; этот макрос не будет работать на массиве распределённом в динамической памяти, только статические массивы или массивы в стеке.

arr : массив

G_VA_COPY()

#define     G_VA_COPY(ap1,ap2)

Переносимый способ копирования va_list переменных.

Чтобы использовать эту функцию, вы должны включить string.h самостоятельно, потому что эта команда может использовать memmove(), а GLib не включит string.h за вас.

ap1 : переменная va_list помещаемая в виде копии ap2.
ap2 : va_list.

G_STRINGIFY()

#define G_STRINGIFY(macro_or_string)	G_STRINGIFY_ARG (macro_or_string)

Принимает макрос или строку и преобразует в строку.

macro_or_string : макрос или строка.

G_GNUC_EXTENSION

#define     G_GNUC_EXTENSION

Расширение для __extension__ когда в качестве компилятора используется gcc. Это просто сообщает gcc не предупреждать о следующем не стандартном коде когда выполняется компиляция с опцией -pedantic.


G_GNUC_CONST

#define     G_GNUC_CONST

Расширение для GNU C const параметра функции если компилятор gcc. Объявляет функцию как константу включающую лучшую оптимизацию вызываемой функции. Константная функция не проверяет никаких значений кроме параметров, и влияет только на возвращаемое значение. Детали смотрите в документации GNU C.

Примечание

Функция которая имеет указанные аргументы и проверяет указанные данные не должна объявляться константой. Аналогично, функция которая вызвана не константной функцией обычно не должна быть константной. Это не имеет смысла для функций констант возвращающих (void) пустое значение.


G_GNUC_PURE

#define     G_GNUC_PURE

Расширение для GNU C pure параметра функции если компилятор gcc. Объявление функции как полное включение (pure enables) улучшает оптимизацию вызова функции. Полные (pure) функции имеют влияние только на возвращаемое значение а возвращаемое значение зависит только от параметров и/или глобальных переменных. Детали смотрите в документации GNU C.


G_GNUC_MALLOC

#define     G_GNUC_MALLOC

Расширение для GNU C malloc параметра функции если компилятор gcc. Объявление функции с включением malloc улучшает оптимизацию функции. Функция может иметь параметр malloc, если возвращаемый указатель гарантировано не связан с любым другим указателем когда возвращается функцией (на практике, это означает вновь распределяемую память). Подробности смотрите в документации GNU C.

Начиная с версии 2.6


G_GNUC_DEPRECATED

#define     G_GNUC_DEPRECATED

Расширение для GNU C deprecated параметра для компилятора gcc. Он может использоваться для маркировки определения типа (typedefs), переменных и функций как устаревших. Когда вызывается с опцией -Wdeprecated, компилятор будет предупреждать когда используется устаревший интерфейс. Подробности смотрите в документации GNU C.

Начиная с версии 2.2


G_GNUC_NORETURN

#define     G_GNUC_NORETURN

Расширение для GNU C noreturn параметра функции, если компилятор gcc. Он используется для объявления функции когда нет возвращаемого значения. Включает оптимизацию функции и предотвращает возможные предупреждения компилятора. Детали смотрите в документации GNU C.


G_GNUC_UNUSED

#define     G_GNUC_UNUSED

Расширение GNU C unused параметра функции, если компилятор gcc. Используется для объявления функций которые никогда не используются. Предотвращает возможные предупреждения компилятора. Подробности смотрите в документации GNU C.


G_GNUC_PRINTF()

#define     G_GNUC_PRINTF( format_idx, arg_idx )

Расширение для GNU C format параметра функции, если компилятор gcc. Используется для объявления функций которые принимают разное количество аргументов с таким же синтаксисом как у printf(). Позволяет компилятору контролировать типы помещаемых аргументов в функцию. Подробности смотрите в GNU C.

gint g_snprintf (gchar  *string,
                 gulong       n,
                 gchar const *format,
                 ...) G_GNUC_PRINTF (3, 4);
format_idx : перечень аргументов соответствующий форматируемой строке. (Нумерация аргументов начинается с 1).
arg_idx : первый из форматируемых параметров.

G_GNUC_SCANF()

#define     G_GNUC_SCANF( format_idx, arg_idx )

Расширение GNU C format параметра функции, если компилятор gcc. Используется для объявления функций которые принимают переменное количество аргументов, с таким же синтаксисом как у scanf(). Позволяет компилятору проверять тип помещаемых в функцию аргументов. Подробности смотрите в документации GNU C.

format_idx : перечень аргументов соответствующий форматируемой строке. (Нумерация аргументов начинается с 1).
arg_idx : первый из форматируемых параметров.

G_GNUC_FORMAT()

#define     G_GNUC_FORMAT( arg_idx )

Расширение GNU C format_arg параметра функции, если компилятор gcc. Этот атрибут функции определяет что функция принимает форматированную строку в стиле функций printf(), scanf(), strftime() или strfmon() и модифицирует так, чтобы результат можно было поместить в printf(), scanf(), strftime() или strfmon() функцию (с оставшимися параметрами в формате функции так же, как если они были бы не модифицированной строкой). Подробности смотрите в документации GNU C.

gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
arg_idx : порядковый номер аргумента.

G_GNUC_NULL_TERMINATED

#define     G_GNUC_NULL_TERMINATED

Расширение GNU C sentinel параметра функции, если компилятор gcc, или "" если нет. Этот параметр функции применяется только к variadic функциям и инструктирует компилятор проверить что список аргументов завершается явным NULL. Подробности смотрите в документации GNU C.

Начиная с версии 2.8


G_GNUC_WARN_UNUSED_RESULT

#define     G_GNUC_WARN_UNUSED_RESULT

Расширение GNU C warn_unused_ersult параметра функции, если компилятор gcc, или "" если нет. Этот параметр функции заставляет компилятор сообщать предупреждение, если результат вызова функции игнорируется. Подробности смотрите в документации GNU C.

Начиная с версии 2.10


G_GNUC_FUNCTION

#define     G_GNUC_FUNCTION

Расширение GNU C __FUNCTION__ переменной, если компилятор gcc, или "" если нет. GNU C __FUNCTION__ переменная содержит имя текущей функции. Подробности смотрите в документации GNU C.


G_GNUC_PRETTY_FUNCTION

#define     G_GNUC_PRETTY_FUNCTION

Расширение для GNU C __PRETTY_FUNCTION__ переменной, если компилятор gcc, или "" если нет. GNU C __PRETTY_FUNCTION__ переменная содержит имя текущей функции. Для C программ это тоже самое как переменная __FUNCTION__, но для C++ включается дополнительная информация, такая как прототип и класс функции. Подробности смотрите в документации GNU C.


G_GNUC_NO_INSTRUMENT

#define     G_GNUC_NO_INSTRUMENT

Расширение GNU C no_instrument_function параметра функции, если компилятор gcc. Функция с этим параметром не будет инструментом для профилирования, когда компилятор вызывается с опцией -finstrument-functions. Подробности смотрите в документации GNU C.


G_HAVE_GNUC_VISIBILITY

#define G_HAVE_GNUC_VISIBILITY 1

Этот макрос определяется как 1, если компилятор поддерживает ELF видимость атрибутов (на данный момент только gcc).

Начиная с версии 2.6


G_GNUC_INTERNAL

#define G_GNUC_INTERNAL __attribute__((visibility("hidden")))

Расширение GNU C visibility(hidden) параметра, если компилятор поддерживает это (в настоящее время только gcc). Этот параметр может использоваться для маркировки библиотечных функций как используемые только внутри библиотеки, чтобы не создавать не эффективный ввод PLT. Помните что статичные функции не нуждаются в подобной маркировки. Подробности смотрите в документации GNU C.

Начиная с версии 2.6


G_LIKELY()

#define     G_LIKELY(expr)

Подсказывает компилятору что логическое выражение вероятно эквивалентно значению true. Компилятор может использовать эту информацию для оптимизации.

if (G_LIKELY (random() != 1))
  g_print ("not one");
expr : логическое выражение

Начиная с версии 2.2


G_UNLIKELY()

#define     G_UNLIKELY(expr)

Подсказывает компилятору что логическое выражение вероятно не равно значению true. Компилятор может использовать эту информацию для оптимизации.

if (G_UNLIKELY (random() == 1))
  g_print ("a random one");
expr : логическое выражение

Начиная с версии 2.2


G_STRLOC

#define     G_STRLOC

Дополняется до строки идентифицирующей текущую позицию кода.


G_STRFUNC

#define     G_STRFUNC

Дополняется до строки идентифицирующей текущую функцию.

Начиная с версии 2.4


G_GINT16_MODIFIER

#define G_GINT16_MODIFIER "h"

Платформо-зависимая длина модификатора для создания преобразуемых модификаторов printf() для значений типов gint16 или guint16. Это строковые литералы, но не включающие знак процента, так что вы можете добавить точность и длину модификатора между знаком процента и преобразующим спецификатором и прибавить с переди преобразованный спецификатор.

Следующий пример печатает "0x7b";

gint16 value = 123;
g_print ("%#" G_GINT16_MODIFIER "x", value);

Начиная с версии 2.4


G_GINT16_FORMAT

#define G_GINT16_FORMAT "hi"

Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gint16. Это строковый литерал, но не включает знак процента, таким образом вы можете добавлять точность и длину модификатора между знаком процента и спецификатором преобразования.

gint16 in;
gint32 out;
sscanf ("42", "%" G_GINT16_FORMAT, &in)
out = in * 1000;
g_print ("%" G_GINT32_FORMAT, out);


G_GUINT16_FORMAT

#define G_GUINT16_FORMAT "hu"

Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа guint16. Смотрите также G_GINT16_FORMAT.


G_GINT32_MODIFIER

#define G_GINT32_MODIFIER ""

Платформо-зависимая длина модификатора для создания преобразуемых спецификаторов printf() для значений типов gint32 или guint32. Смотрите также G_GINT16_MODIFIER.

Начиная с версии 2.4


G_GINT32_FORMAT

#define G_GINT32_FORMAT "i"

Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gint32. Смотрите также G_GINT16_FORMAT.


G_GUINT32_FORMAT

#define G_GUINT32_FORMAT "u"

Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа guint32. Смотрите также G_GINT16_FORMAT.


G_GINT64_MODIFIER

#define G_GINT64_MODIFIER "ll"

Зависящая от платформы длина модификатора для создания спецификаторов преобразования printf() для значений типов gint64 или guint64. Смотрите также G_GINT16_MODIFIER.

Примечание

Некоторые платформы не поддерживают печать 64 битных целочисленных, даже если поддерживают типы. На таких платформах G_GINT64_MODIFIER не определяется.

Начиная с версии 2.4


G_GINT64_FORMAT

#define G_GINT64_FORMAT "lli"

Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gint64. Смотрите также G_GINT16_FORMAT.

Примечание

Некоторые платформы не поддерживают сканирование и печать 64 битных целочисленных, даже если поддерживают типы. На таких платформах G_GINT64_FORMAT не определяется. Помните что scanf() может не поддерживать 64 битные целочисленные, даже если G_GINT64_FORMAT определён. Из-за плохой обработки ошибок, scanf() не рекомендуется для использования в анализе так или иначе; вместо неё возможно использование g_strtoull().


G_GUINT64_FORMAT

#define G_GUINT64_FORMAT "llu"

Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа guint64. Смотрите также G_GINT16_FORMAT.

Примечание

Некоторые платформы не поддерживают сканирование и печать 64 битных целочисленных, даже если поддерживают типы. На таких платформах G_GUINT64_FORMAT не определяется. Помните что scanf() может не поддерживать 64 битные целочисленные, даже если G_GUINT64_FORMAT определён. Из-за плохой обработки ошибок, scanf() не рекомендуется для использования в анализе так или иначе; вместо неё возможно использование g_strtoull().


G_GSIZE_MODIFIER

#define G_GSIZE_MODIFIER ""

Платформо-зависимая длина модификатора для создания спецификаторов printf() для значений типов gsize или gssize. Смотрите также G_GINT16_MODIFIER.

Начиная с версии 2.6


G_GSIZE_FORMAT

#define G_GSIZE_FORMAT "u"

Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gsize. Смотрите также G_GINT16_FORMAT.

Начиная с версии 2.6


G_GSSIZE_FORMAT

#define G_GSSIZE_FORMAT "i"

Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gssize. Смотрите также G_GINT16_FORMAT.

Начиная с версии 2.6


Miscellaneous Utility Functions

Miscellaneous Utility Functions — Набор портируемых сервисных функций.

Краткое описание


#include <glib.h>


const gchar* g_get_application_name         (void);
void        g_set_application_name          (const gchar *application_name);
gchar*      g_get_prgname                   (void);
void        g_set_prgname                   (const gchar *prgname);
const gchar* g_getenv                       (const gchar *variable);
gboolean    g_setenv                        (const gchar *variable,
                                             const gchar *value,
                                             gboolean overwrite);
void        g_unsetenv                      (const gchar *variable);
gchar**     g_listenv                       (void);
const gchar* g_get_user_name                (void);
const gchar* g_get_real_name                (void);
const gchar* g_get_user_cache_dir           (void);
const gchar* g_get_user_data_dir            (void);
const gchar* g_get_user_config_dir          (void);
const gchar* const * g_get_system_data_dirs (void);
const gchar* const * g_get_system_config_dirs
                                            (void);

const gchar* g_get_host_name                (void);
const gchar* g_get_home_dir                 (void);
const gchar* g_get_tmp_dir                  (void);
gchar*      g_get_current_dir               (void);
const gchar* g_basename                     (const gchar *file_name);
#define     g_dirname
gboolean    g_path_is_absolute              (const gchar *file_name);
const gchar* g_path_skip_root               (const gchar *file_name);
gchar*      g_path_get_basename             (const gchar *file_name);
gchar*      g_path_get_dirname              (const gchar *file_name);
gchar*      g_build_filename                (const gchar *first_element,
                                             ...);
gchar*      g_build_filenamev               (gchar **args);
gchar*      g_build_path                    (const gchar *separator,
                                             const gchar *first_element,
                                             ...);
gchar*      g_build_pathv                   (const gchar *separator,
                                             gchar **args);

gchar*      g_find_program_in_path          (const gchar *program);

gint        g_bit_nth_lsf                   (gulong mask,
                                             gint nth_bit);
gint        g_bit_nth_msf                   (gulong mask,
                                             gint nth_bit);
guint       g_bit_storage                   (gulong number);

guint       g_spaced_primes_closest         (guint num);

void        g_atexit                        (GVoidFunc func);

guint       g_parse_debug_string            (const gchar *string,
                                             const GDebugKey *keys,
                                             guint nkeys);
            GDebugKey;

void        (*GVoidFunc)                    (void);
void        (*GFreeFunc)                    (gpointer data);

void        g_qsort_with_data               (gconstpointer pbase,
                                             gint total_elems,
                                             gsize size,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

void        g_nullify_pointer               (gpointer *nullify_location);

Описание

Эти функции являются портируемыми сервисными функциями.

Детали

g_get_application_name ()

const gchar* g_get_application_name         (void);

Получает удобочитаемое имя приложения, установленное с помощью g_set_application_name(). Это имя должно быть локализовано если возможно и передано для отображения пользователю. В отличие от g_get_prgname(), которая получает не локализованное имя. Если g_set_application_name() не была вызвана, возвращается результат из g_get_prgname() (который может быть NULL если g_set_prgname() также не была вызвана).

Возвращает : удобочитаемое имя программы. Может вернутся NULL

Начиная с версии 2.2


g_set_application_name ()

void        g_set_application_name          (const gchar *application_name);

Устанавливает удобочитаемое имя для приложения. Это имя должно быть локализовано если возможно и предоставлено для отображения пользователю. В отличие от g_set_prgname(), которая устанавливает не локализованное имя. g_set_prgname() будет вызвана автоматически функцией gtk_init(), но g_set_application_name() не будет.

Помните что из соображений потокобезопасности, эти функции должны вызываться только один раз.

Имя приложения используется в таком контексте как сообщения об ошибках (error messages), или при отображении имени приложения в списке задач.

application_name : локализованное имя приложения

g_get_prgname ()

gchar*      g_get_prgname                   (void);

Получает имя программы. Это имя должно быть не локализовано, в отличие от g_get_application_name(). (Если вы используете GDK или GTK+ имя программы устанавливает gdk_init(), которую вызывает gtk_init(). Имя программы находится в последнем компоненте argv[0].)

Возвращает : имя программы. Возвращаемая строка принадлежит GLib и не должна освобождаться или модифицироваться.

g_set_prgname ()

void        g_set_prgname                   (const gchar *prgname);

Устанавливает имя программы. Это имя не должно быть локализовано, в отличие от g_set_application_name(). Помните что из соображений потокобезопасности эта функция должна вызываться один раз.

prgname : имя программы.

g_getenv ()

const gchar* g_getenv                       (const gchar *variable);

Возвращает значение переменной окружения. Имя и значение находятся в кодировке имён файлов GLib. В UNIX, это фактически означает байты которые могут или не могут быть в некотором последовательном наборе символов или кодировке. В Windows, это UTF-8. В Windows, в случае когда переменная окружения содержит ссылку на другие переменные окружения, они рассширяются.

variable : переменная окружения для получения значения, в кодировке имён файлов GLib.
Возвращает : значение переменной окружения, или NULL если переменная окружения не найдена. Возвращаемая строка может быть переписана следующим вызовом g_getenv(), g_setenv() или g_unsetenv().

g_setenv ()

gboolean    g_setenv                        (const gchar *variable,
                                             const gchar *value,
                                             gboolean overwrite);

Устанавливает переменную окружения. И значение переменной и её имя должны быть в кодировке имён файлов GLib. В UNIX, это означает что они могут быть в любой последовательности байт. В Windows, они должны быть в UTF-8.

Помните что в некоторых системах, когда переменные перезаписаны, память используется для предыдущих переменных и их значения не изменяется.

variable : переменная окружения для установки, не должна содержать '='.
value : значение для устанавливаемой переменной.
overwrite : изменять ли переменную если она уже существует.
Возвращает : FALSE если переменная окружения не может быть установлена.

Начиная с версии 2.4


g_unsetenv ()

void        g_unsetenv                      (const gchar *variable);

Удаляет переменную окружения.

Помните что в некоторых системах, когда перезаписывается переменная, память используемая для предыдущих переменных и их значения не изменяется. Кроме того, эта функция не гарантирует потокобезопасную работу.

variable : переменная окружения для удаления, не должна содержать '='.

Начиная с версии 2.4


g_listenv ()

gchar**     g_listenv                       (void);

Получает имена всех установленных переменных окружения.

Возвращает : NULL-завершённый список строк который должен освобождаться с помощью g_strfreev(). Программы которые должны быть портированы в Windows обычно должны использовать эту функцию и g_getenv() вместо использования массива переменных окружения непосредственно из библиотеки C. В Windows, строки в массиве переменных окружения находятся в системной кодировке, тогда как в большинстве обычных случаев для переменных окружения в программах GLib вам понадобится использовать кодировку UTF-8 которую обеспечивает эта функция и g_getenv().

Начиная с версии 2.8


g_get_user_name ()

const gchar* g_get_user_name                (void);

Получает текущее имя пользователя. Кодировка возвращаемой строки определяется системой. В UNIX, это может быть предпочтительно кодировка имён файлов, или что-то ещё, и нет никакой гарантии что это даже не противоречит машине. В Windows, это всегда UTF-8.

Возвращает : текущее имя пользователя.

g_get_real_name ()

const gchar* g_get_real_name                (void);

Получает реальное имя пользователя. Оно обычно берётся из пользовательского ввода в файле passwd. Кодировка возвращаемой строки определяется системой. (В Windows, это всегда UTF-8.) Если реальное имя пользователя не определено, то возвращается строка "Unknown".

Возвращает : реальное имя пользователя.

g_get_user_cache_dir ()

const gchar* g_get_user_cache_dir           (void);

Возвращает основной каталог в котором хранятся несущественные, кэшируемые, специфические данные для определённого пользователя.

На UNIX платформах это определяется используя механизм описанный в XDG Base Directory Specification

Возвращает : строка которой владеет GLib и которую не нужно освобождать или модифицировать.

Начиная с версии 2.6


g_get_user_data_dir ()

const gchar* g_get_user_data_dir            (void);

Возвращает основной каталог для доступа приложений к данным на подобие значков которые настроены для определённого пользователя.

На UNIX платформах это определяется с использованием механизма описанного в XDG Base Directory Specification

Возвращает : строка которой владеет GLib и которую не нужно освобождать или модифицировать.

Начиная с версии 2.6


g_get_user_config_dir ()

const gchar* g_get_user_config_dir          (void);

Возвращает основной каталог в котором хранится конфигурационная информация приложений для определённого пользователя, такая как свойства (preferences) и настройки (settings).

На UNIX платформах это определяется с использованием механизма описанного в XDG Base Directory Specification

Возвращает : строка которой владеет GLib и которую не нужно освобождать или изменять.

Начиная с версии 2.6


g_get_system_data_dirs ()

const gchar* const * g_get_system_data_dirs (void);

Возвращает упорядоченный список основных каталогов для доступа приложений к общесистемным данным.

На UNIX платформах это определяется с помощью механизма описанного в XDG Base Directory Specification

В Windows первыми элементами списка являются Application Data (Данные приложения) и Documents folders (Каталог документов) для All Users (Всех пользователей). (Это определено только в Windows 2000 или более поздних версиях и не представлено в списках других версий Windows.) Смотрите документацию для CSIDL_COMMON_APPDATA и CSIDL_COMMON_DOCUMENTS.

Затем следует "общий" подкаталог в инсталяционном каталоге для пакета содержащего DLL который вызывает эта функция, если он может быть определён.

В конце список содержит "общий" подкаталог в инсталяционном каталоге для GLib, и в инсталяционном каталоге пакет приложений файлов .exe.

Инсталяционные каталоги выше определяются поиском каталога где расположены модули (DLL или EXE). Если имя каталога "bin", используется его родитель, иначе непосредственно сам каталог.

Помните что возвращаемый Windows список может зависеть от того где вызвать эту функцию.

Возвращает : NULL-завершённый массив строк которым владеет GLib и который не нужно освобождать или изменять.

Начиная с версии 2.6


g_get_system_config_dirs ()

const gchar* const * g_get_system_config_dirs
                                            (void);

Возвращает упорядоченный список общих каталогов в которых доступна общесистемная, конфигурационная, информация.

На UNIX платформах это определяется с использованием механизма описанного в XDG Base Directory Specification

Возвращает : NULL-завершённый массив строк которым владеет GLib и который не должен освобождаться или изменятся.

Начиная с версии 2.6


g_get_host_name ()

const gchar* g_get_host_name                (void);

Возвращает имя машины.

Возвращаемое имя - не обязательно полностью-компетентное имя домена, или даже представленное в DNS или в некотором другом сервисе имён вообще. Оно не должно даже быть уникальным в вашей локальной сети или сайте, но обычно это так. Вызывающие программы не должны полагаться на возвращаемое значение, имеющее специфическое свойство как уникальность, в целях безопасности. Даже если имя машины изменено в процессе выполнения приложения, возвращаемое значение из функции не изменяется. Возвращаемой строкой владеет GLib и её не нужно освобождать или изменять. Если нет определённого имени, по умолчанию возвращается зафиксированная строка "localhost".

Возвращает : узловое имя машины (host name).

Начиная с версии 2.8


g_get_home_dir ()

const gchar* g_get_home_dir                 (void);

Возвращает текущий домашний каталог пользователя.

Помните что в отличие от традиционных UNIX инструментов, эта функция предпочитает ввод passwd через переменную окружения HOME.

Возвращает : текущий домашний каталог пользователя.

g_get_tmp_dir ()

const gchar* g_get_tmp_dir                  (void);

Возвращает каталог используемый для временных файлов. Она использует для этого переменную окружения TMPDIR, TMP и TEMP в соответствующем порядке. Если они не определены, то возвращается "/tmp" в UNIX и "C:\" в Windows. Кодировка возвращаемой строки зависит от системы. В Windows, это всегда UTF-8. Возвращаемое значение никогда не будет NULL.

Возвращает : каталог для временных файлов.

g_get_current_dir ()

gchar*      g_get_current_dir               (void);

Возвращает текущий каталог. Возвращаемая строка должна быть освобождена когда больше не нужна. Кодировка возвращаемой строки зависит от системы. В Windows, это всегда UTF-8.

Возвращает : текущий каталог.

g_basename ()

const gchar* g_basename                     (const gchar *file_name);

Внимание

g_basename устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Вместо неё используйте g_path_get_basename(), но помните что g_path_get_basename() распределяет новую память для возвращаемой строки, в отличие от этот функции которая возвращает указатель в параметре.

Возвращает имя файла без любых компонентов каталога. Она возвращает указатель на полученную строку имени файла.

file_name : имя файла.
Возвращает : имя файла без любых компонентов каталога.

g_dirname

#define     g_dirname

Внимание

g_dirname устарела и не должна использоваться во вновь создаваемом коде.

Эта функция устарела и будет удалена в следующих версиях GLib. Вместо неё используйте g_path_get_dirname().

Возвращает компоненты каталога имени файла. Если имя файла не имеет компонентов каталога, то возвращает ".". Возвращаемая строка должна быть освобождена когда будет больше не нужна.

Возвращает : компоненты каталога для файла.

g_path_is_absolute ()

gboolean    g_path_is_absolute              (const gchar *file_name);

Возвращает TRUE если полученное имя файла file_name является абсолютным, то есть оно содержит полный путь из корневого каталога, такой как "/usr/local" в UNIX или "C:\windows" в Windows системах.

file_name : имя файла.
Возвращает : TRUE если file_name является абсолютным именем.

g_path_skip_root ()

const gchar* g_path_skip_root               (const gchar *file_name);

Возвращает указатель в file_name после корневого компонента, то есть после "/" в UNIX или "C:\" в Windows. Если file_name не является абсолютным именем, то возвращается NULL.

file_name : имя файла.
Возвращает : указатель в file_name после корневого компонента.

g_path_get_basename ()

gchar*      g_path_get_basename             (const gchar *file_name);

Возвращает последний компонент имени файла. Если file_name завершается разделителем каталога она возвращает компонент перед последним слэшем. Если file_name содержит только разделители каталога (а в Windows, возможно букву диска), возвращается единственный разделитель. Если file_name пустой, она возвращает ".".

file_name : имя файла.
Возвращает : вновь распределённая строка содержащая последний компонент имени файла.

g_path_get_dirname ()

gchar*      g_path_get_dirname              (const gchar *file_name);

Возвращает компонент каталога имени файла. Если имя файла не имеет компонент каталога то возвращается ".". Возвращаемая строка должна быть освобождена когда будет больше не нужна.

file_name : имя файла.
Возвращает : компонент каталога имени файла.

g_build_filename ()

gchar*      g_build_filename                (const gchar *first_element,
                                             ...);

Создаёт имя файла из ряда элементов используя правильный разделитель для имён файлов.

В Unix, эта функция ведёт себя аналогично g_build_path (G_DIR_SEPARATOR_S, first_element, ....).

В Windows, она учитывает что может быть либо обратный слэш (\), либо слэш (/) может использоваться как разделитель имен файлов, но в остальном ведёт себя как в Unix. Когда необходимо вставить разделитель в имя пути файла, используется один из последних предварительно установленный в параметрах (читается слева на право).

Не делается никаких попыток сделать результирующие имя файла абсолютным путём. Если первый элемент является относительным путём, результат тоже будет относительным путём.

first_element : первый элемент в пути
... : сохраняемый элемент в пути, завершается NULL
Возвращает : вновь распределённая строка которая должна освобождаться с помощью g_free().

g_build_filenamev ()

gchar*      g_build_filenamev               (gchar **args);

Ведёт себя также как g_build_filename(), но принимает элементы пути как строковый массив, вместо массива аргументов. Эта функция в основном полезна для языковых привязок.

args : NULL-завершённый массив строк содержащих элементы пути.
Возвращает : вновь распределённая строка которую нужно освобождать с помощью g_free().

Начиная с версии 2.8


g_build_path ()

gchar*      g_build_path                    (const gchar *separator,
                                             const gchar *first_element,
                                             ...);

Создаёт имя из ряда элементов используя separator как разделитель между элементами. В границах между двумя элементами, любые возникшие завершающие разделители в первом элементе, или возникшие ведущие разделители во втором элементе удаляются и остаётся только одна копия вставленного разделителя.

Пустые элементы игнорируются.

Количество начальных разделителей в результате тоже самое как количество копий разделителя в первом не пустом элементе.

Количество завершающих копий разделителя в результате такое же как количество завершающих копий разделителя в последнем не пустом элементе. (Определение количества завершающих копий выполняется без вытеснения начальных копий, поэтому если разделитель ABA, ABABA имеет одну завершающую копию.)

Однако, если есть только один не пустой элемент, а в нём нет никаких символов и никаких частей начальных или завершающих разделителей, то результатом будет оригинальное значение этого элемента.

Кроме этого для определения количества начальных или завершающих копий разделителя, элементы содержащие только копии разделителя игнорируются.

separator : строка используемая для разделения элементов пути.
first_element : первый элемент в пути
... : сохраняемый элемент в пути, завершается NULL
Возвращает : вновь распределённая строка которая должна быть освобождена с помощью g_free().

g_build_pathv ()

gchar*      g_build_pathv                   (const gchar *separator,
                                             gchar **args);

Ведёт себя также как g_build_path(), но принимает элементы пути как строковый массив, вместо массива аргументов. Эта функция в основном полезна для языковых привязок (language bindings).

separator : строка используемая как разделитель элементов пути.
args : NULL-завершённый массив строк содержащий элементы пути.
Возвращает : вновь распределённая строка которую нужно освобождать с помощью g_free().

Начиная с версии 2.8


g_find_program_in_path ()

gchar*      g_find_program_in_path          (const gchar *program);

Определяет первую исполняемую именованную program в пути пользователя, тем же способом что execvp() определила бы это. Возвращает распределённую строку с абсолютным именем, или NULL если программа не найдена в пути. Если program уже является абсолютным путём, возвращает копию program если program существует и может исполняться, иначе NULL. В Windows, если program не имеет суффикса типа файла, проверит суффиксы .exe, .cmd, .bat и .com, и суффиксы в переменной окружения PATHEXT.

В Windows, она находит файл тем же способом как CreateProcess(). Это значит -- сначала в каталоге из которого исполняемая программа была загружена, затем в текущем каталоге, затем в системном каталоге Windows 32-bit, затем в каталоге Windows и в конце в каталоге указанном переменной окружения PATH. Если программа найдена, то возвращаемое значение содержит полное имя включая типовой суффикс.

program : имя программы в кодировке имён файлов GLib
Возвращает : абсолютный путь, или NULL

g_bit_nth_lsf ()

gint        g_bit_nth_lsf                   (gulong mask,
                                             gint nth_bit);

Находит позицию первого набора бит в mask, ищет вверх от (но не включая) nth_bit. Биты нумеруются с 0 (самый младший) до sizeof(gulong) * 8 - 1 (31 или 63, обычно). Для начала поиска с нулевого бита (0th bit), установите nth_bit в -1.

mask : gulong содержащий флаги.
nth_bit : номер бита с которого начинается поиск.
Возвращает : индекс первого набора бит которые больше чем nth_bit.

g_bit_nth_msf ()

gint        g_bit_nth_msf                   (gulong mask,
                                             gint nth_bit);

Находит позицию первого набора бит в mask, ищет вниз от (но не включая) nth_bit. Биты нумеруются с 0 (наименьшее значение) до sizeof(gulong) * 8 - 1 (31 или 63, обычно). Для поиска с последнего бита, установите nth_bit в -1 или GLIB_SIZEOF_LONG * 8.

mask : gulong содержащий флаги.
nth_bit : номер бита от которого начинается поиск.
Возвращает : индекс первого набора бит которые меньше чем nth_bit.

g_bit_storage ()

guint       g_bit_storage                   (gulong number);

Получает количество бит используемое для содержания number, например если number это 4, то необходимо 3 бита.

number : guint.
Возвращает : количество бит используемое для содержания number.

g_spaced_primes_closest ()

guint       g_spaced_primes_closest         (guint num);

Получает наименьшее простое число из внутреннего массива простых чисел, которое больше чем num. Это используется внутри GLib для расчёта оптимального размера GHashTable.

Внутренний массив простых чисел имеет диапазон от 11 до 13845163 such that each prime is approximately 1.5-2 times the previous prime.

num : guint.
Возвращает : наименьшее простое число из внутреннего массива простых чисел которое меньше чем num.

g_atexit ()

void        g_atexit                        (GVoidFunc func);

Специальная функция вызываемая для нормального завершения программы.

Начиная с GLib 2.8.2, в Windows g_atexit() фактически макрокоманда препроцессора которая вызывает функцию atexit() в библиотеке C. Это значит что в случае когда код вызова g_atexit(), то есть atexit(), находится в DLL, функция будет вызвана когда DLL отделена от программы. Это обычно имеет больше смысла, чем вызов функции когда GLib DLL отдельна, что происходило раньше когда g_atexit() была функцией в GLib DLL.

Поведение atexit() в контексте динамически загружаемых модулей формально не определено и непредсказуемо.

В POSIX системах, вызов g_atexit() (или atexit()) в динамически загружаемом модуле который выгружается перед завершением программы может вызвать крах при выходе из программы.

Некоторые POSIX системы реализуют atexit() как Windows, и имеют динамически загружаемый модуль поддерживающий собственную цепочку atexit которая вызывается когда модуль выгружен.

В других POSIX системах, перед выгрузкой динамически загружаемого модуля, регистрируется atexit функция (если есть) находящаяся в этом вызванном модуле, вне зависимости от нахождения зарегистрированного кода. Это по видимому самый надёжный подход.

Как видно из вышеупомянутого, для лучшей портируемости стоит избегать вызова g_atexit() (или atexit()) кроме как из основной исполняемой программы.

func : функция для вызова нормального завершения программы.

g_parse_debug_string ()

guint       g_parse_debug_string            (const gchar *string,
                                             const GDebugKey *keys,
                                             guint nkeys);

Анализирует строку содержащую параметры отладки в guint, содержащий битовые флаги. Это используется в GDK и GTK+ для анализа параметров отладки помещаемых в командную строку или через переменные окружения.

string : список параметров отладки разделённый двоеточиями, пробелами, или запятыми; или строка "all" для установки всех флагов.
keys : указатель на массив GDebugKey которые связывают строки с битовыми флагами.
nkeys : номер GDebugKeys в массиве.
Возвращает : комбинированный набор битовых флагов.

GDebugKey

typedef struct {
  gchar *key;
  guint	 value;
} GDebugKey;

Связывает строку с битовым флагом. Используется в g_parse_debug_string().

gchar *key; строка
guint value; флаг

GVoidFunc ()

void        (*GVoidFunc)                    (void);

Декларация функции которая не принимает аргументов и ничего не возвращает. Она используется для определения что специального типа функция помещена в g_atexit().


GFreeFunc ()

void        (*GFreeFunc)                    (gpointer data);

Декларация типа функции которая принимает в качестве аргумента указатель произвольных данных и не возвращает никакого значения. В текущий момент не используется в GLib или GTK+.

data : указатель данных.

g_qsort_with_data ()

void        g_qsort_with_data               (gconstpointer pbase,
                                             gint total_elems,
                                             gsize size,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

Тоже самое как стандартная C функция qsort(), но подпрограмма сравнения принимает параметр пользовательских данных.

pbase : начало массива для сортировки
total_elems : элементы в массиве
size : размер каждого элемента
compare_func : функция для сравнения элементов
user_data : данные для помещения в compare_func

g_nullify_pointer ()

void        g_nullify_pointer               (gpointer *nullify_location);

Устанавливает указатель в определённом расположении в NULL.

nullify_location : адрес указателя в памяти.

N-ary Trees

N-ary Trees — Деревья данных с любым количеством ответвлений.

Краткое описание


#include <glib.h>


            GNode;
GNode*      g_node_new                      (gpointer data);
GNode*      g_node_copy                     (GNode *node);
gpointer    (*GCopyFunc)                    (gconstpointer src,
                                             gpointer data);
GNode*      g_node_copy_deep                (GNode *node,
                                             GCopyFunc copy_func,
                                             gpointer data);

GNode*      g_node_insert                   (GNode *parent,
                                             gint position,
                                             GNode *node);
GNode*      g_node_insert_before            (GNode *parent,
                                             GNode *sibling,
                                             GNode *node);
GNode*      g_node_insert_after             (GNode *parent,
                                             GNode *sibling,
                                             GNode *node);
#define     g_node_append                   (parent, node)
GNode*      g_node_prepend                  (GNode *parent,
                                             GNode *node);

#define     g_node_insert_data              (parent, position, data)
#define     g_node_insert_data_before       (parent, sibling, data)
#define     g_node_append_data              (parent, data)
#define     g_node_prepend_data             (parent, data)

void        g_node_reverse_children         (GNode *node);
void        g_node_traverse                 (GNode *root,
                                             GTraverseType order,
                                             GTraverseFlags flags,
                                             gint max_depth,
                                             GNodeTraverseFunc func,
                                             gpointer data);
enum        GTraverseFlags;
gboolean    (*GNodeTraverseFunc)            (GNode *node,
                                             gpointer data);
void        g_node_children_foreach         (GNode *node,
                                             GTraverseFlags flags,
                                             GNodeForeachFunc func,
                                             gpointer data);
void        (*GNodeForeachFunc)             (GNode *node,
                                             gpointer data);

GNode*      g_node_get_root                 (GNode *node);
GNode*      g_node_find                     (GNode *root,
                                             GTraverseType order,
                                             GTraverseFlags flags,
                                             gpointer data);
GNode*      g_node_find_child               (GNode *node,
                                             GTraverseFlags flags,
                                             gpointer data);
gint        g_node_child_index              (GNode *node,
                                             gpointer data);
gint        g_node_child_position           (GNode *node,
                                             GNode *child);
#define     g_node_first_child              (node)
GNode*      g_node_last_child               (GNode *node);
GNode*      g_node_nth_child                (GNode *node,
                                             guint n);
GNode*      g_node_first_sibling            (GNode *node);
#define     g_node_next_sibling             (node)
#define     g_node_prev_sibling             (node)
GNode*      g_node_last_sibling             (GNode *node);

#define     G_NODE_IS_LEAF                  (node)
#define     G_NODE_IS_ROOT                  (node)
guint       g_node_depth                    (GNode *node);
guint       g_node_n_nodes                  (GNode *root,
                                             GTraverseFlags flags);
guint       g_node_n_children               (GNode *node);
gboolean    g_node_is_ancestor              (GNode *node,
                                             GNode *descendant);
guint       g_node_max_height               (GNode *root);

void        g_node_unlink                   (GNode *node);
void        g_node_destroy                  (GNode *root);

void        g_node_push_allocator           (gpointer dummy);
void        g_node_pop_allocator            (void);

Описание

Структура GNode и связанные с ней функции обеспечивают N-ary дерево структур данных, где узлы в дереве могут содержать произвольные данные.

Для создания нового дерева используйте g_node_new().

Для вставки узлов в дерево используйте g_node_insert(), g_node_insert_before(), g_node_append() и g_node_prepend().

Для создания нового узла и вставки его в дерево используйте g_node_insert_data(), g_node_insert_data_before(), g_node_append_data() и g_node_prepend_data().

Для реверса дочерних элементов узла используйте g_node_reverse_children().

Для поиска узла используйте g_node_get_root(), g_node_find(), g_node_find_child(), g_node_child_index(), g_node_child_position(), g_node_first_child(), g_node_last_child(), g_node_nth_child(), g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() или g_node_last_sibling().

Для получения информации об узле или дереве используйте G_NODE_IS_LEAF(), G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), g_node_n_children(), g_node_is_ancestor() or g_node_max_height().

Для обхода дерева, вызывая функцию для каждого посещяемого узла при обходе, используйте g_node_traverse() или g_node_children_foreach().

Для удаления узла или дочернего дерева из дерева используйте g_node_unlink() или g_node_destroy().

Детали

GNode

typedef struct {
  gpointer data;
  GNode	  *next;
  GNode	  *prev;
  GNode	  *parent;
  GNode	  *children;
} GNode;

Структура GNode представляет один узел в N-ary Tree. Поле data содержит фактические данные в узле. Поля next и prev указывают на дочерние узлы (дочерние - это другие GNode с тем же родителем). Поле parent указывает на родителя GNode, или NULL если GNode является корнем дерева. Поле children указывает на первую дочернюю GNode. Другие дочерние узлы связываются используя указатель next каждого дочернего узла.


g_node_new ()

GNode*      g_node_new                      (gpointer data);

Создаёт новую GNode содержащую полученные данные. Используется для создания первого узла в дереве.

data : данные нового узла.
Возвращает : новый GNode.

g_node_copy ()

GNode*      g_node_copy                     (GNode *node);

Рекурсивно копирует GNode (но не делает глубоких копий данных в узлах, смотрите g_node_copy_deep() если вам это нужно).

node : GNode.
Возвращает : новый GNode содержащий те же указатели данных.

GCopyFunc ()

gpointer    (*GCopyFunc)                    (gconstpointer src,
                                             gpointer data);

Функция этой сигнатуры используется для копирования узла данных выполняя глубокую копию дерева.

src : указатель на данные которые должны быть скопированны.
data : дополнительные данные.
Возвращает : указатель на копию.

Начиная с версии 2.4


g_node_copy_deep ()

GNode*      g_node_copy_deep                (GNode *node,
                                             GCopyFunc copy_func,
                                             gpointer data);

Рекурсивно копирует GNode и его данные.

node : GNode
copy_func : функция вызываемая для копирования данных внутри каждого узла, или NULL для использования оригинальных данных.
data : данные помещаемые в copy_func
Возвращает : новый GNode содержащий копии данных в node.

Начиная с версии 2.4


g_node_insert ()

GNode*      g_node_insert                   (GNode *parent,
                                             gint position,
                                             GNode *node);

Вставляет GNode ниже родителя в указанную позицию.

parent : GNode под которым размещается node.
position : позиция для размещения node, относительно родственных элементов. Если позиция -1, node вставляется как последний дочерний элемент parent.
node : GNode для вставки.
Возвращает : вставляемый GNode.

g_node_insert_before ()

GNode*      g_node_insert_before            (GNode *parent,
                                             GNode *sibling,
                                             GNode *node);

Вставляет GNode ниже родителя перед указанным соседом.

parent : GNode под которым располагается node.
sibling : соседний GNode для размещения node перед ним. Если соседний это NULL, узел вставляется как последний дочерний parent.
node : вставляемый GNode.
Возвращает : вставленный GNode.

g_node_insert_after ()

GNode*      g_node_insert_after             (GNode *parent,
                                             GNode *sibling,
                                             GNode *node);

Вставляет GNode ниже родителя после указанного соседа.

parent : GNode под которым размещается node.
sibling : соседний GNode после которого размещается node. Если сосед это NULL, узел вставляется как первый дочерний parent.
node : вставляемый GNode.
Возвращает : вставленный GNode.

g_node_append()

#define     g_node_append(parent, node)

Вставляет GNode как последний дочерний указанного родителя.

parent : GNode под которым размещается новый GNode.
node : вставляемый GNode.
Возвращает : вставляемый GNode.

g_node_prepend ()

GNode*      g_node_prepend                  (GNode *parent,
                                             GNode *node);

Вставляет GNode как первый дочерний указанного родителя.

parent : GNode под которым размещается новый GNode under.
node : вставляемый GNode.
Возвращает : вставленный GNode.

g_node_insert_data()

#define     g_node_insert_data(parent, position, data)

Вставляет новый GNode в указанную позицию.

parent : GNode под которым размещается новый GNode.
position : позиция для размещения нового GNode. Если позиция равна -1, новый GNode вставляется как последний дочерний parent.
data : данные для нового GNode.
Возвращает : новый GNode.

g_node_insert_data_before()

#define     g_node_insert_data_before(parent, sibling, data)

Вставляет новый GNode перед указанным соседом.

parent : GNode под которым размещается новый GNode.
sibling : соседний GNode перед которым размещается новый GNode.
data : данные для нового GNode.
Возвращает : новый GNode.

g_node_append_data()

#define     g_node_append_data(parent, data)

Вставляет новый GNode как последний дочерний указанного родителя.

parent : GNode под которым размещается новый GNode.
data : данные для нового GNode.
Возвращает : новый GNode.

g_node_prepend_data()

#define     g_node_prepend_data(parent, data)

Вставляет новый GNode как первый дочерний указанного родителя.

parent : GNode под которым размещается новый GNode.
data : данные для нового GNode.
Возвращает : новый GNode.

g_node_reverse_children ()

void        g_node_reverse_children         (GNode *node);

Переворачивает порядок дочерних GNode. (Она не меняет порядок внуков.)

node : GNode.

g_node_traverse ()

void        g_node_traverse                 (GNode *root,
                                             GTraverseType order,
                                             GTraverseFlags flags,
                                             gint max_depth,
                                             GNodeTraverseFunc func,
                                             gpointer data);

Обходит дерево начиная с указанного корня GNode. Она вызывает указанную функцию для каждого посещяемого узла. Обход может быть прекращён в любой точке когда TRUE вернётся из func.

root : корень GNode дерева для обхода.
order : порядок в котором посещаются узлы - G_IN_ORDER, G_PRE_ORDER, G_POST_ORDER, или G_LEVEL_ORDER.
flags : какие типы дочерних узлов будут посещены, один из вариантов - G_TRAVERSE_ALL, G_TRAVERSE_LEAVES и G_TRAVERSE_NON_LEAVES.
max_depth : максимальная глубина обхода. Узлы на этой глубине не будут посещаться. Если max_depth равна -1 посещаются все узлы в дереве. Если глубина 1, посещается только корень. Если глубина 2, посещаются корень и его дочерние узлы. И так далее.
func : функция вызываемая для каждого посещённого элемента GNode.
data : пользовательские данные помещаемые в функцию.

enum GTraverseFlags

typedef enum
{
  G_TRAVERSE_LEAVES     = 1 << 0,
  G_TRAVERSE_NON_LEAVES = 1 << 1,
  G_TRAVERSE_ALL        = G_TRAVERSE_LEAVES | G_TRAVERSE_NON_LEAVES,
  G_TRAVERSE_MASK       = 0x03,
  G_TRAVERSE_LEAFS      = G_TRAVERSE_LEAVES,
  G_TRAVERSE_NON_LEAFS  = G_TRAVERSE_NON_LEAVES
} GTraverseFlags;

Определяет какие узлы посещаются при выполнении некоторых функций дерева, включая g_node_traverse() и g_node_find().

G_TRAVERSE_LEAVES только вершины узлов должны посещаться. Это название было введено в версии 2.6, ранние версии использовали G_TRAVERSE_LEAFS.
G_TRAVERSE_NON_LEAVES только не вершины должны посещаться. Это имя введено в версии 2.6, в ранних версиях использовалось G_TRAVERSE_NON_LEAFS.
G_TRAVERSE_ALL все узлы должны посещаться.
G_TRAVERSE_MASK
G_TRAVERSE_LEAFS идентично G_TRAVERSE_LEAVES
G_TRAVERSE_NON_LEAFS идентично G_TRAVERSE_NON_LEAVES

GNodeTraverseFunc ()

gboolean    (*GNodeTraverseFunc)            (GNode *node,
                                             gpointer data);

Определяет тип функции помещаемой в g_node_traverse(). Функция вызывается с каждым посещённым узлом, который передают вместе с пользовательскими данными в g_node_traverse(). Если функция возвращает TRUE, то обход прекращается.

node : GNode.
data : пользовательские данные помещаемые в g_node_traverse().
Возвращает : TRUE для остановки обхода.

g_node_children_foreach ()

void        g_node_children_foreach         (GNode *node,
                                             GTraverseFlags flags,
                                             GNodeForeachFunc func,
                                             gpointer data);

Вызывает функцию для каждого дочернего GNode. Помните что она не опускается ниже дочерних узлов.

node : GNode.
flags : какие типы дочерних элементов посещаются, один из G_TRAVERSE_ALL, G_TRAVERSE_LEAVES и G_TRAVERSE_NON_LEAVES.
func : функция вызываемая для каждого посещённого узла.
data : пользовательские данные помещаемые в функцию.

GNodeForeachFunc ()

void        (*GNodeForeachFunc)             (GNode *node,
                                             gpointer data);

Определяет тип функции помещаемой в g_node_children_foreach(). Функция вызываемая для каждого дочернего узла, вместе с пользовательскими данными которые помещаются в g_node_children_foreach().

node : GNode.
data : пользовательские данные помещаемые в g_node_children_foreach().

g_node_get_root ()

GNode*      g_node_get_root                 (GNode *node);

Определяет корень дерева.

node : GNode.
Возвращает : корень дерева.

g_node_find ()

GNode*      g_node_find                     (GNode *root,
                                             GTraverseType order,
                                             GTraverseFlags flags,
                                             gpointer data);

Находит GNode в дереве.

root : корневой GNode дерева для поиска.
order : порядок в котором посещаются узлы - G_IN_ORDER, G_PRE_ORDER, G_POST_ORDER, или G_LEVEL_ORDER.
flags : какой тип дочернего элемента должен быть найден, один из G_TRAVERSE_ALL, G_TRAVERSE_LEAVES и G_TRAVERSE_NON_LEAVES.
data : данные для поиска.
Возвращает : найденный GNode, или NULL если данные не найдены.

g_node_find_child ()

GNode*      g_node_find_child               (GNode *node,
                                             GTraverseFlags flags,
                                             gpointer data);

Находит первый дочерний GNode с указанными данными.

node : GNode.
flags : какой тип дочерних узлов разыскивается, один из G_TRAVERSE_ALL, G_TRAVERSE_LEAVES и G_TRAVERSE_NON_LEAVES.
data : данные для поиска.
Возвращает : найденный дочерний GNode, или NULL если данные не найдены.

g_node_child_index ()

gint        g_node_child_index              (GNode *node,
                                             gpointer data);

Определяет позицию первого дочернего GNode который содержит указанные данные.

node : GNode.
data : данные для поиска.
Возвращает : номер дочернего node который содержит data, или -1 если данные не найдены.

g_node_child_position ()

gint        g_node_child_position           (GNode *node,
                                             GNode *child);

Определяет позицию GNode относительно его соседей. child должен быть дочерним по отношению к node. Первый дочерний нумеруется 0, второй 1, и так далее.

node : GNode.
child : дочерний по отношению к node.
Возвращает : позиция child относительно его соседей.

g_node_first_child()

#define     g_node_first_child(node)

Определяет первый дочерний GNode.

node : GNode.
Возвращает : первый дочерний node, или NULL если node это NULL или нет дочерних элементов.

g_node_last_child ()

GNode*      g_node_last_child               (GNode *node);

Определяет последний дочерний GNode.

node : GNode (не должен быть NULL).
Возвращает : последний дочерний node, или NULL если node не имеет дочерних элементов.

g_node_nth_child ()

GNode*      g_node_nth_child                (GNode *node,
                                             guint n);

Определяет дочерний GNode, используя указанный номер. Первый это номер 0. Если номер слишком большой, возвращает NULL.

node : GNode.
n : номер желаемого дочернего элемента.
Возвращает : дочерний node с номером n.

g_node_first_sibling ()

GNode*      g_node_first_sibling            (GNode *node);

Определяет первый соседний GNode. Это может быть сам узел.

node : GNode.
Возвращает : первый соседний node.

g_node_next_sibling()

#define     g_node_next_sibling(node)

Определяет следующего соседа GNode.

node : GNode.
Возвращает : следующий сосед node, или NULL если node это NULL.

g_node_prev_sibling()

#define     g_node_prev_sibling(node)

Определяет предыдущего соседа GNode.

node : GNode.
Возвращает : предыдущий сосед node, или NULL если node это NULL.

g_node_last_sibling ()

GNode*      g_node_last_sibling             (GNode *node);

Определяет последнего соседа GNode. Это может быть сам узел.

node : GNode.
Возвращает : последний соседний node.

G_NODE_IS_LEAF()

#define	 G_NODE_IS_LEAF(node)	(((GNode*) (node))->children == NULL)

Возвращает TRUE если GNode это вершина узла.

node : GNode.
Возвращает : TRUE если GNode вершина узла (то есть он не имеет дочерних элементов).

G_NODE_IS_ROOT()

#define     G_NODE_IS_ROOT(node)

Возвращает TRUE если GNode это корень дерева.

node : GNode.
Возвращает : TRUE если GNode является корнем дерева (то есть он не имеет родительского соседа).

g_node_depth ()

guint       g_node_depth                    (GNode *node);

Определяет глубину GNode.

Если node это NULL глубина равна 0. Корневой узел имеет глубину равную 1. Для дочерних элементов корневого узла глубина равна 2. И так далее.

node : GNode.
Возвращает : глубина GNode.

g_node_n_nodes ()

guint       g_node_n_nodes                  (GNode *root,
                                             GTraverseFlags flags);

Определяет количество узлов в дереве.

root : GNode.
flags : какие типы дочерних элементов подсчитываются, один из вариантов G_TRAVERSE_ALL, G_TRAVERSE_LEAVES и G_TRAVERSE_NON_LEAVES.
Возвращает : количество узлов в дереве.

g_node_n_children ()

guint       g_node_n_children               (GNode *node);

Определяет количество дочерних GNode.

node : GNode.
Возвращает : количество дочерних node.

g_node_is_ancestor ()

gboolean    g_node_is_ancestor              (GNode *node,
                                             GNode *descendant);

Возвращает TRUE если node предок descendant. Это правильно если узел является родителем descendant, или если узел является родителем родителя descendant и так далее.

node : GNode.
descendant : GNode.
Возвращает : TRUE если node является родителем descendant.

g_node_max_height ()

guint       g_node_max_height               (GNode *root);

Определяет максимальную высоту всех переходов от GNode. Это максимальное расстояние от GNode до всех вершин.

Если root это NULL, возвращается 0. Если root не имеет дочерних элементов, возвращается 1. Если root имеет дочерние элементы, возвращается 2. И так далее.

root : GNode.
Возвращает : максимальная высота дерева от root.

g_node_unlink ()

void        g_node_unlink                   (GNode *node);

Сбрасывает ссылки GNode из дерева, получая в качестве результата два разделённых дерева.

node : GNode для разлинковки, который становится корнем нового дерева.

g_node_destroy ()

void        g_node_destroy                  (GNode *root);

Удаляет GNode и дочерние элементы из дерева, освобождает любую распределённую память.

root : корень дерева/поддерева для уничтожения.

g_node_push_allocator ()

void        g_node_push_allocator           (gpointer dummy);

Внимание

g_node_push_allocator устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде. Она ничего не делает, так как GNode конвертируется в slice allocator

Устанавливает распределитель для распределения элементов GNode. Использует g_node_pop_allocator() для восстановления предыдущего распределителя.

Помните что эта функция не доступна если GLib была скомпилирована с опцией --disable-mem-pools

dummy : GAllocator для распределения элементов GNode.

g_node_pop_allocator ()

void        g_node_pop_allocator            (void);

Внимание

g_node_pop_allocator устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде. Она ничего не делает, так как GNode конвертируется в slice allocator

Восстанавливает предыдущий GAllocator, используется при распределении элементов GNode.

Помните что эта функция не доступна если GLib скомпилирована с опцией --disable-mem-pools


Числовое разбиение

Numerical Definitions — Математические константы и разбиение плавающей точкой.

Краткое описание


#include <glib.h>


#define     G_IEEE754_FLOAT_BIAS
#define     G_IEEE754_DOUBLE_BIAS
union       GFloatIEEE754;
union       GDoubleIEEE754;


#define     G_E
#define     G_LN2
#define     G_LN10
#define     G_PI
#define     G_PI_2
#define     G_PI_4
#define     G_SQRT2
#define     G_LOG_2_BASE_10

Описание

GLib предлагает математические константы такие как G_PI для значения pi; большинство платформ имеют их в C библиотеке, но некоторые нет, GLib версии всегда включают их.

Множества GFloatIEEE754 и GDoubleIEEE754 используются для доступности знаков, десятичных точек (mantissa) и степеней IEEE floats и doubles. Эти множества определяются как соответствующие для данной платформы. IEEE floats и doubles поддерживаются (используются для хранения) по крайней мере Intel, PPC и Sparc.

Для справки: http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html

Детали

G_IEEE754_FLOAT_BIAS

#define G_IEEE754_FLOAT_BIAS	(127)

Смотрите http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html


G_IEEE754_DOUBLE_BIAS

#define G_IEEE754_DOUBLE_BIAS	(1023)

Смотрите http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html


union GFloatIEEE754

union GFloatIEEE754
{
  gfloat v_float;
  struct {
    guint mantissa : 23;
    guint biased_exponent : 8;
    guint sign : 1;
  } mpn;
};

Множества GFloatIEEE754 и GDoubleIEEE754 используются для доступности знаков, десятичных точек (mantissa) и степеней IEEE floats и doubles. Эти множества определяются как соответствующие для данной платформы. IEEE floats и doubles поддерживаются (используются для хранения) по крайней мере Intel, PPC и Sparc.

Для справки:http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html


union GDoubleIEEE754

union GDoubleIEEE754
{
  gdouble v_double;
  struct {
    guint mantissa_low : 32;
    guint mantissa_high : 20;
    guint biased_exponent : 11;
    guint sign : 1;
  } mpn;
};

The GFloatIEEE754 and GDoubleIEEE754 используются для доступности знаков, десятичных точек (mantissa) и степеней IEEE floats и doubles. Эти множества определяются как соответствующие для данной платформы. IEEE floats и doubles поддерживаются (используются для хранения) по крайней мере Intel, PPC и Sparc.

Для справки:http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html


G_E

#define G_E     2.7182818284590452353602874713526624977572470937000

Основа естественных логарифмов.


G_LN2

#define G_LN2   0.69314718055994530941723212145817656807550013436026

Естественный логарифм 2.


G_LN10

#define G_LN10  2.3025850929940456840179914546843642076011014886288

Естевственный логарифм 10.


G_PI

#define G_PI    3.1415926535897932384626433832795028841971693993751

Значение pi (соотношение окружности круга к диаметру).


G_PI_2

#define G_PI_2  1.5707963267948966192313216916397514420985846996876

Pi разделённое на 2.


G_PI_4

#define G_PI_4  0.78539816339744830961566084581987572104929234984378

Pi разделённое на 4.


G_SQRT2

#define G_SQRT2 1.4142135623730950488016887242096980785696718753769

Квадратный корень 2.


G_LOG_2_BASE_10

#define G_LOG_2_BASE_10		(0.30102999566398119521)

Используется для дурачеств с форматом float, смотрите http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html

Смотрите также

http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html



Pointer Arrays

Pointer Arrays — Массив указателей для любого типа данных, который увеличивается автоматически при добавлении элементов.

Краткое описание


#include <glib.h>


            GPtrArray;
GPtrArray*  g_ptr_array_new                 (void);
GPtrArray*  g_ptr_array_sized_new           (guint reserved_size);
void        g_ptr_array_add                 (GPtrArray *array,
                                             gpointer data);
gboolean    g_ptr_array_remove              (GPtrArray *array,
                                             gpointer data);
gpointer    g_ptr_array_remove_index        (GPtrArray *array,
                                             guint index_);
gboolean    g_ptr_array_remove_fast         (GPtrArray *array,
                                             gpointer data);
gpointer    g_ptr_array_remove_index_fast   (GPtrArray *array,
                                             guint index_);
void        g_ptr_array_remove_range        (GPtrArray *array,
                                             guint index_,
                                             guint length);
void        g_ptr_array_sort                (GPtrArray *array,
                                             GCompareFunc compare_func);
void        g_ptr_array_sort_with_data      (GPtrArray *array,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);
void        g_ptr_array_set_size            (GPtrArray *array,
                                             gint length);
#define     g_ptr_array_index               (array,index_)
gpointer*   g_ptr_array_free                (GPtrArray *array,
                                             gboolean free_seg);
void        g_ptr_array_foreach             (GPtrArray *array,
                                             GFunc func,
                                             gpointer user_data);

Описание

Массивы указателей похожи на простые массивы, но используются только для хранения указатедей.

Примечание

Если вы удалите элементы из массива, элементы из конца массива переместятся в свободное пространство освобождённое удалёнными элементами. Это значит что вы не должны полагаться на сохраняющуюся нумерацию специфичных элементов. Вы должны быть так же внимательны удаляя элементы при перемещении через массив.

Для создания массива указателей, используйте g_ptr_array_new().

Для добавления элементов в массив указателей, используйте g_ptr_array_add().

Для удаления элементов из массива указателей, используйте g_ptr_array_remove(), g_ptr_array_remove_index(), или g_ptr_array_remove_index_fast().

Для доступа к элементам в массиве указателей, используйте g_ptr_array_index().

Для установки размера массива указателей, используйте g_ptr_array_set_size().

Для освобождения массива указателей, используйте g_ptr_array_free().

Пример 7. Using a GPtrArray

  GPtrArray *gparray;
  gchar *string1 = "one", *string2 = "two", *string3 = "three";

  gparray = g_ptr_array_new ();
  g_ptr_array_add (gparray, (gpointer) string1);
  g_ptr_array_add (gparray, (gpointer) string2);
  g_ptr_array_add (gparray, (gpointer) string3);

  if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
    g_print ("ERROR: got %p instead of %p\n",
             g_ptr_array_index (gparray, 0), string1);

  g_ptr_array_free (gparray, TRUE);

Детали

GPtrArray

typedef struct {
  gpointer *pdata;
  guint	    len;
} GPtrArray;

Содержит общедоступные поля массива указателей.

gpointer *pdata; пункты в массиве указателей, которые могут быть перемещёны при увеличении массива.
guint len; количество указателей в массиве.

g_ptr_array_new ()

GPtrArray*  g_ptr_array_new                 (void);

Создаёт новый GPtrArray.

Возвращает : новый GPtrArray.

g_ptr_array_sized_new ()

GPtrArray*  g_ptr_array_sized_new           (guint reserved_size);

Создаёт новый GPtrArray с предварительно распределенными reserved_size указателями. Это исключает частое перераспределение, если вы собираетесь добавить много указателей в массив. Однако помните, размер массива остаётся 0.

reserved_size : количество предварительно распределённых указателей.
Возвращает : новый GPtrArray.

g_ptr_array_add ()

void        g_ptr_array_add                 (GPtrArray *array,
                                             gpointer data);

Добавляет указатель в конец массива указателей. Массив будет автоматически увеличен, если это необходимо.

array : GPtrArray.
data : добавляемый указатель.

g_ptr_array_remove ()

gboolean    g_ptr_array_remove              (GPtrArray *array,
                                             gpointer data);

Удаляет первый найденный полученный указатель из массива. Следующие элементы перемещаются вниз на одно место.

Она возвращает TRUE если указатель был удалён, или FALSE если указатель не найден.

array : GPtrArray.
data : указатель для удаления.
Возвращает : TRUE если указатель удалён. FALSE если указатель не найден в массиве.

g_ptr_array_remove_index ()

gpointer    g_ptr_array_remove_index        (GPtrArray *array,
                                             guint index_);

Удаляет указатель с полученным номером из массива указателей. Следующие элементы перемещаются на одну позицию вниз.

array : GPtrArray.
index_ : номер указателя для удаления.
Возвращает : указатель который был удалён.

g_ptr_array_remove_fast ()

gboolean    g_ptr_array_remove_fast         (GPtrArray *array,
                                             gpointer data);

Удаляет первый обнаруженный указатель, полученный в качестве параметра, из массива указателей. Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок массива. Но она быстрее чем g_ptr_array_remove().

Возвращает TRUE если указатель был удалён, или FALSE если указатель не найден в массиве.

array : GPtrArray.
data : указатель для удаления.
Возвращает : TRUE если был найден в массиве.

g_ptr_array_remove_index_fast ()

gpointer    g_ptr_array_remove_index_fast   (GPtrArray *array,
                                             guint index_);

Удаляет указатель с полученным номером из массива указателей. Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок в массиве. Но она быстрее чем g_ptr_array_remove_index().

array : GPtrArray.
index_ : номер указателя для удаления.
Возвращает : указатель который был удалён.

g_ptr_array_remove_range ()

void        g_ptr_array_remove_range        (GPtrArray *array,
                                             guint index_,
                                             guint length);

Удаляет полученное количество указателей начиная с полученного номера из GPtrArray. Следующие элементы перемещаются закрывая пустоту.

array : GPtrArray.
index_ : номер первого указателя для удаления.
length : количество указателей для удаления.

Начиная с версии 2.4


g_ptr_array_sort ()

void        g_ptr_array_sort                (GPtrArray *array,
                                             GCompareFunc compare_func);

Сортирует массив, используя compare_func которая должна быть в стиле функции сравнения qsort() (возвращает отрицательное если первый arg меньше чем второй arg, ноль если они равны, положительное если первый arg больше чем второй arg).

Если оба сравниваемых элемента массива равны, их положение в порядке сортировки массива неопределено.

Примечание

Функция сравнения для g_ptr_array_sort() не принимает указатели из массива как аргументы, она принимает указатели на указатели в массиве.

array : GPtrArray.
compare_func : функция сравнения.

g_ptr_array_sort_with_data ()

void        g_ptr_array_sort_with_data      (GPtrArray *array,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

Похожа на g_ptr_array_sort(), но функция сравнения имеет дополнительный аргумент пользовательских данных.

Примечание

Функция сравнения для g_ptr_array_sort_with_data() не принимает указатели из массива как аргументы, она принимает указатели на указатели в массиве.

array : GPtrArray.
compare_func : функция сравнения.
user_data : данные помещаемые в compare_func.

g_ptr_array_set_size ()

void        g_ptr_array_set_size            (GPtrArray *array,
                                             gint length);

Устанавливает размер массива, расширяя его если необходимо. Новые элементы устанавливаются в NULL.

array : GPtrArray.
length : новый размер массива указателей.

g_ptr_array_index()

#define     g_ptr_array_index(array,index_)

Возвращает указатель с полученным номером массива указателей.

array : GPtrArray.
index_ : номер возвращаемого указателя.
Возвращает : указатель с полученным номером.

g_ptr_array_free ()

gpointer*   g_ptr_array_free                (GPtrArray *array,
                                             gboolean free_seg);

Освобождает всю память распределённую для массива указателей.

array : GPtrArray.
free_seg : если TRUE массив указателей (pdata) освобождается.
Возвращает : NULL если free_seg это TRUE, иначе возвращает массив указателей (pdata).

g_ptr_array_foreach ()

void        g_ptr_array_foreach             (GPtrArray *array,
                                             GFunc func,
                                             gpointer user_data);

Вызывает функцию для каждого элемента GPtrArray.

array : GPtrArray
func : функция вызываемая для каждого элемента массива
user_data : пользовательские данные помещаемые в функцию

Начиная с версии 2.4


Quarks

Quarks — Два способа связать строку и уникальный целочисленный идентификатор.

Краткое описание


#include <glib.h>


typedef     GQuark;
GQuark      g_quark_from_string             (const gchar *string);
GQuark      g_quark_from_static_string      (const gchar *string);
const gchar* g_quark_to_string              (GQuark quark);
GQuark      g_quark_try_string              (const gchar *string);
const gchar* g_intern_string                (const gchar *string);
const gchar* g_intern_static_string         (const gchar *string);

Описание

Кварк является связью между строками и целочисленными идентификаторами. Получая либо строку, либо GQuark идентификатор, можно найти либо то, либо другое.

Кварки используются и для Datasets и для Keyed Data Lists.

Для создания нового кварка из строки, используйте g_quark_from_string() или g_quark_from_static_string().

Для поиска строки соответствующей полученному GQuark, используйте g_quark_to_string().

Для поиска GQuark соответствующего полученной строке, используйте g_quark_try_string().

Другой способ использования для строкового пула поддерживающего функции кварка интернирования строки, использование g_intern_string() или g_intern_static_string(). Интернированная строка это канонически представленная строка. Одно важно преимущество интернированных строк в том, что они могут сравниваться на эквивалентность с помощью простого сравнения указателя, в отличие от использования strcmp().

Детали

GQuark

typedef guint32 GQuark;

GQuark это уникальный целочисленный идентификатор специфичной строки.


g_quark_from_string ()

GQuark      g_quark_from_string             (const gchar *string);

Определяет GQuark идентификатор указанной строки. Если строка не имеет текущего связанного с ней GQuark, создаётся новый GQuark, используя копию строки.

string : строка.
Возвращает : GQuark идентификатор строки.

g_quark_from_static_string ()

GQuark      g_quark_from_static_string      (const gchar *string);

Определяет GQuark идентификатор указанной (статичной) строки. Если строка не имеет связанного с ней GQuark, создаётся новый GQuark, связывая с указанной строкой.

Помните что эта функция идентична g_quark_from_string(), исключая то, что если новый GQuark создан, используется сама строка, а не её копия. Это сохраняет память, но может использоваться только если строка всегда существует. Она может использоваться со статически распределёнными строками в основной программе, но не со статически распределённой памятью в динамически загружаемых модулях, если вы планируете выгружать модуль снова (например не используйте эту функцию в движках GTK+ тем).

string : строка.
Возвращает : GQuark идентификатор строки.

g_quark_to_string ()

const gchar* g_quark_to_string              (GQuark quark);

Определяет строку связанную с полученным GQuark.

quark : GQuark.
Возвращает : строка связанная с GQuark.

g_quark_try_string ()

GQuark      g_quark_try_string              (const gchar *string);

Определяет GQuark связанный с полученной строкой, или 0 если строка не связана с GQuark.

Если вы хотите чтобы GQuark был создан, если он не существует, используйте g_quark_from_string(), или g_quark_from_static_string().

string : строка.
Возвращает : GQuark связанный со строкой, или 0, если нет GQuark связанного со строкой.

g_intern_string ()

const gchar* g_intern_string                (const gchar *string);

Возвращает каноническое представление string. Интернированные строки могут сравниваться на эквивалентность с помощью сравнения указателей, вместо использования strcmp().

string : строка
Возвращает : каноническое представление строки

Начиная с версии 2.10


g_intern_static_string ()

const gchar* g_intern_static_string         (const gchar *string);

Возвращает каноническое представление string. Интернированные строки могут сравниваться на эквивалентность с помощью сравнения указателей, вместо использования strcmp(). g_intern_static_string() не копирует строку, однако string не должна освобождаться или изменяться.

string : статичная строка
Возвращает : каноническое представление строки

Начиная с версии 2.10


Random Numbers

Random Numbers — генератор псевдо-случайных чисел.

Краткое описание


#include <glib.h>


            GRand;
GRand*      g_rand_new_with_seed            (guint32 seed);
GRand*      g_rand_new_with_seed_array      (const guint32 *seed,
                                             guint seed_length);
GRand*      g_rand_new                      (void);
GRand*      g_rand_copy                     (GRand *rand_);
void        g_rand_free                     (GRand *rand_);
void        g_rand_set_seed                 (GRand *rand_,
                                             guint32 seed);
void        g_rand_set_seed_array           (GRand *rand_,
                                             const guint32 *seed,
                                             guint seed_length);
#define     g_rand_boolean                  (rand_)
guint32     g_rand_int                      (GRand *rand_);
gint32      g_rand_int_range                (GRand *rand_,
                                             gint32 begin,
                                             gint32 end);
gdouble     g_rand_double                   (GRand *rand_);
gdouble     g_rand_double_range             (GRand *rand_,
                                             gdouble begin,
                                             gdouble end);
void        g_random_set_seed               (guint32 seed);
#define     g_random_boolean                ()
guint32     g_random_int                    (void);
gint32      g_random_int_range              (gint32 begin,
                                             gint32 end);
gdouble     g_random_double                 (void);
gdouble     g_random_double_range           (gdouble begin,
                                             gdouble end);

Описание

Следующие функции позволяют вам использовать портируемый, быстрый и хороший генератор псевдо-случайных чисел (PRNG). Он использует Mersenne Twister PRNG, который первоначально был разработан Makoto Matsumoto и Takuji Nishimura. Детальная информация может быть найдена на www.math.keio.ac.jp/~matumoto/emt.html.

Если вам просто нужен случайный номер, вы вызываете функции g_random_*, которые создают глобально используемую GRand и используется внутренне согласно функций g_rand_*. Всякий раз когда вам необходим поток репродуктивных случайных чисел, вам лучше создать непосредственно GRand и напрямую использовать функции g_rand_*, которые будут также немного быстрее. Инициализация GRand с определённым начальным числом производит одинаковую серию случайных чисел на всех платформах. Они могут также использоваться как начальные числа например игр.

Функции g_rand*_range возвращают одинаково распределённые случайные числа высокого качества, тогда как например (g_random_int()%max) часто не приводит к одинаковому распределению чисел.

GLib изменил алгоритм отбора для генератора псевдо-случайных чисел Mersenne Twister, который используется для GRand и GRandom. Это было необходимо, потому что некоторые начальные числа ведут к очень плохим псевдо-случайным потокам. Также псевдо-случайные целочисленные сгенерированные с помощью g_rand*_int_range() будут иметь немного лучший эквивалент распределения в новой версии GLib.

Оригинальный алгоритм отбора и генерации, который может быть найден в GLib 2.0.x, может быть использован вместо нового с помощью установки переменной окружения G_RANDOM_VERSION в значение '2.0'. Используйте алгоритм GLib-2.0 только если вам необходимо точно воспроизвести последовательность чисел сгенерированных с помощью Glib-2.0.

Детали

GRand

typedef struct _GRand GRand;

Структура GRand является непрозрачной структурой данных. Доступ к ней возможен только с помощью функций g_rand_*.


g_rand_new_with_seed ()

GRand*      g_rand_new_with_seed            (guint32 seed);

Создаёт новый генератор случайного числа инициализированный с помощью seed.

seed : значение для инициализации генератора случайного числа.
Возвращает : новый GRand.

g_rand_new_with_seed_array ()

GRand*      g_rand_new_with_seed_array      (const guint32 *seed,
                                             guint seed_length);

Создаёт новый генератор случайного числа инициализированный с помощью seed.

seed : массив начальных чисел для инициализации генератора случайного числа.
seed_length : длина массива начальных чисел для инициализации генератора случайного числа.
Возвращает : новый GRand.

Начиная с версии 2.4


g_rand_new ()

GRand*      g_rand_new                      (void);

Создаёт генератор случайного числа инициализированный с помощью начального числа принятого из /dev/urandom (если существует) или из текущего времени (как аварийный режим).

Возвращает : новый GRand.

g_rand_copy ()

GRand*      g_rand_copy                     (GRand *rand_);

Копирует GRand в новый с тем же самым состоянием как прежде. Таким образом вы можете сделать снимок (snapshot) генератора случайного числа для воспроизведения в будущем.

rand_ : GRand.
Возвращает : новый GRand.

Начиная с версии 2.4


g_rand_free ()

void        g_rand_free                     (GRand *rand_);

Освобождает память распределённую для GRand.

rand_ : GRand.

g_rand_set_seed ()

void        g_rand_set_seed                 (GRand *rand_,
                                             guint32 seed);

Устанавливает начальное число для генератора случайных чисел GRand в значение seed.

rand_ : GRand.
seed : значение для переинициализации генератора случайного числа.

g_rand_set_seed_array ()

void        g_rand_set_seed_array           (GRand *rand_,
                                             const guint32 *seed,
                                             guint seed_length);

Инициализирует генератор случайного числа массивом longs. Массив может иметь произвольный размер, но только первые 624 значения принимаются во внимание. Эта функция полезна если вы имеете много начальных чисел низкой энтропии, или если требуется больше чем 32 разрядная энтропия для вашего приложения.

rand_ : GRand.
seed : массив для инициализации
seed_length : длина массива

Начиная с версии 2.4


g_rand_boolean()

#define     g_rand_boolean(rand_)

Возвращает произвольное gboolean из rand_. Это соответствует броску монеты без смещения.

rand_ : GRand.
Возвращает : произвольное число gboolean.

g_rand_int ()

guint32     g_rand_int                      (GRand *rand_);

Возвращает следующее произвольное guint32 из rand_ одинаково распределённое в диапазоне [0..2^32-1].

rand_ : GRand.
Возвращает : Произвольное число.

g_rand_int_range ()

gint32      g_rand_int_range                (GRand *rand_,
                                             gint32 begin,
                                             gint32 end);

Возвращает следующее произвольное gint32 из rand_ одинаково распределённое в диапазоне [begin..end-1].

rand_ : GRand.
begin : нижняя граница интервала.
end : верхняя граница интервала.
Возвращает : Произвольное число.

g_rand_double ()

gdouble     g_rand_double                   (GRand *rand_);

Возвращает следующее произвольное gdouble из rand_ одинаково распределённое в диапазоне [0..1).

rand_ : GRand.
Возвращает : Произвольное число.

g_rand_double_range ()

gdouble     g_rand_double_range             (GRand *rand_,
                                             gdouble begin,
                                             gdouble end);

Возвращает следующее произвольное gdouble из rand_ одинаково распределённое в диапазоне [begin..end).

rand_ : GRand.
begin : нижняя граница интервала.
end : верхняя граница интервала.
Возвращает : Произвольное число.

g_random_set_seed ()

void        g_random_set_seed               (guint32 seed);

Устанавливает начальное число для глобального генератора случайных чисел, который используется функциями g_random_*, в значение seed.

seed : значение для переинициализации глобального генератора случайных чисел.

g_random_boolean()

#define     g_random_boolean()

Возвращает произвольное gboolean. Это соответствует броску монеты без смещения.

Возвращает : произвольное gboolean.

g_random_int ()

guint32     g_random_int                    (void);

Возвращает произвольное guint32 одинаково распределённое в диапазоне [0..2^32-1].

Возвращает : Произвольное число.

g_random_int_range ()

gint32      g_random_int_range              (gint32 begin,
                                             gint32 end);

Возвращает произвольное gint32 одинаково распределённое в диапазоне [begin..end-1].

begin : нижняя граница интервала.
end : верхняя граница интервала.
Возвращает : Произвольное число.

g_random_double ()

gdouble     g_random_double                 (void);

Возвращает произвольное gdouble одинаково распределённое в диапазоне [0..1).

Возвращает : Произвольное число.

g_random_double_range ()

gdouble     g_random_double_range           (gdouble begin,
                                             gdouble end);

Возвращает произвольное gdouble одинаково распределённое в диапазоне [begin..end).

begin : нижняя граница диапазона.
end : верхняя граница диапазона.
Возвращает : Произвольное число.

Relations and Tuples

Relations and Tuples — Таблицы данных которые могут быть проиндексированы любым количеством полей.

Краткое описание


#include <glib.h>


            GRelation;
GRelation*  g_relation_new                  (gint fields);
void        g_relation_index                (GRelation *relation,
                                             gint field,
                                             GHashFunc hash_func,
                                             GEqualFunc key_equal_func);
void        g_relation_insert               (GRelation *relation,
                                             ...);
gboolean    g_relation_exists               (GRelation *relation,
                                             ...);
gint        g_relation_count                (GRelation *relation,
                                             gconstpointer key,
                                             gint field);
GTuples*    g_relation_select               (GRelation *relation,
                                             gconstpointer key,
                                             gint field);
gint        g_relation_delete               (GRelation *relation,
                                             gconstpointer key,
                                             gint field);
void        g_relation_destroy              (GRelation *relation);

void        g_relation_print                (GRelation *relation);

            GTuples;
void        g_tuples_destroy                (GTuples *tuples);
gpointer    g_tuples_index                  (GTuples *tuples,
                                             gint index_,
                                             gint field);

Описание

GRelation - это таблица данных которая может быть проиндексирована любым количеством полей, точнее как простые таблицы базы данных. GRelation содержит множество записей, называемых кортежами. каждая запись содержит множество полей. Записи не сортируются, поэтому невозможно найти запись по порядковому номеру.

Помните что GRelation таблицы в настоящее время лимитированы двумя полями.

Для создания GRelation, используйте g_relation_new().

Для определения какие поля должны проиндексироваться, используйте g_relation_index(). Помните что её нужно вызывать прежде чем любой кортеж будет добавлен в GRelation.

Для добавления записей в GRelation используйте g_relation_insert().

Для определения есть ли данная запись в GRelation, используйте g_relation_exists(). Помните что поля сравниваются непосредственно, поэтому указатели должны указывать в туже самую позицию (то есть разные копии одной и той же строки не будут соответсвовать.)

Для подсчёта количества записей которые имеют специфичное значение в указанном поле, используйте g_relation_count().

Для получения всех записей которые имеют специфичное значение в указанном поле, используйте g_relation_select(). Для доступа к полям получившихся записей, используйте g_tuples_index(). Для освобождения получившихся записей используйте g_tuples_destroy().

Для удаления всех записей которые имеют специфичное значение в указанном поле, используйте g_relation_delete().

Для уничтожения GRelation, используйте g_relation_destroy().

Для помощи отслеживания объектов GRelation, используйте g_relation_print().

Детали

GRelation

typedef struct _GRelation GRelation;

Структура GRelation - это непрозрачная структура данных представляющая Relation. Доступ к ней должен осуществляться только следующими функциями.


g_relation_new ()

GRelation*  g_relation_new                  (gint fields);

Создаёт новую GRelation с указанным количеством полей. Помните что текущее количество полей должно быть 2.

fields : количество полей.
Возвращает : новая GRelation.

g_relation_index ()

void        g_relation_index                (GRelation *relation,
                                             gint field,
                                             GHashFunc hash_func,
                                             GEqualFunc key_equal_func);

Создаёт индекс указанного поля. Помните что её нужно вызвать перед добавлением любых записей в GRelation.

relation : GRelation.
field : индексируемое поле, подсчёт с 0.
hash_func : функция для производства хеш значения из поля данных.
key_equal_func : функция для сравнения двух значений указанного поля.

g_relation_insert ()

void        g_relation_insert               (GRelation *relation,
                                             ...);

Вставляет запись в GRelation.

relation : GRelation.
... : поля добавляемой записи. Должно соответствовать количеству полей в GRelation, и типу gpointer или gconstpointer.

g_relation_exists ()

gboolean    g_relation_exists               (GRelation *relation,
                                             ...);

Возвращает TRUE если запись с указанным значением существует в GRelation. Помните что значения сравниваются непосредственно, поэтому, например, две копии одной и той же строки не будут соответствовать.

relation : GRelation.
... : поля записи для сравнения. Количество должно соответствовать количеству полей в GRelation.
Возвращает : TRUE если запись соответсвует.

g_relation_count ()

gint        g_relation_count                (GRelation *relation,
                                             gconstpointer key,
                                             gint field);

Возвращает количество кортежей в GRelation которые имеют указанное значение в указанном поле.

relation : GRelation.
key : значение для сравнения.
field : поле в каждой записи для сопоставления.
Возвращает : количество соответствий.

g_relation_select ()

GTuples*    g_relation_select               (GRelation *relation,
                                             gconstpointer key,
                                             gint field);

Возвращает все кортежи которые имеют указанный ключ в указанном поле. Используйте g_tuples_index() для доступа к возвращаемым записям. Возвращаемые записи должны быть освобождены с помощью g_tuples_destroy().

relation : GRelation.
key : значение для сравнения.
field : поле в каждой записи для сопоставления.
Возвращает : записи (кортежи) которые соответствуют.

g_relation_delete ()

gint        g_relation_delete               (GRelation *relation,
                                             gconstpointer key,
                                             gint field);

Удаляет любые записи из GRelation которые имеют указанный ключ в указанном поле.

relation : GRelation.
key : значение для сравнения.
field : поле каждой записи для сопоставления.
Возвращает : количество удалённых записей.

g_relation_destroy ()

void        g_relation_destroy              (GRelation *relation);

Уничтожает GRelation, освобождает всю распределённую память. Однако, она не освобождает память распределённую для кортежей данных, поэтому вы должны освободить их соответственно первыми.

relation : GRelation.

g_relation_print ()

void        g_relation_print                (GRelation *relation);

Выводит информацию о всех записях в GRelation, также как о индексах. Это для отладки.

relation : GRelation.

GTuples

typedef struct {
  guint len;
} GTuples;

Структура GTuples используется для возвращаемых записей (или кортежей) из GRelation с помощью g_relation_select(). Она содержит только одно общедоступное поле - количество записей которые соответствуют. Для доступа к соответствующим записям вы должны использовать g_tuples_index().

guint len; количество записей которое соответствует.

g_tuples_destroy ()

void        g_tuples_destroy                (GTuples *tuples);

Освобождает записи которые были возвращены g_relation_select(). Она должна всегда вызываться после g_relation_select() когда вы закончите с записями. Записи не удаляются из GRelation.

tuples : кортежи данных для освобождения.

g_tuples_index ()

gpointer    g_tuples_index                  (GTuples *tuples,
                                             gint index_,
                                             gint field);

Получает поля из записей возвращённых g_relation_select(). Она возвращает указанное поле записи по указанному индексу. Возвращаемое значение не должно изменяться.

tuples : кортеж данных, возвращаемый g_relation_select().
index_ : индекс записи.
field : возвращаемое поле.
Возвращает : поле записи.

Shell-related Utilities

Shell-related Utilities — shell-подобная обработка командной строки.

Краткое описание


#include <glib.h>


enum        GShellError;
#define     G_SHELL_ERROR
gboolean    g_shell_parse_argv              (const gchar *command_line,
                                             gint *argcp,
                                             gchar ***argvp,
                                             GError **error);
gchar*      g_shell_quote                   (const gchar *unquoted_string);
gchar*      g_shell_unquote                 (const gchar *quoted_string,
                                             GError **error);

Описание

Детали

enum GShellError

typedef enum
{
  /* несоответствие или иначе искажённое квотирование */
  G_SHELL_ERROR_BAD_QUOTING,
  /* анализируемая строка пустая */
  G_SHELL_ERROR_EMPTY_STRING,
  G_SHELL_ERROR_FAILED
} GShellError;

Коды ошибок возвращаемые функциями оболочки (shell functions).

G_SHELL_ERROR_BAD_QUOTING Несоответствие или искажённое квотирование.
G_SHELL_ERROR_EMPTY_STRING Анализируемая строка пустая.
G_SHELL_ERROR_FAILED Некоторые другие ошибки.

G_SHELL_ERROR

#define G_SHELL_ERROR g_shell_error_quark ()

Домен ошибки для функций оболочки. Ошибки в этом домене из перечисления GShellError. Смотрите GError для информации о доменах ошибки.


g_shell_parse_argv ()

gboolean    g_shell_parse_argv              (const gchar *command_line,
                                             gint *argcp,
                                             gchar ***argvp,
                                             GError **error);

Анализирует командную строку в одномерном массиве параметров, аналогичным с shell способом, но без многих расширений выполняемых shell (переменные, globs, операторы, расширение файлового имени, и т.д. не поддерживаются). Результат определяется в том же самом стиля как вы могли бы получить из UNIX98 /bin/sh, пока ввод не содержит не поддерживаемых shell расширений. Если ввод содержит такие расширения, они помещаются буквально. Возможные ошибки происходят из G_SHELL_ERROR домена. Освобождается одномерный массив с помощью g_strfreev().

command_line : анализируемая командная строка
argcp : расположение возвращаемого количества аргументов
argvp : расположение возвращаемого массива аргументов
error : расположение возвращаемой ошибки
Возвращает : TRUE при успешном выполнении, FALSE если установлена ошибка

g_shell_quote ()

gchar*      g_shell_quote                   (const gchar *unquoted_string);

Квотирует строку так чтобы оболочка (/bin/sh) интерпретировала её как unquoted_string. Если вы поместите имя файла в оболочку, например, вы должны сначала квотировать его с помощью этой функции. Возвращаемое значение должно освобождаться с помощью g_free(). Используемый стиль квотирования не определён (могут использоваться или одинарные или двойные кавычки).

unquoted_string : строка литерал
Возвращает : квотированная строка

g_shell_unquote ()

gchar*      g_shell_unquote                 (const gchar *quoted_string,
                                             GError **error);

Снимает квотирование строки как если бы это сделала оболочка (/bin/sh). Обрабатывает кавычки только; если строка содержит file globs, арифметические операторы, переменные, обратные кавычки, переназначения, или другие специальные shell особенности, результат будет отличаться от реального результата который дала бы shell (переменные, обратные кавычки, и т.д. будут помещены как литералы вместо интерпретации). Эта функция гарантировано завершается успешно если применяется результат g_shell_quote(). Если она завершилась неудачей, то возвращает NULL и устанавливает ошибку. quoted_string не должен фактически содержать кавычки или escaped текст; g_shell_unquote() просто проходит через строку и снимает квотирование (unquotes/unescapes) как если бы это сделала shell-оболочка. Обрабатываются и двойные и одинарные кавычки, а так же escapes включая завершающий символ новой строки. Возвращаемое значение должно освобождаться с помощью g_free(). Возможные ошибки находятся в домене G_SHELL_ERROR.

Shell правила квотирования немного странные. Единственные кавычки сохраняют литеральную строку в точности. escape-последовательность не допускается; даже \' - если вы хотите иметь ' в квотированном тексте, вы можете сделать примерно так 'foo'\''bar'. Двойные кавычки позволяют $, `, ", \, и символ новой строки выделять обратным слэшем. Иначе двойные кавычки сохраняют всё буквально.

quoted_string : shell-quoted строка
error : расположение для возвращаемой ошибки или NULL
Возвращает : unquoted строка

Simple XML Subset Parser

Simple XML Subset Parser — Синтаксический анализатор подмножества XML.

Краткое описание


#include <glib.h>


enum        GMarkupError;
#define     G_MARKUP_ERROR
enum        GMarkupParseFlags;
            GMarkupParseContext;
            GMarkupParser;
gchar*      g_markup_escape_text            (const gchar *text,
                                             gssize length);
gchar*      g_markup_printf_escaped         (const char *format,
                                             ...);
gchar*      g_markup_vprintf_escaped        (const char *format,
                                             va_list args);
gboolean    g_markup_parse_context_end_parse
                                            (GMarkupParseContext *context,
                                             GError **error);
void        g_markup_parse_context_free     (GMarkupParseContext *context);
void        g_markup_parse_context_get_position
                                            (GMarkupParseContext *context,
                                             gint *line_number,
                                             gint *char_number);
const gchar* g_markup_parse_context_get_element
                                            (GMarkupParseContext *context);
GMarkupParseContext* g_markup_parse_context_new
                                            (const GMarkupParser *parser,
                                             GMarkupParseFlags flags,
                                             gpointer user_data,
                                             GDestroyNotify user_data_dnotify);
gboolean    g_markup_parse_context_parse    (GMarkupParseContext *context,
                                             const gchar *text,
                                             gssize text_len,
                                             GError **error);

Описание

Анализатор "GMarkup" предназначен для анализа простого формата разметки подмножества XML. Это небольшой, эффективный, лёгкий в использовании анализатор. Он не должен использоваться если вы хотите интегрироваться с другими приложениями генерирующими полномасштабный XML. Однако, он очень полезен для файлов данных программы, конфигурационных файлов и т.д. где вы знаете что ваше приложение будет единственным пишущим в файл. Полномасштабные анализаторы XML должны быть в состоянии анализировать подмножество используемое GMarkup, поэтому вы сможете легко перейти к полномасштабному анализатору позже, если возникнет необходимость.

GMarkup не гарантирует сигнал об ошибке на любом недопустимом XML; анализатор может принять документ XML который не будет проанализирован. Однако, XML документы которые не в формате[4] рассматриваются как недопустимые документы GMarkup.

Упращение XML включает:

  • Допускается только кодировка UTF-8.

  • Нет объектов определяемых пользователем.

  • Инструкции выполнения, комментарии и doctype объявления "проходят" но никогда не интерпретируются.

  • Нет DTD или проверки правильности.

Форматированная разметка поддерживает:

  • Элементы

  • Атрибуты

  • 5 стандартных объектов: &amp; &lt; &gt; &quot; &apos;

  • Символьные ссылки

  • Разделы помеченные как CDATA

Детали

enum GMarkupError

typedef enum
{
  G_MARKUP_ERROR_BAD_UTF8,
  G_MARKUP_ERROR_EMPTY,
  G_MARKUP_ERROR_PARSE,
  /* These three are primarily intended for specific GMarkupParser
   * implementations to set.
   */
  G_MARKUP_ERROR_UNKNOWN_ELEMENT,
  G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
  G_MARKUP_ERROR_INVALID_CONTENT
} GMarkupError;

Коды ошибок возвращаемые анализатором разметки.

G_MARKUP_ERROR_BAD_UTF8 анализируемый текст не был в допустимой UTF-8
G_MARKUP_ERROR_EMPTY документ пустой, или содержит только пробелы
G_MARKUP_ERROR_PARSE документ был плохо сформирован
G_MARKUP_ERROR_UNKNOWN_ELEMENT ошибка устанавливается функциями GMarkupParser; неизвестный элемент
G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE ошибка устанавливаться функциями GMarkupParser; неизвестный атрибут
G_MARKUP_ERROR_INVALID_CONTENT ошибка устанавливается функциями GMarkupParser; кое-что неправильно в содержимом документе, например недопустимое значение атрибута

G_MARKUP_ERROR

#define G_MARKUP_ERROR g_markup_error_quark ()

Домен ошибки для анализатора разметки. Ошибки в этом домене будут из перечисления GMarkupError. Смотрите GError для информации о доменах ошибки.


enum GMarkupParseFlags

typedef enum
{
  G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0,
  G_MARKUP_TREAT_CDATA_AS_TEXT              = 1 << 1  
} GMarkupParseFlags;

Флаги которые влияют на поведение анализатора.

G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG вы не должны использовать флаг.
G_MARKUP_TREAT_CDATA_AS_TEXT Когда этот флаг установлен, разделы помеченные как CDATA не помещаются буквально в функцию passthrough анализатора. Вместо этого, содержимое раздела (без <![CDATA[ и ]]>) помещается в функцию text. Этот флаг добавлен в версии GLib 2.12.

GMarkupParseContext

typedef struct _GMarkupParseContext GMarkupParseContext;

Контекст анализатора используемый для анализа потока байт которые вы ожидаете в содержимом размеченного текста. Смотрите g_markup_parse_context_new(), GMarkupParser и так далее, для получения подробностей.


GMarkupParser

typedef struct {
  /* Вызов для открывающего тега <foo bar="baz"> */
  void (*start_element)  (GMarkupParseContext *context,
                          const gchar         *element_name,
                          const gchar        **attribute_names,
                          const gchar        **attribute_values,
                          gpointer             user_data,
                          GError             **error);

  /* Вызов для закрывающего тега </foo> */
  void (*end_element)    (GMarkupParseContext *context,
                          const gchar         *element_name,
                          gpointer             user_data,
                          GError             **error);

  /* Вызов для символьных данных */
  /* текст не nul-завершённый */
  void (*text)           (GMarkupParseContext *context,
                          const gchar         *text,
                          gsize                text_len,  
                          gpointer             user_data,
                          GError             **error);

  /* Вызов для строк которые должны быть повторно сохранены дословно 
   * в том же самом месте, но не являются иначе истолкованными.  
   * В настоящий момент это включает комментарии и исполняемые инструкции.
   */
  /* текст не nul-завершённый. */
  void (*passthrough)    (GMarkupParseContext *context,
                          const gchar         *passthrough_text,
                          gsize                text_len,  
                          gpointer             user_data,
                          GError             **error);

  /* Вызов ошибки, включая один из методов установленный в vtable. 
   * GError не должна освобождаться.
   */
  void (*error)          (GMarkupParseContext *context,
                          GError              *error,
                          gpointer             user_data);
} GMarkupParser;

Любые поля в GMarkupParser могут быть NULL, в этом случае они будут игнорироваться. За исключением error функции, любые callback-функции могут установить; особенно ошибки G_MARKUP_ERROR_UNKNOWN_ELEMENT, G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, и G_MARKUP_ERROR_INVALID_CONTENT предназначены для установки из этих callback-функций. Если вы установили ошибку из callback-функции, g_markup_parse_context_parse() сообщит что ошибка вернулась в вызывающую программу.

start_element () Callback-функция вызываемая при обнаружении элемента открывающего тега.
end_element () Callback-функция вызываемая при обнаружении элемента закрывающего тега. Помните что она также вызывается для пустых тегов, например <empty/>.
text () Callback-функция вызываемая при обнаружении некоторого текста (текст всегда находится внутри элементов). Помните что текст элемента может распространяться на множество вызовов этой функции. Если установлен флаг G_MARKUP_TREAT_CDATA_AS_TEXT, эта функция также вызывается для содержимого раздела помеченного как CDATA.
passthrough () Callback-функция вызываемая для комментариев, исполняемых инструкций и doctype деклараций; если вы перезаписываете анализируемый документ, текст записывается в туже самую позицию. Если установлен флаг G_MARKUP_TREAT_CDATA_AS_TEXT, эта функция также вызывается для раздела помеченного как CDATA.
error () Callback-функция вызываемая когда происходит ошибка.

g_markup_escape_text ()

gchar*      g_markup_escape_text            (const gchar *text,
                                             gssize length);

Ограничивает текст так чтобы анализатор разметки анализировал его дословно. Меньше чем, больше чем, амперсанд и т.д. заменяются соответствующими объектами. Эта функция обычно используется когда записываемый вывод файла должен быть проанализирован анализатором разметки.

Помните что эта функция не защищает пробелы и конец строк от обработки согласно правилам XML для нормализации концов строк и значений атрибутов.

text : некоторый текст в UTF-8
length : длина text в байтах, или -1 если текст nul-завершённый
Возвращает : вновь распределённая строка с ограниченным текстом (escaped text)

g_markup_printf_escaped ()

gchar*      g_markup_printf_escaped         (const char *format,
                                             ...);

Форматирует аргументы согласно format, ограничивает всю строку и символьные аргументы в стиле g_markup_escape_text(). Это полезно когда вам нужно вставить буквенную строку в вывод в стиле XML, не беспокоясь о том, что строки могут иметь собственную разметку.

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

format : строка формата в стиле printf()
... : аргументы для вставки в строку формата
Возвращает : Вновь распределённый результат операции форматирвания. Освобождается с помощью g_free().

Начиная с версии 2.4


g_markup_vprintf_escaped ()

gchar*      g_markup_vprintf_escaped        (const char *format,
                                             va_list args);

Форматирует данные в args согласно format, ограничивает все строки и символьные аргументы в стиле g_markup_escape_text(). Смотрите g_markup_printf_escaped().

format : строка формата в стиле printf()
args : список аргументов переменных, подобных vprintf()
Возвращает : Вновь распределённый результат операции фоматирования. Освобождается с помощью g_free().

Начиная с версии 2.4


g_markup_parse_context_end_parse ()

gboolean    g_markup_parse_context_end_parse
                                            (GMarkupParseContext *context,
                                             GError **error);

Сигнализирует GMarkupParseContext что все данные были предоставлены в анализируемый контекст с помощью g_markup_parse_context_parse(). Эта функция сообщает об ошибке если документ неполон, например если есть открытые элементы.

context : GMarkupParseContext
error : расположение возвращаемой GError
Возвращает : TRUE при успешном выполнении, FALSE если была установлена ошибка

g_markup_parse_context_free ()

void        g_markup_parse_context_free     (GMarkupParseContext *context);

Освобождает GMarkupParseContext. Может быть вызвана из функций GMarkupParser.

context : GMarkupParseContext

g_markup_parse_context_get_position ()

void        g_markup_parse_context_get_position
                                            (GMarkupParseContext *context,
                                             gint *line_number,
                                             gint *char_number);

Находит текущий номер строки и количество символов в этой строке. Предназначена для использования с сообщениями об ошибках; нет определённой семантики составляющей "текущий" номер строки, кроме "лучший номер который мы смогли придумать для сообщения об ошибке".

context : GMarkupParseContext
line_number : расположение для возвращаемого номера строки, или NULL
char_number : расположение для возвращаемого количества символов в строке, или NULL

g_markup_parse_context_get_element ()

const gchar* g_markup_parse_context_get_element
                                            (GMarkupParseContext *context);

Находит имя текущего открытого элемента.

context : GMarkupParseContext
Возвращает : имя текущего открытого элемента, или NULL

Начиная с версии 2.2


g_markup_parse_context_new ()

GMarkupParseContext* g_markup_parse_context_new
                                            (const GMarkupParser *parser,
                                             GMarkupParseFlags flags,
                                             gpointer user_data,
                                             GDestroyNotify user_data_dnotify);

Создаёт новый анализатор контекста. Анализатор контекста используется для анализа размеченных документов. Вы можете направить любое количество документов в контекст, пока не произойдёт ошибка; как только происходит ошибка, анализатор контекста не сможет продолжать анализ текста (вы должны освободить его и создать новый анализатор контекста).

parser : GMarkupParser
flags : один или больше GMarkupParseFlags
user_data : пользовательские данные помещаемые в функции GMarkupParser
user_data_dnotify : пользовательские данные разрушающего уведомления вызываемого когда анализатор контекста освобождён
Возвращает : новый GMarkupParseContext

g_markup_parse_context_parse ()

gboolean    g_markup_parse_context_parse    (GMarkupParseContext *context,
                                             const gchar *text,
                                             gssize text_len,
                                             GError **error);

Заполняет некоторые данные в GMarkupParseContext. Данные не должны быть в допустимой UTF-8; будет сообщено об ошибке если они будут недопустимы. Данные не должны быть полным документом; вы можете подавать документ в анализатор инкрементно, через множество вызовов этой функции. Обычно, поскольку вы получаете данные через сетевое подключение или файл, вы направляете каждую полученную часть данных в эту функцию, прерывая процесс если происходит ошибка. Как только происходит ошибка, никакие данные больше не могут быть направлены в GMarkupParseContext; все ошибки фатальны.

context : GMarkupParseContext
text : часть анализируемого текста
text_len : длина text в байтах
error : расположение для возвращаемой GError
Возвращает : FALSE если произошла ошибка, TRUE при успешном выполнении


[4] XML спецификация

Singly-Linked Lists

Singly-Linked Lists — Связанные списки содержащие целочисленные значения или указатели на данные, с ограничением итерации только в одном направлении.

Краткое описание


#include <glib.h>


            GSList;

GSList*     g_slist_alloc                   (void);
GSList*     g_slist_append                  (GSList *list,
                                             gpointer data);
GSList*     g_slist_prepend                 (GSList *list,
                                             gpointer data);
GSList*     g_slist_insert                  (GSList *list,
                                             gpointer data,
                                             gint position);
GSList*     g_slist_insert_before           (GSList *slist,
                                             GSList *sibling,
                                             gpointer data);
GSList*     g_slist_insert_sorted           (GSList *list,
                                             gpointer data,
                                             GCompareFunc func);
GSList*     g_slist_remove                  (GSList *list,
                                             gconstpointer data);
GSList*     g_slist_remove_link             (GSList *list,
                                             GSList *link_);
GSList*     g_slist_delete_link             (GSList *list,
                                             GSList *link_);
GSList*     g_slist_remove_all              (GSList *list,
                                             gconstpointer data);
void        g_slist_free                    (GSList *list);
void        g_slist_free_1                  (GSList *list);
#define     g_slist_free1

guint       g_slist_length                  (GSList *list);
GSList*     g_slist_copy                    (GSList *list);
GSList*     g_slist_reverse                 (GSList *list);
GSList*     g_slist_insert_sorted_with_data (GSList *list,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);
GSList*     g_slist_sort                    (GSList *list,
                                             GCompareFunc compare_func);
GSList*     g_slist_sort_with_data          (GSList *list,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);
GSList*     g_slist_concat                  (GSList *list1,
                                             GSList *list2);
void        g_slist_foreach                 (GSList *list,
                                             GFunc func,
                                             gpointer user_data);

GSList*     g_slist_last                    (GSList *list);
#define     g_slist_next                    (slist)
GSList*     g_slist_nth                     (GSList *list,
                                             guint n);
gpointer    g_slist_nth_data                (GSList *list,
                                             guint n);

GSList*     g_slist_find                    (GSList *list,
                                             gconstpointer data);
GSList*     g_slist_find_custom             (GSList *list,
                                             gconstpointer data,
                                             GCompareFunc func);
gint        g_slist_position                (GSList *list,
                                             GSList *llink);
gint        g_slist_index                   (GSList *list,
                                             gconstpointer data);

void        g_slist_push_allocator          (gpointer dummy);
void        g_slist_pop_allocator           (void);

Описание

Структура GSList и связанные с ней функции обеспечивают стандартный односвязный список структур данных.

Каждый элемент в списке содержит часть данных, вместе с указателем который привязывает следующий элемент в списке. Используя этот указатель можно перемещаться по списку только в одном направлении (в отличие от двусвязных списков которые позволяют перемещение в двух направлениях).

Данные содержащиеся в каждом элементе могут быть либо целочисленными значениями, используя один из Type Conversion Macros, либо просто указателями на любой тип данных.

Список элементов распределяется slice allocator, что более эффективно чем индивидуальное распределение элементов.

Помните что функции GSList предполагают помещение указателя на первый элемент в списке. Функции которые вставляют элементы, возвращают новое начало списка, которое может иметь изменения.

Нет функции для создания GSList. NULL рассматривается как пустой список, поэтому вы можете установить GSList* в NULL.

Для добавления элементов, используйте g_slist_append(), g_slist_prepend(), g_slist_insert() и g_slist_insert_sorted().

Для удаления элементов, используйте g_slist_remove().

Для поиска элементов в списке используйте g_slist_last(), g_slist_next(), g_slist_nth(), g_slist_nth_data(), g_slist_find() и g_slist_find_custom().

Для поиска номера элемента используйте g_slist_position() и g_slist_index().

Для вызова функции для каждого элемента в списке используйте g_slist_foreach().

Для освобождения элементов списка, используйте g_slist_free().

Детали

GSList

typedef struct {
  gpointer data;
  GSList *next;
} GSList;

Структура GSList используется для каждого элемента в односвязном списке.

gpointer data; содержит элементы данных, которые могут указывать на любой тип данных, или любое целочисленное значение используя Type Conversion Macros.
GSList *next; содержит ссылку на следующий элемент в списке.

g_slist_alloc ()

GSList*     g_slist_alloc                   (void);

Распределяет свободное пространство для одного элемента GSList. Она вызывается с помощью g_slist_append(), g_slist_prepend(), g_slist_insert() и g_slist_insert_sorted() функций и очень редко используется самостоятельно.

Возвращает : указатель на вновь распределённый элемент GSList.

g_slist_append ()

GSList*     g_slist_append                  (GSList *list,
                                             gpointer data);

Добавляет новый элемент в конец списка.

Примечание

Возвращает значение начала списка, которое может измениться, поэтому убедитесь что вы сохранили новое значение.

Примечание

Помните что g_slist_append() перебирает все элементы в списке для поиска конца, это не эффективно когда добавляется много элементов. Основная идиома избежать неэффективности в прикреплении элементов сначала перевернутого списка и последующее переворачивание обратно когда все элементы добавлены.

  /* Помните что это инициализирует пустой список. */
  GSList *list = NULL, *number_list = NULL;

  /* Это список строк. */
  list = g_slist_append (list, "first");
  list = g_slist_append (list, "second");

  /* Это список целочисленных. */
  number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
  number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
list : GSList.
data : данные для нового элемента.
Возвращает : новое начало GSList.

g_slist_prepend ()

GSList*     g_slist_prepend                 (GSList *list,
                                             gpointer data);

Добавляет новый элемент в начало списка.

Примечание

Возвращает значение нового начала списка, которое может меняться, поэтому убедитесь что вы сохранили новое значение.

  /* Помните что это инициализирует пустой список. */
  GSList *list = NULL;
  list = g_slist_prepend (list, "last");
  list = g_slist_prepend (list, "first");
list : GSList.
data : данные для нового элемента
Возвращает : новое начало GSList.

g_slist_insert ()

GSList*     g_slist_insert                  (GSList *list,
                                             gpointer data,
                                             gint position);

Вставляет новый элемент в данную позицию списка.

list : GSList.
data : данные для нового элемента.
position : позиция для вставляемого элемента. Если отрицательное, или больше чем число элементов в списке, новый элемент добавляется в конец списка.
Возвращает : новое начало GSList.

g_slist_insert_before ()

GSList*     g_slist_insert_before           (GSList *slist,
                                             GSList *sibling,
                                             gpointer data);

Вставляет узел перед sibling содержащим data. Возвращает новый первый элемент списка.

slist : GSList.
sibling : узел для вставки перед data.
data : данные помещаемые во вновь вставленный узел.
Возвращает : новый первый элемент списка.

g_slist_insert_sorted ()

GSList*     g_slist_insert_sorted           (GSList *list,
                                             gpointer data,
                                             GCompareFunc func);

Вставляет новый элемент в список, используя полученную функцию сравнения для определения его позиции.

list : GSList.
data : данные для нового элемента.
func : функция для сравнения элементов всписке. Она должна возвращать число > 0 если первый параметр располагается после второго параметра при сортировке.
Возвращает : новое начало GSList.

g_slist_remove ()

GSList*     g_slist_remove                  (GSList *list,
                                             gconstpointer data);

Удаляет элемент из GSList. Если два элемента содержат одинаковые данные, удаляет только первый. Если нет элементов содержащих данные, GSList не изменяется.

list : GSList.
data : данные удаляемого элемента.
Возвращает : новое начало GSList.

g_slist_remove_link ()

GSList*     g_slist_remove_link             (GSList *list,
                                             GSList *link_);

Удаляет элемент из GSList, не освобождая элемент. Ссылка на следующий элемент у удаляемого устанавливается в NULL, так как он сам становится списком с единственным элементом.

list : GSList.
link_ : элемент в GSList.
Возвращает : новое начало GSList, без элемента.

g_slist_delete_link ()

GSList*     g_slist_delete_link             (GSList *list,
                                             GSList *link_);

Удаляет узел list. Возвращает новый первый элемент списка.

list : GSList.
link_ : узел для удаления.
Возвращает : новый первый элемент list.

g_slist_remove_all ()

GSList*     g_slist_remove_all              (GSList *list,
                                             gconstpointer data);

Удаляет все узлы списка с данными data. Возвращает новый первый элемент списка. В отличие от g_slist_remove() которая удаляет только первый узел соответствующий полученным данным.

list : GSList.
data : данные для удаления.
Возвращает : новый первый элемент list.

g_slist_free ()

void        g_slist_free                    (GSList *list);

Освобождает всю память используемую GSList. Освобождает элементы возвращаемые распределителем слайсов.

list : GSList.

g_slist_free_1 ()

void        g_slist_free_1                  (GSList *list);

Освобождает один элемент GSList. Её полезно использовать после g_slist_remove_link().

list : элемент GSList.

g_slist_free1

#define     g_slist_free1

Макрос который делает тоже самое что и g_slist_free_1().

Начиная с версии 2.10


g_slist_length ()

guint       g_slist_length                  (GSList *list);

Определяет количество элементов в GSList.

list : GSList.
Возвращает : количество элементов в GSList.

g_slist_copy ()

GSList*     g_slist_copy                    (GSList *list);

Копирует GSList.

Помните что это "пустая" копия. Если список элементов содержит указатели на данные, то указатели копируются, а фактические данные нет.

list : GSList.
Возвращает : копия list.

g_slist_reverse ()

GSList*     g_slist_reverse                 (GSList *list);

Переворачивает GSList.

list : GSList.
Возвращает : начало перевернутой GSList.

g_slist_insert_sorted_with_data ()

GSList*     g_slist_insert_sorted_with_data (GSList *list,
                                             gpointer data,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Вставляет новый элемент в список, использует полученную функцию сравнения для определения позиции.

list : GSList.
data : данные для нового элемента.
func : функция сравнивающая элементы в списке. Она должна возвращать число > 0 если первый параметр располагается после второго параметра при сортировке.
user_data : данные помещаемые в функцию сравнения.
Возвращает : новое начало GSList. Начиная с версии 2.10

g_slist_sort ()

GSList*     g_slist_sort                    (GSList *list,
                                             GCompareFunc compare_func);

Сортирует GSList используя полученную функцию сравнения.

list : GSList.
compare_func : функция сравнения используемая для сортировки GSList. Эта функция принимает данные из 2 элементов GSList и должна вернуть 0 если они равны, отрицательное значение если первый элемент располагается перед вторым, или положительное значение если первый элемент располагается после второго.
Возвращает : начало отсортированной GSList.

g_slist_sort_with_data ()

GSList*     g_slist_sort_with_data          (GSList *list,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

Подобна g_slist_sort(), но сравнивающая функция принимает аргумент пользовательских данных.

list : GSList
compare_func : сравнивающая функция.
user_data : данные помещаемые в функцию сравнения.
Возвращает : новый первый элемент списка.

g_slist_concat ()

GSList*     g_slist_concat                  (GSList *list1,
                                             GSList *list2);

Добавляет второй GSList в конец первого GSList. Помните что элементы второго GSList не копируются. Они используются непосредственно.

list1 : GSList.
list2 : GSList для добавления в конец первого GSList.
Возвращает : начало нового GSList.

g_slist_foreach ()

void        g_slist_foreach                 (GSList *list,
                                             GFunc func,
                                             gpointer user_data);

Вызывает функцию для каждого элемента GSList.

list : GSList.
func : функция вызываемая для каждого элемента данных.
user_data : пользовательские данные для помещения в функцию.

g_slist_last ()

GSList*     g_slist_last                    (GSList *list);

Получает последний элемент в GSList.

list : GSList.
Возвращает : последний элемент в GSList, или NULL если GSList не имеет элементов.

g_slist_next()

#define     g_slist_next(slist)

Удобный макрос для получения следующего элемента в GSList.

slist : элемент в GSList.
Возвращает : следующий элемент, или NULL если нет больше элементов.

g_slist_nth ()

GSList*     g_slist_nth                     (GSList *list,
                                             guint n);

Определяет элемент в указанной позиции GSList.

list : GSList.
n : позиция элемента, подсчёт с 0.
Возвращает : элемент, или NULL если позиция выходит за пределы GSList.

g_slist_nth_data ()

gpointer    g_slist_nth_data                (GSList *list,
                                             guint n);

Определяет данные элемента в указанной позиции.

list : GSList.
n : позиция элемента.
Возвращает : данные элемента, или NULL если выходит за пределы GSList.

g_slist_find ()

GSList*     g_slist_find                    (GSList *list,
                                             gconstpointer data);

Находит элемент в GSList который содержит указанные данные.

list : GSList.
data : данные элемента для поиска.
Возвращает : найденный элемент GSList, или NULL если он не найден.

g_slist_find_custom ()

GSList*     g_slist_find_custom             (GSList *list,
                                             gconstpointer data,
                                             GCompareFunc func);

Ищет элемент в GSList, используя полученную функцию для поиска желаемого элемента. Она перемещается по списку, вызов полученной функции должен вернуть 0 когда желаемый элемент найден. Функция принимает два gconstpointer аргумента, данные элемента GSList как первый аргумент и полученные пользовательские данные.

list : GSList.
data : пользовательские данные помещаемые в функцию.
func : функция вызываемая для каждого элемента. Она должна возвращать 0 когда желаемый элемент найден.
Возвращает : найденный элемент GSList, или NULL если он не найден.

g_slist_position ()

gint        g_slist_position                (GSList *list,
                                             GSList *llink);

Определяет позицию полученного элемента в GSList (начиная с 0).

list : GSList.
llink : элемент в GSList.
Возвращает : позиция элемента в GSList, или -1 если элемент не найден.

g_slist_index ()

gint        g_slist_index                   (GSList *list,
                                             gconstpointer data);

Получает позицию элемента содержащего полученные данные (начиная с 0).

list : GSList.
data : данные для поиска.
Возвращает : номер элемента содержащего данные, или -1 если данные не найдены.

g_slist_push_allocator ()

void        g_slist_push_allocator          (gpointer dummy);

Внимание

g_slist_push_allocator устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде. Она ничего не делает, так как GSList конвертирован в slice allocator

Устанавливает распределитель используемый для распределения элементов GSList. Использует g_slist_pop_allocator() для восстановления предыдущих распределений.

Помните что эта функция не доступна если GLib скомпилирована с опцией --disable-mem-pools

dummy : GAllocator используемый для распределения элементов GSList.

g_slist_pop_allocator ()

void        g_slist_pop_allocator           (void);

Внимание

g_slist_pop_allocator устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде. Она ничего не делает, так как GSList конвертирован в slice allocator

Восстанавливает предыдущий GAllocator, используемый для распределения элементов GSList.

Помните что эта функция не доступна если GLib скомпилирована с опцией --disable-mem-pools


Spawning Processes

Spawning Processes — Порождение процессов с помощью fork()/exec().

Краткое описание


#include <glib.h>


enum        GSpawnError;
#define     G_SPAWN_ERROR
enum        GSpawnFlags;
void        (*GSpawnChildSetupFunc)         (gpointer user_data);
gboolean    g_spawn_async_with_pipes        (const gchar *working_directory,
                                             gchar **argv,
                                             gchar **envp,
                                             GSpawnFlags flags,
                                             GSpawnChildSetupFunc child_setup,
                                             gpointer user_data,
                                             GPid *child_pid,
                                             gint *standard_input,
                                             gint *standard_output,
                                             gint *standard_error,
                                             GError **error);
gboolean    g_spawn_async                   (const gchar *working_directory,
                                             gchar **argv,
                                             gchar **envp,
                                             GSpawnFlags flags,
                                             GSpawnChildSetupFunc child_setup,
                                             gpointer user_data,
                                             GPid *child_pid,
                                             GError **error);
gboolean    g_spawn_sync                    (const gchar *working_directory,
                                             gchar **argv,
                                             gchar **envp,
                                             GSpawnFlags flags,
                                             GSpawnChildSetupFunc child_setup,
                                             gpointer user_data,
                                             gchar **standard_output,
                                             gchar **standard_error,
                                             gint *exit_status,
                                             GError **error);
gboolean    g_spawn_command_line_async      (const gchar *command_line,
                                             GError **error);
gboolean    g_spawn_command_line_sync       (const gchar *command_line,
                                             gchar **standard_output,
                                             gchar **standard_error,
                                             gint *exit_status,
                                             GError **error);
void        g_spawn_close_pid               (GPid pid);

Описание

Детали

enum GSpawnError

typedef enum
{
  G_SPAWN_ERROR_FORK,   /* fork failed due to lack of memory */
  G_SPAWN_ERROR_READ,   /* read or select on pipes failed */
  G_SPAWN_ERROR_CHDIR,  /* changing to working dir failed */
  G_SPAWN_ERROR_ACCES,  /* execv() returned EACCES */
  G_SPAWN_ERROR_PERM,   /* execv() returned EPERM */
  G_SPAWN_ERROR_2BIG,   /* execv() returned E2BIG */
  G_SPAWN_ERROR_NOEXEC, /* execv() returned ENOEXEC */
  G_SPAWN_ERROR_NAMETOOLONG, /* ""  "" ENAMETOOLONG */
  G_SPAWN_ERROR_NOENT,       /* ""  "" ENOENT */
  G_SPAWN_ERROR_NOMEM,       /* ""  "" ENOMEM */
  G_SPAWN_ERROR_NOTDIR,      /* ""  "" ENOTDIR */
  G_SPAWN_ERROR_LOOP,        /* ""  "" ELOOP   */
  G_SPAWN_ERROR_TXTBUSY,     /* ""  "" ETXTBUSY */
  G_SPAWN_ERROR_IO,          /* ""  "" EIO */
  G_SPAWN_ERROR_NFILE,       /* ""  "" ENFILE */
  G_SPAWN_ERROR_MFILE,       /* ""  "" EMFLE */
  G_SPAWN_ERROR_INVAL,       /* ""  "" EINVAL */
  G_SPAWN_ERROR_ISDIR,       /* ""  "" EISDIR */
  G_SPAWN_ERROR_LIBBAD,      /* ""  "" ELIBBAD */
  G_SPAWN_ERROR_FAILED       /* other fatal failure, error->message
                              * should explain
                              */
} GSpawnError;

Коды ошибок возвращаемые при выполнении процессов.

G_SPAWN_ERROR_FORK форк не удался из-за нехватки памяти.
G_SPAWN_ERROR_READ чтение или выбор канала неудался.
G_SPAWN_ERROR_CHDIR изменение рабочего каталога неудалось.
G_SPAWN_ERROR_ACCES execv() вернул EACCES.
G_SPAWN_ERROR_PERM execv() вернул EPERM.
G_SPAWN_ERROR_2BIG execv() вернул E2BIG.
G_SPAWN_ERROR_NOEXEC execv() вернул ENOEXEC.
G_SPAWN_ERROR_NAMETOOLONG execv() вернул ENAMETOOLONG.
G_SPAWN_ERROR_NOENT execv() вернул ENOENT.
G_SPAWN_ERROR_NOMEM execv() вернул ENOMEM.
G_SPAWN_ERROR_NOTDIR execv() вернул ENOTDIR.
G_SPAWN_ERROR_LOOP execv() вернул ELOOP.
G_SPAWN_ERROR_TXTBUSY execv() вернул ETXTBUSY.
G_SPAWN_ERROR_IO execv() вернул EIO.
G_SPAWN_ERROR_NFILE execv() вернул ENFILE.
G_SPAWN_ERROR_MFILE execv() вернул EMFILE.
G_SPAWN_ERROR_INVAL execv() вернул EINVAL.
G_SPAWN_ERROR_ISDIR execv() вернул EISDIR.
G_SPAWN_ERROR_LIBBAD execv() вернул ELIBBAD.
G_SPAWN_ERROR_FAILED Некоторая другая проблема, error->message должно пояснить.

G_SPAWN_ERROR

#define G_SPAWN_ERROR g_spawn_error_quark ()

Домен ошибки для порождения процессов. Ошибки в этом домене будут из перечисления GSpawnError. Смотрите GError для информации о доменах ошибки.


enum GSpawnFlags

typedef enum
{
  G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0,
  G_SPAWN_DO_NOT_REAP_CHILD      = 1 << 1,
  /* look for argv[0] in the path i.e. use execvp() */
  G_SPAWN_SEARCH_PATH            = 1 << 2,
  /* Dump output to /dev/null */
  G_SPAWN_STDOUT_TO_DEV_NULL     = 1 << 3,
  G_SPAWN_STDERR_TO_DEV_NULL     = 1 << 4,
  G_SPAWN_CHILD_INHERITS_STDIN   = 1 << 5,
  G_SPAWN_FILE_AND_ARGV_ZERO     = 1 << 6
} GSpawnFlags;

Флаги помещаемые в g_spawn_sync(), g_spawn_async() и g_spawn_async_with_pipes().

G_SPAWN_LEAVE_DESCRIPTORS_OPEN дескриптор открытого родительского файла будет унаследован дочерним процессом; иначе все дескрипторы кроме stdin/stdout/stderr будут закрыты перед вызовом exec() в дочернем процессе.
G_SPAWN_DO_NOT_REAP_CHILD дочерний процесс не будет автоматически получен; вы должны вызвать waitpid() или обработать SIGCHLD самостоятельно, или дочерний процесс станет зомби.
G_SPAWN_SEARCH_PATH argv[0] не должен быть абсолютным путём, он будет найден в пользовательском PATH.
G_SPAWN_STDOUT_TO_DEV_NULL стандартный вывод из дочернего процесса будет отменён, вместо направления в тоже расположение родительского стандартного вывода.
G_SPAWN_STDERR_TO_DEV_NULL стандартные ошибки дочернего процесса будут отменены.
G_SPAWN_CHILD_INHERITS_STDIN дочерний процесс унаследует стандартный ввод родителя (по умолчанию, стандартный дочерний ввод прикреплён к /dev/null).
G_SPAWN_FILE_AND_ARGV_ZERO первый элемент argv это выполняемый файл, остальные элементы являются фактически одномерным массивом параметров для помещения в файл. Обычно g_spawn_async_with_pipes() использует argv[0] как файл для выполнения и передаёт все argv в дочерний процесс.

GSpawnChildSetupFunc ()

void        (*GSpawnChildSetupFunc)         (gpointer user_data);

Определяет тип установочной функции помещаемой в g_spawn_async(), g_spawn_sync() и g_spawn_async_with_pipes(). На POSIX платформах она вызывается в дочернем процессе после того как GLib выполнит все запланированные установки, но перед вызовом exec(). В POSIX, действия принятые в этой функции, затронут таким образом только дочерний процесс, а не родителя.

В Windows функция вызывается в родительском процессе. Её полноценность в Windows таким образом сомнительна. В большинстве случаев выполнение функции установки в родительском процессе может иметь плохой эффект, вы должны быть очень осторожны когда портируете программы в Windows использующие дочерние функции установки.

user_data : пользовательские данные помещаемые в функцию.

g_spawn_async_with_pipes ()

gboolean    g_spawn_async_with_pipes        (const gchar *working_directory,
                                             gchar **argv,
                                             gchar **envp,
                                             GSpawnFlags flags,
                                             GSpawnChildSetupFunc child_setup,
                                             gpointer user_data,
                                             GPid *child_pid,
                                             gint *standard_input,
                                             gint *standard_output,
                                             gint *standard_error,
                                             GError **error);

Выполняет дочернюю программу асинхронно (ваша программа не будет блокирована для выхода из дочернего процесса). Дочерняя программа определяет только аргументы которые должны быть предоставлены массивом argv. argv должен быть NULL-завершённым массивом строк, для помещения как одномерный массив в дочерний процесс. Первая строка в argv является названием программы для выполнения. По умолчанию имя программы должно быть полным путём; переменная PATH оболочки (shell) будет использоваться для поиска только если вы поместите флаг G_SPAWN_SEARCH_PATH.

Помните что в Windows все строки или одномерные строковые массивы аргументов для этой функции и других g_spawn*() функций находятся в кодировке UTF-8, кодировка имён файлов GLib. Unicode символы которые не являются частью системной кодовой страницы которые передают в одномерном массиве аргументов будут корректно доступны в порождённой программе только если она использует широкий символьный API для поиска в её командной строке. Для C программ собранных с помощью инструментария Microsoft's достаточно создать программу имея wmain() вместо main(). wmain() имеет широкий символ одномерного массива как параметр.

По крайней мере в настоящее время mingw не поддерживает wmain(), поэтому если вы используете mingw для разработки порождаемых программ, то должны вызвать недокументированную функцию __wgetmainargs() для получения широкого символа аргументов одномерного массива и окружения. Смотрите gspawn-win32-helper.c в GLib исходниках или init.c в исходниках программы mingw для определения прототипа этой функции. Альтернативно вы можете найти широкий символ командной строки системного уровня Win32 помещаемый в порождённую программу используя функцию GetCommandLineW().

В Windows нижний уровень API создания дочерних процессов CreateProcess() не использует одномерный массив аргументов, но использует командную строку. Семейство функций библиотеки C spawn*() (которые вызывают в конечном счёте g_spawn_async_with_pipes()) помещают элементы одномерного массива аргументов вместе в командную строку, а во время выполнения C код делает соответствующую реконструкцию одномерного массива аргументов из командной строки для помещения в main(). Осложнения возникают когда вы имеете элементы одномерного массива аргументов которые содержат пробелы заключённые в двойные кавычки. Функции spawn*() не делают никакого квотирования или выхода, но с другой стороны код запуска закрывает кавычки и не выходит чтобы позволить получить аргументы с включёнными пробелами или двойными кавычками. Для работы вокруг этой ассиметрии, g_spawn_async_with_pipes() выполнит квотирование и прервёт элементы одномерного массива аргументов которые нужны ей перед вызовом функции C runtime spawn().

envp это NULL-завершённый массив строк, где каждая строка имеет форму KEY=VALUE. Это будет окружением дочернего процесса. Если envp это NULL, дочерний процесс наследует окружение его родителя.

flags должен быть поразрядным ИЛИ любых флагов которые должны влиять на поведение функции. G_SPAWN_DO_NOT_REAP_CHILD означает что дочерний процесс не будет автоматически выполнен; вы должны использовать источник GChildWatch для получения уведомления об уничтожении дочернего процесса. В конечном счёте вы должны вызвать g_spawn_close_pid() в child_pid, для освобождения ресурсов связанных с дочерним процессом. (В Unix, используется источник GChildWatch равноценный вызову waitpid() или обрабатывается сигнал SIGCHLD вручную. В Windows, вызов g_spawn_close_pid() равноценно вызову CloseHandle() для обработки возвращаемого child_pid). G_SPAWN_LEAVE_DESCRIPTORS_OPEN означает что родительский дескриптор открытого файла будет унаследован дочерним процессом; иначе все дескрипторы кроме stdin/stdout/stder будут закрыты перед вызовом exec() в дочернем процессе. G_SPAWN_SEARCH_PATH означает что argv[0] не должен быть абсолютным путём, он будет найден в пользовательской переменной PATH. G_SPAWN_STDOUT_TO_DEV_NULL означает что стандартный вывод дочернего процесса будет отменён, он будет направлен в тоже расположение что и стандартный вывод родительского процесса. Если вы используете этот флаг, standard_output должен быть NULL. G_SPAWN_STDERR_TO_DEV_NULL означает что дочерний стандартный поток error будет отменён, вместо этого он будет направлен в тоже расположение что и стандартный поток error родительского процесса. Если вы используете этот флаг, standard_error должен быть NULL. G_SPAWN_CHILD_INHERITS_STDIN означает что дочерний процесс будет наследовать родительский стандартный поток ввода (input) (по умолчанию, стандартный поток ввода дочернего процесса прикреплён к /dev/null). Если вы используете этот флаг, standard_input должен быть NULL. G_SPAWN_FILE_AND_ARGV_ZERO означает что первый элемент argv является исполняемым файлом, в то время как остальные элементы являются фактически одномерным массивом аргументов помещаемых в файл. Обычно g_spawn_async_with_pipes() использует argv[0] как исполняемый файл, и помещает остальные argv в дочерний процесс.

child_setup и user_data являются функцией и пользовательскими данными. На POSIX платформах, функция вызывается в дочернем процессе после выполнения GLib всех запланированных установок (включая создание каналов, закрытие дескрипторов файлов, etc.) но перед вызовом exec(). Таким образом, child_setup вызывается перед вызовом exec() в дочернем процессе. Очевидно что действия принятые в этой функции затронут только дочерний процесс, но не родителя. В Windows, нет разделения fork() и exec() функциональности. Дочерний процесс создаётся и выполняется единственным API вызовом, CreateProcess(). child_setup вызывается в родительском процессе как раз перед созданием дочернего процесса. Вы должны внимательно рассмотреть то что вы делаете в child_setup если вы планируете переносить свою программу в Windows.

Если не-NULL, child_pid будет заполнен в Unix с помощью ID дочернего процесса. Вы можете использовать ID процесса для отправки сигналов дочернему процессу, или для waitpid() если вы определили флаг G_SPAWN_DO_NOT_REAP_CHILD. В Windows, child_pid будет заполнен с помощью обработки дочернего процесса только если вы определили флаг G_SPAWN_DO_NOT_REAP_CHILD. Вы сможете тогда обратиться к дочернему процессу используя Win32 API, например ожидать его завершения с помощью функций WaitFor*(), или например проверить его код завершения с помощью GetExitCodeProcess(). Вы должны завершить обработку с помощью CloseHandle() или g_spawn_close_pid() когда вы больше не нуждаетесь в ней.

Если не-NULL, standard_input, standard_output, standard_error расположения будут заполнены дескрипторами файлов для записи в стандартном потоке ввода дочерних процессов или для чтения в стандартном потоке вывода или для стандартного потока error. Вызывающий g_spawn_async_with_pipes() должен закрыть этот дескриптор файла когда он больше не нужен. Если эти параметры равны NULL, соответственно канал не будет создан.

Если standard_input равен NULL, стандартный ввод дочернего процесса прикреплён к /dev/null пока не установлен G_SPAWN_CHILD_INHERITS_STDIN.

Если standard_error равен NULL, стандартный поток error дочернего процесса направлен в тоже расположение что и стандартный поток error родительского процесса пока не установлен G_SPAWN_STDERR_TO_DEV_NULL.

Если standard_output равен NULL, стандартный вывод дочернего процесса направлен в то же расположение что и стандартный вывод родительского процесса пока не установлен G_SPAWN_STDOUT_TO_DEV_NULL.

error может быть NULL для игнорирования ошибок, или не-NULL для сообщения об ошибках. Если error установлен, функция возвращает FALSE. Об ошибках сообщается даже если они происходят в дочернем процессе (например если исполняемый файл в argv[0] небыл найден). Обычно поле message возвращаемой ошибки должно отображаться пользователям. Возможные ошибки указаны в домене G_SPAWN_ERROR.

Если произошла ошибка, child_pid, standard_input, standard_output, и standard_error не будут заполнены допустимыми значениями.

Если child_pid не-NULL и не происходит ошибки то возвращаемый pid должен быть закрыт с помощью g_spawn_close_pid().

working_directory : текущий рабочий каталог дочернего процесса, или NULL для наследования родительского, в кодировке имён файлов GLib
argv : одномерный массив аргументов дочернего процесса, в кодировке имён файлов GLib
envp : окружение дочернего процесса, или NULL для наследования родительского, в кодировке имён файлов GLib
flags : флаги из GSpawnFlags
child_setup : функция запускаемая в дочернем процессе перед exec()
user_data : пользовательские данные для child_setup
child_pid : расположение для возвращаемого ID дочернего процесса, или NULL
standard_input : расположение возвращаемого дескриптора файла для записи стандартным потоком stdin дочернего процесса, или NULL
standard_output : расположение возвращаемого дескриптора файла для чтения стандартным потоком stdout дочернего процесса, или NULL
standard_error : расположение возвращаемого дескриптора файла для чтения стандартным потоком stderr дочернего процесса, или NULL
error : расположение для возвращаемой ошибки
Возвращает : TRUE при успешном выполнении, FALSE если была установлена ошибка

g_spawn_async ()

gboolean    g_spawn_async                   (const gchar *working_directory,
                                             gchar **argv,
                                             gchar **envp,
                                             GSpawnFlags flags,
                                             GSpawnChildSetupFunc child_setup,
                                             gpointer user_data,
                                             GPid *child_pid,
                                             GError **error);

Смотрите g_spawn_async_with_pipes() для полного описания; эта функция просто вызывает g_spawn_async_with_pipes() без всяких каналов.

working_directory : текущий рабочий каталог дочернего процесса, или NULL для наследования родительского
argv : одномерный массив аргументов дочернего процесса
envp : окружение дочернего процесса, или NULL для наследования родительского
flags : флаги из GSpawnFlags
child_setup : функция для запуска в дочернем процессе перед exec()
user_data : пользовательские данные для child_setup
child_pid : расположение для возвращаемого ID дочернего процесса, или NULL
error : расположение для возвращаемой ошибки
Возвращает : TRUE при успешном выполнении, FALSE если установлена ошибка

g_spawn_sync ()

gboolean    g_spawn_sync                    (const gchar *working_directory,
                                             gchar **argv,
                                             gchar **envp,
                                             GSpawnFlags flags,
                                             GSpawnChildSetupFunc child_setup,
                                             gpointer user_data,
                                             gchar **standard_output,
                                             gchar **standard_error,
                                             gint *exit_status,
                                             GError **error);

Выполняет дочерний процесс синхронно (ждёт выхода из дочернего процесса перед возвращением). Весь вывод из дочернего процесса сохраняется в standard_output и standard_error, если эти параметры не-NULL. Если exit_status не-NULL, статус выхода из дочернего процесса сохраняется как если бы было возвращено waitpid(); стандартные UNIX макросы такие как WIFEXITED() и WEXITSTATUS() должны использоваться для оценки состояния выхода. Если произошла ошибка, нет данных возвращённых в standard_output, standard_error, или exit_status.

Эта функция вызывает g_spawn_async_with_pipes() внутренне; смотрите полные детали в других параметрах и детали как эти функции работают в Windows.

working_directory : текущий рабочий каталог дочернего процесса, или NULL для наследования родительского
argv : одномерный массив аргументов дочернего процесса
envp : окружение дочернего процесса, или NULL для наследования родительского
flags : флаги из GSpawnFlags
child_setup : функция для запуска в дочернем процессе перед exec()
user_data : пользовательские данные для child_setup
standard_output : расположение возвращаемого дочернего потока output
standard_error : расположение возвращаемых дочерних сообщений об ошибках
exit_status : расположение для возвращаемого статуса выхода дочернего процесса, который возвращается из waitpid()
error : расположение для возвращаемой ошибки
Возвращает : TRUE при успешном выполнении, FALSE если была установлена ошибка.

g_spawn_command_line_async ()

gboolean    g_spawn_command_line_async      (const gchar *command_line,
                                             GError **error);

Простая версия g_spawn_async() которая анализирует командную строку с помощью g_shell_parse_argv() и направляет в g_spawn_async(). Выполняет командную строку в фоновом режиме. В отличие от g_spawn_async(), флаг G_SPAWN_SEARCH_PATH включен, другие флаги нет. Помните что G_SPAWN_SEARCH_PATH может иметь безопасные включения, поэтому рассмотрите непосредственное использование g_spawn_async() если возможно. Возможные ошибки указаны в g_shell_parse_argv() и g_spawn_async().

Встречаются те же проблемы в Windows применении, что и для g_spawn_command_line_sync().

command_line : командная строка
error : расположение для возвращаемых ошибок
Возвращает : TRUE при успешном выполнении, FALSE если установлена ошибка.

g_spawn_command_line_sync ()

gboolean    g_spawn_command_line_sync       (const gchar *command_line,
                                             gchar **standard_output,
                                             gchar **standard_error,
                                             gint *exit_status,
                                             GError **error);

Простая версия g_spawn_sync() с удалёнными мало-используемыми параметрами, принимает командную строку вместо одномерного массива аргументов. Смотрите g_spawn_sync() для изучения всех деталей. command_line будет анализироваться с помощью g_shell_parse_argv(). В отличие от g_spawn_sync(), флаг G_SPAWN_SEARCH_PATH включен. Помните что G_SPAWN_SEARCH_PATH может иметь безопасные включения, поэтому рассмотрите непосредственное использование g_spawn_sync() если возможно. Возможные ошибки происходят из g_spawn_sync() и from g_shell_parse_argv().

Если exit_status не-NULL, статус выхода дочернего процесса сохраняется как возвращаемый waitpid(); стандартные UNIX макросы WIFEXITED() и WEXITSTATUS() должны использоваться для оценки статуса выхода.

В Windows, пожалуйста помните включение g_shell_parse_argv() анализирующую command_line. Анализ выполняется согласно правилам оболочки Unix, а не правил командного интерпретатора Windows. Пробел является разделителем, и backslashes является специальным. Поэтому вы не можете прост поместить command_line содержащую канонический Windows путь, как "c:\\program files\\app\\app.exe", поскольку backslashes будут подавлены, и пробелы будут действовать как разделители. Вам нужно заключать такие пути в одиночные кавычки, например "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".

command_line : командная строка
standard_output : расположение возвращаемого дочернего потока output
standard_error : расположение возвращаемых дочерних ошибок
exit_status : расположение для возвращаемого статуса выхода дочернего процесса, который возвращает waitpid()
error : расположение для возвращаемых ошибок
Возвращает : TRUE при успешном выполнении, FALSE если установлена ошибка

g_spawn_close_pid ()

void        g_spawn_close_pid               (GPid pid);

На некоторых платформах, особенно WIN32, тип GPid представляет ресурс который должен быть закрыт для предотвращения утечки ресурсов. g_spawn_close_pid() предназначена для этих целей. Она должна использоваться на всех платформах, даже при том что она ничего не делает в UNIX.

pid : идентификатор процесса для закрытия

Стандартные макросы

Standard Macros — Основные макросы.

Краткое описание


#include <glib.h>



#define     G_OS_WIN32
#define     G_OS_BEOS
#define     G_OS_UNIX

#define     G_DIR_SEPARATOR
#define     G_DIR_SEPARATOR_S
#define     G_IS_DIR_SEPARATOR              (c)
#define     G_SEARCHPATH_SEPARATOR
#define     G_SEARCHPATH_SEPARATOR_S

#define     TRUE
#define     FALSE

#define     NULL

#define     MIN                             (a, b)
#define     MAX                             (a, b)

#define     ABS                             (a)
#define     CLAMP                           (x, low, high)

#define     G_STRUCT_MEMBER                 (member_type, struct_p, struct_offset)
#define     G_STRUCT_MEMBER_P               (struct_p, struct_offset)
#define     G_STRUCT_OFFSET                 (struct_type, member)

#define     G_MEM_ALIGN

#define     G_CONST_RETURN

Описание

Эти макросы обеспечивают обычное выполнение некоторых особенностей.

Детали

G_OS_WIN32

#define G_OS_WIN32

Этот макрос определяется только в Windows. Поэтому вы можете группировать Windows-специфичный код в "#ifdef G_OS_WIN32".


G_OS_BEOS

#define G_OS_BEOS

Этот макрос определяется только в BeOS. Поэтому вы можете группировать BeOS-специфичный код в "#ifdef G_OS_BEOS".


G_OS_UNIX

#define G_OS_UNIX

Этот макрос определяется только в UNIX. Поэтому вы можете группировать UNIX-специфичный код в #ifdef G_OS_UNIX".


G_DIR_SEPARATOR

#define     G_DIR_SEPARATOR

Символ разделения каталогов. Это '/' в UNIX и '\' в Windows.


G_DIR_SEPARATOR_S

#define     G_DIR_SEPARATOR_S

Разделитель каталогов как строка. Это "/" в UNIX и "\" в Windows.


G_IS_DIR_SEPARATOR()

#define     G_IS_DIR_SEPARATOR(c)

Проверяет является ли символ разделителем каталогов. Возвращает TRUE для '/' в UNIX и для '\' или '/' в Windows.

c : символ

Начиная с версии 2.6


G_SEARCHPATH_SEPARATOR

#define     G_SEARCHPATH_SEPARATOR

Символ разделитель пути поиска. Это ':' в UNIX и ';' в Windows.


G_SEARCHPATH_SEPARATOR_S

#define     G_SEARCHPATH_SEPARATOR_S

Строка разделитель в пути поиска. Это ":" в UNIX и ";" в Windows.


TRUE

#define	TRUE	(!FALSE)

Определяет значение TRUE для gboolean типа.


FALSE

#define	FALSE	(0)

Определяет значение FALSE для gboolean типа.


NULL

#define     NULL

Определяет стандартный указатель NULL.


MIN()

#define MIN(a, b)  (((a) < (b)) ? (a) : (b))

Находит меньшее из a и b.

a : числовое значение.
b : числовое значение.
Возвращает : наименьшее из a и b.

MAX()

#define MAX(a, b)  (((a) > (b)) ? (a) : (b))

Находит наибольшее из a и b.

a : числовое значение.
b : числовое значение.
Возвращает : наибольшее из a и b.

ABS()

#define ABS(a)	   (((a) < 0) ? -(a) : (a))

Расчитывает абсолютное значение a. Абсолютное значение это простое число без отрицательного знака.

Например,

  • ABS(-10) равно 10.

  • ABS(10) также равно 10.

a : числовое значение.
Возвращает : абсолютное значение a.

CLAMP()

#define CLAMP(x, low, high)  (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x)))

Находит x между установленными лимитами low и high.

Например,

  • CLAMP(5, 10, 15) это 10.

  • CLAMP(15, 5, 10) это 10.

  • CLAMP(20, 15, 25) это 20.

x : промежуточное числовое значение.
low : допустимое минимальное значение.
high : допустимое максимальное значение.
Возвращает : значение x заключенное между диапазоном low и high.

G_STRUCT_MEMBER()

#define     G_STRUCT_MEMBER(member_type, struct_p, struct_offset)

Возвращает элемент структуры в полученном смещении, используя полученный тип.

member_type : типовое поле структуры.
struct_p : указатель в структуре.
struct_offset : смещение поля от начала структуры, в байтах.
Возвращает : элемент структуры.

G_STRUCT_MEMBER_P()

#define     G_STRUCT_MEMBER_P(struct_p, struct_offset)

Возвращает указатель без типа для полученного смещения структуры.

struct_p : указатель в структуре.
struct_offset : смещение от начала структуры, в байтах.
Возвращает : указатель без типа struct_p плюс struct_offset байт.

G_STRUCT_OFFSET()

#define     G_STRUCT_OFFSET(struct_type, member)

Возвращает смещение в байтах элемента структуры.

struct_type : тип структуры, например GtkWidget.
member : поле структуры, например window.
Возвращает : смещение элемента от начала struct_type.

G_MEM_ALIGN

#define     G_MEM_ALIGN

Указывает количество байт по которым будет распределена память в текущей платформе.


G_CONST_RETURN

#define     G_CONST_RETURN

Если G_DISABLE_CONST_RETURNS определён, этот макрос не выполняется. По умолчанию, макрос расширяется до const. Макрос должен использоваться для помещения const в функции возвращающие значения которые не должны изменяться. В основном этот макрос позволяет использовать включение const для возвращаемых константных строк по умолчанию, пока программист не отключит это. Этот макрос должен использоваться только для возвращаемых значений и для out параметров, он не действует для in параметров.



String Chunks

String Chunks — Эффективное хранение групп строк.

Краткое описание


#include <glib.h>


            GStringChunk;
GStringChunk* g_string_chunk_new            (gsize size);
gchar*      g_string_chunk_insert           (GStringChunk *chunk,
                                             const gchar *string);
gchar*      g_string_chunk_insert_const     (GStringChunk *chunk,
                                             const gchar *string);
gchar*      g_string_chunk_insert_len       (GStringChunk *chunk,
                                             const gchar *string,
                                             gssize len);
void        g_string_chunk_free             (GStringChunk *chunk);

Описание

Строковый блок используется для хранения групп строк. Память распределяется блоками и когда строки добавляются в GStringChunk они копируются в следующую свободную позицию в блоке. Когда блок заполняется распределяется следующий блок.

Когда сохраняется большое количество строк, строковые блоки более эффективны чем использование g_strdup(), так как необходимо меньше вызовов malloc(), и при распределении тратится меньше памяти на накладные расходы.

Добавление строк с помощью g_string_chunk_insert_const(), также позволяет удалять дубликаты.

Для создания новой GStringChunk используется g_string_chunk_new().

Для добавления строк в GStringChunk используется g_string_chunk_insert().

Для добавления строк в GStringChunk, но без дубликатов уже существующих строк в GStringChunk, используется g_string_chunk_insert_const().

Для освобождения элементов GStringChunk используется g_string_chunk_free(). Она не позволяет освобождать отдельные строки.

Детали

GStringChunk

typedef struct _GStringChunk GStringChunk;

Непрозрачная структура данных представляющая строковый блок (String Chunks). Она должна использоваться только при помощи следующих функций.


g_string_chunk_new ()

GStringChunk* g_string_chunk_new            (gsize size);

Создаёт новый GStringChunk.

size : размер по умолчанию блока памяти который распределён для хранения строк. Если определённая строка больше чем этот размер по умолчанию, то для неё будет распределён блок большего размера.
Возвращает : новый GStringChunk.

g_string_chunk_insert ()

gchar*      g_string_chunk_insert           (GStringChunk *chunk,
                                             const gchar *string);

Добавляет копию string в GStringChunk. Возвращает указатель на новую копию строки в GStringChunk. Символы в строке могут быть изменены, если необходимо, однако вы не должны изменять ничего после завершения строки.

В отличие g_string_chunk_insert_const(), эта функция не контролирует дубликаты. А также строки добавленные с помощью g_string_chunk_insert() не будут найдены с помощью g_string_chunk_insert_const() при поиске дубликатов.

chunk : GStringChunk.
string : строка для добавления.
Возвращает : указатель на копию string внутри GStringChunk.

g_string_chunk_insert_const ()

gchar*      g_string_chunk_insert_const     (GStringChunk *chunk,
                                             const gchar *string);

Добавляет копию string в GStringChunk, если такая же строка уже не добавлена в GStringChunk с помощью g_string_chunk_insert_const().

Эта функция полезна если вам нужно копировать большое количество строк но не нужно тратить пространство хранилища под дубликаты. Но вы должны помнить что здесь могут быть указатели на туже строку и поэтому любые изменения в строках должны выполняться очень осторожно.

Помните что g_string_chunk_insert_const() не будет возвращать указатель на строку добавленную с помощью g_string_chunk_insert(), даже если они соответствуют.

chunk : GStringChunk.
string : строка для добавления.
Возвращает : указатель на новую или существующую копию string внутри GStringChunk.

g_string_chunk_insert_len ()

gchar*      g_string_chunk_insert_len       (GStringChunk *chunk,
                                             const gchar *string,
                                             gssize len);

Добавляет копию первых len байт string в GStringChunk. Копия nul-завершённая.

Символы в строке могут изменяться, если необходимо, однако вы не должны делать никаких изменений после завершения строки.

chunk : GStringChunk
string : байты для вставки
len : количество байт string для вставки, или -1 для вставки nul-завершённой строки.
Возвращает : указатель на копию string внутри GStringChunk

Начиная с версии 2.4


g_string_chunk_free ()

void        g_string_chunk_free             (GStringChunk *chunk);

Освобождает всю память распределённую GStringChunk. После вызова g_string_chunk_free() запрещается доступ к любым строкам которые содержались внутри.

chunk : GStringChunk.

Строковые сервисные функции

String Utility Functions — Варианты строковых функций.

Краткое описание


#include <glib.h>
#include <glib/gprintf.h>


gchar*      g_strdup                        (const gchar *str);
gchar*      g_strndup                       (const gchar *str,
                                             gsize n);
gchar**     g_strdupv                       (gchar **str_array);
gchar*      g_strnfill                      (gsize length,
                                             gchar fill_char);
gchar*      g_stpcpy                        (gchar *dest,
                                             const char *src);
gchar*      g_strstr_len                    (const gchar *haystack,
                                             gssize haystack_len,
                                             const gchar *needle);
gchar*      g_strrstr                       (const gchar *haystack,
                                             const gchar *needle);
gchar*      g_strrstr_len                   (const gchar *haystack,
                                             gssize haystack_len,
                                             const gchar *needle);
gboolean    g_str_has_prefix                (const gchar *str,
                                             const gchar *prefix);
gboolean    g_str_has_suffix                (const gchar *str,
                                             const gchar *suffix);

gsize       g_strlcpy                       (gchar *dest,
                                             const gchar *src,
                                             gsize dest_size);
gsize       g_strlcat                       (gchar *dest,
                                             const gchar *src,
                                             gsize dest_size);

gchar*      g_strdup_printf                 (const gchar *format,
                                             ...);
gchar*      g_strdup_vprintf                (const gchar *format,
                                             va_list args);
gint        g_printf                        (gchar const *format,
                                             ...);
gint        g_vprintf                       (gchar const *format,
                                             va_list args);
gint        g_fprintf                       (FILE *file,
                                             gchar const *format,
                                             ...);
gint        g_vfprintf                      (FILE *file,
                                             gchar const *format,
                                             va_list args);
gint        g_sprintf                       (gchar *string,
                                             gchar const *format,
                                             ...);
gint        g_vsprintf                      (gchar *string,
                                             gchar const *format,
                                             va_list args);
gint        g_snprintf                      (gchar *string,
                                             gulong n,
                                             gchar const *format,
                                             ...);
gint        g_vsnprintf                     (gchar *string,
                                             gulong n,
                                             gchar const *format,
                                             va_list args);
gint        g_vasprintf                     (gchar **string,
                                             gchar const *format,
                                             va_list args);
gsize       g_printf_string_upper_bound     (const gchar *format,
                                             va_list args);

gboolean    g_ascii_isalnum                 (gchar c);
gboolean    g_ascii_isalpha                 (gchar c);
gboolean    g_ascii_iscntrl                 (gchar c);
gboolean    g_ascii_isdigit                 (gchar c);
gboolean    g_ascii_isgraph                 (gchar c);
gboolean    g_ascii_islower                 (gchar c);
gboolean    g_ascii_isprint                 (gchar c);
gboolean    g_ascii_ispunct                 (gchar c);
gboolean    g_ascii_isspace                 (gchar c);
gboolean    g_ascii_isupper                 (gchar c);
gboolean    g_ascii_isxdigit                (gchar c);

gint        g_ascii_digit_value             (gchar c);
gint        g_ascii_xdigit_value            (gchar c);

gint        g_ascii_strcasecmp              (const gchar *s1,
                                             const gchar *s2);
gint        g_ascii_strncasecmp             (const gchar *s1,
                                             const gchar *s2,
                                             gsize n);

gchar*      g_ascii_strup                   (const gchar *str,
                                             gssize len);
gchar*      g_ascii_strdown                 (const gchar *str,
                                             gssize len);

gchar       g_ascii_tolower                 (gchar c);
gchar       g_ascii_toupper                 (gchar c);

GString*    g_string_ascii_up               (GString *string);
GString*    g_string_ascii_down             (GString *string);

gchar*      g_strup                         (gchar *string);
gchar*      g_strdown                       (gchar *string);

gint        g_strcasecmp                    (const gchar *s1,
                                             const gchar *s2);
gint        g_strncasecmp                   (const gchar *s1,
                                             const gchar *s2,
                                             guint n);

gchar*      g_strreverse                    (gchar *string);

gint64      g_ascii_strtoll                 (const gchar *nptr,
                                             gchar **endptr,
                                             guint base);
guint64     g_ascii_strtoull                (const gchar *nptr,
                                             gchar **endptr,
                                             guint base);
#define     G_ASCII_DTOSTR_BUF_SIZE
gdouble     g_ascii_strtod                  (const gchar *nptr,
                                             gchar **endptr);
gchar*      g_ascii_dtostr                  (gchar *buffer,
                                             gint buf_len,
                                             gdouble d);
gchar*      g_ascii_formatd                 (gchar *buffer,
                                             gint buf_len,
                                             const gchar *format,
                                             gdouble d);
gdouble     g_strtod                        (const gchar *nptr,
                                             gchar **endptr);

gchar*      g_strchug                       (gchar *string);
gchar*      g_strchomp                      (gchar *string);
#define     g_strstrip                      ( string )

gchar*      g_strdelimit                    (gchar *string,
                                             const gchar *delimiters,
                                             gchar new_delimiter);
#define     G_STR_DELIMITERS
gchar*      g_strescape                     (const gchar *source,
                                             const gchar *exceptions);
gchar*      g_strcompress                   (const gchar *source);
gchar*      g_strcanon                      (gchar *string,
                                             const gchar *valid_chars,
                                             gchar substitutor);
gchar**     g_strsplit                      (const gchar *string,
                                             const gchar *delimiter,
                                             gint max_tokens);
gchar**     g_strsplit_set                  (const gchar *string,
                                             const gchar *delimiters,
                                             gint max_tokens);
void        g_strfreev                      (gchar **str_array);
gchar*      g_strconcat                     (const gchar *string1,
                                             ...);
gchar*      g_strjoin                       (const gchar *separator,
                                             ...);
gchar*      g_strjoinv                      (const gchar *separator,
                                             gchar **str_array);
guint       g_strv_length                   (gchar **str_array);

const gchar* g_strerror                     (gint errnum);
const gchar* g_strsignal                    (gint signum);

Описание

Этот раздел описывает множество сервисных функций для создания, дублирования и манипулирования строками.

Помните что функции g_printf(), g_fprintf(), g_sprintf(), g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() и g_vsnprintf() объявлены в заголовочном файле gprintf.h который не включён в glib.h (иначе использование glib.h привлекло бы stdio.h), поэтому вы должны явно включить <glib/gprintf.h> чтобы использовать GLib printf() функции.

Во время использования printf() функций для строк формата UTF-8, обратите внимание что точность параметра %Ns интерпретируется в количество байт, а не символов для печати. В добавок к этому, реализация GNU libc printf() функций имеет "особеность" прверять что полученная строка для %Ns параметра состоит из целого числа символов в текущей кодировке. Поэтому если вы не уверены что всегда используется UTF-8 locale или знаете что ваш текст находится в ASCII, избегайте использования %Ns. Если вы намереваетесь отформатировать строки в несколько столбцов, то %Ns не подходит для этого в любом случае, так как он не принимает во внимание широкие символы (смотрите g_unichar_iswide()).

Детали

g_strdup ()

gchar*      g_strdup                        (const gchar *str);

Дублирует строку. Если параметр str равен NULL возвращает NULL. Возвращаемая строка должна освобождаться когда больше не нужна.

str : строка для дублирования.
Возвращает : вновь распределённая копия str.

g_strndup ()

gchar*      g_strndup                       (const gchar *str,
                                             gsize n);

Дублирует первые n символов строки, возвращает вновь распределённый буфер длиной n + 1 символ который всегда nul-terminated. Если str меньше чем n символов, буфер дополняется нулями (nuls). Если str равен NULL возвращается NULL. Возвращаемая строка должна освобождаться когда больше не нужна.

str : строка для частичного дублирования.
n : максимальное количество символов для копирования из строки str.
Возвращает : вновь распределённый буфер содержащий первые n символов строки str, nul-завершённый.

g_strdupv ()

gchar**     g_strdupv                       (gchar **str_array);

Копирует NULL-завершённый массив строк. Новый массив освобождается сначала освобождая каждую строку, затем непосредственно сам массив. g_strfreev() делает это за вас. Если вызвать с значением NULL, g_strdupv() просто вернёт NULL.

str_array : NULL-завершённый массив строк.
Возвращает : новый NULL-завершённый массив строк.

g_strnfill ()

gchar*      g_strnfill                      (gsize length,
                                             gchar fill_char);

Создаёт новую строку длинной length символов на всю длину заполненную символами fill_char. Возвращаемая строка должна освобождаться когда больше не нужна.

length : длина новой строки.
fill_char : символ для заполнения строки.
Возвращает : вновь распределённая строка заполненная fill_char.

g_stpcpy ()

gchar*      g_stpcpy                        (gchar *dest,
                                             const char *src);

Копирует nul-завершённую строку в буфер dest, включая замыкающий nul и возвращает указатель на завершающий nul байт. Это полезно при соединении нескольких строк вместе без необходимости неоднократного сканирования конца.

dest : буфер назначения.
src : исходная строка.
Возвращает : указатель на завершающий нулевой байт.

g_strstr_len ()

gchar*      g_strstr_len                    (const gchar *haystack,
                                             gssize haystack_len,
                                             const gchar *needle);

Ищет строку haystack до первого появления строки needle, ограничивая длину поиска значением haystack_len.

haystack : строка.
haystack_len : максимальная длина haystack.
needle : строка для поиска.
Возвращает : указатель на найденное совпадение, или NULL если ничего не найдено.

g_strrstr ()

gchar*      g_strrstr                       (const gchar *haystack,
                                             const gchar *needle);

Ищет строку haystack до последнего совпадения строки needle.

haystack : nul-завершённая строка.
needle : nul-завершённая строка для поиска.
Возвращает : указатель на найденное совпадение, или NULL если ничего не найдено.

g_strrstr_len ()

gchar*      g_strrstr_len                   (const gchar *haystack,
                                             gssize haystack_len,
                                             const gchar *needle);

Ищет строку haystack до последнего совпадения строки needle, ограничивая длину поиска значением haystack_len.

haystack : nul-завершённая строка.
haystack_len : максимальная длина haystack.
needle : nul-завершённая строка для поиска.
Возвращает : указатель на найденное совпадение, или NULL если ничего не найдено.

g_str_has_prefix ()

gboolean    g_str_has_prefix                (const gchar *str,
                                             const gchar *prefix);

Определяет начинается ли строка str с префикса prefix.

str : nul-завершённая строка.
prefix : nul-завершённый префикс для поиска.
Возвращает : TRUE если str начинается с prefix, иначе FALSE.

Начиная с версии 2.2


g_str_has_suffix ()

gboolean    g_str_has_suffix                (const gchar *str,
                                             const gchar *suffix);

Определяет заканчивается ли строка str суффиксом suffix.

str : nul-завершённая строка.
suffix : nul-завершённый суффикс для поиска.
Возвращает : TRUE если str заканчивается suffix, иначе FALSE.

Начиная с версии 2.2


g_strlcpy ()

gsize       g_strlcpy                       (gchar *dest,
                                             const gchar *src,
                                             gsize dest_size);

Переносимая оболочка для вызова strlcpy() на системах которые имеют эту функцию она просто вызывает её, а на системах где нет strlcpy() эмулирует её. Копирует src в dest; dest гарантированно будет nul-завершённой; src должна быть nul-terminated; dest_size является размером буфера, а не количеством символов для копирования. Предостережение: strlcpy() более безопасна чем strcpy() или strncpy(), но если вы действительно хотите избежать проблем, то лучше используйте g_strdup().

dest : буфер назначения
src : исходный буфер
dest_size : длина dest в байтах
Возвращает : длина src

g_strlcat ()

gsize       g_strlcat                       (gchar *dest,
                                             const gchar *src,
                                             gsize dest_size);

Переносимая оболочка функции strlcat(), на системах где нет этой функции она её эмулирует. Добавляет nul-завершённую строку src в dest, гарантирует nul-заврершённую dest. Полный размер dest не превышает dest_size. Предостережение: это возможно более безопасная альтернатива для strcat() или strncat(), но для действительно безопасного соединения лучше использовать g_strconcat().

dest : буфер назначения, уже содержащий одну nul-завершённую строку
src : исходный буфер
dest_size : длина буфера dest в байтах (не размер существующей строки внутри dest)
Возвращает : длина src плюс начальная длина строки в dest

g_strdup_printf ()

gchar*      g_strdup_printf                 (const gchar *format,
                                             ...);

Аналогична для стандартной C функции sprintf() но безопасней, так как она рассчитывает максимальное требуемое пространство и распределяет память содержащую результат. Возвращаемая строка должна освобождаться когда больше не нужна.

format : стандартная строка формата printf(), но помните опасность строковой точности.
... : параметры вставляемые в форматируемую строку.
Возвращает : вновь распределённая строка содержащая результат.

g_strdup_vprintf ()

gchar*      g_strdup_vprintf                (const gchar *format,
                                             va_list args);

Похожа на стандартную C функцию vsprintf() но безопасней, так как она рассчитывает максимальное требуемое свободное пространство и распределяет память содержащую результат. Возвращаемая строка должна освобождаться когда больше не нужна.

Смотрите также g_vasprintf(), которая отличается некоторой функциональностью, но дополняет возвращаемый результат длинной распредделённой строки.

format : стандартная строка формата printf(), но помните проблемы точности строк.
args : список параметров для вставки в форматируемую строку.
Возвращает : вновь распределённая строка содержащая результат.

g_printf ()

gint        g_printf                        (gchar const *format,
                                             ...);

Реализация стандартной функции printf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

format : стандартная строка формата printf(), но помните о проблеме точности строк.
... : аргументы для вставки в вывод (output).
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_vprintf ()

gint        g_vprintf                       (gchar const *format,
                                             va_list args);

Реализация стандартной функции vprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов вставляемых в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_fprintf ()

gint        g_fprintf                       (FILE *file,
                                             gchar const *format,
                                             ...);

Реализация стандартной функции fprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

file : поток для записи.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
... : аргументы вставляемые в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_vfprintf ()

gint        g_vfprintf                      (FILE *file,
                                             gchar const *format,
                                             va_list args);

Реализация стандартной функции fprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

file : попыток для записи.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов для вставки в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_sprintf ()

gint        g_sprintf                       (gchar *string,
                                             gchar const *format,
                                             ...);

Реализация стандартной функции sprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

string : буфер для содержания вывода.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
... : аргументы для вставки в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_vsprintf ()

gint        g_vsprintf                      (gchar *string,
                                             gchar const *format,
                                             va_list args);

Реализация стандартной функции vsprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

string : буфер для содержания вывода.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов вставляемых в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_snprintf ()

gint        g_snprintf                      (gchar *string,
                                             gulong n,
                                             gchar const *format,
                                             ...);

Более безопасный вариант стандартной функции sprintf(). Гарантирует что вывод не превысит n символов (включая завершающий нулевой символ (nul character)), поэтому переполнение буфера невозможно.

Смотрите также g_strdup_printf().

В версиях GLib до 1.2.3, эта функция может возвращать -1 если вывод был усечён, а усечённая строка может быть не nul-завершённой. В версии до 1.3.12, эта функция возвращает длину строки вывода.

Возвращаемое значение g_snprintf() согласуется с функцией snprintf() как стандартизировано в ISO C99. Помните что это отличается от традиционной snprintf(), которая возвращает длину строки вывода.

Форматируемая строка может содержать параметры позиционирования, как определено в Single Unix Specification.

string : буфер для содержания вывода.
n : максимальное количество производимых символов (включая символ завершения nul).
format : стандартная строка формата printf(), но помните о проблеме точности строк.
... : аргументы для вставки в вывод.
Возвращает : количество произведённых символов если бы буфер был достаточно большим.

g_vsnprintf ()

gint        g_vsnprintf                     (gchar *string,
                                             gulong n,
                                             gchar const *format,
                                             va_list args);

Более безопасный вариант стандартной функции vsprintf(). Вывод гарантировано не превысит n символов (включая завершающий символ), поэтому переполнение буфера не возможно.

Смотрите также g_strdup_vprintf().

В версиях GLib до 1.2.3, эта функция может возвращать -1 если вывод был усечён, а усечённая строка может быть не nul-завершённой. В версии до 1.3.12, эта функция возвращает длину строки вывода.

Возвращаемое значение g_vsnprintf() согласуется с функцией vsnprintf() как стандартизировано в ISO C99. Помните что это отличается от традиционной vsnprintf(), которая возвращает длину строки вывода.

Форматируемая строка может содержать параметры позиционирования, как описано в Single Unix Specification.

string : буфер для вывода.
n : максимальное количество символов (включая завершающий nul символ).
format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов для вставки в вывод.
Возвращает : количество символов которые должны быть произведены если буфер окажется больше чем необходимо.

g_vasprintf ()

gint        g_vasprintf                     (gchar **string,
                                             gchar const *format,
                                             va_list args);

Реализация функции GNU vasprintf() которая поддерживает параметры позиционирования, как описано в Single Unix Specification. Эта функция похожа на g_vsprintf(), но она распределяет строку содержащую вывод, а не помещает вывод в буфер распределённый вами заранее.

string : расположение для возвращаемой вновь распределённой строки.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов для вставки в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.4


g_printf_string_upper_bound ()

gsize       g_printf_string_upper_bound     (const gchar *format,
                                             va_list args);

Расчитывает необходимое пространство необходимое для сохранения вывода функции sprintf().

format : форматируемая строка. Смотрите документацию printf().
args : параметры для вставки в форматируемую строку.
Возвращает : максимальное пространство необходимое для сохранения форматируемой строки.

g_ascii_isalnum ()

gboolean    g_ascii_isalnum                 (gchar c);

Определяет являются ли символы алфавитно-цифровыми.

В отличие от стандартной библиотечной C функции isalnum(), эта функция распознаёт только стандартные ASCII символы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её в конце файла EOF и не нужно приводить к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c алфавитно-цифровой символ ASCII.

g_ascii_isalpha ()

gboolean    g_ascii_isalpha                 (gchar c);

Определяет является ли символ алфавитным (то есть буквой).

В отличие от стандартной библиотечной функции isalpha(), эта распознаёт только стандартные ASCII буквы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывается в конце файла EOF и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c является алфавитным ASCII символом.

g_ascii_iscntrl ()

gboolean    g_ascii_iscntrl                 (gchar c);

Определяет является ли символ управляющим символом.

В отличие от стандартной библиотечной функции iscntrl(), эта рассматривает только стандартные символы управления ASCII и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной функции, эта принимает char, вместо int, поэтому не вызывается в конце файла EOF и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c является управляющим символом ASCII.

g_ascii_isdigit ()

gboolean    g_ascii_isdigit                 (gchar c);

Определяет является ли символ цифрой (0-9).

В отличие от стандартной библиотечной функции isdigit(), эта принимает char, вместо int, поэтому не вызывается в конце файла EOF и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c является ASCII цифрой.

g_ascii_isgraph ()

gboolean    g_ascii_isgraph                 (gchar c);

Определяет является ли символ печатным и не прбелом.

В отличие от стандартной библиотечной функции isgraph(), эта распознаёт только стандартные символы ASCII и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, вместо int, поэтому не должна вызываться в конце файла EOF и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII печатный символ отличающийся от пробела.

g_ascii_islower ()

gboolean    g_ascii_islower                 (gchar c);

Определяет является ли символ буквой ASCII в нижнем регистре.

В отличие от стандартной библиотечной функции islower(), эта принимает только стандартные ASCII символы и игнорирует локаль (locale), возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её на EOF, и нет необходимости приведения к guchar перед помещением возможно не-ASCII символа в функцию.

c : любой символ
Возвращает : TRUE если c это ASCII символ в нижнем регистре

g_ascii_isprint ()

gboolean    g_ascii_isprint                 (gchar c);

Определяет является ли символ печатным символом.

В отличие от стандартной библиотечной функции isprint(), эта принимает только стандартные ASCII символы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её в EOF и не нужно приводить к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это печатный ASCII символ.

g_ascii_ispunct ()

gboolean    g_ascii_ispunct                 (gchar c);

Определяет является ли символ символом пунктуации.

В отличие от стандартной библиотечной функции ispunct(), это принимает только стандартные ASCII символы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её в EOF и не нужно приводить к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII символ пунктуации.

g_ascii_isspace ()

gboolean    g_ascii_isspace                 (gchar c);

Определяет является ли символ символом табуляции, пробела или символом пустой строки (white-space character).

В отличие от стандартной библиотечной функции isspace(), эта принимает только стандартные ASCII символы white-space и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её в EOF и не нужно приводить тип к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII white-space символ

g_ascii_isupper ()

gboolean    g_ascii_isupper                 (gchar c);

Определяет является ли символ символом ASCII верхнего регистра.

В отличие от стандартной библиотечной функции isupper(), это принимает только стандартные ASCII символы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает тип char, а не int, поэтому не вызывайте её в EOF и не нужно приводить тип к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII символ верхнего регистра

g_ascii_isxdigit ()

gboolean    g_ascii_isxdigit                (gchar c);

Определяет является ли символ шестнадцатеричным-цифровым символом.

В отличие от стандартной библиотечной функции isxdigit(), эта принимает тип char, а не int, поэтому не нужно вызывать её в EOF и не нужно приводить тип к guchar перед помещением вохможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII шестнадцатеричный-цифровой символ.

g_ascii_digit_value ()

gint        g_ascii_digit_value             (gchar c);

Определяет числовое значение символа в виде десятичной цифры. Отличается от g_unichar_digit_value() потому что принимает тип char, поэтому не беспокойтесь о дополнительном знаке (+ или -) если символы со знаком.

c : ASCII символ.
Возвращает : Если c десятичная цифра (согласно g_ascii_isdigit()), её числовое значение. Иначе, -1.

g_ascii_xdigit_value ()

gint        g_ascii_xdigit_value            (gchar c);

Определяет числовое значение символа как шестнадцатеричное число. Отличается от g_unichar_xdigit_value() так как принимает символ, поэтому нет смысла беспокоится о знаке если символы со знаком.

c : ASCII символ.
Возвращает : Если c шестнадцатеричное число (согласно g_ascii_isxdigit()), его числовое значение. Иначе, -1.

g_ascii_strcasecmp ()

gint        g_ascii_strcasecmp              (const gchar *s1,
                                             const gchar *s2);

Сравнивает две строки, игнорирует регистр ASCII символов.

В отличие от BSD функции strcasecmp(), эта принимает только стандартные ASCII буквы и игнорирует локаль, обрабатывая все не-ASCII байты как будто они не буквы.

Эта функция должна использоваться только в строках кодировка байт которых соответствует ASCII литерам всегда представляя самих себя. Это включает UTF-8 и ISO-8859-* символы, но не двойную кодировку байт как в Windows Codepage 932, где завершающий байт двух-байтовых символов включает все ASCII буквы. Если вы сравниваете две CP932 строки используя эту функцию, то вы получите неправильный результат.

s1 : строка для сравнения с s2.
s2 : строка для сравнения с s1.
Возвращает : 0 если строки соответсвуют, отрицательное значение если s1 < s2, или положительное значение если s1 > s2.

g_ascii_strncasecmp ()

gint        g_ascii_strncasecmp             (const gchar *s1,
                                             const gchar *s2,
                                             gsize n);

Сравнивает s1 и s2, игнорирует регистр ASCII символов и любые символы после первых n в каждой строке.

В отличие от BSD функции strcasecmp(), эта функция понимает только стандартные ASCII буквы и игнорирует локаль, обрабатывая все не-ASCII символы как не буквы.

Тоже самое предупреждение как и для g_ascii_strcasecmp(): Используйте эту функцию только для строк известной кодировки где байты соответствуют ASCII литерам и представляют самих себя.

s1 : строка для сравнения с s2.
s2 : строка для сравнения с s1.
n : количество символов для сравнения.
Возвращает : 0 если строки соответсвуют, отрицательное значение если s1 < s2, или положительное значение если s1 > s2.

g_ascii_strup ()

gchar*      g_ascii_strup                   (const gchar *str,
                                             gssize len);

Конвертирует все символы нижнего регистра ASCII букв в верхний регистр букв ASCII.

str : строка.
len : длина str в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределёная строка, все символы нижнего регистра в str преобразуются в верхний регистр, семантика которой точно соответствует g_ascii_toupper(). (Помните что это отличается от старой g_strup(), которая изменяла строку на месте.)

g_ascii_strdown ()

gchar*      g_ascii_strdown                 (const gchar *str,
                                             gssize len);

Конвертирует все символы ASCII верхнего регистра в символы ASCII нижнего регистра.

str : строка.
len : длина str в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределённая строка, все символы верхнего регистра str конвертированы в символы нижнего регистра, с семантикой точно соответствующей g_ascii_tolower(). (Помните это не похоже на старую g_strdown(), которая изменялся строку на месте.)

g_ascii_tolower ()

gchar       g_ascii_tolower                 (gchar c);

Конвертирует символ в нижний регистр ASCII.

В отличие от стандартной библиотечной функции tolower(), эта принимает только стандартные ASCII буквы и игнорирует локаль, возвращает все не-ASCII символы не изменёнными, даже если они являются буквами нижнего регистра в специальном наборе символов. Также в отличие от стандартной библиотечной функции, эта принимает и возвращает тип char, а не int, поэтому не вызывайте её в EOF и не беспокойтесь о приведении типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ.
Возвращает : результат конвертации c в нижний регистр. Если c не ASCII буква верхнего регистра, c возвращается не изменённым.

g_ascii_toupper ()

gchar       g_ascii_toupper                 (gchar c);

Ковертирует символ в ASCII верхнего регистра.

В отличие от стандартной библиотечной функции toupper(), эта принимает только стандартные ASCII буквы и игнорирует локаль, возвращает все не-ASCII символы без изменений, даже если они являются символами верхнего регистра в специальном наборе символов. Также в отличие от стандартной библиотечной функции, эта принимает и возвращает тип char, а не int, поэтому не вызывайте её в EOF и не беспокойтесь о приведении типа к guchar перед помещением в неё возможно не-ASCII символа.

c : любой символ.
Возвращает : результат конвертации c в верхний регистр. Если c не ASCII буква нижнего регистра, c возвращается без изменений.

g_string_ascii_up ()

GString*    g_string_ascii_up               (GString *string);

Конвертирует все буквы ASCII нижнего регистра в буквы верхнего регистра ASCII.

string : GString
Возвращает : помещённый указатель на string, в которой все символы нижнего регистра конвертированы в верхний регистр на месте, с семантикой которая соответствует g_ascii_toupper.

g_string_ascii_down ()

GString*    g_string_ascii_down             (GString *string);

Конвертирует все буквы верхнего регистра ASCII в нижний регистр букв ASCII.

string : GString
Возвращает : помещённый указатель на string, в которой все символы верхнего регистра конвертированы в нижний регистр на месте, с семантикой соответствующей g_ascii_tolower.

g_strup ()

gchar*      g_strup                         (gchar *string);

Внимание

g_strup устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Эта функция неисправна по причинам обсуждаемым в документации g_strncasecmp() - используйте вместо неё g_ascii_strup() или g_utf8_strup().

Конвертирует строку в верхний регистр.

string : строка для конвертации.
Возвращает : конвертированную строку

g_strdown ()

gchar*      g_strdown                       (gchar *string);

Внимание

g_strdown устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Эта функция полностью неисправна по причинам обсуждаемым в документации g_strncasecmp() - используйте вместо неё g_ascii_strdown() или g_utf8_strdown().

Конвертирует строку в нижний регистр.

string : строка для конвертации.
Возвращает : строка

g_strcasecmp ()

gint        g_strcasecmp                    (const gchar *s1,
                                             const gchar *s2);

Внимание

g_strcasecmp устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Смотрите g_strncasecmp() для обсуждения причины по которой не рекомендуется использовать эту функцию и чем её заменить.

Не чувствительное к регистру сравнение строк, соответствует стандартной функции strcasecmp() на платформах которые поддерживают её.

s1 : строка.
s2 : a строка для сравнения с s1.
Возвращает : 0 если строки соответсвуют, отрицательное значение если s1 < s2, или положительное значение если s1 > s2.

g_strncasecmp ()

gint        g_strncasecmp                   (const gchar *s1,
                                             const gchar *s2,
                                             guint n);

Внимание

g_strncasecmp устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Проблема g_strncasecmp() в том что она вызывает для сравнения toupper()/tolower(). Эти функции являются локаль-специфичными (locale-specific) и оперируют одним байтом. Однако, это не позволяет правильно обрабатывать возможности I18N так как требуются многобайтные символы. Поэтому g_strncasecmp() не работает правильно если ваша строка гарантировано в ASCII, так как это зависит от локали (locale-sensitive), и она неправильно работает если ваша строка локализована, так как она не работает на большинстве кодировок, включая UTF-8, EUC-JP, и т.д..

Пэтому есть две заменяющие функции: g_ascii_strncasecmp(), которая работает только в ASCII и не зависит от локали, а так же g_utf8_casefold(), которая хорошо подходит для сортировки без учета регистра UTF-8.

Сравнение строк без учёта регистра, соответствует стандартной функции strncasecmp() на платформах которые её поддерживают. Она похожа на g_strcasecmp() за исключением того что сравнивает только первые n символов в строках.

s1 : строка.
s2 : a строка для сравнения с s1.
n : максимальное число символов для сравнения.
Возвращает : 0 если строки эквивалентны, отрицательное значение если s1 < s2, или положительное значение если s1 > s2.

g_strreverse ()

gchar*      g_strreverse                    (gchar *string);

Переворачивает строку. Например, g_strreverse ("abcdef") выдаст результат "fedcba".

Помните что g_strreverse() не работает в UTF-8 строках содержащих многобайтные символы. Для этих случаев используйте g_utf8_strreverse().

указатель помещённый как string.
string : строка для переворота.
Возвращает :

g_ascii_strtoll ()

gint64      g_ascii_strtoll                 (const gchar *nptr,
                                             gchar **endptr,
                                             guint base);

Конвертирует строку в значение gint64. Эта функция ведёт себя как стандартная функция strtoll() выполняемая в C локали. Она выполняет это без фактического изменения текущей локали, так как это было бы не потоко-безопасным (thread-safe).

Эта функция обычно используется когда читаются конфигурационные файлы или другой не пользовательский ввод который должен быть независим от локали. Для обработки пользовательского ввода вы должны обычно использовать чувствительную к локали (locale-sensitive) системную функцию strtoll().

Если текущее значение вызвало бы переполнение буфера, возвращается G_MAXINT64 или G_MININT64, а ERANGE сохраняется в errno. Если base вне допустимого диапазона, возвращается ноль, а EINVAL сохраняется в errno. Если преобразование строки не удалось, возвращается ноль, а endptr возвращает nptr (если endptr это не-NULL).

nptr : строка для конвертации в числовое значение.
endptr : если не-NULL, возвращается символ после последнего символа используемого в преобразовании.
base : используется для преобразования, 2..36 или 0
Возвращает : gint64 значение или ноль при ошибке.

Начиная с версии 2.12


g_ascii_strtoull ()

guint64     g_ascii_strtoull                (const gchar *nptr,
                                             gchar **endptr,
                                             guint base);

Конвертирует строку в значение guint64. Эта функция ведёт себя также как стандартная strtoull() выполняющаяся в C локали. Она работает без фактического изменения текущей локали, так как это было бы не потоко-безопасным (thread-safe).

Эта функция обычно используется при чтении конфигурационных файлов или другого не пользовательского ввода который должен быть независимым от локали. Для обработки пользовательского ввода вы должны обычно использовать чувствительную к локали (locale-sensitive) системную функцию strtoull().

Если правильное значение вызывает переполнение буфера, то возвращается G_MAXUINT64, а ERANGE сохраняется в errno. Если base вне допустимого диапазона, возвращается ноль, а EINVAL сохраняется в errno. Если преобразование строки не удалось, возвращается ноль, а endptr возвращает nptr (если endptr не-NULL).

nptr : строка для конвертации to a numeric value.
endptr : если не-NULL, возвращается символ после последнего используемого при конвертации.
base : используется для преобразования, 2..36 или 0
Возвращает : значение guint64 или ноль в error.

Начиная с версии 2.2


G_ASCII_DTOSTR_BUF_SIZE

#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)

Правильный размер буфера для помещения в g_ascii_dtostr(). Этого гарантированно достаточно для всего вывода функции в системах с 64bit IEEE-совместимым doubles.

Обычное использование выглядит так:

  char buf[G_ASCII_DTOSTR_BUF_SIZE];

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


g_ascii_strtod ()

gdouble     g_ascii_strtod                  (const gchar *nptr,
                                             gchar **endptr);

Конвертирует строку в gdouble значение. Эта функция ведёт себя как стандартная функция strtod() работающая в C лосали. Она работает без фактического изменения текущей локали, так как это было бы не потоко-безопасным (thread-safe).

Эта функция обычно используется когда читаются конфигурационные файлы или другой не пользовательский ввод который должен быть не зависим от локали. Для обработки ввода пользователя вы должны обычно использовать чувствительную к локали системную функцию strtod().

Для конвертации из gdouble в строку чувствительным к локали способом, используйте g_ascii_dtostr().

Если правильное значение вызвало бы переполнение буфера, возвращается плюс или минус HUGE_VAL (соответсвенно значению со знаком), а ERANGE сохраняется в errno. Если правильное значение вызвало бы антипереполнение буфера (underflow), возвращается ноль и ERANGE сохраняется в errno.

Эта функция сбрасывает errno перед вызовом strtod() так, чтобы вы могли надёжно обнаружить переполнение или антипереполнение буфера.

nptr : строка для конвертации to a numeric value.
endptr : если не-NULL, возвращает символ после последнего символа используемого в конвертации.
Возвращает : gdouble значение.

g_ascii_dtostr ()

gchar*      g_ascii_dtostr                  (gchar *buffer,
                                             gint buf_len,
                                             gdouble d);

Конвертирует gdouble в строку, используя '.' как десятичную точку.

Эта функция генерирует достаточно точно конвертированную с помощью g_ascii_strtod() строку, получая то же машинное число (machine-number) (на машинах с IEEE совместимым 64bit doubles). Гарантирует что результирующая строка не будет больше чем G_ASCII_DTOSTR_BUF_SIZE байт.

buffer : Буфер для размещения строки результата
buf_len : Размер буфера.
d : gdouble для конвертации
Возвращает : Указатель на буфер с конвертированной строкой.

g_ascii_formatd ()

gchar*      g_ascii_formatd                 (gchar *buffer,
                                             gint buf_len,
                                             const gchar *format,
                                             gdouble d);

Конвертирует gdouble в строку, используя '.' как десятичную точку. Для форматирования числа вы помещаете строку формата в стиле printf(). Допускаются спецификаторы преобразования 'e', 'E', 'f', 'F', 'g' и 'G'.

Если вы просто хотите преобразовать в последовательную форму значение в строке, используйте g_ascii_dtostr().

buffer : Буфер для размещения строки результата
buf_len : Размер буфера.
format : Формат в стиле printf() используемый для конвертации.
d : gdouble для конвертации
Возвращает : Указатель на буфер с конвертированной строкой.

g_strtod ()

gdouble     g_strtod                        (const gchar *nptr,
                                             gchar **endptr);

Конвертирует строку в gdouble значение. Она вызывает стандартную функцию strtod() для обработки конвертации, но если строка конвертирована не полностью она пытается конвертировать снова с помощью g_ascii_strtod() и возвращает лучшее соответствие.

Эта функция должна использоваться редко. В обычных ситуациях когда читаются числа не для применения человеком используется g_ascii_strtod(). Вы должны её использовать только когда знаете что ожидается оба формата чисел и в локали и в C формате. Убедитесь что вы не поместили строки такие как разделённые запятыми списки значений, так как запятая может интерпретироваться как десятичная точка в некоторых локалях, вызывая неожиданный результат.

nptr : строка для конвертации в числовое значение.
endptr : Если не-NULL, возвращается символ после последнего символа используемого в конвертации.
Возвращает : gdouble значение.

g_strchug ()

gchar*      g_strchug                       (gchar *string);

Удаляет все символы табуляций (whitespace) из строки, но перемещает символы вперёд.

Эта функция не распределяет и не перераспределяет никакую память; она изменяет string на месте. Указатель на string возвращается чтобы позволить вложенные функции.

Также смотрите g_strchomp() и g_strstrip().

string : строка из которой удаляются табуляции.
Возвращает : string.

g_strchomp ()

gchar*      g_strchomp                      (gchar *string);

Удаляет замыкающие табуляции из строки.

Эта функция не распределяет и не перераспределяет никакую память; она изменяет string на месте. Указатель на string возвращается чтобы позволить вложенные функции.

Также смотрите g_strchug() и g_strstrip().

string : строка to remove the trailing whitespace from.
Возвращает : string.

g_strstrip()

#define     g_strstrip( string )

Удаляет начальные и завершающие пробелы (whitespace) из строки. Смотрите g_strchomp() и g_strchug().

string : строка из которой удаляются начальные и завершающие пробелы (whitespace).

g_strdelimit ()

gchar*      g_strdelimit                    (gchar *string,
                                             const gchar *delimiters,
                                             gchar new_delimiter);

Конвертирует любые разделительные символы (delimiter characters) в string в new_delimiter. Любые найденные в string символы delimiters изменяются на new_delimiter. Изменяет строку string на месте и возвращает непосредственно string, а не копию. Возвращаемое значение позволяет вложение, такое как g_ascii_strup (g_strdelimit (str, "abc", '?')).

string : строка для конвертации.
delimiters : строка содержащая текущие разделители, или NULL для использования стандартных разделителей определённых в G_STR_DELIMITERS.
new_delimiter : новые разделительные символы.
Возвращает : string.

G_STR_DELIMITERS

#define	 G_STR_DELIMITERS	"_-|> <."

Стандартные разделительные символы используемые в g_strdelimit().


g_strescape ()

gchar*      g_strescape                     (const gchar *source,
                                             const gchar *exceptions);

Выводит специальные символы '\b', '\f', '\n', '\r', '\t', '\' и '"' в строке source и вставляет перед ними '\'. Дополнительно все символы в диапазоне 0x01-0x1F (все ниже SPACE) м в диапазоне 0x7F-0xFF (все не-ASCII символы) заменяются с помощью '\' сопровождаемого их восьмеричным представлением. Символы поставляемые в exceptions не выводятся.

g_strcompress() выполняет обратную конвертацию.

source : строка для вывода.
exceptions : строка of characters not to escape in source.
Возвращает : вновь распределённая копия source с определёнными символами вывода. Смотрите выше.

g_strcompress ()

gchar*      g_strcompress                   (const gchar *source);

Заменяет все escape-символы их однобайтными эквивалентами. Вы полняет обратную конвертацию для g_strescape().

source : строка для сжатия.
Возвращает : вновь распределённая копия source в которой все escape-символы сжаты.

g_strcanon ()

gchar*      g_strcanon                      (gchar *string,
                                             const gchar *valid_chars,
                                             gchar substitutor);

Каждый символ в string, если символ не valid_chars, заменяет символом substitutor. Изменяет строку string на месте и возвращает непосредственно string, а не копию. Возвращаемое значение допускает вложенность, такую как g_ascii_strup (g_strcanon (str, "abc", '?')).

string : nul-завершённый массив байт.
valid_chars : байты разрешённые в string.
substitutor : символ заменяющий запрещённые байты.
Возвращает : string.

g_strsplit ()

gchar**     g_strsplit                      (const gchar *string,
                                             const gchar *delimiter,
                                             gint max_tokens);

Разбивает строку на максимум max_tokens частей, используя разделитель delimiter. Если max_tokens достигнут, остаток строки string прикрепляется к последней лексеме.

Как специальный случай, результатом разбиения пустой строки "" является пустой вектор, а не вектор содержащий единственную строку. Причиной такого специального случая является то, что обычно представление пустого вектора полезнее чем обработка пустых элементов. Если вам нужно представить пустые элементы, вы должны проверить пустую строку перед вызовом g_strsplit().

string : строка для разбиения.
delimiter : строка определяющая места разбиения строки. Разделитель не включается ни в одну из результирующих строк, пока не достигнут max_tokens.
max_tokens : максимальное число частей для разбиения string. Если меньше чем 1, строка разбивается полностью.
Возвращает : вновь распределённый NULL-завершённый массив строк. Используйте g_strfreev() для его освобождения.

g_strsplit_set ()

gchar**     g_strsplit_set                  (const gchar *string,
                                             const gchar *delimiters,
                                             gint max_tokens);

Разбивает string на множество лексем не содержащих любой из символов в delimiter. Лексемы это (возможно пустые) длинные строки которые не содержат любой из символов находящихся в delimiters. Если достигнут max_tokens, остаток предложения прикрепляется к последней лексеме.

Например результатом g_strsplit_set ("abc:def/ghi", ":/", -1) будет NULL-завершённый вектор содержащий дерево строк "abc", "def", и "ghi".

Результатом g_strsplit_set (":def/ghi:", ":/", -1) NULL-завершённый вектор содержащий четыре строки "", "def", "ghi", и "".

Как специальный случай, результатом разбиения пустой строки "" является пустой вектор, а не вектор содержащий единственную строку. Причиной такого специального случая является то, что обычно представление пустого вектора полезнее чем обработка пустых элементов. Если вам нужно представить пустые элементы, вы должны проверить пустую строку перед вызовом g_strsplit().

Помните что эта функция работает с байтами а не с символами, поэтому она не может использоваться для разграничения UTF-8 строк чем нибудь кроме ASCII символов.

string : строка для разбиения на лексемы
delimiters : nul-завершённая строка содержащая байты которые используются для разбиения строки.
max_tokens : максимальное число лексем для разбиения string. Если меньше 1, строка разбивается полностью
Возвращает : вновь распределённый NULL-завершённый массив строк. Используйте g_strfreev() для его освобождения.

Начиная с версии 2.4


g_strfreev ()

void        g_strfreev                      (gchar **str_array);

Освобождает NULL-завершённый массив строк, и непосредственно массив. Если вызвана для значения NULL, g_strfreev() просто возвращается.

str_array : NULL-завершённый массив строк для освобождения.

g_strconcat ()

gchar*      g_strconcat                     (const gchar *string1,
                                             ...);

Соединяет все полученные строки в одну длинную строку. Возвращаемая строка должна быть освобождена когда больше не нужна.

Внимание

Переменный список параметров must должен завершаться NULL. Если вы забудете о NULL, g_strconcat() добавит к ваше строке произвольный участок памяти.

string1 : Первая строка для добавления, которая не должна быть NULL.
... : NULL-завершённый список строк для добавления к строке.
Возвращает : вновь распределённая строка содержащая все строки аргументов.

g_strjoin ()

gchar*      g_strjoin                       (const gchar *separator,
                                             ...);

Объединяет множество строк вместе в форме одной длинной строки, с необязательным разделителем separator вставляемым между ними.

separator : строка для вставки между каждой строкой, или NULL.
... : NULL-завершённый список строк в объединении.
Возвращает : вновь распределённая строка содержащая все строки объединённые вместе, с separator между ними.

g_strjoinv ()

gchar*      g_strjoinv                      (const gchar *separator,
                                             gchar **str_array);

Объединяет множество строк вместе в форме одной длинной строки, с необязательным separator вставляемым между каждой из них.

separator : строка вставляемая между каждой из строк, или NULL.
str_array : NULL-завершённый массив строк для объединения.
Возвращает : вновь распределённая строка содержащая все строки объединённые вместе, с separator между ними.

g_strv_length ()

guint       g_strv_length                   (gchar **str_array);

Возвращает длину полученного NULL-завершённого массива строк str_array.

str_array : NULL-завершённый массив строк.
Возвращает : длина str_array.

Начиная с версии 2.6


g_strerror ()

const gchar* g_strerror                     (gint errnum);

Возвращает строку соответствующую данному коду ошибки (error code), например "no such process". Эта функция включена так как не все платформы поддерживают функцию strerror().

errnum : номер системной ошибки. Смотрите стандарт C errno документацию.
Возвращает : строка описывающая кодовую ошибку. Если данный код ошибки не известен, возвращается "unknown error (<code>)". Строка может использоваться только до следующего вызова g_strerror().

g_strsignal ()

const gchar* g_strsignal                    (gint signum);

Возвращает строку описывающую полученный сигнал, например "Segmentation fault". Эта функция включена так как не на всех платформах поддерживается функция strsignal().

signum : номер сигнала. Смотрите signal документацию.
Возвращает : строка описывающая сигнал. Если сигнал не известен, возвращается "unknown signal (<signum>)". Строка может использоваться только до следующего вызова g_strsignal().

Strings

Strings — Текстовые буферы которые автоматически увеличиваются при добавлении текста.

Краткое описание


#include <glib.h>


            GString;
GString*    g_string_new                    (const gchar *init);
GString*    g_string_new_len                (const gchar *init,
                                             gssize len);
GString*    g_string_sized_new              (gsize dfl_size);
GString*    g_string_assign                 (GString *string,
                                             const gchar *rval);
#define     g_string_sprintf
#define     g_string_sprintfa
void        g_string_printf                 (GString *string,
                                             const gchar *format,
                                             ...);
void        g_string_append_printf          (GString *string,
                                             const gchar *format,
                                             ...);
GString*    g_string_append                 (GString *string,
                                             const gchar *val);
GString*    g_string_append_c               (GString *string,
                                             gchar c);
GString*    g_string_append_unichar         (GString *string,
                                             gunichar wc);
GString*    g_string_append_len             (GString *string,
                                             const gchar *val,
                                             gssize len);
GString*    g_string_prepend                (GString *string,
                                             const gchar *val);
GString*    g_string_prepend_c              (GString *string,
                                             gchar c);
GString*    g_string_prepend_unichar        (GString *string,
                                             gunichar wc);
GString*    g_string_prepend_len            (GString *string,
                                             const gchar *val,
                                             gssize len);
GString*    g_string_insert                 (GString *string,
                                             gssize pos,
                                             const gchar *val);
GString*    g_string_insert_c               (GString *string,
                                             gssize pos,
                                             gchar c);
GString*    g_string_insert_unichar         (GString *string,
                                             gssize pos,
                                             gunichar wc);
GString*    g_string_insert_len             (GString *string,
                                             gssize pos,
                                             const gchar *val,
                                             gssize len);
GString*    g_string_erase                  (GString *string,
                                             gssize pos,
                                             gssize len);
GString*    g_string_truncate               (GString *string,
                                             gsize len);
GString*    g_string_set_size               (GString *string,
                                             gsize len);
gchar*      g_string_free                   (GString *string,
                                             gboolean free_segment);

GString*    g_string_up                     (GString *string);
GString*    g_string_down                   (GString *string);

guint       g_string_hash                   (const GString *str);
gboolean    g_string_equal                  (const GString *v,
                                             const GString *v2);

Описание

GString подобна стандартной C string, за исключением того что она автоматически увеличивается при добавлении или вставке текста. Также, она хранит длину строки, поэтому может использоваться для двоичных данных с включением нулевых байт.

Детали

GString

typedef struct {
  gchar  *str;
  gsize len;    
  gsize allocated_len;
} GString;

Структура GString содержит общедоступные поля GString. Поле str указывает на символьные данные. Он может меняться при добавлении текста. Поле len содержит длину строки, не включая завершающий нулевой байт.

Поле str nul-завершённое и поэтому может быть использовано как обычная C string. Но она может перемещаться когда в строку добавляется или вставляется текст.


g_string_new ()

GString*    g_string_new                    (const gchar *init);

Создаёт новую GString, инициализируя полученной строкой.

init : инициализируемый текст для копирования в строку.
Возвращает : новая GString.

g_string_new_len ()

GString*    g_string_new_len                (const gchar *init,
                                             gssize len);

Создаёт новую GString с длиной len байт буфера init. Поскольку длина обеспечена, init не должен быть nul-завершённым и может содержать встроенные nul байты.

init : начальное содержимое строки.
len : длина init для использования.
Возвращает : новая GString.

g_string_sized_new ()

GString*    g_string_sized_new              (gsize dfl_size);

Создаёт новую GString, с достаточным пространством для dfl_size байт. Это полезно если вы добавляете много текста в строку и не хотите перераспределять её слишком часто.

dfl_size : размер свободного пространства которое содержит распределённая строка.
Возвращает : новая GString.

g_string_assign ()

GString*    g_string_assign                 (GString *string,
                                             const gchar *rval);

Копирует байты из строки в GString, уничтожает любое предыдущее содержимое. Она скорее похожа на стандартную функцию strcpy(), за исключением того, что вам не нужно беспокоится о наличии достаточного пространства для копируемой строки.

string : целевая GString. Её содержимое будет уничтожено.
rval : строка копируемая в string
Возвращает : целевая GString.

g_string_sprintf

#define     g_string_sprintf

Внимание

g_string_sprintf устарела и не должна использоваться во вновь создаваемом коде. Эта функция переименована в g_string_printf().

Записывает форматированную строку в GString. Подобна стандартной функции sprintf(), за исключением того, что буфер GString автоматически расширяется для вмещения результата. Предыдущее содержимое GString уничтожается.


g_string_sprintfa

#define     g_string_sprintfa

Внимание

g_string_sprintfa устарела и не должна использоваться во вновь создаваемом коде. This function has been renamed to g_string_append_printf().

Добавляет форматированную строку в конец GString. Эта функция подобна g_string_sprintf(), за исключением того, что текст добавляется к GString.


g_string_printf ()

void        g_string_printf                 (GString *string,
                                             const gchar *format,
                                             ...);

Записывает форматированную строку в GString. Это подобно стандартной функции sprintf(), за исключением того, что буфер GString автоматически расширяется для вмещения результата. Предыдущее содержимое GString уничтожается.

string : GString.
format : строка формата. Смотрите документацию printf().
... : параметры вставляемые в форматируемую строку.

g_string_append_printf ()

void        g_string_append_printf          (GString *string,
                                             const gchar *format,
                                             ...);

Добавляет форматированную строку в конец GString. Эта функция подобна g_string_printf(), за исключением того, что текст добавляется к GString.

string : GString.
format : строка формата. Смотрите документацию printf().
... : параметры вставляемые в форматируемую строку.

g_string_append ()

GString*    g_string_append                 (GString *string,
                                             const gchar *val);

Добавляет строку в конец GString, расширяя её если необходимо.

string : GString.
val : строка добавляемая в конец GString.
Возвращает : GString.

g_string_append_c ()

GString*    g_string_append_c               (GString *string,
                                             gchar c);

Добавляет бай в конец GString, расширяя её если необходимо.

string : GString.
c : байт для добавления в конец GString.
Возвращает : GString.

g_string_append_unichar ()

GString*    g_string_append_unichar         (GString *string,
                                             gunichar wc);

Конвертирует Unicode символ в UTF-8, и добавляет его в строку.

string : GString
wc : Unicode символ
Возвращает : string

g_string_append_len ()

GString*    g_string_append_len             (GString *string,
                                             const gchar *val,
                                             gssize len);

Добавляет len байт val в string. Поскольку len обеспечена, val может содержать встроенные nuls и не должна быть nul-завершённой.

string : GString.
val : байты для добавления.
len : количество байт val для использования.
Возвращает : GString.

g_string_prepend ()

GString*    g_string_prepend                (GString *string,
                                             const gchar *val);

Добавляет строку в начало GString, расширяя её если необходимо.

string : GString.
val : строка для добавления в начало GString.
Возвращает : GString.

g_string_prepend_c ()

GString*    g_string_prepend_c              (GString *string,
                                             gchar c);

Добавляет байт в начало GString, расширяя её если необходимо.

string : GString.
c : байт добавляемый в начало GString.
Возвращает : GString.

g_string_prepend_unichar ()

GString*    g_string_prepend_unichar        (GString *string,
                                             gunichar wc);

Конвертирует Unicode символ в UTF-8, и добавляет его в начало строки.

string : GString.
wc : Unicode символ.
Возвращает : string.

g_string_prepend_len ()

GString*    g_string_prepend_len            (GString *string,
                                             const gchar *val,
                                             gssize len);

Добавляет len байт val в string. Поскольку len обеспечена, val может содержать встроенные nuls и не должна быть nul-завершённой.

string : GString.
val : байты для вставки в начало.
len : количество байт в val для вставки.
Возвращает : GString в которую помещён байт.

g_string_insert ()

GString*    g_string_insert                 (GString *string,
                                             gssize pos,
                                             const gchar *val);

Вставляет копию строки в GString, расширяя её если необходимо.

string : GString.
pos : позиция вставляемой копии строки.
val : вставляемая строка.
Возвращает : GString.

g_string_insert_c ()

GString*    g_string_insert_c               (GString *string,
                                             gssize pos,
                                             gchar c);

Вставляет байт в GString, расширяя её если необходимо.

string : GString.
pos : позиция вставляемого байта.
c : вставляемый байт.
Возвращает : GString.

g_string_insert_unichar ()

GString*    g_string_insert_unichar         (GString *string,
                                             gssize pos,
                                             gunichar wc);

Конвертирует Unicode символ в UTF-8, и вставляет его в строку в указанную позицию.

string : GString
pos : позиция в которую вставляется символ, или -1 для добавления в конец строки.
wc : Unicode символ
Возвращает : string

g_string_insert_len ()

GString*    g_string_insert_len             (GString *string,
                                             gssize pos,
                                             const gchar *val,
                                             gssize len);

Вставляет len байт val в string в позицию pos. Поскольку len обеспечена, val может содержать встроенные nuls и не должна быть nul-завершённой. Если pos это -1, байты вставляются в конец строки.

string : GString.
pos : позиция в string куда происходит вставка, или -1 если в конец.
val : вставляемые байты.
len : количество байт val для вставки.
Возвращает : GString.

g_string_erase ()

GString*    g_string_erase                  (GString *string,
                                             gssize pos,
                                             gssize len);

Удаляет len байт из GString, сначала позиции pos. Остальная часть GString смещается вниз для заполнения пустоты.

string : GString.
pos : позоция контекста для удаления.
len : количество байт для удаления, или -1 для удаления всех последующих байт.
Возвращает : GString.

g_string_truncate ()

GString*    g_string_truncate               (GString *string,
                                             gsize len);

Вырезает окончание GString, оставляя первые len байт.

string : GString.
len : новый размер GString.
Возвращает : GString.

g_string_set_size ()

GString*    g_string_set_size               (GString *string,
                                             gsize len);

Устанавливает длину GString. Если длина меньше чем текущая, строка будет обрезана. Если длина больше чем текущая, содержимое вновь добавленного пространства неопределено. (Однако, как всегда, string->str[string->len] будет nul байтом.)

string : GString
len : новая длина
Возвращает : string

g_string_free ()

gchar*      g_string_free                   (GString *string,
                                             gboolean free_segment);

Освобождает память распределённую для GString. Если free_segment это TRUE она так же освобождает символьные данные.

string : GString.
free_segment : если TRUE фактические символьные данные так же освобождаются.
Возвращает : символьные данные string (например NULL если free_segment это TRUE)

g_string_up ()

GString*    g_string_up                     (GString *string);

Внимание

g_string_up устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Эта функция использует locale-специфичную функцию toupper(), которая почти никогда не является правильным выбором. Используйте g_string_ascii_up() или g_utf8_strup() вместо неё.

Конвертирует GString в верхний регистр.

string : GString
Возвращает : GString

g_string_down ()

GString*    g_string_down                   (GString *string);

Внимание

g_string_down устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Эта функция использует locale-специфичную функцию tolower(), которая почти никогда не является правильным выбором. Используйте g_string_ascii_down() или g_utf8_strdown() вместо неё.

Конвертирует GString в нижний регистр.

string : GString
Возвращает : GString.

g_string_hash ()

guint       g_string_hash                   (const GString *str);

Создаёт новый хеш код для str; для использования с GHashTable.

str : строка для хеширования.
Возвращает : хеш код для str.

g_string_equal ()

gboolean    g_string_equal                  (const GString *v,
                                             const GString *v2);

Сравнивает две строки на эквивалентность, возвращает TRUE если они равны. Для использования с GHashTable.

v : GString.
v2 : другая GString.
Возвращает : TRUE если эти строки одинаковой длины и содержат одинаковые байты.

Основной цикл событий

The Main Event Loop — Управление всеми доступными источниками событий.

Краткое описание


#include <glib.h>


            GMainLoop;
GMainLoop*  g_main_loop_new                 (GMainContext *context,
                                             gboolean is_running);
GMainLoop*  g_main_loop_ref                 (GMainLoop *loop);
void        g_main_loop_unref               (GMainLoop *loop);
void        g_main_loop_run                 (GMainLoop *loop);
void        g_main_loop_quit                (GMainLoop *loop);
gboolean    g_main_loop_is_running          (GMainLoop *loop);
GMainContext* g_main_loop_get_context       (GMainLoop *loop);
#define     g_main_new                      (is_running)
#define     g_main_destroy                  (loop)
#define     g_main_run                      (loop)
#define     g_main_quit                     (loop)
#define     g_main_is_running               (loop)

#define     G_PRIORITY_HIGH
#define     G_PRIORITY_DEFAULT
#define     G_PRIORITY_HIGH_IDLE
#define     G_PRIORITY_DEFAULT_IDLE
#define     G_PRIORITY_LOW

            GMainContext;
GMainContext* g_main_context_new            (void);
GMainContext* g_main_context_ref            (GMainContext *context);
void        g_main_context_unref            (GMainContext *context);
GMainContext* g_main_context_default        (void);
gboolean    g_main_context_iteration        (GMainContext *context,
                                             gboolean may_block);
#define     g_main_iteration                (may_block)
gboolean    g_main_context_pending          (GMainContext *context);
#define     g_main_pending                  ()
GSource*    g_main_context_find_source_by_id
                                            (GMainContext *context,
                                             guint source_id);
GSource*    g_main_context_find_source_by_user_data
                                            (GMainContext *context,
                                             gpointer user_data);
GSource*    g_main_context_find_source_by_funcs_user_data
                                            (GMainContext *context,
                                             GSourceFuncs *funcs,
                                             gpointer user_data);
void        g_main_context_wakeup           (GMainContext *context);
gboolean    g_main_context_acquire          (GMainContext *context);
void        g_main_context_release          (GMainContext *context);
gboolean    g_main_context_is_owner         (GMainContext *context);
gboolean    g_main_context_wait             (GMainContext *context,
                                             GCond *cond,
                                             GMutex *mutex);
gboolean    g_main_context_prepare          (GMainContext *context,
                                             gint *priority);
gint        g_main_context_query            (GMainContext *context,
                                             gint max_priority,
                                             gint *timeout_,
                                             GPollFD *fds,
                                             gint n_fds);
gint        g_main_context_check            (GMainContext *context,
                                             gint max_priority,
                                             GPollFD *fds,
                                             gint n_fds);
void        g_main_context_dispatch         (GMainContext *context);
void        g_main_context_set_poll_func    (GMainContext *context,
                                             GPollFunc func);
GPollFunc   g_main_context_get_poll_func    (GMainContext *context);
gint        (*GPollFunc)                    (GPollFD *ufds,
                                             guint nfsd,
                                             gint timeout_);
void        g_main_context_add_poll         (GMainContext *context,
                                             GPollFD *fd,
                                             gint priority);
void        g_main_context_remove_poll      (GMainContext *context,
                                             GPollFD *fd);
gint        g_main_depth                    (void);
GSource*    g_main_current_source           (void);
#define     g_main_set_poll_func            (func)

GSource*    g_timeout_source_new            (guint interval);
GSource*    g_timeout_source_new_seconds    (guint interval);
guint       g_timeout_add                   (guint interval,
                                             GSourceFunc function,
                                             gpointer data);
guint       g_timeout_add_full              (gint priority,
                                             guint interval,
                                             GSourceFunc function,
                                             gpointer data,
                                             GDestroyNotify notify);
guint       g_timeout_add_seconds           (guint interval,
                                             GSourceFunc function,
                                             gpointer data);

GSource*    g_idle_source_new               (void);
guint       g_idle_add                      (GSourceFunc function,
                                             gpointer data);
guint       g_idle_add_full                 (gint priority,
                                             GSourceFunc function,
                                             gpointer data,
                                             GDestroyNotify notify);
gboolean    g_idle_remove_by_data           (gpointer data);

typedef     GPid;
void        (*GChildWatchFunc)              (GPid pid,
                                             gint status,
                                             gpointer data);
GSource*    g_child_watch_source_new        (GPid pid);
guint       g_child_watch_add               (GPid pid,
                                             GChildWatchFunc function,
                                             gpointer data);
guint       g_child_watch_add_full          (gint priority,
                                             GPid pid,
                                             GChildWatchFunc function,
                                             gpointer data,
                                             GDestroyNotify notify);

            GPollFD;

            GSource;
void        (*GSourceDummyMarshal)          (void);
            GSourceFuncs;
            GSourceCallbackFuncs;
GSource*    g_source_new                    (GSourceFuncs *source_funcs,
                                             guint struct_size);
GSource*    g_source_ref                    (GSource *source);
void        g_source_unref                  (GSource *source);
void        g_source_set_funcs              (GSource *source,
                                             GSourceFuncs *funcs);
guint       g_source_attach                 (GSource *source,
                                             GMainContext *context);
void        g_source_destroy                (GSource *source);
gboolean    g_source_is_destroyed           (GSource *source);
void        g_source_set_priority           (GSource *source,
                                             gint priority);
gint        g_source_get_priority           (GSource *source);
void        g_source_set_can_recurse        (GSource *source,
                                             gboolean can_recurse);
gboolean    g_source_get_can_recurse        (GSource *source);
guint       g_source_get_id                 (GSource *source);
GMainContext* g_source_get_context          (GSource *source);
void        g_source_set_callback           (GSource *source,
                                             GSourceFunc func,
                                             gpointer data,
                                             GDestroyNotify notify);
gboolean    (*GSourceFunc)                  (gpointer data);
void        g_source_set_callback_indirect  (GSource *source,
                                             gpointer callback_data,
                                             GSourceCallbackFuncs *callback_funcs);
void        g_source_add_poll               (GSource *source,
                                             GPollFD *fd);
void        g_source_remove_poll            (GSource *source,
                                             GPollFD *fd);
void        g_source_get_current_time       (GSource *source,
                                             GTimeVal *timeval);
gboolean    g_source_remove                 (guint tag);
gboolean    g_source_remove_by_funcs_user_data
                                            (GSourceFuncs *funcs,
                                             gpointer user_data);
gboolean    g_source_remove_by_user_data    (gpointer user_data);

Описание

Основной цикл событий управляет всеми возможными источниками событий для GLib и GTK+ приложений. Эти события могут исходить из любого числа различных типов источников таких как файловые дескрипторы (простые файлы, каналы или сокеты) и таймауты. Новые типы источников событий также могут быть добавлены используя g_source_attach().

Чтобы разрешить обработку множества независимых наборов источников в различных потоках (threads), каждый источник ассоциируется с GMainContext. GMainContext может выполняться только в единственном потоке, но источники могут добавляться в него и удаляться из него из других потоков.

Каждому источнику события назначается приоритет. Приоритет по умолчанию, G_PRIORITY_DEFAULT, равен 0. Значения меньше чем 0 обозначают более высокие приоритеты. Значения больше чем 0 обозначают более низкие приоритеты. События из источников с высоким приоритетом всегда выполняются перед событиями из источников с более низким приоритетом.

Бездействующие (Idle) функции могут быть также добавлены с присвоением приоритета. Они выполняются всякий раз когда события с более высоким приоритетом не готовы к выполнению.

Тип данных GMainLoop представляет основной цикл события. GMainLoop создаётся с помощью g_main_loop_new(). После добавления исходных источников событий, вызывается g_main_loop_run(). Это непрерывно проверяет новые события из каждого источника событий и отправляет их на обработку. Наконец, обработка события из одного из источников приводит к вызову g_main_loop_quit() для выхода из основного цикла, а g_main_loop_run() завершает работу.

Это позволяет создавать новые экземпляры GMainLoop рекурсивно. Часто используется в GTK+ приложениях при показе модальных диалоговых окон. Помните что источники события связаны со специфичным GMainContext, и будут проверены и посланы для всех основных циклов связанных с этим GMainContext.

GTK+ содержит оболочки некоторых из этих функций, например gtk_main(), gtk_main_quit() и gtk_events_pending().

Создание новых типов источников

Одна из необычных особенностей функциональности основного цикла GTK+ в том, что могут создаваться новые типы источников событий в дополнение к встроенным типам источников событий. Новый тип источника событий используется для обработки GDK событий. Новый тип источника создаётся с помощью наследования из GSource структуры. Наследуемый тип источника представляется структурой которая имеет в качестве первого элемента структуру GSource, а также другие элементы специфичные для нового типа источника. Для создания экземпляра нового типа источника, вызывается g_source_new() помещая размер наследуемой структуры и таблицы функций. Эти GSourceFuncs определяют поведение нового типа источника.

Новые типы источников в основном взаимодействуют с основным контекстом двумя способами. Они подготавливают функцию в GSourceFuncs способную установить тайм аут для определения максимального промежутка времени бездействия основного цикла перед повторной проверкой. Кроме того, или в дополнение, источник может добавить файловый дескриптор для установки проверки основного контекста используя g_source_add_poll().


Настройка основной итерации цикла

Одиночная итерация GMainContext может быть выполнена с помощью g_main_context_iteration(). В некоторых случаях, вместо этого желательно более точное управление деталями работы основного цикла, например объединяя GMainLoop с внешним основным циклом. В этом случае, вы можете вызвать непосредственно составные функции g_main_context_iteration(). Этими функциями являются g_main_context_prepare(), g_main_context_query(), g_main_context_check() и g_main_context_dispatch().

Операции этих функций могут быть лучше рассмотрены в терминах диаграммы состояния, как показано на Рисунке 1, “Состояния основного контекста”.

Рисунок 1. Состояния основного контекста

States of a Main Context

Детали

GMainLoop

typedef struct _GMainLoop GMainLoop;

Структура GMainLoop непрозрачный тип данных представляющий основной цикл события GLib или GTK+ приложений.


g_main_loop_new ()

GMainLoop*  g_main_loop_new                 (GMainContext *context,
                                             gboolean is_running);

Создаёт новую структуру GMainLoop.

context : GMainContext (если NULL, используется контекст по умолчанию).
is_running : устанавливается в TRUE указывая на то, что цикл выполняется. Это не очень важно с момента вызова g_main_loop_run() который установит это значение в TRUE в любом случае.
Возвращает : новый GMainLoop.

g_main_loop_ref ()

GMainLoop*  g_main_loop_ref                 (GMainLoop *loop);

Увеличивает счёт ссылок объекта GMainLoop на одну.

loop : GMainLoop
Возвращает : loop

g_main_loop_unref ()

void        g_main_loop_unref               (GMainLoop *loop);

Уменьшает количество ссылок на объект GMainLoop на одну. Если результат ноль, освобождает цикл и всю связанную с ним память.

loop : GMainLoop

g_main_loop_run ()

void        g_main_loop_run                 (GMainLoop *loop);

Выполняет основной цикл до тех пор пока не вызвана g_main_loop_quit(). Если вызвана для потока (thread) GMainContext циклов, то выполняет событие из цикла, или просто ждёт.

loop : GMainLoop

g_main_loop_quit ()

void        g_main_loop_quit                (GMainLoop *loop);

Останавливает выполнение GMainLoop. Любые вызовы g_main_loop_run() для цикла будут возвращены.

loop : GMainLoop

g_main_loop_is_running ()

gboolean    g_main_loop_is_running          (GMainLoop *loop);

Выясняет выполняется ли в данный момент основной цикл через g_main_loop_run().

loop : GMainLoop.
Возвращает : TRUE если основной цикл в текущий момент выполняется.

g_main_loop_get_context ()

GMainContext* g_main_loop_get_context       (GMainLoop *loop);

Возвращает GMainContext цикла (loop).

loop : GMainLoop.
Возвращает : GMainContext цикла loop

g_main_new()

#define     g_main_new(is_running)

Внимание

g_main_new устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_new() вместо неё.

Создаёт новый GMainLoop для основного цикла по умолчанию.

is_running : устанавливается в значение TRUE указывая что основной цикл выполняется. Это не очень полезно с момента вызова g_main_run() которая установит TRUE в любом случае.
Возвращает : новый GMainLoop.

g_main_destroy()

#define     g_main_destroy(loop)

Внимание

g_main_destroy устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_unref() вместо неё.

Освобождает память распределённую для GMainLoop.

loop : GMainLoop.

g_main_run()

#define     g_main_run(loop)

Внимание

g_main_run устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_run() вместо неё.

Выполняет основной цикл до остановки.

loop : GMainLoop.

g_main_quit()

#define     g_main_quit(loop)

Внимание

g_main_quit устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_quit() вместо неё.

Останавливает GMainLoop. Если g_main_run() был вызван для выполнения GMainLoop, он будет возвращен.

loop : GMainLoop.

g_main_is_running()

#define     g_main_is_running(loop)

Внимание

g_main_is_running устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_is_running() вместо неё.

Проверяет выполняется ли основной цикл.

loop : GMainLoop.
Возвращает : TRUE если основной цикл выполняется.

G_PRIORITY_HIGH

#define G_PRIORITY_HIGH            -100

Используется для повышения приоритета источников событий. Не используется внутри GLib или GTK+.


G_PRIORITY_DEFAULT

#define G_PRIORITY_DEFAULT          0

Используется для приоритета по умолчанию для источника события. В GLib этот приоритет используется когда добавляется функция-таймаут с помощью g_timeout_add(). В GDK этот приоритет используется для событий из X server.


G_PRIORITY_HIGH_IDLE

#define G_PRIORITY_HIGH_IDLE        100

Используется для повышения приоритета idle функций. GTK+ используется G_PRIORITY_HIGH_IDLE + 10 для операций изменения размера, а G_PRIORITY_HIGH_IDLE + 20 операций перерисовки. (Это выполняется для гарантии что любое изменение размера обрабатывается перед любой перерисовкой, чтобы виджеты не перерисовывались лишний раз.)


G_PRIORITY_DEFAULT_IDLE

#define G_PRIORITY_DEFAULT_IDLE     200

Используется для приоритета idle функций по умолчанию. В GLib этот приоритет используется когда добавляются idle функции с помощью g_idle_add().


G_PRIORITY_LOW

#define G_PRIORITY_LOW	            300

Этот очень медленный приоритет используется для фоновых задач. Не используется внутри GLib или GTK+.


GMainContext

typedef struct _GMainContext GMainContext;

Структура GMainContext это непрозрачный тип данных представляющий наборы источников для обработки в основном цикле.


g_main_context_new ()

GMainContext* g_main_context_new            (void);

Создаёт новую GMainContext структуру.

Возвращает : новая GMainContext

g_main_context_ref ()

GMainContext* g_main_context_ref            (GMainContext *context);

Увеличивает число ссылок на GMainContext объект на одну.

context : GMainContext
Возвращает : помещённый context (Начиная с версии 2.6)

g_main_context_unref ()

void        g_main_context_unref            (GMainContext *context);

Уменьшает количество ссылок на GMainContext объект на одну. Если результат ноль, освобождает контекст и всю связанную с ним память.

context : GMainContext

g_main_context_default ()

GMainContext* g_main_context_default        (void);

Возвращает основной контекст по умолчанию. Основной контекст используется для функции основного цикла, когда основной цикл явно не определён.

Возвращает : основной контекст по умолчанию.

g_main_context_iteration ()

gboolean    g_main_context_iteration        (GMainContext *context,
                                             gboolean may_block);

Выполняет единственную итерацию для данного основного цикла. Это включает проверку готовы ли любые источники событий к обработке, если нет готовых источников событий и may_block равен TRUE, ждёт подготовки источника, затем отсылает самый высокий приоритет источнику событий который уже готов. Помните, что даже когда may_block равен TRUE, фукция g_main_context_iteration() всё же может вернуть FALSE, так как ожидание может быть прервано не только когда будет готов источник событий, но и по другим причинам.

context : GMainContext (если NULL, используется контекст по умолчанию)
may_block : можно ли заблокировать вызов.
Возвращает : TRUE если события были отправлены.

g_main_iteration()

#define     g_main_iteration(may_block)

Внимание

g_main_iteration устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_context_iteration() вместо неё.

Выполняет единственную итерацию для GMainContext по умолчанию.

may_block : устанавливается в значение TRUE если нужна блокировка (то есть ожидание) пока источник события не будет готов. Возвращается после обработки источника. Если установлено в FALSE возвращается немедленно если нет источника для обработки.
Возвращает : TRUE если ещё есть события на рассмотрении.

g_main_context_pending ()

gboolean    g_main_context_pending          (GMainContext *context);

Проверяет имеют ли источники ожидающие обработки события для данного контекста.

context : GMainContext (если NULL, используется контекст по умолчанию)
Возвращает : TRUE если есть события на рассмотрении.

g_main_pending()

#define     g_main_pending()

Внимание

g_main_pending устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_context_pending() вместо неё.

Проверяет есть ли события ожидающие обработки для GMainContext по умолчанию.

Возвращает : TRUE если есть события ожидающие обработки.

g_main_context_find_source_by_id ()

GSource*    g_main_context_find_source_by_id
                                            (GMainContext *context,
                                             guint source_id);

Находит GSource данной пары контекста и ID.

context : GMainContext (если NULL, используется контекст по умолчанию)
source_id : ID источника, который возвращает g_source_get_id().
Возвращает : GSource если найден, иначе NULL

g_main_context_find_source_by_user_data ()

GSource*    g_main_context_find_source_by_user_data
                                            (GMainContext *context,
                                             gpointer user_data);

Находит источник с полученными пользовательскими данными для callback-функции. Если существует множество источников с такими пользовательскими данными, будет возвращён первый найденный.

context : GMainContext
user_data : user_data для callback-функции.
Возвращает : источник, если найден, иначе NULL

g_main_context_find_source_by_funcs_user_data ()

GSource*    g_main_context_find_source_by_funcs_user_data
                                            (GMainContext *context,
                                             GSourceFuncs *funcs,
                                             gpointer user_data);

Находит источник с данной исходной функцией и пользовательскими данными. Если существует множество источников с такими же функциями и данными, возвращается первый найденный.

context : GMainContext (если NULL, используется контекст по умолчанию).
funcs : source_funcs помещаемая в g_source_new().
user_data : пользовательские данные из callback-функции.
Возвращает : источник, если был найден, иначе NULL

g_main_context_wakeup ()

void        g_main_context_wakeup           (GMainContext *context);

Если context в настоящее время ожидает в poll(), прерывает poll(), и продолжает интерактивный процесс.

context : GMainContext

g_main_context_acquire ()

gboolean    g_main_context_acquire          (GMainContext *context);

Попытается стать владельцем указанного контекста. Если кто то другой владеет контекстом, немедленно возвращает FALSE. Владение является правильной рекурсией: владелец может запросить владение снова и отменить владение когда g_main_context_release() вызывается столько же раз сколько g_main_context_acquire().

Вы должны быть владельцем контекста прежде чем вы сможете вызвать g_main_context_prepare(), g_main_context_query(), g_main_context_check(), g_main_context_dispatch().

context : GMainContext
Возвращает : TRUE если операция выполнена и поток теперь владеет данным context.

g_main_context_release ()

void        g_main_context_release          (GMainContext *context);

Отменяет владение контекстом предварительно полученное потоком с помощью g_main_context_acquire(). Если контекст был получен множество раз, отменяет владение только когда g_main_context_release() вызван соответствующее количество раз.

context : GMainContext

g_main_context_is_owner ()

gboolean    g_main_context_is_owner         (GMainContext *context);

Определяет владеет ли этот поток (рекурсивно) GMaincontext. Это полезно знать перед ожиданием в другом потоке который может быть блокирован для получения владения данным context.

context : GMainContext
Возвращает : TRUE если текущий поток владеет context.

Начиная с версии 2.10


g_main_context_wait ()

gboolean    g_main_context_wait             (GMainContext *context,
                                             GCond *cond,
                                             GMutex *mutex);

Пытается получить владение определенным контекстом, так же как с помощью g_main_context_acquire(). Но если другой поток владеет контекстом, автоматически сбрасывается в mutex и ждёт в cond пока этот владелец освободит владение или пока cond просигнализирует попытаться снова стать владельцем.

context : GMainContext
cond : переменное условие
mutex : взаимное исключение, имеющееся в настоящий момент
Возвращает : TRUE если операция выполнена, и данный поток теперь владеет context.

g_main_context_prepare ()

gboolean    g_main_context_prepare          (GMainContext *context,
                                             gint *priority);

Подготавливает для опроса источник внутри основного цикла. Результирующая информация для опроса определяется с помощью вызова g_main_context_query().

context : GMainContext
priority : расположение для хранения приоритета готового источника с высоким приоритетом.
Возвращает : TRUE если некоторый источник готов для предварительной отправки опроса.

g_main_context_query ()

gint        g_main_context_query            (GMainContext *context,
                                             gint max_priority,
                                             gint *timeout_,
                                             GPollFD *fds,
                                             gint n_fds);

Определяет информацию необходимую для опроса этого основного цикла.

context : GMainContext
max_priority : максимальный приоритет источника для проверки
timeout_ : расположение для хранения пауз используемых в опросах
fds : расположение для хранения GPollFD отчётов опросов.
n_fds : длина fds.
Возвращает : количество отчётов фактически сохрнённых в fds, или, если больше чем n_fds отчётов для хранения, количество отчётов которое необходимо сохранить.

g_main_context_check ()

gint        g_main_context_check            (GMainContext *context,
                                             gint max_priority,
                                             GPollFD *fds,
                                             gint n_fds);

Помещает результат опроса обратно в основной цикл.

context : GMainContext
max_priority : максимальное число приоритета источника для проверки
fds : массив GPollFD's которые были помещены в последний вызов g_main_context_query()
n_fds : значение возвращаемое функцией g_main_context_query()
Возвращает : TRUE если некоторый источник готов для отправки.

g_main_context_dispatch ()

void        g_main_context_dispatch         (GMainContext *context);

Отправляет все ожидающие обработки источники.

context : GMainContext

g_main_context_set_poll_func ()

void        g_main_context_set_poll_func    (GMainContext *context,
                                             GPollFunc func);

Устанавливает функцию используемую для обработки опроса дескриптора файла. Используется вместо poll() системой вызовов (или функцией замены GLib's, которая используется когда poll() не доступен).

Эта функция может использоваться для интеграции GLib цикла события с внешним циклом события.

context : GMainContext
func : функция для вызова опроса всех дескрипторов файла

g_main_context_get_poll_func ()

GPollFunc   g_main_context_get_poll_func    (GMainContext *context);

Получает функцию опроса установленную с помощью g_main_context_set_poll_func().

context : GMainContext
Возвращает : функция опроса

GPollFunc ()

gint        (*GPollFunc)                    (GPollFD *ufds,
                                             guint nfsd,
                                             gint timeout_);

Определяет тип функции помещаемой в g_main_context_set_poll_func(). Семантика функции должна соответствовать системному вызову poll().

ufds : массив GPollFD элементов.
nfsd : количество элементов в ufds.
timeout_ : максимальное время ожидания события дескриптора файла. Отрицательное значение указывает на бесконечное время ожидания.
Возвращает : количество GPollFD элементов которые имеют события или сообщения об ошибках, или -1 если произошла ошибка.

g_main_context_add_poll ()

void        g_main_context_add_poll         (GMainContext *context,
                                             GPollFD *fd,
                                             gint priority);

Добавляет дескриптор файла в набор дескрипторов файлов опрашиваемых для данного контекста. Это очень редко используется непосредственно. Вместо этого обычно источник события использует g_source_add_poll().

context : GMainContext (или NULL для контекста по умолчанию)
fd : GPollFD структура содержащая информацию о дескрипторах файла для просмотра.
priority : приоритет для этого дескриптора файла должен быть таким же как приоритет используемый для g_source_attach() чтобы убедиться что дескриптор файла будет опрошен всякий раз когда может понадобиться результат.

g_main_context_remove_poll ()

void        g_main_context_remove_poll      (GMainContext *context,
                                             GPollFD *fd);

Удаляет дескриптор файла из набора дескрипторов файла опрашиваемых для определенного контекста.

context : GMainContext
fd : GPollFD предварительно добавленный с помощью g_main_context_add_poll()

g_main_depth ()

gint        g_main_depth                    (void);

Возвращает значение основного цикла рекурсии в текущем потоке

Возвращает : глубину стека вызовов для g_main_context_dispatch() в любом GMainContext текущего потока. Таким образом, когда вызов из верхнего уровня, она выдаёт 0. Когда вызов изнутри callback-функции g_main_context_iteration() (или g_main_loop_run(), и т.д.) она возвращает 1. Когда вызов изнутри callback-функции для рекурсивного вызова g_main_context_iterate(), она возвращает 2. И так далее. Эта функция полезна в ситуациях описанных ниже: Представьте чрезвычайно простую систему "сборки мусора".

Пример 1. 

static GList *free_list;

gpointer
allocate_memory (gsize size)
{ 
  gpointer result = g_malloc (size);
  free_list = g_list_prepend (free_list, result);
  return result;
}

void
free_allocated_memory (void)
{
  GList *l;
  for (l = free_list; l; l = l->next);
    g_free (l->data);
  g_list_free (free_list);
  free_list = NULL;
 }

[...]

while (TRUE); 
 {
   g_main_context_iteration (NULL, TRUE);
   free_allocated_memory();
  }

Это работает в приложении, однако, если вы захотите сделать тоже самое в библиотеке, возникнет много проблем, так как вы не можете больше контролировать основной цикл. Вы можете подумать, что можно просто использовать idle функцию создав вызов для free_allocated_memory(), но это не работает, так как idle функция вызывается из рекурсивной callback-функции. Это может быть исправлено при помощи g_main_depth()

Пример 2. 

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

Есть искушение использовать g_main_depth() для решения проблем с повторными входами (reentrancy). Например, во время ожидания данных получаемых из сети в ответ на пункт меню, пункт меню мог бы быть выбран снова. Может показаться, что можно было бы сделать немедленное возвращение callback-функции пункта меню и ничего не делать если g_main_depth() возвращает значение больше 1. Однако, этого нужно избегать, так как пользователь выбрав меню ничего не делает. Кроме того, вам пришлось бы добавлять эти проверки на протяжении всего кода, так как несомненно пользователь мог сделать разные вещи. Вместо этого вы можете использовать следующие методы:

  1. Использовать gtk_widget_set_sensitive() или модальные диалоги, чтобы запретить пользователю взаимодействовать с элементами во время выполнения рекурсии основного цикла.

  2. Запретить рекурсию основного цикла в ситуациях когда вы не можете обрабатывать произвольные callback-функции. Вместо этого, структурируйте ваш код так, чтобы вы просто возвращались в основной цикл и затем получали вызов снова когда есть ещё работа для выполнения.


g_main_current_source ()

GSource*    g_main_current_source           (void);

Возвращает текущий источник для этого потока.

Возвращает : текущий источник или NULL.

Начиная с версии 2.12


g_main_set_poll_func()

#define     g_main_set_poll_func(func)

Внимание

g_main_set_poll_func устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_context_set_poll_func() вместо неё.

Устанавливает функцию используемую для обработки опроса дескрипторов файла основного контекста по умолчанию.

func : функция для вызова опроса всех дескрипторов файла.

g_timeout_source_new ()

GSource*    g_timeout_source_new            (guint interval);

Создаёт новый источник пауз.

Источник первоначально не связан ни с каким GMainContext и должен быть добавлен с помощью g_source_attach() перед выполнением этой функции.

interval : интервал времени ожидания в милесекундах.
Возвращает : вновь созданный источник времени ожидания

g_timeout_source_new_seconds ()

GSource*    g_timeout_source_new_seconds    (guint interval);

Создаёт новый источник времени ожидания.

Первоначально не связан ни с каким GMainContext и должен быть добавлен с помощью g_source_attach() перед выполнением. Точность данного источника времени ожидания измеряется в секундах.

interval : интервал времени ожидания в секундах
Возвращает : вновь созданный источник времени ожидания

Начиная с версии 2.14


g_timeout_add ()

guint       g_timeout_add                   (guint interval,
                                             GSourceFunc function,
                                             gpointer data);

Заставляет вызывать функцию с равномерными интервалами, с приоритетом по умолчанию G_PRIORITY_DEFAULT. Функция вызывается до тех пор пока не возвращено FALSE, в этой точке время ожидания автоматически уничтожается и функция больше не вызывается. Первый вызов функции выполняется в конце первого interval.

Помните что функции паузы могут быть отсрочены, из-за обработки других событий источника. Таким образом нельзя рассчитывать на точную синхронизацию. После каждого вызова функции паузы, время следующей паузы пересчитывается исходя из текущего времени и данного интервала (это не учитывает время потерянное во время задержек).

Если вы хотите иметь таймер в "секундах" и не беспокоиться о точном времени первого вызова таймера, используйте функцию g_timeout_add_seconds(); она позволяет большую оптимизацию и более эффективное использование мощностей системы.

interval : время между вызовами функции, в миллисекундах (1/1000 секунды)
function : вызываемая функция
data : данные помещаемые в function
Возвращает : ID (больше чем 0) источника события.

g_timeout_add_full ()

guint       g_timeout_add_full              (gint priority,
                                             guint interval,
                                             GSourceFunc function,
                                             gpointer data,
                                             GDestroyNotify notify);

Заставляет вызывать функцию с регулярными интервалами, с данным приоритетом. Функция вызывается до тех пор пока возвращено значение FALSE, в этой точке время ожидания автоматически уничтожается и функция больше не вызывается. Функция notify вызывается когда пауза уничтожена. Первый вызов функции происходит в конце первого interval.

Помните что функции паузы могут быть отсрочены, из-за обработки других событий источника. Таким образом нельзя рассчитывать на точную синхронизацию. После каждого вызова функции паузы, время следующей паузы пересчитывается исходя из текущего времени и данного интервала (это не учитывает время потерянное во время задержек).

priority : приоритет idle источника. Обычно в диапазоне между G_PRIORITY_DEFAULT_IDLE и G_PRIORITY_HIGH_IDLE.
interval : время между вызовами функций, в миллисекундах (1/1000 секунды)
function : вызываемая функция
data : данные помещаемые в function
notify : функция вызываемая когда интервал удалён, или NULL
Возвращает : ID (больше 0) источника события.

g_timeout_add_seconds ()

guint       g_timeout_add_seconds           (guint interval,
                                             GSourceFunc function,
                                             gpointer data);

Вызывает функцию через равномерные интервалы, с приоритетом по умолчанию, G_PRIORITY_DEFAULT. Функция вызывается до тех пор пока не возвращено значение FALSE, в этой точке интервал автоматически уничтожается и функция больше не вызывается.

В отличии от g_timeout_add(), эта функция оперирует секундной точностью. Начальная точка таймера определяется реализацией и реализация как ожидается соберёт множество таймеров в группу, чтобы они все запускались в одно время. Чтобы позволить эту группировку, interval для первого таймера округляется и может отклониться на одну секунду от указанного интервала. Последующие итерации таймера будут в общем выполняться в указанном интервале.

Помните что тайм аут функции могут быть отсрочены, из-за обработки других источников событий. Таким образом на них нельзя рассчитывать при точной синхронизации. После каждого вызова тайм аут функции, время следующей паузы пересчитывается исходя из текущего времени и полученного интервала interval

Если вам нужны более точные расчеты нежели секунды, используйте вместо этой функции g_timeout_add().

Группирование таймеров для старта в одно и тоже время приводит к более эффективному использованию CPU, поэтому если ваш таймер в секундах и находится в множестве однотипных и вам не требуется запуск первого таймера с точностью до 1 секунды, использование g_timeout_add_second() предпочтительней чем g_timeout_add().

interval : время между запусками функций, в секундах
function : функция для вызова
data : данные для помещения в function
Возвращает : ID (больше чем 0) источника события.

Начиная с версии 2.14


g_idle_source_new ()

GSource*    g_idle_source_new               (void);

Создаёт новый пустой (idle) источник.

Источник первоначально не связан ни с каким GMainContext и должен быть добавлен в него с помощью g_source_attach() перед выполнением. Помните что приоритетом по умолчанию idle источника является G_PRIORITY_DEFAULT_IDLE, тогда как другие источники по умолчанию имеют приоритет G_PRIORITY_DEFAULT.

Возвращает : вновь созданный пустой (idle) источник

g_idle_add ()

guint       g_idle_add                      (GSourceFunc function,
                                             gpointer data);

Добавляет функцию которая вызывается каждый раз когда нет обрабатываемого события с более высоким приоритетом в основном цикле по умолчанию. Функция получает по умолчанию idle приоритет, G_PRIORITY_DEFAULT_IDLE. Если функция возвращает FALSE она автоматически удаляется из списка источника событий и больше не вызывается.

function : функция для вызова
data : данные для помещения в function.
Возвращает : ID (больше 0) источника события.

g_idle_add_full ()

guint       g_idle_add_full                 (gint priority,
                                             GSourceFunc function,
                                             gpointer data,
                                             GDestroyNotify notify);

Добавляет функцию для вызова когда нет события с более высоким приоритетом на рассмотрении. Если функция возвращает FALSE, то автоматически удаляется из списка источника событий и больше не вызывается.

priority : приоритет idle источника. Обычно в диапазоне между G_PRIORITY_DEFAULT_IDLE и G_PRIORITY_HIGH_IDLE.
function : функция для вызова
data : данные помещаемые в function
notify : функция вызываемая при удалении idle функции, или NULL
Возвращает : ID (больше 0) источника события.

g_idle_remove_by_data ()

gboolean    g_idle_remove_by_data           (gpointer data);

Удаляет idle функцию с полученными данными.

data : данные для idle источников callback-функций.
Возвращает : TRUE если idle источник найден и удалён.

GPid

typedef int GPid;

Тип содержащий идентификатор процесса. В Unix, процессы идентифицируются с помощью process id (целочисленное), в то время как в Windows используются маркеры процесса (которые являются указателями).


GChildWatchFunc ()

void        (*GChildWatchFunc)              (GPid pid,
                                             gint status,
                                             gpointer data);

Тип функций для вызова при существовании дочерних процессов.

pid : id дочернего процесса
status : Информация состояния дочернего процесса, более подробную информацию об этом поле смотрите в waitpid(2)
data : пользовательские данные помещаемые в g_child_watch_add()

g_child_watch_source_new ()

GSource*    g_child_watch_source_new        (GPid pid);

Создаёт новый child_watch источник.

Первоначально источник не связан ни с каким GMainContext и должен быть добавлен в него с помощью g_source_attach() перед использованием.

Помните, что дочерний процесс наблюдения может использоваться только совместно с g_spawn... когда используется флаг G_SPAWN_DO_NOT_REAP_CHILD.

Помните, что на платформах где GPid должен быть явно закрыт (смотрите g_spawn_close_pid()) pid не должен закрываться пока источник активен. Обычно, вам нужно вызывать g_spawn_close_pid() в callback-функции для источника.

Помните также что использование g_child_watch_source_new() не совместимо с вызовом waitpid(-1) в приложении. Вызов waitpid() для индивидуального pids будет прекрасно работать.

pid : process id дочернего процесса для наблюдения. В Windows, МАРКЕР (HANDLE) для процесса наблюдения (который фактически не является дочерним).
Возвращает : вновь созданный дочерний процесс наблюдения

Начиная с версии 2.4


g_child_watch_add ()

guint       g_child_watch_add               (GPid pid,
                                             GChildWatchFunc function,
                                             gpointer data);

Устанавливает функцию для вызова при существовании дочернего процесса указанного с помощью pid, с приоритетом по умолчанию G_PRIORITY_DEFAULT.

Помните что на платформах где GPid должен быть явно закрыт (смотрите g_spawn_close_pid()) pid не должен закрываться пока источник активен. Обычно, вам потребуется вызвать g_spawn_close_pid() в callback-функции для источника.

GLib поддерживает только один вызов callback-функции через process id.

pid : process id дочернего процесса для наблюдения
function : функция для вызова
data : данные помещаемые в function
Возвращает : ID (больше 0) источника события.

Начиная с версии 2.4


g_child_watch_add_full ()

guint       g_child_watch_add_full          (gint priority,
                                             GPid pid,
                                             GChildWatchFunc function,
                                             gpointer data,
                                             GDestroyNotify notify);

Устанавливает функцию вызываемую когда дочерний процесс указанный с помощью pid существует, с приоритетом по умолчанию G_PRIORITY_DEFAULT.

Помните что на платформах где GPid должен быть закрыт явно (смотрите g_spawn_close_pid()) pid не должен закрываться пока источник активен. Обычно, вам необходимо вызвать g_spawn_close_pid() в callback-функции для источника.

GLib поддерживает только единственный вызов callback-функции через process id.

priority : приоритет idle источника. Обычно в диапазоне между G_PRIORITY_DEFAULT_IDLE и G_PRIORITY_HIGH_IDLE.
pid : process id дочернего процесса для наблюдения
function : вызываемая функция
data : данные помещаемые в function
notify : функция вызываемая при удалении idle функции, или NULL
Возвращает : ID (больше 0) источника события.

Начиная с версии 2.4


GPollFD

typedef struct {
  gint		fd;
  gushort 	events;
  gushort 	revents;
} GPollFD;

gint fd; дескриптор файла для опроса (или МАРКЕР (HANDLE) на Win32 платформах).
gushort events; поразарядная комбинация флажков из GIOCondition, определяющая события для опроса. Обычно для чтения из дескриптора файла вы должны использовать G_IO_IN | G_IO_HUP | G_IO_ERR, а для записи вы должны использовать G_IO_OUT | G_IO_ERR.
gushort revents; поразрядная комбинация флажков из GIOCondition, возвращаемая из функции poll() указывая какие события произошли.


GSource

typedef struct {
} GSource;

Структура GSource непрозрачного типа данных представляющих источник события.


GSourceDummyMarshal ()

void        (*GSourceDummyMarshal)          (void);

Это просто метка для GClosureMarshal, которая не используется по причине зависимостей.


GSourceFuncs

typedef struct {
  gboolean (*prepare)  (GSource    *source,
			gint       *timeout_);
  gboolean (*check)    (GSource    *source);
  gboolean (*dispatch) (GSource    *source,
			GSourceFunc callback,
			gpointer    user_data);
  void     (*finalize) (GSource    *source); /* Может быть NULL */

  /* Для использования g_source_set_closure */
  GSourceFunc     closure_callback;	   
  GSourceDummyMarshal closure_marshal; /* Фактически тип GClosureMarshal */
} GSourceFuncs;

Структура GSourceFuncs содержит таблицу функций используемых для обработки источника события основным способом.

prepare Вызывается перед опросом всех дескрипторов файла. Если источник может определить что он готов (не ждет результата вызова poll()) он должен вернуть TRUE. Он также может вернуть значение timeout_ которое должно быть максимальным временем ожидания (в миллесекундах) помещаемым в вызов poll(). Фактический используемый тайм аут будет равен -1 если все источники вернут -1, или он будет меньше всех возвращённых значений timeout_ которые были >= 0.
check Вызывается после опроса всех дескрипторов файла. Источник должен вернуть TRUE если он готов для отправки. Помните что пройдёт некоторое время так как была вызвана предварительно подготовленная функция, поэтому источник должен проверяться снова.
dispatch Вызывается после отправки источника события, после того как он возвратил TRUE или в prepare или check функции. Функция dispatch помещает callback-функцию и данные. callback-функция может быть NULL если источник никогда не связывается с callback-функцией используя g_source_set_callback(). Функция dispatch должна вызывать callback-функцию с user_data и независимо от дополнительных параметров необходимых для этого типа источника события.
finalize Вызывается когда источник окончательно реализован (finalized).

Для idle источников, функции prepare и check всегда возвращают TRUE указывая что источник всегда готов к обработке. Функция prepare также возвращает значение тайм аута равное 0, чтобы гарантировать что вызов poll() не заблокируется (так как это было бы впустую потраченным временем которое можно потратить на idle функцию).

Для источников, обе функции prepare и check возвращают TRUE если интервал тайм аута истек. Функция prepare также возвращает значение таймаута, чтобы гарантировать что вызов poll() не блокируется слишком долго и не пропустит следующий таймаут.

Для источников дескриптора файлов, функция prepare обычно возвращает FALSE, так как нужно ждать пока poll() будет вызвана перед определением нужно ли обрабатывать какое нибудь событие. Это установит возвращённый тайм аут в значение -1 указывая что не знает как долго блокирован вызов poll(). В функции check, проверяет результат вызова poll() чтобы видеть встречалось ли необходимое условие, и возвращает TRUE.


GSourceCallbackFuncs

typedef struct {
  void (*ref)   (gpointer     cb_data);
  void (*unref) (gpointer     cb_data);
  void (*get)   (gpointer     cb_data,
		 GSource     *source, 
		 GSourceFunc *func,
		 gpointer    *data);
} GSourceCallbackFuncs;

Структура GSourceCallbackFuncs содержит функции для управления callback-объектами.

ref () Вызывается при добавлении ссылки на callback-объект.
unref () Вызывается при сбросе ссылки на callback-объект.
get () Вызывается для извлечения callback-функции и данных из callback-объекта.

g_source_new ()

GSource*    g_source_new                    (GSourceFuncs *source_funcs,
                                             guint struct_size);

Содаёт новую структуру GSource. Размер определяется для создания структур полученных из GSource который содержит дополнительные данные. Помещаемый размер должен быть как минимум sizeof (GSource).

Первоначально источник не связан ни с каким GMainContext и должен быть добавлен в него с помощью g_source_attach() перед использованием.

source_funcs : структура содержащая функции которые реализуют поведение источников.
struct_size : размер структуры GSource для создания.
Возвращает : вновь созданный GSource.

g_source_ref ()

GSource*    g_source_ref                    (GSource *source);

Увеличивает количество ссылок источника на одну.

source : GSource
Возвращает : source

g_source_unref ()

void        g_source_unref                  (GSource *source);

Уменьшает количество ссылок источника на одну. Если в результате получается ноль, источник и связанная с ним память освобождаются.

source : GSource

g_source_set_funcs ()

void        g_source_set_funcs              (GSource *source,
                                             GSourceFuncs *funcs);

Отсоединяет функции от источника (может использоваться для отмены выполнения по умолчанию).

source : GSource
funcs : новый GSourceFuncs

Начиная с версии 2.12


g_source_attach ()

guint       g_source_attach                 (GSource *source,
                                             GMainContext *context);

Добавляет GSource в context так чтобы он выполнялся внутри контекста.

source : GSource
context : GMainContext (если NULL, используется контекст по умолчанию)
Возвращает : ID (больше 0) для источника внутри GMainContext.

g_source_destroy ()

void        g_source_destroy                (GSource *source);

Удаляет источник из его GMainContext, если есть, и маркирует его как уничтоженный. Источник не может в последствии добавляться в другой контекст.

source : GSource

g_source_is_destroyed ()

gboolean    g_source_is_destroyed           (GSource *source);

Определяет уничтожен ли source.

Это важно когда вы оперируете с вашими объектами внутри idle обработчиков, но при этом возможно освободили объект перед отправкой вашего idle обработчика.

static gboolean 
idle_callback (gpointer data)
{
  SomeWidget *self = data;
   
  GDK_THREADS_ENTER ();
  /* заполняется самостоятельно */
  self->idle_id = 0;
  GDK_THREADS_LEAVE ();
   
  return FALSE;
}
 
static void 
some_widget_do_stuff_later (SomeWidget *self)
{
  self->idle_id = g_idle_add (idle_callback, self);
}
 
static void 
some_widget_finalize (GObject *object)
{
  SomeWidget *self = SOME_WIDGET (object);
   
  if (self->idle_id)
    g_source_remove (self->idle_id);
   
  G_OBJECT_CLASS (parent_class)->finalize (object);
}

Этот пример завершится неудачей в много-потоковом приложении если виджет уничтожен перед запуском idle обработчика из-за использования после освобождения в обратном вызове. Решение этой специфической проблемы в том, чтобы проверить уничтожен ли уже источник в обратном вызове.

static gboolean 
idle_callback (gpointer data)
{
  SomeWidget *self = data;
  
  GDK_THREADS_ENTER();
  if (!g_source_is_destroyed (g_main_current_source()))
    {
      /* заполняется самостоятельно */
    }
  GDK_THREADS_LEAVE();
  
  return FALSE;
}

source : GSource
Возвращает : TRUE если источник уничтожен

Начиная с версии 2.12


g_source_set_priority ()

void        g_source_set_priority           (GSource *source,
                                             gint priority);

Устанавливает приоритет источника. Во время выполнения основного цикла, источник отправляется если готов и нет готовых источников с более высоким приоритетом (с меньшим номером).

source : GSource
priority : новый приоритет.

g_source_get_priority ()

gint        g_source_get_priority           (GSource *source);

Определяет приоритет источника.

source : GSource
Возвращает : приоритет источника

g_source_set_can_recurse ()

void        g_source_set_can_recurse        (GSource *source,
                                             gboolean can_recurse);

Устанавливает может ли источник вызываться рекурсивно. Если параметр can_recurse равен TRUE, то во время отправки источник обрабатывается обычно. Иначе, все процессы источника блокируются до возвращения функции отправки.

source : GSource
can_recurse : разрешена ли рекурсия для данного источника

g_source_get_can_recurse ()

gboolean    g_source_get_can_recurse        (GSource *source);

Проверяет разрешено ли источнику вызываться рекурсивно. (смотрите g_source_set_can_recurse()).

source : GSource
Возвращает : разрешена ли рекурсия.

g_source_get_id ()

guint       g_source_get_id                 (GSource *source);

Возвращает число ID для специального источника. ID источника это положительное целое которое является уникальным внутри определённого контекста основного цикла. Обратное преобразование из ID в источник выполняется с помощью g_main_context_find_source_by_id().

source : GSource
Возвращает : ID (больше 0) для источника

g_source_get_context ()

GMainContext* g_source_get_context          (GSource *source);

Определяет GMainContext с которым связан источник. Вызов этой функции для уничтоженного источника недопустим.

source : GSource
Возвращает : GMainContext с которым связан источник, или NULL если контекст не имеет добавленного источника.

g_source_set_callback ()

void        g_source_set_callback           (GSource *source,
                                             GSourceFunc func,
                                             gpointer data,
                                             GDestroyNotify notify);

Устанавливает callback-функцию для источника. callback-функция для источника вызывается из dispatch функции источников.

Точный тип func зависит от типа источника; то есть вы не должны рассчитывать на func вызванную с data как её первый параметр.

Обычно вам не нужно использовать эту функцию. Вместо неё используйте функции определённого типа для используемого вами типа источника.

source : источник
func : callback-функция
data : данные помещаемые в callback-функцию
notify : функция вызываемая когда data больше не используются, или NULL.

GSourceFunc ()

gboolean    (*GSourceFunc)                  (gpointer data);

Конкретизирует тип функции помещаемой в g_timeout_add(), g_timeout_add_full(), g_idle_add() и g_idle_add_full().

data : данные помещаемые в функцию, устанавливаются когда источник создаётся одной из упомянутых выше функцией.
Возвращает : должна вернуть FALSE если источник должен быть удалён.

g_source_set_callback_indirect ()

void        g_source_set_callback_indirect  (GSource *source,
                                             gpointer callback_data,
                                             GSourceCallbackFuncs *callback_funcs);

Устанавливает callback-функцию хранения данных как refcounted callback "object". Это используется внутренне. Помните что вызов g_source_set_callback_indirect() предполагает, что начат подсчёт ссылок на callback_data, и поэтому callback_funcs->unref будет в конечном счёте вызван больше чем callback_funcs->ref.

source : источник
callback_data : указатель для данных callback-объекта "object"
callback_funcs : функция для подсчёта ссылок callback_data и получения callback-функции и данных

g_source_add_poll ()

void        g_source_add_poll               (GSource *source,
                                             GPollFD *fd);

Добавляет дескриптор в набор опрашиваемых дескрипторов файла для данного источника. Это полезно комбинировать с g_source_new() для добавления источника события. Функция проверки источников события обычно проверяет поле revents в GPollFD структуре и возвращает TRUE если события должны быть обработаны.

source : GSource
fd : GPollFD структура содержащая информацию о дескрипторе файла для наблюдения.

g_source_remove_poll ()

void        g_source_remove_poll            (GSource *source,
                                             GPollFD *fd);

Удаляет дескриптор файла из набора опрашиваемых дескрипторов файла для данного источника.

source : GSource
fd : GPollFD структура предварительно помещённая в g_source_add_poll().

g_source_get_current_time ()

void        g_source_get_current_time       (GSource *source,
                                             GTimeVal *timeval);

Определяет "текущее время" для использования при проверки источника. Преимущество вызова этой функции перед вызовом g_get_current_time() заключается в проверке множества источников, GLib может кэшировать единственное значение вместо необходимости неоднократного получения системного времени.

source : GSource
timeval : GTimeVal структура в которой хранится текущее время.

g_source_remove ()

gboolean    g_source_remove                 (guint tag);

Удаляет источник с полученным id из основного контекста по умолчанию. Идентификатор (id) GSource получается при помощи g_source_get_id(), или возвращается функциями 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() и g_io_add_watch_full().

Смотрите также g_source_destroy().

tag : ID удаляемого источника.
Возвращает : TRUE если источник найден и удалён.

g_source_remove_by_funcs_user_data ()

gboolean    g_source_remove_by_funcs_user_data
                                            (GSourceFuncs *funcs,
                                             gpointer user_data);

Удаляет источник из контекста основного цикла по умолчанию с данными функциями источника и пользовательскими данными. Если существует множество источников с одинаковыми функциями источника и пользовательскими данными, будет удалён только один.

funcs : source_funcs помещаемые в g_source_new()
user_data : пользовательские данные для callback-функции
Возвращает : TRUE если источник найден и удалён.

g_source_remove_by_user_data ()

gboolean    g_source_remove_by_user_data    (gpointer user_data);

Удаляет источник из контекста основного цикла по умолчанию с полученными пользовательскими данными для callback-функции. Если существует множество одинаковых источников с такими же пользовательскими данными, удаляется только один.

user_data : user_data для callback-функции.
Возвращает : TRUE если источник найден и удалён.

Thread Pools

Thread Pools — Пулы потоков для одновременного выполнения работы.

Краткое описание


#include <glib.h>


            GThreadPool;
GThreadPool* g_thread_pool_new              (GFunc func,
                                             gpointer user_data,
                                             gint max_threads,
                                             gboolean exclusive,
                                             GError **error);
void        g_thread_pool_push              (GThreadPool *pool,
                                             gpointer data,
                                             GError **error);
void        g_thread_pool_set_max_threads   (GThreadPool *pool,
                                             gint max_threads,
                                             GError **error);
gint        g_thread_pool_get_max_threads   (GThreadPool *pool);
guint       g_thread_pool_get_num_threads   (GThreadPool *pool);
guint       g_thread_pool_unprocessed       (GThreadPool *pool);
void        g_thread_pool_free              (GThreadPool *pool,
                                             gboolean immediate,
                                             gboolean wait);
void        g_thread_pool_set_max_unused_threads
                                            (gint max_threads);
gint        g_thread_pool_get_max_unused_threads
                                            (void);
guint       g_thread_pool_get_num_unused_threads
                                            (void);
void        g_thread_pool_stop_unused_threads
                                            (void);
void        g_thread_pool_set_sort_function (GThreadPool *pool,
                                             GCompareDataFunc func,
                                             gpointer user_data);
void        g_thread_pool_set_max_idle_time (guint interval);
guint       g_thread_pool_get_max_idle_time (void);

Описание

Иногда вам нужна асинхронная работа, прекращение работы и продолжение работы вашего потока. Если это происходит часто, накладные расходы запуска и уничтожения процесса каждый раз могут быть слишком высоки. В таких случаях хорошей идеей является многократное использование уже существующих потоков. Но реализация этого может быть утомительной и подвержена ошибкам.

Поэтому для вашего удобства GLib обеспечивает пулы потоков. Дополнительное преимущество в том, что потоки могут использоваться совместно разными подсистемами вашей программы, когда используется GLib.

Для создания нового пула потоков используется g_thread_pool_new(). Освобождается созданный пул потоков с помощью g_thread_pool_free().

Если вам нужно выполнить определённую задачу внутри потокового пула, вызовите g_thread_pool_push().

Для получения текущего количества выполняемых потоков используйте g_thread_pool_get_num_threads(). Для получения количества ещё не обработанных задач используйте g_thread_pool_unprocessed(). Для управления максимальным количеством потоков пула, используйте g_thread_pool_get_max_threads() и g_thread_pool_set_max_threads().

Наконец вы можете контролировать количество неиспользуемых потоков, которые поддерживаются GLib для использования в будущем. Текущее количество может быть выбрано с помощью g_thread_pool_get_num_unused_threads(). Максимальное количество может контролироваться с помощью g_thread_pool_get_max_unused_threads() и g_thread_pool_set_max_unused_threads(). Все текущие неиспользуемые потоки могут быть остановлены при помощи g_thread_pool_stop_unused_threads().

Детали

GThreadPool

typedef struct {
  GFunc func;
  gpointer user_data;
  gboolean exclusive;
} GThreadPool;

Структура GThreadPool представляет потоковый пул. Она имеет шесть общих доступных только для чтения элементов, но скрытая структура больше, поэтому вы не должны копировать эту структуру.

GFunc func; Функция выполняемая в потоках этого пула
gpointer user_data; пользовательские данные для потоков этого пула
gboolean exclusive; все исключительные потоки этого пула

g_thread_pool_new ()

GThreadPool* g_thread_pool_new              (GFunc func,
                                             gpointer user_data,
                                             gint max_threads,
                                             gboolean exclusive,
                                             GError **error);

Эта функция создаёт новый потоковый пул.

Каждый раз при вызове g_thread_pool_push(), или создаётся новый поток или повторно используется один из неиспользуемых. Большинство max_threads потоков выполняются параллельно для этого потокового пула. max_threads = -1 позволяет безлимитное создание потоков для этого пула. Вновь созданный или повторно используемый поток выполняет функцию func с двумя аргументами. Первый для g_thread_pool_push() а второй user_data.

Параметр exclusive определяет, владеет ли всеми исключительными потоками пул, или потоки доступны глобально. Если exclusive равен TRUE, max_threads потоки начинаются немедленно и они будут выполняться исключительно для этого пула пока он не разрушен g_thread_pool_free(). Если exclusive равен FALSE, потоки создаются когда необходимы и доступны всем не исключительным потоковым пулам. Это подразумевает что max_threads может не быть -1 для исключительных потоковых пулов.

error может быть NULL для игнорирования ошибок, или не-NULL для сообщения об ошибках. Ошибка может произойти только когда exclusive установлен в TRUE и не все max_threads могут быть созданы.

func : функция выполняемая в потоке нового потокового пула
user_data : пользовательские данные передаваемые в функцию func при каждом вызове
max_threads : максимальное количество потоков для параллельного выполнения в новом потоковом пуле, -1 означает отсутствие лимита
exclusive : должен ли этот пул быть исключительным?
error : расположение возвращаемой ошибки
Возвращает : новую GThreadPool

g_thread_pool_push ()

void        g_thread_pool_push              (GThreadPool *pool,
                                             gpointer data,
                                             GError **error);

Вставляет data в список задач для выполнения пулом pool. Когда количество выполняемых потоков меньше чем максимально допустимое, новый поток запускается (или повторно выполняется) с параметрами полученными в g_thread_pool_new(). Иначе data остаются в очереди пока поток в этом пуле не завершит предыдущие задачи и не начнет обрабатывать data.

error может быть NULL для игнорирования ошибок, или не-NULL для сообщения об ошибках. Ошибка может произойти только когда новый поток не может быть создан. В этом случае data просто вставляются в начало очереди для выполнения.

pool : GThreadPool
data : новая задача для pool
error : расположение для возвращаемой ошибки

g_thread_pool_set_max_threads ()

void        g_thread_pool_set_max_threads   (GThreadPool *pool,
                                             gint max_threads,
                                             GError **error);

Устанавливает максимально допустимое число потоков для pool. Значение -1 означает безлимитное количество потоков.

Установка max_threads в значение 0 означает полную остановку работы pool. Пул замораживается до тех пор пока значение max_threads не будет установлено в не-нулевое значение.

Поток никогда не завершается во время выполнения вызова func, которая поставляется g_thread_pool_new(). Вместо этого максимальное число потоков имеет эффект только для распределения новых потоков в g_thread_pool_push(). Новый поток распределяется каждый раз, когда текущее количество выполняемых потоков в пуле меньше pool меньше чем максимальное число.

error может быть NULL для игнорирования ошибок, или не-NULL для сообщения об ошибках. Ошибка происходит только когда новый поток не может быть создан.

pool : GThreadPool
max_threads : новое максимальное число потоков для pool
error : расположение возвращаемой ошибки

g_thread_pool_get_max_threads ()

gint        g_thread_pool_get_max_threads   (GThreadPool *pool);

Возвращает максимальное число потоков для pool.

pool : GThreadPool
Возвращает : максимальное число потоков

g_thread_pool_get_num_threads ()

guint       g_thread_pool_get_num_threads   (GThreadPool *pool);

Возвращает текущее количество выполняемых потоков в pool.

pool : GThreadPool
Возвращает : текущее количество выполняемых потоков

g_thread_pool_unprocessed ()

guint       g_thread_pool_unprocessed       (GThreadPool *pool);

Возвращает количество задач остающихся не обработанными в pool.

pool : GThreadPool
Возвращает : количество не обработанных задач

g_thread_pool_free ()

void        g_thread_pool_free              (GThreadPool *pool,
                                             gboolean immediate,
                                             gboolean wait);

Освобождает все ресурсы распределённые для pool.

Если immediate равен TRUE, нет новых задач обрабатываемых в pool. Иначе pool не освободиться до тех пор пока последняя задача не обработана. Однако помните, поток не прерывается в пуле пока выполняет задачу. Все потоки выполняющие свои задачи завершают их перед тем как pool будет освобождён.

Если wait равен TRUE, функции не возвращают прежде чем все обрабатываемые задачи (зависит от immediate, все или только выполняемые в текущий момент) будут готовы. Иначе функции возвращаются немедленно.

После вызова этой функции pool не должен больше использоваться.

pool : GThreadPool
immediate : должен ли пул pool завершиться немедленно?
wait : должна ли функция ждать завершения всех задач?

g_thread_pool_set_max_unused_threads ()

void        g_thread_pool_set_max_unused_threads
                                            (gint max_threads);

Устанавливает максимальное количество неиспользуемых потоков в max_threads. Если max_threads равен -1, количество неиспользуемых потоков не лимитировано.

max_threads : максимальное число неиспользуемых потоков

g_thread_pool_get_max_unused_threads ()

gint        g_thread_pool_get_max_unused_threads
                                            (void);

Возвращает максимально допустимое число неиспользуемых потоков.

Возвращает : максимальное число неиспользуемых потоков

g_thread_pool_get_num_unused_threads ()

guint       g_thread_pool_get_num_unused_threads
                                            (void);

Возвращает текущее количество неиспользуемых потоков.

Возвращает : текущее число неиспользуемых потоков

g_thread_pool_stop_unused_threads ()

void        g_thread_pool_stop_unused_threads
                                            (void);

Останавливает все текущие неиспользуемые потоки. Это не меняет максимальное число неиспользуемых потоков. Эта функция может использоваться для регулярной остановки всех неиспользуемых потоков например из g_timeout_add().


g_thread_pool_set_sort_function ()

void        g_thread_pool_set_sort_function (GThreadPool *pool,
                                             GCompareDataFunc func,
                                             gpointer user_data);

Устанавливает функцию для сортировки списка задач. Это позволяет обрабатывать задачи с приоритетом определяемым с помощью func, а не только в порядке в котором они были добавлены в пул.

Помните, если максимальное количество потоков больше 1, порядок выполнения потоков не может быть гарантирован на 100%. Потоки планируются операционной системой и выполняются в случайном порядке. Не предполагайте что потоки выполняются в порядке их создания.

pool : GThreadPool
func : GCompareDataFunc используемая для сортировки списка задач. При передаче в функцию две задачи, она должна возвращать 0 если порядок в котором обрабатываются задачи не важен, отрицательное значение если первая задача должна быть обработана перед второй или положительное если вторая задача должна обрабатываться перед первой.
user_data : пользовательские данные помещаемые в func.

Начиная с версии 2.10


g_thread_pool_set_max_idle_time ()

void        g_thread_pool_set_max_idle_time (guint interval);

Эта функция устанавливает максимальный interval ожидания потоком новых задач в пуле перед остановкой. Эта функция похожа на вызов g_thread_pool_stop_unused_threads() с регулярным таймаутом, но выполняется на основании потока.

Установка interval в 0, не останавливает бездействующие потоки. Эта функция создаёт g_async_queue_timed_pop() используя interval.

interval : максимальный interval (1/1000 секунды) бездействия потока.

Начиная с версии 2.10


g_thread_pool_get_max_idle_time ()

guint       g_thread_pool_get_max_idle_time (void);

Эта функция возвращает максимальный interval ожидания потоком новых задач в пуле перед остановкой.

Если функция вернула 0, потоки ожидающие новые задачи в пуле не останавливаются.

Возвращает : максимальный interval ожидания потоком новых задач в пуле перед остановкой (1/1000 секунды).

Начиная с версии 2.10

Смотрите также

GThread

система потока GLib.


Потоки

Threads — Абстракция потока; включает потоки, различные взаимоисключения (mutexes), условия и поток закрытых данных.

Краткое описание


#include <glib.h>



#define     G_THREADS_ENABLED
#define     G_THREADS_IMPL_POSIX
#define     G_THREADS_IMPL_NONE

#define     G_THREAD_ERROR
enum        GThreadError;

            GThreadFunctions;
void        g_thread_init                   (GThreadFunctions *vtable);
gboolean    g_thread_supported              ();

gpointer    (*GThreadFunc)                  (gpointer data);
enum        GThreadPriority;
            GThread;
GThread*    g_thread_create                 (GThreadFunc func,
                                             gpointer data,
                                             gboolean joinable,
                                             GError **error);
GThread*    g_thread_create_full            (GThreadFunc func,
                                             gpointer data,
                                             gulong stack_size,
                                             gboolean joinable,
                                             gboolean bound,
                                             GThreadPriority priority,
                                             GError **error);
GThread*    g_thread_self                   (void);
gpointer    g_thread_join                   (GThread *thread);
void        g_thread_set_priority           (GThread *thread,
                                             GThreadPriority priority);
void        g_thread_yield                  ();
void        g_thread_exit                   (gpointer retval);
void        g_thread_foreach                (GFunc thread_func,
                                             gpointer user_data);

            GMutex;
GMutex*     g_mutex_new                     ();
void        g_mutex_lock                    (GMutex *mutex);
gboolean    g_mutex_trylock                 (GMutex *mutex);
void        g_mutex_unlock                  (GMutex *mutex);
void        g_mutex_free                    (GMutex *mutex);

            GStaticMutex;
#define     G_STATIC_MUTEX_INIT
void        g_static_mutex_init             (GStaticMutex *mutex);
void        g_static_mutex_lock             (GStaticMutex *mutex);
gboolean    g_static_mutex_trylock          (GStaticMutex *mutex);
void        g_static_mutex_unlock           (GStaticMutex *mutex);
GMutex*     g_static_mutex_get_mutex        (GStaticMutex *mutex);
void        g_static_mutex_free             (GStaticMutex *mutex);

#define     G_LOCK_DEFINE                   (name)
#define     G_LOCK_DEFINE_STATIC            (name)
#define     G_LOCK_EXTERN                   (name)
#define     G_LOCK                          (name)
#define     G_TRYLOCK                       (name)
#define     G_UNLOCK                        (name)

            GStaticRecMutex;
#define     G_STATIC_REC_MUTEX_INIT
void        g_static_rec_mutex_init         (GStaticRecMutex *mutex);
void        g_static_rec_mutex_lock         (GStaticRecMutex *mutex);
gboolean    g_static_rec_mutex_trylock      (GStaticRecMutex *mutex);
void        g_static_rec_mutex_unlock       (GStaticRecMutex *mutex);
void        g_static_rec_mutex_lock_full    (GStaticRecMutex *mutex,
                                             guint depth);
guint       g_static_rec_mutex_unlock_full  (GStaticRecMutex *mutex);
void        g_static_rec_mutex_free         (GStaticRecMutex *mutex);

            GStaticRWLock;
#define     G_STATIC_RW_LOCK_INIT
void        g_static_rw_lock_init           (GStaticRWLock *lock);
void        g_static_rw_lock_reader_lock    (GStaticRWLock *lock);
gboolean    g_static_rw_lock_reader_trylock (GStaticRWLock *lock);
void        g_static_rw_lock_reader_unlock  (GStaticRWLock *lock);
void        g_static_rw_lock_writer_lock    (GStaticRWLock *lock);
gboolean    g_static_rw_lock_writer_trylock (GStaticRWLock *lock);
void        g_static_rw_lock_writer_unlock  (GStaticRWLock *lock);
void        g_static_rw_lock_free           (GStaticRWLock *lock);

            GCond;
GCond*      g_cond_new                      ();
void        g_cond_signal                   (GCond *cond);
void        g_cond_broadcast                (GCond *cond);
void        g_cond_wait                     (GCond *cond,
                                             GMutex *mutex);
gboolean    g_cond_timed_wait               (GCond *cond,
                                             GMutex *mutex,
                                             GTimeVal *abs_time);
void        g_cond_free                     (GCond *cond);

            GPrivate;
GPrivate*   g_private_new                   (GDestroyNotify destructor);
gpointer    g_private_get                   (GPrivate *private_key);
void        g_private_set                   (GPrivate *private_key,
                                             gpointer data);

            GStaticPrivate;
#define     G_STATIC_PRIVATE_INIT
void        g_static_private_init           (GStaticPrivate *private_key);
gpointer    g_static_private_get            (GStaticPrivate *private_key);
void        g_static_private_set            (GStaticPrivate *private_key,
                                             gpointer data,
                                             GDestroyNotify notify);
void        g_static_private_free           (GStaticPrivate *private_key);

            GOnce;
enum        GOnceStatus;
#define     G_ONCE_INIT
#define     g_once                          (once, func, arg)

Описание

Потоки действуют почти как процессы, но в отличии от процессов все потоки одного процесса совместно используют одну и туже память. Это хорошо, поскольку обеспечивает простую взаимосвязь между вовлечёнными потоками через общую память, и это плохо, потому что могут происходить странные вещи (так называемый "Heisenbugs") если программа спроектирована не достаточно внимательно. В частности из-за параллельной природы потоков, выполняемый код не может выполняться в разных потоках, если программист явно не назначил это через синхронизацию примитивов.

Цель связанных с потоком функций в GLib заключается в обеспечении переносимого способа создания многопоточных программ. Есть примитивы для взаимоисключений для защиты доступа к участкам памяти (GMutex, GStaticMutex, G_LOCK_DEFINE, GStaticRecMutex и GStaticRWLock). Есть примитивы для переменных условий позволяющие синхронизацию потоков (GCond). Есть примитивы для закрытых потоковых данных - данных которые каждый поток имеет закрытый экземпляр (GPrivate, GStaticPrivate). И не в последнюю очередь есть примитивы для портативного создания и управления потоками (GThread).

Вы должны вызывать g_thread_init() перед выполнением любых других функций GLib в потоковых GLib программах. После этого, GLib полностью потоко-безопасен (все глобальные данные автоматически блокируются), но индивидуальные экземпляры структур данных не блокируются автоматически по причине выполнения. Поэтому, например вы должны координировать доступ к одной и той же GHashTable из множества потоков. Известно два исключения из этого правила GMainLoop и GAsyncQueue, которые являются потоко-безопасными и не нуждаются в дальнейшей блокировки на уровне приложения для доступности из множества потоков.

Детали

G_THREADS_ENABLED

#define G_THREADS_ENABLED

Этот макрос определяется если GLib была скомпилирована с поддержкой потоков. Это не означает обязательную доступность реализации потоков, но это значит что необходимая инфраструктура на месте и как только вы обеспечите реализацию потоков в g_thread_init(), GLib станет потоко-безопасной. Если G_THREADS_ENABLED не определён, то Glib не может быть безопасной для много-поточности.


G_THREADS_IMPL_POSIX

#define G_THREADS_IMPL_POSIX

Этот макрос определяется если используется стиль потоков POSIX.


G_THREADS_IMPL_NONE

#define G_THREADS_IMPL_NONE

Этот макрос определяется если нет используемой реализации потоков. Вы можете однако обеспечить это с помощью g_thread_init() для создания безопасной много-поточности GLib.


G_THREAD_ERROR

#define G_THREAD_ERROR g_thread_error_quark ()

Область ошибок в подсистеме потоков GLib.


enum GThreadError

typedef enum
{
  G_THREAD_ERROR_AGAIN /* Ресурс временно не доступен */
} GThreadError;

Возможные ошибки связанные с функциями потока.

G_THREAD_ERROR_AGAIN поток не создан из-за нехватки ресурсов. Попробуйте повторить попытку позже.

GThreadFunctions

typedef struct {
  GMutex*  (*mutex_new)           (void);
  void     (*mutex_lock)          (GMutex               *mutex);
  gboolean (*mutex_trylock)       (GMutex               *mutex);
  void     (*mutex_unlock)        (GMutex               *mutex);
  void     (*mutex_free)          (GMutex               *mutex);
  GCond*   (*cond_new)            (void);
  void     (*cond_signal)         (GCond                *cond);
  void     (*cond_broadcast)      (GCond                *cond);
  void     (*cond_wait)           (GCond                *cond,
                                   GMutex               *mutex);
  gboolean (*cond_timed_wait)     (GCond                *cond,
                                   GMutex               *mutex,
                                   GTimeVal             *end_time);
  void      (*cond_free)          (GCond                *cond);
  GPrivate* (*private_new)        (GDestroyNotify        destructor);
  gpointer  (*private_get)        (GPrivate             *private_key);
  void      (*private_set)        (GPrivate             *private_key,
                                   gpointer              data);
  void      (*thread_create)      (GThreadFunc           func,
                                   gpointer              data,
                                   gulong                stack_size,
                                   gboolean              joinable,
                                   gboolean              bound,
                                   GThreadPriority       priority,
                                   gpointer              thread,
                                   GError              **error);
  void      (*thread_yield)       (void);
  void      (*thread_join)        (gpointer              thread);
  void      (*thread_exit)        (void);
  void      (*thread_set_priority)(gpointer              thread,
                                   GThreadPriority       priority);
  void      (*thread_self)        (gpointer              thread);
  gboolean  (*thread_equal)       (gpointer              thread1,
				   gpointer              thread2);
} GThreadFunctions;

Эта таблица функций используется g_thread_init() для инициализации системы потоков. Функции в таблице непосредственно используются их копиями с предустановленным в названиях g_* (описаны в данном документе). Например, если вы вызвали g_mutex_new(), тогда будет вызвана mutex_new() из таблицы g_thread_init().

Примечание

Не используйте эту структуры если не уверены в том что делаете.


g_thread_init ()

void        g_thread_init                   (GThreadFunctions *vtable);

Если вы используете GLib из более одного потока, вы должны инициализировать систему потоков вызовом g_thread_init(). В основном вам нужно вызывать g_thread_init (NULL).

Примечание

Не вызывайте g_thread_init() с не-NULL параметром если не уверены в том что делаете.

Примечание

g_thread_init() не должна вызываться непосредственно или косвенно как callback из GLib. Также взаимоисключения не могут блокироваться в течении вызова g_thread_init().

g_thread_init() можно вызвать только один раз. Второй вызов вернёт ошибку. Если вы хотите убедиться в том что система потоков инициализирована, вы можете сделать следующее:

if (!g_thread_supported ()) g_thread_init (NULL);

После этой команды либо инициализируется система потоков либо, ели нет доступной системы потоков в GLib (то есть либо G_THREADS_ENABLED не определён, либо определён G_THREADS_IMPL_NONE), программа будет отменена.

Если нет доступной системы потоков и параметр vtable равен NULL, или если не все элементы vtable являются не-NULL, то g_thread_init() будет отменён.

Примечание

Для использования g_thread_init() в вашей программе, вы должны привязаться к библиотекам которые выдаёт команда pkg-config --libs gthread-2.0. Это не касается остальных связанных с потоками функций GLib. Они могут использоваться без привязки к потоковым библиотекам.

vtable : таблица функций типа GThreadFunctions, которые обеспечивают точки входа в используемую систему потоков.

g_thread_supported ()

gboolean    g_thread_supported              ();

Эта функция возвращает TRUE если система потоков инициализирована, а FALSE если нет.

Примечание

Эта функция является фактически макрокомандой. Однако, кроме захвата адреса её можно использовать как функуию.

Возвращает : TRUE, если система потоков инициализирована.

GThreadFunc ()

gpointer    (*GThreadFunc)                  (gpointer data);

Определяет тип функций func помещаемых в g_thread_create() или g_thread_create_full().

data : данные помещаемые в поток.
Возвращает : значение возвращаемое потоком, которое будет возвращено g_thread_join().

enum GThreadPriority

typedef enum
{
  G_THREAD_PRIORITY_LOW,
  G_THREAD_PRIORITY_NORMAL,
  G_THREAD_PRIORITY_HIGH,
  G_THREAD_PRIORITY_URGENT
} GThreadPriority;

Определяет приоритет потока.

Примечание

Не гарантируется что потоки с разными приоритетами будут вести себя соответственно. В некоторых системах (например Linux) нет приоритетов потоков. В других системах (например Solaris) существует разное планирование для разных приоритетов. В основном пытайтесь избегать зависимости от приоритетов.

G_THREAD_PRIORITY_LOW приоритет ниже нормального
G_THREAD_PRIORITY_NORMAL приоритет по умолчанию
G_THREAD_PRIORITY_HIGH приоритет выше нормального
G_THREAD_PRIORITY_URGENT наивысший приоритет

GThread

typedef struct {
} GThread;

GThread структура представляет выполняемый поток. Она имеет три общих элемента доступных только для чтения, но основных в структуре больше, поэтому вы не должны копировать эту структуру.

Примечание

Ресурсы для объединяемого потока реализуются не полностью пока для этого потока вызвана g_thread_join().


g_thread_create ()

GThread*    g_thread_create                 (GThreadFunc func,
                                             gpointer data,
                                             gboolean joinable,
                                             GError **error);

Эта функция создаёт новый поток с приоритетом по умолчанию.

Если joinable равен TRUE, вы можете подождать завершения потоков вызывающих g_thread_join(). Иначе поток просто исчезнет когда она завершиться.

Новый поток выполняет функцию func с параметром data. Если поток был создан успешно, он возвращается.

error может быть NULL для игнорирования ошибок, или не-NULL для сообщения об ошибках. Ошибка устанавливается только если функция возвращает NULL.

func : функция выполняемая в новом потоке.
data : аргумент поставляемый новому потоку.
joinable : должен ли поток быть объединяемым?
error : размещение для возвращаемой ошибки.
Возвращает : новый GThread при успешном выполнении.

g_thread_create_full ()

GThread*    g_thread_create_full            (GThreadFunc func,
                                             gpointer data,
                                             gulong stack_size,
                                             gboolean joinable,
                                             gboolean bound,
                                             GThreadPriority priority,
                                             GError **error);

Эта функция создаёт поток с приоритетом priority. Если реализация потока поддерживает это, поток получает размер стека stack_size или значение по умолчанию для текущей платформы, если stack_size это 0.

Если joinable равно TRUE, вы можете подождать завершения вызова g_thread_join() для потока. Иначе поток просто исчезнет при завершении. Если bound равен TRUE, этот поток будет планироваться в системной области, иначе реализация это свободно выполняемое планирование в пределах процесса. Первый вариант более требователен к ресурсам, но в общем быстрее. В некоторых системах (например Linux) все потоки связаны.

Новый поток выполняет функцию func с аргументом data. Если поток был успешно создан, он возвращается.

error может быть NULL для игнорирования ошибок, или не-NULL для сообщения об ошибках. Ошибка устанавливается, только если функция вернула NULL.

Примечание

Не гарантируется что потоки с разными приоритетами будут вести себя соответственно. В некоторых системах (например Linux) нет приоритетов потоков. В других системах (например Solaris) существует разное планирование для разных приоритетов. В основном пытайтесь избегать зависимости от приоритетов. Используйте G_THREAD_PRIORITY_NORMAL здесь как значение по умолчанию.

Примечание

Используйте g_thread_create_full() только если вы действительно не можете использовать g_thread_create() вместо неё. g_thread_create() не применяет stack_size, bound, и priority как аргументы, поскольку они должны использоваться только если это явно не избежно.

func : функция для выполнения в новом потоке.
data : аргумент поставляемый в новый поток.
stack_size : размер стека для нового потока.
joinable : должен ли этот поток быть объединяемым?
bound : должен ли этот поток привязываться к системе потоков?
priority : приоритет потока.
error : расположение для возвращаемой ошибки.
Возвращает : новый GThread при удачном выполнении.

g_thread_self ()

GThread*    g_thread_self                   (void);

Эта функция возвращает GThread соответствующий вызываемому потоку.

Возвращает : текущий поток.

g_thread_join ()

gpointer    g_thread_join                   (GThread *thread);

Ждёт завершения thread, то есть функции func, полученной в g_thread_create(), возврат или g_thread_exit() вызванный thread. Все ресурсы thread включая структуру GThread освобождаются. thread должен быть создан с joinable=TRUE в g_thread_create(). Значение возвращаемое func или полученное в g_thread_exit()thread возвращается этой функцией.

thread : GThread из которого ожидается результат.
Возвращает : возвращаемое потоком значение.

g_thread_set_priority ()

void        g_thread_set_priority           (GThread *thread,
                                             GThreadPriority priority);

Изменяет приоритет thread в значение priority.

Примечание

Не гарантируется что потоки с разными приоритетами будут вести себя соответственно. В некоторых системах (например Linux) нет приоритетов потоков. В других системах (например Solaris) существует разное планирование для разных приоритетов. В основном пытайтесь избегать зависимости от приоритетов.

thread : GThread.
priority : новый приоритет для thread.

g_thread_yield ()

void        g_thread_yield                  ();

Позволяет запланировать другой поток.

Эта функция часто используется как метод для создания занятого ожидания менее вредным. Но в большинстве случаев есть лучше методы для этого. Поэтому в основном вы не должны использовать эту функцию.


g_thread_exit ()

void        g_thread_exit                   (gpointer retval);

Выход из текущего потока. Если другой поток ожидает завершение этого потока используя функцию g_thread_join() и текущий поток является совмещённым, то ожидающий поток будет разбужен и получит retval как возвращаемое значение g_thread_join(). Если текущий поток не совмещён, retval игнорируется. Вызов

g_thread_exit (retval);

эквивалентен вызову

return retval;

в функции func, полученной в g_thread_create().

Примечание

Никогда не вызывайте g_thread_exit() внутри потока GThreadPool, так как это запутает расчеты и приведёт к нежелательным последствиям.

retval : значение возвращаемое этим потоком.

g_thread_foreach ()

void        g_thread_foreach                (GFunc thread_func,
                                             gpointer user_data);

Вызывает thread_func на всех существующих структурах GThread. Помните, что потоки могут принять решение о выходе в то время как thread_func выполняется, поэтому без близкого знания продолжительности жизни внешних потоков, thread_func не имеет доступа к указателю GThread* помещаемому в первый аргумент. Однако, thread_func не будет вызвана для потоков выход из которых уже совершён.

Из-за проверок жизненного цикла потока, эта функция имеет сложности при выполнении которые взводятся в степень количества существующих потоков.

thread_func : функция вызываемая для всех структур GThread
user_data : второй аргумент для thread_func

Начиная с версии 2.10


GMutex

typedef struct _GMutex GMutex;

Структура GMutex - закрытая структура данных представляющая взаимоисключения (mutex - mutual exclusion). Она может использоваться для защиты данных от совместного доступа. Возьмём например следующую функцию:

Пример 3. Функция которая не будет работать в потоковом окружении

  int give_me_next_number ()
  {
    static int current_number = 0;

    /* теперь выполняем очень cложное вычисление для расчёта нового числа,
       это может быть например генератор случайных чисел */
    current_number = calc_next_number (current_number); 
    return current_number;
  }

Просто заметить что это не будет работать в многопоточных приложениях. Переменная current_number должна быть защищена от совместного доступа. Первая наивная реализация могла бы быть такой:

Пример 4. Не правильный способ создания потоко-безопасной функции

  int give_me_next_number ()
  {
    static int current_number = 0;
    int ret_val;
    static GMutex * mutex = NULL;

    if (!mutex)
      mutex = g_mutex_new ();
    g_mutex_lock (mutex);
    ret_val = current_number = calc_next_number (current_number); 
    g_mutex_unlock (mutex);
    return ret_val;
  }

Похоже что это должно работать, но есть условие гонки пока создаётся взаимоисключение и этот код не может надежно работать. Пожалуйста не используйте эту конструкцию в собственных программах! Вот одно работающее решение:

Пример 5. A correct thread-safe function

  static GMutex *give_me_next_number_mutex = NULL;

  /* эта функция должна быть вызвана перед любым вызовом give_me_next_number ()
     она должна вызываться только один раз. */
  void init_give_me_next_number () 
  {
    g_assert (give_me_next_number_mutex == NULL);
    give_me_next_number_mutex = g_mutex_new ();
  }

  int give_me_next_number ()
  {
    static int current_number = 0;
    int ret_val;

    g_mutex_lock (give_me_next_number_mutex);
    ret_val = current_number = calc_next_number (current_number); 
    g_mutex_unlock (give_me_next_number_mutex);
    return ret_val;
  }

GStaticMutex обеспечивает более простой и безопасный способ выполнения этого.

Если вы хотите использовать взаимоисключения и ваш код должен также работать не вызывая сначала g_thread_init(), то вы не можете использовать GMutex, так как g_mutex_new() требует инициализации системы потоков. Вместо этого используйте GStaticMutex.

Доступ к GMutex должен производиться только с помощью функций описанных ниже.

Примечание

Все g_mutex_* функции фактически являются макрокомандами. Кроме взятия адреса, вы можете однако использовать их как будто они являются функциями.


g_mutex_new ()

GMutex*     g_mutex_new                     ();

Создаёт новую структуру GMutex.

Примечание

Эта функция прерывается если не вызвана g_thread_init().

Возвращает : новая структура GMutex.

g_mutex_lock ()

void        g_mutex_lock                    (GMutex *mutex);

Блокирует mutex. Если mutex уже блокирован другим потоком, то текущий поток блокируется пока mutex не будет разблокирован.

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае она не делает ничего.

Примечание

GMutex не гарантирует не рекурсию не её отсутсвие, то есть поток может зависнуть вызывая g_mutex_lock(), если она уже заблокировала mutex. Используйте GStaticRecMutex, если вам нужны рекурсивные взаимоисключения.

mutex : GMutex.

g_mutex_trylock ()

gboolean    g_mutex_trylock                 (GMutex *mutex);

Пытается блокировать mutex. Если mutex уже заблокирован другим потоком, она немедленно возвращает FALSE. Иначе блокируется mutex и возвращается TRUE.

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае она немедленно вернёт TRUE.

Примечание

GMutex не гарантирует рекурсию не её отсутсвие, то есть возвращаемое значение g_mutex_trylock() может быть и FALSE и TRUE, если текущий поток уже заблокировал mutex. Используйте GStaticRecMutex, если вам нужны рекурсивные взаимоисключения.

mutex : GMutex.
Возвращает : TRUE, если mutex может быть заблокирован.

g_mutex_unlock ()

void        g_mutex_unlock                  (GMutex *mutex);

Разблокирует mutex. Если другой поток блокирован в g_mutex_lock() вызовом для mutex, то он будет разбужен и сможет заблокировать mutex самостоятельно.

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае она ничего не делает.

mutex : GMutex.

g_mutex_free ()

void        g_mutex_free                    (GMutex *mutex);

Уничтожает mutex.

mutex : GMutex.

GStaticMutex

typedef struct _GStaticMutex GStaticMutex;

GStaticMutex работает также как GMutex, но имеет одно существенное преимущество. Она не должна создаваться во время выполнения как GMutex, а может быть определена во время компиляции. Вот более короткий и более безопасный пример нашей функции give_me_next_number():

Пример 6. Использование GStaticMutex для упрощения потокобезопасного программирования

  int give_me_next_number ()
  {
    static int current_number = 0;
    int ret_val;
    static GStaticMutex mutex = G_STATIC_MUTEX_INIT;

    g_static_mutex_lock (&mutex);
    ret_val = current_number = calc_next_number (current_number); 
    g_static_mutex_unlock (&mutex);
    return ret_val;
  }

Иногда вам может понадобиться создавать динамические взаимоисключения. Если вы не хотите предварительно вызывать g_thread_init(), потому что ваш код должен также использоваться в не потоковых программах, вы не сможете использовать g_mutex_new() а также GMutex, так как требуется предварительный вызов g_thread_init(). В этом случае вы также можете использовать GStaticMutex. Она должна быть инициализирована перед использованием с помощью g_static_mutex_init() и освобождена с помощью g_static_mutex_free() когда нет больше никаких освобождаемых распределённых ресурсов.

Даже при том, что GStaticMutex не непрозрачная структура, она должна использоваться только следующими функциями, так как она определяется по разному на разных платформах.

Все функции g_static_mutex_* могут использоваться даже если не была вызвана g_thread_init().

Примечание

Все функции g_static_mutex_* фактически являются макросами. Однако, кроме взятия адреса, вы можете использовать их как функции.


G_STATIC_MUTEX_INIT

#define G_STATIC_MUTEX_INIT

С помощью этого макроса должна инициализироваться GStaticMutex, перед использованием. Этот макрос может использоваться для инициализации переменной, но он не может присваиваться переменной. В этом случае вы должны использовать g_static_mutex_init().

GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;


g_static_mutex_init ()

void        g_static_mutex_init             (GStaticMutex *mutex);

Инициализирует mutex. Альтернативно его можно инициализировать с помощью G_STATIC_MUTEX_INIT.

mutex : GStaticMutex для инициализации.

g_static_mutex_lock ()

void        g_static_mutex_lock             (GStaticMutex *mutex);

Работает как g_mutex_lock(), но для GStaticMutex.

mutex : GStaticMutex.

g_static_mutex_trylock ()

gboolean    g_static_mutex_trylock          (GStaticMutex *mutex);

Работает как g_mutex_trylock(), но для GStaticMutex.

mutex : GStaticMutex.
Возвращает : TRUE, если GStaticMutex может быть заблокирован.

g_static_mutex_unlock ()

void        g_static_mutex_unlock           (GStaticMutex *mutex);

Работает как g_mutex_unlock(), но для GStaticMutex.

mutex : GStaticMutex.

g_static_mutex_get_mutex ()

GMutex*     g_static_mutex_get_mutex        (GStaticMutex *mutex);

Для некоторых операций (как g_cond_wait()) вы должны использовать GMutex вместо GStaticMutex. Эта функция соответственно возвращает GMutex для mutex.

mutex : GStaticMutex.
Возвращает : GMutex соответствующий mutex.

g_static_mutex_free ()

void        g_static_mutex_free             (GStaticMutex *mutex);

Освобождает все ресурсы распределённые для mutex.

Вы не должны вызывать эту функцию для GStaticMutex с неограниченным жизненным циклом, то есть для объектов объявленных как 'static', но если GStaticMutex является членом структуры и структура освобождается, вы должны также освободить GStaticMutex.

mutex : GStaticMutex для освобождения.

G_LOCK_DEFINE()

#define     G_LOCK_DEFINE(name)

Макрос G_LOCK_* обеспечивает удобный интерфейс для GStaticMutex с преимуществом распространения для программ скомпилированных без поддержки потоков GLib, сохраняя код и память. G_LOCK_DEFINE определяет блокировку. Он может появляться там же где могут появляться переменные в программах, то есть в первом блоке функции или вне функций. Параметр name будет изменён для получения имени GStaticMutex. Это значит что вы можете использовать имена существующих переменных как параметр - например имя переменной вы можете защитить с помощью блокировки. Рассмотрим наш пример give_me_next_number() с использованием G_LOCK_* macros:

Пример 7. Использование удобного макроса G_LOCK_*

G_LOCK_DEFINE (current_number);

int give_me_next_number ()
  {
    static int current_number = 0;
    int ret_val;

    G_LOCK (current_number);
    ret_val = current_number = calc_next_number (current_number); 
    G_UNLOCK (current_number);
    return ret_val;
  }

name : имя блокировки.

G_LOCK_DEFINE_STATIC()

#define     G_LOCK_DEFINE_STATIC(name)

Работает также как G_LOCK_DEFINE, но создаёт статический объект.

name : имя блокировки.

G_LOCK_EXTERN()

#define     G_LOCK_EXTERN(name)

Объявляет блокировку, которая определена с помощью G_LOCK_DEFINE в другом модуле.

name : имя блокировки.

G_LOCK()

#define     G_LOCK(name)

Работает также как g_mutex_lock(), но для блокировки определённой с помощьюG_LOCK_DEFINE.

name : имя блокировки.

G_TRYLOCK()

#define     G_TRYLOCK(name)

Работает также как g_mutex_trylock(), но для блокировки определённой с помощью G_LOCK_DEFINE.

name : имя блокировки.
Возвращает : TRUE, если блокировка может быть блокирована.

G_UNLOCK()

#define     G_UNLOCK(name)

Работает также как g_mutex_unlock(), но для блокировки определённой с помощью G_LOCK_DEFINE.

name : имя блокировки.

GStaticRecMutex

typedef struct {
} GStaticRecMutex;

GStaticRecMutex работает также как GStaticMutex, но он может быть блокирован множество раз одним потоком. Если вы ввели его n раз, вы должны разблокировать его n раз позволяя другим потокам блокировать его. Исключением является функция g_static_rec_mutex_unlock_full(): она позволяет вам разблокировать GStaticRecMutex на всю глубину полностью, (то есть на то количество раз на которое был заблокирован этот объект mutex). Глубина может позже использоваться для восстановления состояния GStaticRecMutex с помощью вызова g_static_rec_mutex_lock_full().

Даже при том, что GStaticRecMutex не является закрытой, она должна использоваться только следующими функциями.

Все функции g_static_rec_mutex_* могут использоваться даже если не была вызвана g_thread_init().


G_STATIC_REC_MUTEX_INIT

#define G_STATIC_REC_MUTEX_INIT { G_STATIC_MUTEX_INIT }

GStaticRecMutex должна быть инициализирована с помощью макроса перед использованием. Этот макрос может использоваться для инициализации переменных, но он не должен назначаться переменным. Для этого случая используется g_static_rec_mutex_init().

GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;


g_static_rec_mutex_init ()

void        g_static_rec_mutex_init         (GStaticRecMutex *mutex);

GStaticRecMutex должна инициализироваться с помощью этой функции перед использованием. Альтернативно вы можете инициализировать её с помощью G_STATIC_REC_MUTEX_INIT.

mutex : GStaticRecMutex для инициализации.

g_static_rec_mutex_lock ()

void        g_static_rec_mutex_lock         (GStaticRecMutex *mutex);

Блокирует mutex. Если mutex уже заблокирован другим потоком, текущий поток будет заблокирован пока mutex не разблокируется. Если mutex уже заблокирован вызываемым потоком, эта функция увеличит глубину блокировки mutex и немедленно возвратит.

mutex : GStaticRecMutex для блокирования.

g_static_rec_mutex_trylock ()

gboolean    g_static_rec_mutex_trylock      (GStaticRecMutex *mutex);

Пытается блокировать mutex. Если mutex уже заблокирован другим потоком, она немедленно возвращает FALSE. Иначе mutex блокируется и возвращается TRUE. Если mutex уже заблокирован вызываемым потоком, эта функция увеличивает глубину блокировки mutex и немедленно возвращает TRUE.

mutex : GStaticRecMutex для блокировки.
Возвращает : TRUE, если mutex может быть заблокирован.

g_static_rec_mutex_unlock ()

void        g_static_rec_mutex_unlock       (GStaticRecMutex *mutex);

Разблокирует mutex. Другой поток может быть допущен к блокировки mutex только когда он будет разблокирован такое же количество раз сколько раз был заблокирован перед этим. Если mutex полностью разблокирован а другой поток блокирован в g_static_rec_mutex_lock() вызове для mutex, он будет разбужен и сможет заблокировать mutex самостоятельно.

mutex : GStaticRecMutex для разблокирования.

g_static_rec_mutex_lock_full ()

void        g_static_rec_mutex_lock_full    (GStaticRecMutex *mutex,
                                             guint depth);

Работает также как вызов g_static_rec_mutex_lock() для mutex depth раз.

mutex : GStaticRecMutex для разблокирования.
depth : количество разблокирований для полного разблокирования.

g_static_rec_mutex_unlock_full ()

guint       g_static_rec_mutex_unlock_full  (GStaticRecMutex *mutex);

Полностью разблокирует mutex. Если другой поток блокирован в g_static_rec_mutex_lock() вызове для mutex, он будет разбужен и сможет заблокировать mutex самостоятельно. Эта функция возвращает количество раз которое mutex был заблокирован текущим потоком. Для восстановления состояния перед вызовом g_static_rec_mutex_unlock_full() вы можете вызвать g_static_rec_mutex_lock_full() с глубиной возвращаемой этой функцией.

mutex : GStaticRecMutex для полного разблокирования.
Возвращает : количество раз которым mutex был заблокирован текущим процессом.

g_static_rec_mutex_free ()

void        g_static_rec_mutex_free         (GStaticRecMutex *mutex);

Освобождает все ресурсы распределённые для GStaticRecMutex.

Вы не должны вызывать эту функцию для GStaticRecMutex с безграничным жизненным циклом, то есть для объектов объявленных как 'static', но если GStaticRecMutex является членом освобождаемой структуры, вы должны также освободить GStaticRecMutex.

mutex : GStaticRecMutex для освобождения.

GStaticRWLock

typedef struct {
} GStaticRWLock;

Структура GStaticRWLock представляет блокировку чтения-записи. Блокировка чтения-записи может использоваться для защиты данных которые некоторые части кода только читают, в то время как другие также записывают. В таких ситуациях конечно лучше чтобы читать могли несколько процессов/потоков одновременно, а писать только один. Рассмотрим следующий пример:

Пример 8. Массив с функциями доступа

  GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;

  GPtrArray *array;

  gpointer my_array_get (guint index)
  {
    gpointer retval = NULL;

    if (!array)
      return NULL;

    g_static_rw_lock_reader_lock (&rwlock);

    if (index < array->len)
      retval = g_ptr_array_index (array, index);

    g_static_rw_lock_reader_unlock (&rwlock);

    return retval;
  }

  void my_array_set (guint index, gpointer data)
  {
    g_static_rw_lock_writer_lock (&rwlock);

    if (!array)
      array = g_ptr_array_new ();

    if (index >= array->len)
      g_ptr_array_set_size (array, index+1);

    g_ptr_array_index (array, index) = data; 

    g_static_rw_lock_writer_unlock (&rwlock);
  }

Этот пример демонстрирует массив доступ к которому позволен многим "читателям" (my_array_get() функция) одновременно, тогда как "писателям" (my_array_set() функция) он доступен только одному за раз и только если нет "читателей" обращающихся к массиву в текущий момент. Это из-за потенциальной опасности изменения размера массива. При таком использовании функции полностью безопасны в много-поточности.

В большинстве случаев, "писатель" должен иметь преимущество перед "читателями". Это значит, для этой реализации, как только "писатель" захочет блокировать данные никому из "читателей" не позволено блокировать их, хотя "читателям" которые уже блокировали данные конечно позволено завершить свои операции. Как только последний "читатель" разблокировал данные, "писатель" блокирует их.

Даже при том, что структура GStaticRWLock не является закрытой, доступ к ней должен осуществляться только с помощью функций описанных ниже.

Все функции g_static_rw_lock_* могут использоваться даже если g_thread_init() не была вызвана.

Примечание

Блокировка чтение-запись имеет приоритет над взаимоисключениями (mutex). Например, обе g_static_rw_lock_reader_lock() и g_static_rw_lock_reader_unlock() должны блокировать и разблокировать GStaticMutex, поэтому по крайней мере дважды блокируется и разблокируется GStaticRWLock который в свою очередь блокирует и разблокирует GStaticMutex. Таким образом структуры данных которые доступны для множества "читателей" и которые сохраняют блокировку в течении длительного времени оправдывают GStaticRWLock. Выше упомянутый пример вероятней всего намного лучше использовать с GStaticMutex.


G_STATIC_RW_LOCK_INIT

#define G_STATIC_RW_LOCK_INIT { G_STATIC_MUTEX_INIT, NULL, NULL, 0, FALSE, 0, 0 }

GStaticRWLock должна быть инициализирована макросом перед использованием. Этот макрос может использоваться для инициализации переменных, но он не должен присваиваться переменным. В этом случае вы должны использовать g_static_rw_lock_init().

GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;


g_static_rw_lock_init ()

void        g_static_rw_lock_init           (GStaticRWLock *lock);

GStaticRWLock должна быть инициализирована с помощью этой функции перед использованием. Альтернативно вы можете инициализировать её с помощью G_STATIC_RW_LOCK_INIT.

lock : GStaticRWLock для инициализации.

g_static_rw_lock_reader_lock ()

void        g_static_rw_lock_reader_lock    (GStaticRWLock *lock);

Блокирует lock для чтения. Могут быть бесконечные параллельные блокировки для одновременного чтения GStaticRWLock. Если lock уже заблокирован для записи другим потоком или если другой поток уже ожидает блокировки lock для записи, эта функция будет блокирована пока lock не разблокирует другой поток записи и никакие другие потоки не ожидают блокировки lock. Эта блокировка должна разблокироваться с помощью g_static_rw_lock_reader_unlock().

GStaticRWLock не имеет рекурсии. Это может показаться возможным для рекурсивной блокировки чтения, но может привести к зависанию из-за привилегий "писателя".

lock : GStaticRWLock для блокировки чтения.

g_static_rw_lock_reader_trylock ()

gboolean    g_static_rw_lock_reader_trylock (GStaticRWLock *lock);

Пытается блокировать lock для чтения. Если lock уже заблокирован для записи другим потоком или другой поток уже ожидает блокировку lock для записи, немедленно возвращает FALSE. Иначе блокирует lock для чтения и возвращает TRUE. Эта блокировка должна разблокироваться с помощью g_static_rw_lock_reader_unlock().

lock : GStaticRWLock для блокирования чтения.
Возвращает : TRUE, если lock можно блокировать для чтения.

g_static_rw_lock_reader_unlock ()

void        g_static_rw_lock_reader_unlock  (GStaticRWLock *lock);

Разблокирует lock. Если поток ожидает блокировку lock для записи и все блокировки для чтения были разблокированы, ожидающий поток пробуждается и может заблокировать lock для записи.

lock : GStaticRWLock для разблокирования после чтения.

g_static_rw_lock_writer_lock ()

void        g_static_rw_lock_writer_lock    (GStaticRWLock *lock);

Блокирует lock для записи. Если lock уже заблокирован для записи или чтения другим потоком, эта функция блокируется до тех пор пока lock полностью не разблокируется а затем блокирует lock для записи. Пока эта функция ожидает блокировки lock, другие потоки не могут блокировать lock для чтения. Когда lock заблокирован для записи, другие потоки не могут блокировать lock (не для чтения не для записи). Эта блокировка должна разблокироваться с помощью g_static_rw_lock_writer_unlock().

lock : GStaticRWLock блокируемая для записи.

g_static_rw_lock_writer_trylock ()

gboolean    g_static_rw_lock_writer_trylock (GStaticRWLock *lock);

Пытается блокировать lock для записи. Если lock уже заблокирован (для записи или чтенияg) другим потоком, она немедленно возвращает FALSE. Иначе блокирует lock для записи и возвращает TRUE. Эта блокировка должна быть разблокирована с помощью g_static_rw_lock_writer_unlock().

lock : GStaticRWLock блокируемая для записи.
Возвращает : TRUE, если lock может блокироваться для записи.

g_static_rw_lock_writer_unlock ()

void        g_static_rw_lock_writer_unlock  (GStaticRWLock *lock);

Разблокирует lock. Если поток ожидает блокировки lock для записи и все блокировки для чтения разблокированы, ожидающий поток просыпается и может блокировать lock для записи. Если не тпотоков ожидающих блокировки lock для записи, а некоторые потоки ожидают блокировку lock для чтения, ожидающие потоки просыпаются и могут блокировать lock для чтения.

lock : GStaticRWLock для разблокирования после записи.

g_static_rw_lock_free ()

void        g_static_rw_lock_free           (GStaticRWLock *lock);

Освобождает все ресурсы распределённые для lock.

Вы не должны вызывать эту функцию для GStaticRWLock с безграничным жизненным циклом, то есть для объектов объявленных статическими 'static', но если GStaticRWLock является частью структуры и структура освобождается, то вы также должны освободить GStaticRWLock.

lock : GStaticRWLock для освобождения.

GCond

typedef struct _GCond GCond;

Структура GCond является закрытой структурой данных представляющих условие. Потоки могут блокироваться на GCond если они обнаружат определённое ложное условие. Если другие потоки изменяют состояние этого условия они сообщают GCond и тогда ожидающий поток просыпается.

Пример 9. Использование GCond для блокировки потока пока условие не удавлетворено

GCond* data_cond = NULL;   /* Должен быть где-нибудь инициализирован */
GMutex* data_mutex = NULL; /* Должен быть где-нибудь инициализирован */
gpointer current_data = NULL;

void push_data (gpointer data)
{
  g_mutex_lock (data_mutex);
  current_data = data;
  g_cond_signal (data_cond);
  g_mutex_unlock (data_mutex);
}

gpointer pop_data ()
{
  gpointer data;

  g_mutex_lock (data_mutex);
  while (!current_data)
      g_cond_wait (data_cond, data_mutex);
  data = current_data;
  current_data = NULL;
  g_mutex_unlock (data_mutex);
  return data;
}

Теперь, каждый раз когда поток вызывает pop_data(), он будет ждать пока current_data будет не-NULL, то есть пока какой-нибудь поток вызовет push_data().

Примечание

Важно использовать g_cond_wait() и g_cond_timed_wait() функции только внутри цикла который проверяет правильность условия. Не гарантируется что ожидающий поток будет искать условие выполнения после пробуждения, даже если сообщающий поток сбросит условие в это состояние: другой поток может переключить условие прежде чем ожидающий поток проснётся, даже если само условие защищено с помощью GMutex, как описано выше.

GCond доступна только через функции описанные далее.

Примечание

Все g_cond_* функции фактически являются макросами. Однако, за исключением взятия адреса, вы можете использовать их как функции.


g_cond_new ()

GCond*      g_cond_new                      ();

Создаёт новую GCond. Эта функция прерывается, если не была вызвана g_thread_init().

Возвращает : новая GCond.

g_cond_signal ()

void        g_cond_signal                   (GCond *cond);

Если потоки ожидают условие cond, только один из них пробуждается. Хорошая практика удерживать блокировку ожидающего потока пока вызывается эта функция, хотя и необязательно.

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае она ничего не делает.

cond : GCond.

g_cond_broadcast ()

void        g_cond_broadcast                (GCond *cond);

Если потоки ожидают условие cond, все они пробуждаются. Хорошей практикой является блокирование ожидающих потоков некоторым взаимоисключением (mutex), пока вызывается эта функция, хотя не обязательно.

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае она ничего не делает.

cond : GCond.

g_cond_wait ()

void        g_cond_wait                     (GCond *cond,
                                             GMutex *mutex);

Заставляет поток ждать условие cond. Взаимоисключение mutex разблокируется перед отключением и блокируется после возобнавления.

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае она немедленно возвращает результат.

cond : GCond.
mutex : GMutex, который в настоящее время заблокирован.

g_cond_timed_wait ()

gboolean    g_cond_timed_wait               (GCond *cond,
                                             GMutex *mutex,
                                             GTimeVal *abs_time);

Заставляет поток ждать условия пробуждения cond, но не дольше чем определено параметром abs_time. Взаимоисключение mutex разблокируется перед отключением и блокируется снова после возобнавления.

Если abs_time равен NULL, g_cond_timed_wait() действует как g_cond_wait().

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае она немедленно возвращает TRUE.

Для простоты вычисления abs_time может использоваться комбинация g_get_current_time() и g_time_val_add().

cond : GCond.
mutex : GMutex который заблокирован в текущий момент.
abs_time : GTimeVal, определяющая максимальное время ожидания.
Возвращает : TRUE если об условии cond было сообщено, или FALSE при истечении времени ожидания.

g_cond_free ()

void        g_cond_free                     (GCond *cond);

Уничтожает GCond.

cond : GCond.

GPrivate

typedef struct _GPrivate GPrivate;

Структура GPrivate является закрытой структурой данных представляющая индивидуальные ключевые данные для потоков. Потоки таким образом могут устанавливать и получать указатели которые индивидуальны для текущего потока. Возьмём наш выше приведенный пример give_me_next_number(). Предположим что мы не хотим чтобы переменная current_number распределялясь между потоками, а вместо этого была бы индивидуальной для каждого потока. Это можно сделать следующим образом:

Пример 10. Using GPrivate for per-thread data

  GPrivate* current_number_key = NULL; /* Должна быть где-нибудь инициализирована */
                                       /* с помощью g_private_new (g_free); */

  int give_me_next_number ()
  {
    int *current_number = g_private_get (current_number_key);

    if (!current_number)
    {
      current_number = g_new (int,1);
      *current_number = 0;
      g_private_set (current_number_key, current_number);
    }
    *current_number = calc_next_number (*current_number); 
    return *current_number;
  }

Здесь указатель принадлежащий ключу current_number_key читается. Если он равен NULL, то не устанавливается. Затем получаем память для целочисленного значения, привязываем эту память к указателю и записываем указатель обратно. Теперь мы имеем целочисленное значение которое индивидуально для текущего потока.

К структуре GPrivate должны обращаться только следующие функции.

Примечание

Все функции g_private_* фактически являются макросами. Однако, за исключением взятия адреса, вы можете использовать их как обычные функции.


g_private_new ()

GPrivate*   g_private_new                   (GDestroyNotify destructor);

Создаёт новую GPrivate. Если destructor не-NULL, то указывает на разрушающую функцию. Каждый раз когда поток завершается и ключевой указатель соответствующий этому образцу GPrivate не является NULL, разрушающая функция вызывается с этим указателем в качестве параметра.

Примечание

destructor используется иначе чем notify в g_static_private_set().

Примечание

GPrivate не может освобождаться. Вместо этого используйте её повторно, или используйте GStaticPrivate.

Примечание

Эта функция прерывается если g_thread_init() не была вызвана.

destructor : функция для уничтожения ключевых данных в GPrivate когда поток завершён.
Возвращает : новая GPrivate.

g_private_get ()

gpointer    g_private_get                   (GPrivate *private_key);

Возвращает ключевой указатель private_key для текущего потока. Если g_private_set() не была вызвана для текущего private_key и потока, этот указатель будет NULL.

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае она возвращает значение private_key приведённый к gpointer.

private_key : GPrivate.
Возвращает : соответсвующий указатель.

g_private_set ()

void        g_private_set                   (GPrivate *private_key,
                                             gpointer data);

Устанавливает ключевой указатель private_key для текущего потока.

Эта функция может использоваться даже если g_thread_init() не была вызвана, в этом случае будет установлен private_key в data приведенный к GPrivate*.

private_key : GPrivate.
data : новый указатель.

GStaticPrivate

typedef struct {
} GStaticPrivate;

GStaticPrivate работает также как GPrivate, но имеет одно существенное приимущество. Она не должна создаваться во время выполнения как GPrivate, а может быть определена во время компиляции. Это подобно различию между GMutex и GStaticMutex. Теперь взглянем на наш пример give_me_next_number() с использованием GStaticPrivate:

Пример 11. Использование GStaticPrivate в качестве потоковых данных

  int give_me_next_number ()
  {
    static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
    int *current_number = g_static_private_get (&current_number_key);

    if (!current_number)
    {
      current_number = g_new (int,1);
      *current_number = 0;
      g_static_private_set (&current_number_key, current_number, g_free);
    }
    *current_number = calc_next_number (*current_number); 
    return *current_number;
  }


G_STATIC_PRIVATE_INIT

#define G_STATIC_PRIVATE_INIT 

Все GStaticPrivate перед использованием должны быть инициализированы этим макросом.

GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;


g_static_private_init ()

void        g_static_private_init           (GStaticPrivate *private_key);

Инициализирует private_key. Альтернативно вы можете инициализировать его с помощью G_STATIC_PRIVATE_INIT.

private_key : GStaticPrivate для инициализации.

g_static_private_get ()

gpointer    g_static_private_get            (GStaticPrivate *private_key);

Работает также как g_private_get() только для GStaticPrivate.

Эта функция работает даже если g_thread_init() не была вызвана.

private_key : GStaticPrivate.
Возвращает : соответствующий указатель.

g_static_private_set ()

void        g_static_private_set            (GStaticPrivate *private_key,
                                             gpointer data,
                                             GDestroyNotify notify);

Устанавливает ключевой указатель private_key для текущего потока и функцию notify вызываемую с этим указателем (NULL или не-NULL), каждый раз когда указатель установлен снова или каждый раз когда текущий поток завершается.

Эта функция работает даже если g_thread_init() не была вызвана. Если g_thread_init() вызвана позже, то data ключевые для private_key будут унаследованы только основным потоком, то есть тем который вызван g_thread_init().

Примечание

notify используется иначе чем destructor в g_private_new().

private_key : GStaticPrivate.
data : новый указатель.
notify : функция вызываемая с указателем каждый раз когда завершается текущий поток или указатель устанавливается снова.

g_static_private_free ()

void        g_static_private_free           (GStaticPrivate *private_key);

Освобождает все ресурсы распределённые для private_key.

Вы не должны вызывать эту функцию для GStaticPrivate с неограниченным жизненным циклом, то есть для объявленной статично 'static', но если GStaticPrivate член структуры и структура освобождается, вы должны также освободить GStaticPrivate.

private_key : освобождаемая GStaticPrivate.

GOnce

typedef struct {
  volatile GOnceStatus status;
  volatile gpointer retval;
} GOnce;

Структура GOnce контролирует одноразовую функцию инициализации. Любые одноразовые функции инициализации должны иметь собственную уникальную структуру GOnce.

volatile GOnceStatus status; состояние GOnce
volatile gpointer retval; возвращаемое значение, если status равен G_ONCE_STATUS_READY

Начиная с версии 2.4


enum GOnceStatus

typedef enum
{
  G_ONCE_STATUS_NOTCALLED,
  G_ONCE_STATUS_PROGRESS,
  G_ONCE_STATUS_READY  
} GOnceStatus;

Возвможные состояния одноразовых функций инициализации контролируемые структурой GOnce.

G_ONCE_STATUS_NOTCALLED функция не была вызвана.
G_ONCE_STATUS_PROGRESS вызов функции происходит в текущий момент.
G_ONCE_STATUS_READY функия вызвана.

Начиная с версии 2.4


G_ONCE_INIT

#define G_ONCE_INIT { G_ONCE_STATUS_NOTCALLED, NULL }

GOnce должна быть инициализирована перед использованием с помощью этого макроса.

GOnce my_once = G_ONCE_INIT;

Начиная с версии 2.4


g_once()

#define     g_once(once, func, arg)

Первый вызов с полученной структурой GOnce struct вызывает функцию func с полученным аргументом. Последующие вызовы g_once() с той же структурой GOnce не вызывают func снова, а возвращают сохранённый результат первого вызова. Возвращаемое из g_once() состояние once будет G_ONCE_STATUS_READY.

Например, взаимоисключение или ключевые потоковые данные должны быть созданы только один раз. В потоковом окружении, вызов g_once() гарантирует что инициализация преобразована в последовательную форму через множество потоков.

Примечание

Рекурсивный вызов g_once() на той же самой структуре GOnce в func приведёт к зависанию.

gpointer 
get_debug_flags()
{
  static GOnce my_once = G_ONCE_INIT;
  
  g_once (&my_once, parse_debug_flags, NULL);

  return my_once.retval;
}

once : структура GOnce
func : GThreadFunc функция ассоциированная с once. Эта функция вызывается только один раз, не зависимо от количества раз помещения структуры GOnce в g_once() .
arg : данные помещаемые в func

Начиная с версии 2.4

Смотрите также

GThreadPool

Объединённые потоки.

GAsyncQueue

Отправка асинхронных сообщений между потоками.


Timers

Timers — отслеживание истёкшего времени.

Краткое описание


#include <glib.h>


            GTimer;
GTimer*     g_timer_new                     (void);
void        g_timer_start                   (GTimer *timer);
void        g_timer_stop                    (GTimer *timer);
void        g_timer_continue                (GTimer *timer);
gdouble     g_timer_elapsed                 (GTimer *timer,
                                             gulong *microseconds);
void        g_timer_reset                   (GTimer *timer);
void        g_timer_destroy                 (GTimer *timer);

Описание

GTimer записывает начальное время и подсчитывает микросекунды прошедшие с этого времени. Это выполняется по разному на разных платформах и может быть сложно получить правильное соответсвие, поэтому GTimer обеспечивает переносимый/удобный интерфейс.

Детали

GTimer

typedef struct _GTimer GTimer;

Непрозрачный тип данных который записывает начальное время.


g_timer_new ()

GTimer*     g_timer_new                     (void);

Создаёт новый таймер и начинает отсчёт (то есть g_timer_start() не явно вызывается для вас).

Возвращает : новая структура GTimer.

g_timer_start ()

void        g_timer_start                   (GTimer *timer);

Отмечает начальное время, так, чтобы следующие вызовы g_timer_elapsed() сообщали время прошедшее с момента вызова g_timer_start(). g_timer_new() автоматически отмечает начальное время, поэтому нет необходимости вызывать g_timer_start() сразу после создания таймера.

timer : GTimer.

g_timer_stop ()

void        g_timer_stop                    (GTimer *timer);

Отмечает конечное время, поэтому вызовы g_timer_elapsed() будут возвращать разницу между конечным и начальным временем.

timer : GTimer.

g_timer_continue ()

void        g_timer_continue                (GTimer *timer);

Возобнавляет работу таймера который был предварительно остановлен с помощью g_timer_stop(). g_timer_stop() должна быть вызвана перед использованием этой функции.

timer : GTimer.

Начиная с версии 2.4


g_timer_elapsed ()

gdouble     g_timer_elapsed                 (GTimer *timer,
                                             gulong *microseconds);

Если timer был запущен но не остановлен, получает время так как таймер был запущен. Если timer был остановлен, получает прошедшее время между между временем начала и временем остановки. Возвращаемое значение является количеством прошедших секунд, включая любую дробную часть. Параметр microseconds бесполезен.

timer : GTimer.
microseconds : расположение для возвращаемой дробной части прошедших секунд, в микросекундах (то есть общее количество прошедших микросекунд, по модулю 1000000), или NULL
Возвращает : прошедшие секунды в виде значения с плавающей точкой, включая любую дробную часть.

g_timer_reset ()

void        g_timer_reset                   (GTimer *timer);

Эта функция бесполезна; достаточно вызвать g_timer_start() для уже запущенного таймера для сброса начального времени, поэтому g_timer_reset() нет смысла использовать.

timer : GTimer.

g_timer_destroy ()

void        g_timer_destroy                 (GTimer *timer);

Уничтожает таймер, освобождает связанные с ним ресурсы.

timer : GTimer для уничтожения.

Trash Stacks

Trash Stacks — Поддержка стека неиспользуемых распределённых частей памяти.

Краткое описание


#include <glib.h>


            GTrashStack;
void        g_trash_stack_push              (GTrashStack **stack_p,
                                             gpointer data_p);
gpointer    g_trash_stack_pop               (GTrashStack **stack_p);
gpointer    g_trash_stack_peek              (GTrashStack **stack_p);
guint       g_trash_stack_height            (GTrashStack **stack_p);

Описание

GTrashStack это эффективный способ сохранить стек неиспользуемых распределённых участков памяти. Каждый участок памяти должен быть достаточно большим для вмещения gpointer. Это позволяет поддержку стека без дополнительного пространства, так как стек указателей может быть сохранён внутри участка памяти.

Нет функции для создания GTrashStack. NULL GTrashStack* это совершенно правильный пустой стек.

Детали

GTrashStack

typedef struct {
  GTrashStack *next;
} GTrashStack;

Каждый участок памяти, который помещён в стек, приводится к GTrashStack*.

GTrashStack *next; указатель на предыдущий элемент стека, сохраняется в первом sizeof (gpointer) байте элемента.

g_trash_stack_push ()

void        g_trash_stack_push              (GTrashStack **stack_p,
                                             gpointer data_p);

Помещает участок памяти в GTrashStack.

stack_p : указатель на GTrashStack.
data_p : участок памяти помещаемый в стек.

g_trash_stack_pop ()

gpointer    g_trash_stack_pop               (GTrashStack **stack_p);

Выталкивает участок памяти из GTrashStack.

stack_p : указатель на GTrashStack.
Возвращает : верхний элемент стека.

g_trash_stack_peek ()

gpointer    g_trash_stack_peek              (GTrashStack **stack_p);

Возвращает верхний элемент GTrashStack, который может быть NULL.

stack_p : указатель на GTrashStack.
Возвращает : верхний элемент стека.

g_trash_stack_height ()

guint       g_trash_stack_height            (GTrashStack **stack_p);

Возвращает высоту GTrashStack. Помните что выполнение этой функции имеет сложность O(N), где N означает количество элементов стека.

stack_p : указатель на GTrashStack.
Возвращает : высота стека.

Макросы преобразования типов

Type Conversion Macros — Переносимый способ хранения целочисленных в указателях переменных.

Краткое описание


#include <glib.h>


#define     GINT_TO_POINTER                 (i)
#define     GPOINTER_TO_INT                 (p)

#define     GUINT_TO_POINTER                (u)
#define     GPOINTER_TO_UINT                (p)
#define     GSIZE_TO_POINTER                (s)
#define     GPOINTER_TO_SIZE                (p)

Описание

Часто GLib, GTK+ и другие библиотеки позволяют вам помещать "пользовательские данные" в callback-функции, в форме void указателей. Время от времени вам необходимо помещать целочисленные вместо указателей. Вы можете разместить целочисленное примерно так:

 int *ip = g_new (int, 1);
 *ip = 42;

Но это не удобно и требует в последствии освобождать память.

Указатели имеют размер всегда 32 бита (На всех платформах.GLib подразумевает поддержку). Поэтому вы можете хранить небольшие 32-битные целочисленные значения в указателях. Вы бы могли попробовать следующий способ, но он не верен:

 gpointer p;
 int i;
 p = (void*) 42;
 i = (int) p;

Ещё раз напоминаем пример выше не правильный, не копируйте его. Проблема в том, что на некоторых системах вы должны сделать так:

 gpointer p;
 int i;
 p = (void*) (long) 42;
 i = (int) (long) p;

Поэтому GPOINTER_TO_INT(), GINT_TO_POINTER(), и т.д. сделают эти вещи правильно на текущей платформе.

Внимание

ВЫ НЕ МОЖЕТЕ ХРАНИТЬ УКАЗАТЕЛИ В ЦЕЛЫХ ЧИСЛАХ. ЭТО НЕ ПЕРЕНОСИМО НИ В КАКОЙ ФОРМЕ. Эти макросы позволяют хранить ТОЛЬКО целочисленные в указателях, и хранят только 32 битные целочисленные; значения целочисленных за пределами диапазона 32-бит будут искажены.

Детали

GINT_TO_POINTER()

#define GINT_TO_POINTER(i)	((gpointer)  (i))

Помещает целочисленное в тип указателя.

Помните, ВЫ НЕ МОЖЕТЕ СОХРАНЯТЬ УКАЗАТЕЛИ В ЦЕЛОЧИСЛЕННЫХ. ЭТО НЕ ПЕРЕНОСИМЫЙ СПОСОБ ФОРМИРОВАНИЯ ИЛИ ФОРМЫ. Эти макросы позволяют хранить ТОЛЬКО целочисленные в указателях, и хранят только 32 битные целочисленные; значения целочисленных за пределами диапазона 32-бит будут искажены.

i : целочисленное для помещения в указатель.

GPOINTER_TO_INT()

#define GPOINTER_TO_INT(p)	((gint)   (p))

Извлекает целочисленное из указателя. Это целочисленное должно быть предварительно помещено в указатель с помощью GINT_TO_POINTER().

Помните, ВЫ НЕ МОЖЕТЕ СОХРАНЯТЬ УКАЗАТЕЛИ В ЦЕЛОЧИСЛЕННЫХ. ЭТО НЕ ПЕРЕНОСИМЫЙ СПОСОБ ФОРМИРОВАНИЯ ИЛИ ФОРМЫ. Эти макросы позволяют хранить ТОЛЬКО целочисленные в указателях, и хранят только 32 битные целочисленные; значения целочисленных за пределами диапазона 32-бит будут искажены.

p : указатель содержащий целочисленное.

GUINT_TO_POINTER()

#define GUINT_TO_POINTER(u)	((gpointer)  (u))

Помещает целочисленное без знака в тип указателя.

u : целочисленное без знака для помещения в указатель.

GPOINTER_TO_UINT()

#define GPOINTER_TO_UINT(p)	((guint)  (p))

Извлекает целочисленное без знака из указателя. Целочисленное должно быть предварительно помещено в указатель с помощью GUINT_TO_POINTER().

p : указатель содержащий целочисленное без знака.

GSIZE_TO_POINTER()

#define GSIZE_TO_POINTER(s)	((gpointer) (gsize) (s))

Помещает gsize в тип указателя.

s : gsize для помещения в указатель.

GPOINTER_TO_SIZE()

#define GPOINTER_TO_SIZE(p)	((gsize) (p))

Извлекает gsize из указателя. Предварительно gsize должен быть помещён в указатель с помощью GSIZE_TO_POINTER().

p : указатель для извлечения gsize.


Unicode Manipulation

Unicode Manipulation — функции оперирующие на Unicode символах и UTF-8 строках.

Краткое описание


#include <glib.h>


typedef     gunichar;
typedef     gunichar2;

gboolean    g_unichar_validate              (gunichar ch);
gboolean    g_unichar_isalnum               (gunichar c);
gboolean    g_unichar_isalpha               (gunichar c);
gboolean    g_unichar_iscntrl               (gunichar c);
gboolean    g_unichar_isdigit               (gunichar c);
gboolean    g_unichar_isgraph               (gunichar c);
gboolean    g_unichar_islower               (gunichar c);
gboolean    g_unichar_isprint               (gunichar c);
gboolean    g_unichar_ispunct               (gunichar c);
gboolean    g_unichar_isspace               (gunichar c);
gboolean    g_unichar_isupper               (gunichar c);
gboolean    g_unichar_isxdigit              (gunichar c);
gboolean    g_unichar_istitle               (gunichar c);
gboolean    g_unichar_isdefined             (gunichar c);
gboolean    g_unichar_iswide                (gunichar c);
gboolean    g_unichar_iswide_cjk            (gunichar c);
gunichar    g_unichar_toupper               (gunichar c);
gunichar    g_unichar_tolower               (gunichar c);
gunichar    g_unichar_totitle               (gunichar c);
gint        g_unichar_digit_value           (gunichar c);
gint        g_unichar_xdigit_value          (gunichar c);
enum        GUnicodeType;
GUnicodeType g_unichar_type                 (gunichar c);
enum        GUnicodeBreakType;
GUnicodeBreakType g_unichar_break_type      (gunichar c);
void        g_unicode_canonical_ordering    (gunichar *string,
                                             gsize len);
gunichar*   g_unicode_canonical_decomposition
                                            (gunichar ch,
                                             gsize *result_len);
gboolean    g_unichar_get_mirror_char       (gunichar ch,
                                             gunichar *mirrored_ch);
enum        GUnicodeScript;
GUnicodeScript g_unichar_get_script         (gunichar ch);

#define     g_utf8_next_char                (p)
gunichar    g_utf8_get_char                 (const gchar *p);
gunichar    g_utf8_get_char_validated       (const gchar *p,
                                             gssize max_len);
gchar*      g_utf8_offset_to_pointer        (const gchar *str,
                                             glong offset);
glong       g_utf8_pointer_to_offset        (const gchar *str,
                                             const gchar *pos);
gchar*      g_utf8_prev_char                (const gchar *p);
gchar*      g_utf8_find_next_char           (const gchar *p,
                                             const gchar *end);
gchar*      g_utf8_find_prev_char           (const gchar *str,
                                             const gchar *p);
glong       g_utf8_strlen                   (const gchar *p,
                                             gssize max);
gchar*      g_utf8_strncpy                  (gchar *dest,
                                             const gchar *src,
                                             gsize n);
gchar*      g_utf8_strchr                   (const gchar *p,
                                             gssize len,
                                             gunichar c);
gchar*      g_utf8_strrchr                  (const gchar *p,
                                             gssize len,
                                             gunichar c);
gchar*      g_utf8_strreverse               (const gchar *str,
                                             gssize len);
gboolean    g_utf8_validate                 (const gchar *str,
                                             gssize max_len,
                                             const gchar **end);

gchar*      g_utf8_strup                    (const gchar *str,
                                             gssize len);
gchar*      g_utf8_strdown                  (const gchar *str,
                                             gssize len);
gchar*      g_utf8_casefold                 (const gchar *str,
                                             gssize len);
gchar*      g_utf8_normalize                (const gchar *str,
                                             gssize len,
                                             GNormalizeMode mode);
enum        GNormalizeMode;
gint        g_utf8_collate                  (const gchar *str1,
                                             const gchar *str2);
gchar*      g_utf8_collate_key              (const gchar *str,
                                             gssize len);
gchar*      g_utf8_collate_key_for_filename (const gchar *str,
                                             gssize len);

gunichar2*  g_utf8_to_utf16                 (const gchar *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);
gunichar*   g_utf8_to_ucs4                  (const gchar *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);
gunichar*   g_utf8_to_ucs4_fast             (const gchar *str,
                                             glong len,
                                             glong *items_written);
gunichar*   g_utf16_to_ucs4                 (const gunichar2 *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);
gchar*      g_utf16_to_utf8                 (const gunichar2 *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);
gunichar2*  g_ucs4_to_utf16                 (const gunichar *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);
gchar*      g_ucs4_to_utf8                  (const gunichar *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);
gint        g_unichar_to_utf8               (gunichar c,
                                             gchar *outbuf);

Описание

Эта секция описывает множество функций для работы с Unicode символами и строками. Они аналогичны традиционной классификации символа ctype.h и функциям приведения и преобразования, UTF-8 аналогичны таким же строковым функциям, функции выполнения нормализации, преобразование регистра и сопоставление в UTF-8 строках и наконец функции для преобразования между UTF-8, UTF-16 и UCS-4 кодировками Unicode.

Реализация Unicode функций в GLib базируется на таблице данных символов Unicode (Unicode Character Data tables), которая доступна из www.unicode.org. GLib 2.8 поддерживает Unicode 4.0, GLib 2.10 поддерживает Unicode 4.1, GLib 2.12 поддерживает Unicode 5.0.

Детали

gunichar

typedef guint32 gunichar;

Тип который может содержать любой код символа UCS-4.


gunichar2

typedef guint16 gunichar2;

Тип который может содержать любой указатель кода UTF-16[3].


g_unichar_validate ()

gboolean    g_unichar_validate              (gunichar ch);

Проверяет является ли ch допустимым символом Unicode. Любые возможные целочисленные значения ch не будут допустимы. 0 рассматривается как правильный символ, хотя обычно он является концом строки.

ch : Unicode символ
Возвращает : TRUE если ch является допустимым Unicode символом.

g_unichar_isalnum ()

gboolean    g_unichar_isalnum               (gunichar c);

Определяет является ли символ алфавитно-цифровым. Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

c : Unicode символ
Возвращает : TRUE если c является алфавитно-цифровым символом

g_unichar_isalpha ()

gboolean    g_unichar_isalpha               (gunichar c);

Определяет является ли символ алфавитным (то есть буквой). Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

c : Unicode символ
Возвращает : TRUE если c является алфавитным символом

g_unichar_iscntrl ()

gboolean    g_unichar_iscntrl               (gunichar c);

Определяет является ли символ управляющим символом. Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

c : Unicode символ
Возвращает : TRUE если c является управляющим символом

g_unichar_isdigit ()

gboolean    g_unichar_isdigit               (gunichar c);

Определяет является ли символ числовым (то есть цифрой). Это распространяется на ASCII 0-9 а так же цифры в других языках/сценариях. Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

c : Unicode символ
Возвращает : TRUE если c является цифрой

g_unichar_isgraph ()

gboolean    g_unichar_isgraph               (gunichar c);

Определяет является ли символ печатным и не пробелом (возвращает FALSE для управляющих символов, символов форматирования, и пробелов). Похожа на g_unichar_isprint(), но возвращает TRUE для пробелов. Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

c : Unicode символ
Возвращает : TRUE если c является печатным символом отличающимся от пробела

g_unichar_islower ()

gboolean    g_unichar_islower               (gunichar c);

Определяет является ли символ буквой в нижнем регистре. Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

c : Unicode символ
Возвращает : TRUE если c является буквой нижнего регистра

g_unichar_isprint ()

gboolean    g_unichar_isprint               (gunichar c);

Определяет является ли символ печатным. В отличие от g_unichar_isgraph(), возвращает TRUE для пробелов. Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

c : Unicode символ
Возвращает : TRUE если c является печатным

g_unichar_ispunct ()

gboolean    g_unichar_ispunct               (gunichar c);

Определяет является ли символ символом пунктуации или знаком. Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

c : Unicode символ
Возвращает : TRUE если c является символом пунктуации или знаком

g_unichar_isspace ()

gboolean    g_unichar_isspace               (gunichar c);

Определяет является ли символ пробелом, табуляцией, или строковым разделителем (перевод строки, возврат каретки, и т.д.). Получая некоторый UTF-8 текст, определяет значение символа с помощью g_utf8_get_char().

(Помните: не нужно использовать это для прерывания слова; вы должны использовать Pango или эквивалент для получения правильного прерывания слова, алгоритм довольно сложен.)

c : Unicode символ
Возвращает : TRUE если c является символом пробела

g_unichar_isupper ()

gboolean    g_unichar_isupper               (gunichar c);

Определяет является ли символ символом верхнего регистра.

c : Unicode символ
Возвращает : TRUE если c является символом верхнего регистра

g_unichar_isxdigit ()

gboolean    g_unichar_isxdigit              (gunichar c);

Определяет является ли символ шестнадцатеричным числом.

c : Unicode символ.
Возвращает : TRUE если символ является шестнадцатеричным числом

g_unichar_istitle ()

gboolean    g_unichar_istitle               (gunichar c);

Определяет является ли символ символом заголовочного регистра (titlecase). Некоторые символы в Unicode которые являются составными, такие как DZ диаграф имеют три варианта регистра вместо двух. Форма заголовочного регистра (titlecase) используется в начале слова, где только первый символ напечатан только прописными буквами. Форма заголовочного регистра (titlecase) из DZ диаграфа это U+01F2 ЛАТИНСКАЯ ПРОПИСНАЯ БУКВА D СО СТРОЧНОЙ БУКВОЙ Z.

c : Unicode символ
Возвращает : TRUE если символ в заголовочном регистре (titlecase)

g_unichar_isdefined ()

gboolean    g_unichar_isdefined             (gunichar c);

Определяет является ли полученный символ назначенным в Unicode стандарте.

c : Unicode символ
Возвращает : TRUE если символ имеет назначенное значение

g_unichar_iswide ()

gboolean    g_unichar_iswide                (gunichar c);

Определяет если символ обычно отрисовывается в ячейке двойной ширины.

c : Unicode символ
Возвращает : TRUE если символ широкий

g_unichar_iswide_cjk ()

gboolean    g_unichar_iswide_cjk            (gunichar c);

Определяет если символ обычно отрисовывается в ячейке двойной ширины устаревшей East Asian локали. Если символ шире согласно g_unichar_iswide(), то он также сообщает ширину этой функции, но обратное не обязательно верно. Смотрите Unicode Standard Annex 11 для детального изучения.

c : Unicode символ
Возвращает : TRUE если символ шириной устаревшей East Asian локали

Начиная с версии 2.12


g_unichar_toupper ()

gunichar    g_unichar_toupper               (gunichar c);

Конвертирует символ в верхний регистр.

c : Unicode символ
Возвращает : результат конвертации c в верхний регистр. Если c не является символом нижнего регистра или заголовочного регистра (titlecase), или не имеет эквивалента в верхнем регистре, c возвращается без изменений.

g_unichar_tolower ()

gunichar    g_unichar_tolower               (gunichar c);

Конвертирует символ в нижний регистр.

c : Unicode символ.
Возвращает : результат конвертации c в нижний регистр. Если c не является символом верхнего регистра или заголовочного регистра (titlecase), или не имеет эквивалента в нижнем регистре, то c возвращается без изменений.

g_unichar_totitle ()

gunichar    g_unichar_totitle               (gunichar c);

Конвертирует символ в заголовочный регистр.

c : Unicode символ
Возвращает : результат конвертации c в заголовочный регистр. Если c не является символом верхнего регистра или символом нижнего регистра, то c возвращается без изменений.

g_unichar_digit_value ()

gint        g_unichar_digit_value           (gunichar c);

Определяет числовое значение символа как десятичное число.

c : Unicode символ
Возвращает : Если c десятичное число (согласно g_unichar_isdigit()), его числовое значение. Иначе, -1.

g_unichar_xdigit_value ()

gint        g_unichar_xdigit_value          (gunichar c);

Определяет числовое значение символа как шестнадцатеричное число.

c : Unicode символ
Возвращает : Если c это шестнадцатеричное число (согласно g_unichar_isxdigit()), его цифровое значение. Иначе, -1.

enum GUnicodeType

typedef enum
{
  G_UNICODE_CONTROL,
  G_UNICODE_FORMAT,
  G_UNICODE_UNASSIGNED,
  G_UNICODE_PRIVATE_USE,
  G_UNICODE_SURROGATE,
  G_UNICODE_LOWERCASE_LETTER,
  G_UNICODE_MODIFIER_LETTER,
  G_UNICODE_OTHER_LETTER,
  G_UNICODE_TITLECASE_LETTER,
  G_UNICODE_UPPERCASE_LETTER,
  G_UNICODE_COMBINING_MARK,
  G_UNICODE_ENCLOSING_MARK,
  G_UNICODE_NON_SPACING_MARK,
  G_UNICODE_DECIMAL_NUMBER,
  G_UNICODE_LETTER_NUMBER,
  G_UNICODE_OTHER_NUMBER,
  G_UNICODE_CONNECT_PUNCTUATION,
  G_UNICODE_DASH_PUNCTUATION,
  G_UNICODE_CLOSE_PUNCTUATION,
  G_UNICODE_FINAL_PUNCTUATION,
  G_UNICODE_INITIAL_PUNCTUATION,
  G_UNICODE_OTHER_PUNCTUATION,
  G_UNICODE_OPEN_PUNCTUATION,
  G_UNICODE_CURRENCY_SYMBOL,
  G_UNICODE_MODIFIER_SYMBOL,
  G_UNICODE_MATH_SYMBOL,
  G_UNICODE_OTHER_SYMBOL,
  G_UNICODE_LINE_SEPARATOR,
  G_UNICODE_PARAGRAPH_SEPARATOR,
  G_UNICODE_SPACE_SEPARATOR
} GUnicodeType;

Это возможная классификация символа из спецификации Unicode. Смотрите http://www.unicode.org/Public/UNIDATA/UnicodeData.html.

G_UNICODE_CONTROL Основная категория "Other, Control" (Cc)
G_UNICODE_FORMAT Основная категория "Other, Format" (Cf)
G_UNICODE_UNASSIGNED Основная категория "Other, Not Assigned" (Cn)
G_UNICODE_PRIVATE_USE Основная категория "Other, Private Use" (Co)
G_UNICODE_SURROGATE Основная категория "Other, Surrogate" (Cs)
G_UNICODE_LOWERCASE_LETTER Основная категория "Letter, Lowercase" (Ll)
G_UNICODE_MODIFIER_LETTER Основная категория "Letter, Modifier" (Lm)
G_UNICODE_OTHER_LETTER Основная категория "Letter, Other" (Lo)
G_UNICODE_TITLECASE_LETTER Основная категория "Letter, Titlecase" (Lt)
G_UNICODE_UPPERCASE_LETTER Основная категория "Letter, Uppercase" (Lu)
G_UNICODE_COMBINING_MARK Основная категория "Mark, Spacing Combining" (Mc)
G_UNICODE_ENCLOSING_MARK Основная категория "Mark, Enclosing" (Me)
G_UNICODE_NON_SPACING_MARK Основная категория "Mark, Nonspacing" (Mn)
G_UNICODE_DECIMAL_NUMBER Основная категория "Number, Decimal Digit" (Nd)
G_UNICODE_LETTER_NUMBER Основная категория "Number, Letter" (Nl)
G_UNICODE_OTHER_NUMBER Основная категория "Number, Other" (No)
G_UNICODE_CONNECT_PUNCTUATION Основная категория "Punctuation, Connector" (Pc)
G_UNICODE_DASH_PUNCTUATION Основная категория "Punctuation, Dash" (Pd)
G_UNICODE_CLOSE_PUNCTUATION Основная категория "Punctuation, Close" (Pe)
G_UNICODE_FINAL_PUNCTUATION Основная категория "Punctuation, Final quote" (Pf)
G_UNICODE_INITIAL_PUNCTUATION Основная категория "Punctuation, Initial quote" (Pi)
G_UNICODE_OTHER_PUNCTUATION Основная категория "Punctuation, Other" (Po)
G_UNICODE_OPEN_PUNCTUATION Основная категория "Punctuation, Open" (Ps)
G_UNICODE_CURRENCY_SYMBOL Основная категория "Symbol, Currency" (Sc)
G_UNICODE_MODIFIER_SYMBOL Основная категория "Symbol, Modifier" (Sk)
G_UNICODE_MATH_SYMBOL Основная категория "Symbol, Math" (Sm)
G_UNICODE_OTHER_SYMBOL Основная категория "Symbol, Other" (So)
G_UNICODE_LINE_SEPARATOR Основная категория "Separator, Line" (Zl)
G_UNICODE_PARAGRAPH_SEPARATOR Основная категория "Separator, Paragraph" (Zp)
G_UNICODE_SPACE_SEPARATOR Основная категория "Separator, Space" (Zs)

g_unichar_type ()

GUnicodeType g_unichar_type                 (gunichar c);

Класифицирует Unicode символ по типу.

c : Unicode символ
Возвращает : тип символа.

enum GUnicodeBreakType

typedef enum
{
  G_UNICODE_BREAK_MANDATORY,
  G_UNICODE_BREAK_CARRIAGE_RETURN,
  G_UNICODE_BREAK_LINE_FEED,
  G_UNICODE_BREAK_COMBINING_MARK,
  G_UNICODE_BREAK_SURROGATE,
  G_UNICODE_BREAK_ZERO_WIDTH_SPACE,
  G_UNICODE_BREAK_INSEPARABLE,
  G_UNICODE_BREAK_NON_BREAKING_GLUE,
  G_UNICODE_BREAK_CONTINGENT,
  G_UNICODE_BREAK_SPACE,
  G_UNICODE_BREAK_AFTER,
  G_UNICODE_BREAK_BEFORE,
  G_UNICODE_BREAK_BEFORE_AND_AFTER,
  G_UNICODE_BREAK_HYPHEN,
  G_UNICODE_BREAK_NON_STARTER,
  G_UNICODE_BREAK_OPEN_PUNCTUATION,
  G_UNICODE_BREAK_CLOSE_PUNCTUATION,
  G_UNICODE_BREAK_QUOTATION,
  G_UNICODE_BREAK_EXCLAMATION,
  G_UNICODE_BREAK_IDEOGRAPHIC,
  G_UNICODE_BREAK_NUMERIC,
  G_UNICODE_BREAK_INFIX_SEPARATOR,
  G_UNICODE_BREAK_SYMBOL,
  G_UNICODE_BREAK_ALPHABETIC,
  G_UNICODE_BREAK_PREFIX,
  G_UNICODE_BREAK_POSTFIX,
  G_UNICODE_BREAK_COMPLEX_CONTEXT,
  G_UNICODE_BREAK_AMBIGUOUS,
  G_UNICODE_BREAK_UNKNOWN,
  G_UNICODE_BREAK_NEXT_LINE,
  G_UNICODE_BREAK_WORD_JOINER,
  G_UNICODE_BREAK_HANGUL_L_JAMO,
  G_UNICODE_BREAK_HANGUL_V_JAMO,
  G_UNICODE_BREAK_HANGUL_T_JAMO,
  G_UNICODE_BREAK_HANGUL_LV_SYLLABLE,
  G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE
} GUnicodeBreakType;

Это классификация возможных прерываний строк. Пять типов корейской азбуки (Hangul) добавлены в Unicode 4.1, поэтому были введены в GLib 2.10. Помните что новые типы могут быть добавлены в будущем. Приложения должны быть готовы обрабатывать не известные значения. Они могут расцениваться как G_UNICODE_BREAK_UNKNOWN. Смотрите http://www.unicode.org/unicode/reports/tr14/.


g_unichar_break_type ()

GUnicodeBreakType g_unichar_break_type      (gunichar c);

Определяет тип прерывания c. c должен быть Unicode символом (для извлечения символа из текста в кодировке UTF-8, используйте g_utf8_get_char()). Тип прерывания используется для поиска конца слова и строки ("границы текста"), Pango реализует алгоритмы разрешения границ Unicode и обычно вы должны использовать функции такие как pango_break() вместо того, чтобы беспокоится о типе границы самостоятельно.

c : Unicode символ
Возвращает : тип границы c

g_unicode_canonical_ordering ()

void        g_unicode_canonical_ordering    (gunichar *string,
                                             gsize len);

Расчитывает канонический порядок строки на месте. Это перераспределяет разложение символов в строке согласно их классам объединения. Смотрите руководство Unicode для большей информации.

string : строка в кодировке UCS-4.
len : максимальная длина строки string для использования.

g_unicode_canonical_decomposition ()

gunichar*   g_unicode_canonical_decomposition
                                            (gunichar ch,
                                             gsize *result_len);

Расчитывает каноническую декомпозицию символа Unicode.

ch : Unicode символ.
result_len : расположение для хранения длины возвращаемого значения.
Возвращает : вновь распределённая строка Unicode символов. result_len устанавливается в результирующую длину строки.

g_unichar_get_mirror_char ()

gboolean    g_unichar_get_mirror_char       (gunichar ch,
                                             gunichar *mirrored_ch);

В Unicode, некоторые символы являются зеркальными (mirrored). Это значит что их изображение является отражённым горизонтально в тексте который расположен с право на лево. Например, "(" стал бы зеркальным отражением, ")", в тексте с обратной ориентацией (right-to-left).

Если ch имеет зеркальное свойство Unicode и есть другой символ unicode который обычно имеет глиф являющийся зеркальным изображением ch's глифа и параметр mirrored_ch установлен, он помещает символ в адрес указанный mirrored_ch. Иначе размещается оригинальный символ.

ch : Unicode символ
mirrored_ch : расположение для хранения отражённого символа
Возвращает : TRUE если ch имеет зеркальный символ, иначе FALSE

Начиная с версии 2.4


enum GUnicodeScript

typedef enum 
{                         /* ISO 15924 code */
  G_UNICODE_SCRIPT_INVALID_CODE = -1,
  G_UNICODE_SCRIPT_COMMON       = 0,   /* Zyyy */
  G_UNICODE_SCRIPT_INHERITED,          /* Qaai */
  G_UNICODE_SCRIPT_ARABIC,             /* Arab */
  G_UNICODE_SCRIPT_ARMENIAN,           /* Armn */
  G_UNICODE_SCRIPT_BENGALI,            /* Beng */
  G_UNICODE_SCRIPT_BOPOMOFO,           /* Bopo */
  G_UNICODE_SCRIPT_CHEROKEE,           /* Cher */
  G_UNICODE_SCRIPT_COPTIC,             /* Qaac */
  G_UNICODE_SCRIPT_CYRILLIC,           /* Cyrl (Cyrs) */
  G_UNICODE_SCRIPT_DESERET,            /* Dsrt */
  G_UNICODE_SCRIPT_DEVANAGARI,         /* Deva */
  G_UNICODE_SCRIPT_ETHIOPIC,           /* Ethi */
  G_UNICODE_SCRIPT_GEORGIAN,           /* Geor (Geon, Geoa) */
  G_UNICODE_SCRIPT_GOTHIC,             /* Goth */
  G_UNICODE_SCRIPT_GREEK,              /* Grek */
  G_UNICODE_SCRIPT_GUJARATI,           /* Gujr */
  G_UNICODE_SCRIPT_GURMUKHI,           /* Guru */
  G_UNICODE_SCRIPT_HAN,                /* Hani */
  G_UNICODE_SCRIPT_HANGUL,             /* Hang */
  G_UNICODE_SCRIPT_HEBREW,             /* Hebr */
  G_UNICODE_SCRIPT_HIRAGANA,           /* Hira */
  G_UNICODE_SCRIPT_KANNADA,            /* Knda */
  G_UNICODE_SCRIPT_KATAKANA,           /* Kana */
  G_UNICODE_SCRIPT_KHMER,              /* Khmr */
  G_UNICODE_SCRIPT_LAO,                /* Laoo */
  G_UNICODE_SCRIPT_LATIN,              /* Latn (Latf, Latg) */
  G_UNICODE_SCRIPT_MALAYALAM,          /* Mlym */
  G_UNICODE_SCRIPT_MONGOLIAN,          /* Mong */
  G_UNICODE_SCRIPT_MYANMAR,            /* Mymr */
  G_UNICODE_SCRIPT_OGHAM,              /* Ogam */
  G_UNICODE_SCRIPT_OLD_ITALIC,         /* Ital */
  G_UNICODE_SCRIPT_ORIYA,              /* Orya */
  G_UNICODE_SCRIPT_RUNIC,              /* Runr */
  G_UNICODE_SCRIPT_SINHALA,            /* Sinh */
  G_UNICODE_SCRIPT_SYRIAC,             /* Syrc (Syrj, Syrn, Syre) */
  G_UNICODE_SCRIPT_TAMIL,              /* Taml */
  G_UNICODE_SCRIPT_TELUGU,             /* Telu */
  G_UNICODE_SCRIPT_THAANA,             /* Thaa */
  G_UNICODE_SCRIPT_THAI,               /* Thai */
  G_UNICODE_SCRIPT_TIBETAN,            /* Tibt */
  G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL, /* Cans */
  G_UNICODE_SCRIPT_YI,                 /* Yiii */
  G_UNICODE_SCRIPT_TAGALOG,            /* Tglg */
  G_UNICODE_SCRIPT_HANUNOO,            /* Hano */
  G_UNICODE_SCRIPT_BUHID,              /* Buhd */
  G_UNICODE_SCRIPT_TAGBANWA,           /* Tagb */

  /* Unicode-4.0 additions */
  G_UNICODE_SCRIPT_BRAILLE,            /* Brai */
  G_UNICODE_SCRIPT_CYPRIOT,            /* Cprt */
  G_UNICODE_SCRIPT_LIMBU,              /* Limb */
  G_UNICODE_SCRIPT_OSMANYA,            /* Osma */
  G_UNICODE_SCRIPT_SHAVIAN,            /* Shaw */
  G_UNICODE_SCRIPT_LINEAR_B,           /* Linb */
  G_UNICODE_SCRIPT_TAI_LE,             /* Tale */
  G_UNICODE_SCRIPT_UGARITIC,           /* Ugar */
      
  /* Unicode-4.1 additions */
  G_UNICODE_SCRIPT_NEW_TAI_LUE,        /* Talu */
  G_UNICODE_SCRIPT_BUGINESE,           /* Bugi */
  G_UNICODE_SCRIPT_GLAGOLITIC,         /* Glag */
  G_UNICODE_SCRIPT_TIFINAGH,           /* Tfng */
  G_UNICODE_SCRIPT_SYLOTI_NAGRI,       /* Sylo */
  G_UNICODE_SCRIPT_OLD_PERSIAN,        /* Xpeo */
  G_UNICODE_SCRIPT_KHAROSHTHI,         /* Khar */

  /* Unicode-5.0 additions */
  G_UNICODE_SCRIPT_UNKNOWN,            /* Zzzz */
  G_UNICODE_SCRIPT_BALINESE,           /* Bali */
  G_UNICODE_SCRIPT_CUNEIFORM,          /* Xsux */
  G_UNICODE_SCRIPT_PHOENICIAN,         /* Phnx */
  G_UNICODE_SCRIPT_PHAGS_PA,           /* Phag */
  G_UNICODE_SCRIPT_NKO                 /* Nkoo */
} GUnicodeScript;

Перечисление GUnicodeScript идентифицирует различные системы записи. Значения соответствуют именам определённым в стандарте Unicode. Перечисление было добавлено в GLib 2.14. Помните что новые типы могут быть добавлены в будущем. Приложения должны уметь обрабатывать неизвестные значения. Смотрите Unicode Standard Annex 24: Script names.

G_UNICODE_SCRIPT_INVALID_CODE значение никогда не возвращаемое из g_unichar_get_script()
G_UNICODE_SCRIPT_COMMON символ используемый в множестве различных писменностях
G_UNICODE_SCRIPT_INHERITED маркер глифа который берёт его письменность из основного глифа к которому он прикреплён
G_UNICODE_SCRIPT_ARABIC Арабский язык
G_UNICODE_SCRIPT_ARMENIAN Армянский язык
G_UNICODE_SCRIPT_BENGALI Бенгальский язык
G_UNICODE_SCRIPT_BOPOMOFO Китайский (Bopomofo)
G_UNICODE_SCRIPT_CHEROKEE Cherokee
G_UNICODE_SCRIPT_COPTIC Коптский язык (Coptic)
G_UNICODE_SCRIPT_CYRILLIC Кириллица (Cyrillic)
G_UNICODE_SCRIPT_DESERET Deseret
G_UNICODE_SCRIPT_DEVANAGARI Деванагари (Devanagari)
G_UNICODE_SCRIPT_ETHIOPIC Древнеэфиопский (Ethiopic)
G_UNICODE_SCRIPT_GEORGIAN Грузинский (Georgian)
G_UNICODE_SCRIPT_GOTHIC Готический (Gothic)
G_UNICODE_SCRIPT_GREEK Греческий (Greek)
G_UNICODE_SCRIPT_GUJARATI Gujarati
G_UNICODE_SCRIPT_GURMUKHI Gurmukhi
G_UNICODE_SCRIPT_HAN Ханьшуй (Han)
G_UNICODE_SCRIPT_HANGUL Хангул (Hangul)
G_UNICODE_SCRIPT_HEBREW Иврит (Hebrew)
G_UNICODE_SCRIPT_HIRAGANA Хирагана (Hiragana)
G_UNICODE_SCRIPT_KANNADA Канада (Kannada)
G_UNICODE_SCRIPT_KATAKANA Японская слоговая азбука катакана (Katakana)
G_UNICODE_SCRIPT_KHMER Кхмер (Khmer)
G_UNICODE_SCRIPT_LAO Лао (Lao)
G_UNICODE_SCRIPT_LATIN Латинский (Latin)
G_UNICODE_SCRIPT_MALAYALAM Малайялам (Malayalam)
G_UNICODE_SCRIPT_MONGOLIAN Монгольский (Mongolian)
G_UNICODE_SCRIPT_MYANMAR Myanmar
G_UNICODE_SCRIPT_OGHAM Огам (Ogham)
G_UNICODE_SCRIPT_OLD_ITALIC Староитальянский (Old Italic)
G_UNICODE_SCRIPT_ORIYA Язык ория (Oriya)
G_UNICODE_SCRIPT_RUNIC Руническое письмо (Runic)
G_UNICODE_SCRIPT_SINHALA Сингальский язык (Sinhala)
G_UNICODE_SCRIPT_SYRIAC Сирийский язык (Syriac)
G_UNICODE_SCRIPT_TAMIL Тамильский язык (Tamil)
G_UNICODE_SCRIPT_TELUGU Язык телугу (Telugu)
G_UNICODE_SCRIPT_THAANA Таана (Thaana)
G_UNICODE_SCRIPT_THAI Тайский язык (Thai)
G_UNICODE_SCRIPT_TIBETAN Тибетский (Tibetan)
G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL Канадский язык аборигенов (Canadian Aboriginal)
G_UNICODE_SCRIPT_YI Идиш (Yi)
G_UNICODE_SCRIPT_TAGALOG Тагальский язык (Tagalog)
G_UNICODE_SCRIPT_HANUNOO Hanunoo
G_UNICODE_SCRIPT_BUHID Buhid
G_UNICODE_SCRIPT_TAGBANWA Tagbanwa
G_UNICODE_SCRIPT_BRAILLE Шрифт Брайля (Braille)
G_UNICODE_SCRIPT_CYPRIOT Киприотский (Cypriot)
G_UNICODE_SCRIPT_LIMBU Limbu
G_UNICODE_SCRIPT_OSMANYA Сомалийский алфавит (Osmanya)
G_UNICODE_SCRIPT_SHAVIAN Shavian
G_UNICODE_SCRIPT_LINEAR_B Линейный B (Linear B)
G_UNICODE_SCRIPT_TAI_LE Tai Le
G_UNICODE_SCRIPT_UGARITIC Ugaritic
G_UNICODE_SCRIPT_NEW_TAI_LUE New Tai Lue
G_UNICODE_SCRIPT_BUGINESE Buginese
G_UNICODE_SCRIPT_GLAGOLITIC Glagolitic
G_UNICODE_SCRIPT_TIFINAGH Tifinagh
G_UNICODE_SCRIPT_SYLOTI_NAGRI Syloti Nagri
G_UNICODE_SCRIPT_OLD_PERSIAN Старый персидский (Old Persian)
G_UNICODE_SCRIPT_KHAROSHTHI Kharoshthi
G_UNICODE_SCRIPT_UNKNOWN неизвестный указатель кода
G_UNICODE_SCRIPT_BALINESE Балинизиский (Balinese)
G_UNICODE_SCRIPT_CUNEIFORM Cuneiform
G_UNICODE_SCRIPT_PHOENICIAN Финский (Phoenician)
G_UNICODE_SCRIPT_PHAGS_PA Phags-pa
G_UNICODE_SCRIPT_NKO N'Ko

g_unichar_get_script ()

GUnicodeScript g_unichar_get_script         (gunichar ch);

Находит GUnicodeScript для специфического символа (как определено в Unicode Standard Annex 24). Проверка на правильность ch для Unicode символа не производится; если вы поместите недопустимый символ, результат будет неопределённым.

ch : Unicode символ
Возвращает : GUnicodeScript для символа.

Начиная с версии 2.14


g_utf8_next_char()

#define     g_utf8_next_char(p)

Пропускает следующий символ в UTF-8 строке. Строка должна быть допустимой; это максимально быстрая макрокоманда и никакого контроля ошибок не проводится. Вы должны использовать эту макрокоманду для посимвольной итерации строки. Эта макрокоманда возвращает начало следующего символа UTF-8. Перед использованием этой макрокоманды используйте g_utf8_validate() для проверки правильности строк которые могут содержать недопустимые символы UTF-8.

p : указатель на начало допустимого символа UTF-8.

g_utf8_get_char ()

gunichar    g_utf8_get_char                 (const gchar *p);

Конвертирует последовательность байт в кодировке UTF-8 в Unicode символ. Если p не указывает на допустимый символ в кодировке UTF-8, результат будет неопределённым. Если вы не уверены в том что последовательность байт является допустимым кодом Unicode символов, вы должны использовать вместо этой функции g_utf8_get_char_validated().

p : указатель на Unicode символ в кодировке UTF-8
Возвращает : результирующий символ

g_utf8_get_char_validated ()

gunichar    g_utf8_get_char_validated       (const gchar *p,
                                             gssize max_len);

Конвертирует последовательность байт в кодировке UTF-8 в Unicode символ. Эта функция проверяет незаконченность символов, для недопустимых символов таких как символы которые выходят за диапазон Unicode и слишком длинных допустимых символов.

p : указатель на Unicode символ в кодировке UTF-8
max_len : максимальное количество байт для чтения, или -1, если нет максимума.
Возвращает : результирующий символ. Если p указатель на часть последовательности конца строки которая могла начать допустимый символ, возвращается (gunichar)-2; иначе, если p не является указателем на допустимый в UTF-8 кодировке Unicode символ, возвращается (gunichar)-1.

g_utf8_offset_to_pointer ()

gchar*      g_utf8_offset_to_pointer        (const gchar *str,
                                             glong offset);

Конвертирует из целочисленного символа смещения в указатель на позицию внутри строки.

Начиная с версии 2.10, эта функция позволяет помещать отрицательное offset для смещения назад. Это в основном полезно при движении с конца вместо движения вперед если offset это последняя четверть строки, так как передвижение вперёд в три раза быстрее чем назад.

str : строка в кодировке UTF-8
offset : символьное смещение внутри строки str
Возвращает : результирующий указатель

g_utf8_pointer_to_offset ()

glong       g_utf8_pointer_to_offset        (const gchar *str,
                                             const gchar *pos);

Конвертирует из указателя внутри строки в целочисленное смещение символов.

Начиная с версии 2.10, эта функция позволяет pos быть перед str, и возвращает негативное смещение в этом случае.

str : строка в кодировке UTF-8
pos : указатель на позицию внутри str
Возвращает : результирующее символьное смещение

g_utf8_prev_char ()

gchar*      g_utf8_prev_char                (const gchar *p);

Находит предыдущий символ UTF-8 в строке перед p.

p не должен быть в начале символа UTF-8. Никакая проверка не проводится для найденого символа кроме фактической допустимости начального байта. Если p может оказаться первым символом строки, вы должны использовать g_utf8_find_prev_char() вместо этой функции.

p : указатель на позицию в UTF-8 строке
Возвращает : указатель на найденный символ.

g_utf8_find_next_char ()

gchar*      g_utf8_find_next_char           (const gchar *p,
                                             const gchar *end);

Ищет начало следующего символа UTF-8 в строке после p.

p не должен быть началом UTF-8 символа. Для найденного символа не проводится никакой проверки фактической правильности символа, кроме допустимости начального байта.

p : указатель на позицию внутри строки UTF-8
end : указатель на конец строки, или NULL для указания что строка nul-завершённая, в этом случае он будет возвращённым значением
Возвращает : указатель на найденный символ или NULL

g_utf8_find_prev_char ()

gchar*      g_utf8_find_prev_char           (const gchar *str,
                                             const gchar *p);

Учитывая позицию p со строкой UTF-8 str, находит начало предыдущего символа UTF-8 строки перед p. Возвращает NULL если нет символов UTF-8 представленных в строке str перед p.

p не должен быть началом UTF-8 символа. Никакой проверки не проводится для найденного символа за исключением соответствия начального байта.

str : указатель на начало строки UTF-8
p : указатель на некоторую позицию внутри строки str
Возвращает : указатель на найденный символ или NULL.

g_utf8_strlen ()

glong       g_utf8_strlen                   (const gchar *p,
                                             gssize max);

Возвращает длину строки в символах.

p : указатель на начало строки UTF-8.
max : максимальное число байт для проверки. Если max меньше чем 0, то строка предположительно будет nul-завершённой. Если max это 0, p не будет проверен и может быть NULL.
Возвращает : длина строки в символах

g_utf8_strncpy ()

gchar*      g_utf8_strncpy                  (gchar *dest,
                                             const gchar *src,
                                             gsize n);

Как стандартная C функция strncpy(), но копирует полученное количество символов а не байт. Строка src должна быть допустимым UTF-8 текстом. (Используйте g_utf8_validate() для всех текстов перед попыткой использования UTF-8 функций.)

dest : буфер для заполнения символами из src
src : строка в кодировке UTF-8
n : количество символов
Возвращает : dest

g_utf8_strchr ()

gchar*      g_utf8_strchr                   (const gchar *p,
                                             gssize len,
                                             gunichar c);

Находит крайнее левое появление полученного символа Unicode в строке UTF-8, ограничивая поиск в len байт. Если len равен -1, допускается неограниченный поиск.

p : nul-завершённая строка UTF-8
len : максимальная длина p
c : Unicode символ
Возвращает : NULL если строка не содержит символ, иначе, указатель на начало крайнего левого появления символа в строке.

g_utf8_strrchr ()

gchar*      g_utf8_strrchr                  (const gchar *p,
                                             gssize len,
                                             gunichar c);

Находит крайний правый полученный Unicode символ в строке UTF-8, поиск ограничивается len байтами. Если len это -1, допускается неограниченный поиск.

p : nul-завершённая строка UTF-8
len : максимальная длина p
c : Unicode символ
Возвращает : NULL если строка не содержит символа, иначе, указатель на начало крайнего правого появления символа в строке.

g_utf8_strreverse ()

gchar*      g_utf8_strreverse               (const gchar *str,
                                             gssize len);

Переворачивает строку в кодировке UTF-8. str должна быть допустимым текстом в кодировке UTF-8. (Используйте g_utf8_validate() для всех текстов перед попыткой использования сервисных функций UTF-8.)

Помните что в отличие от g_strreverse(), эта функция возвращает вновь распределённую память, которая должна быть освобождена с помощью g_free() когда больше не нужна.

str : строка в кодировке UTF-8
len : максимальная длина str для использования. Если len < 0, то строка nul-завершённая.
Возвращает : вновь распределённая строка которая является перевёрнутой строкой str.

Начиная с версии 2.2


g_utf8_validate ()

gboolean    g_utf8_validate                 (const gchar *str,
                                             gssize max_len,
                                             const gchar **end);

Утверждает правильность текста в кодировке UTF-8. str это текст для подтверждения; если str nul-завершённая, то max_len может быть -1, иначе max_len должен быть количеством байт для подтверждения. Если end это non-NULL, то конец подтверждённого диапазона будет сохранён здесь (то есть начало первого недопустимого символа, если некоторые байты недопустимы, или иначе конец подтверждённого текста).

Помните что g_utf8_validate() возвращает FALSE если max_len положительное и NUL был встречен перед прочтением max_len байт.

Возвращает TRUE если вся str была допустимой. Многие GLib и GTK+ подпрограммы требуют допустимого ввода UTF-8; поэтому данные прочтённые из файла или сети должны быть проверены с помощью g_utf8_validate() перед выполнением других действий с ними.

str : указатель на символьные данные
max_len : максимальное количество байт для подтверждения, или -1 чтобы действовать пока не встретится NUL
end : расположение для возвращаемого конца подтверждённых данных
Возвращает : TRUE если текст соответствует кодировке UTF-8

g_utf8_strup ()

gchar*      g_utf8_strup                    (const gchar *str,
                                             gssize len);

Конвертирует все Unicode символы строки в верхний регистр. Точный способ которым это выполняется зависит от текущей локали, и может привести к увеличению количества символов в строке. (Например, немецкая ess-zet будет изменена на SS.)

str : строка в кодировке UTF-8
len : длина str, в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределённая строка, все символы которой конвертированы в верхний регистр.

g_utf8_strdown ()

gchar*      g_utf8_strdown                  (const gchar *str,
                                             gssize len);

Конвертирует все Unicode символы строки в нижний регистр. Точный способ которым это выполняется зависит от текущей локали, и может привести к изменению количества символов в строке.

str : строка в кодировке UTF-8
len : длина str, в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределённая строка, в которой все символы конвертированы в нижний регистр.

g_utf8_casefold ()

gchar*      g_utf8_casefold                 (const gchar *str,
                                             gssize len);

Конвертирует строку в форму которая не зависит от регистра. Результат не будет соответствовать никакому специальному регистру, но может быть сравнен для равенства или упорядочен с результатом вызова g_utf8_casefold() для других строк.

Помните что вызов g_utf8_casefold() сопровождаемый g_utf8_collate() только приближает к правильному лингвистическому регистру нечувствительному к упорядочиванию, однако это достаточно хорошо. Получение более точного и правильного результата требует более сложной функции сопоставления которая принимает во внимание чувствительность к регистру. GLib в настоящее время не поддерживает такую функцию.

str : строка в кодировке UTF-8
len : длина str, в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределённая строка, которая является регистронезависимой str.

g_utf8_normalize ()

gchar*      g_utf8_normalize                (const gchar *str,
                                             gssize len,
                                             GNormalizeMode mode);

Конвертирует строку в изначальную форму, стандартизируя такие проблемы как, представлен ли символ с акцентом как основной и комбинирующий акцент, или как единственный составной символ. В основном вы должны вызвать g_utf8_normalize() перед сравнением двух Unicode строк.

Режим нормализации G_NORMALIZE_DEFAULT только стандартизирует различия которые не затрагивают текстовое содержание, такие как упомянутые выше акценты представления. G_NORMALIZE_ALL также стандартизирует символы "совместимости" в Unicode, такие как SUPERSCRIPT THREE в стандартные формы (в данном случае DIGIT THREE). Форматирование информации может быть потеряно но в большинстве текстовых операций такие символы должны быть рассмотрены одинаково. Например, g_utf8_collate() нормализуется с помощью G_NORMALIZE_ALL как первый шаг.

G_NORMALIZE_DEFAULT_COMPOSE и G_NORMALIZE_ALL_COMPOSE являются подобными G_NORMALIZE_DEFAULT и G_NORMALIZE_ALL, но возвращают результат с составными формами а не в максимально разложенной форме. Это часто полезно если вы хотите преобразовать строку в устаревшую кодировку или поместить её в систему с меньшей способностью обрабатывать Unicode.

str : строка в кодировке UTF-8.
len : длина str, в байтах, или -1 если str nul-завершённая.
mode : тип выполняемой нормализации.
Возвращает : вновь распределённая строка, которая представляет нормализованную форму str.

enum GNormalizeMode

typedef enum {
  G_NORMALIZE_DEFAULT,
  G_NORMALIZE_NFD = G_NORMALIZE_DEFAULT,
  G_NORMALIZE_DEFAULT_COMPOSE,
  G_NORMALIZE_NFC = G_NORMALIZE_DEFAULT_COMPOSE,
  G_NORMALIZE_ALL,
  G_NORMALIZE_NFKD = G_NORMALIZE_ALL,
  G_NORMALIZE_ALL_COMPOSE,
  G_NORMALIZE_NFKC = G_NORMALIZE_ALL_COMPOSE
} GNormalizeMode;

Определяет как трансформировать Unicode строку в каноническую форму, стандартизирует такие проблемы как представлен ли символ с акцентом основного символа и акцентом комбинирования или как единственный составной символ. Unicode строки должны в основном быть нормализованы после их сравнения.

G_NORMALIZE_DEFAULT стандартизирует различия которые не затрагивают текстовое содержимое, такие как описанный выше метод представления акцента.
G_NORMALIZE_NFD другое имя для G_NORMALIZE_DEFAULT.
G_NORMALIZE_DEFAULT_COMPOSE тоже что G_NORMALIZE_DEFAULT, но с составными формами вместо максимально разложенных форм.
G_NORMALIZE_NFC другое имя для G_NORMALIZE_DEFAULT_COMPOSE.
G_NORMALIZE_ALL помимо G_NORMALIZE_DEFAULT также стандартизирует символы "совместимости" в Unicode, такие как SUPERSCRIPT THREE для стандартных форм (в этом случае DIGIT THREE). Форматирование информации может быть нарушено, но для большинства текстовых операций такие символы должны быть рассмотрены одинаково.
G_NORMALIZE_NFKD другое имя для G_NORMALIZE_ALL.
G_NORMALIZE_ALL_COMPOSE аналогично G_NORMALIZE_ALL, но с составными формами вместо максимально разложенных форм.
G_NORMALIZE_NFKC другое имя для G_NORMALIZE_ALL_COMPOSE.

g_utf8_collate ()

gint        g_utf8_collate                  (const gchar *str1,
                                             const gchar *str2);

Сравнивает две строки для правильного использования лингвистических правил текущей локали. Сортируя большое количество строк, она будет значительно быстрее определять ключи сопоставления с помощью g_utf8_collate_key() и сравнивать ключи и сортируя с помощью strcmp(), вместо сортировки оригинальных строк.

str1 : строка в кодировке UTF-8
str2 : строка в кодировке UTF-8
Возвращает : < 0 если str1 сравнивается перед str2, 0 если сравнение эквивалентно, > 0 если str1 сравнивается после str2.

g_utf8_collate_key ()

gchar*      g_utf8_collate_key              (const gchar *str,
                                             gssize len);

Конвертирует строку в ключ сопоставления который можно сравнить с другим ключом сравнения произведенным той же функцией используя strcmp(). Результат сравнения ключей сопоставления двух строк с помощью strcmp() всегда будет сопоставим с результатом сравнения оригинальных ключей с помощью g_utf8_collate().

str : строка в кодировке UTF-8.
len : длина str, в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределённая строка. Эта строка должна быть освобождена с помощью g_free() когда больше не нужна.

g_utf8_collate_key_for_filename ()

gchar*      g_utf8_collate_key_for_filename (const gchar *str,
                                             gssize len);

Конвертирует строку в ключ сопоставления который можно сравнить с другим ключом произведённым этой же функцией с помощью strcmp().

Для правильной сортировки имён файлов, эта функция обрабатывает точку '.' как специфичный случай. Большинство словарей считают это незначительным, производя таким образом порядок "event.c" "eventgenerator.c" "event.h" вместо "event.c" "event.h" "eventgenerator.c". Кроме того, хотелось бы обрабатывать разумно числа, так чтобы "file1" "file10" "file5" сортировались как "file1" "file5" "file10".

str : строка в кодировке UTF-8.
len : длина str, в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределённая строка. Эта строка должна быть освобождена с помощью g_free() когда больше не нужна.

Начиная с версии 2.8


g_utf8_to_utf16 ()

gunichar2*  g_utf8_to_utf16                 (const gchar *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);

Конвертирует строку из UTF-8 в UTF-16. Символ 0 будет добавлен к результату после конвертации текста.

str : строка в кодировке UTF-8
len : максимальная длина (количество символов) str для использования. Если len < 0, то строка nul-завершённая.
items_read : расположение для хранения количества прочтённых байт, или NULL. Если NULL, то G_CONVERT_ERROR_PARTIAL_INPUT будет возвращён в случае, если str содержит завершённый частично символ. Если произошла ошибка, то здесь сохраняется индекс недопустимого ввода.
items_written : расположение для хранения записанного числа gunichar2, или NULL. Значение сохраняемое здесь не включает завершающий 0.
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут происходить любые ошибки из GConvertError кроме G_CONVERT_ERROR_NO_CONVERSION.
Возвращает : указатель на вновь распределённую строку UTF-16. Это значение может быть освобождено с помощью g_free(). Если произошла ошибка, NULL будет возвращён и установлена error.

g_utf8_to_ucs4 ()

gunichar*   g_utf8_to_ucs4                  (const gchar *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);

Конвертирует строку из UTF-8 в 32-bit фиксированной ширины представленный как UCS-4. Заверщающий 0 будет добавлен к строке после конвертации текста.

str : строка в кодировке UTF-8
len : максимальная длина str для использования. Если len < 0, то строка nul-завершённая.
items_read : расположение для хранения прочитанных байт, или NULL. Если NULL, то G_CONVERT_ERROR_PARTIAL_INPUT будет возвращён в случае, если str содержит завершающую часть символа. Если произошла ошибка, то здесь сохраняется индекс недопустимого ввода.
items_written : расположение для хранения записанных символов или NULL. Значение сохраняемое здесь не включает завершающий символ 0.
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки из GConvertError кроме G_CONVERT_ERROR_NO_CONVERSION.
Возвращает : указатель на вновь распределённую строку UCS-4. Это значение должно быть освобождено с помощью g_free(). Если произошла ошибка, то возвращается NULL и устанавливается error.

g_utf8_to_ucs4_fast ()

gunichar*   g_utf8_to_ucs4_fast             (const gchar *str,
                                             glong len,
                                             glong *items_written);

Конвертирует строку из UTF-8 в 32-bit представление фиксированной ширины UCS-4, принимая правильный ввод UTF-8. Эта функция примерно в два раза быстрее чем g_utf8_to_ucs4(), но не производит никакой проверки ошибок ввода.

str : строка в кодировке UTF-8
len : максимальная длина str для использования. Если len < 0, то строка nul-завершённая.
items_written : расположение для хранения количества символов в результате, или NULL.
Возвращает : указатель на вновь распределённую строку UCS-4. Это значение должно быть освобождено с помощью g_free().

g_utf16_to_ucs4 ()

gunichar*   g_utf16_to_ucs4                 (const gunichar2 *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);

Конвертирует строку из UTF-16 в UCS-4. Результат будет завершён символом 0.

str : строка в кодировке UTF-16
len : максимальная длина (число gunichar2) str для использования. Если len < 0, то строка завершается символом 0.
items_read : расположение для хранения прочтенных слов, или NULL. Если NULL, то G_CONVERT_ERROR_PARTIAL_INPUT будет возвращён в случае, если str содержит часть завершающего символа. Если произошла ошибка то здесь сохраняется индекс недопустимого ввода.
items_written : расположение для хранения количества записанных символов, или NULL. Значение сохраняемое здесь не включает завершающий символ 0.
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки из GConvertError кроме G_CONVERT_ERROR_NO_CONVERSION.
Возвращает : указатель на вновь распределённую строку UCS-4. Это значение должно быть освобождено с помощью g_free(). Если произошла ошибка, то возврашается NULL и устанавливается error.

g_utf16_to_utf8 ()

gchar*      g_utf16_to_utf8                 (const gunichar2 *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);

Конвертирует строку из UTF-16 в UTF-8. Результат будет завершён 0 байтом.

Помните что ввод находится уже в родном порядке байт (endianness), начальный символ byte-order-mark специально не обрабатывается. g_convert() может быть использована для конвертации буфера байт данных UTF-16 неоднозначного порядка байт (endianess).

str : строка в кодировке UTF-16
len : максимальная длина (число gunichar2) str для использования. Если len < 0, то строка завершается символом 0.
items_read : расположение для хранения количества прочитанных слов, или NULL. Если NULL, то G_CONVERT_ERROR_PARTIAL_INPUT будет возвращено в случае, если str содержит часть завершающего символа. Если произошла ошибка то здесь сохраняется индекс недопустимого ввода.
items_written : расположение для хранения количества записанных байт, или NULL. Значение записанное здесь не включает завершающий 0 байт.
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки из GConvertError кроме G_CONVERT_ERROR_NO_CONVERSION.
Возвращает : указатель на вновь распределённую строку UTF-8. Это значение должно быть освобождено с помощью g_free(). Если произошла ошибка, NULL будет возвращён и установлена error.

g_ucs4_to_utf16 ()

gunichar2*  g_ucs4_to_utf16                 (const gunichar *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);

Конвертирует строку из UCS-4 в UTF-16. Символ 0 будет добавлен к результату после конвертации текста.

str : строка в кодировке UCS-4
len : максимальная длина (число символов) str для использования. Если len < 0, то строка завершается символом 0.
items_read : расположение для хранения количества прочитанных байт, или NULL. Если произошла ошибка то здесь сохраняется индекс недопустимого ввода.
items_written : расположение для хранения числа gunichar2 записей, или NULL. Значение сохраняемое здесь не включает завершающий 0.
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут произойти любые ошибки из GConvertError кроме G_CONVERT_ERROR_NO_CONVERSION.
Возвращает : указатель на вновь распределённую строку UTF-16. Это значение должно быть освобождено с помощью g_free(). Если произошла ошибка, NULL будет возвращён и установлена error.

g_ucs4_to_utf8 ()

gchar*      g_ucs4_to_utf8                  (const gunichar *str,
                                             glong len,
                                             glong *items_read,
                                             glong *items_written,
                                             GError **error);

Конвертирует строку из 32-bit фиксированной ширины представленной как UCS-4. в UTF-8. Результат будет завершён 0 байтом.

str : строка в кодировке UCS-4
len : максимальная длина (количество символов) str для использования. Если len < 0, то строка завершается 0 символом.
items_read : расположение для хранения количества прочитанных символов, или NULL.
items_written : расположение для хранения записанных байт или NULL. Значение сохраняемое здесь не включает завершающий 0 байт.
error : расположение для хранения произошедшей ошибки, или NULL для игнорирования ошибок. Могут происходить любые ошибки из GConvertError кроме G_CONVERT_ERROR_NO_CONVERSION.
Возвращает : указатель на вновь распределённую строку UTF-8. Это значение должно быть освобождено с помощью g_free(). Если произошла ошибка, NULL будет возвращён и установлена error. В этом случае, items_read будет установлен в позицию первого недопустимого символа ввода.

g_unichar_to_utf8 ()

gint        g_unichar_to_utf8               (gunichar c,
                                             gchar *outbuf);

Конвертирует единственный символ в UTF-8.

c : символ в кодировке Unicode
outbuf : буфер вывода, должен иметь последние 6 байт свободными. Если NULL, то длина будет вычислена и возвращена и ничего не будет записано в буфер outbuf.
Возвращает : количество записанных байт

Смотрите также

g_locale_to_utf8(), g_locale_from_utf8()

Удобные функции для конвертации между UTF-8 и локальной кодировкой.



[3] суррогатные пары

Информация о версии

Version Information — Переменные и функции для проверки версии GLib

Краткое описание


#include <glib.h>


extern      const guint glib_major_version;
extern      const guint glib_minor_version;
extern      const guint glib_micro_version;
extern      const guint glib_binary_age;
extern      const guint glib_interface_age;
const gchar* glib_check_version             (guint required_major,
                                             guint required_minor,
                                             guint required_micro);

#define     GLIB_MAJOR_VERSION
#define     GLIB_MINOR_VERSION
#define     GLIB_MICRO_VERSION
#define     GLIB_CHECK_VERSION              (major,minor,micro)

Описание

GLib обеспечивает информации о версии, в первую очередь полезно для проверки конфигурации при сборке скриптом configure. Приложения обычно не используют особенности описанные здесь.

Детали

glib_major_version

extern const guint glib_major_version;

Основной номер библиотеки GLib. (например в GLib версии 1.2.5 это 1.)

Эта переменная находится в библиотеке, таким образом представляется библиотека GLib к которой вы привязываетесь. В отличии от макроса GLIB_MAJOR_VERSION, который представляет главную версию заголовков GLib которые вы включили.


glib_minor_version

extern const guint glib_minor_version;

Младший номер версии библиотеки GLib. (например в GLib версии 1.2.5 это 2.)

Эта переменная находится в библиотеки, таким образом представляя библиотеку GLib к которой вы привязываетесь. В отличии от макроса GLIB_MINOR_VERSION, который представляет младший номер версии заголовков GLib которые вы включили.


glib_micro_version

extern const guint glib_micro_version;

Наименьший номер версии библиотеки GLib. (например в GLib версии 1.2.5 это 5.)

Эта переменная находится в библиотеки, таким образом представляя библиотеку GLib к которой вы привязываетесь. В отличии от макроса GLIB_MICRO_VERSION, который представляет наименьший номер версии заголовков GLib которые вы включили.


glib_binary_age

extern const guint glib_binary_age;

Это бинарный возраст передаваемый в libtool. Если libtool ни о чём вам не говорит, не беспокойтесь об этом. ;-)


glib_interface_age

extern const guint glib_interface_age;

Это интерфейсный возраст передаваемый в libtool. Если libtool ни о чём вам не говорит, не беспокойтесь об этом. ;-)


glib_check_version ()

const gchar* glib_check_version             (guint required_major,
                                             guint required_minor,
                                             guint required_micro);

Проверяет что библиотека GLib совместима с полученной версией. В основном вы должны помещать константы GLIB_MAJOR_VERSION, GLIB_MINOR_VERSION, GLIB_MICRO_VERSION как три аргумента для этой функции; это производит проверку что используемая библиотека совместима с версией GLib приложения, или напротив были собраны модули.

Совместимость определяется двумя вещами: сначала версия запущенной библиотеки новее чем версия required_major.required_minor. required_micro. Затем выполняемая библиотека должна быть бинарно совместима с версией required_major.required_minor.required_micro (одинаковый главный номер версии.)

required_major : необходимая главная версия.
required_minor : необходимая младшая версия.
required_micro : необходимая наименьшая версия.
Возвращает : NULL если библиотека GLib совместима с полученной версией, или строку описывающую несоответствие версий. Возвращаемой строкой владеет GLib и она не должна модифицироваться или освобождаться.

Начиная с версии 2.6


GLIB_MAJOR_VERSION

#define GLIB_MAJOR_VERSION 2

Главный номер версии библиотеки GLib. Тоже самое что glib_major_version, но из заголовков используемых во время компиляции приложения, вместо библиотеки связываемой с приложением во время выполнения.


GLIB_MINOR_VERSION

#define GLIB_MINOR_VERSION 13

Младший номер версии библиотеки GLib. Тоже самое что gtk_minor_version, но из заголовков используемых во время компиляции приложения, а не из библиотеки связываемой с приложением во время выполнения.


GLIB_MICRO_VERSION

#define GLIB_MICRO_VERSION 0

Наименьший номер версии библиотеки GLib. Тоже самое что gtk_micro_version, но из заголовков используемых во время компиляции приложения, а не из библиотеки связываемой с приложением во время выполнения


GLIB_CHECK_VERSION()

#define     GLIB_CHECK_VERSION(major,minor,micro)

Проверяет номер версии библиотеки GLib. Возвращает TRUE если версия заголовочных файлов GLib та же самая или более новая чем передаваемая.

Пример 1. Проверка версии библиотеки GLib

  if (!GLIB_CHECK_VERSION (1, 2, 0))
    g_error ("GLib version 1.2.0 or above is needed");

major : главный номер версии.
minor : младший номер версии.
micro : наименьший номер версии.


Вывод сообщений и функции отладки

Message Output and Debugging Functions — Функции для вывода сообщений и помощь отладки приложений.

Краткое описание


#include <glib.h>


void        g_print                         (const gchar *format,
                                             ...);
GPrintFunc  g_set_print_handler             (GPrintFunc func);
void        (*GPrintFunc)                   (const gchar *string);

void        g_printerr                      (const gchar *format,
                                             ...);
GPrintFunc  g_set_printerr_handler          (GPrintFunc func);

#define     g_return_if_fail                (expr)
#define     g_return_val_if_fail            (expr,val)
#define     g_return_if_reached             ()
#define     g_return_val_if_reached         (val)

#define     g_assert                        (expr)
#define     g_assert_not_reached            ()

void        g_on_error_query                (const gchar *prg_name);
void        g_on_error_stack_trace          (const gchar *prg_name);

#define     G_BREAKPOINT                    ()

Описание

Эти функции обеспечивают поддержку вывода сообщений.

Детали

g_print ()

void        g_print                         (const gchar *format,
                                             ...);

Вывод форматированных сообщений через обработчик печати. По умолчанию обработчик печати просто выводит сообщения на стандартный вывод (stdout).

g_print() не должна использоваться внутри библиотеки для отладочных сообщений, так как они могут переадресовываться приложениями в специальные окна сообщений или даже в файлы. Вместо неё библиотека должна использовать g_log(), или удобные функции g_message(), g_warning() и g_error().

format : форматированное сообщение. Смотрите printf() документацию.
... : параметры для вставки в форматированную строку.

g_set_print_handler ()

GPrintFunc  g_set_print_handler             (GPrintFunc func);

Устанавливает обработчик печати. Любые сообщения помещаемые в g_print() будут выводиться через новый обработчик. Обработчик по умолчанию просто выводит сообщения на stdout. Обеспечивая собственный обработчик вы можете перенаправить вывод, например в виджет GTK+ или файл журнала.

func : новый обработчик печати.
Возвращает : старый обработчик печати.

GPrintFunc ()

void        (*GPrintFunc)                   (const gchar *string);

Определяет тип функции обработчика печати. Их вызывают для вывода полностью отформатированной строки на output.

string : сообщение для вывода.

g_printerr ()

void        g_printerr                      (const gchar *format,
                                             ...);

Выводит отформатированные сообщения через обработчик сообщений об ошибках. По умолчанию обработчик просто выводит сообщения на stderr.

g_printerr() не должна использоваться внутри библиотеки. Вместо неё используйте g_log(), или удобные функции g_message(), g_warning() и g_error().

format : отформатированное сообщение. Смотрите документацию для printf().
... : параметры для вставки в форматированную строку.

g_set_printerr_handler ()

GPrintFunc  g_set_printerr_handler          (GPrintFunc func);

Устанавливает обработчик для печати сообщений об ошибках. Любые сообщения помещённые в g_printerr() будут выводиться через новый обработчик. Обработчик по умолчанию просто выводит сообщения на stderr. Обеспечивая собственный обработчик вы можете перенаправить вывод, например в виджет GTK+ или файл журнала.

func : новый обработчик сообщений об ошибках.
Возвращает : старый обработчик сообщений об ошибках.

g_return_if_fail()

#define     g_return_if_fail(expr)

Возвращается из текущей функции если выражение не верно. Если выражение вычисляет FALSE, регистрируется критическое сообщение и функция возвращается. Это может использоваться только в функциях которые не возвращают значение.

expr : выражение для проверки.

g_return_val_if_fail()

#define     g_return_val_if_fail(expr,val)

Возвращается из текущей функции, возвращая значение val, если выражение не верно. Если выражение вычисляет FALSE, регистрируется критическое сообщение и возвращается val.

expr : выражение для проверки.
val : значение возвращаемое из текущей функции если выражение не верно.

g_return_if_reached()

#define     g_return_if_reached()

Регистрирует критическое сообщение и возвращается из текущей функции. Это используется только в функциях которые не возвращают значений.


g_return_val_if_reached()

#define     g_return_val_if_reached(val)

Регистрирует критическое сообщение и возвращает val.

val : значение возвращаемое из текущей функции.

g_assert()

#define     g_assert(expr)

Отладочный макрос для завершения приложения если выражение неправильно. Если выражение неправильно (то есть логическое выражение не верно), регистрируется сообщение об ошибке и приложение закрывается.

Макрос можно отключить в завершающем релизе определив G_DISABLE_ASSERT при компиляции приложения.

expr : проверяемое выражение.

g_assert_not_reached()

#define     g_assert_not_reached()

Отладочный макрос для прекращения выполнения приложения при его достижении. Если он достигнут, регистрируется сообщение об ошибке и приложение закрывается.

Макрос можно отключить при окончательной реализации с помощью определения G_DISABLE_ASSERT при компиляции приложения.


g_on_error_query ()

void        g_on_error_query                (const gchar *prg_name);

Подсказка ввода для пользователя [E]xit, [H]alt, показать [S]tack trace или [P]roceed. Эта функция только для отладки использования. Следующий пример демонстрирует как её можно использовать совместно с функцией g_log().

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

 /* ... */  

Если [E]xit выбран, приложение закрывается с помощью вызова _exit(0).

Если выбрано [H]alt, приложение входит в бесконечный цикл. Бесконечный цикл можно остановить только уничтожив приложение, или установив glib_on_error_halt в FALSE (возможно через отладчик).

Если выбрано [S]tack trace, вызывается g_on_error_stack_trace(). Это вызывает gdb, который присоединяется к текущему процессу и показывает распечатку стека (stack trace). Подсказка ввода показывается снова.

Если выбрано [P]roceed, функция завершается возвращением.

Эта функция может вызвать разные действия на не-UNIX платформах.

prg_name : имя программы, необходимо отладчику gdb для опции распечатки стека ([S]tack trace option). Если prg_name равно NULL, g_get_prgname() вызывается для получения имени программы (которая будет работать правильно если вызваны gdk_init() или gtk_init()).

g_on_error_stack_trace ()

void        g_on_error_stack_trace          (const gchar *prg_name);

Вызывает gdb, который присоединяется к текущему процессу и показывает распечатку стека. Вызывается функцией g_on_error_query() когда выбрана опция [S]tack trace.

Эта функция может выполнять разные действия на не-UNIX платформах.

prg_name : имя програмы, нужно отладчику gdb для опции распечатки стека ([S]tack trace option). Если prg_name равно NULL, g_get_prgname() вызывается для получения имени программы (которая будет правильно работать если вызваны gdk_init() или gtk_init()).

G_BREAKPOINT()

#define     G_BREAKPOINT()

Вставляет контрольную точку в код (только на x86 архитектуре).


Windows Compatibility Functions

Windows Compatibility Functions — UNIX emulation on Windows.

Краткое описание


#include <glib.h>


#define     MAXPATHLEN
#define     pipe                            (phandles)
gchar*      g_win32_error_message           (gint error);
gchar*      g_win32_getlocale               (void);
gchar*      g_win32_get_package_installation_directory
                                            (gchar *package,
                                             gchar *dll_name);
gchar*      g_win32_get_package_installation_subdirectory
                                            (gchar *package,
                                             gchar *dll_name,
                                             gchar *subdir);
guint       g_win32_get_windows_version     (void);
gchar*      g_win32_locale_filename_from_utf8
                                            (const gchar *utf8filename);
#define     G_WIN32_DLLMAIN_FOR_DLL_NAME    (static, dll_name)
#define     G_WIN32_HAVE_WIDECHAR_API       ()
#define     G_WIN32_IS_NT_BASED             ()

Описание

These functions provide some level of UNIX emulation on the Windows platform. If your application really needs the POSIX APIs, we suggest you try the Cygwin project.

Детали

MAXPATHLEN

#define MAXPATHLEN 1024

Provided for UNIX emulation on Windows; equivalent to UNIX macro MAXPATHLEN, which is the maximum length of a filename (including full path).


pipe()

#define pipe(phandles)	_pipe (phandles, 4096, _O_BINARY)

Provided for UNIX emulation on Windows; see documentation for pipe() in any UNIX manual.

phandles : file descriptors, the first one for reading, the second one for writing.

g_win32_error_message ()

gchar*      g_win32_error_message           (gint error);

Translate a Win32 error code (as returned by GetLastError()) into the corresponding message. The message is either language neutral, or in the thread's language, or the user's language, the system's language, or US English (see docs for FormatMessage()). The returned string is in UTF-8. It should be deallocated with g_free().

error : error code.
Возвращает : newly-allocated error message

g_win32_getlocale ()

gchar*      g_win32_getlocale               (void);

The setlocale() function in the Microsoft C library uses locale names of the form "English_United States.1252" etc. We want the UNIXish standard form "en_US", "zh_TW" etc. This function gets the current thread locale from Windows - without any encoding info - and returns it as строка of the above form for use in forming file names etc. The returned string should be deallocated with g_free().

Возвращает : newly-allocated locale name.

g_win32_get_package_installation_directory ()

gchar*      g_win32_get_package_installation_directory
                                            (gchar *package,
                                             gchar *dll_name);

Try to determine the installation directory for a software package. Typically used by GNU software packages.

package should be a short identifier for the package. Typically it is the same identifier as used for GETTEXT_PACKAGE in software configured according to GNU standards. The function first looks in the Windows Registry for the value #InstallationDirectory in the key #HKLM\Software\package, and if that value exists and is строка, returns that.

If package is NULL, or the above value isn't found in the Registry, but dll_name is non-NULL, it should name a DLL loaded into the current process. Typically that would be the name of the DLL calling this function, looking for its installation directory. The function then asks Windows what directory that DLL was loaded from. If that directory's last component is "bin" or "lib", the parent directory is returned, otherwise the directory itself. If that DLL isn't loaded, the function proceeds as if dll_name was NULL.

If both package and dll_name are NULL, the directory from where the main executable of the process was loaded is used instead in the same way as above.

package : An identifier for a software package, or NULL, in UTF-8
dll_name : The name of a DLL that a package provides, or NULL, in UTF-8
Возвращает : строка containing the installation directory for package. The string is in the GLib file name encoding, i.e. UTF-8 on Windows. The return value should be freed with g_free() when not needed any longer.

g_win32_get_package_installation_subdirectory ()

gchar*      g_win32_get_package_installation_subdirectory
                                            (gchar *package,
                                             gchar *dll_name,
                                             gchar *subdir);

Returns a newly-allocated string containing the path of the subdirectory subdir in the return value from calling g_win32_get_package_installation_directory() with the package and dll_name parameters.

package : An identifier for a software package, in UTF-8, or NULL
dll_name : The name of a DLL that a package provides, in UTF-8, or NULL
subdir : A subdirectory of the package installation directory, also in UTF-8
Возвращает : строка containing the complete path to subdir inside the installation directory of package. The returned string is in the GLib file name encoding, i.e. UTF-8 on Windows. The return value should be freed with g_free() when no longer needed.

g_win32_get_windows_version ()

guint       g_win32_get_windows_version     (void);

Returns version information for the Windows operating system the code is running on. See MSDN documentation for the GetVersion() function. To summarize, the most significant bit is one on Win9x, and zero on NT-based systems. The least significant byte is 4 on Windows NT 4, 5 on Windows XP. Software that needs really detailled version and feature information should use Win32 API like GetVersionEx() and VerifyVersionInfo().

If there is an environment variable G_WIN32_PRETEND_WIN9X defined (with any value), this function always returns a version code for Windows 9x. This is mainly an internal debugging aid for GTK+ and GLib developers, to be able to check the code paths for Windows 9x.

Возвращает : The version information.

Начиная с версии 2.6


g_win32_locale_filename_from_utf8 ()

gchar*      g_win32_locale_filename_from_utf8
                                            (const gchar *utf8filename);

Конвертирует filename from UTF-8 to the system codepage.

On NT-based Windows, on NTFS file systems, file names are in Unicode. It is quite possible that Unicode file names contain characters not representable in the system codepage. (For instance, Greek or Cyrillic characters on Western European or US Windows installations, or various less common CJK characters on CJK Windows installations.)

In such a case, and if the filename refers to an existing file, and the file system stores alternate short (8.3) names for directory entries, the short form of the filename is returned. Note that the "short" name might in fact be longer than the Unicode name if the Unicode name has very short pathname components containing non-ASCII characters. If no system codepage name for the file is possible, NULL is returned.

The return value is dynamically allocated and should be freed with g_free() when no longer needed.

utf8filename : a UTF-8 encoded filename.
Возвращает : The converted filename, or NULL on conversion failure and lack of short names.

Начиная с версии 2.8


G_WIN32_DLLMAIN_FOR_DLL_NAME()

#define     G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)

On Windows, this macro defines a DllMain() function that stores the actual DLL name that the code being compiled will be included in.

On non-Windows platforms, expands to nothing.

static : empty or "static".
dll_name : the name of the (pointer to the) char array where the DLL name will be stored. If this is used, you must also include windows.h. If you need a more complex DLL entry point function, you cannot use this.

G_WIN32_HAVE_WIDECHAR_API()

#define G_WIN32_HAVE_WIDECHAR_API() (G_WIN32_IS_NT_BASED ())

On Windows, this macro defines an expression which evaluates to TRUE if the code is running on a version of Windows where the wide character versions of the Win32 API functions, and the wide chaacter versions of the C library functions work. (They are always present in the DLLs, but don't work on Windows 9x and Me.)

On non-Windows platforms, it is not defined.

Начиная с версии 2.6


G_WIN32_IS_NT_BASED()

#define G_WIN32_IS_NT_BASED() (g_win32_get_windows_version () < 0x80000000)

On Windows, this macro defines an expression which evaluates to TRUE if the code is running on an NT-based Windows operating system.

On non-Windows platforms, it is not defined.

Начиная с версии 2.6


Windows Compatibility Functions

Windows Compatibility Functions — Эмуляция UNIX в Windows.

Краткое описание


#include <glib.h>


#define     MAXPATHLEN
#define     pipe                            (phandles)
gchar*      g_win32_error_message           (gint error);
gchar*      g_win32_getlocale               (void);
gchar*      g_win32_get_package_installation_directory
                                            (gchar *package,
                                             gchar *dll_name);
gchar*      g_win32_get_package_installation_subdirectory
                                            (gchar *package,
                                             gchar *dll_name,
                                             gchar *subdir);
guint       g_win32_get_windows_version     (void);
gchar*      g_win32_locale_filename_from_utf8
                                            (const gchar *utf8filename);
#define     G_WIN32_DLLMAIN_FOR_DLL_NAME    (static, dll_name)
#define     G_WIN32_HAVE_WIDECHAR_API       ()
#define     G_WIN32_IS_NT_BASED             ()

Описание

Эти функции обеспечивают некоторый уровень эмуляции UNIX на Windows платыорме. Если ваше приложение реально нуждается в POSIX APIs, мы предлагаем попробовать проект Cygwin.

Детали

MAXPATHLEN

#define MAXPATHLEN 1024

Предусматривает эмуляцию UNIX в Windows; эквивалентна UNIX макрокоманде MAXPATHLEN, которая представляет максимальную длину имени файла (включая полный путь).


pipe()

#define pipe(phandles)	_pipe (phandles, 4096, _O_BINARY)

Обеспечивает эмуляцию UNIX в Windows; смотрите документацию для pipe() в любом руководстве UNIX.

phandles : дескрипторы файла, первый для чтения, второй для записи.

g_win32_error_message ()

gchar*      g_win32_error_message           (gint error);

Переводит коды ошибок Win32 (которые возвращает GetLastError()) в соответствующие сообщения. Сообщения либо на нейтральном языке, либо на языке потоков, либо пользовательском языке, системном языке, или US English (смотрите документацию для FormatMessage()). Возвращаемая строка находится в кодировке UTF-8. Она должна быть освобождена с помощью g_free().

error : код ошибки.
Возвращает : вновь распределённое сообщение об ошибке

g_win32_getlocale ()

gchar*      g_win32_getlocale               (void);

Функция setlocale() в библиотеке Microsoft C использует имена локали из "English_United States.1252" и т.д.. Мы предпочитаем стандартную UNIX форму "en_US", "zh_TW" и т.д.. Эта функция получает текущий поток локали из Windows - без информации о кодировке - и возвращает её как строку в выше указанной форме для использования в формировании имён файлов и т.д.. Возвращаемая строка должна освобождаться с помощью g_free().

Возвращает : вновь распределённое имя локали.

g_win32_get_package_installation_directory ()

gchar*      g_win32_get_package_installation_directory
                                            (gchar *package,
                                             gchar *dll_name);

Пытается определить каталог для установки программного пакета. Обычно используется программными пакетами GNU.

package должен быть коротким идентификатором для пакета. Обычно это тот же идентификатор который используется для GETTEXT_PACKAGE в конфигурационном программном обеспечении согласно стандартов GNU. Функция сначала ищет в Windows Registry значение #InstallationDirectory в ключе #HKLM\Software\package и если значение существует возвращает его.

Если package это NULL, или выше упомянутое значение не найдено в реестре, но dll_name не-NULL, она должна загрузить имя DLL в текущий процесс. Обычно это будет имя DLL вызывающей эту функцию, находящую для неё каталог установки. Затем функция запрашивает Windows из какого каталога эта DLL была загружена. Если последний компонент этого каталога "bin" или "lib", возвращается родительский каталог, иначе непосредственно сам каталог. Если эта DLL не загружена, функция выполняется как если бы dll_name был NULL.

Если и package и dll_name являются NULL, используется основной каталог в котором запущен процесс, вместо использования способа описанного выше.

package : Целочисленное для программного пакета в кодировке UTF8, или NULL,
dll_name : Имя DLL которую обеспечивает пакет, или NULL, в кодировке UTF-8
Возвращает : строка содержащая каталог установки для package. Строка в кодировке имён файлов GLib, то есть UTF-8 в Windows. Возвращаемое значение должно быть освобождено с помощью g_free() когда больше не используется.

g_win32_get_package_installation_subdirectory ()

gchar*      g_win32_get_package_installation_subdirectory
                                            (gchar *package,
                                             gchar *dll_name,
                                             gchar *subdir);

Возвращает вновь распределённую строку содержащую путь подкаталога subdir в возвращаемом значении из вызова g_win32_get_package_installation_directory() с параметрами package и dll_name.

package : Идентификатор для программного пакета, в кодировке UTF-8, или NULL
dll_name : Имя DLL которую обеспечивает пакет, в кодировке UTF-8, или NULL
subdir : подкаталог установочного каталога для пакета, так же в кодировке UTF-8
Возвращает : строка содержащая полный путь к subdir внутри каталога установки package. Возвращаемая строка находится в кодировке имён файлов GLib, то есть UTF-8 в Windows. Возвращаемое значение должно освобождаться с помощью g_free() когда больше не используется.

g_win32_get_windows_version ()

guint       g_win32_get_windows_version     (void);

Возвращает информацию о версии для исполняемого кода операционной системы Windows. Смотрите документацию MSDN для функции GetVersion(). Коротко, наиболее важный бит - это один в Win9x, и ноль в NT-based системах. Начиная с версии 2.14, GLib работает только в NT-based системах, поэтому проверки выполняются ли ваши собственные программы в Win9x сомнительны. Самый младший байт - это 4 в Windows NT 4, и 5 в Windows XP. Программы которым реально необходима детальная информация о версии и особенностях, должны использовать Win32 API, например GetVersionEx() и VerifyVersionInfo().

Возвращает : Информация о версии.

Начиная с версии 2.6


g_win32_locale_filename_from_utf8 ()

gchar*      g_win32_locale_filename_from_utf8
                                            (const gchar *utf8filename);

Конвертирует имя файла из UTF-8 в системную кодировку.

В NT-based Windows, на файловых системах NTFS, имена файлов находятся в Unicode. Весьма возможно, что имена файлов в Unicode содержат символы не представленные в системной кодовой странице. (Например, Греческие или Кириллические символы в Восточной Европе или US Windows инсталяции, или менее общие символы CJK в CJK Windows инсталяции.)

В этом случае, и если имя файла ссылается на существующий файл, и файловая система хранит альтернативные короткие (8.3) имена для каталогов, возвращается короткая форма имени файла. Помните что "короткое" имя может быть фактически длиннее чем Unicode имя, если Unicode имя имеет очень короткий путь имени содержащий не-ASCII символы. Если нет возможного имени в системной кодировке для файла, возвращается NULL.

Возвращаемое значение динамически распределяется и должно быть освобождено с помощью g_free() когда больше не используется.

utf8filename : имя файла в кодировке UTF-8.
Возвращает : Конвертированное имя файла, или NULL если нет короткого имени.

Начиная с версии 2.8


G_WIN32_DLLMAIN_FOR_DLL_NAME()

#define     G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)

В Windows, этот макрос определяет DllMain() функцию которая сохраняет фактическое имя DLL для включения в компилируемый код.

На не-Windows платформах, ничего не делает.

static : свободная или "статичная".
dll_name : имя (указатель на) массив символов где будет хранится имя DLL. Если это используется, вы должны так же включить windows.h. Если вам нужно более сложную функцию точки ввода DLL, вы не должны использовать это.

G_WIN32_HAVE_WIDECHAR_API()

#define G_WIN32_HAVE_WIDECHAR_API() TRUE

В Windows, этот макрос определяет выражение которое выдаёт TRUE если код запущен в версии Windows использующей функции Win32 API широких символов, и широко-символьные версии функций библиотеки C работают. (Они всегда присутствуют в DLLs, но не работают в Windows 9x и Me.)

На не-Windows платформах, это не определено.

Начиная с версии 2.6


G_WIN32_IS_NT_BASED()

#define G_WIN32_IS_NT_BASED() TRUE

В Windows, этот макрос определяет выражение которое выдаёт TRUE если код выполняется в операционной системе на основе Windows NT.

На не-Windows платформах, это не определено.

Начиная с версии 2.6


Компиляция пакета GLib

Compiling the GLib Package — Как самостоятельно скомпилировать GLib

Сборка библиотеки в UNIX

В UNIX, GLib использует стандартную систему сборки GNU, autoconf для конфигурации пакета и решения проблем переносимости, automake для создания makefiles который выполняется с помощью GNU Coding Standards и libtool для сборки общих библиотек на множестве платформ. Нормальная последовательность сборки и инсталяции GLib библиотеки такая:


          ./configure
          make
          make install
        

Стандартные опции представленные GNU autoconf можно передать в скрипт configure. Пожалуйста изучите autoconf документацию или запустите ./configure --help для получения информации о стандартных опциях.

GTK+ документация содержит further details о процессе сборки и способах влияния на него.

Зависимости

Перед компиляцией библиотеки GLib, вам необходимо иметь дополнительные инструменты и библиотеки установленные в вашей системе. Два инструмента необходимы в течении процесса сборки (которые отличаются от от инструментов используемых при создании GLib, упомянутых выше таких как autoconf) pkg-config и GNU make.

  • pkg-config это инструмент для отслеживания флагов компиляции необходимых для библиотек которые используются библиотекой GLib. (Для каждой библиотеки, в стандартном расположении установлен текстовый файл .pc который содержит флаги компиляции необходимые для данной библиотеки и номер её версии.) Версия pkg-config необходимая для сборки GLib указана в каталоге зависимостей на GTK+ FTP сайте.

  • GTK+ makefiles будет работать с разными версиями make, однако, есть некоторая тенденция небольших несовместимостей, поэтому команда разработчиков GTK+ рекомендует установить GNU make если она ещё не установлена в вашей системе и использовать именно её. (Она может называться gmake вместо make.)

GLib зависит от множества других библиотек.

  • Библиотека GNU libiconv необходима для сборки GLib если ваша система не имеет iconv() функции для конвертации символов в разных кодировках. Современные системы должны иметь iconv(), однако некоторые устаревшие системы не имеют iconv(). На таких системах, вы должны установить библиотеку libiconv. Она может быть найдена на: http://www.gnu.org/software/libiconv.

    Если ваша система имеет iconv() реализациию, но вы хотите использовать libiconv вместо неё, то вы должны указать опцию --with-libiconv для скрипта configure. Это заставит использовать libiconv.

    Помните что если вы имеете libiconv установленную в путь поиска по умолчанию (например в /usr/local/), но не включаете её, вы получите ошибку в процессе компиляции GLib, потому что iconv.h установленной libiconv скрывает системную iconv.

    Если вы используете родную реализацию iconv в Solaris вместо libiconv, вы должны убедиться что можете конвертировать между локальной кодировкой и UTF-8. Как минимум вам нужен пакет SUNWuiu8. Вероятно вам потребуется установить также пакеты SUNWciu8, SUNWhiu8, SUNWjiu8 и SUNWkiu8.

    Родная iconv в Compaq Tru64 не поддерживает UTF-8, поэтому вам необходимо использовать вместо неё GNU libiconv. (Когда используете GNU libiconv для GLib, вы также должны использовать GNU libiconv для GNU gettext.) Это также касается связанных с ней систем.

  • Библиотека libintl из GNU gettext package необходима если ваша система не имеет gettext() функций для обработки базы переводимых сообщений.

  • Реализация потоков (thread) необходима, если вам нужно собрать GLib без поддержки потоков (thread support), что не рекомендуется. Поддержка потоков в GLib может базироваться на некой родной реализации потоков, например POSIX threads, DCE threads или Solaris threads.

Дополнительные конфигурационные опции

В дополнение к обычным опциям, скрипт configure в библиотеке GLib поддерживает следующие аргументы:

configure [[--enable-debug=[no|minimum|yes]]] [[--disable-gc-friendly] | [--enable-gc-friendly]] [[--disable-mem-pools] | [--enable-mem-pools]] [[--disable-threads] | [--enable-threads]] [[--with-threads=[none|posix|dce|win32]]] [[--disable-included-printf] | [--enable-included-printf]] [[--disable-visibility] | [--enable-visibility]] [[--disable-gtk-doc] | [--enable-gtk-doc]] [[--disable-man] | [--enable-man]]

--enable-debug Включает разное количество отладочной поддержки. Установка в значение 'no' отключает g_assert(), g_return_if_fail(), g_return_val_if_fail() и контроль приведения между разными типами объектов. Установка в значение 'minimum' отключает только контроль приведения типов. Установка в значение 'yes' включает отладку во время выполнения. По умолчанию используется значение 'minimum'. Помните что значение 'no' ускоряет процесс, но опасно, поскольку имеет тенденцию дестабилизировать даже программное обеспечение без ошибок превращая эффект от небольших ошибок в фатальные сбои. Поэтому --enable-debug=no не должен использоваться для стабильных реализаций GLib.

--disable-gc-friendly и --enable-gc-friendly По умолчанию, а также с помощью --disable-gc-friendly Glib не очищает память для определённых объектов прежде чем они освобождаются. Например, Glib может решить переработать узлы GList поместив их в освобождённый список. Однако, профилирование памяти и инструменты отладки такие как Valgrind работают лучше если приложение не сохраняет указатели в освобождённой памяти (даже если эти указатели больше не разыменованы), или не допускает указатели внутри не инициализированной памяти. Опция --enable-gc-friendly заставляет Glib очищать память в этой ситуации:

  • Когда сокращается GArray, Glib очищает память не доступную больше в массиве: сокращая массив из 10 байт в 7, последние 3 байта будут очищены. Это включает удаление единственных и множественных элементов.

  • Когда увеличивается GArray, Glib очищает новую часть памяти. При увеличении массива с 7 байт до 10 байт, последние 3 байта очищаются.

  • Выше упомянутое также относится и к GPtrArray.

  • Когда освобождаются узлы из GHashTable, Glib сначала очищает узел, который имеет указатель на ключ и значение сохранённое в этом узле.

  • Разрушая или удаляя узел GTree, Glib очищает узел, который имеет указатель на значение узлов, а также левые и правые подузлы.

Начиная c очистки памяти, значение --disable-gc-friendly по умолчанию.

--disable-mem-pools и --enable-mem-pools Множество небольших участков памяти часто распределяются через пулы в GLib и кэшируются после реализации для ускорения перераспределения. Для разряженных систем памяти это поведение является плохим, поэтому пулы памяти могут быть отключены, чтобы избежать чрезмерное кэширование и заставить сопровождать атомарные участки через g_malloc() и g_free() функции. Код в настоящее время влияет на:

  • GList, GSList, GNode, распределения GHash. Функции g_list_push_allocator(), g_list_pop_allocator(), g_slist_push_allocator(), g_slist_pop_allocator(), g_node_push_allocator() и g_node_pop_allocator() не доступны.

  • GMemChunks в основном не эффективны.

  • GSignal отключает всё кэширование (потенциально очень медленный).

  • GType не учитывает GTypeInfo n_preallocs поля больше.

  • GBSearchArray флажок G_BSEARCH_ALIGN_POWER2 не функционален.

--disable-threads и --enable-threads Не компилируйте GLib многопоточностью, тогда GLib будет немного быстрее. Однако это не рекомендуется, так как множество программ предполагает что GLib имеет многопоточность.

--with-threads Определяет использование многопоточной реализации.

  • 'posix' и 'dce' могут быть взаимозаменяемыми для обозначения различных версий Posix threads. Скрипт configure попытается определить, какой из них установлен.

  • 'none' означает что GLib будет сохранять многопоточность, но не имеет по умолчанию реализованной многопоточности. Это должно определяться с помощью g_thread_init() программистом.

--disable-included-printf и --enable-included-printf По умолчанию скрипт configure попытается автоматически определить использует ли C библиотека подходящий набор функций printf(). Точнее, configure проверит семантику snprintf() на соответствие стандарту C99 и что позиционные параметры соответствуют Single Unix Specification. Если это не так, GLib включит реализацию семейства функций printf(). Эти опции могут использоваться для непосредственного осуществления контроля включения или не включения реализации семейства функций printf().

--disable-visibility и --enable-visibility По умолчанию, GLib использует видимые атрибуты в формате ELF для оптимизации PLT таблицы ввода если компилятор поддерживает ELF видимые атрибуты. Побочный эффект в том что текущая реализация при любом изменении заголовка вызывает полную перекомпиляцию, а отсутствие includes может быть незамечено. Поэтому имеет смысл выключать эту особенность выполняя разработку GLib, даже если компилятор поддерживает ELF видимость атрибутов. Опция --disable-visibility позволяет делать это.

--disable-gtk-doc и --enable-gtk-doc По умолчанию скрипт configure попытается автоматически определить установлен ли пакет gtk-doc. Если да, то использует его для извлечения и сборки документации для GLib библиотеки. Эти опции используются для непосредственного контроля должен ли применяться gtk-doc или нет. Если он не используется, то будут установлены предварительно сгенерированные HTML файлы вместо сборки их на вашей машине.

--disable-man и --enable-man По умолчанию скрипт configure попытается автоматически определить установлен ли xsltproc и необходимые таблицы стилей Docbook. Если установлены, то они будут использованы для пересборки включенных страниц руководства (man pages) из XML исходников. Эти опции могут использоваться для непосредственного контроля должны ли страницы руководства (man pages) пересобираться или нет. Дистрибутив включает предварительно сгенерированные man страницы.



Changes to GLib

Changes to GLib — Incompatible changes made between successing versions of GLib

Incompatible changes from 2.0 to 2.2

  • GLib changed the seeding algorithm for the pseudo-random number generator Mersenne Twister, as used by GRand and GRandom. This was necessary, because some seeds would yield very bad pseudo-random streams. Also the pseudo-random integers generated by g_rand*_int_range() will have a slightly better equal distribution with the new version of GLib.

    Further information can be found at the website of the Mersenne Twister random number generator at http://www.math.keio.ac.jp/~matumoto/emt.html.

    The original seeding and generation algorithms, as found in GLib 2.0.x, can be used instead of the new ones by setting the environment variable G_RANDOM_VERSION to the value of '2.0'. Use the GLib-2.0 algorithms only if you have sequences of numbers generated with Glib-2.0 that you need to reproduce exactly.

Incompatible changes from 1.2 to 2.0

The GNOME 2.0 porting guide on http://developer.gnome.org has some more detailed discussion of porting from 1.2 to 2.0. See the section on GLib.

  • The event loop functionality GMain has extensively been revised to support multiple separate main loops in separate threads. All sources (timeouts, idle functions, etc.) are associated with a GMainContext.

    Compatibility functions exist so that most application code dealing with the main loop will continue to work. However, code that creates new custom types of sources will require modification.

    The main changes here are:

    • Sources are now exposed as GSource *, rather than simply as numeric ids.

    • New types of sources are created by structure "derivation" from GSource, so the source_data parameter to the GSource virtual functions has been replaced with a GSource *.

    • Sources are first created, then later added to a specific GMainContext.

    • Dispatching has been modified so both the callback and data are passed in to the dispatch() virtual function.

    To go along with this change, the vtable for GIOChannel has changed and add_watch() has been replaced by create_watch().

  • g_list_foreach() and g_slist_foreach() have been changed so they are now safe against removal of the current item, not the next item.

    It's not recommended to mutate the list in the callback to these functions in any case.

  • GDate now works in UTF-8, not in the current locale. If you want to use it with the encoding of the locale, you need to convert strings using g_locale_to_utf8() first.

  • g_strsplit() has been fixed to:

    • include trailing empty tokens, rather than stripping them

    • split into a maximum of max_tokens tokens, rather than max_tokens + 1

    Code depending on either of these bugs will need to be fixed.

  • Deprecated functions that got removed: g_set_error_handler(), g_set_warning_handler(), g_set_message_handler(), use g_log_set_handler() instead.


Компиляция приложений GLib

Compiling GLib Applications — Как скомпилировать ваше GLib приложение

Компиляция GLib приложений в UNIX

Для компиляции GLib приложений, вам необходимо сообщить компилятору где находятся заголовочные файлы и библиотека GLib. Это выполняется с помощью утилиты pkg-config.

В следующем примере демонстрируется как использовать pkg-config (фактический вывод в вашей системе может отличаться):

$ pkg-config --cflags glib-2.0
 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include 
$ pkg-config --libs glib-2.0
 -L/usr/lib -lm -lglib-2.0  

Если ваше приложение использует потоки (threads) или GObject особенности, оно может быть скомпилировано и слинковано с помощью опций возвращаемых следующими вызовами pkg-config:

$ pkg-config --cflags --libs gthread-2.0
$ pkg-config --cflags --libs gobject-2.0

Если ваше приложение использует модули, оно может быть слинковано и скомпилировано с помощью опций возвращаемых одним из следующих вызовов pkg-config:

$ pkg-config --cflags --libs gmodule-no-export-2.0 
$ pkg-config --cflags --libs gmodule-2.0 

Отличие между двумя этими gmodule-2.0 в добавляемом флажке --export-dynamic к линковщику, который зачастую ненужен.

Простой способ компиляции программ - это использование "backticks" особенности оболочки. Если вы заключите команду в обратные одинарные кавычки (backticks) (не одиночные кавычки), то вывод будет перенаправлен в командную строку перед выполнением основной команды. Таким образом для компиляции GLib Hello, World, вы должны напечатать следующее:

$ cc `pkg-config --cflags --libs glib-2.0` hello.c -o hello

Если вы уверены что ваша программа не использует устаревших функций, вы можете определить символ препроцессора G_DISABLE_DEPRECATED используя опцию командной строки -DG_DISABLE_DEPRECATED=1.



Cross-компиляция пакета GLib

Cross-compiling the GLib Package — Как скомпилировать пакет GLib для разных платформ.

Сборка библиотеки для разных архитектур

Cross-компиляция это процесс компиляции программ или библиотек на разных архитектурах или операционных системах на которых они будут выполняться. GLib немного сложна для cross-компиляции чем большинство пакетов потому что большая часть GLib о скрытых различиях между разными системами.

Данные замечания разъясняют специфику cross-компиляции GLib; основную информацию о cross-компиляции, смотрите в autoconf info pages.

GLib попытается обнаружить как можно больше информации о целевой системе с помощью компиляции и линковки программ ничего фактически не выполняя; однако, некоторая информация необходимая GLib не доступна таким способом. Эту информацию нужно обеспечить для скрипта configure через "cache file" или с помощью настроек переменных в вашем окружении.

Как пример использования кэш файла (cache file), при cross-компиляции для "MingW32" Win32 окружения на Linux системе, создаём файл 'win32.cache' со следующим содержимым:

 
glib_cv_long_long_format=I64
glib_cv_stack_grows=no
      

Затем выполняем следующие команды:

PATH=/path/to/mingw32-compiler/bin:$PATH
chmod a-w win32.cache   # prevent configure from changing it
./configure --cache-file=win32.cache --host=mingw32
      

Полный список переменных кэш файла следующий. Большинство из этого не нужно устанавливать в большинстве случаев.

Переменные кэш файла

glib_cv_long_long_format=[ll/q/I64].  Формат используемой printf() и scanf() для 64 bit целых. "ll" это стандарт C99, что означает использование библиотеки 'trio' которую GLib соберёт если ваша printf() недостаточно функциональна. Не нужно устанавливать если вы собираетесь компилировать с использованием trio.

glib_cv_stack_grows=[yes/no].  Увеличение стека вверх или вниз. Для большинства необходимо "no", некоторые архитектуры, такие как PA-RISC нуждаются в "yes".

glib_cv_working_bcopy=[yes/no].  Может ли ваш bcopy() обрабатывать перекрывающиеся копии. Нужно установить только если вы не имеете memmove(). (Очень вряд ли)

glib_cv_sane_realloc=[yes/np].  Соответствует ли ваш realloc() ANSI C и может ли обрабатывать NULL как первый аргумент. По умолчанию "yes" и вероятно не потребуется переустанавливать.

glib_cv_have_strlcpy=[yes/no].  Имеете ли вы strlcpy() соответствующую OpenBSD. По умолчанию "no", что является безопасным, поэтому GLib использует встроенную версию в этом случае.

glib_cv_va_val_copy=[yes/no].  Может ли va_list копироваться как указатель. Если установлено в "no", то используется memcopy(). Имеет смысл только если у вас нет va_copy() или __va_copy(). (Поэтому не имеет значения для GCC.) По умолчанию "yes" что намного чаще необходимо чем "no".

glib_cv_rtldglobal_broken=[yes/no].  Обнаруживается ли ошибка в OSF/1 v5.0. По умолчанию "no".

glib_cv_uscore=[yes/no].  Нужно ли подчёркивание перед символами при поиске их через dlsym(). Необходимо для установки только если система использует dlopen()/dlsym().

ac_cv_func_posix_getpwuid_r=[yes/no].  Имеете ли вы функцию getpwuid_r (в вашей C библиотеке, а не библиотеке потока) которая соответствует спецификации POSIX. (Берёт 'struct passwd **' как последний параметр)

ac_cv_func_nonposix_getpwuid_r=[yes/no].  Имеете ли вы какой нибудь вариант getpwuid_r() который не соответствует спецификации POSIX, но мог бы использоваться GLib (or might segfault.) Нужно установить только если ac_cv_func_posix_getpwuid_r не установлен. Безопасней устанавливать в "no".

glib_cv_use_pid_surrogate=[yes/no].  Используется ли setpriority() в PID нити как метод для настройки приоритетов нитей (threads). Устанавливается только при использовании POSIX threads.

ac_cv_func_printf_unix98=[yes/no].  Поддерживает ли ваше семейство printf() стиль Unix98 %N$ параметров позиционирования. По умолчанию "no".

ac_cv_func_vsnprintf_c99=[yes/no].  Имеете ли вы vsnprintf() с семантикой C99 (C99 семантика означает возвращение количество байт которые должны быть записаны имея буфер достаточного размера). По умолчанию "no".



GLib Data Types

Memory Slices - Эффективный способ распределения групп эквивалентных по размеру участков памяти.
Memory Chunks - Устаревший способ распределения групп эквивалентных по размеру участков памяти.
Doubly-Linked Lists - Связанные списки содержащие целочисленные значения или указатели на данные, с возможностью итерации по списку в обоих направлениях.
Singly-Linked Lists - Связанные списки содержащие целочисленные значения или указатели на данные, с ограничением итерации только в одном направлении.
Double-ended Queues - Двусторонняя очередь структур данных.
Trash Stacks - Поддержка стека неиспользуемых рапределённых участков памяти.
Hash Tables - Связь между ключами и значениями для быстрого поиска.
Strings - Текстовые буферы которые автоматически увеличиваются при добавлении текста.
String Chunks - Эффективное хранение групп строк.
Arrays - Массивы произвольных элементов, которые автоматически увеличиваются при добавлении элементов.
Pointer Arrays - Массив указателей для любого типа данных, который увеличивается автоматически при добавлении элементов.
Byte Arrays - Массив байт, который автоматически увеличивается при добавлении элементов.
Balanced Binary Trees - Отсортированная коллекция пар ключ/значение оптимизированная для поиска и пересечения в определённом порядке.
N-ary Trees - Деревья данных с любым количеством ответвлений.
Quarks - Два способа связать строку и уникальный целочисленный идентификатор.
Keyed Data Lists - Списки элементов данных которые являются доступными при помощи строки или GQuark идентификатора.
Datasets - Связь групп элементов данных со специфическим расположением памяти.
Relations and Tuples - Таблицы данных которые могут быть проиндексированы любым количеством полей.
Caches - Кеши позволяют объединять комплекс структур данных для сохранения ресурсов.
Memory Allocators - Устаревший способ распределения участков памяти для GList, GSList и GNode.

GLib Fundamentals

Version Information - Переменные и функции для проверки версии GLib
Basic Types - Стандартные типы GLib, определяемые для простоты использования и переносимости.
Limits of Basic Types - Переносимый метод определения лимитов стандартных типов.
Standard Macros - Обычно используемые макросы.
Type Conversion Macros - Переносимый способ хранения целочисленных в указателях переменных.
Byte Order Macros - Переносимый способ преобразования между разными последовательностями байт.
Numerical Definitions - Математические константы и разбиение плавающей точкой.
Miscellaneous Macros - Редко используемые специализированные макросы.
Atomic Operations - основные атомарные операции с целочисленными и указателями

glib-gettextize

glib-gettextize — утилита интернационализации gettext

Краткое описание

glib-gettextize [option...] [directory]

Описание

glib-gettextize помогает подготовить исходный пакет для начала интернационализации через gettext. Это вариант gettextize которая поставляется с gettext.

glib-gettextize отличается от gettextize тем, что не создаёт подкаталог intl/ и не изменяет po/ChangeLog (помните что новые версии gettextize ведут себя таким образом когда вызваны с опцией --no-changelog).

Options

--help

печатает справку и выходит

--version

печатает информацию о версии и выходит

-c, --copy

копирует файлы вместо создания ссылок

-f, --force

заставляет записать файлы даже если они старше существующих

Смотрите также

gettextize(1)


Списки рассылки и сообщения об ошибках

Mailing lists and bug reports — Получение помощи по GLib

Сообщение об ошибке или запрос улучшений

Если вы столкнулись с ошибкой, неудобством, или пропущенной особенностью в GLib, пожалуйста отправьте сообщение об ошибке в http://bugzilla.gnome.org. Мы также будем благодарны за сообщения об ошибках или недостатках в документации GLib; поместите их напротив "docs" компонента "glib" в Bugzilla.

Пожалуйста сообщайте об ошибках даже если думаете что мы знаем о них, или не совсем уверены в деталях. Просто сообщите нам как можно больше информации которую вы имеете и если это уже обсуждалось и исправлено то мы добавим сообщение об этом.

Программа слежения за ошибками (bug tracker) должна использоваться для запросов улучшений, она не только для ошибок. Мы отслеживаем всю разработку GLib в Bugzilla, таким образом это хороший способ убедиться что разработчики GLib не забудут об этом улучшении.

Передача исправлений

Если вы разработали исправление ошибки или усовершенствование для GLib, пожалуйста отправьте его также в Bugzilla. Bugzilla позволяет вам прикреплять файлы; пожалуйста прикрепите "заплатку" (patch) сгенерированную утилитой diff, используя -u опцию для создания более читабельной "заплатки" (patch). Все "заплатки" должны быть под лицензией GNU LGPL, поэтому убедитесь что вы уполномочены представлять "заплатки" (patch) согласно этой лицензии.

Если вы хотите обсудить ваше исправление до или после разработки, пишите на gtk-devel-list@gnome.org. Но убедитесь в том что сообщили об этом в Bugzilla; если "заплатка" (patch) будет только в списке рассылки и не будет присутствовать в Bugzilla, она вероятней всего будет рассмотрена как ошибка.

Списки рассылки

Есть несколько адресов списков рассылки специализированных для GTK+ и связанных с ней библиотек. Дискусии о GLib в основном происходят в этих списках рассылки. Вы можете подписаться или посмотреть эти списки на http://mail.gnome.org.

gtk-list@gnome.org

gtk-list в основном относится к GTK+ (и GLib); вопросы об использовании GLib в программах, GLib с точки зрения пользователей, анонсы GLib-связанных проектов входят в диапазон данного списка рассылки. Большая часть трафика состоит из вопросов связанных с программированием с помощью GTK+.

gtk-devel-list@gnome.org

gtk-devel-list для дискуссий непосредственно о работе в GTK+ (и GLib), он не для вопросов о том как использовать GTK+ (или GLib) в приложениях. gtk-devel-list предназначен для обсуждения "заплаток" (patches), ошибок, будущих улучшений, и так далее.

gtk-doc-list@gnome.org

gtk-doc-list для обсуждения системы документирования gtk-doc (используется для документации GTK+ и Glib), и для работы над документацией GTK+ (и GLib).



Выполнение GLib приложения

Running GLib Applications — Как выполнять и отлаживать GLib приложение

Выполнение и отладка GLib приложений

Переменные окружения

GLib проверяет несколько переменных окружения в дополнение к стандартным переменным таких как LANG, PATH или HOME.

G_FILENAME_ENCODING Эта переменная окружения может определять разделённый запятыми список имён наборов символов. GLib предполагает что имена файлов находятся в кодировке первого набора символов в этом списке вместо UTF-8. Специальная лексема "@locale" может использоваться для определения набора символов текущей локали (locale).

G_BROKEN_FILENAMES Если эта переменная окружения установлена, GLib предполагает что имена файлов находятся в кодировке локали (locale) вместо UTF-8. G_FILENAME_ENCODING имеет приоритет над G_BROKEN_FILENAMES.

G_MESSAGES_PREFIXED Список регистрационного уровня для которого сообщения должны быть предустановленны именем программы и PID приложения. По умолчанию с префиксом все кроме G_LOG_LEVEL_MESSAGE и G_LOG_LEVEL_INFO.

G_DEBUG Если GLib сконфигурирована с --enable-debug=yes, эта переменная может быть установлена в список отладочных опций, которые заставят GLib печатать различную отладочную информацию.

fatal_warnings

Заставит GLib прервать программу при первом вызове g_warning() или g_critical(). Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки.

fatal_criticals

Заставит GLib прервать программу при первом вызове g_critical(). Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки.

gc-friendly

Вновь распределенная память которая непосредственно не инициализирована, также как освобождаемая память будет сброшена в 0. Позволяет проверочным программам памяти и подобным программам использующим алгоритмы подобные GC (сборщик мусора) произвести более точные результаты. Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки.

resident-modules

Все модули загруженные GModule будут сделаны постоянно находящимися в оперативной памяти. Это может быть полезно при отслеживании утечек памяти в модулях которые загружаются позже; но это может также скрыть ошибки когда к коду обращаются после обычной выгрузки модуля. Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки.

bind-now-modules

Все модули загруженные GModule свяжут свои идентификаторы во время загрузки, даже когда код использует %G_MODULE_BIND_LAZY. Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки.

G_SLICE Эта переменная окружения позволяет переконфигурировать #GSlice программу распределения памяти (memory allocator).

always-malloc

Это заставит все участки распределённые через g_slice_alloc() и освобожденные с помощью g_slice_free1() фактически распределяться непосредственно через вызовы g_malloc() и g_free(). Позволяет проверочным программам памяти и подобным программам использующим алгоритмы подобные GC (сборщик мусора) произвести более точные результаты. Может также связать с отладочной особенностью реализации системы malloc такой как glibc's MALLOC_CHECK_=2 для отладки кода ошибочно распределенных участков.

G_RANDOM_VERSION Если эта переменная установлена в '2.0', будут использоваться устаревшие алгоритмы генерирования псевдо-случайных чисел из GLib-2.0 вместо улучшенных новых. Используйте GLib-2.0 алгоритмы только если вы генерировали последовательность чисел с помощью Glib-2.0 которую вам нужно воспроизвести в точности.

LIBCHARSET_ALIAS_DIR Позволяет специфичное не стандартное расположение для charset.aliases файла который используется подпрограммами конвертации наборов символов. По умолчанию расположение определяет libdir во время компиляции.

G_WIN32_PRETEND_WIN9X Установка этой переменной в любое значение заставит g_win32_get_windows_version() возвращать версию кода для Windows 9x. Это главным образом для внутренней отладки GTK+ и GLib, позволяет разработчикам проверить код для Windows 9x.


Ловушки и трассировка (Traps and traces)

Некоторые части кода содержат переменные "ловушки" которые могут быть установлены во время отладки если GLib сконфигурирована с --enable-debug=yes. Такие "ловушки" приводят к непосредственной остановки кода для исследования текущего состояния программы и отслеживания (backtrace).

В настоящее время существуют следующие переменные "ловушки":

static volatile gulong g_trap_free_size;
static volatile gulong g_trap_realloc_size;
static volatile gulong g_trap_malloc_size;

Если установлен размер > 0, g_free(), g_realloc() и g_malloc() будут прерваны, если размер будет соответствовать размеру блока памяти. Это работает только с g_mem_set_vtable (glib_mem_profiler_table) во время старта, потому что профиль памяти требует соответствия в размерах блоков памяти.

Помните что многие современные отладчики поддерживают условные точки остановки, которые выполняют аналогичные функции. Например в gdb, вы можете сделать следующее

break g_malloc
condition 1 n_bytes == 20

для остановки только в g_malloc() вызове где размер распределяемого блока равен 20.



GLib Utilities

String Utility Functions - Варианты строковых функций.
Character Set Conversion - конвертирование строк между разными наборами символов используя iconv().
Unicode Manipulation - Функции оперирующие на Unicode символах и UTF-8 строках.
Base64 Encoding - Кодирование и декодирование данных в формат Base64
Internationalization - Макросы поддерживающие gettext.
Date and Time Functions - Календарные вычисления и различный временной материал.
Random Numbers - Генератор псевдо-случайных чисел.
Hook Functions - Поддержка для манипулирования списками hook-функций.
Miscellaneous Utility Functions - Набор портируемых сервисных функций.
Lexical Scanner - Универсальный лексический сканер.
Automatic String Completion - поддержка автоматического завершения строк используя группу целевых строк.
Timers - Отслеживание прошедшего времени.
Spawning Processes - Порождение процессов с помощью fork()/exec().
File Utilities - Варианты функций связанных с файлами.
Shell-related Utilities - shell-подобная обработка командной строки.
Commandline option parser - Анализатор опций командной строки
Glob-style pattern matching - Сравнение строк с шаблонами содержащими '*' (wildcard) и '?' (joker).
Simple XML Subset Parser - Синтаксический анализатор подмножества XML.
Key-value file parser - Анализ .ini-подобных конфигурационных файлов
Bookmark file parser - Анализ файлов содержащих закладки
Windows Compatibility Functions - Эмуляция UNIX в Windows.

GLib Overview

Compiling the GLib package - Как самостоятельно скомпилировать GLib
Cross-compiling the GLib package - Как скомпилировать пакет GLib для разных архитектур
Compiling GLib Applications - Как скомпилировать ваше GLib приложение
Running GLib Applications - Как выполнять и отлаживать GLib приложение
Changes to GLib - Несовместимые изменения сделанные между разными версиями GLib
Mailing lists and bug reports - Получение помощи по GLib

GLib это универсальная библиотека, которая обеспечивает много полезных типов данных, макросов, преобразований типов, строковых утилит, файловых утилит, абстракцию основного цикла и многое другое. Она работает на большинстве UNIX-подобных платформах, Windows, OS/2 и BeOS. GLib реализована на основе GNU Library General Public License (GNU LGPL).

Основная политика GLib в том, что все функции являются невидимыми и многопоточными за исключением функций манипулирующих структурными данными, где, если вы имеете два потока манипуляции одинаковыми данными структуры, они могут использовать блокировку для синхронизации своих операций.


Index

Symbols

_, _()

A

ABS, ABS()

C

CLAMP, CLAMP()

F

FALSE, FALSE

G

GAllocator, GAllocator
GArray, GArray
GAsyncQueue, GAsyncQueue
GBookmarkFile, GBookmarkFile
GBookmarkFileError, enum GBookmarkFileError
gboolean, gboolean
GByteArray, GByteArray
GCache, GCache
GCacheDestroyFunc, GCacheDestroyFunc ()
GCacheDupFunc, GCacheDupFunc ()
GCacheNewFunc, GCacheNewFunc ()
gchar, gchar
GChildWatchFunc, GChildWatchFunc ()
GCompareDataFunc, GCompareDataFunc ()
GCompareFunc, GCompareFunc ()
GCompletion, GCompletion
GCompletionFunc, GCompletionFunc ()
GCompletionStrncmpFunc, GCompletionStrncmpFunc ()
GCond, GCond
gconstpointer, gconstpointer
GConvertError, enum GConvertError
GCopyFunc, GCopyFunc ()
GData, GData
GDataForeachFunc, GDataForeachFunc ()
GDate, GDate
GDateDay, GDateDay
GDateDMY, enum GDateDMY
GDateMonth, enum GDateMonth
GDateWeekday, enum GDateWeekday
GDateYear, GDateYear
GDebugKey, GDebugKey
GDestroyNotify, GDestroyNotify ()
GDir, GDir
gdouble, gdouble
GDoubleIEEE754, union GDoubleIEEE754
GEqualFunc, GEqualFunc ()
GError, GError
GErrorType, enum GErrorType
GFileError, enum GFileError
GFileTest, enum GFileTest
gfloat, gfloat
GFloatIEEE754, union GFloatIEEE754
GFreeFunc, GFreeFunc ()
GFunc, GFunc ()
GHashFunc, GHashFunc ()
GHashTable, GHashTable
GHFunc, GHFunc ()
GHook, GHook
GHookCheckFunc, GHookCheckFunc ()
GHookCheckMarshaller, GHookCheckMarshaller ()
GHookCompareFunc, GHookCompareFunc ()
GHookFinalizeFunc, GHookFinalizeFunc ()
GHookFindFunc, GHookFindFunc ()
GHookFlagMask, enum GHookFlagMask
GHookFunc, GHookFunc ()
GHookList, GHookList
GHookMarshaller, GHookMarshaller ()
GHRFunc, GHRFunc ()
GIConv, GIConv
gint, gint
gint16, gint16
GINT16_FROM_BE, GINT16_FROM_BE()
GINT16_FROM_LE, GINT16_FROM_LE()
GINT16_TO_BE, GINT16_TO_BE()
GINT16_TO_LE, GINT16_TO_LE()
gint32, gint32
GINT32_FROM_BE, GINT32_FROM_BE()
GINT32_FROM_LE, GINT32_FROM_LE()
GINT32_TO_BE, GINT32_TO_BE()
GINT32_TO_LE, GINT32_TO_LE()
gint64, gint64
GINT64_FROM_BE, GINT64_FROM_BE()
GINT64_FROM_LE, GINT64_FROM_LE()
GINT64_TO_BE, GINT64_TO_BE()
GINT64_TO_LE, GINT64_TO_LE()
gint8, gint8
GINT_FROM_BE, GINT_FROM_BE()
GINT_FROM_LE, GINT_FROM_LE()
GINT_TO_BE, GINT_TO_BE()
GINT_TO_LE, GINT_TO_LE()
GINT_TO_POINTER, GINT_TO_POINTER()
GIOChannel, GIOChannel
GIOChannelError, enum GIOChannelError
GIOCondition, enum GIOCondition
GIOError, enum GIOError
GIOFlags, enum GIOFlags
GIOFunc, GIOFunc ()
GIOFuncs, GIOFuncs
GIOStatus, enum GIOStatus
GKeyFile, GKeyFile
GKeyFileError, enum GKeyFileError
GKeyFileFlags, enum GKeyFileFlags
glib_binary_age, glib_binary_age
glib_check_version, glib_check_version ()
GLIB_CHECK_VERSION, GLIB_CHECK_VERSION()
glib_interface_age, glib_interface_age
glib_major_version, glib_major_version
GLIB_MAJOR_VERSION, GLIB_MAJOR_VERSION
glib_mem_profiler_table, glib_mem_profiler_table
glib_micro_version, glib_micro_version
GLIB_MICRO_VERSION, GLIB_MICRO_VERSION
glib_minor_version, glib_minor_version
GLIB_MINOR_VERSION, GLIB_MINOR_VERSION
GList, GList
GLogFunc, GLogFunc ()
GLogLevelFlags, enum GLogLevelFlags
glong, glong
GLONG_FROM_BE, GLONG_FROM_BE()
GLONG_FROM_LE, GLONG_FROM_LE()
GLONG_TO_BE, GLONG_TO_BE()
GLONG_TO_LE, GLONG_TO_LE()
GMainContext, GMainContext
GMainLoop, GMainLoop
GMappedFile, GMappedFile
GMarkupError, enum GMarkupError
GMarkupParseContext, GMarkupParseContext
GMarkupParseFlags, enum GMarkupParseFlags
GMarkupParser, GMarkupParser
GMemChunk, GMemChunk
GMemVTable, GMemVTable
GModule, GModule
GModuleCheckInit, GModuleCheckInit ()
GModuleFlags, enum GModuleFlags
GModuleUnload, GModuleUnload ()
GMutex, GMutex
GNode, GNode
GNodeForeachFunc, GNodeForeachFunc ()
GNodeTraverseFunc, GNodeTraverseFunc ()
GNormalizeMode, enum GNormalizeMode
GOnce, GOnce
GOnceStatus, enum GOnceStatus
GOptionArg, enum GOptionArg
GOptionArgFunc, GOptionArgFunc ()
GOptionContext, GOptionContext
GOptionEntry, GOptionEntry
GOptionError, enum GOptionError
GOptionErrorFunc, GOptionErrorFunc ()
GOptionFlags, enum GOptionFlags
GOptionGroup, GOptionGroup
GOptionParseFunc, GOptionParseFunc ()
GPatternSpec, GPatternSpec
GPid, GPid
gpointer, gpointer
GPOINTER_TO_INT, GPOINTER_TO_INT()
GPOINTER_TO_SIZE, GPOINTER_TO_SIZE()
GPOINTER_TO_UINT, GPOINTER_TO_UINT()
GPollFD, GPollFD
GPollFunc, GPollFunc ()
GPrintFunc, GPrintFunc ()
GPrivate, GPrivate
GPtrArray, GPtrArray
GQuark, GQuark
GQueue, GQueue
GRand, GRand
GRelation, GRelation
GScanner, GScanner
GScannerConfig, GScannerConfig
GScannerMsgFunc, GScannerMsgFunc ()
GSeekType, enum GSeekType
GShellError, enum GShellError
gshort, gshort
gsize, gsize
GSIZE_TO_POINTER, GSIZE_TO_POINTER()
GSList, GSList
GSource, GSource
GSourceCallbackFuncs, GSourceCallbackFuncs
GSourceDummyMarshal, GSourceDummyMarshal ()
GSourceFunc, GSourceFunc ()
GSourceFuncs, GSourceFuncs
GSpawnChildSetupFunc, GSpawnChildSetupFunc ()
GSpawnError, enum GSpawnError
GSpawnFlags, enum GSpawnFlags
gssize, gssize
GStaticMutex, GStaticMutex
GStaticPrivate, GStaticPrivate
GStaticRecMutex, GStaticRecMutex
GStaticRWLock, GStaticRWLock
GString, GString
GStringChunk, GStringChunk
GThread, GThread
GThreadError, enum GThreadError
GThreadFunc, GThreadFunc ()
GThreadFunctions, GThreadFunctions
GThreadPool, GThreadPool
GThreadPriority, enum GThreadPriority
GTime, GTime
GTimer, GTimer
GTimeVal, GTimeVal
GTokenType, enum GTokenType
GTokenValue, union GTokenValue
GTranslateFunc, GTranslateFunc ()
GTrashStack, GTrashStack
GTraverseFlags, enum GTraverseFlags
GTraverseFunc, GTraverseFunc ()
GTraverseType, enum GTraverseType
GTree, GTree
GTuples, GTuples
guchar, guchar
guint, guint
guint16, guint16
GUINT16_FROM_BE, GUINT16_FROM_BE()
GUINT16_FROM_LE, GUINT16_FROM_LE()
GUINT16_SWAP_BE_PDP, GUINT16_SWAP_BE_PDP()
GUINT16_SWAP_LE_BE, GUINT16_SWAP_LE_BE()
GUINT16_SWAP_LE_PDP, GUINT16_SWAP_LE_PDP()
GUINT16_TO_BE, GUINT16_TO_BE()
GUINT16_TO_LE, GUINT16_TO_LE()
guint32, guint32
GUINT32_FROM_BE, GUINT32_FROM_BE()
GUINT32_FROM_LE, GUINT32_FROM_LE()
GUINT32_SWAP_BE_PDP, GUINT32_SWAP_BE_PDP()
GUINT32_SWAP_LE_BE, GUINT32_SWAP_LE_BE()
GUINT32_SWAP_LE_PDP, GUINT32_SWAP_LE_PDP()
GUINT32_TO_BE, GUINT32_TO_BE()
GUINT32_TO_LE, GUINT32_TO_LE()
guint64, guint64
GUINT64_FROM_BE, GUINT64_FROM_BE()
GUINT64_FROM_LE, GUINT64_FROM_LE()
GUINT64_SWAP_LE_BE, GUINT64_SWAP_LE_BE()
GUINT64_TO_BE, GUINT64_TO_BE()
GUINT64_TO_LE, GUINT64_TO_LE()
guint8, guint8
GUINT_FROM_BE, GUINT_FROM_BE()
GUINT_FROM_LE, GUINT_FROM_LE()
GUINT_TO_BE, GUINT_TO_BE()
GUINT_TO_LE, GUINT_TO_LE()
GUINT_TO_POINTER, GUINT_TO_POINTER()
gulong, gulong
GULONG_FROM_BE, GULONG_FROM_BE()
GULONG_FROM_LE, GULONG_FROM_LE()
GULONG_TO_BE, GULONG_TO_BE()
GULONG_TO_LE, GULONG_TO_LE()
gunichar, gunichar
gunichar2, gunichar2
GUnicodeBreakType, enum GUnicodeBreakType
GUnicodeScript, enum GUnicodeScript
GUnicodeType, enum GUnicodeType
gushort, gushort
GVoidFunc, GVoidFunc ()
g_access, g_access ()
g_alloca, g_alloca()
g_allocator_free, g_allocator_free ()
g_allocator_new, g_allocator_new ()
G_ALLOC_AND_FREE, G_ALLOC_AND_FREE
G_ALLOC_ONLY, G_ALLOC_ONLY
g_array_append_val, g_array_append_val()
g_array_append_vals, g_array_append_vals ()
g_array_free, g_array_free ()
g_array_index, g_array_index()
g_array_insert_val, g_array_insert_val()
g_array_insert_vals, g_array_insert_vals ()
g_array_new, g_array_new ()
g_array_prepend_val, g_array_prepend_val()
g_array_prepend_vals, g_array_prepend_vals ()
g_array_remove_index, g_array_remove_index ()
g_array_remove_index_fast, g_array_remove_index_fast ()
g_array_remove_range, g_array_remove_range ()
g_array_set_size, g_array_set_size ()
g_array_sized_new, g_array_sized_new ()
g_array_sort, g_array_sort ()
g_array_sort_with_data, g_array_sort_with_data ()
g_ascii_digit_value, g_ascii_digit_value ()
g_ascii_dtostr, g_ascii_dtostr ()
G_ASCII_DTOSTR_BUF_SIZE, G_ASCII_DTOSTR_BUF_SIZE
g_ascii_formatd, g_ascii_formatd ()
g_ascii_isalnum, g_ascii_isalnum ()
g_ascii_isalpha, g_ascii_isalpha ()
g_ascii_iscntrl, g_ascii_iscntrl ()
g_ascii_isdigit, g_ascii_isdigit ()
g_ascii_isgraph, g_ascii_isgraph ()
g_ascii_islower, g_ascii_islower ()
g_ascii_isprint, g_ascii_isprint ()
g_ascii_ispunct, g_ascii_ispunct ()
g_ascii_isspace, g_ascii_isspace ()
g_ascii_isupper, g_ascii_isupper ()
g_ascii_isxdigit, g_ascii_isxdigit ()
g_ascii_strcasecmp, g_ascii_strcasecmp ()
g_ascii_strdown, g_ascii_strdown ()
g_ascii_strncasecmp, g_ascii_strncasecmp ()
g_ascii_strtod, g_ascii_strtod ()
g_ascii_strtoll, g_ascii_strtoll ()
g_ascii_strtoull, g_ascii_strtoull ()
g_ascii_strup, g_ascii_strup ()
g_ascii_tolower, g_ascii_tolower ()
g_ascii_toupper, g_ascii_toupper ()
g_ascii_xdigit_value, g_ascii_xdigit_value ()
g_assert, g_assert()
g_assert_not_reached, g_assert_not_reached()
g_async_queue_length, g_async_queue_length ()
g_async_queue_length_unlocked, g_async_queue_length_unlocked ()
g_async_queue_lock, g_async_queue_lock ()
g_async_queue_new, g_async_queue_new ()
g_async_queue_pop, g_async_queue_pop ()
g_async_queue_pop_unlocked, g_async_queue_pop_unlocked ()
g_async_queue_push, g_async_queue_push ()
g_async_queue_push_sorted, g_async_queue_push_sorted ()
g_async_queue_push_sorted_unlocked, g_async_queue_push_sorted_unlocked ()
g_async_queue_push_unlocked, g_async_queue_push_unlocked ()
g_async_queue_ref, g_async_queue_ref ()
g_async_queue_ref_unlocked, g_async_queue_ref_unlocked ()
g_async_queue_sort, g_async_queue_sort ()
g_async_queue_sort_unlocked, g_async_queue_sort_unlocked ()
g_async_queue_timed_pop, g_async_queue_timed_pop ()
g_async_queue_timed_pop_unlocked, g_async_queue_timed_pop_unlocked ()
g_async_queue_try_pop, g_async_queue_try_pop ()
g_async_queue_try_pop_unlocked, g_async_queue_try_pop_unlocked ()
g_async_queue_unlock, g_async_queue_unlock ()
g_async_queue_unref, g_async_queue_unref ()
g_async_queue_unref_and_unlock, g_async_queue_unref_and_unlock ()
g_atexit, g_atexit ()
g_atomic_int_add, g_atomic_int_add ()
g_atomic_int_compare_and_exchange, g_atomic_int_compare_and_exchange ()
g_atomic_int_dec_and_test, g_atomic_int_dec_and_test ()
g_atomic_int_exchange_and_add, g_atomic_int_exchange_and_add ()
g_atomic_int_get, g_atomic_int_get ()
g_atomic_int_inc, g_atomic_int_inc ()
g_atomic_int_set, g_atomic_int_set ()
g_atomic_pointer_compare_and_exchange, g_atomic_pointer_compare_and_exchange ()
g_atomic_pointer_get, g_atomic_pointer_get ()
g_atomic_pointer_set, g_atomic_pointer_set ()
g_base64_decode, g_base64_decode ()
g_base64_decode_step, g_base64_decode_step ()
g_base64_encode, g_base64_encode ()
g_base64_encode_close, g_base64_encode_close ()
g_base64_encode_step, g_base64_encode_step ()
g_basename, g_basename ()
G_BEGIN_DECLS, G_BEGIN_DECLS
G_BIG_ENDIAN, G_BIG_ENDIAN
g_bit_nth_lsf, g_bit_nth_lsf ()
g_bit_nth_msf, g_bit_nth_msf ()
g_bit_storage, g_bit_storage ()
g_blow_chunks, g_blow_chunks ()
g_bookmark_file_add_application, g_bookmark_file_add_application ()
g_bookmark_file_add_group, g_bookmark_file_add_group ()
G_BOOKMARK_FILE_ERROR, G_BOOKMARK_FILE_ERROR
g_bookmark_file_free, g_bookmark_file_free ()
g_bookmark_file_get_added, g_bookmark_file_get_added ()
g_bookmark_file_get_applications, g_bookmark_file_get_applications ()
g_bookmark_file_get_app_info, g_bookmark_file_get_app_info ()
g_bookmark_file_get_description, g_bookmark_file_get_description ()
g_bookmark_file_get_groups, g_bookmark_file_get_groups ()
g_bookmark_file_get_icon, g_bookmark_file_get_icon ()
g_bookmark_file_get_is_private, g_bookmark_file_get_is_private ()
g_bookmark_file_get_mime_type, g_bookmark_file_get_mime_type ()
g_bookmark_file_get_modified, g_bookmark_file_get_modified ()
g_bookmark_file_get_size, g_bookmark_file_get_size ()
g_bookmark_file_get_title, g_bookmark_file_get_title ()
g_bookmark_file_get_uris, g_bookmark_file_get_uris ()
g_bookmark_file_get_visited, g_bookmark_file_get_visited ()
g_bookmark_file_has_application, g_bookmark_file_has_application ()
g_bookmark_file_has_group, g_bookmark_file_has_group ()
g_bookmark_file_has_item, g_bookmark_file_has_item ()
g_bookmark_file_load_from_data, g_bookmark_file_load_from_data ()
g_bookmark_file_load_from_data_dirs, g_bookmark_file_load_from_data_dirs ()
g_bookmark_file_load_from_file, g_bookmark_file_load_from_file ()
g_bookmark_file_move_item, g_bookmark_file_move_item ()
g_bookmark_file_new, g_bookmark_file_new ()
g_bookmark_file_remove_application, g_bookmark_file_remove_application ()
g_bookmark_file_remove_group, g_bookmark_file_remove_group ()
g_bookmark_file_remove_item, g_bookmark_file_remove_item ()
g_bookmark_file_set_added, g_bookmark_file_set_added ()
g_bookmark_file_set_app_info, g_bookmark_file_set_app_info ()
g_bookmark_file_set_description, g_bookmark_file_set_description ()
g_bookmark_file_set_groups, g_bookmark_file_set_groups ()
g_bookmark_file_set_icon, g_bookmark_file_set_icon ()
g_bookmark_file_set_is_private, g_bookmark_file_set_is_private ()
g_bookmark_file_set_mime_type, g_bookmark_file_set_mime_type ()
g_bookmark_file_set_modified, g_bookmark_file_set_modified ()
g_bookmark_file_set_title, g_bookmark_file_set_title ()
g_bookmark_file_set_visited, g_bookmark_file_set_visited ()
g_bookmark_file_to_data, g_bookmark_file_to_data ()
g_bookmark_file_to_file, g_bookmark_file_to_file ()
G_BREAKPOINT, G_BREAKPOINT()
g_build_filename, g_build_filename ()
g_build_filenamev, g_build_filenamev ()
g_build_path, g_build_path ()
g_build_pathv, g_build_pathv ()
g_byte_array_append, g_byte_array_append ()
g_byte_array_free, g_byte_array_free ()
g_byte_array_new, g_byte_array_new ()
g_byte_array_prepend, g_byte_array_prepend ()
g_byte_array_remove_index, g_byte_array_remove_index ()
g_byte_array_remove_index_fast, g_byte_array_remove_index_fast ()
g_byte_array_remove_range, g_byte_array_remove_range ()
g_byte_array_set_size, g_byte_array_set_size ()
g_byte_array_sized_new, g_byte_array_sized_new ()
g_byte_array_sort, g_byte_array_sort ()
g_byte_array_sort_with_data, g_byte_array_sort_with_data ()
G_BYTE_ORDER, G_BYTE_ORDER
g_cache_destroy, g_cache_destroy ()
g_cache_insert, g_cache_insert ()
g_cache_key_foreach, g_cache_key_foreach ()
g_cache_new, g_cache_new ()
g_cache_remove, g_cache_remove ()
g_cache_value_foreach, g_cache_value_foreach ()
g_chdir, g_chdir ()
g_child_watch_add, g_child_watch_add ()
g_child_watch_add_full, g_child_watch_add_full ()
g_child_watch_source_new, g_child_watch_source_new ()
g_chmod, g_chmod ()
g_chunk_free, g_chunk_free()
g_chunk_new, g_chunk_new()
g_chunk_new0, g_chunk_new0()
g_clear_error, g_clear_error ()
g_completion_add_items, g_completion_add_items ()
g_completion_clear_items, g_completion_clear_items ()
g_completion_complete, g_completion_complete ()
g_completion_complete_utf8, g_completion_complete_utf8 ()
g_completion_free, g_completion_free ()
g_completion_new, g_completion_new ()
g_completion_remove_items, g_completion_remove_items ()
g_completion_set_compare, g_completion_set_compare ()
g_cond_broadcast, g_cond_broadcast ()
g_cond_free, g_cond_free ()
g_cond_new, g_cond_new ()
g_cond_signal, g_cond_signal ()
g_cond_timed_wait, g_cond_timed_wait ()
g_cond_wait, g_cond_wait ()
G_CONST_RETURN, G_CONST_RETURN
g_convert, g_convert ()
G_CONVERT_ERROR, G_CONVERT_ERROR
g_convert_with_fallback, g_convert_with_fallback ()
g_convert_with_iconv, g_convert_with_iconv ()
g_creat, g_creat ()
g_critical, g_critical()
G_CSET_a_2_z, G_CSET_a_2_z
G_CSET_A_2_Z, G_CSET_A_2_Z
G_CSET_DIGITS, G_CSET_DIGITS
G_CSET_LATINC, G_CSET_LATINC
G_CSET_LATINS, G_CSET_LATINS
g_datalist_clear, g_datalist_clear ()
G_DATALIST_FLAGS_MASK, G_DATALIST_FLAGS_MASK
g_datalist_foreach, g_datalist_foreach ()
g_datalist_get_data, g_datalist_get_data()
g_datalist_get_flags, g_datalist_get_flags ()
g_datalist_id_get_data, g_datalist_id_get_data ()
g_datalist_id_remove_data, g_datalist_id_remove_data()
g_datalist_id_remove_no_notify, g_datalist_id_remove_no_notify ()
g_datalist_id_set_data, g_datalist_id_set_data()
g_datalist_id_set_data_full, g_datalist_id_set_data_full ()
g_datalist_init, g_datalist_init ()
g_datalist_remove_data, g_datalist_remove_data()
g_datalist_remove_no_notify, g_datalist_remove_no_notify()
g_datalist_set_data, g_datalist_set_data()
g_datalist_set_data_full, g_datalist_set_data_full()
g_datalist_set_flags, g_datalist_set_flags ()
g_datalist_unset_flags, g_datalist_unset_flags ()
g_dataset_destroy, g_dataset_destroy ()
g_dataset_foreach, g_dataset_foreach ()
g_dataset_get_data, g_dataset_get_data()
g_dataset_id_get_data, g_dataset_id_get_data ()
g_dataset_id_remove_data, g_dataset_id_remove_data()
g_dataset_id_remove_no_notify, g_dataset_id_remove_no_notify ()
g_dataset_id_set_data, g_dataset_id_set_data()
g_dataset_id_set_data_full, g_dataset_id_set_data_full ()
g_dataset_remove_data, g_dataset_remove_data()
g_dataset_remove_no_notify, g_dataset_remove_no_notify()
g_dataset_set_data, g_dataset_set_data()
g_dataset_set_data_full, g_dataset_set_data_full()
g_date_add_days, g_date_add_days ()
g_date_add_months, g_date_add_months ()
g_date_add_years, g_date_add_years ()
G_DATE_BAD_DAY, G_DATE_BAD_DAY
G_DATE_BAD_JULIAN, G_DATE_BAD_JULIAN
G_DATE_BAD_YEAR, G_DATE_BAD_YEAR
g_date_clamp, g_date_clamp ()
g_date_clear, g_date_clear ()
g_date_compare, g_date_compare ()
g_date_days_between, g_date_days_between ()
g_date_free, g_date_free ()
g_date_get_day, g_date_get_day ()
g_date_get_days_in_month, g_date_get_days_in_month ()
g_date_get_day_of_year, g_date_get_day_of_year ()
g_date_get_iso8601_week_of_year, g_date_get_iso8601_week_of_year ()
g_date_get_julian, g_date_get_julian ()
g_date_get_monday_weeks_in_year, g_date_get_monday_weeks_in_year ()
g_date_get_monday_week_of_year, g_date_get_monday_week_of_year ()
g_date_get_month, g_date_get_month ()
g_date_get_sunday_weeks_in_year, g_date_get_sunday_weeks_in_year ()
g_date_get_sunday_week_of_year, g_date_get_sunday_week_of_year ()
g_date_get_weekday, g_date_get_weekday ()
g_date_get_year, g_date_get_year ()
g_date_is_first_of_month, g_date_is_first_of_month ()
g_date_is_last_of_month, g_date_is_last_of_month ()
g_date_is_leap_year, g_date_is_leap_year ()
g_date_new, g_date_new ()
g_date_new_dmy, g_date_new_dmy ()
g_date_new_julian, g_date_new_julian ()
g_date_order, g_date_order ()
g_date_set_day, g_date_set_day ()
g_date_set_dmy, g_date_set_dmy ()
g_date_set_julian, g_date_set_julian ()
g_date_set_month, g_date_set_month ()
g_date_set_parse, g_date_set_parse ()
g_date_set_time, g_date_set_time ()
g_date_set_time_t, g_date_set_time_t ()
g_date_set_time_val, g_date_set_time_val ()
g_date_set_year, g_date_set_year ()
g_date_strftime, g_date_strftime ()
g_date_subtract_days, g_date_subtract_days ()
g_date_subtract_months, g_date_subtract_months ()
g_date_subtract_years, g_date_subtract_years ()
g_date_to_struct_tm, g_date_to_struct_tm ()
g_date_valid, g_date_valid ()
g_date_valid_day, g_date_valid_day ()
g_date_valid_dmy, g_date_valid_dmy ()
g_date_valid_julian, g_date_valid_julian ()
g_date_valid_month, g_date_valid_month ()
g_date_valid_weekday, g_date_valid_weekday ()
g_date_valid_year, g_date_valid_year ()
g_debug, g_debug()
g_direct_equal, g_direct_equal ()
g_direct_hash, g_direct_hash ()
g_dirname, g_dirname
g_dir_close, g_dir_close ()
g_dir_open, g_dir_open ()
g_dir_read_name, g_dir_read_name ()
g_dir_rewind, g_dir_rewind ()
G_DIR_SEPARATOR, G_DIR_SEPARATOR
G_DIR_SEPARATOR_S, G_DIR_SEPARATOR_S
G_E, G_E
G_END_DECLS, G_END_DECLS
g_error, g_error()
g_error_copy, g_error_copy ()
g_error_free, g_error_free ()
g_error_matches, g_error_matches ()
g_error_new, g_error_new ()
g_error_new_literal, g_error_new_literal ()
g_filename_display_basename, g_filename_display_basename ()
g_filename_display_name, g_filename_display_name ()
g_filename_from_uri, g_filename_from_uri ()
g_filename_from_utf8, g_filename_from_utf8 ()
g_filename_to_uri, g_filename_to_uri ()
g_filename_to_utf8, g_filename_to_utf8 ()
G_FILE_ERROR, G_FILE_ERROR
g_file_error_from_errno, g_file_error_from_errno ()
g_file_get_contents, g_file_get_contents ()
g_file_open_tmp, g_file_open_tmp ()
g_file_read_link, g_file_read_link ()
g_file_set_contents, g_file_set_contents ()
g_file_test, g_file_test ()
g_find_program_in_path, g_find_program_in_path ()
g_fopen, g_fopen ()
g_fprintf, g_fprintf ()
g_free, g_free ()
g_freopen, g_freopen ()
g_getenv, g_getenv ()
g_get_application_name, g_get_application_name ()
g_get_charset, g_get_charset ()
g_get_current_dir, g_get_current_dir ()
g_get_current_time, g_get_current_time ()
g_get_filename_charsets, g_get_filename_charsets ()
g_get_home_dir, g_get_home_dir ()
g_get_host_name, g_get_host_name ()
g_get_language_names, g_get_language_names ()
g_get_prgname, g_get_prgname ()
g_get_real_name, g_get_real_name ()
g_get_system_config_dirs, g_get_system_config_dirs ()
g_get_system_data_dirs, g_get_system_data_dirs ()
g_get_tmp_dir, g_get_tmp_dir ()
g_get_user_cache_dir, g_get_user_cache_dir ()
g_get_user_config_dir, g_get_user_config_dir ()
g_get_user_data_dir, g_get_user_data_dir ()
g_get_user_name, g_get_user_name ()
G_GINT16_FORMAT, G_GINT16_FORMAT
G_GINT16_MODIFIER, G_GINT16_MODIFIER
G_GINT32_FORMAT, G_GINT32_FORMAT
G_GINT32_MODIFIER, G_GINT32_MODIFIER
G_GINT64_CONSTANT, G_GINT64_CONSTANT()
G_GINT64_FORMAT, G_GINT64_FORMAT
G_GINT64_MODIFIER, G_GINT64_MODIFIER
G_GNUC_CONST, G_GNUC_CONST
G_GNUC_DEPRECATED, G_GNUC_DEPRECATED
G_GNUC_EXTENSION, G_GNUC_EXTENSION
G_GNUC_FORMAT, G_GNUC_FORMAT()
G_GNUC_FUNCTION, G_GNUC_FUNCTION
G_GNUC_INTERNAL, G_GNUC_INTERNAL
G_GNUC_MALLOC, G_GNUC_MALLOC
G_GNUC_NORETURN, G_GNUC_NORETURN
G_GNUC_NO_INSTRUMENT, G_GNUC_NO_INSTRUMENT
G_GNUC_NULL_TERMINATED, G_GNUC_NULL_TERMINATED
G_GNUC_PRETTY_FUNCTION, G_GNUC_PRETTY_FUNCTION
G_GNUC_PRINTF, G_GNUC_PRINTF()
G_GNUC_PURE, G_GNUC_PURE
G_GNUC_SCANF, G_GNUC_SCANF()
G_GNUC_UNUSED, G_GNUC_UNUSED
G_GNUC_WARN_UNUSED_RESULT, G_GNUC_WARN_UNUSED_RESULT
G_GSIZE_FORMAT, G_GSIZE_FORMAT
G_GSIZE_MODIFIER, G_GSIZE_MODIFIER
G_GSSIZE_FORMAT, G_GSSIZE_FORMAT
G_GUINT16_FORMAT, G_GUINT16_FORMAT
G_GUINT32_FORMAT, G_GUINT32_FORMAT
G_GUINT64_CONSTANT, G_GUINT64_CONSTANT()
G_GUINT64_FORMAT, G_GUINT64_FORMAT
g_hash_table_destroy, g_hash_table_destroy ()
g_hash_table_find, g_hash_table_find ()
g_hash_table_foreach, g_hash_table_foreach ()
g_hash_table_foreach_remove, g_hash_table_foreach_remove ()
g_hash_table_foreach_steal, g_hash_table_foreach_steal ()
g_hash_table_freeze, g_hash_table_freeze()
g_hash_table_insert, g_hash_table_insert ()
g_hash_table_lookup, g_hash_table_lookup ()
g_hash_table_lookup_extended, g_hash_table_lookup_extended ()
g_hash_table_new, g_hash_table_new ()
g_hash_table_new_full, g_hash_table_new_full ()
g_hash_table_ref, g_hash_table_ref ()
g_hash_table_remove, g_hash_table_remove ()
g_hash_table_remove_all, g_hash_table_remove_all ()
g_hash_table_replace, g_hash_table_replace ()
g_hash_table_size, g_hash_table_size ()
g_hash_table_steal, g_hash_table_steal ()
g_hash_table_steal_all, g_hash_table_steal_all ()
g_hash_table_thaw, g_hash_table_thaw()
g_hash_table_unref, g_hash_table_unref ()
G_HAVE_GINT64, G_HAVE_GINT64
G_HAVE_GNUC_VISIBILITY, G_HAVE_GNUC_VISIBILITY
G_HOOK, G_HOOK()
G_HOOK_ACTIVE, G_HOOK_ACTIVE()
g_hook_alloc, g_hook_alloc ()
g_hook_append, g_hook_append()
g_hook_compare_ids, g_hook_compare_ids ()
g_hook_destroy, g_hook_destroy ()
g_hook_destroy_link, g_hook_destroy_link ()
g_hook_find, g_hook_find ()
g_hook_find_data, g_hook_find_data ()
g_hook_find_func, g_hook_find_func ()
g_hook_find_func_data, g_hook_find_func_data ()
g_hook_first_valid, g_hook_first_valid ()
G_HOOK_FLAGS, G_HOOK_FLAGS()
G_HOOK_FLAG_USER_SHIFT, G_HOOK_FLAG_USER_SHIFT
g_hook_free, g_hook_free ()
g_hook_get, g_hook_get ()
g_hook_insert_before, g_hook_insert_before ()
g_hook_insert_sorted, g_hook_insert_sorted ()
G_HOOK_IN_CALL, G_HOOK_IN_CALL()
G_HOOK_IS_UNLINKED, G_HOOK_IS_UNLINKED()
G_HOOK_IS_VALID, G_HOOK_IS_VALID()
g_hook_list_clear, g_hook_list_clear ()
g_hook_list_init, g_hook_list_init ()
g_hook_list_invoke, g_hook_list_invoke ()
g_hook_list_invoke_check, g_hook_list_invoke_check ()
g_hook_list_marshal, g_hook_list_marshal ()
g_hook_list_marshal_check, g_hook_list_marshal_check ()
g_hook_next_valid, g_hook_next_valid ()
g_hook_prepend, g_hook_prepend ()
g_hook_ref, g_hook_ref ()
g_hook_unref, g_hook_unref ()
g_htonl, g_htonl()
g_htons, g_htons()
g_iconv, g_iconv ()
g_iconv_close, g_iconv_close ()
g_iconv_open, g_iconv_open ()
g_idle_add, g_idle_add ()
g_idle_add_full, g_idle_add_full ()
g_idle_remove_by_data, g_idle_remove_by_data ()
g_idle_source_new, g_idle_source_new ()
G_IEEE754_DOUBLE_BIAS, G_IEEE754_DOUBLE_BIAS
G_IEEE754_FLOAT_BIAS, G_IEEE754_FLOAT_BIAS
G_INLINE_FUNC, G_INLINE_FUNC
g_intern_static_string, g_intern_static_string ()
g_intern_string, g_intern_string ()
g_int_equal, g_int_equal ()
g_int_hash, g_int_hash ()
g_io_add_watch, g_io_add_watch ()
g_io_add_watch_full, g_io_add_watch_full ()
g_io_channel_close, g_io_channel_close ()
G_IO_CHANNEL_ERROR, G_IO_CHANNEL_ERROR
g_io_channel_error_from_errno, g_io_channel_error_from_errno ()
g_io_channel_flush, g_io_channel_flush ()
g_io_channel_get_buffered, g_io_channel_get_buffered ()
g_io_channel_get_buffer_condition, g_io_channel_get_buffer_condition ()
g_io_channel_get_buffer_size, g_io_channel_get_buffer_size ()
g_io_channel_get_close_on_unref, g_io_channel_get_close_on_unref ()
g_io_channel_get_encoding, g_io_channel_get_encoding ()
g_io_channel_get_flags, g_io_channel_get_flags ()
g_io_channel_get_line_term, g_io_channel_get_line_term ()
g_io_channel_init, g_io_channel_init ()
g_io_channel_new_file, g_io_channel_new_file ()
g_io_channel_read, g_io_channel_read ()
g_io_channel_read_chars, g_io_channel_read_chars ()
g_io_channel_read_line, g_io_channel_read_line ()
g_io_channel_read_line_string, g_io_channel_read_line_string ()
g_io_channel_read_to_end, g_io_channel_read_to_end ()
g_io_channel_read_unichar, g_io_channel_read_unichar ()
g_io_channel_ref, g_io_channel_ref ()
g_io_channel_seek, g_io_channel_seek ()
g_io_channel_seek_position, g_io_channel_seek_position ()
g_io_channel_set_buffered, g_io_channel_set_buffered ()
g_io_channel_set_buffer_size, g_io_channel_set_buffer_size ()
g_io_channel_set_close_on_unref, g_io_channel_set_close_on_unref ()
g_io_channel_set_encoding, g_io_channel_set_encoding ()
g_io_channel_set_flags, g_io_channel_set_flags ()
g_io_channel_set_line_term, g_io_channel_set_line_term ()
g_io_channel_shutdown, g_io_channel_shutdown ()
g_io_channel_unix_get_fd, g_io_channel_unix_get_fd ()
g_io_channel_unix_new, g_io_channel_unix_new ()
g_io_channel_unref, g_io_channel_unref ()
g_io_channel_win32_new_fd, g_io_channel_win32_new_fd ()
g_io_channel_win32_new_messages, g_io_channel_win32_new_messages ()
g_io_channel_win32_new_socket, g_io_channel_win32_new_socket ()
g_io_channel_write, g_io_channel_write ()
g_io_channel_write_chars, g_io_channel_write_chars ()
g_io_channel_write_unichar, g_io_channel_write_unichar ()
g_io_create_watch, g_io_create_watch ()
G_IS_DIR_SEPARATOR, G_IS_DIR_SEPARATOR()
G_KEY_FILE_ERROR, G_KEY_FILE_ERROR
g_key_file_free, g_key_file_free ()
g_key_file_get_boolean, g_key_file_get_boolean ()
g_key_file_get_boolean_list, g_key_file_get_boolean_list ()
g_key_file_get_comment, g_key_file_get_comment ()
g_key_file_get_double, g_key_file_get_double ()
g_key_file_get_double_list, g_key_file_get_double_list ()
g_key_file_get_groups, g_key_file_get_groups ()
g_key_file_get_integer, g_key_file_get_integer ()
g_key_file_get_integer_list, g_key_file_get_integer_list ()
g_key_file_get_keys, g_key_file_get_keys ()
g_key_file_get_locale_string, g_key_file_get_locale_string ()
g_key_file_get_locale_string_list, g_key_file_get_locale_string_list ()
g_key_file_get_start_group, g_key_file_get_start_group ()
g_key_file_get_string, g_key_file_get_string ()
g_key_file_get_string_list, g_key_file_get_string_list ()
g_key_file_get_value, g_key_file_get_value ()
g_key_file_has_group, g_key_file_has_group ()
g_key_file_has_key, g_key_file_has_key ()
g_key_file_load_from_data, g_key_file_load_from_data ()
g_key_file_load_from_data_dirs, g_key_file_load_from_data_dirs ()
g_key_file_load_from_file, g_key_file_load_from_file ()
g_key_file_new, g_key_file_new ()
g_key_file_remove_comment, g_key_file_remove_comment ()
g_key_file_remove_group, g_key_file_remove_group ()
g_key_file_remove_key, g_key_file_remove_key ()
g_key_file_set_boolean, g_key_file_set_boolean ()
g_key_file_set_boolean_list, g_key_file_set_boolean_list ()
g_key_file_set_comment, g_key_file_set_comment ()
g_key_file_set_double, g_key_file_set_double ()
g_key_file_set_double_list, g_key_file_set_double_list ()
g_key_file_set_integer, g_key_file_set_integer ()
g_key_file_set_integer_list, g_key_file_set_integer_list ()
g_key_file_set_list_separator, g_key_file_set_list_separator ()
g_key_file_set_locale_string, g_key_file_set_locale_string ()
g_key_file_set_locale_string_list, g_key_file_set_locale_string_list ()
g_key_file_set_string, g_key_file_set_string ()
g_key_file_set_string_list, g_key_file_set_string_list ()
g_key_file_set_value, g_key_file_set_value ()
g_key_file_to_data, g_key_file_to_data ()
G_LIKELY, G_LIKELY()
g_listenv, g_listenv ()
g_list_alloc, g_list_alloc ()
g_list_append, g_list_append ()
g_list_concat, g_list_concat ()
g_list_copy, g_list_copy ()
g_list_delete_link, g_list_delete_link ()
g_list_find, g_list_find ()
g_list_find_custom, g_list_find_custom ()
g_list_first, g_list_first ()
g_list_foreach, g_list_foreach ()
g_list_free, g_list_free ()
g_list_free1, g_list_free1
g_list_free_1, g_list_free_1 ()
g_list_index, g_list_index ()
g_list_insert, g_list_insert ()
g_list_insert_before, g_list_insert_before ()
g_list_insert_sorted, g_list_insert_sorted ()
g_list_insert_sorted_with_data, g_list_insert_sorted_with_data ()
g_list_last, g_list_last ()
g_list_length, g_list_length ()
g_list_next, g_list_next()
g_list_nth, g_list_nth ()
g_list_nth_data, g_list_nth_data ()
g_list_nth_prev, g_list_nth_prev ()
g_list_pop_allocator, g_list_pop_allocator ()
g_list_position, g_list_position ()
g_list_prepend, g_list_prepend ()
g_list_previous, g_list_previous()
g_list_push_allocator, g_list_push_allocator ()
g_list_remove, g_list_remove ()
g_list_remove_all, g_list_remove_all ()
g_list_remove_link, g_list_remove_link ()
g_list_reverse, g_list_reverse ()
g_list_sort, g_list_sort ()
g_list_sort_with_data, g_list_sort_with_data ()
G_LITTLE_ENDIAN, G_LITTLE_ENDIAN
G_LN10, G_LN10
G_LN2, G_LN2
g_locale_from_utf8, g_locale_from_utf8 ()
g_locale_to_utf8, g_locale_to_utf8 ()
G_LOCK, G_LOCK()
G_LOCK_DEFINE, G_LOCK_DEFINE()
G_LOCK_DEFINE_STATIC, G_LOCK_DEFINE_STATIC()
G_LOCK_EXTERN, G_LOCK_EXTERN()
g_log, g_log ()
g_logv, g_logv ()
G_LOG_2_BASE_10, G_LOG_2_BASE_10
g_log_default_handler, g_log_default_handler ()
G_LOG_DOMAIN, G_LOG_DOMAIN
G_LOG_FATAL_MASK, G_LOG_FATAL_MASK
G_LOG_LEVEL_USER_SHIFT, G_LOG_LEVEL_USER_SHIFT
g_log_remove_handler, g_log_remove_handler ()
g_log_set_always_fatal, g_log_set_always_fatal ()
g_log_set_default_handler, g_log_set_default_handler ()
g_log_set_fatal_mask, g_log_set_fatal_mask ()
g_log_set_handler, g_log_set_handler ()
g_lstat, g_lstat ()
g_main_context_acquire, g_main_context_acquire ()
g_main_context_add_poll, g_main_context_add_poll ()
g_main_context_check, g_main_context_check ()
g_main_context_default, g_main_context_default ()
g_main_context_dispatch, g_main_context_dispatch ()
g_main_context_find_source_by_funcs_user_data, g_main_context_find_source_by_funcs_user_data ()
g_main_context_find_source_by_id, g_main_context_find_source_by_id ()
g_main_context_find_source_by_user_data, g_main_context_find_source_by_user_data ()
g_main_context_get_poll_func, g_main_context_get_poll_func ()
g_main_context_is_owner, g_main_context_is_owner ()
g_main_context_iteration, g_main_context_iteration ()
g_main_context_new, g_main_context_new ()
g_main_context_pending, g_main_context_pending ()
g_main_context_prepare, g_main_context_prepare ()
g_main_context_query, g_main_context_query ()
g_main_context_ref, g_main_context_ref ()
g_main_context_release, g_main_context_release ()
g_main_context_remove_poll, g_main_context_remove_poll ()
g_main_context_set_poll_func, g_main_context_set_poll_func ()
g_main_context_unref, g_main_context_unref ()
g_main_context_wait, g_main_context_wait ()
g_main_context_wakeup, g_main_context_wakeup ()
g_main_current_source, g_main_current_source ()
g_main_depth, g_main_depth ()
g_main_destroy, g_main_destroy()
g_main_is_running, g_main_is_running()
g_main_iteration, g_main_iteration()
g_main_loop_get_context, g_main_loop_get_context ()
g_main_loop_is_running, g_main_loop_is_running ()
g_main_loop_new, g_main_loop_new ()
g_main_loop_quit, g_main_loop_quit ()
g_main_loop_ref, g_main_loop_ref ()
g_main_loop_run, g_main_loop_run ()
g_main_loop_unref, g_main_loop_unref ()
g_main_new, g_main_new()
g_main_pending, g_main_pending()
g_main_quit, g_main_quit()
g_main_run, g_main_run()
g_main_set_poll_func, g_main_set_poll_func()
g_malloc, g_malloc ()
g_malloc0, g_malloc0 ()
g_mapped_file_free, g_mapped_file_free ()
g_mapped_file_get_contents, g_mapped_file_get_contents ()
g_mapped_file_get_length, g_mapped_file_get_length ()
g_mapped_file_new, g_mapped_file_new ()
G_MARKUP_ERROR, G_MARKUP_ERROR
g_markup_escape_text, g_markup_escape_text ()
g_markup_parse_context_end_parse, g_markup_parse_context_end_parse ()
g_markup_parse_context_free, g_markup_parse_context_free ()
g_markup_parse_context_get_element, g_markup_parse_context_get_element ()
g_markup_parse_context_get_position, g_markup_parse_context_get_position ()
g_markup_parse_context_new, g_markup_parse_context_new ()
g_markup_parse_context_parse, g_markup_parse_context_parse ()
g_markup_printf_escaped, g_markup_printf_escaped ()
g_markup_vprintf_escaped, g_markup_vprintf_escaped ()
G_MAXDOUBLE, G_MAXDOUBLE
G_MAXFLOAT, G_MAXFLOAT
G_MAXINT, G_MAXINT
G_MAXINT16, G_MAXINT16
G_MAXINT32, G_MAXINT32
G_MAXINT64, G_MAXINT64
G_MAXINT8, G_MAXINT8
G_MAXLONG, G_MAXLONG
G_MAXSHORT, G_MAXSHORT
G_MAXSIZE, G_MAXSIZE
G_MAXUINT, G_MAXUINT
G_MAXUINT16, G_MAXUINT16
G_MAXUINT32, G_MAXUINT32
G_MAXUINT64, G_MAXUINT64
G_MAXUINT8, G_MAXUINT8
G_MAXULONG, G_MAXULONG
G_MAXUSHORT, G_MAXUSHORT
g_memdup, g_memdup ()
g_memmove, g_memmove()
G_MEM_ALIGN, G_MEM_ALIGN
g_mem_chunk_alloc, g_mem_chunk_alloc ()
g_mem_chunk_alloc0, g_mem_chunk_alloc0 ()
g_mem_chunk_clean, g_mem_chunk_clean ()
g_mem_chunk_create, g_mem_chunk_create()
g_mem_chunk_destroy, g_mem_chunk_destroy ()
g_mem_chunk_free, g_mem_chunk_free ()
g_mem_chunk_info, g_mem_chunk_info ()
g_mem_chunk_new, g_mem_chunk_new ()
g_mem_chunk_print, g_mem_chunk_print ()
g_mem_chunk_reset, g_mem_chunk_reset ()
g_mem_gc_friendly, g_mem_gc_friendly
g_mem_is_system_malloc, g_mem_is_system_malloc ()
g_mem_profile, g_mem_profile ()
g_mem_set_vtable, g_mem_set_vtable ()
g_message, g_message()
G_MINDOUBLE, G_MINDOUBLE
G_MINFLOAT, G_MINFLOAT
G_MININT, G_MININT
G_MININT16, G_MININT16
G_MININT32, G_MININT32
G_MININT64, G_MININT64
G_MININT8, G_MININT8
G_MINLONG, G_MINLONG
G_MINSHORT, G_MINSHORT
g_mkdir, g_mkdir ()
g_mkdir_with_parents, g_mkdir_with_parents ()
g_mkstemp, g_mkstemp ()
g_module_build_path, g_module_build_path ()
g_module_close, g_module_close ()
g_module_error, g_module_error ()
G_MODULE_EXPORT, G_MODULE_EXPORT
G_MODULE_IMPORT, G_MODULE_IMPORT
g_module_make_resident, g_module_make_resident ()
g_module_name, g_module_name ()
g_module_open, g_module_open ()
G_MODULE_SUFFIX, G_MODULE_SUFFIX
g_module_supported, g_module_supported ()
g_module_symbol, g_module_symbol ()
g_mutex_free, g_mutex_free ()
g_mutex_lock, g_mutex_lock ()
g_mutex_new, g_mutex_new ()
g_mutex_trylock, g_mutex_trylock ()
g_mutex_unlock, g_mutex_unlock ()
g_new, g_new()
g_new0, g_new0()
g_newa, g_newa()
g_node_append, g_node_append()
g_node_append_data, g_node_append_data()
g_node_children_foreach, g_node_children_foreach ()
g_node_child_index, g_node_child_index ()
g_node_child_position, g_node_child_position ()
g_node_copy, g_node_copy ()
g_node_copy_deep, g_node_copy_deep ()
g_node_depth, g_node_depth ()
g_node_destroy, g_node_destroy ()
g_node_find, g_node_find ()
g_node_find_child, g_node_find_child ()
g_node_first_child, g_node_first_child()
g_node_first_sibling, g_node_first_sibling ()
g_node_get_root, g_node_get_root ()
g_node_insert, g_node_insert ()
g_node_insert_after, g_node_insert_after ()
g_node_insert_before, g_node_insert_before ()
g_node_insert_data, g_node_insert_data()
g_node_insert_data_before, g_node_insert_data_before()
g_node_is_ancestor, g_node_is_ancestor ()
G_NODE_IS_LEAF, G_NODE_IS_LEAF()
G_NODE_IS_ROOT, G_NODE_IS_ROOT()
g_node_last_child, g_node_last_child ()
g_node_last_sibling, g_node_last_sibling ()
g_node_max_height, g_node_max_height ()
g_node_new, g_node_new ()
g_node_next_sibling, g_node_next_sibling()
g_node_nth_child, g_node_nth_child ()
g_node_n_children, g_node_n_children ()
g_node_n_nodes, g_node_n_nodes ()
g_node_pop_allocator, g_node_pop_allocator ()
g_node_prepend, g_node_prepend ()
g_node_prepend_data, g_node_prepend_data()
g_node_prev_sibling, g_node_prev_sibling()
g_node_push_allocator, g_node_push_allocator ()
g_node_reverse_children, g_node_reverse_children ()
g_node_traverse, g_node_traverse ()
g_node_unlink, g_node_unlink ()
g_ntohl, g_ntohl()
g_ntohs, g_ntohs()
g_nullify_pointer, g_nullify_pointer ()
G_N_ELEMENTS, G_N_ELEMENTS()
g_once, g_once()
G_ONCE_INIT, G_ONCE_INIT
g_on_error_query, g_on_error_query ()
g_on_error_stack_trace, g_on_error_stack_trace ()
g_open, g_open ()
g_option_context_add_group, g_option_context_add_group ()
g_option_context_add_main_entries, g_option_context_add_main_entries ()
g_option_context_free, g_option_context_free ()
g_option_context_get_description, g_option_context_get_description ()
g_option_context_get_help_enabled, g_option_context_get_help_enabled ()
g_option_context_get_ignore_unknown_options, g_option_context_get_ignore_unknown_options ()
g_option_context_get_main_group, g_option_context_get_main_group ()
g_option_context_get_summary, g_option_context_get_summary ()
g_option_context_new, g_option_context_new ()
g_option_context_parse, g_option_context_parse ()
g_option_context_set_description, g_option_context_set_description ()
g_option_context_set_help_enabled, g_option_context_set_help_enabled ()
g_option_context_set_ignore_unknown_options, g_option_context_set_ignore_unknown_options ()
g_option_context_set_main_group, g_option_context_set_main_group ()
g_option_context_set_summary, g_option_context_set_summary ()
g_option_context_set_translate_func, g_option_context_set_translate_func ()
g_option_context_set_translation_domain, g_option_context_set_translation_domain ()
G_OPTION_ERROR, G_OPTION_ERROR
g_option_group_add_entries, g_option_group_add_entries ()
g_option_group_free, g_option_group_free ()
g_option_group_new, g_option_group_new ()
g_option_group_set_error_hook, g_option_group_set_error_hook ()
g_option_group_set_parse_hooks, g_option_group_set_parse_hooks ()
g_option_group_set_translate_func, g_option_group_set_translate_func ()
g_option_group_set_translation_domain, g_option_group_set_translation_domain ()
G_OPTION_REMAINING, G_OPTION_REMAINING
G_OS_BEOS, G_OS_BEOS
G_OS_UNIX, G_OS_UNIX
G_OS_WIN32, G_OS_WIN32
g_parse_debug_string, g_parse_debug_string ()
g_path_get_basename, g_path_get_basename ()
g_path_get_dirname, g_path_get_dirname ()
g_path_is_absolute, g_path_is_absolute ()
g_path_skip_root, g_path_skip_root ()
g_pattern_match, g_pattern_match ()
g_pattern_match_simple, g_pattern_match_simple ()
g_pattern_match_string, g_pattern_match_string ()
g_pattern_spec_equal, g_pattern_spec_equal ()
g_pattern_spec_free, g_pattern_spec_free ()
g_pattern_spec_new, g_pattern_spec_new ()
G_PDP_ENDIAN, G_PDP_ENDIAN
G_PI, G_PI
G_PI_2, G_PI_2
G_PI_4, G_PI_4
g_print, g_print ()
g_printerr, g_printerr ()
g_printf, g_printf ()
g_printf_string_upper_bound, g_printf_string_upper_bound ()
G_PRIORITY_DEFAULT, G_PRIORITY_DEFAULT
G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_DEFAULT_IDLE
G_PRIORITY_HIGH, G_PRIORITY_HIGH
G_PRIORITY_HIGH_IDLE, G_PRIORITY_HIGH_IDLE
G_PRIORITY_LOW, G_PRIORITY_LOW
g_private_get, g_private_get ()
g_private_new, g_private_new ()
g_private_set, g_private_set ()
g_propagate_error, g_propagate_error ()
g_ptr_array_add, g_ptr_array_add ()
g_ptr_array_foreach, g_ptr_array_foreach ()
g_ptr_array_free, g_ptr_array_free ()
g_ptr_array_index, g_ptr_array_index()
g_ptr_array_new, g_ptr_array_new ()
g_ptr_array_remove, g_ptr_array_remove ()
g_ptr_array_remove_fast, g_ptr_array_remove_fast ()
g_ptr_array_remove_index, g_ptr_array_remove_index ()
g_ptr_array_remove_index_fast, g_ptr_array_remove_index_fast ()
g_ptr_array_remove_range, g_ptr_array_remove_range ()
g_ptr_array_set_size, g_ptr_array_set_size ()
g_ptr_array_sized_new, g_ptr_array_sized_new ()
g_ptr_array_sort, g_ptr_array_sort ()
g_ptr_array_sort_with_data, g_ptr_array_sort_with_data ()
g_qsort_with_data, g_qsort_with_data ()
g_quark_from_static_string, g_quark_from_static_string ()
g_quark_from_string, g_quark_from_string ()
g_quark_to_string, g_quark_to_string ()
g_quark_try_string, g_quark_try_string ()
g_queue_copy, g_queue_copy ()
g_queue_delete_link, g_queue_delete_link ()
g_queue_find, g_queue_find ()
g_queue_find_custom, g_queue_find_custom ()
g_queue_foreach, g_queue_foreach ()
g_queue_free, g_queue_free ()
g_queue_get_length, g_queue_get_length ()
g_queue_index, g_queue_index ()
g_queue_insert_after, g_queue_insert_after ()
g_queue_insert_before, g_queue_insert_before ()
g_queue_insert_sorted, g_queue_insert_sorted ()
g_queue_is_empty, g_queue_is_empty ()
g_queue_link_index, g_queue_link_index ()
g_queue_new, g_queue_new ()
g_queue_peek_head, g_queue_peek_head ()
g_queue_peek_head_link, g_queue_peek_head_link ()
g_queue_peek_nth, g_queue_peek_nth ()
g_queue_peek_nth_link, g_queue_peek_nth_link ()
g_queue_peek_tail, g_queue_peek_tail ()
g_queue_peek_tail_link, g_queue_peek_tail_link ()
g_queue_pop_head, g_queue_pop_head ()
g_queue_pop_head_link, g_queue_pop_head_link ()
g_queue_pop_nth, g_queue_pop_nth ()
g_queue_pop_nth_link, g_queue_pop_nth_link ()
g_queue_pop_tail, g_queue_pop_tail ()
g_queue_pop_tail_link, g_queue_pop_tail_link ()
g_queue_push_head, g_queue_push_head ()
g_queue_push_head_link, g_queue_push_head_link ()
g_queue_push_nth, g_queue_push_nth ()
g_queue_push_nth_link, g_queue_push_nth_link ()
g_queue_push_tail, g_queue_push_tail ()
g_queue_push_tail_link, g_queue_push_tail_link ()
g_queue_remove, g_queue_remove ()
g_queue_remove_all, g_queue_remove_all ()
g_queue_reverse, g_queue_reverse ()
g_queue_sort, g_queue_sort ()
g_queue_unlink, g_queue_unlink ()
g_random_boolean, g_random_boolean()
g_random_double, g_random_double ()
g_random_double_range, g_random_double_range ()
g_random_int, g_random_int ()
g_random_int_range, g_random_int_range ()
g_random_set_seed, g_random_set_seed ()
g_rand_boolean, g_rand_boolean()
g_rand_copy, g_rand_copy ()
g_rand_double, g_rand_double ()
g_rand_double_range, g_rand_double_range ()
g_rand_free, g_rand_free ()
g_rand_int, g_rand_int ()
g_rand_int_range, g_rand_int_range ()
g_rand_new, g_rand_new ()
g_rand_new_with_seed, g_rand_new_with_seed ()
g_rand_new_with_seed_array, g_rand_new_with_seed_array ()
g_rand_set_seed, g_rand_set_seed ()
g_rand_set_seed_array, g_rand_set_seed_array ()
g_realloc, g_realloc ()
g_relation_count, g_relation_count ()
g_relation_delete, g_relation_delete ()
g_relation_destroy, g_relation_destroy ()
g_relation_exists, g_relation_exists ()
g_relation_index, g_relation_index ()
g_relation_insert, g_relation_insert ()
g_relation_new, g_relation_new ()
g_relation_print, g_relation_print ()
g_relation_select, g_relation_select ()
g_remove, g_remove ()
g_rename, g_rename ()
g_renew, g_renew()
g_return_if_fail, g_return_if_fail()
g_return_if_reached, g_return_if_reached()
g_return_val_if_fail, g_return_val_if_fail()
g_return_val_if_reached, g_return_val_if_reached()
g_rmdir, g_rmdir ()
g_scanner_add_symbol, g_scanner_add_symbol()
g_scanner_cur_line, g_scanner_cur_line ()
g_scanner_cur_position, g_scanner_cur_position ()
g_scanner_cur_token, g_scanner_cur_token ()
g_scanner_cur_value, g_scanner_cur_value ()
g_scanner_destroy, g_scanner_destroy ()
g_scanner_eof, g_scanner_eof ()
g_scanner_error, g_scanner_error ()
g_scanner_foreach_symbol, g_scanner_foreach_symbol()
g_scanner_freeze_symbol_table, g_scanner_freeze_symbol_table()
g_scanner_get_next_token, g_scanner_get_next_token ()
g_scanner_input_file, g_scanner_input_file ()
g_scanner_input_text, g_scanner_input_text ()
g_scanner_lookup_symbol, g_scanner_lookup_symbol ()
g_scanner_new, g_scanner_new ()
g_scanner_peek_next_token, g_scanner_peek_next_token ()
g_scanner_remove_symbol, g_scanner_remove_symbol()
g_scanner_scope_add_symbol, g_scanner_scope_add_symbol ()
g_scanner_scope_foreach_symbol, g_scanner_scope_foreach_symbol ()
g_scanner_scope_lookup_symbol, g_scanner_scope_lookup_symbol ()
g_scanner_scope_remove_symbol, g_scanner_scope_remove_symbol ()
g_scanner_set_scope, g_scanner_set_scope ()
g_scanner_sync_file_offset, g_scanner_sync_file_offset ()
g_scanner_thaw_symbol_table, g_scanner_thaw_symbol_table()
g_scanner_unexp_token, g_scanner_unexp_token ()
g_scanner_warn, g_scanner_warn ()
G_SEARCHPATH_SEPARATOR, G_SEARCHPATH_SEPARATOR
G_SEARCHPATH_SEPARATOR_S, G_SEARCHPATH_SEPARATOR_S
g_setenv, g_setenv ()
g_set_application_name, g_set_application_name ()
g_set_error, g_set_error ()
g_set_prgname, g_set_prgname ()
g_set_printerr_handler, g_set_printerr_handler ()
g_set_print_handler, g_set_print_handler ()
G_SHELL_ERROR, G_SHELL_ERROR
g_shell_parse_argv, g_shell_parse_argv ()
g_shell_quote, g_shell_quote ()
g_shell_unquote, g_shell_unquote ()
g_slice_alloc, g_slice_alloc ()
g_slice_alloc0, g_slice_alloc0 ()
g_slice_free, g_slice_free()
g_slice_free1, g_slice_free1 ()
g_slice_free_chain, g_slice_free_chain()
g_slice_free_chain_with_offset, g_slice_free_chain_with_offset ()
g_slice_new, g_slice_new()
g_slice_new0, g_slice_new0()
g_slist_alloc, g_slist_alloc ()
g_slist_append, g_slist_append ()
g_slist_concat, g_slist_concat ()
g_slist_copy, g_slist_copy ()
g_slist_delete_link, g_slist_delete_link ()
g_slist_find, g_slist_find ()
g_slist_find_custom, g_slist_find_custom ()
g_slist_foreach, g_slist_foreach ()
g_slist_free, g_slist_free ()
g_slist_free1, g_slist_free1
g_slist_free_1, g_slist_free_1 ()
g_slist_index, g_slist_index ()
g_slist_insert, g_slist_insert ()
g_slist_insert_before, g_slist_insert_before ()
g_slist_insert_sorted, g_slist_insert_sorted ()
g_slist_insert_sorted_with_data, g_slist_insert_sorted_with_data ()
g_slist_last, g_slist_last ()
g_slist_length, g_slist_length ()
g_slist_next, g_slist_next()
g_slist_nth, g_slist_nth ()
g_slist_nth_data, g_slist_nth_data ()
g_slist_pop_allocator, g_slist_pop_allocator ()
g_slist_position, g_slist_position ()
g_slist_prepend, g_slist_prepend ()
g_slist_push_allocator, g_slist_push_allocator ()
g_slist_remove, g_slist_remove ()
g_slist_remove_all, g_slist_remove_all ()
g_slist_remove_link, g_slist_remove_link ()
g_slist_reverse, g_slist_reverse ()
g_slist_sort, g_slist_sort ()
g_slist_sort_with_data, g_slist_sort_with_data ()
g_snprintf, g_snprintf ()
g_source_add_poll, g_source_add_poll ()
g_source_attach, g_source_attach ()
g_source_destroy, g_source_destroy ()
g_source_get_can_recurse, g_source_get_can_recurse ()
g_source_get_context, g_source_get_context ()
g_source_get_current_time, g_source_get_current_time ()
g_source_get_id, g_source_get_id ()
g_source_get_priority, g_source_get_priority ()
g_source_is_destroyed, g_source_is_destroyed ()
g_source_new, g_source_new ()
g_source_ref, g_source_ref ()
g_source_remove, g_source_remove ()
g_source_remove_by_funcs_user_data, g_source_remove_by_funcs_user_data ()
g_source_remove_by_user_data, g_source_remove_by_user_data ()
g_source_remove_poll, g_source_remove_poll ()
g_source_set_callback, g_source_set_callback ()
g_source_set_callback_indirect, g_source_set_callback_indirect ()
g_source_set_can_recurse, g_source_set_can_recurse ()
g_source_set_funcs, g_source_set_funcs ()
g_source_set_priority, g_source_set_priority ()
g_source_unref, g_source_unref ()
g_spaced_primes_closest, g_spaced_primes_closest ()
g_spawn_async, g_spawn_async ()
g_spawn_async_with_pipes, g_spawn_async_with_pipes ()
g_spawn_close_pid, g_spawn_close_pid ()
g_spawn_command_line_async, g_spawn_command_line_async ()
g_spawn_command_line_sync, g_spawn_command_line_sync ()
G_SPAWN_ERROR, G_SPAWN_ERROR
g_spawn_sync, g_spawn_sync ()
g_sprintf, g_sprintf ()
G_SQRT2, G_SQRT2
g_stat, g_stat ()
g_static_mutex_free, g_static_mutex_free ()
g_static_mutex_get_mutex, g_static_mutex_get_mutex ()
G_STATIC_MUTEX_INIT, G_STATIC_MUTEX_INIT
g_static_mutex_init, g_static_mutex_init ()
g_static_mutex_lock, g_static_mutex_lock ()
g_static_mutex_trylock, g_static_mutex_trylock ()
g_static_mutex_unlock, g_static_mutex_unlock ()
g_static_private_free, g_static_private_free ()
g_static_private_get, g_static_private_get ()
G_STATIC_PRIVATE_INIT, G_STATIC_PRIVATE_INIT
g_static_private_init, g_static_private_init ()
g_static_private_set, g_static_private_set ()
g_static_rec_mutex_free, g_static_rec_mutex_free ()
G_STATIC_REC_MUTEX_INIT, G_STATIC_REC_MUTEX_INIT
g_static_rec_mutex_init, g_static_rec_mutex_init ()
g_static_rec_mutex_lock, g_static_rec_mutex_lock ()
g_static_rec_mutex_lock_full, g_static_rec_mutex_lock_full ()
g_static_rec_mutex_trylock, g_static_rec_mutex_trylock ()
g_static_rec_mutex_unlock, g_static_rec_mutex_unlock ()
g_static_rec_mutex_unlock_full, g_static_rec_mutex_unlock_full ()
g_static_rw_lock_free, g_static_rw_lock_free ()
G_STATIC_RW_LOCK_INIT, G_STATIC_RW_LOCK_INIT
g_static_rw_lock_init, g_static_rw_lock_init ()
g_static_rw_lock_reader_lock, g_static_rw_lock_reader_lock ()
g_static_rw_lock_reader_trylock, g_static_rw_lock_reader_trylock ()
g_static_rw_lock_reader_unlock, g_static_rw_lock_reader_unlock ()
g_static_rw_lock_writer_lock, g_static_rw_lock_writer_lock ()
g_static_rw_lock_writer_trylock, g_static_rw_lock_writer_trylock ()
g_static_rw_lock_writer_unlock, g_static_rw_lock_writer_unlock ()
G_STMT_END, G_STMT_END
G_STMT_START, G_STMT_START
g_stpcpy, g_stpcpy ()
g_strcanon, g_strcanon ()
g_strcasecmp, g_strcasecmp ()
g_strchomp, g_strchomp ()
g_strchug, g_strchug ()
g_strcompress, g_strcompress ()
g_strconcat, g_strconcat ()
g_strdelimit, g_strdelimit ()
g_strdown, g_strdown ()
g_strdup, g_strdup ()
g_strdupv, g_strdupv ()
g_strdup_printf, g_strdup_printf ()
g_strdup_vprintf, g_strdup_vprintf ()
g_strerror, g_strerror ()
g_strescape, g_strescape ()
g_strfreev, g_strfreev ()
G_STRFUNC, G_STRFUNC
G_STRINGIFY, G_STRINGIFY()
g_string_append, g_string_append ()
g_string_append_c, g_string_append_c ()
g_string_append_len, g_string_append_len ()
g_string_append_printf, g_string_append_printf ()
g_string_append_unichar, g_string_append_unichar ()
g_string_ascii_down, g_string_ascii_down ()
g_string_ascii_up, g_string_ascii_up ()
g_string_assign, g_string_assign ()
g_string_chunk_free, g_string_chunk_free ()
g_string_chunk_insert, g_string_chunk_insert ()
g_string_chunk_insert_const, g_string_chunk_insert_const ()
g_string_chunk_insert_len, g_string_chunk_insert_len ()
g_string_chunk_new, g_string_chunk_new ()
g_string_down, g_string_down ()
g_string_equal, g_string_equal ()
g_string_erase, g_string_erase ()
g_string_free, g_string_free ()
g_string_hash, g_string_hash ()
g_string_insert, g_string_insert ()
g_string_insert_c, g_string_insert_c ()
g_string_insert_len, g_string_insert_len ()
g_string_insert_unichar, g_string_insert_unichar ()
g_string_new, g_string_new ()
g_string_new_len, g_string_new_len ()
g_string_prepend, g_string_prepend ()
g_string_prepend_c, g_string_prepend_c ()
g_string_prepend_len, g_string_prepend_len ()
g_string_prepend_unichar, g_string_prepend_unichar ()
g_string_printf, g_string_printf ()
g_string_set_size, g_string_set_size ()
g_string_sized_new, g_string_sized_new ()
g_string_sprintf, g_string_sprintf
g_string_sprintfa, g_string_sprintfa
g_string_truncate, g_string_truncate ()
g_string_up, g_string_up ()
g_strip_context, g_strip_context ()
g_strjoin, g_strjoin ()
g_strjoinv, g_strjoinv ()
g_strlcat, g_strlcat ()
g_strlcpy, g_strlcpy ()
G_STRLOC, G_STRLOC
g_strncasecmp, g_strncasecmp ()
g_strndup, g_strndup ()
g_strnfill, g_strnfill ()
g_strreverse, g_strreverse ()
g_strrstr, g_strrstr ()
g_strrstr_len, g_strrstr_len ()
g_strsignal, g_strsignal ()
g_strsplit, g_strsplit ()
g_strsplit_set, g_strsplit_set ()
g_strstrip, g_strstrip()
g_strstr_len, g_strstr_len ()
g_strtod, g_strtod ()
G_STRUCT_MEMBER, G_STRUCT_MEMBER()
G_STRUCT_MEMBER_P, G_STRUCT_MEMBER_P()
G_STRUCT_OFFSET, G_STRUCT_OFFSET()
g_strup, g_strup ()
g_strv_length, g_strv_length ()
G_STR_DELIMITERS, G_STR_DELIMITERS
g_str_equal, g_str_equal ()
g_str_hash, g_str_hash ()
g_str_has_prefix, g_str_has_prefix ()
g_str_has_suffix, g_str_has_suffix ()
G_THREADS_ENABLED, G_THREADS_ENABLED
G_THREADS_IMPL_NONE, G_THREADS_IMPL_NONE
G_THREADS_IMPL_POSIX, G_THREADS_IMPL_POSIX
g_thread_create, g_thread_create ()
g_thread_create_full, g_thread_create_full ()
G_THREAD_ERROR, G_THREAD_ERROR
g_thread_exit, g_thread_exit ()
g_thread_foreach, g_thread_foreach ()
g_thread_init, g_thread_init ()
g_thread_join, g_thread_join ()
g_thread_pool_free, g_thread_pool_free ()
g_thread_pool_get_max_idle_time, g_thread_pool_get_max_idle_time ()
g_thread_pool_get_max_threads, g_thread_pool_get_max_threads ()
g_thread_pool_get_max_unused_threads, g_thread_pool_get_max_unused_threads ()
g_thread_pool_get_num_threads, g_thread_pool_get_num_threads ()
g_thread_pool_get_num_unused_threads, g_thread_pool_get_num_unused_threads ()
g_thread_pool_new, g_thread_pool_new ()
g_thread_pool_push, g_thread_pool_push ()
g_thread_pool_set_max_idle_time, g_thread_pool_set_max_idle_time ()
g_thread_pool_set_max_threads, g_thread_pool_set_max_threads ()
g_thread_pool_set_max_unused_threads, g_thread_pool_set_max_unused_threads ()
g_thread_pool_set_sort_function, g_thread_pool_set_sort_function ()
g_thread_pool_stop_unused_threads, g_thread_pool_stop_unused_threads ()
g_thread_pool_unprocessed, g_thread_pool_unprocessed ()
g_thread_self, g_thread_self ()
g_thread_set_priority, g_thread_set_priority ()
g_thread_supported, g_thread_supported ()
g_thread_yield, g_thread_yield ()
g_timeout_add, g_timeout_add ()
g_timeout_add_full, g_timeout_add_full ()
g_timeout_add_seconds, g_timeout_add_seconds ()
g_timeout_source_new, g_timeout_source_new ()
g_timeout_source_new_seconds, g_timeout_source_new_seconds ()
g_timer_continue, g_timer_continue ()
g_timer_destroy, g_timer_destroy ()
g_timer_elapsed, g_timer_elapsed ()
g_timer_new, g_timer_new ()
g_timer_reset, g_timer_reset ()
g_timer_start, g_timer_start ()
g_timer_stop, g_timer_stop ()
g_time_val_add, g_time_val_add ()
g_time_val_from_iso8601, g_time_val_from_iso8601 ()
g_time_val_to_iso8601, g_time_val_to_iso8601 ()
g_trap_free_size, Traps and traces
g_trap_malloc_size, Traps and traces
g_trap_realloc_size, Traps and traces
g_trash_stack_height, g_trash_stack_height ()
g_trash_stack_peek, g_trash_stack_peek ()
g_trash_stack_pop, g_trash_stack_pop ()
g_trash_stack_push, g_trash_stack_push ()
g_tree_destroy, g_tree_destroy ()
g_tree_foreach, g_tree_foreach ()
g_tree_height, g_tree_height ()
g_tree_insert, g_tree_insert ()
g_tree_lookup, g_tree_lookup ()
g_tree_lookup_extended, g_tree_lookup_extended ()
g_tree_new, g_tree_new ()
g_tree_new_full, g_tree_new_full ()
g_tree_new_with_data, g_tree_new_with_data ()
g_tree_nnodes, g_tree_nnodes ()
g_tree_remove, g_tree_remove ()
g_tree_replace, g_tree_replace ()
g_tree_search, g_tree_search ()
g_tree_steal, g_tree_steal ()
g_tree_traverse, g_tree_traverse ()
G_TRYLOCK, G_TRYLOCK()
g_try_malloc, g_try_malloc ()
g_try_malloc0, g_try_malloc0 ()
g_try_new, g_try_new()
g_try_new0, g_try_new0()
g_try_realloc, g_try_realloc ()
g_try_renew, g_try_renew()
g_tuples_destroy, g_tuples_destroy ()
g_tuples_index, g_tuples_index ()
g_ucs4_to_utf16, g_ucs4_to_utf16 ()
g_ucs4_to_utf8, g_ucs4_to_utf8 ()
g_unichar_break_type, g_unichar_break_type ()
g_unichar_digit_value, g_unichar_digit_value ()
g_unichar_get_mirror_char, g_unichar_get_mirror_char ()
g_unichar_get_script, g_unichar_get_script ()
g_unichar_isalnum, g_unichar_isalnum ()
g_unichar_isalpha, g_unichar_isalpha ()
g_unichar_iscntrl, g_unichar_iscntrl ()
g_unichar_isdefined, g_unichar_isdefined ()
g_unichar_isdigit, g_unichar_isdigit ()
g_unichar_isgraph, g_unichar_isgraph ()
g_unichar_islower, g_unichar_islower ()
g_unichar_isprint, g_unichar_isprint ()
g_unichar_ispunct, g_unichar_ispunct ()
g_unichar_isspace, g_unichar_isspace ()
g_unichar_istitle, g_unichar_istitle ()
g_unichar_isupper, g_unichar_isupper ()
g_unichar_iswide, g_unichar_iswide ()
g_unichar_iswide_cjk, g_unichar_iswide_cjk ()
g_unichar_isxdigit, g_unichar_isxdigit ()
g_unichar_tolower, g_unichar_tolower ()
g_unichar_totitle, g_unichar_totitle ()
g_unichar_toupper, g_unichar_toupper ()
g_unichar_to_utf8, g_unichar_to_utf8 ()
g_unichar_type, g_unichar_type ()
g_unichar_validate, g_unichar_validate ()
g_unichar_xdigit_value, g_unichar_xdigit_value ()
g_unicode_canonical_decomposition, g_unicode_canonical_decomposition ()
g_unicode_canonical_ordering, g_unicode_canonical_ordering ()
G_UNLIKELY, G_UNLIKELY()
g_unlink, g_unlink ()
G_UNLOCK, G_UNLOCK()
g_unsetenv, g_unsetenv ()
g_uri_list_extract_uris, g_uri_list_extract_uris ()
G_USEC_PER_SEC, G_USEC_PER_SEC
g_usleep, g_usleep ()
g_utf16_to_ucs4, g_utf16_to_ucs4 ()
g_utf16_to_utf8, g_utf16_to_utf8 ()
g_utf8_casefold, g_utf8_casefold ()
g_utf8_collate, g_utf8_collate ()
g_utf8_collate_key, g_utf8_collate_key ()
g_utf8_collate_key_for_filename, g_utf8_collate_key_for_filename ()
g_utf8_find_next_char, g_utf8_find_next_char ()
g_utf8_find_prev_char, g_utf8_find_prev_char ()
g_utf8_get_char, g_utf8_get_char ()
g_utf8_get_char_validated, g_utf8_get_char_validated ()
g_utf8_next_char, g_utf8_next_char()
g_utf8_normalize, g_utf8_normalize ()
g_utf8_offset_to_pointer, g_utf8_offset_to_pointer ()
g_utf8_pointer_to_offset, g_utf8_pointer_to_offset ()
g_utf8_prev_char, g_utf8_prev_char ()
g_utf8_strchr, g_utf8_strchr ()
g_utf8_strdown, g_utf8_strdown ()
g_utf8_strlen, g_utf8_strlen ()
g_utf8_strncpy, g_utf8_strncpy ()
g_utf8_strrchr, g_utf8_strrchr ()
g_utf8_strreverse, g_utf8_strreverse ()
g_utf8_strup, g_utf8_strup ()
g_utf8_to_ucs4, g_utf8_to_ucs4 ()
g_utf8_to_ucs4_fast, g_utf8_to_ucs4_fast ()
g_utf8_to_utf16, g_utf8_to_utf16 ()
g_utf8_validate, g_utf8_validate ()
g_vasprintf, g_vasprintf ()
G_VA_COPY, G_VA_COPY()
g_vfprintf, g_vfprintf ()
g_vprintf, g_vprintf ()
g_vsnprintf, g_vsnprintf ()
g_vsprintf, g_vsprintf ()
g_warning, g_warning()
G_WIN32_DLLMAIN_FOR_DLL_NAME, G_WIN32_DLLMAIN_FOR_DLL_NAME()
g_win32_error_message, g_win32_error_message ()
g_win32_getlocale, g_win32_getlocale ()
g_win32_get_package_installation_directory, g_win32_get_package_installation_directory ()
g_win32_get_package_installation_subdirectory, g_win32_get_package_installation_subdirectory ()
g_win32_get_windows_version, g_win32_get_windows_version ()
G_WIN32_HAVE_WIDECHAR_API, G_WIN32_HAVE_WIDECHAR_API()
G_WIN32_IS_NT_BASED, G_WIN32_IS_NT_BASED()
g_win32_locale_filename_from_utf8, g_win32_locale_filename_from_utf8 ()

M

MAX, MAX()
MAXPATHLEN, MAXPATHLEN
MIN, MIN()

N

NULL, NULL
N_, N_()

P

pipe, pipe()

Q

Q_, Q_()

T

TRUE, TRUE

Index of deprecated symbols

Symbols

G

GAllocator, GAllocator
GMemChunk, GMemChunk
g_allocator_free, g_allocator_free ()
g_allocator_new, g_allocator_new ()
G_ALLOC_AND_FREE, G_ALLOC_AND_FREE
G_ALLOC_ONLY, G_ALLOC_ONLY
g_async_queue_ref_unlocked, g_async_queue_ref_unlocked ()
g_async_queue_unref_and_unlock, g_async_queue_unref_and_unlock ()
g_basename, g_basename ()
g_blow_chunks, g_blow_chunks ()
g_cache_value_foreach, g_cache_value_foreach ()
g_chunk_free, g_chunk_free()
g_chunk_new, g_chunk_new()
g_chunk_new0, g_chunk_new0()
g_date_set_time, g_date_set_time ()
g_dirname, g_dirname
g_hash_table_freeze, g_hash_table_freeze()
g_hash_table_thaw, g_hash_table_thaw()
G_HAVE_GINT64, G_HAVE_GINT64
g_io_channel_close, g_io_channel_close ()
g_io_channel_read, g_io_channel_read ()
g_io_channel_seek, g_io_channel_seek ()
g_io_channel_write, g_io_channel_write ()
g_list_pop_allocator, g_list_pop_allocator ()
g_list_push_allocator, g_list_push_allocator ()
g_main_destroy, g_main_destroy()
g_main_is_running, g_main_is_running()
g_main_iteration, g_main_iteration()
g_main_new, g_main_new()
g_main_pending, g_main_pending()
g_main_quit, g_main_quit()
g_main_run, g_main_run()
g_main_set_poll_func, g_main_set_poll_func()
g_mem_chunk_alloc, g_mem_chunk_alloc ()
g_mem_chunk_alloc0, g_mem_chunk_alloc0 ()
g_mem_chunk_clean, g_mem_chunk_clean ()
g_mem_chunk_create, g_mem_chunk_create()
g_mem_chunk_destroy, g_mem_chunk_destroy ()
g_mem_chunk_free, g_mem_chunk_free ()
g_mem_chunk_info, g_mem_chunk_info ()
g_mem_chunk_new, g_mem_chunk_new ()
g_mem_chunk_print, g_mem_chunk_print ()
g_mem_chunk_reset, g_mem_chunk_reset ()
g_node_pop_allocator, g_node_pop_allocator ()
g_node_push_allocator, g_node_push_allocator ()
g_scanner_add_symbol, g_scanner_add_symbol()
g_scanner_foreach_symbol, g_scanner_foreach_symbol()
g_scanner_freeze_symbol_table, g_scanner_freeze_symbol_table()
g_scanner_remove_symbol, g_scanner_remove_symbol()
g_scanner_thaw_symbol_table, g_scanner_thaw_symbol_table()
g_slist_pop_allocator, g_slist_pop_allocator ()
g_slist_push_allocator, g_slist_push_allocator ()
g_strcasecmp, g_strcasecmp ()
g_strdown, g_strdown ()
g_string_down, g_string_down ()
g_string_sprintf, g_string_sprintf
g_string_sprintfa, g_string_sprintfa
g_string_up, g_string_up ()
g_strncasecmp, g_strncasecmp ()
g_strup, g_strup ()
g_tree_traverse, g_tree_traverse ()

Index of new symbols in 2.2

Symbols

G

g_ascii_strtoull, g_ascii_strtoull ()
g_fprintf, g_fprintf ()
g_get_application_name, g_get_application_name ()
G_GNUC_DEPRECATED, G_GNUC_DEPRECATED
G_LIKELY, G_LIKELY()
g_markup_parse_context_get_element, g_markup_parse_context_get_element ()
g_printf, g_printf ()
g_sprintf, g_sprintf ()
g_str_has_prefix, g_str_has_prefix ()
g_str_has_suffix, g_str_has_suffix ()
G_UNLIKELY, G_UNLIKELY()
g_utf8_strreverse, g_utf8_strreverse ()
g_vfprintf, g_vfprintf ()
g_vprintf, g_vprintf ()
g_vsprintf, g_vsprintf ()

Index of new symbols in 2.4

Symbols

_, _()

G

GCopyFunc, GCopyFunc ()
GOnce, GOnce
GOnceStatus, enum GOnceStatus
g_array_remove_range, g_array_remove_range ()
g_atomic_int_add, g_atomic_int_add ()
g_atomic_int_compare_and_exchange, g_atomic_int_compare_and_exchange ()
g_atomic_int_dec_and_test, g_atomic_int_dec_and_test ()
g_atomic_int_exchange_and_add, g_atomic_int_exchange_and_add ()
g_atomic_int_get, g_atomic_int_get ()
g_atomic_int_inc, g_atomic_int_inc ()
g_atomic_pointer_compare_and_exchange, g_atomic_pointer_compare_and_exchange ()
g_atomic_pointer_get, g_atomic_pointer_get ()
g_byte_array_remove_range, g_byte_array_remove_range ()
g_child_watch_add, g_child_watch_add ()
g_child_watch_add_full, g_child_watch_add_full ()
g_child_watch_source_new, g_child_watch_source_new ()
g_completion_complete_utf8, g_completion_complete_utf8 ()
g_file_read_link, g_file_read_link ()
G_GINT16_MODIFIER, G_GINT16_MODIFIER
G_GINT32_MODIFIER, G_GINT32_MODIFIER
G_GINT64_MODIFIER, G_GINT64_MODIFIER
g_hash_table_find, g_hash_table_find ()
g_markup_printf_escaped, g_markup_printf_escaped ()
g_markup_vprintf_escaped, g_markup_vprintf_escaped ()
G_MAXINT16, G_MAXINT16
G_MAXINT32, G_MAXINT32
G_MAXINT8, G_MAXINT8
G_MAXSIZE, G_MAXSIZE
G_MAXUINT16, G_MAXUINT16
G_MAXUINT32, G_MAXUINT32
G_MAXUINT8, G_MAXUINT8
G_MININT16, G_MININT16
G_MININT32, G_MININT32
G_MININT8, G_MININT8
g_node_copy_deep, g_node_copy_deep ()
g_once, g_once()
G_ONCE_INIT, G_ONCE_INIT
g_ptr_array_foreach, g_ptr_array_foreach ()
g_ptr_array_remove_range, g_ptr_array_remove_range ()
g_queue_copy, g_queue_copy ()
g_queue_delete_link, g_queue_delete_link ()
g_queue_find, g_queue_find ()
g_queue_find_custom, g_queue_find_custom ()
g_queue_foreach, g_queue_foreach ()
g_queue_get_length, g_queue_get_length ()
g_queue_index, g_queue_index ()
g_queue_insert_after, g_queue_insert_after ()
g_queue_insert_before, g_queue_insert_before ()
g_queue_insert_sorted, g_queue_insert_sorted ()
g_queue_link_index, g_queue_link_index ()
g_queue_peek_head_link, g_queue_peek_head_link ()
g_queue_peek_nth, g_queue_peek_nth ()
g_queue_peek_nth_link, g_queue_peek_nth_link ()
g_queue_peek_tail_link, g_queue_peek_tail_link ()
g_queue_pop_nth, g_queue_pop_nth ()
g_queue_pop_nth_link, g_queue_pop_nth_link ()
g_queue_push_nth, g_queue_push_nth ()
g_queue_push_nth_link, g_queue_push_nth_link ()
g_queue_remove, g_queue_remove ()
g_queue_remove_all, g_queue_remove_all ()
g_queue_reverse, g_queue_reverse ()
g_queue_sort, g_queue_sort ()
g_queue_unlink, g_queue_unlink ()
g_rand_copy, g_rand_copy ()
g_rand_new_with_seed_array, g_rand_new_with_seed_array ()
g_rand_set_seed_array, g_rand_set_seed_array ()
g_setenv, g_setenv ()
G_STRFUNC, G_STRFUNC
g_string_chunk_insert_len, g_string_chunk_insert_len ()
g_strip_context, g_strip_context ()
g_strsplit_set, g_strsplit_set ()
g_timer_continue, g_timer_continue ()
g_unichar_get_mirror_char, g_unichar_get_mirror_char ()
g_unsetenv, g_unsetenv ()
g_vasprintf, g_vasprintf ()

N

N_, N_()

Q

Q_, Q_()

Index of new symbols in 2.6

Symbols

G

glib_check_version, glib_check_version ()
g_date_get_iso8601_week_of_year, g_date_get_iso8601_week_of_year ()
g_debug, g_debug()
g_filename_display_basename, g_filename_display_basename ()
g_filename_display_name, g_filename_display_name ()
g_fopen, g_fopen ()
g_freopen, g_freopen ()
g_get_filename_charsets, g_get_filename_charsets ()
g_get_language_names, g_get_language_names ()
g_get_system_config_dirs, g_get_system_config_dirs ()
g_get_system_data_dirs, g_get_system_data_dirs ()
g_get_user_cache_dir, g_get_user_cache_dir ()
g_get_user_config_dir, g_get_user_config_dir ()
g_get_user_data_dir, g_get_user_data_dir ()
G_GNUC_MALLOC, G_GNUC_MALLOC
G_GSIZE_FORMAT, G_GSIZE_FORMAT
G_GSIZE_MODIFIER, G_GSIZE_MODIFIER
G_GSSIZE_FORMAT, G_GSSIZE_FORMAT
G_IS_DIR_SEPARATOR, G_IS_DIR_SEPARATOR()
g_key_file_free, g_key_file_free ()
g_key_file_get_boolean, g_key_file_get_boolean ()
g_key_file_get_boolean_list, g_key_file_get_boolean_list ()
g_key_file_get_comment, g_key_file_get_comment ()
g_key_file_get_groups, g_key_file_get_groups ()
g_key_file_get_integer, g_key_file_get_integer ()
g_key_file_get_integer_list, g_key_file_get_integer_list ()
g_key_file_get_keys, g_key_file_get_keys ()
g_key_file_get_locale_string, g_key_file_get_locale_string ()
g_key_file_get_locale_string_list, g_key_file_get_locale_string_list ()
g_key_file_get_start_group, g_key_file_get_start_group ()
g_key_file_get_string, g_key_file_get_string ()
g_key_file_get_string_list, g_key_file_get_string_list ()
g_key_file_get_value, g_key_file_get_value ()
g_key_file_has_group, g_key_file_has_group ()
g_key_file_has_key, g_key_file_has_key ()
g_key_file_load_from_data, g_key_file_load_from_data ()
g_key_file_load_from_data_dirs, g_key_file_load_from_data_dirs ()
g_key_file_load_from_file, g_key_file_load_from_file ()
g_key_file_new, g_key_file_new ()
g_key_file_remove_comment, g_key_file_remove_comment ()
g_key_file_remove_group, g_key_file_remove_group ()
g_key_file_remove_key, g_key_file_remove_key ()
g_key_file_set_boolean, g_key_file_set_boolean ()
g_key_file_set_boolean_list, g_key_file_set_boolean_list ()
g_key_file_set_comment, g_key_file_set_comment ()
g_key_file_set_integer, g_key_file_set_integer ()
g_key_file_set_integer_list, g_key_file_set_integer_list ()
g_key_file_set_list_separator, g_key_file_set_list_separator ()
g_key_file_set_locale_string, g_key_file_set_locale_string ()
g_key_file_set_locale_string_list, g_key_file_set_locale_string_list ()
g_key_file_set_string, g_key_file_set_string ()
g_key_file_set_string_list, g_key_file_set_string_list ()
g_key_file_set_value, g_key_file_set_value ()
g_key_file_to_data, g_key_file_to_data ()
g_log_set_default_handler, g_log_set_default_handler ()
g_lstat, g_lstat ()
g_mkdir, g_mkdir ()
g_open, g_open ()
g_option_context_add_group, g_option_context_add_group ()
g_option_context_add_main_entries, g_option_context_add_main_entries ()
g_option_context_free, g_option_context_free ()
g_option_context_get_help_enabled, g_option_context_get_help_enabled ()
g_option_context_get_ignore_unknown_options, g_option_context_get_ignore_unknown_options ()
g_option_context_get_main_group, g_option_context_get_main_group ()
g_option_context_new, g_option_context_new ()
g_option_context_parse, g_option_context_parse ()
g_option_context_set_help_enabled, g_option_context_set_help_enabled ()
g_option_context_set_ignore_unknown_options, g_option_context_set_ignore_unknown_options ()
g_option_context_set_main_group, g_option_context_set_main_group ()
g_option_group_add_entries, g_option_group_add_entries ()
g_option_group_free, g_option_group_free ()
g_option_group_new, g_option_group_new ()
g_option_group_set_error_hook, g_option_group_set_error_hook ()
g_option_group_set_parse_hooks, g_option_group_set_parse_hooks ()
g_option_group_set_translate_func, g_option_group_set_translate_func ()
g_option_group_set_translation_domain, g_option_group_set_translation_domain ()
G_OPTION_REMAINING, G_OPTION_REMAINING
g_remove, g_remove ()
g_rename, g_rename ()
g_rmdir, g_rmdir ()
g_stat, g_stat ()
g_strv_length, g_strv_length ()
g_unlink, g_unlink ()
g_uri_list_extract_uris, g_uri_list_extract_uris ()
g_win32_get_windows_version, g_win32_get_windows_version ()
G_WIN32_HAVE_WIDECHAR_API, G_WIN32_HAVE_WIDECHAR_API()
G_WIN32_IS_NT_BASED, G_WIN32_IS_NT_BASED()

Index of new symbols in 2.8

Symbols

G

g_access, g_access ()
g_build_filenamev, g_build_filenamev ()
g_build_pathv, g_build_pathv ()
g_chdir, g_chdir ()
g_chmod, g_chmod ()
g_creat, g_creat ()
g_datalist_get_flags, g_datalist_get_flags ()
g_datalist_set_flags, g_datalist_set_flags ()
g_datalist_unset_flags, g_datalist_unset_flags ()
g_file_set_contents, g_file_set_contents ()
g_get_host_name, g_get_host_name ()
g_listenv, g_listenv ()
g_mapped_file_free, g_mapped_file_free ()
g_mapped_file_get_contents, g_mapped_file_get_contents ()
g_mapped_file_get_length, g_mapped_file_get_length ()
g_mapped_file_new, g_mapped_file_new ()
g_mkdir_with_parents, g_mkdir_with_parents ()
g_try_malloc0, g_try_malloc0 ()
g_try_new, g_try_new()
g_try_new0, g_try_new0()
g_try_renew, g_try_renew()
g_utf8_collate_key_for_filename, g_utf8_collate_key_for_filename ()
g_win32_locale_filename_from_utf8, g_win32_locale_filename_from_utf8 ()

Index of new symbols in 2.10

Symbols

G

g_async_queue_push_sorted, g_async_queue_push_sorted ()
g_async_queue_push_sorted_unlocked, g_async_queue_push_sorted_unlocked ()
g_async_queue_sort, g_async_queue_sort ()
g_async_queue_sort_unlocked, g_async_queue_sort_unlocked ()
g_atomic_int_set, g_atomic_int_set ()
g_atomic_pointer_set, g_atomic_pointer_set ()
g_date_set_time_t, g_date_set_time_t ()
g_date_set_time_val, g_date_set_time_val ()
G_GNUC_WARN_UNUSED_RESULT, G_GNUC_WARN_UNUSED_RESULT
G_GUINT64_CONSTANT, G_GUINT64_CONSTANT()
g_hash_table_ref, g_hash_table_ref ()
g_hash_table_unref, g_hash_table_unref ()
g_intern_static_string, g_intern_static_string ()
g_intern_string, g_intern_string ()
g_main_context_is_owner, g_main_context_is_owner ()
g_slice_alloc, g_slice_alloc ()
g_slice_alloc0, g_slice_alloc0 ()
g_slice_free, g_slice_free()
g_slice_free1, g_slice_free1 ()
g_slice_free_chain, g_slice_free_chain()
g_slice_free_chain_with_offset, g_slice_free_chain_with_offset ()
g_slice_new, g_slice_new()
g_slice_new0, g_slice_new0()
g_slist_free1, g_slist_free1
g_thread_foreach, g_thread_foreach ()
g_thread_pool_get_max_idle_time, g_thread_pool_get_max_idle_time ()
g_thread_pool_set_max_idle_time, g_thread_pool_set_max_idle_time ()
g_thread_pool_set_sort_function, g_thread_pool_set_sort_function ()

Index of new symbols in 2.12

Symbols

G

g_ascii_strtoll, g_ascii_strtoll ()
g_base64_decode, g_base64_decode ()
g_base64_decode_step, g_base64_decode_step ()
g_base64_encode, g_base64_encode ()
g_base64_encode_close, g_base64_encode_close ()
g_base64_encode_step, g_base64_encode_step ()
g_bookmark_file_add_application, g_bookmark_file_add_application ()
g_bookmark_file_add_group, g_bookmark_file_add_group ()
g_bookmark_file_free, g_bookmark_file_free ()
g_bookmark_file_get_added, g_bookmark_file_get_added ()
g_bookmark_file_get_applications, g_bookmark_file_get_applications ()
g_bookmark_file_get_app_info, g_bookmark_file_get_app_info ()
g_bookmark_file_get_description, g_bookmark_file_get_description ()
g_bookmark_file_get_groups, g_bookmark_file_get_groups ()
g_bookmark_file_get_icon, g_bookmark_file_get_icon ()
g_bookmark_file_get_is_private, g_bookmark_file_get_is_private ()
g_bookmark_file_get_mime_type, g_bookmark_file_get_mime_type ()
g_bookmark_file_get_modified, g_bookmark_file_get_modified ()
g_bookmark_file_get_size, g_bookmark_file_get_size ()
g_bookmark_file_get_title, g_bookmark_file_get_title ()
g_bookmark_file_get_uris, g_bookmark_file_get_uris ()
g_bookmark_file_get_visited, g_bookmark_file_get_visited ()
g_bookmark_file_has_application, g_bookmark_file_has_application ()
g_bookmark_file_has_group, g_bookmark_file_has_group ()
g_bookmark_file_has_item, g_bookmark_file_has_item ()
g_bookmark_file_load_from_data, g_bookmark_file_load_from_data ()
g_bookmark_file_load_from_data_dirs, g_bookmark_file_load_from_data_dirs ()
g_bookmark_file_load_from_file, g_bookmark_file_load_from_file ()
g_bookmark_file_move_item, g_bookmark_file_move_item ()
g_bookmark_file_new, g_bookmark_file_new ()
g_bookmark_file_remove_application, g_bookmark_file_remove_application ()
g_bookmark_file_remove_group, g_bookmark_file_remove_group ()
g_bookmark_file_remove_item, g_bookmark_file_remove_item ()
g_bookmark_file_set_added, g_bookmark_file_set_added ()
g_bookmark_file_set_app_info, g_bookmark_file_set_app_info ()
g_bookmark_file_set_description, g_bookmark_file_set_description ()
g_bookmark_file_set_groups, g_bookmark_file_set_groups ()
g_bookmark_file_set_icon, g_bookmark_file_set_icon ()
g_bookmark_file_set_is_private, g_bookmark_file_set_is_private ()
g_bookmark_file_set_mime_type, g_bookmark_file_set_mime_type ()
g_bookmark_file_set_modified, g_bookmark_file_set_modified ()
g_bookmark_file_set_title, g_bookmark_file_set_title ()
g_bookmark_file_set_visited, g_bookmark_file_set_visited ()
g_bookmark_file_to_data, g_bookmark_file_to_data ()
g_bookmark_file_to_file, g_bookmark_file_to_file ()
g_hash_table_remove_all, g_hash_table_remove_all ()
g_hash_table_steal_all, g_hash_table_steal_all ()
g_key_file_get_double, g_key_file_get_double ()
g_key_file_get_double_list, g_key_file_get_double_list ()
g_key_file_set_double, g_key_file_set_double ()
g_key_file_set_double_list, g_key_file_set_double_list ()
g_main_current_source, g_main_current_source ()
g_option_context_get_description, g_option_context_get_description ()
g_option_context_get_summary, g_option_context_get_summary ()
g_option_context_set_description, g_option_context_set_description ()
g_option_context_set_summary, g_option_context_set_summary ()
g_option_context_set_translate_func, g_option_context_set_translate_func ()
g_option_context_set_translation_domain, g_option_context_set_translation_domain ()
g_source_is_destroyed, g_source_is_destroyed ()
g_source_set_funcs, g_source_set_funcs ()
g_time_val_from_iso8601, g_time_val_from_iso8601 ()
g_time_val_to_iso8601, g_time_val_to_iso8601 ()
g_unichar_iswide_cjk, g_unichar_iswide_cjk ()

GLib Tools

glib-gettextize - gettext internationalization utility