### Retrieve PCAPNG File Info

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Use `light_pcang_get_file_info` to get metadata like version, comment, OS, hardware, and application descriptions from an open PCAPNG file. The returned pointer is managed by the `light_pcapng` handle.

```c
#include "light_pcapng_ext.h"
#include <stdio.h>

int main(void) {
    light_pcapng pcap = light_pcapng_open("capture.pcapng", "rb");
    if (pcap == NULL) return 1;

    light_pcapng_file_info *info = light_pcang_get_file_info(pcap);
    if (info) {
        printf("PCAPNG version : %d.%d\n", info->major_version, info->minor_version);
        printf("Comment        : %s\n", info->comment      ? info->comment      : "(none)");
        printf("OS             : %s\n", info->os_desc      ? info->os_desc      : "(none)");
        printf("Hardware       : %s\n", info->hardware_desc ? info->hardware_desc : "(none)");
        printf("Application    : %s\n", info->app_desc     ? info->app_desc     : "(none)");
    }

    light_pcapng_close(pcap);
    return 0;
}
```

--------------------------------

### Open PCAPNG Files with I/O Abstraction

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Shows how to open PCAPNG files using the unified I/O backend, which automatically handles plain, ZLIB, or Zstandard compressed files based on their extensions.

```c
#include "light_io.h"
#include <stdio.h>

int main(void) {
    // Plain PCAPNG
    light_file f1 = light_io_open("capture.pcapng",     "rb");
    // ZLIB / gzip compressed
    light_file f2 = light_io_open("capture.pcapng.gz",  "rb");
    // Zstandard compressed
    light_file f3 = light_io_open("capture.pcapng.zst", "rb");

    if (!f1 || !f2 || !f3) {
        fprintf(stderr, "Failed to open one or more files\n");
    }

    light_io_close(f1);
    light_io_close(f2);
    light_io_close(f3);
    return 0;
}
```

--------------------------------

### Build LightPcapNg with CMake

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Configure and compile the library as a static or shared library, with optional compression support.

```cmake
cmake -B build -S .
cmake --build build
```

```cmake
cmake -B build -S \
  -DBUILD_SHARED_LIBS=ON \
  -DLIGHT_USE_ZSTD=ON \
  -DLIGHT_USE_ZLIB=ON
cmake --build build
```

```cmake
cmake --install build
```

--------------------------------

### Create In-Memory PCAPNG I/O Handle

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Demonstrates wrapping a memory buffer as a `light_file` for parsing PCAPNG data without filesystem access. The caller must manage the buffer's lifecycle.

```c
#include "light_io_mem.h"
#include "light_io.h"
#include "light_pcapng.h"
#include <stdlib.h>
#include <stdio.h>
#include <sys/stat.h>

int main(void) {
    // Load file into memory
    const char *path = "capture.pcapng";
    struct stat st;
    stat(path, &st);
    uint8_t *buf = malloc(st.st_size);

    FILE *fp = fopen(path, "rb");
    fread(buf, 1, st.st_size, fp);
    fclose(fp);

    // Parse from the in-memory buffer
    light_file mem = light_io_mem_create(buf, st.st_size);

    light_block block = NULL;
    bool swap = false;
    light_read_block(mem, &block, &swap);
    while (block != NULL) {
        printf("Block type: 0x%08X  length: %u\n",
               block->type, block->total_length);
        light_read_block(mem, &block, &swap);
    }

    light_io_close(mem);
    free(buf);
    return 0;
}
```

--------------------------------

### Manipulate PCAPNG Block Options

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Demonstrates how to create, add, and find options within PCAPNG blocks. Use `light_add_option` with `copy=true` to attach data, and `light_find_option` to retrieve it.

```c
#include "light_pcapng.h"
#include "light_io.h"
#include <string.h>

int main(void) {
    light_file fd   = light_io_open("capture.pcapng", "rb");
    light_file out  = light_io_open("annotated.pcapng", "wb");
    light_block block = NULL;
    bool swap = false;

    light_read_block(fd, &block, &swap);
    while (block != NULL) {
        if (block->type == LIGHT_ENHANCED_PACKET_BLOCK) {
            // Attach a human-readable comment option to every EPB
            const char *note = "reviewed";
            light_option comment = light_create_option(
                LIGHT_OPTION_COMMENT,
                (uint16_t)strlen(note),
                note
            );
            // section=NULL is acceptable when the SHB is already written
            light_add_option(NULL, block, comment, /*copy=*/true);
            light_free_option(comment);

            // Retrieve the comment we just added
            light_option found = light_find_option(block, LIGHT_OPTION_COMMENT);
            if (found)
                printf("Comment: %.*s\n", found->length, (char *)found->data);
        }
        light_write_block(out, block);
        light_read_block(fd, &block, &swap);
    }

    light_io_close(fd);
    light_io_close(out);
    return 0;
}
```

