curl_ws_meta(3)

💖 NAME 💖

okay so bestie, this is the curl_ws_meta(3) page from the Library Functions Manual — it's literally curl_ws_meta for meta data WebSocket information. No cap, this is the one that hands you the tea about the current WebSocket frame. 💅

✨ SYNOPSIS ✨

#include <curl/curl.h>

const struct curl_ws_frame *curl_ws_meta(CURL *curl);

🦋 DESCRIPTION 🦋

When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on received WebSocket traffic, curl_ws_meta(3) can be called from inside the callback to give you extra information about the current frame. ✨

bestie, listen: this function only works from within the callback, and only when receiving WebSocket data. That's the vibe check. 🫶

This function requires an easy handle as its input argument so libcurl knows which transfer you're asking about, but since libcurl itself does not provide such a pointer to the callback, applications that want to use curl_ws_meta(3) need to pass it on to the callback on their own. Yes, you gotta hand-deliver the easy handle. iconic, honestly. 💀

🧚 struct curl_ws_frame 🧚

struct curl_ws_frame {
  int age;
  int flags;
  curl_off_t offset;
  curl_off_t bytesleft;
  size_t len;
};

• age — this field specifies the age of this struct. It is always zero for now. 🎀
• flags — this is a bitmask with individual bits set that describes the WebSocket data. See the list below. 👑
• offset — when this chunk is a continuation of frame data already delivered, this is the offset into the final frame data where this piece belongs. 🧩
• bytesleft — if this is not a complete fragment, the bytesleft field tells you how many additional bytes are expected to arrive before this fragment is complete. ⏳
• len — the length of the current data chunk. 📏

🔥 FLAGS 🔥

The message type flags (CURLWS_TEXT/BINARY/CLOSE/PING/PONG) are mutually exclusive. pick one, bestie — no combo meals. 🍓

• CURLWS_TEXT — this is a message with text data. Note that this makes a difference to WebSocket but libcurl itself does not make any verification of the content or precautions that you actually receive valid UTF-8 content. 👀
• CURLWS_BINARY — this is a message with binary data. 🖤
• CURLWS_CLOSE — this is a close message. No more data follows. ✌️
  • It may contain a 2-byte unsigned integer in network byte order that indicates the close reason and may additionally contain up to 123 bytes of further textual payload for a total of at most 125 bytes. libcurl does not verify that the textual description is valid UTF-8. 🔢
• CURLWS_PING — this is a ping message. It may contain up to 125 bytes of payload text. libcurl does not verify that the payload is valid UTF-8. 🏓
  • Upon receiving a ping message, libcurl automatically responds with a pong message unless the CURLWS_NOAUTOPONG or CURLWS_RAW_MODE bit of CURLOPT_WS_OPTIONS(3) is set. 🤖
• CURLWS_PONG — this is a pong message. It may contain up to 125 bytes of payload text. libcurl does not verify that the payload is valid UTF-8. 🏸
• CURLWS_CONT — can only occur in conjunction with CURLWS_TEXT or CURLWS_BINARY. 🧵
  • This is not the final fragment of the message, it implies that there is another fragment coming as part of the same message. The application must reassemble the fragments to receive the complete message. 🧩
  • Only a single fragmented message can be transmitted at a time, but it may be interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames. ⚡

🌈 PROTOCOLS 🌈

This functionality affects ws only. that's it, that's the protocol. 💫

🎀 EXAMPLE 🎀

/* we pass a pointer to this struct to the callback */
struct customdata {
  CURL *easy;
  void *ptr;
};

static size_t writecb(char *buffer, size_t size, size_t nitems, void *p)
{
  struct customdata *c = (struct customdata *)p;
  const struct curl_ws_frame *m = curl_ws_meta(c->easy);

  printf("flags: %x\n", m->flags);
  return 0;
}

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    struct customdata custom;
    custom.easy = curl;
    custom.ptr = NULL;
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb);
    curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom);

    curl_easy_perform(curl);
  }
  return 0;
}

⭐ AVAILABILITY ⭐

Added in curl 7.86.0. yes bestie, exact version. 💚

👑 RETURN VALUE 👑

This function returns a pointer to a curl_ws_frame struct with read-only information that is valid for this specific callback invocation. If it cannot return this information, or if the function is called in the wrong context, it returns NULL. 😭 no info, no pointer, periodt. 💅

💜 SEE ALSO 💜

• curl_easy_getinfo(3)
• curl_easy_setopt(3)
• curl_ws_recv(3)
• curl_ws_send(3)
• libcurl-ws(3)

---

mwah 💋 — this sassy lil page comes from libcurl, dated 2026-10-12, and the manual name is curl_ws_meta(3) 🎀✨