curl_ws_recv(3)

💅 curl_ws_recv(3) — the WebSocket tea ☕✨

okay bestie, so this is a libcurl function — like, the actual manual page vibe — and we're gonna get into curl_ws_recv together. no cap, it's giving "receiving WebSocket data" and it's lowkey iconic. let's go 🫶

---

✨ NAME ✨

curl_ws_recv — receive WebSocket data 🦋

---

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
                      size_t *recv, const struct curl_ws_frame **meta);

---

💖 DESCRIPTION 💖

So the way this works: it retrieves as much as possible of a received WebSocket frame into the buffer, but bestie, not more than buflen bytes. and recv gets set to the number of bytes actually stored. periodt.

If the function call is successful, the meta pointer gets set to point to a const struct curl_ws_frame that contains all the info about the received data. That struct must not be freed and its contents must not be relied upon anymore once another WebSocket function is called. like, it's not yours to keep, okay? see curl_ws_meta(3) for more deets on that struct 👑

The application must check meta->bytesleft to determine whether the complete frame has been received. If more payload is pending, the application must call this function again with an updated buffer and buflen to resume receiving. this may for example happen when the data does not fit into the provided buffer or when not all frame data has been delivered over the network yet. it's giving "patience is a virtue" energy fr fr 😭

If the application wants to read the metadata without consuming any payload, it may call this function with a buflen of zero. setting buffer to a NULL pointer is permitted in this case. note that frames without payload are consumed by this action 👀 (sneaky but valid)

If the received message consists of multiple fragments, the CURLWS_CONT bit is set in all frames except the final one. the appropriate CURLWS_TEXT or CURLWS_BINARY flag is set in every frame, regardless whether it is the first fragment, an intermediate fragment or the final fragment. the application is responsible for reassembling fragmented messages. special care must be taken to correctly handle control frames (i.e. CLOSE, PING and PONG) arriving in between consecutive fragments of a fragmented TEXT or BINARY message. see curl_ws_meta(3) for more details on CURLWS_CONT. this is the main character energy of the whole page, ngl 💀

The WebSocket protocol consists of messages that can be delivered over the wire as one or more frames — but since a frame can be too large to buffer in memory, libcurl may need to deliver partial frames to the application. fragments, or chunks, of frames. it's giving "sliced bread but make it networking" 🍓

---

🦋 PROTOCOLS 🦋

This functionality affects ws only ✨

---

🎀 EXAMPLE 🎀

int main(void)
{
  char buffer[256];
  size_t offset = 0;
  CURLcode result = CURLE_OK;
  CURL *curl = curl_easy_init();

  curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/");
  curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L);
  /* start HTTPS connection and upgrade to WSS, then return control */
  curl_easy_perform(curl);

  /* Note: This example neglects fragmented messages.
     (CURLWS_CONT bit) A real application must handle them
     appropriately. */

  while(!result) {
    size_t recv;
    const struct curl_ws_frame *meta;
    result = curl_ws_recv(curl, buffer + offset,
                          sizeof(buffer) - offset, &recv,
                          &meta);
    offset += recv;

    if(result == CURLE_OK) {
      if(meta->bytesleft == 0)
        break; /* finished receiving */
      if(meta->bytesleft > sizeof(buffer) - offset)
        result = CURLE_TOO_LARGE;
    }

    if(result == CURLE_AGAIN)
      /* in real application: wait for socket here, e.g. using select() */
      result = CURLE_OK;
  }

  curl_easy_cleanup(curl);
  return (int)result;
}

⚠️ bestie, this example neglects fragmented messages (the CURLWS_CONT bit) — a real application must handle them appropriately. don't be like this example in prod, iykyk 🙈

---

🌈 AVAILABILITY 🌈

Added in curl 7.86.0 — vintage but cute 💜

---

🔥 RETURN VALUE 🔥

This function returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3) there can be an error message stored in the error buffer when non-zero is returned. handy, right? 🫶

Returns CURLE_GOT_NOTHING if the associated connection is closed. yes, again — it's that important, they said it twice, so i'm saying it twice too 💀

Instead of blocking, the function returns CURLE_AGAIN. the correct behavior is then to wait for the socket to signal readability before calling this function again. like, don't just spin, bestie, wait for the signal ✨

Any other non-zero return value indicates an error. see the libcurl-errors(3) man page for the full list with descriptions. it's all there, no gatekeeping 📚

Returns CURLE_GOT_NOTHING if the associated connection is closed. (yes, that's the second time. iconic of them tbh 👑)

---

⭐ SEE ALSO ⭐

curl_easy_getinfo(3), curl_easy_perform(3), curl_easy_setopt(3), curl_ws_send(3), libcurl-ws(3) — go read these next, bestie, they're all linked and everything 🌸

---

and that's the whole page, no cap 💅✨

— sign-off: this masterpiece is from libcurl, dated 2026-10-12, and it's literally the curl_ws_recv(3) manual page. periodt. 🎀🦋💖