--------------------------------

### Open PCAPNG file for reading or writing

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Opens a PCAPNG file by path and returns an opaque light_pcapng handle. Pass "rb" for reading and "wb" for writing. Returns NULL on failure. The file extension determines the compression backend used (.gz → zlib, .zst → zstd).

```c
#include "light_pcapng_ext.h"
#include <stdio.h>

int main(void) {
    // Open for reading (supports plain, .gz, .zst)
    light_pcapng reader = light_pcapng_open("capture.pcapng", "rb");
    if (reader == NULL) {
        fprintf(stderr, "Failed to open capture.pcapng\n");
        return 1;
    }

    // Open for writing
    light_pcapng writer = light_pcapng_open("output.pcapng", "wb");
    if (writer == NULL) {
        fprintf(stderr, "Failed to open output.pcapng for writing\n");
        light_pcapng_close(reader);
        return 1;
    }

    light_pcapng_close(reader);
    light_pcapng_close(writer);
    return 0;
}
```

--------------------------------

### I/O Abstraction Layer: light_io_open

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Opens a file using a unified I/O backend that automatically detects and dispatches to plain-file, ZSTD, or ZLIB handlers based on the file extension. The returned `light_file` handle is used by subsequent block and option APIs.

```APIDOC
## `light_io_open` — Open a file through the unified I/O backend

`light_io_open` detects the file extension and automatically dispatches to the plain-file, ZSTD, or ZLIB backend. The returned `light_file` handle is used by all block and option APIs.

### Example Usage
```c
#include "light_io.h"
#include <stdio.h>

int main(void) {
    // Plain PCAPNG
    light_file f1 = light_io_open("capture.pcapng",     "rb");
    // ZLIB / gzip compressed
    light_file f2 = light_io_open("capture.pcapng.gz",  "rb");
    // Zstandard compressed
    light_file f3 = light_io_open("capture.pcapng.zst", "rb");

    if (!f1 || !f2 || !f3) {
        fprintf(stderr, "Failed to open one or more files\n");
    }

    light_io_close(f1);
    light_io_close(f2);
    light_io_close(f3);
    return 0;
}
```
```

--------------------------------

### I/O Abstraction Layer: light_io_mem_create

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Creates an in-memory I/O handle by wrapping an existing memory buffer as a `light_file`. This allows PCAPNG parsing directly from memory without file system access. The caller retains ownership of the buffer and must free it after closing the handle.

```APIDOC
## `light_io_mem_create` — Create an in-memory I/O handle

Wraps an existing memory buffer as a `light_file`, enabling PCAPNG parsing without touching the filesystem. The caller retains ownership of the buffer and must free it after closing the handle.

### Example Usage
```c
#include "light_io_mem.h"
#include "light_io.h"
#include "light_pcapng.h"
#include <stdlib.h>
#include <stdio.h>
#include <sys/stat.h>

int main(void) {
    // Load file into memory
    const char *path = "capture.pcapng";
    struct stat st;
    stat(path, &st);
    uint8_t *buf = malloc(st.st_size);

    FILE *fp = fopen(path, "rb");
    fread(buf, 1, st.st_size, fp);
    fclose(fp);

    // Parse from the in-memory buffer
    light_file mem = light_io_mem_create(buf, st.st_size);

    light_block block = NULL;
    bool swap = false;
    light_read_block(mem, &block, &swap);
    while (block != NULL) {
        printf("Block type: 0x%08X  length: %u\n",
               block->type, block->total_length);
        light_read_block(mem, &block, &swap);
    }

    light_io_close(mem);
    free(buf);
    return 0;
}
```
```

--------------------------------

### light_pcapng_open

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Opens a PCAPNG file for reading or writing. The file extension determines the compression backend used (.gz for zlib, .zst for zstd). Returns NULL on failure.

