1--- 2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_easy_send 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_getinfo (3) 9 - curl_easy_perform (3) 10 - curl_easy_recv (3) 11 - curl_easy_setopt (3) 12--- 13 14# NAME 15 16curl_easy_send - sends raw data over an "easy" connection 17 18# SYNOPSIS 19 20~~~c 21#include <curl/curl.h> 22 23CURLcode curl_easy_send(CURL *curl, const void *buffer, 24 size_t buflen, size_t *n); 25~~~ 26 27# DESCRIPTION 28 29This function sends arbitrary data over the established connection. You may 30use it together with curl_easy_recv(3) to implement custom protocols 31using libcurl. This functionality can be particularly useful if you use 32proxies and/or SSL encryption: libcurl takes care of proxy negotiation and 33connection setup. 34 35**buffer** is a pointer to the data of length **buflen** that you want 36sent. The variable **n** points to receives the number of sent bytes. 37 38To establish the connection, set CURLOPT_CONNECT_ONLY(3) option before 39calling curl_easy_perform(3) or curl_multi_perform(3). Note that 40curl_easy_send(3) does not work on connections that were created without 41this option. 42 43The call returns **CURLE_AGAIN** if it is not possible to send data right now 44- the socket is used in non-blocking mode internally. When **CURLE_AGAIN** 45is returned, use your operating system facilities like *select(2)* to wait 46until the socket is writable. The socket may be obtained using 47curl_easy_getinfo(3) with CURLINFO_ACTIVESOCKET(3). 48 49Furthermore if you wait on the socket and it tells you it is writable, 50curl_easy_send(3) may return **CURLE_AGAIN** if the only data that was sent 51was for internal SSL processing, and no other data could be sent. 52 53# EXAMPLE 54 55~~~c 56int main(void) 57{ 58 CURL *curl = curl_easy_init(); 59 if(curl) { 60 CURLcode res; 61 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 62 /* Do not do the transfer - only connect to host */ 63 curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); 64 res = curl_easy_perform(curl); 65 66 if(res == CURLE_OK) { 67 long sockfd; 68 size_t sent; 69 /* Extract the socket from the curl handle - we need it for waiting. */ 70 res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); 71 72 /* send data */ 73 res = curl_easy_send(curl, "hello", 5, &sent); 74 } 75 } 76} 77~~~ 78 79# AVAILABILITY 80 81Added in 7.18.2. 82 83# RETURN VALUE 84 85On success, returns **CURLE_OK** and stores the number of bytes actually 86sent into ***n**. Note that this may be less than the amount you wanted to 87send. 88 89On failure, returns the appropriate error code. 90 91This function may return **CURLE_AGAIN**. In this case, use your operating 92system facilities to wait until the socket is writable, and retry. 93 94If there is no socket available to use from the previous transfer, this function 95returns **CURLE_UNSUPPORTED_PROTOCOL**. 96