diff options
Diffstat (limited to 'docs/libcurl/gnurl_easy_pause.3')
| -rw-r--r-- | docs/libcurl/gnurl_easy_pause.3 | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/docs/libcurl/gnurl_easy_pause.3 b/docs/libcurl/gnurl_easy_pause.3 new file mode 100644 index 000000000..6d223f2dd --- /dev/null +++ b/docs/libcurl/gnurl_easy_pause.3 @@ -0,0 +1,103 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH gnurl_easy_pause 3 "17 Dec 2007" "libcurl 7.18.0" "libgnurl Manual" +.SH NAME +curl_easy_pause - pause and unpause a connection +.SH SYNOPSIS +.B #include <gnurl/curl.h> + +.BI "CURLcode curl_easy_pause(CURL *"handle ", int "bitmask " );" + +.SH DESCRIPTION +Using this function, you can explicitly mark a running connection to get +paused, and you can unpause a connection that was previously paused. + +A connection can be paused by using this function or by letting the read or +the write callbacks return the proper magic return code +(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback +that returns pause signals to the library that it couldn't take care of any +data at all, and that data will then be delivered again to the callback when +the writing is later unpaused. + +While it may feel tempting, take care and notice that you cannot call this +function from another thread. To unpause, you may for example call it from the +progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP), which gets called at +least once per second, even if the connection is paused. + +When this function is called to unpause reading, the chance is high that you +will get your write callback called before this function returns. + +The \fBhandle\fP argument is of course identifying the handle that operates on +the connection you want to pause or unpause. + +The \fBbitmask\fP argument is a set of bits that sets the new state of the +connection. The following bits can be used: +.IP CURLPAUSE_RECV +Pause receiving data. There will be no data received on this connection until +this function is called again without this bit set. Thus, the write callback +(\fICURLOPT_WRITEFUNCTION(3)\fP) won't be called. +.IP CURLPAUSE_SEND +Pause sending data. There will be no data sent on this connection until this +function is called again without this bit set. Thus, the read callback +(\fICURLOPT_READFUNCTION(3)\fP) won't be called. +.IP CURLPAUSE_ALL +Convenience define that pauses both directions. +.IP CURLPAUSE_CONT +Convenience define that unpauses both directions. +.SH RETURN VALUE +CURLE_OK (zero) means that the option was set properly, and a non-zero return +code means something wrong occurred after the new state was set. See the +\fIlibcurl-errors(3)\fP man page for the full list with descriptions. +.SH LIMITATIONS +The pausing of transfers does not work with protocols that work without +network connectivity, like FILE://. Trying to pause such a transfer, in any +direction, will cause problems in the worst case or an error in the best case. +.SH AVAILABILITY +This function was added in libcurl 7.18.0. Before this version, there was no +explicit support for pausing transfers. +.SH "USAGE WITH THE MULTI-SOCKET INTERFACE" +Before libcurl 7.32.0, when a specific handle was unpaused with this function, +there was no particular forced rechecking or similar of the socket's state, +which made the continuation of the transfer get delayed until next +multi-socket call invoke or even longer. Alternatively, the user could +forcibly call for example \fIcurl_multi_socket_all(3)\fP - with a rather hefty +performance penalty. + +Starting in libcurl 7.32.0, unpausing a transfer will schedule a timeout +trigger for that handle 1 millisecond into the future, so that a +curl_multi_socket_action( ... CURL_SOCKET_TIMEOUT) can be used immediately +afterwards to get the transfer going again as desired. +.SH "MEMORY USE" +When pausing a read by returning the magic return code from a write callback, +the read data is already in libcurl's internal buffers so it'll have to keep +it in an allocated buffer until the reading is again unpaused using this +function. + +If the downloaded data is compressed and is asked to get uncompressed +automatically on download, libcurl will continue to uncompress the entire +downloaded chunk and it will cache the data uncompressed. This has the side- +effect that if you download something that is compressed a lot, it can result +in a very large data amount needing to be allocated to save the data during +the pause. This said, you should probably consider not using paused reading if +you allow libcurl to uncompress data automatically. +.SH "SEE ALSO" +.BR curl_easy_cleanup "(3), " curl_easy_reset "(3)" |