curl_ws_recv(3) Library Functions Manual curl_ws_recv(3)
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
Retrieves as much as possible of a received WebSocket frame into the
buffer, but not more than buflen bytes. recv is set to the number of
bytes actually stored.
If the function call is successful, the meta pointer gets set to point
to a const struct curl_ws_frame that contains information about the re-
ceived data. That struct must not be freed and its contents must not be
relied upon anymore once another WebSocket function is called. See
curl_ws_meta(3) for more details on that struct.
The application must check meta->bytesleft to determine whether the com-
plete frame has been received. If more payload is pending, the applica-
tion 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 deliv-
ered over the network yet.
If the application wants to read the metadata without consuming any pay-
load, 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 pay-
load are consumed by this action.
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 de-
tails on CURLWS_CONT.
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 ap-
plication. Fragments, or chunks, of frames.
PROTOCOLS
This functionality affects ws only
EXAMPLE
int main(void)
{
char buffer[256];
size_t offset = 0;
CURLcode res = 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(!res) {
size_t recv;
const struct curl_ws_frame *meta;
res = curl_ws_recv(curl, buffer + offset, sizeof(buffer) - offset, &recv,
&meta);
offset += recv;
if(res == CURLE_OK) {
if(meta->bytesleft == 0)
break; /* finished receiving */
if(meta->bytesleft > sizeof(buffer) - offset)
res = CURLE_TOO_LARGE;
}
if(res == CURLE_AGAIN)
/* in real application: wait for socket here, e.g. using select() */
res = CURLE_OK;
}
curl_easy_cleanup(curl);
return (int)res;
}
AVAILABILITY
Added in curl 7.86.0
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.
Returns CURLE_GOT_NOTHING if the associated connection is closed.
Instead of blocking, the function returns CURLE_AGAIN. The correct be-
havior is then to wait for the socket to signal readability before call-
ing this function again.
Any other non-zero return value indicates an error. See the libcurl-er-
rors(3) man page for the full list with descriptions.
Returns CURLE_GOT_NOTHING if the associated connection is closed.
SEE ALSO
curl_easy_getinfo(3), curl_easy_perform(3), curl_easy_setopt(3),
curl_ws_send(3), libcurl-ws(3)
libcurl 2026-07-12 curl_ws_recv(3)
Generated by dwww version 1.16 on Sat Oct 3 04:57:53 CEST 2026.