```APIDOC
## light_pcapng_open

### Description
Opens a PCAPNG file by path and returns an opaque `light_pcapng` handle. Pass `"rb"` for reading and `"wb"` for writing. Returns `NULL` on failure. The file extension determines the compression backend used (`.gz` → zlib, `.zst` → zstd).

### Function Signature
```c
light_pcapng light_pcapng_open(const char *path, const char *mode)
```

### Parameters
#### Path Parameters
- **path** (const char *) - The path to the PCAPNG file.
- **mode** (const char *) - The mode to open the file in (`"rb"` for read, `"wb"` for write).

### Return Value
- **light_pcapng** - An opaque handle to the opened PCAPNG file, or `NULL` on failure.

### Request Example
```c
#include "light_pcapng_ext.h"
#include <stdio.h>

int main(void) {
    // Open for reading (supports plain, .gz, .zst)
    light_pcapng reader = light_pcapng_open("capture.pcapng", "rb");
    if (reader == NULL) {
        fprintf(stderr, "Failed to open capture.pcapng\n");
        return 1;
    }

    // Open for writing
    light_pcapng writer = light_pcapng_open("output.pcapng", "wb");
    if (writer == NULL) {
        fprintf(stderr, "Failed to open output.pcapng for writing\n");
        light_pcapng_close(reader);
        return 1;
    }

    light_pcapng_close(reader);
    light_pcapng_close(writer);
    return 0;
}
```
```

--------------------------------

### Create PCAPNG writer from FILE handle

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Creates a light_pcapng writer on top of an already-open light_file handle, optionally embedding file-level metadata in the Section Header Block.

```c
#include "light_pcapng_ext.h"
#include "light_io.h"
#include <stdio.h>

int main(void) {
    light_pcapng_file_info *info = light_create_file_info(
        "Linux 5.15",            // os_desc
        "x86_64",                // hardware_desc
        "my-capture-tool 1.0",   // app_desc
        "Test capture session"   // comment
    );

    light_file fd = light_io_open("annotated.pcapng", "wb");
    light_pcapng pcap = light_pcapng_create(fd, "wb", info);

    // ... write packets ...

    light_pcapng_close(pcap);        // also closes underlying fd
    light_free_file_info(info);
    return 0;
}
```

--------------------------------

### Block Options: light_create_option, light_add_option, light_find_option

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Functions for managing options within PCAPNG blocks. `light_create_option` allocates an option node, `light_add_option` attaches it to a block, and `light_find_option` searches for an option by its code.

```APIDOC
## `light_create_option` / `light_add_option` / `light_find_option` — Block options

`light_create_option` allocates an option (TLV) node. `light_add_option` attaches it to a block (optionally copying data), adjusting `total_length`. `light_find_option` traverses the option chain by code.

### Example Usage
```c
#include "light_pcapng.h"
#include "light_io.h"
#include <string.h>

int main(void) {
    light_file fd   = light_io_open("capture.pcapng", "rb");
    light_file out  = light_io_open("annotated.pcapng", "wb");
    light_block block = NULL;
    bool swap = false;

    light_read_block(fd, &block, &swap);
    while (block != NULL) {
        if (block->type == LIGHT_ENHANCED_PACKET_BLOCK) {
            // Attach a human-readable comment option to every EPB
            const char *note = "reviewed";
            light_option comment = light_create_option(
                LIGHT_OPTION_COMMENT,
                (uint16_t)strlen(note),
                note
            );
            // section=NULL is acceptable when the SHB is already written
            light_add_option(NULL, block, comment, /*copy=*/true);
            light_free_option(comment);

            // Retrieve the comment we just added
            light_option found = light_find_option(block, LIGHT_OPTION_COMMENT);
            if (found)
                printf("Comment: %.*s\n", found->length, (char *)found->data);
        }
        light_write_block(out, block);
        light_read_block(fd, &block, &swap);
    }

    light_io_close(fd);
    light_io_close(out);
    return 0;
}
```
```

--------------------------------

### light_pcang_get_file_info

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Retrieves metadata from an open PCAPNG file, including version, comment, OS, hardware, and application descriptions.

```APIDOC
## light_pcang_get_file_info — Retrieve metadata from an open PCAPNG file

### Description
Returns a pointer to a `light_pcapng_file_info` struct containing the PCAPNG version, comment, OS, hardware, and application description recorded in the Section Header Block. The returned pointer is owned by the `light_pcapng` handle and must not be freed independently.

### Parameters
- **pcap** (`light_pcapng`) - Required - Handle to an open PCAPNG file.

### Returns
- (`light_pcapng_file_info*`) - A pointer to a struct containing file information, or NULL on error.

### Example
```c
#include "light_pcapng_ext.h"
#include <stdio.h>

