curl_easy_pause(3)

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

NAME

6       curl_easy_pause - pause and unpause a connection
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLcode curl_easy_pause(CURL *handle, int bitmask);
12

DESCRIPTION

14       Using  this  function,  you can explicitly mark a running connection to
15       get paused, and you  can  unpause  a  connection  that  was  previously
16       paused.
17
18       A  connection  can  be  paused by using this function or by letting the
19       read or the  write  callbacks  return  the  proper  magic  return  code
20       (CURL_READFUNC_PAUSE  and  CURL_WRITEFUNC_PAUSE). A write callback that
21       returns pause signals to the library that it could not take care of any
22       data at all, and that data will then be delivered again to the callback
23       when the transfer is unpaused.
24
25       While it may feel tempting, take care and notice that you  cannot  call
26       this function from another thread. To unpause, you may for example call
27       it from the progress callback (CURLOPT_PROGRESSFUNCTION(3)).
28
29       When this function is called to unpause receiving, the  write  callback
30       might  get  called  before this function returns to deliver cached con‐
31       tent. When libcurl delivers such cached data to the write callback,  it
32       will  be delivered as fast as possible, which may overstep the boundary
33       set in CURLOPT_MAX_RECV_SPEED_LARGE(3) etc.
34
35       The handle argument identifies the transfer you want to  pause  or  un‐
36       pause.
37
38       A  paused  transfer  is  excluded  from  low speed cancels via the CUR‐
39       LOPT_LOW_SPEED_LIMIT(3) option and unpausing a transfer will reset  the
40       time period required for the low speed limit to be met.
41
42       The  bitmask  argument  is a set of bits that sets the new state of the
43       connection. The following bits can be used:
44
45       CURLPAUSE_RECV
46              Pause receiving data. There will be no  data  received  on  this
47              connection  until this function is called again without this bit
48              set. Thus, the write  callback  (CURLOPT_WRITEFUNCTION(3))  will
49              not be called.
50
51       CURLPAUSE_SEND
52              Pause  sending  data. There will be no data sent on this connec‐
53              tion until this function is called again without this  bit  set.
54              Thus,  the  read  callback (CURLOPT_READFUNCTION(3)) will not be
55              called.
56
57       CURLPAUSE_ALL
58              Convenience define that pauses both directions.
59
60       CURLPAUSE_CONT
61              Convenience define that unpauses both directions.
62

LIMITATIONS

64       The pausing of transfers does not work with protocols that work without
65       network connectivity, like FILE://. Trying to pause such a transfer, in
66       any direction, will cause problems in the worst case or an error in the
67       best case.
68

MULTIPLEXED

70       When  a connection is used multiplexed, like for HTTP/2, and one of the
71       transfers over the connection is paused and the others  continue  flow‐
72       ing,  libcurl  might end up buffering contents for the paused transfer.
73       It has to do this because it needs to drain the socket  for  the  other
74       transfers and the already announced window size for the paused transfer
75       will allow the server to continue sending data up to that  window  size
76       amount.  By default, libcurl announces a 32 megabyte window size, which
77       thus can make libcurl end up buffering 32 megabyte of data for a paused
78       stream.
79
80       When  such a paused stream is unpaused again, any buffered data will be
81       delivered first.
82

EXAMPLE

84       /* pause a transfer in both directions */
85       curl_easy_pause(curl, CURL_READFUNC_PAUSE | CURL_WRITEFUNC_PAUSE);
86

MEMORY USE

88       When pausing a read by returning the magic return  code  from  a  write
89       callback,  the read data is already in libcurl's internal buffers so it
90       will have to keep it in an allocated  buffer  until  the  receiving  is
91       again unpaused using this function.
92
93       If  the  downloaded data is compressed and is asked to get uncompressed
94       automatically on download, libcurl will continue to uncompress the  en‐
95       tire downloaded chunk and it will cache the data uncompressed. This has
96       the side- effect that if you download something that  is  compressed  a
97       lot,  it  can  result in a large data amount needing to be allocated to
98       save the data during the pause. This said, you should probably consider
99       not  using paused receiving if you allow libcurl to uncompress data au‐
100       tomatically.
101

AVAILABILITY

103       Added in 7.18.0.
104

RETURN VALUE

106       CURLE_OK (zero) means that the option was set properly, and a  non-zero
107       return code means something wrong occurred after the new state was set.
108       See the libcurl-errors(3) man page for the full list with descriptions.
109