1curl_easy_recv(3)               libcurl Manual               curl_easy_recv(3)
2
3
4

NAME

6       curl_easy_recv - receives raw data on an "easy" connection
7

SYNOPSIS

9       #include <curl/easy.h>
10
11       CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n);
12

DESCRIPTION

14       This  function  receives  raw data from the established connection. You
15       may use it together with curl_easy_send(3) to implement  custom  proto‐
16       cols  using  libcurl.  This functionality can be particularly useful if
17       you use proxies and/or SSL encryption: libcurl will take care of  proxy
18       negotiation and connection setup.
19
20       buffer is a pointer to your buffer that will get the received data. bu‐
21       flen is the maximum amount of data you can  get  in  that  buffer.  The
22       variable n points to will receive the number of received bytes.
23
24       To  establish the connection, set CURLOPT_CONNECT_ONLY(3) option before
25       calling  curl_easy_perform(3)  or  curl_multi_perform(3).   Note   that
26       curl_easy_recv(3)  does not work on connections that were created with‐
27       out this option.
28
29       The call will return CURLE_AGAIN if there is no  data  to  read  -  the
30       socket is used in non-blocking mode internally. When CURLE_AGAIN is re‐
31       turned, use your operating system facilities like select(2) to wait for
32       data.  The  socket  may  be  obtained  using  curl_easy_getinfo(3) with
33       CURLINFO_ACTIVESOCKET(3).
34
35       Wait on the socket only if curl_easy_recv(3) returns CURLE_AGAIN.   The
36       reason for this is libcurl or the SSL library may internally cache some
37       data, therefore you should call curl_easy_recv(3)  until  all  data  is
38       read which would include any cached data.
39
40       Furthermore if you wait on the socket and it tells you there is data to
41       read, curl_easy_recv(3) may return CURLE_AGAIN if the  only  data  that
42       was  read  was for internal SSL processing, and no other data is avail‐
43       able.
44

EXAMPLE

46        curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
47        /* Do not do the transfer - only connect to host */
48        curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
49        res = curl_easy_perform(curl);
50
51        if(res == CURLE_OK) {
52          /* Extract the socket from the curl handle -
53             we will need it for waiting. */
54          res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
55
56          /* read data */
57          res = curl_easy_recv(curl, buf, sizeof(buf), &nread);
58        }
59

AVAILABILITY

61       Added in 7.18.2.
62

RETURN VALUE

64       On success, returns CURLE_OK, stores the received data into buffer, and
65       the number of bytes it actually read into *n.
66
67       On failure, returns the appropriate error code.
68
69       The  function  may return CURLE_AGAIN. In this case, use your operating
70       system facilities to wait until data can be read, and retry.
71
72       Reading exactly 0 bytes indicates a closed connection.
73
74       If there's no socket available to use from the previous transfer,  this
75       function returns CURLE_UNSUPPORTED_PROTOCOL.
76

SEE ALSO

78       curl_easy_setopt(3),     curl_easy_perform(3),    curl_easy_getinfo(3),
79       curl_easy_send(3)
80
81
82
83libcurl 7.85.0                   May 17, 2022                curl_easy_recv(3)
Impressum