Introducing curl_easy_pause() and new magic return codes for both the read

                                  Changelog

Daniel S (8 Jan 2008)

- Introducing curl_easy_pause() and new magic return codes for both the read

  and the write callbacks that now can make a connection's reading and/or

  writing get paused.

Daniel S (6 Jan 2008)

- Jeff Johnson filed bug report #1863171

  (http://curl.haxx.se/bug/view.cgi?id=1863171) where he pointed out that

Curl and libcurl 7.17.2

Curl and libcurl 7.18.0

 Public curl releases:         103

 Command line options:         125

 curl_easy_setopt() options:   148

 Public functions in libcurl:  55

 Public functions in libcurl:  56

 Public web site mirrors:      42

 Known libcurl bindings:       36

 Contributors:                 597

   keep-alive enabled by default

 o --socks4a added (proxy type CURLPROXY_SOCKS4A for libcurl)

 o --socks5-hostname added (CURLPROXY_SOCKS5_HOSTNAME for libcurl)

 o curl_easy_pause() added

This release includes the following bugfixes:

.\" * $Id$

.\" **************************************************************************

.\"

.TH curl 1 "5 Jan 2008" "Curl 7.17.2" "Curl Manual"

.TH curl 1 "5 Jan 2008" "Curl 7.18.0" "Curl Manual"

.SH NAME

curl \- transfer a URL

.SH SYNOPSIS

data. As described in \fI-d/--data\fP.

.IP "--data-urlencode <data>"

(HTTP) This posts data, similar to the other --data options with the exception

that this performs URL encoding. (Added in 7.17.2)

that this performs URL encoding. (Added in 7.18.0)

To be CGI compliant, the <data> part should begin with a \fIname\fP followed

by a separator and a content specification. The <data> part can be passed to

If this option is used several times, the last one will be used.

.IP "--socks4a <host[:port]>"

Use the specified SOCKS4a proxy. If the port number is not specified, it is

assumed at port 1080. (Added in 7.17.2)

assumed at port 1080. (Added in 7.18.0)

This option overrides any previous use of \fI-x/--proxy\fP, as they are

mutually exclusive.

.IP "--socks5-hostname <host[:port]>"

Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If

the port number is not specified, it is assumed at port 1080. (Added in

7.17.2)

7.18.0)

This option overrides any previous use of \fI-x/--proxy\fP, as they are

mutually exclusive.

 curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3	 \

 libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3		 \

 curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3		 \

 curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3

 curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3		 \

 curl_easy_pause.3

HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html		  \

 curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html	  \

 curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \

 curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html	  \

 curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html	  \

 curl_formget.html curl_multi_assign.html

 curl_formget.html curl_multi_assign.html curl_easy_pause.html

PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \

 curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf	  \

 curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf	  \

 curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf	  \

 curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf	  \

 curl_formget.pdf curl_multi_assign.pdf

 curl_formget.pdf curl_multi_assign.pdf curl_easy_pause.pdf

CLEANFILES = $(HTMLPAGES) $(PDFPAGES)

.\" $Id$

.\"

.TH curl_easy_pause 3 "17 Dec 2007" "libcurl 7.18.0" "libcurl Manual"

.SH NAME

curl_easy_pause - pause and unpause a connection

.SH SYNOPSIS

.B #include <curl/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 made to pause 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).

NOTE: while it may feel tempting, take care and notice that you cannot call

this function from another thread.

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 conneciton until

this function is called again without this bit set. Thus, the write callback

(\fICURLOPT_WRITEFUNCTION\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\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 AVAILABILITY

This function was added in libcurl 7.18.0. Before this version, there was no

explicit support for pausing transfers.

.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

automatially 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)"