int main(void) {
    light_pcapng pcap = light_pcapng_open("capture.pcapng", "rb");
    if (pcap == NULL) return 1;

    light_pcapng_file_info *info = light_pcang_get_file_info(pcap);
    if (info) {
        printf("PCAPNG version : %d.%d\n", info->major_version, info->minor_version);
        printf("Comment        : %s\n", info->comment      ? info->comment      : "(none)");
        printf("OS             : %s\n", info->os_desc      ? info->os_desc      : "(none)");
        printf("Hardware       : %s\n", info->hardware_desc ? info->hardware_desc : "(none)");
        printf("Application    : %s\n", info->app_desc     ? info->app_desc     : "(none)");
    }

    light_pcapng_close(pcap);
    return 0;
}
```
```

--------------------------------

### Create and Destroy PCAPNG Blocks with light_create_block and light_free_block

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Allocates a new `light_block` of a given type and copies data into it. `light_free_block` releases the block and its options. Used for manual block construction.

```c
#include "light_pcapng.h"
#include "light_io.h"
#include <stdint.h>

int main(void) {
    // Build a minimal Section Header Block body manually
    uint32_t shb_body[] = {
        0x1A2B3C4D,   // byte-order magic
        0x00010000,   // major=1, minor=0
        0xFFFFFFFF,   // section_length high (unspecified)
        0xFFFFFFFF,   // section_length low
    };

    light_block shb = light_create_block(
        LIGHT_SECTION_HEADER_BLOCK,
        shb_body,
        sizeof(shb_body)
    );

    light_file out = light_io_open("manual.pcapng", "wb");
    light_write_block(out, shb);
    light_io_close(out);

    light_free_block(shb);   // must free when not handed back to light_read_block
    return 0;
}

```

--------------------------------

### light_pcapng_create

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Creates a PCAPNG writer on top of an existing `light_file` handle, optionally embedding file-level metadata in the Section Header Block.

```APIDOC
## light_pcapng_create

### Description
Creates a `light_pcapng` writer on top of an already-open `light_file` handle, optionally embedding file-level metadata (OS, hardware, application description, comment) in the Section Header Block.

### Function Signature
```c
light_pcapng light_pcapng_create(light_file fd, const char *mode, light_pcapng_file_info *info)
```

### Parameters
#### Path Parameters
- **fd** (light_file) - An already-open `light_file` handle.
- **mode** (const char *) - The mode to open the file in (`"wb"` for write).
- **info** (light_pcapng_file_info *) - Optional file information to embed in the SHB. Can be `NULL`.

### Return Value
- **light_pcapng** - An opaque handle to the created PCAPNG writer.

### Request Example
```c
#include "light_pcapng_ext.h"
#include "light_io.h"
#include <stdio.h>

int main(void) {
    light_pcapng_file_info *info = light_create_file_info(
        "Linux 5.15",            // os_desc
        "x86_64",                // hardware_desc
        "my-capture-tool 1.0",   // app_desc
        "Test capture session"   // comment
    );

    light_file fd = light_io_open("annotated.pcapng", "wb");
    light_pcapng pcap = light_pcapng_create(fd, "wb", info);

    // ... write packets ...

    light_pcapng_close(pcap);        // also closes underlying fd
    light_free_file_info(info);
    return 0;
}
```
```

--------------------------------

### Read and Write Raw PCAPNG Blocks with light_read_block and light_write_block

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Provides the foundation for generic block-level processing, such as file merging. `light_read_block` reads the next block, and `light_write_block` serializes a block to a file.

```c
#include "light_pcapng.h"
#include "light_io.h"
#include <stdio.h>

// Merge multiple PCAPNG files into one using the block API
int main(int argc, const char **argv) {
    // argv[1] = output, argv[2..] = inputs
    light_file out = light_io_open(argv[1], "wb");

    for (int i = 2; i < argc; i++) {
        light_file in = light_io_open(argv[i], "rb");
        if (in == NULL) { fprintf(stderr, "Cannot open %s\n", argv[i]); continue; }

        light_block block = NULL;
        bool swap = false;

        light_read_block(in, &block, &swap);
        while (block != NULL) {
            light_write_block(out, block);           // copy block verbatim
            light_read_block(in, &block, &swap);     // frees previous block
        }
        light_io_close(in);
    }

    light_io_close(out);
    return 0;
}

```

