zx_debuglog_read

总结

从内核调试日志中读取单个日志记录。

声明

#include <zircon/syscalls.h>

zx_status_t zx_debuglog_read(zx_handle_t handle,
                             uint32_t options,
                             void* buffer,
                             size_t buffer_size);

说明

zx_debuglog_read() 会尝试将内核调试日志中的单个记录读取到大小为 buffer_size 字节的给定缓冲区。

options 必须设置为 0。

如果成功，系统会将 zx_log_record_t 类型的一条记录写入缓冲区。记录的长度（以字节为单位）在系统调用的返回值中指定。

返回的记录采用以下格式：

typedef struct zx_log_record {
  uint64_t sequence;
  uint32_t unused;
  uint16_t datalen;
  uint8_t severity;
  uint8_t flags;
  zx_time_t timestamp;
  uint64_t pid;
  uint64_t tid;
  char data[];
} zx_log_record_t;

这些字段的定义如下：

字段 说明
序列 此记录的序列号。每条记录的序列编号为 1，其值比前面的记录数大 1。该序列从 0 开始。序列中的缺口表示已丢弃的日志记录。
datalen data 字段中数据的字节数。
严重级别 此日志消息的严重性。标准严重级别在标头 zircon/syscalls/log.h 中定义。
标志 与此消息相关联的额外标志。标志在标头 zircon/syscalls/log.h 中定义。
时间戳 用于说明首次写入此记录的时间的时间戳。
pid 写入此日志记录的进程的 Koid，如果记录是由内核生成的，则为 ZX_KOID_INVALID。
tid 写入此日志记录的线程的 Koid，如果记录由内核生成，则为 ZX_KOID_INVALID。
数据 日志消息，由 datalen 字节组成。日志消息可能包含嵌入的 NUL 字符，并且不能保证以 NUL 终止。

如果 buffer_size 小于日志记录的大小，则记录的前 buffer_size 个字节会被写入缓冲区，其余部分会被舍弃。调用方应确保其输入缓冲区至少为 ZX_LOG_RECORD_MAX 字节，以避免日志记录被截断。

权限

handle 必须为 ZX_OBJ_TYPE_LOG 类型，且具有 ZX_RIGHT_READ。

返回值

zx_debuglog_read() 会在成功时返回一个非负值，表示写入缓冲区的字节数。如果失败，则返回负数错误值。

错误

ZX_ERR_ACCESS_DENIED 句柄没有 ZX_RIGHT_READ。

ZX_ERR_BAD_HANDLE 句柄不是有效的句柄。

ZX_ERR_INVALID_ARGS 为 options 指定的值无效，或者 buffer 是无效的指针。

ZX_ERR_SHOULD_WAIT 调试日志中没有要读取的记录。

ZX_ERR_WRONG_TYPE 句柄不是调试日志句柄。

另请参阅