Message Logging

Регистрация сообщений

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

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