Issue 583 (#586)

* s/bandwidth/bitrate/ in user-facing places.  Towards #583.

iperf3 has long misused terminology; bandwidth is a measure of
capacity.  iperf3 measures bitrate or throughput.  We standardize
on "bitrate" because it begins with the same letter as "bandwidth"
(to match the -b command-line option).

User-facing output mentioning "bandwidth" now uses "bitrate".
The long command-line option for -b (--bandwidth) is now --bitrate
(--bandwidth is transparently accepted for backward compatibility).
A few places in documentation that talk about bandwidth as a
measured value have been reworded to use bitrate or throughput.

There are a number of places in code where variables are still
called "bandwidth".  We leave these alone for now.

A mention of "bandwidth" in the test parameters JSON also needs
to remain unchanged to avoid breaking compatibility.  However,
the test results JSON never used the term "bandwidth" in
the first place.

* s/bandwidth/throughput in one place in RPM description.  Towards #583.

README.md

@@ -7,7 +7,7 @@ Summary
 iperf is a tool for active measurements of the maximum achievable
 bandwidth on IP networks.  It supports tuning of various parameters
 related to timing, protocols, and buffers.  For each test it reports
-the bandwidth, loss, and other parameters.
+the measured throughput / bitrate, loss, and other parameters.
 
 This version, sometimes referred to as iperf3, is a redesign of an
 original version developed at NLANR/DAST.  iperf3 is a new

docs/index.rst

@@ -9,7 +9,7 @@ iperf3
 iperf is a tool for active measurements of the maximum achievable
 bandwidth on IP networks.  It supports tuning of various parameters
 related to timing, protocols, and buffers.  For each test it reports
-the bandwidth, loss, and other parameters.
+the measured throughput, loss, and other parameters.
 
 This version, sometimes referred to as iperf3, is a redesign of an
 original version developed at NLANR / DAST.  iperf3 is a new

iperf3.spec.in

@@ -19,7 +19,7 @@ BuildRequires: openssl-devel
 iperf3 is a tool for active measurements of the maximum achievable
 bandwidth between two IP hosts.  It supports tuning of various
 parameters related to timing, protocols, and buffers.  For each test,
-it reports the bandwidth, loss, and other parameters.
+it reports the throughput, loss, and other parameters.
 
 %package        devel
 Summary:        Development files for %{name}

src/iperf3.1

@@ -118,24 +118,27 @@ connection establishment.
 Providing a shorter value may speed up detection of a down iperf3
 server.
 .TP
-.BR -b ", " --bandwidth " \fIn\fR[KM]"
-set target bandwidth to \fIn\fR bits/sec (default 1 Mbit/sec for UDP, unlimited for TCP).
-If there are multiple streams (\-P flag), the bandwidth limit is applied 
+.BR -b ", " --bitrate " \fIn\fR[KM]"
+set target bitrate to \fIn\fR bits/sec (default 1 Mbit/sec for UDP,
+unlimited for TCP/SCTP).
+If there are multiple streams (\-P flag), the throughput limit is applied
 separately to each stream.
-You can also add a '/' and a number to the bandwidth specifier.
+You can also add a '/' and a number to the bitrate specifier.
 This is called "burst mode".
 It will send the given number of packets without pausing, even if that
-temporarily exceeds the specified bandwidth limit.
-Setting the target bandwidth to 0 will disable bandwidth limits
+temporarily exceeds the specified throughput limit.
+Setting the target bitrate to 0 will disable bitrate limits
 (particularly useful for UDP tests).
-This bandwidth limit is implemented internally inside iperf3, and is
+This throughput limit is implemented internally inside iperf3, and is
 available on all platforms.
 Compare with the \--fq-rate flag.
+This option replaces the \--bandwidth flag, which is now deprecated
+but (at least for now) still accepted.
 .TP
 .BR --pacing-timer " \fIn\fR[KMG]"
 set pacing timer interval in microseconds (default 1000 microseconds,
 or 1 ms).
-This controls iperf3's internal pacing timer for the -b/--bandwidth
+This controls iperf3's internal pacing timer for the \-b/\--bitrate
 option.
 The timer fires at the interval set by this parameter.
 Smaller values of the pacing timer parameter smooth out the traffic
@@ -146,7 +149,7 @@ more frequent timer processing.
 Set a rate to be used with fair-queueing based socket-level pacing,
 in bits per second.
 This pacing (if specified) will be in addition to any pacing due to
-iperf3's internal bandwidth pacing (\-b flag), and both can be
+iperf3's internal throughput pacing (\-b/\--bitrate flag), and both can be
 specified for the same test.
 Only available on platforms supporting the
 \fCSO_MAX_PACING_RATE\fR socket option (currently only Linux).

src/iperf_api.c

@@ -633,6 +633,7 @@ iperf_parse_arguments(struct iperf_test *test, int argc, char **argv)
         {"server", no_argument, NULL, 's'},
         {"client", required_argument, NULL, 'c'},
         {"udp", no_argument, NULL, 'u'},
+        {"bitrate", required_argument, NULL, 'b'},
         {"bandwidth", required_argument, NULL, 'b'},
         {"time", required_argument, NULL, 't'},
         {"bytes", required_argument, NULL, 'n'},

src/iperf_locale.c

@@ -99,7 +99,7 @@ const char usage_longstr[] = "Usage: iperf3 [-s|-c host] [options]\n"
                            "Server or Client:\n"
                            "  -p, --port      #         server port to listen on/connect to\n"
                            "  -f, --format   [kmgtKMGT] format to report: Kbits, Mbits, Gbits, Tbits\n"
-                           "  -i, --interval  #         seconds between periodic bandwidth reports\n"
+                           "  -i, --interval  #         seconds between periodic throughput reports\n"
                            "  -F, --file name           xmit/recv the specified file\n"
 #if defined(HAVE_CPU_AFFINITY)
                            "  -A, --affinity n/n,m      set CPU affinity\n"
@@ -132,7 +132,7 @@ const char usage_longstr[] = "Usage: iperf3 [-s|-c host] [options]\n"
 #endif /* HAVE_SCTP */
                            "  -u, --udp                 use UDP rather than TCP\n"
                            "  --connect-timeout #       timeout for control connection setup (ms)\n"
-                           "  -b, --bandwidth #[KMG][/#] target bandwidth in bits/sec (0 for unlimited)\n"
+                           "  -b, --bitrate #[KMG][/#]  target bitrate in bits/sec (0 for unlimited)\n"
                            "                            (default %d Mbit/sec for UDP, unlimited for TCP)\n"
                            "                            (optional slash and packet count for burst mode)\n"
 			   "  --pacing-timer #[KMG]     set the timing for pacing, in microseconds (default 1000)\n"
@@ -302,19 +302,19 @@ const char report_read_length_times[] =
 "[%3d] %5d bytes read %5d times (%.3g%%)\n";
 
 const char report_bw_header[] =
-"[ ID] Interval           Transfer     Bandwidth\n";
+"[ ID] Interval           Transfer     Bitrate\n";
 
 const char report_bw_retrans_header[] =
-"[ ID] Interval           Transfer     Bandwidth       Retr\n";
+"[ ID] Interval           Transfer     Bitrate         Retr\n";
 
 const char report_bw_retrans_cwnd_header[] =
-"[ ID] Interval           Transfer     Bandwidth       Retr  Cwnd\n";
+"[ ID] Interval           Transfer     Bitrate         Retr  Cwnd\n";
 
 const char report_bw_udp_header[] =
-"[ ID] Interval           Transfer     Bandwidth       Jitter    Lost/Total Datagrams\n";
+"[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams\n";
 
 const char report_bw_udp_sender_header[] =
-"[ ID] Interval           Transfer     Bandwidth       Total Datagrams\n";
+"[ ID] Interval           Transfer     Bitrate         Total Datagrams\n";
 
 const char report_bw_format[] =
 "[%3d] %6.2f-%-6.2f sec  %ss  %ss/sec                  %s\n";