libcurl/control.md: new subsection

With five separate pages for "transfer control"

SUMMARY.md

@@ -213,7 +213,12 @@
     * [Sending trailers](libcurl/callbacks/trailers.md)
     * [HSTS](libcurl/callbacks/hsts.md)
     * [Prereq](libcurl/callbacks/prereq.md)
-  * [Stop](libcurl/stop.md)
+  * [Transfer control](libcurl/control.md)
+    * [Stop](libcurl/control/stop.md)
+    * [Stop slow transfers](libcurl/control/stopslow.md)
+    * [Rate limit](libcurl/control/ratelimit.md)
+    * [Progress meter](libcurl/control/meter.md)
+    * [Progress callback](libcurl/control/progress-callback.md)
   * [Cleanup](libcurl/cleanup.md)
   * [Name resolving](libcurl/names.md)
   * [Proxies](libcurl/proxies.md)

libcurl/control.md

@@ -0,0 +1,10 @@
+# Transfer control
+
+An ongoing transfer can be controlled in several ways. The following pages
+describe further details:
+
+* [Stop](control/stop.md)
+* [Stop slow transfers](control/stopslow.md)
+* [Rate limit](control/ratelimit.md)
+* [Progress meter](control/meter.md)
+* [Progress callback](control/progress-callback.md)

libcurl/control/meter.md

@@ -0,0 +1,34 @@
+# Progress meter
+
+libcurl can be made to output a progress meter on stderr. This feature is
+disabled by default and is one of those options with an ones awkward negation
+in the name: `CURLOPT_NOPROGRESS` - set it to `1L` to *disable* progress
+meter. Set it to `0L` to enable it.
+
+Return error to stop transfer
+
+## Example
+
+~~~c
+    #include <stdio.h>
+    #include <curl/curl.h>
+
+    int main(void)
+    {
+      CURL *curl;
+      CURLcode res = CURLE_OK;
+
+      curl = curl_easy_init();
+      if(curl) {
+        /* enable progress meter */
+        curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L);
+
+        curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/");
+
+        res = curl_easy_perform(curl);
+
+        curl_easy_cleanup(curl);
+      }
+
+      return (int)res;
+    }

libcurl/control/progress-callback.md

@@ -0,0 +1,8 @@
+# Progress callback
+
+This callback lets the application keep track of transfer progress. It is also
+called on idle with the easy interface and is a common way to make libcurl
+stop a transfer by returning error.
+
+See the [progress callback](../callbacks/progress.md) section for all the
+details.

libcurl/control/ratelimit.md

@@ -0,0 +1,37 @@
+# Rate limit
+
+Lets an application set a speed cap. Do not transfer data faster than a set
+number of bytes per second. libcurl then attempts to keep the average speed
+below the given threshold over a period of multiple seconds.
+
+There are separate options for receiving (`CURLOPT_MAX_RECV_SPEED_LARGE`) and
+sending (`CURLOPT_MAX_SEND_SPEED_LARGE`).
+
+## Example
+
+~~~c
+    #include <stdio.h>
+    #include <curl/curl.h>
+
+    int main(void)
+    {
+      CURL *curl;
+      CURLcode res = CURLE_OK;
+
+      curl = curl_easy_init();
+      if(curl) {
+        curl_off_t maxrecv = 31415;
+        curl_off_t maxsend = 67954;
+
+        curl_easy_setopt(curl, CURLOPT_MAX_RECV_SPEED_LARGE, maxrecv);
+        curl_easy_setopt(curl, CURLOPT_MAX_SEND_SPEED_LARGE, maxsend);
+
+        curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/");
+
+        res = curl_easy_perform(curl);
+
+        curl_easy_cleanup(curl);
+      }
+
+      return (int)res;
+    }

libcurl/stop.md → libcurl/control/stop.md

@@ -20,7 +20,7 @@ end:
 1. return an error from a callback
 2. set an option that makes the transfer stop after a fixed period of time
 
-Every [callback](callbacks.md) can return an error, and when an error is
+Every [callback](../callbacks.md) can return an error, and when an error is
 returned from one of those functions the entire transfer is stopped. For
 example the read, write or progress callbacks.
 

libcurl/control/stopslow.md

@@ -0,0 +1,33 @@
+# Stop slow transfers
+
+By default, a transfer can stall or transfer data extremely slow for any
+period without that being an error.
+
+Stop a transfer if below **N** bytes/sec during **M** seconds. Set **N** with
+`CURLOPT_LOW_SPEED_LIMIT` and set **M** with `CURLOPT_LOW_SPEED_TIME`.
+
+## Example
+
+    #include <stdio.h>
+    #include <curl/curl.h>
+
+    int main(void)
+    {
+      CURL *curl;
+      CURLcode res = CURLE_OK;
+
+      curl = curl_easy_init();
+      if(curl) {
+        /* abort if slower than 30 bytes/sec during 60 seconds */
+        curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L);
+        curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L);
+
+        curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/");
+
+        res = curl_easy_perform(curl);
+
+        curl_easy_cleanup(curl);
+      }
+
+      return (int)res;
+    }