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 chance  is  high
30       that  you  will get your write callback called before this function re‐
31       turns.
32
33       The handle argument identifies the transfer you want to  pause  or  un‐
34       pause.
35
36       A  paused  transfer  is  excluded  from  low speed cancels via the CUR‐
37       LOPT_LOW_SPEED_LIMIT(3) option and unpausing a transfer will reset  the
38       time period required for the low speed limit to be met.
39
40       The  bitmask  argument  is a set of bits that sets the new state of the
41       connection. The following bits can be used:
42
43       CURLPAUSE_RECV
44              Pause receiving data. There will be no  data  received  on  this
45              connection  until this function is called again without this bit
46              set. Thus, the write  callback  (CURLOPT_WRITEFUNCTION(3))  will
47              not be called.
48
49       CURLPAUSE_SEND
50              Pause  sending  data. There will be no data sent on this connec‐
51              tion until this function is called again without this  bit  set.
52              Thus,  the  read  callback (CURLOPT_READFUNCTION(3)) will not be
53              called.
54
55       CURLPAUSE_ALL
56              Convenience define that pauses both directions.
57
58       CURLPAUSE_CONT
59              Convenience define that unpauses both directions.
60

LIMITATIONS

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

MULTIPLEXED

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

EXAMPLE

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

MEMORY USE

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

AVAILABILITY

101       Added in 7.18.0.
102

RETURN VALUE

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