curl_easy_setopt.3: clarify CURLOPT_PROGRESSFUNCTION frequency

Make it clearer that the CURLOPT_PROGRESSFUNCTION callback will be
called more frequently than once per second when things are happening.

1 files changed, 12 insertions, 6 deletions

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 3b804a1f6..e5ca09f4b 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -342,11 +342,15 @@ argument in the closesocket callback set with
 The default value of this parameter is unspecified.
 (Option added in 7.21.7)
 .IP CURLOPT_PROGRESSFUNCTION
-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.
+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. While data is being transferred it will be called very
+frequently, and during slow periods like when nothing is being transferred it
+can slow down to about one call per second.
 
 \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
@@ -360,7 +364,9 @@ 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).
+(like if you only download data, the upload size will remain 0). Many times
+the callback will be called one or more times first, before it knows the data
+sizes so a program must be made to handle that.
 
 Returning a non-zero value from this callback will cause libcurl to abort the
 transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.