GLiblog_structured

使用结构数据记录一条消息。

消息将通过应用程序使用 g_log_set_writer_func() 设置的日志写入器进行传递。如果消息具有致命性（即其日志级别为 G_LOG_LEVEL_ERROR），程序会在该函数的末尾调用 G_BREAKPOINT() 来中止。如果日志写入器返回 G_LOG_WRITER_UNHANDLED（失败），则不会尝试其他任何备用写入器。有关链接写入器的信息，请参阅 GLogWriterFunc 的文档。

结构数据以键-值对的形式提供，其中键是 UTF-8 字符串，值是任意指针，通常指向 UTF-8 字符串，但这并不是一个要求。要传递二进制（非空终止）结构数据，请使用 g_log_structured_array()。结构数据的键应遵循 systemd 日志字段 规范。建议根据设置它们代码对自定义键进行命名空间划分。例如，GLib 中的所有自定义键都具有 GLIB_ 前缀。

请注意，预计为 UTF-8 字符串的键（尤其是 "MESSAGE" 和 "GLIB_DOMAIN"）在 GLib 版本 2.74.1 之前必须作为空终止 UTF-8 字符串传递，因为默认日志处理程序并不会考虑 GLogField 的长度。从 GLib 2.74.1 开始，已修复这个问题，可以不使用空终止 UTF-8 字符串传递其正确长度，但 "GLIB_DOMAIN" 除外，它在 GLib 2.82.3 中才得到修复。

log_domain 会转换为 GLIB_DOMAIN 字段。log_level 会转换为 PRIORITY 字段。格式字符串的占位符会替换为提供的值，并转换为 MESSAGE 字段。

你可能通常希望传递到该函数的其他字段

• MESSAGE_ID
• CODE_FILE
• CODE_LINE
• CODE_FUNC
• ERRNO

请注意，如果在包含 glib.h 之前定义了符号 G_LOG_USE_STRUCTURED，则日志记录宏（例如 G_DEBUG_HERE()、g_message()、g_warning()、g_critical()、g_error() 等）会自动设置 CODE_FILE、CODE_LINE 和 CODE_FUNC。

例如

g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
                  "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
                  "MY_APPLICATION_CUSTOM_FIELD", "some debug string",
                  "MESSAGE", "This is a debug message about pointer %p and integer %u.",
                  some_pointer, some_integer);

请注意，每个 MESSAGE_ID 必须 唯一且随机生成。如果添加 MESSAGE_ID，请考虑随软件一起发布 消息目录。

要将用户数据指针传递到特定于此日志记录调用的日志记录器函数，必须使用 g_log_structured_array() 并将指针作为字段传递，其中 GLogField.length 设为零，否则将其解释为字符串。

例如

const GLogField fields[] = {
  { "MESSAGE", "This is a debug message.", -1 },
  { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 },
  { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 },
  { "MY_APPLICATION_STATE", state_object, 0 },
};
g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields));

另请注意，即使未指定其他结构化字段，也必须在格式字符串之前始终存在一个 MESSAGE 键。MESSAGE 格式对必须是键值对的最后一个，而 MESSAGE 是唯一支持 printf() 格式化的字段。

stdout 和 stderr 的默认 writer 函数会在消息后自动附加一个换行符，因此不应手动添加一个到格式字符串中。

自 2.50 起可用

此函数不可直接用于语言绑定。