[PATCH] Make the libaio fsync fallback really work

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 57c0730b13d0ef7ef8b257a97ff56c1181aa53cf..38f5dcea06670849809efb94af69ea7eebee6b1b 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -179,7 +179,10 @@ siint      SI integer. A whole number value, which may contain a postfix
 bool   Boolean. Usually parsed as an integer, however only defined for
        true and false (1 and 0).
 irange Integer range with postfix. Allows value range to be given, such
-       as 1024-4096. Also see siint.
+       as 1024-4096. A colon may also be used as the seperator, eg
+       1k:4k. If the option allows two sets of ranges, they can be
+       specified with a ',' or '/' delimiter: 1k-4k/8k-32k. Also see
+       siint.
 
 With the above in mind, here follows the complete list of fio job
 parameters.
@@ -190,13 +193,19 @@ name=str  ASCII name of the job. This may be used to override the
                special purpose of also signaling the start of a new
                job.
 
+description=str        Text description of the job. Doesn't do anything except
+               dump this text description when this job is run. It's
+               not parsed.
+
 directory=str  Prefix filenames with this directory. Used to places files
                in a different location than "./".
 
 filename=str   Fio normally makes up a filename based on the job name,
                thread number, and file number. If you want to share
                files between threads in a job or several jobs, specify
-               a filename for each of them to override the default.
+               a filename for each of them to override the default. If
+               the ioengine used is 'net', the filename is the host and
+               port to connect to in the format of =host:port.
 
 rw=str         Type of io pattern. Accepted values are:
 
@@ -271,13 +280,22 @@ ioengine=str      Defines how the job issues io to the file. The following
                                to. This is mainly used to exercise fio
                                itself and for debugging/testing purposes.
 
+                       net     Transfer over the network to given host:port.
+                               'filename' must be set appropriately to
+                               filename=host:port regardless of send
+                               or receive, if the latter only the port
+                               argument is used.
+
 iodepth=int    This defines how many io units to keep in flight against
                the file. The default is 1 for each file defined in this
                job, can be overridden with a larger value for higher
                concurrency.
 
 direct=bool    If value is true, use non-buffered io. This is usually
-               O_DIRECT. Defaults to true.
+               O_DIRECT.
+
+buffered=bool  If value is true, use buffered io. This is the opposite
+               of the 'direct' option. Defaults to true.
 
 offset=siint   Start io at the given offset in the file. The data before
                the given offset will not be touched. This effectively
@@ -417,8 +435,9 @@ create_serialize=bool       If true, serialize the file creating for the jobs.
 create_fsync=bool      fsync the data file after creation. This is the
                        default.
 
-unlink=bool    Unlink the job files when done. fio defaults to doing this,
-               if it created the file itself.
+unlink=bool    Unlink the job files when done. Not the default, as repeated
+               runs of that job would then waste time recreating the fileset
+               again and again.
 
 loops=int      Run the specified number of iterations of this job. Used
                to repeat the same workload a given number of times. Defaults
@@ -497,7 +516,7 @@ cpuchunks=int       If the job is a CPU cycle eater, split the load into
 fio spits out a lot of output. While running, fio will display the
 status of the jobs created. An example of that would be:
 
-Threads running: 1: [_r] [24.79% done] [ 13509/  8334 kb/s] [eta 00h:01m:31s]
+Threads: 1: [_r] [24.8% done] [ 13509/  8334 kb/s] [eta 00h:01m:31s]
 
 The characters inside the square brackets denote the current status of
 each thread. The possible values (in typical life cycle order) are:
@@ -529,10 +548,11 @@ direction, the output looks like:
 
 Client1 (g=0): err= 0:
   write: io=    32MiB, bw=   666KiB/s, runt= 50320msec
-    slat (msec): min=    0, max=  136, avg= 0.03, dev= 1.92
-    clat (msec): min=    0, max=  631, avg=48.50, dev=86.82
-    bw (KiB/s) : min=    0, max= 1196, per=51.00%, avg=664.02, dev=681.68
+    slat (msec): min=    0, max=  136, avg= 0.03, stdev= 1.92
+    clat (msec): min=    0, max=  631, avg=48.50, stdev=86.82
+    bw (KiB/s) : min=    0, max= 1196, per=51.00%, avg=664.02, stdev=681.68
   cpu        : usr=1.49%, sys=0.25%, ctx=7969
+  IO depths    : 1=0.1%, 2=0.3%, 4=0.5%, 8=99.0%, 16=0.0%, 32=0.0%, >32=0.0%
 
 The client number is printed, along with the group id and error of that
 thread. Below is the io statistics, here for writes. In the order listed,
@@ -557,6 +577,11 @@ runt=              The runtime of that thread
                same disk, since they are then competing for disk access.
 cpu=           CPU usage. User and system time, along with the number
                of context switches this thread went through.
+IO depths=     The distribution of io depths over the job life time. The
+               numbers are divided into powers of 2, so for example the
+               16= entries includes depths up to that value but higher
+               than the previous entry. In other words, it covers the
+               range from 16 to 31.
 
 After each client has been listed, the group statistics are printed. They
 will look like this: