> For the complete documentation index, see [llms.txt](https://pcap.ardikars.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pcap.ardikars.com/packet-structure/packet-buffer.md).

# Packet Buffer

This buffer use network-byte-order (big endian) by default.

#### Using Packet Buffer.

* Allocate and Deallocate buffer

```java
final Pcap pcap = ..;
// allocate 8 bytes memory block.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class).capacity(8);

// deallocate ( free buffer).
assert true == buffer.release();
// double free is not allowed.
assert false == buffer.release();
```

* Slice and Unslice buffer

```java
// allocate 8 bytes memory block.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class).capacity(8);
final PacketBuffer sliced = buffer.slice();
final PacketBuffer unSliced = ((PacketBuffer.Sliced) sliced).unSlice();
assert buffer != sliced;
assert buffer == unSliced;
// Whatever you do with either sliced or unSliced buffer will affect the original buffer.
// for example when calling release() on the sliced buffer.
assert true == sliced.release();
assert false == buffer.release();
assert false == unSliced.release();
```

**What happen if I forget to call release() before it's garbage collected?**

PacketBuffer uses phantom reference for handling that case. Off-heap (native) buffer will be freed automatically when the object that wraps the off-heap buffer is garbage collected. Instead of waiting for unused buffer object garbage collected, you can free the off-heap buffer immediately by calling release() to avoid a large amount of unused off-heap memory.

You can enable memory leak detection by setting the properties "pcap.leakDetection" to "true". It can be useful to find where is the buffer that you forgot to release.

**What happen when I read/write (accessing) freed/closed buffer?**

MemoryAccessException will be thrown when you are trying to access the freed/closed buffer.

* Set/Get value from the buffer

```java
final Pcap pcap = ..;
// allocate 8 bytes memory block.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class).capacity(8);

buffer.setInt(0, 10);
buffet.setInt(4, 20);

assert 10 == buffer.getInt(0);
assert 20 == buffer.getInt(4);

assert true = buffer.release();
```

* Write/Read value from the buffer

```java
final Pcap pcap = ..;
// allocate 8 bytes memory block.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class).capacity(8);
assert 0 == buffer.readerIndex();
assert 0 == buffer.writerIndex();

buffer.writeInt(10);
assert 0 == buffer.readerIndex();
assert 4 == buffer.writerIndex();

buffer.writeInt(20);
assert 0 == buffer.readerIndex();
assert 8 == buffer.writerIndex();

assert 10 == buffer.readInt();
assert 4 == buffer.readerIndex();
assert 8 == buffer.writerIndex();

assert 20 == buffer.readInt();
assert 8 == buffer.readerIndex();
assert 8 == buffer.writerIndex();

assert true = buffer.release();
```

* Using PacketBuffer for nextEx call

```java
final Pcap pcap = ..;
final PacketHeader header = pcap.allocate(PacketHeader.class);
// no need to call buffer.capacity(..); no malloc needed.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class);

pcap.nextEx(header, buffer);

// buffer is not guaranteed to be valid after the next call
// copy the buffer if necessary
final copied = buffer.copy();
assert true == copied.release();

// no need to call buffer.release();
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pcap.ardikars.com/packet-structure/packet-buffer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.