CURLOPT_WS_OPTIONS(3)

💅 CURLOPT_WS_OPTIONS ✨

Okay so bestie, welcome to the CURLOPT_WS_OPTIONS page from the Library Functions Manual — yes, that manual, the one with all the curl lore. This one's all about making your WebSocket behave exactly how you want it to. Sit down, grab a boba, we're getting into it 🧋💖

---

🌸 NAME 🌸

CURLOPT_WS_OPTIONS — WebSocket behavior options, aka the vibe settings for your WebSocket conn 😌✨

---

🎀 SYNOPSIS 🎀

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WS_OPTIONS, long bitmask);

---

🦋 DESCRIPTION 🦋

So you pass a long that's a bitmask, right? And that bitmask tells libcurl about specific WebSocket behaviors. Very "here's my settings, don't ask questions" energy 💅

Now, if you wanna detach a WebSocket connection and use curl_ws_send(3) and curl_ws_recv(3) after the HTTP upgrade procedure — you're gonna set the CURLOPT_CONNECT_ONLY(3) option to 2L. That's the move. No cap 🫶

⭐ Available bits in the bitmask ⭐

• CURLWS_RAW_MODE (1) — Delivers "raw" WebSocket traffic to the CURLOPT_WRITEFUNCTION(3) callback, and reads "raw" WebSocket traffic from the CURLOPT_READFUNCTION(3) callback. And listen — in raw mode, libcurl does not handle pings or any other frame for the application. It's all you, main character 👑
• CURLWS_NOAUTOPONG (2) — Disables the automatic reply to PING messages. Which means you have to send a PONG message yourself with curl_ws_send(3). The way this feature was added with version 8.14.0 — iconic 🔥

---

🌈 DEFAULT 🌈

0

---

💜 PROTOCOLS 💜

This functionality affects ws only. That's it. That's the whole protocol list. ws and nothing else 🦋

---

🍓 EXAMPLE 🍓

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "ws://example.com/");
    /* tell curl we deal with all the WebSocket magic ourselves */
    curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, CURLWS_RAW_MODE);
    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}

Literally the whole thing. We're handling all the WebSocket magic ourselves, bestie 🧚✨

---

💀 HISTORY 💀

Okay so the CURLWS_RAW_MODE and CURLWS_NOAUTOPONG macros became long types in 8.16.0. Which means — before that version, a long cast was necessary when passed to curl_easy_setopt(3). Yes, an actual cast. We used to live like that 😭🙈

---

🌸 AVAILABILITY 🌸

Added in curl 7.86.0 — so if you're on something ancient, sorry babe 🎀

---

✨ RETURN VALUE ✨

curl_easy_setopt(3) returns a CURLcode indicating success or error. Groundbreaking, I know.

CURLE_OK (0) means everything was OK. Non-zero means an error occurred — see libcurl-errors(3) for the full tea ☕💅

---

🫶 SEE ALSO 🫶

• CURLOPT_CONNECT_ONLY(3)
• curl_ws_recv(3)
• curl_ws_send(3)

---

💖 That's the whole page bestie — go forth and configure your WebSockets with confidence. iykyk ✨

---

Later, legend 🦋 — this page came to you from the libcurl fam, dated 2026-10-12, and it's CURLOPT_WS_OPTIONS(3) all day. Mwah 💋