Make --bwlimit take the same size suffixes as the --max-size option

(while keeping it backward compatible). Improve --bwlimit docs.

diff --git a/options.c b/options.c
index 546f63d..b307adf 100644 (file)
--- a/options.c
+++ b/options.c
@@ -301,7 +301,7 @@ static int refused_partial, refused_progress, refused_delete_before;
 static int refused_delete_during;
 static int refused_inplace, refused_no_iconv;
 static BOOL usermap_via_chown, groupmap_via_chown;
-static char *max_size_arg, *min_size_arg;
+static char *bwlimit_arg, *max_size_arg, *min_size_arg;
 static char tmp_partialdir[] = ".~tmp~";
 
 /** Local address to bind.  As a character string because it's
@@ -775,7 +775,7 @@ void usage(enum logcode F)
   rprintf(F,"     --log-file-format=FMT   log updates using the specified FMT\n");
   rprintf(F,"     --password-file=FILE    read daemon-access password from FILE\n");
   rprintf(F,"     --list-only             list the files instead of copying them\n");
-  rprintf(F,"     --bwlimit=KBPS          limit I/O bandwidth; KBytes per second\n");
+  rprintf(F,"     --bwlimit=RATE          limit socket I/O bandwidth\n");
   rprintf(F,"     --write-batch=FILE      write a batched update to FILE\n");
   rprintf(F,"     --only-write-batch=FILE like --write-batch but w/o updating destination\n");
   rprintf(F,"     --read-batch=FILE       read a batched update from FILE\n");
@@ -799,7 +799,7 @@ enum {OPT_VERSION = 1000, OPT_DAEMON, OPT_SENDER, OPT_EXCLUDE, OPT_EXCLUDE_FROM,
       OPT_INCLUDE, OPT_INCLUDE_FROM, OPT_MODIFY_WINDOW, OPT_MIN_SIZE, OPT_CHMOD,
       OPT_READ_BATCH, OPT_WRITE_BATCH, OPT_ONLY_WRITE_BATCH, OPT_MAX_SIZE,
       OPT_NO_D, OPT_APPEND, OPT_NO_ICONV, OPT_INFO, OPT_DEBUG,
-      OPT_USERMAP, OPT_GROUPMAP, OPT_CHOWN,
+      OPT_USERMAP, OPT_GROUPMAP, OPT_CHOWN, OPT_BWLIMIT,
       OPT_SERVER, OPT_REFUSED_BASE = 9000};
 
 static struct poptOption long_options[] = {
@@ -964,7 +964,7 @@ static struct poptOption long_options[] = {
   {"itemize-changes", 'i', POPT_ARG_NONE,   0, 'i', 0, 0 },
   {"no-itemize-changes",0, POPT_ARG_VAL,    &itemize_changes, 0, 0, 0 },
   {"no-i",             0,  POPT_ARG_VAL,    &itemize_changes, 0, 0, 0 },
-  {"bwlimit",          0,  POPT_ARG_INT,    &bwlimit, 0, 0, 0 },
+  {"bwlimit",          0,  POPT_ARG_STRING, &bwlimit_arg, OPT_BWLIMIT, 0, 0 },
   {"no-bwlimit",       0,  POPT_ARG_VAL,    &bwlimit, 0, 0, 0 },
   {"backup",          'b', POPT_ARG_VAL,    &make_backups, 1, 0, 0 },
   {"no-backup",        0,  POPT_ARG_VAL,    &make_backups, 0, 0, 0 },
@@ -1029,7 +1029,7 @@ static void daemon_usage(enum logcode F)
   rprintf(F,"\n");
   rprintf(F,"Usage: rsync --daemon [OPTION]...\n");
   rprintf(F,"     --address=ADDRESS       bind to the specified address\n");
-  rprintf(F,"     --bwlimit=KBPS          limit I/O bandwidth; KBytes per second\n");
+  rprintf(F,"     --bwlimit=RATE          limit socket I/O bandwidth\n");
   rprintf(F,"     --config=FILE           specify alternate rsyncd.conf file\n");
   rprintf(F," -M, --dparam=OVERRIDE       override global daemon config parameter\n");
   rprintf(F,"     --no-detach             do not detach from the parent\n");
@@ -1220,7 +1220,7 @@ static OFF_T parse_size_arg(char **size_arg, char def_suf)
                size += atoi(arg), make_compatible = 1, arg += 2;
        if (*arg)
                return -1;
-       if (size > 0 && make_compatible) {
+       if (size > 0 && make_compatible && def_suf == 'b') {
                /* We convert this manually because we may need %lld precision,
                 * and that's not a portable sprintf() escape. */
                char buf[128], *s = buf + sizeof buf - 1;
@@ -1585,6 +1585,23 @@ int parse_arguments(int *argc_p, const char ***argv_p)
                        }
                        break;
 
