# 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

- [`fuchsia.boot.ReadOnlyLog`](https://fuchsia.dev/reference/fidl/fuchsia.boot#ReadOnlyLog)

- [`zx_debuglog_create()`](https://fuchsia.dev/reference/syscalls/debuglog_create)

- [`zx_debuglog_write()`](https://fuchsia.dev/reference/syscalls/debuglog_write)