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 : адрес указателя в памяти.

			Справочное описание GLib
Начало \| Описание