zx_debuglog_read

NAME

Read a single log record from the kernel debuglog.

SYNOPSIS

  1. #include <zircon/syscalls.h>
  3. zx_status_t zx_debuglog_read(zx_handle_t handle,
  4.                              uint32_t options,
  5.                              void* buffer,
  6.                              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:

  1. typedef struct zx_log_record {
  2.   uint32_t rollout;
  3.   uint16_t datalen;
  4.   uint8_t severity;
  5.   uint8_t flags;
  6.   zx_time_t timestamp;
  7.   uint64_t pid;
  8.   uint64_t tid;
  9.   char data[];
  10. } zx_log_record_t;

The fields are defined as follows:

Field Description
rollout Number of bytes of log messages (including headers) dropped

: : since the last call to zx_debuglog_read on this object. The : : : kernel will drop the oldest log messages when its internal : : : buffer becomes full. : | 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