curl\_ws\_start\_frame(3) Library Functions Manual curl\_ws\_start\_frame(3)

# [NAME](#NAME)

curl\_ws\_start\_frame - start a new WebSocket frame

# [SYNOPSIS](#SYNOPSIS)

```
#include <curl/curl.h>
CURLcode curl_ws_start_frame(CURL *curl,


                             unsigned int flags,


                             curl_off_t frame_len);
```

# [DESCRIPTION](#DESCRIPTION)

Add the WebSocket frame header for the given flags and length to the transfers send buffer for WebSocket encoded data. Intended for use in a [*CURLOPT\_READFUNCTION(3)*](/man/os/curl/CURLOPT_READFUNCTION.3) callback.

When using a [*CURLOPT\_READFUNCTION(3)*](/man/os/curl/CURLOPT_READFUNCTION.3) in a WebSocket transfer, any data returned by that function is sent as a *CURLWS\_BINARY* frame with the length being the amount of data read.

To send larger frames or frames of a different type, call curl\_ws\_start\_frame() from within the read function and then return the data belonging to the frame.

The function fails, if a previous frame has not been completely read yet. Also it fails in *CURLWS\_RAW\_MODE*.

The read function in libcurl usually treats a return value of 0 as the end of file indication and stops any further reads. This would prevent sending WebSocket frames of length 0.

If the read function calls *curl\_ws\_start\_frame()*, a return value of 0 is *not* treated as an end of file and libcurl calls the read function again.

# [FLAGS](#FLAGS)

Supports all flags documented in [*curl\_ws\_meta(3)*](/man/os/curl/curl_ws_meta.3).

# [PROTOCOLS](#PROTOCOLS)

This functionality affects ws only

# [EXAMPLE](#EXAMPLE)

```
#include <string.h> /* for strlen */
struct read_ctx {


  CURL *easy;


  const char *message;


  size_t msg_len;


  size_t nsent;
};
static size_t readcb(char *buf, size_t nitems, size_t buflen, void *p)
{


  struct read_ctx *ctx = p;


  size_t len = nitems * buflen;


  size_t left = ctx->msg_len - ctx->nsent;


  if(!ctx->nsent) {


    CURLcode result;


    /* Want to send TEXT frame. */


    result = curl_ws_start_frame(ctx->easy, CURLWS_TEXT,


                                 (curl_off_t)ctx->msg_len);


    if(result != CURLE_OK) {


      fprintf(stderr, "error starting frame: %d\n", (int)result);


      return CURL_READFUNC_ABORT;


    }


  }


  if(left) {


    if(left < len)


      len = left;


    memcpy(buf, ctx->message + ctx->nsent, len);


    ctx->nsent += len;


    return len;


  }


  return 0;
}
int main(void)
{


  CURL *easy;


  struct read_ctx rctx;


  CURLcode result;


  easy = curl_easy_init();


  if(!easy)


    return 1;


  curl_easy_setopt(easy, CURLOPT_URL, "wss://example.com");


  curl_easy_setopt(easy, CURLOPT_READFUNCTION, readcb);


  /* tell curl that we want to send the payload */


  memset(&rctx, 0, sizeof(rctx));


  rctx.easy = easy;


  rctx.message = "Hello, friend!";


  rctx.msg_len = strlen(rctx.message);


  curl_easy_setopt(easy, CURLOPT_READDATA, &rctx);


  curl_easy_setopt(easy, CURLOPT_UPLOAD, 1L);


  /* Perform the request, result gets the return code */


  result = curl_easy_perform(easy);


  /* Check for errors */


  if(result != CURLE_OK)


    fprintf(stderr, "curl_easy_perform() failed: %s\n",


            curl_easy_strerror(result));


  /* always cleanup */


  curl_easy_cleanup(easy);


  return 0;
}
```

# [AVAILABILITY](#AVAILABILITY)

Added in curl 8.16.0

# [RETURN VALUE](#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)*](/man/os/curl/libcurl-errors.3). If [*CURLOPT\_ERRORBUFFER(3)*](/man/os/curl/CURLOPT_ERRORBUFFER.3) was set with [*curl\_easy\_setopt(3)*](/man/os/curl/curl_easy_setopt.3) there can be an error message stored in the error buffer when non-zero is returned.

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.

Any other non-zero return value indicates an error. See the [*libcurl-errors(3)*](/man/os/curl/libcurl-errors.3) man page for the full list with descriptions.

# [SEE ALSO](#SEE_ALSO)

[**curl\_easy\_getinfo**(3)](/man/os/curl/curl_easy_getinfo.3), [**curl\_easy\_perform**(3)](/man/os/curl/curl_easy_perform.3), [**curl\_easy\_setopt**(3)](/man/os/curl/curl_easy_setopt.3), [**curl\_ws\_recv**(3)](/man/os/curl/curl_ws_recv.3), [**libcurl-ws**(3)](/man/os/curl/libcurl-ws.3)

2026-10-14 libcurl

---

Document: curl_ws_start_frame(3) from curl 8.23.0-r0 (Chainguard OS)
Source: https://github.com/curl/curl.git