+               case OPT_BWLIMIT:
+                       {
+                               OFF_T limit = parse_size_arg(&bwlimit_arg, 'K');
+                               if (limit < 0) {
+                                       snprintf(err_buf, sizeof err_buf,
+                                               "--bwlimit value is invalid: %s\n", bwlimit_arg);
+                                       return 0;
+                               }
+                               bwlimit = (limit + 512) / 1024;
+                               if (limit && !bwlimit) {
+                                       snprintf(err_buf, sizeof err_buf,
+                                               "--bwlimit value is too small: %s\n", bwlimit_arg);
+                                       return 0;
+                               }
+                       }
+                       break;
+
                case OPT_APPEND:
                        if (am_server)
                                append_mode++;

diff --git a/rsync.yo b/rsync.yo
index 8a25a8c..962444b 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -430,7 +430,7 @@ to the detailed description below for a complete description.  verb(
      --log-file-format=FMT   log updates using the specified FMT
      --password-file=FILE    read daemon-access password from FILE
      --list-only             list the files instead of copying them
-     --bwlimit=KBPS          limit I/O bandwidth; KBytes per second
+     --bwlimit=RATE          limit socket I/O bandwidth
      --write-batch=FILE      write a batched update to FILE
      --only-write-batch=FILE like --write-batch but w/o updating dest
      --read-batch=FILE       read a batched update from FILE
@@ -446,7 +446,7 @@ Rsync can also be run as a daemon, in which case the following options are
 accepted: verb(
      --daemon                run as an rsync daemon
      --address=ADDRESS       bind to the specified address
-     --bwlimit=KBPS          limit I/O bandwidth; KBytes per second
+     --bwlimit=RATE          limit socket I/O bandwidth
      --config=FILE           specify alternate rsyncd.conf file
  -M, --dparam=OVERRIDE       override global daemon config parameter
      --no-detach             do not detach from the parent
@@ -2273,13 +2273,27 @@ avoid this problem, either specify the bf(--no-dirs) option (if you don't
 need to expand a directory's content), or turn on recursion and exclude
 the content of subdirectories: bf(-r --exclude='/*/*').
 
-dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
-transfer rate in kilobytes per second. This option is most effective when
-using rsync with large files (several megabytes and up). Due to the nature
-of rsync transfers, blocks of data are sent, then if rsync determines the
-transfer was too fast, it will wait before sending the next data block. The
-result is an average transfer rate equaling the specified limit. A value
-of zero specifies no limit.
+dit(bf(--bwlimit=RATE)) This option allows you to specify the maximum transfer
+rate for the data sent over the socket, specified in units per second.  The
+RATE value can be suffixed with a string to indicate a size multiplier, and may
+be a fractional value (e.g.  "bf(--bwlimit=1.5m)").  If no suffix is specified,
+the value will be assumed to be in units of 1024 bytes (as if "K" or "KiB" had
+been appended).  See the bf(--max-size) option for a description of all the
+available suffixes. A value of zero specifies no limit.
+
+For backward-compatibility reasons, the rate limit will be rounded to the
+nearest KiB unit, so no rate smaller than 1024 bytes per second is possible.
+
+Rsync writes data over the socket in blocks, and this option both limits the
+size of the blocks that rsync writes, and tries to keep the average transfer
+rate at the requested limit.  Some "burstiness" may be seen where rsync writes
+out a block of data and then sleeps to bring the average rate into compliance.
+
+Due to the internal buffering of data, the bf(--progress) option may not be an
+accurate reflection on how fast the data is being sent.  This is because some
+files can show up as being rapidly sent when the data is quickly buffered,
+while other can show up as very slow when the flushing of the output buffer
+occurs.  This may be fixed in a future version.
 
 dit(bf(--write-batch=FILE)) Record a file that can later be applied to
 another identical destination with bf(--read-batch). See the "BATCH MODE"
@@ -2387,11 +2401,10 @@ allows you to specify a specific IP address (or hostname) to bind to.  This
 makes virtual hosting possible in conjunction with the bf(--config) option.
 See also the "address" global option in the rsyncd.conf manpage.
 
-dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
-transfer rate in kilobytes per second for the data the daemon sends.
-The client can still specify a smaller bf(--bwlimit) value, but their
-requested value will be rounded down if they try to exceed it.  See the
-client version of this option (above) for some extra details.
+dit(bf(--bwlimit=RATE)) This option allows you to specify the maximum transfer
+rate for the data the daemon sends over the socket.  The client can still
+specify a smaller bf(--bwlimit) value, but no larger value will be allowed.
+See the client version of this option (above) for some extra details.
 
 dit(bf(--config=FILE)) This specifies an alternate config file than
 the default.  This is only relevant when bf(--daemon) is specified.