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,
12       size_t *n);
13

DESCRIPTION

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

AVAILABILITY

48       Added in 7.18.2.
49

RETURN VALUE

51       On success, returns CURLE_OK, stores the received data into buffer, and
52       the number of bytes it actually read into *n.
53
54       On failure, returns the appropriate error code.
55
56       The function may return CURLE_AGAIN. In this case, use  your  operating
57       system facilities to wait until data can be read, and retry.
58
59       Reading exactly 0 bytes indicates a closed connection.
60
61       If  there's no socket available to use from the previous transfer, this
62       function returns CURLE_UNSUPPORTED_PROTOCOL.
63

EXAMPLE

65       See sendrecv.c in docs/examples directory for usage example.
66

SEE ALSO

68       curl_easy_setopt(3),    curl_easy_perform(3),     curl_easy_getinfo(3),
69       curl_easy_send(3)
70
71
72
73libcurl 7.61.1                 December 18, 2016             curl_easy_recv(3)
Impressum