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_time_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.