1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_easy_pause 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_cleanup (3) 9 - curl_easy_reset (3) 10Protocol: 11 - All 12--- 13 14# NAME 15 16curl_easy_pause - pause and unpause a connection 17 18# SYNOPSIS 19 20~~~c 21#include <curl/curl.h> 22 23CURLcode curl_easy_pause(CURL *handle, int bitmask ); 24~~~ 25 26# DESCRIPTION 27 28Using this function, you can explicitly mark a running connection to get 29paused, and you can unpause a connection that was previously paused. Unlike 30most other libcurl functions, curl_easy_pause(3) can be used from within 31callbacks. 32 33A connection can be paused by using this function or by letting the read or 34the write callbacks return the proper magic return code 35(*CURL_READFUNC_PAUSE* and *CURL_WRITEFUNC_PAUSE*). A write callback 36that returns pause signals to the library that it could not take care of any 37data at all, and that data is then delivered again to the callback when the 38transfer is unpaused. 39 40While it may feel tempting, take care and notice that you cannot call this 41function from another thread. To unpause, you may for example call it from the 42progress callback (CURLOPT_PROGRESSFUNCTION(3)). 43 44When this function is called to unpause receiving, the write callback might 45get called before this function returns to deliver cached content. When 46libcurl delivers such cached data to the write callback, it is delivered as 47fast as possible, which may overstep the boundary set in 48CURLOPT_MAX_RECV_SPEED_LARGE(3) etc. 49 50The **handle** argument identifies the transfer you want to pause or 51unpause. 52 53A paused transfer is excluded from low speed cancels via the 54CURLOPT_LOW_SPEED_LIMIT(3) option and unpausing a transfer resets the 55time period required for the low speed limit to be met. 56 57The **bitmask** argument is a set of bits that sets the new state of the 58connection. The following bits can be used: 59 60## CURLPAUSE_RECV 61 62Pause receiving data. There is no data received on this connection until this 63function is called again without this bit set. Thus, the write callback 64(CURLOPT_WRITEFUNCTION(3)) is not called. 65 66## CURLPAUSE_SEND 67 68Pause sending data. There is no data sent on this connection until this 69function is called again without this bit set. Thus, the read callback 70(CURLOPT_READFUNCTION(3)) is not called. 71 72## CURLPAUSE_ALL 73 74Convenience define that pauses both directions. 75 76## CURLPAUSE_CONT 77 78Convenience define that unpauses both directions. 79 80# LIMITATIONS 81 82The pausing of transfers does not work with protocols that work without 83network connectivity, like FILE://. Trying to pause such a transfer, in any 84direction, might cause problems or error. 85 86# MULTIPLEXED 87 88When a connection is used multiplexed, like for HTTP/2, and one of the 89transfers over the connection is paused and the others continue flowing, 90libcurl might end up buffering contents for the paused transfer. It has to do 91this because it needs to drain the socket for the other transfers and the 92already announced window size for the paused transfer allows the server to 93continue sending data up to that window size amount. By default, libcurl 94announces a 32 megabyte window size, which thus can make libcurl end up 95buffering 32 megabyte of data for a paused stream. 96 97When such a paused stream is unpaused again, any buffered data is delivered 98first. 99 100# EXAMPLE 101 102~~~c 103int main(void) 104{ 105 CURL *curl = curl_easy_init(); 106 if(curl) { 107 /* pause a transfer in both directions */ 108 curl_easy_pause(curl, CURL_READFUNC_PAUSE | CURL_WRITEFUNC_PAUSE); 109 110 } 111} 112~~~ 113 114# MEMORY USE 115 116When pausing a download transfer by returning the magic return code from a 117write callback, the read data is already in libcurl's internal buffers so it 118has to keep it in an allocated buffer until the receiving is again unpaused 119using this function. 120 121If the downloaded data is compressed and is asked to get uncompressed 122automatically on download, libcurl continues to uncompress the entire 123downloaded chunk and it caches the data uncompressed. This has the side- 124effect that if you download something that is compressed a lot, it can result 125in a large data amount needing to be allocated to save the data during the 126pause. Consider not using paused receiving if you allow libcurl to uncompress 127data automatically. 128 129If the download is done with HTTP/2 or HTTP/3, there is up to a stream window 130size worth of data that curl cannot stop but instead needs to cache while the 131transfer is paused. This means that if a window size of 64 MB is used, libcurl 132might end up having to cache 64 MB of data. 133 134# AVAILABILITY 135 136Added in 7.18.0. 137 138# RETURN VALUE 139 140CURLE_OK (zero) means that the option was set properly, and a non-zero return 141code means something wrong occurred after the new state was set. See the 142libcurl-errors(3) man page for the full list with descriptions. 143
