zx_debuglog_read

Summary

Read a single log record from the kernel debuglog.

Declaration

#include <zircon/syscalls.h>

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

Description

zx_debuglog_read() attempts to read a single record from the kernel debug log into the given buffer of size buffer_size bytes.

options must be set to 0.

On success, a single record of type zx_log_record_t is written into buffer. The length of the record in bytes is given in the syscall's return value.

The returned record will have the following format:

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

The fields are defined as follows:

Field Description
sequence The sequence number of this record. Each record's sequence : number is 1 greater than the preceding records's. The sequence starts with 0. Gaps in the sequence indidate dropped log records.
datalen Number of bytes of data in the data field.
severity Severity of this log message. Standard severity levels are defined in the header zircon/syscalls/log.h.
flags Extra flags associated with this message. Flags are defined in the header zircon/syscalls/log.h.
timestamp Timestamp describing when this record was first written.
pid Koid of the process that wrote this log record, or ZX_KOID_INVALID if the record was generated by the kernel.
tid Koid of the thread that wrote this log record, or ZX_KOID_INVALID if the record was generated by the kernel.
data The log message, consisting of datalen bytes. The log message may contain embedded NUL characters, and is not guaranteed to be NUL-terminated.

If buffer_size is smaller than the size of the log record, the first buffer_size bytes of the record will be written to the buffer, and the rest discarded. Callers should ensure that their input buffer is at least ZX_LOG_RECORD_MAX bytes to avoid log records from being truncated.

Rights

handle must be of type ZX_OBJ_TYPE_LOG and have ZX_RIGHT_READ.

Return value

zx_debuglog_read() returns a non-negative value on success, indicating the number of bytes written into buffer. On failure, a negative error value is returned.

Errors

ZX_ERR_ACCESS_DENIED handle does not have ZX_RIGHT_READ.

ZX_ERR_BAD_HANDLE handle is not a valid handle.

ZX_ERR_INVALID_ARGS An invalid value to options was given, or buffer was an invalid pointer.

ZX_ERR_SHOULD_WAIT The debuglog contained no records to read.

ZX_ERR_WRONG_TYPE handle is not a debuglog handle.

See also