(Previous options of the week)
Today we take a closer look at one of the real vintage curl options. It was added already in early 1999. -Y for short, --speed-limit is the long version. This option needs an additional argument: <speed>. Let me describe exactly what that speed is and how it works below.
Slow or stale transfers
Very early on in curl’s lifetime, it became obvious to us that lots of times when you use curl in order to do an Internet transfer, that transfer could sometimes take a long time. Occasionally even ridiculously long times and it could seem that the transfers just stalled without any hope of resurrecting and completing its mission.
How do you tell curl to abandon such lost-hope transfers? The options we provide for timeouts provide one answer. But since the transfer speeds can vary greatly from time to time and machine to machine, you have to use a timeout value that uses an insane margin, which for the cases when everything flies fast turns out annoying.
We needed another way to detect and abort these stale transfers. Enter speed limit.
Lower than speed-limit bytes per second during speed-time
The --speed-limit <speed> you tell curl is the transfer speed threshold below which you think the transfer is untypically slow, specified as bytes per second. If you have a really fast Internet, you might for example think that a transfer that is below 1000 bytes/second is a sign of something not being right.
But just measuring a the transfer speed to be below that special threshold in a single snapshot is not a strong enough signal for curl to act on it. The speed also needs to be measure below that threshold during --limit-time <seconds>. If the transfer speed just incidentally sometimes and very quickly drops below the threshold (bad wifi?) that’s not a reason for concern. The default limit time (when --limit-speed is used without --limit-time set) is 30. The transfer speed needs to be measured below the threshold for that many consecutive seconds (and it samples once per second).
If curl deems that your transfer speed was too slow during the given period, it will break the transfer and return 28. Timeout.
These two options are entirely protocol independent and work for all transfers using any of the protocols curl supports.
Examples
Tell curl to give up the transfer if slower than 1000 bytes per second during 20 seconds:
curl --speed-limit 1000 --speed-time 20 https://example.com
Tell curl to give up the transfer if slower than 100000 bytes per second during 60 seconds:
curl --speed-limit 100000 --speed-time 60 https://example.com
It also works the same for uploads. If the speed is below 2000 bytes per second during 45 seconds, abort:
curl --speed-limit 2000 --speed-time 45 ftp://example.com/upload/ -T sendaway.txt
Related options
--max-time and --connect-timeout are options with similar functionality and purpose, and you can indeed in many cases add those as well.