--------------------------------

### light_create_block / light_free_block

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Functions for managing PCAPNG blocks. `light_create_block` allocates and initializes a new `light_block` of a specified type with provided body data. `light_free_block` releases the memory associated with a `light_block` and its options.

```APIDOC
## `light_create_block` / `light_free_block` — Create and destroy a block

`light_create_block` allocates a new `light_block` of the given type and copies `body_length` bytes from `body`. `light_free_block` releases the block and all attached options.

### `light_create_block`

#### Parameters
- `type`: The type of the block to create (e.g., `LIGHT_SECTION_HEADER_BLOCK`).
- `body`: A pointer to the data for the block body.
- `body_length`: The number of bytes in the block body.

#### Returns
- A pointer to the newly created `light_block` on success.
- `NULL` on failure.

### `light_free_block`

#### Parameters
- `block`: A pointer to the `light_block` to free.
```

--------------------------------

### light_write_interface_block

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Writes an Interface Description Block (IDB) to the output PCAPNG file.

```APIDOC
## light_write_interface_block — Write an Interface Description Block

### Description
Writes an IDB to the output file before writing packets that belong to that interface. The interface is identified by its `link_type`, `name`, `description`, and `timestamp_resolution` fields.

### Parameters
- **writer** (`light_pcapng`) - Required - Handle to the PCAPNG file being written.
- **iface** (`const light_packet_interface*`) - Required - Pointer to a struct containing interface details.

### Returns
- (int) - `0` on success, non-zero on error.

### Example
```c
#include "light_pcapng_ext.h"

int main(void) {
    light_pcapng writer = light_pcapng_open("out.pcapng", "wb");

    light_packet_interface iface = {0};
    iface.link_type          = 1;              // LINKTYPE_ETHERNET
    iface.name               = "eth0";
    iface.description        = "Primary Ethernet adapter";
    iface.timestamp_resolution = 1000000000;   // nanosecond resolution

    int rc = light_write_interface_block(writer, &iface);
    if (rc != 0) fprintf(stderr, "Failed to write IDB\n");

    light_pcapng_close(writer);
    return rc;
}
```
```

--------------------------------

### Flush and Close PCAPNG Handle with light_pcapng_flush and light_pcapng_close

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Flushes pending writes to the I/O backend without closing the handle, useful for live captures. `light_pcapng_close` flushes and releases all resources.

```c
#include "light_pcapng_ext.h"

int main(void) {
    light_pcapng pcap = light_pcapng_open("live.pcapng", "wb");

    // ... write packets in a loop ...
    light_pcapng_flush(pcap);   // make data visible to other readers

    // ... write more packets ...
    int rc = light_pcapng_close(pcap);  // returns LIGHT_SUCCESS (0) on success
    return rc;
}

```

--------------------------------

### light_pcapng_flush / light_pcapng_close

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Provides functionality to flush pending writes to a PCAPNG file handle without closing it, and to properly close the handle, releasing all associated resources. `light_pcapng_flush` is useful for live capture scenarios, while `light_pcapng_close` ensures all data is written and resources are freed.

```APIDOC
## `light_pcapng_flush` / `light_pcapng_close` — Flush and close a PCAPNG handle

`light_pcapng_flush` flushes all pending writes to the underlying I/O backend without closing the handle, useful for live capture scenarios. `light_pcapng_close` flushes and releases all resources.

### `light_pcapng_flush`

#### Parameters
- `pcap`: A handle to the PCAPNG file.

### `light_pcapng_close`

#### Parameters
- `pcap`: A handle to the PCAPNG file.

#### Returns
- `LIGHT_SUCCESS` (0) on success.
- A non-zero error code on failure.
```

--------------------------------

### Write PCAPNG Interface Description Block

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Use `light_write_interface_block` to write an Interface Description Block (IDB) to a PCAPNG file before writing packets associated with that interface. Ensure the `link_type`, `name`, `description`, and `timestamp_resolution` fields are correctly set.

```c
#include "light_pcapng_ext.h"

int main(void) {
    light_pcapng writer = light_pcapng_open("out.pcapng", "wb");

    light_packet_interface iface = {0};
    iface.link_type          = 1;              // LINKTYPE_ETHERNET
    iface.name               = "eth0";
    iface.description        = "Primary Ethernet adapter";
    iface.timestamp_resolution = 1000000000;   // nanosecond resolution

    int rc = light_write_interface_block(writer, &iface);
    if (rc != 0) fprintf(stderr, "Failed to write IDB\n");

    light_pcapng_close(writer);
    return rc;
}
```

