zlog日志库（笔记） —— zlog接口（API）
引入头文件
zlog所有接口都是线程安全的，使用时只需要包含头文件
#include "zlog.h"
初始化和清理
总览
ini zlog_init(const char *confpath);
int zlog_reload(const char *confpath);
void zlog_fini(void);
接口描述
zlog_init: 从配置文件confpath读取配置信息到内存。如果confpath为NULL，会寻找环境变量ZLOG_CONF_PATH的值作为配置文件名；如果环境变量 ZLOG_CONF_PATH为空，所有日志以内置格式写到标准输出（stdout）上。每个进程只有第一次调用zlog_init()有效，后面多余调用都会失败并且不做任何事情。
zlog_reload(): 从confpath重载配置，并根据该配置文件重新计算内部的分类规则匹配、重建每个线程的缓存，并设置原有的用户自定义输出函数。可以做配置文件发生改变后调用该函数。该函数调用次数不限。如果confpath为NULL，会重载上一次zlog_init()或zlog_reload()时使用的配置文件；如果zlog_reload()失败，上一次的配置依然有效。所以zlog_reload()具有原子性。
zlog_fini(): 清理所有zlog API申请的内存，关闭它们打开的文件。使用次数不限。
返回值
如果成功，zlog_init()和zlog_reload()返回0；失败，zlog_init()和zlog_reload()返回-1。详细错误，会被写到由环境变量ZLOG_PROFILE_ERROR指定的错误日志里去。
分类（Category）操作
总览
typedef struct zlog_category_st zlog_category_t;
zlog_category_t *zlog_get_category(const char *name);
接口描述
zlog_get_category() 从zlog的全局分类表里找到分类，用于以后输出日志；如果没有的话，就新建一个。然后，函数会遍历所有的规则，寻找和cname匹配的规则并绑定。
配置文件规则中的分类名匹配cname的规律描述如下：
1）*匹配任意cname；
2）以下划线（""）结尾的分类名同时匹配本级分类和下级分类，例如"aa"匹配aa, aa_, aa_bb, aa_bb_cc这几个cname；
3）不以下划线（"_"）结尾的分类名精确匹配cname，例如"aa_bb"匹配"aa_bb"这个cname；
4）"!"匹配目前还没有规则的cname；
每个zlog_category_t*对应的规则，在zlog_relaod()时会被自动重新计算。不用担心内存释放，zlog_fini()最后会清理一切。
返回值
如果调用成功，返回zlog_category_t的指针；如果失败，返回NULL。详细错误，会被写到由环境变量ZLOG_PROFILE_ERROR指定的错误日志里去。
写日志函数及宏
总览
void zlog(zlog_category_t * category,
const char *file, size_t filelen,
const char *func, size_t funclen,
long line, int level,
const char *format, ...) ZLOG_CHECK_PRINTF(8,9);
void vzlog(zlog_category_t * category,
const char *file, size_t filelen,
const char *func, size_t funclen,
long line, int level,
const char *format, va_list args);
void hzlog(zlog_category_t * category,
const char *file, size_t filelen,
const char *func, size_t funclen,
long line, int level,
const void *buf, size_t buflen);
接口描述
3个函数是实际写日志的函数，输入的数据对应于配置文件中的%m。category来源于调用zlog_get_category()。
zlog()和vzlog()根据format输出，就像printf(3)和vprintf(3)。vzlog()相当于zlog()，不过它用一个va_list参数args，来表示可变参数列表，而不是"..."。vzlog()内部使用了va_copy宏，args内容在vzlog()后保持不变，可参考stdarg(3)。
hzlog()有些区别，它产生下面这样的输出，长度buf_len的内存buf以16进制的形式表示出来。
hex_buf_len=[5365]
0 1 2 3 4 5 6 7 8 9 A B C D E F 0123456789ABCDEF
0000000001 23 21 20 2f 62 69 6e 2f 62 61 73 68 0a 0a 23 20 #! /bin/bash..#
0000000002 74 65 73 74 5f 68 65 78 20 2d 20 74 65 6d 70 6f test_hex - tempo
0000000003 72 61 72 79 20 77 72 61 70 70 65 72 20 73 63 72 rary wrapper scr
参数file和line填写为__FILE__和__LINE__宏，用于标识日志是在哪个文件和哪一行发生的。参数func填写为__func__ (C99)或__FUNCTION__ (GCC)，如果编译器不支持的话，就填写为"
level是一个整数，应该在下面几个里面取值：
typedef enum {
ZLOG_LEVEL_DEBUG = 20,
ZLOG_LEVEL_INFO = 40,
ZLOG_LEVEL_NOTICE = 60,
ZLOG_LEVEL_WARN = 80,
ZLOG_LEVEL_ERROR = 100,
ZLOG_LEVEL_FATAL = 120,
} zlog_level;
每个函数都有便于使用的宏，如：
#define zlog_fatal(cat, ...) \
zlog(cat, __FILE__, sizeof(__FILE__)-1, __func__, sizeof(__func__)-1, __LINE__, \
ZLOG_LEVEL_FATAL, __VA_ARGS__)
由于编译器下，可变参数的使用有所区别，因此这里不展示所有编译器下的宏实现。只列出所有宏列表：
/* 便于用户调用的写日志接口(宏函数) */
/* zlog macros */
zlog_fatal(cat, format, ...)
zlog_error(cat, format, ...)
zlog_warn(cat, format, ...)
zlog_notice(cat, format, ...)
zlog_info(cat, format, ...)
zlog_debug(cat, format, ...)
/* vzlog macros */
vzlog_fatal(cat, format, args)
vzlog_error(cat, format, args)
vzlog_warn(cat, format, args)
vzlog_notice(cat, format, args)
vzlog_info(cat, format, args)
vzlog_debug(cat, format, args)
/* hzlog macros */
hzlog_fatal(cat, buf, buf_len)
hzlog_error(cat, buf, buf_len)
hzlog_warn(cat, buf, buf_len)
hzlog_notice(cat, buf, buf_len)
hzlog_info(cat, buf, buf_len)
hzlog_debug(cat, buf, buf_len)
返回值
无返回值。如果有错误发生，详细错误会被写在由环境变量ZLOG_PROFILE_ERROR指定的错误日志里面。
MDC操作
总览
int zlog_put_mdc(const char *key, const char *value);
char *zlog_get_mdc(const char *key);
void zlog_remove_mdc(const char *key);
void zlog_clean_mdc(void);
接口描述
MDC(Mapped Diagnostic Context) 是一个线程拥有的键-值表，和分类没什么关系。
key-value是字符串，长度不能超过MAXLEN_PATH(1024)；如果超过，则会被截断。
记住这个表是和线程绑定到，每个线程都有自己的表，所以在一个线程内的调用不会影响其他线程，也就是说对其操作是线程安全的。
返回值
zlog_put_mdc()成功返回0，失败返回-1。
zlog_get_mdc成功返回value的指针；失败返回没有相应的key，则返回NULL。
如果有错误发生，详细错误会被写在由环境变量ZLOG_PROFILE_ERROR指定的错误日志里面。
dzlog接口
总览
int dzlog_init(const char *confpath, const char *cname);
int dzlog_set_category(const char *cname);
void dzlog(const char *file, size_t filelen,
const char *func, size_t funclen,
long line, int level,
const char *format, ...);
void vdzlog(const char *file, size_t filelen,
const char *func, size_t funclen,
long line, int level,
const char *format, va_list args);
void hdzlog(const char *file, size_t filelen,
const char *func, size_t funclen,
long line, int level,
const void *buf, size_t buflen);
接口描述
dzlog是忽略分类（zlog_category_t）的一组简单zlog接口。它采用内置的一个默认分类，该分类置于锁的保护之下。这些接口也是线程安全的。忽略了分类，意味着用户不需要操心创建、存储、传输zlog_category_t类型的变量。当然，也可以在用dzlog接口的同时，用一般的zlog接口函数。
dzlog_init()和zlog_init()一样做初始化，就是多需要一个默认分类名cname的参数。zlog_reload()、zlog_fini()可以和以前一样使用，用来刷新配置，或者清理。
dzlog_set_category()用来改变默认分类用的。上一个分类会被替换成新的。同样不用担心内存释放问题，zlog_fini()最后会做清理。
dzlog相关便捷宏，也定义中zlog.h里面。
/* 采用内置的默认分类 */
dzlog_fatal(format, ...)
dzlog_error(format, ...)
dzlog_warn(format, ...)
dzlog_notice(format, ...)
dzlog_info(format, ...)
dezlog_debug(format, ...)
vdzlog_fatal(format, args)
vdzlog_error(format, args)
vdzlog_warn(format, args)
vdzlog_notice(format, args)
vdzlog_info(format, args)
vdzlog_debug(format, args)
hdzlog_fatal(buf, buf_len)
hdzlog_error(buf, buf_len)
hdzlog_warn(buf, buf_len)
hdzlog_noticebuf, buf_len)
hdzlog_info(buf, buf_len)
hdzlog_debug(buf, buf_len)
返回值
成功调用，dzlog_init()和dzlog_set_category()返回0；失败时，dzlog_init()和dzlog_set_category()返回-1。详细错误会被写在ZLOG_PROFILE_ERROR指定错误日志里面。
用户自定义输出
总览
typedef struct zlog_msg_s {
char *buf;
size_t len;
char *path;
} zlog_msg_t;
typedef int (*zlog_record_fn)(zlog_msg_t *msg);
int zlog_set_record(const char *name, zlog_record_fn record);
接口描述
zlog允许用户自定义输出函数。输出函数需要绑定到某条特殊规则（rules）上。例：
[rules]
*.* $name, "record path %c %d"; simple
zlog_set_record()做绑定动作。规则中，输出段有$name，会被用来做用户自定义输出。输出函数record。该函数需要为zlog_record_fn格式。
zlog_msg_t结构的各成员描述如下：
- path 来自规则的逗号后的字符串，该字符串会被动态解析，输出当前path，就像动态文件路径一样；
- buf和len是zlog格式化后的日志信息和长度；
所有zlog_set_record()做的绑定，在zlog_reload()使用后继续有效。
返回值
成功调用时，返回0；失败返回-1。详细错误会被写在ZLOG_PROFILE_ERROR指定错误日志里面。
调试和诊断
总览
void zlog_profile(void);
接口描述
环境变量ZLOG_PROFILE_ERROR指定zlog本身的错误日志。
环境变量ZLOG_PROFILE_DEBUG指定zlog本身的调试日志。
zlog_profile()打印所有内存中的配置信息到ZLOG_PROFILE_ERROR。可以把这个和配置文件比较，看看有没有问题。
