exp: update man page and HOWTO

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 23746cec199e05c6a34ed007794f5c45abc6e8e5..57911b431fb03fa1a069c4e7d413af052b6eb4d8 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -159,6 +159,41 @@ specify:
 
 $ fio --name=random-writers --ioengine=libaio --iodepth=4 --rw=randwrite --bs=32k --direct=0 --size=64m --numjobs=4
 
+When fio is utilized as a basis of any reasonably large test suite, it might be
+desirable to share a set of standardized settings across multiple job files.
+Instead of copy/pasting such settings, any section may pull in an external
+.fio file with 'include filename' directive, as in the following example:
+
+; -- start job file including.fio --
+[global]
+filename=/tmp/test
+filesize=1m
+include glob-include.fio
+
+[test]
+rw=randread
+bs=4k
+time_based=1
+runtime=10
+include test-include.fio
+; -- end job file including.fio --
+
+; -- start job file glob-include.fio --
+thread=1
+group_reporting=1
+; -- end job file glob-include.fio --
+
+; -- start job file test-include.fio --
+ioengine=libaio
+iodepth=4
+; -- end job file test-include.fio --
+
+Settings pulled into a section apply to that section only (except global
+section). Include directives may be nested in that any included file may
+contain further include directive(s). Include files may not contain []
+sections.
+
+
 4.1 Environment variables
 -------------------------
 
@@ -218,7 +253,20 @@ machine.
 
 This section describes in details each parameter associated with a job.
 Some parameters take an option of a given type, such as an integer or
-a string. The following types are used:
+a string. Anywhere a numeric value is required, an arithmetic expression
+may be used, provided it is surrounded by parentheses. Supported operators
+are:
+
+       addition (+)
+       subtraction (-)
+       multiplication (*)
+       division (/)
+       modulus (%)
+       exponentiation (^)
+
+For time values in expressions, units are microseconds by default. This is
+different than for time values not in expressions (not enclosed in
+parentheses). The following types are used:
 
 str    String. This is a sequence of alpha characters.
 time   Integer with possible time suffix. In seconds unless otherwise
@@ -788,7 +836,9 @@ number_ios=int      Fio will normally perform IOs until it has exhausted the size
                time (or hits an error condition). With this setting, the
                range/size can be set independently of the number of IOs to
                perform. When fio reaches this number, it will exit normally
-               and report status.
+               and report status. Note that this does not extend the amount
+               of IO that will be done, it will only stop fio if this
+               condition is met before other end-of-job criteria.
 
 fsync=int      If writing to a file, issue a sync of the dirty data
                for every number of blocks given. For example, if you give