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 類型的單一記錄會寫入緩衝區。記錄的長度 (以位元組為單位) 會透過 syscall 的傳回值提供。

傳回記錄的格式如下：

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;

欄位的定義如下：

欄位 說明
sequence 這筆記錄的序號。每筆記錄的序列：數字比上述記錄的序列大 1。序列的開頭為 0。序列中會出現缺口，捨棄了記錄檔記錄。
datalen data 欄位中資料位元組數。
嚴重程度 這個記錄訊息的嚴重性。標準嚴重性等級是在標頭 zircon/syscalls/log.h 中定義。
flags 與這則訊息相關的其他旗標。標記會在標頭 zircon/syscalls/log.h 中定義。
時間戳記 說明第一次寫入記錄的時間戳記。
pid 寫入此記錄檔記錄的程序 ID，如果是由核心產生記錄，則為 ZX_KOID_INVALID。
tid 寫入此記錄的執行緒的 oid，如果是由核心產生記錄，則為 ZX_KOID_INVALID。
資料 記錄訊息，包含 datalen 位元組。記錄訊息可能包含嵌入 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 處理常式不是偵錯記錄檔控制代碼。

另請參閱