--------------------------------

### light_read_block / light_write_block

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Low-level functions for reading and writing raw PCAPNG blocks. `light_read_block` reads the next block from a file handle, returning a dynamically allocated `light_block`. `light_write_block` serializes a `light_block` to a file. These are fundamental for generic block processing like file merging.

```APIDOC
## `light_read_block` / `light_write_block` — Read and write raw PCAPNG blocks

`light_read_block` sequentially reads the next block from a `light_file` handle, returning a heap-allocated `light_block`. Passing an existing block pointer causes it to be freed before the next read. `light_write_block` serialises a `light_block` back to any `light_file`. This pair is the foundation for generic block-level processing such as file merging.

### `light_read_block`

#### Parameters
- `file`: A handle to the PCAPNG file.
- `block`: A pointer to a `light_block` pointer, which will be updated with the newly read block.
- `swap`: A pointer to a boolean flag indicating if byte-swapping is needed.

#### Returns
- A pointer to the `light_block` on success, or `NULL` if end-of-file is reached or an error occurs.

### `light_write_block`

#### Parameters
- `file`: A handle to the PCAPNG file.
- `block`: A pointer to the `light_block` to write.

#### Returns
- `0` on success.
- A non-zero error code on failure.
```

--------------------------------

### Write Packet to PCAPNG File

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Use `light_write_packet` to append an Enhanced Packet Block. If the interface is new, an IDB is automatically written. Ensure the `light_packet_interface` and `light_packet_header` are populated correctly, and provide the packet `payload` data.

```c
#include "light_pcapng_ext.h"
#include <stdlib.h>
#include <string.h>
#include <time.h>

int main(void) {
    light_pcapng writer = light_pcapng_open("out.pcapng", "wb");

    light_packet_interface iface = {0};
    iface.link_type            = 1;           // LINKTYPE_ETHERNET
    iface.name                 = "eth0";
    iface.timestamp_resolution = 1000000000;  // nanoseconds

    light_packet_header hdr = {0};
    struct timespec ts = {1627228100, 5000};
    hdr.timestamp        = ts;
    hdr.captured_length  = 64;
    hdr.original_length  = 64;
    hdr.flags            = 0x1;              // received direction
    hdr.comment          = "first packet";

    uint8_t *payload = calloc(64, 1);
    memset(payload, 0xAB, 64);

    int rc = light_write_packet(writer, &iface, &hdr, payload);
    if (rc != 0) fprintf(stderr, "light_write_packet failed: %d\n", rc);

    free(payload);
    light_pcapng_close(writer);
    return rc;
}
```

--------------------------------

### Byte-Swap PCAPNG Block Headers

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Provides functions to byte-swap PCAPNG block headers when reading big-endian files. Use these functions when `light_read_block` indicates `swap_endianness` is true.

```c
#include "light_pcapng.h"
#include "light_io.h"
#include "light_special.h"
#include <stdio.h>

int main(void) {
    light_file fd = light_io_open("big_endian.pcapng", "rb");
    light_block block = NULL;
    bool swap = false;

    light_read_block(fd, &block, &swap);
    while (block != NULL) {
        if (block->type == LIGHT_ENHANCED_PACKET_BLOCK) {
            struct _light_enhanced_packet_block *epb =
                (struct _light_enhanced_packet_block *)block->body;

            fix_endianness_enhanced_packet_block(epb, swap);

            printf("Interface ID: %u  Cap len: %u\n",
                   epb->interface_id,
                   epb->capture_packet_length);
        }
        light_read_block(fd, &block, &swap);
    }

    light_io_close(fd);
    return 0;
}
```

--------------------------------

### light_read_packet

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Reads the next packet from an open PCAPNG file, populating interface and header details.

```APIDOC
## light_read_packet — Read the next packet from an open PCAPNG file

### Description
Reads the next Enhanced Packet Block and populates `light_packet_interface` (link type, interface name, timestamp resolution) and `light_packet_header` (timestamp, captured/original lengths, flags, drop count, queue, comment). The `packet_data` pointer is valid until the next call. Returns `0` on success, non-zero at EOF or on error.

### Parameters
- **pcap** (`light_pcapng`) - Required - Handle to an open PCAPNG file.
- **iface** (`light_packet_interface*`) - Output - Pointer to a struct to be populated with interface information.
- **hdr** (`light_packet_header*`) - Output - Pointer to a struct to be populated with packet header information.
- **packet_data** (`const uint8_t**`) - Output - Pointer to a pointer that will be set to the packet data. The data is valid until the next call to `light_read_packet`.

### Returns
- (int) - `0` on success, non-zero at EOF or on error.

### Example
```c
#include "light_pcapng_ext.h"
#include <stdio.h>

