curl_easy_setopt.3: expand the PROGRESSFUNCTION section

Explain the callback and its arguments better and with more descriptive
text.

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index bc81ac8..742f3a1 100644 (file)
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -346,11 +346,24 @@ Pass a pointer to a function that matches the following prototype: \fBint
 function(void *clientp, double dltotal, double dlnow, double ultotal, double
 ulnow); \fP. This function gets called by libcurl instead of its internal
 equivalent with a frequent interval during operation (roughly once per second
-or sooner) no matter if data is being transferred or not.  Unknown/unused
-argument values passed to the callback will be set to zero (like if you only
-download data, the upload size will remain 0). Returning a non-zero value from
-this callback will cause libcurl to abort the transfer and return
-\fICURLE_ABORTED_BY_CALLBACK\fP.
+or sooner) no matter if data is being transferred or not.
+
+\fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA\fP, it is not
+actually used by libcurl but is only passed along from the application to the
+callback.
+
+The callback gets told how much data libcurl will transfer and has
+transferred, in number of bytes. \fIdltotal\fP is the total number of bytes
+libcurl expects to download in this transfer. \fIdlnow\fP is the number of
+bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
+expects to upload in this transfer. \fIulnow\fP is the number of bytes
+uploaded so far.
+
+Unknown/unused argument values passed to the callback will be set to zero
+(like if you only download data, the upload size will remain 0).
+
+Returning a non-zero value from this callback will cause libcurl to abort the
+transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
 
 If you transfer data with the multi interface, this function will not be
 called during periods of idleness unless you call the appropriate libcurl