docs/reference/syscalls/debuglog_read.md

<!--
Copyright 2023 The Fuchsia Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.

DO NOT EDIT. Generated from FIDL library zx by zither, a Fuchsia platform tool.

See //docs/reference/syscalls/README.md#documentation-generation for
regeneration instructions.
-->

# zx_debuglog_read

## Summary

Read a single log record from the kernel debuglog.

## Declaration

```c
#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:

```c
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.

## See also

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

 - [`zx_debuglog_create()`]
 - [`zx_debuglog_write()`]

[`zx_debuglog_create()`]: debuglog_create.md
[`zx_debuglog_write()`]: debuglog_write.md