int main(void) {
    light_pcapng pcap = light_pcapng_open("capture.pcapng", "rb");
    if (pcap == NULL) return 1;

    int index = 0;
    while (1) {
        light_packet_interface iface = {0};
        light_packet_header   hdr   = {0};
        const uint8_t        *data  = NULL;

        int res = light_read_packet(pcap, &iface, &hdr, &data);
        if (res != 0 || data == NULL) break;   // EOF or error

        printf("Pkt #%d: iface=%-12s link=%-4d cap=%5u orig=%5u ts=%ld.%09ld",
               ++index,
               iface.name          ? iface.name : "?",
               iface.link_type,
               hdr.captured_length,
               hdr.original_length,
               (long)hdr.timestamp.tv_sec,
               (long)hdr.timestamp.tv_nsec);

        if (hdr.comment)
            printf("  comment=\"%s\"", hdr.comment);
        printf("\n");
    }

    light_pcapng_close(pcap);
    return 0;
}
```
```

--------------------------------

### Write Decryption Secrets Block (DSB) with light_write_decryption_block

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Appends a DSB to a PCAPNG file to enable traffic decryption. Requires at least one packet to be written before the DSB. Supports TLS key logs and WireGuard keys.

```c
#include "light_pcapng_ext.h"
#include <stdio.h>
#include <string.h>

int main(void) {
    light_pcapng pcap = light_pcapng_open("tls_capture.pcapng", "wb");

    // Write at least one packet before the DSB (required by the spec)
    light_packet_interface iface = {0};
    iface.link_type            = 1;
    iface.name                 = "eth0";
    iface.timestamp_resolution = 1000000000;

    uint8_t pkt[60] = {0};
    light_packet_header hdr = {0};
    hdr.captured_length = hdr.original_length = sizeof(pkt);
    struct timespec ts = {1700000000, 0};
    hdr.timestamp = ts;
    light_write_packet(pcap, &iface, &hdr, pkt);

    // Embed a TLS 1.3 session key log (NSS Key Log Format)
    const char *keylog =
        "CLIENT_RANDOM 0102030405060708090a0b0c0d0e0f "
        "101112131415161718191a1b1c1d1e1f";

    light_packet_decryption dsb;
    dsb.secret_type = LIGHT_DSB_SECRET_TLSK;
    dsb.key         = (uint8_t *)keylog;
    dsb.key_size    = (uint32_t)strlen(keylog);
    dsb.comment     = "TLS session key";

    int rc = light_write_decryption_block(pcap, &dsb);
    if (rc != 0) fprintf(stderr, "Failed to write DSB: %d\n", rc);

    light_pcapng_close(pcap);
    return rc;
}

```

--------------------------------

### Read Packets from PCAPNG File

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Iteratively read packets using `light_read_packet`. This function populates interface and header details, and provides packet data. The `data` pointer is valid until the next call. Returns 0 on success, non-zero at EOF or on error.

```c
#include "light_pcapng_ext.h"
#include <stdio.h>

int main(void) {
    light_pcapng pcap = light_pcapng_open("capture.pcapng", "rb");
    if (pcap == NULL) return 1;

    int index = 0;
    while (1) {
        light_packet_interface iface = {0};
        light_packet_header   hdr   = {0};
        const uint8_t        *data  = NULL;

        int res = light_read_packet(pcap, &iface, &hdr, &data);
        if (res != 0 || data == NULL) break;   // EOF or error

        printf("Pkt #%d: iface=%-12s link=%-4d cap=%5u orig=%5u ts=%ld.%09ld",
               ++index,
               iface.name          ? iface.name : "?",
               iface.link_type,
               hdr.captured_length,
               hdr.original_length,
               (long)hdr.timestamp.tv_sec,
               (long)hdr.timestamp.tv_nsec);

        if (hdr.comment)
            printf("  comment=\"%s\"", hdr.comment);
        printf("\n");
    }

    light_pcapng_close(pcap);
    return 0;
}
```

