btrfs-progs: docs: update scrub manual page

Move ionice options, add example output of status with explanation.

Issue: #200
Signed-off-by: David Sterba <dsterba@suse.com>

Documentation/btrfs-scrub.rst

@@ -23,7 +23,7 @@ cancel <path>|<device>
         The progress is saved in the status file so **btrfs scrub resume** can
         continue from the last position.
 
-resume [-BdqrR] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>
+resume [-BdqrR] <path>|<device>
         Resume a cancelled or interrupted scrub on the filesystem identified by
         *path* or on a given *device*. The starting point is read from the
         status file if it exists.
@@ -34,19 +34,15 @@ resume [-BdqrR] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>
 
         see **scrub start**.
 
-start [-BdqrRf] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>
+start [-BdrRf] <path>|<device>
         Start a scrub on all devices of the mounted filesystem identified by
         *path* or on a single *device*. If a scrub is already running, the new
         one will not start. A device of an unmounted filesystem cannot be
         scrubbed this way.
 
         Without options, scrub is started as a background process. The
-        automatic repairs of damaged copies is performed by default for block
+        automatic repairs of damaged copies are performed by default for block
-        group profiles with redundancy.
+        group profiles with redundancy. No-repair can be enabled by option *-r*.
-
-        The default IO priority of scrub is the idle class. The priority can be
-        configured similar to the ``ionice(1)`` syntax using *-c* and *-n*
-        options.  Note that not all IO schedulers honor the ionice settings.
 
         ``Options``
 
@@ -60,15 +56,21 @@ start [-BdqrRf] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>
                 be run on a read-only filesystem
         -R
                 raw print mode, print full data instead of summary
-        -c <ioprio_class>
-                set IO priority class (see ``ionice(1)`` manpage)
-        -n <ioprio_classdata>
-                set IO priority classdata (see ``ionice(1)`` manpage)
         -f
                 force starting new scrub even if a scrub is already running,
                 this can useful when scrub status file is damaged and reports a
                 running scrub although it is not, but should not normally be
                 necessary
+
+        ``Deprecated options``
+
+        -c <ioprio_class>
+                set IO priority class (see ``ionice(1)`` manpage) if the IO
+                scheduler configured for the device supports ionice. This is
+                not supported byg BFQ or Kyber but is *not* supported by
+                mq-deadline.
+        -n <ioprio_classdata>
+                set IO priority classdata (see ``ionice(1)`` manpage)
         -q
                 (deprecated) alias for global *-q* option
 
@@ -104,6 +106,44 @@ status [options] <path>|<device>
         --tbytes
                 show sizes in TiB, or TB with --si
 
+        A status on a filesystem without any error looks like the following:
+
+        .. code-block:: none
+
+           # btrfs scrub start /
+           # btrfs scrub status /
+           UUID:             76fac721-2294-4f89-a1af-620cde7a1980
+           Scrub started:    Wed Apr 10 12:34:56 2023
+           Status:           running
+           Duration:         0:00:05
+           Time left:        0:00:05
+           ETA:              Wed Apr 10 12:35:01 2023
+           Total to scrub:   28.32GiB
+           Bytes scrubbed:   13.76GiB  (48.59%)
+           Rate:             2.75GiB/s
+           Error summary:    no errors found
+
+        With some errors found:
+
+        .. code-block:: none
+
+           Error summary:    csum=72
+             Corrected:      2
+             Uncorrectable:  72
+             Unverified:     0
+
+       *  *Corrected* -- number of bad blocks that were repaired from another copy
+       *  *Uncorrectable* -- errors detected at read time but not possible to repair from other copy
+       *  *Unverified* -- transient errors, first read failed but a retry
+          succeeded, may be affected by lower layers that group or split IO requests
+       *  *Error summary* -- followed by a more detailed list of errors found
+
+          *  *csum* -- checksum mismatch
+          *  *super* -- super block errors, unless the error is fixed
+             immediately, the next commit will overwrite superblock
+          *  *verify* -- metadata block header errors
+          *  *read* -- blocks can't be read due to IO errors
+
 EXIT STATUS
 -----------
 
@@ -126,5 +166,4 @@ AVAILABILITY
 SEE ALSO
 --------
 
-:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
+:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
-``ionice(1)``