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