--------------------------------

### light_write_packet

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Appends an Enhanced Packet Block for the given interface and header to a PCAPNG file.

```APIDOC
## light_write_packet — Write a packet to a PCAPNG file

### Description
Appends an Enhanced Packet Block for the given interface and header. If the interface has not yet been written to the file, an Interface Description Block is emitted automatically.

### Parameters
- **writer** (`light_pcapng`) - Required - Handle to the PCAPNG file being written.
- **iface** (`const light_packet_interface*`) - Required - Pointer to a struct containing interface details.
- **hdr** (`const light_packet_header*`) - Required - Pointer to a struct containing packet header information.
- **packet_data** (`const uint8_t*`) - Required - Pointer to the packet data payload.

### Returns
- (int) - `0` on success, non-zero on error.

### Example
```c
#include "light_pcapng_ext.h"
#include <stdlib.h>
#include <string.h>
#include <time.h>

int main(void) {
    light_pcapng writer = light_pcapng_open("out.pcapng", "wb");

    light_packet_interface iface = {0};
    iface.link_type            = 1;           // LINKTYPE_ETHERNET
    iface.name                 = "eth0";
    iface.timestamp_resolution = 1000000000;  // nanoseconds

    light_packet_header hdr = {0};
    struct timespec ts = {1627228100, 5000};
    hdr.timestamp        = ts;
    hdr.captured_length  = 64;
    hdr.original_length  = 64;
    hdr.flags            = 0x1;              // received direction
    hdr.comment          = "first packet";

    uint8_t *payload = calloc(64, 1);
    memset(payload, 0xAB, 64);

    int rc = light_write_packet(writer, &iface, &hdr, payload);
    if (rc != 0) fprintf(stderr, "light_write_packet failed: %d\n", rc);

    free(payload);
    light_pcapng_close(writer);
    return rc;
}
```
```

--------------------------------

### Endianness Helpers: fix_endianness_*

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Byte-swaps PCAPNG block headers on big-endian files. When `light_read_block` indicates endianness needs swapping (via the Section Header Block magic number), these functions should be used on the raw block body before accessing numeric fields.

```APIDOC
## `fix_endianness_*` — Byte-swap PCAPNG block headers on big-endian files

When `light_read_block` sets `swap_endianness = true` (detected via the Section Header Block byte-order magic `0x1A2B3C4D`), callers performing direct struct-overlay access must pass the raw body through the appropriate fix function before reading numeric fields.

### Example Usage
```c
#include "light_pcapng.h"
#include "light_io.h"
#include "light_special.h"
#include <stdio.h>

int main(void) {
    light_file fd = light_io_open("big_endian.pcapng", "rb");
    light_block block = NULL;
    bool swap = false;

    light_read_block(fd, &block, &swap);
    while (block != NULL) {
        if (block->type == LIGHT_ENHANCED_PACKET_BLOCK) {
            struct _light_enhanced_packet_block *epb =
                (struct _light_enhanced_packet_block *)block->body;

            fix_endianness_enhanced_packet_block(epb, swap);

            printf("Interface ID: %u  Cap len: %u\n",
                   epb->interface_id,
                   epb->capture_packet_length);
        }
        light_read_block(fd, &block, &swap);
    }

    light_io_close(fd);
    return 0;
}
```
```

--------------------------------

### light_write_decryption_block

Source: https://context7.com/technica-engineering/lightpcapng/llms.txt

Appends a Decryption Secrets Block (DSB) to a PCAPNG file. This block can contain cryptographic keys or keylogs, enabling tools like Wireshark to decrypt captured traffic. Supported secret types include TLS key logs and WireGuard keys.

```APIDOC
## `light_write_decryption_block` — Write a Decryption Secrets Block (DSB)

Appends a DSB containing a cryptographic key or keylog, enabling tools such as Wireshark to decrypt captured traffic inline. Supported secret types are `LIGHT_DSB_SECRET_TLSK` (TLS key log), `LIGHT_DSB_SECRET_WGKL` (WireGuard keys), `LIGHT_DSB_SECRET_ZNWK`, and `LIGHT_DSB_SECRET_ZAPK`. Key data is padded to a 4-byte boundary automatically.

### Parameters
- `pcap`: A handle to the PCAPNG file.
- `dsb`: A pointer to a `light_packet_decryption` structure containing the secret type, key data, key size, and an optional comment.

### Returns
- `0` on success.
- A non-zero error code on failure.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.