curl_ws_meta.md: polish and better vocabulary

[bagder]

No description provided.

[Copilot]

Pull request overview

Polishes the curl_ws_meta(3) manpage wording and formatting, clarifying how to interpret metadata for received WebSocket data.

Changes:

• Reflows the DESCRIPTION paragraph for better readability.
• Adds an explanatory paragraph distinguishing WebSocket frames from libcurl-delivered chunks.
• Updates terminology in bytesleft and CURLWS_CONT sections from “fragment” to “frame”.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bagder]

@HendrikHuebner does it clarify enough? Is it still vague in some area?

[HendrikHuebner]

That's definitely clearer. Additionally, I'd like to see clarification on whether the buffer libcurl provides to the write callback can contain multiple chunks from different frames, and how the application must handle this.

For example, if we receive two frames in quick succession, curl presumably buffers these before dispatching the write callback. In my application I observed this scenario, where meta->len was smaller than nmemb (the number of bytes in the receive buffer). This suggests, that the buffer contained more than one chunk, and I handled this by returning the number of consumed bytes meta->len.

[bagder]

Added:

Each callback delivers data for a single chunk that is then part of a single frame.

if we receive two frames in quick succession, curl presumably buffers these before dispatching the write callback

Not likely. It delivers the first callback and then it reuses buffers internally and calls the callback again with the next chunk, probably using the same memory area as for the previous callback. An application cannot assume anything else at least.

In my application I observed this scenario, where meta->len was smaller than nmemb (the number of bytes in the receive buffer). This suggests, that the buffer contained more than one chunk

It suggests the buffer contains data after the chunk, yes. Right now I can't recall why it would do that...

[HendrikHuebner]

Right, I'll try to investigate in my application, but at least it seems like the shape is generally correct already.

Maybe @icing knows, whether nmemb > meta->len is expected behavior?

The other problem from my original issue is that I observed strange values for len and offset, after pausing in the write callback. I'll create another issue with a reproducer once I'm confident that it's not some obvious problem with my code.