libcurl-ws(3) Library Functions Manual libcurl-ws(3)
NAME
libcurl-ws - WebSocket interface overview
DESCRIPTION
The WebSocket interface provides functions for receiving and sending
WebSocket data.
INCLUDE
You still only include <curl/curl.h> in your code.
SETUP
WebSocket is also often known as WebSockets, in plural. It is done by
upgrading a regular HTTP(S) GET request to a WebSocket connection.
WebSocket is a TCP-like message-based communication protocol done over
HTTP, specified in RFC 6455.
To initiate a WebSocket session with libcurl, setup an easy handle to
use a URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext com-
munication over HTTP and "WSS" is for doing WebSocket securely over
HTTPS.
A WebSocket request is done as an HTTP/1 GET request with an "Upgrade
WebSocket" request header field. When the upgrade is accepted by the
server, it responds with a 101 Switching and then the client can speak
WebSocket with the server. The communication can happen in both direc-
tions at the same time.
EXTENSIONS
The WebSocket protocol allows the client to request and negotiate exten-
sions can add additional features and restrictions to the protocol.
libcurl does not support the use of extensions and always sets up a con-
nection without them.
MESSAGES
WebSocket communication is message based. That means that both ends send
and receive entire messages, not streams like TCP. A WebSocket message
is sent over the wire in one or more frames. A message which is split
into several frames is referred to as a fragmented message and the indi-
vidual frames are called fragments. Each frame (or fragment) in a mes-
sage can have a size of up to 2^63 bytes and declares the frame size in
the header. The total size of a message that is fragmented into multiple
frames is not limited by the protocol and the number of fragments is not
known until the final fragment is received.
Transmission of a frame must not be interrupted by any other data trans-
fers and transmission of the different fragments of a message must not
be interrupted by other user data frames. Control frames - PING, PONG
and CLOSE - may be transmitted in between any other two frames, even in
between two fragments of the same user data message. The control frames
themselves on the other hand must never be fragmented and are limited to
a size of 125 bytes.
libcurl delivers WebSocket data as chunks of frames. It might deliver a
whole frame as a single chunk, but it might also deliver it in several
pieces depending on size and network patterns. See the individual API
documentations for further information.
PING
WebSocket is designed to allow long-lived sessions and in order to keep
the connections alive, both ends can send PING messages for the other
end to respond with a PONG. Both ends may also send unsolicited PONG
messages as unidirectional heartbeat.
libcurl automatically responds to server PING messages with a PONG that
echoes the payload of the PING message. libcurl does neither send any
PING messages nor any unsolicited PONG messages automatically. The auto-
matic reply to PING messages can be disabled through CURLOPT_WS_OP-
TIONS(3).
MODELS
Because of the many different ways WebSocket can be used, which is much
more flexible than limited to plain downloads or uploads, libcurl offers
two different API models to use it:
1. CURLOPT_WRITEFUNCTION model: Using a write callback with CUR-
LOPT_WRITEFUNCTION(3) much like other downloads for when the traffic is
download oriented.
2. CURLOPT_CONNECT_ONLY model: Using curl_ws_recv(3) and curl_ws_send(3)
functions.
CURLOPT_WRITEFUNCTION MODEL
CURLOPT_CONNECT_ONLY(3) must be unset or 0L for this model to
take effect.
curl_easy_perform(3) establishes and sets up the WebSocket commu-
nication and then blocks for the whole duration of the connec-
tion. libcurl calls the callback configured in CURLOPT_WRITEFUNC-
TION(3), whenever an incoming chunk of WebSocket data is re-
ceived. The callback is handed a pointer to the payload data as
an argument and can call curl_ws_meta(3) to get relevant meta-
data.
CURLOPT_CONNECT_ONLY MODEL
CURLOPT_CONNECT_ONLY(3) must be 2L for this model to take effect.
curl_easy_perform(3) only establishes and sets up the WebSocket
communication and then returns control back to the application.
The application can then use curl_ws_recv(3) and curl_ws_send(3)
to exchange WebSocket messages with the server.
RAW MODE
libcurl can be told to speak WebSocket in "raw mode" by setting the
CURLWS_RAW_MODE bit of the CURLOPT_WS_OPTIONS(3) option.
Raw WebSocket means that libcurl passes on the data from the network
without parsing it, leaving that entirely to the application.
This mode is intended for applications that already have a WebSocket
parser/engine and want to switch over to use libcurl for enabling Web-
Socket, and keep parts of the existing software architecture.
SEE ALSO
CURLOPT_CONNECT_ONLY(3), CURLOPT_WRITEFUNCTION(3), CURLOPT_WS_OP-
TIONS(3), curl_easy_init(3), curl_ws_meta(3), curl_ws_recv(3),
curl_ws_send(3)
libcurl 2026-07-12 libcurl-ws(3)
Generated by dwww version 1.16 on Sat Oct 3 04:19:53 CEST 2026.