Document environment variable expansion

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 634a599a26112cec97cd27987ae7cc3911dabbb4..129926b33be660faae02bc6cef0e4f5f4048cdd3 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -111,7 +111,7 @@ several global sections if so desired. A job is only affected by a global
 section residing above it. If the first character in a line is a ';' or a
 '#', the entire line is discarded as a comment.
 
-So lets look at a really simple job file that define to threads, each
+So let's look at a really simple job file that defines two processes, each
 randomly reading from a 128MiB file.
 
 ; -- start job file --
@@ -133,7 +133,7 @@ line, this job would look as follows:
 $ fio --name=global --rw=randread --size=128m --name=job1 --name=job2
 
 
-Lets look at an example that have a number of processes writing randomly
+Let's look at an example that has a number of processes writing randomly
 to files.
 
 ; -- start job file --
@@ -158,6 +158,33 @@ specify:
 
 $ fio --name=random-writers --ioengine=libaio --iodepth=4 --rw=randwrite --bs=32k --direct=0 --size=64m --numjobs=4
 
+fio also supports environment variable expansion in job files. Any
+substring of the form "${VARNAME}" as part of an option value (in other
+words, on the right of the `='), will be expanded to the value of the
+environment variable called VARNAME.  If no such environment variable
+is defined, or VARNAME is the empty string, the empty string will be
+substituted.
+
+As an example, let's look at a sample fio invocation and job file:
+
+$ SIZE=64m NUMJOBS=4 fio jobfile.fio
+
+; -- start job file --
+[random-writers]
+rw=randwrite
+size=${SIZE}
+numjobs=${NUMJOBS}
+; -- end job file --
+
+This will expand to the following equivalent job file at runtime:
+
+; -- start job file --
+[random-writers]
+rw=randwrite
+size=64m
+numjobs=4
+; -- end job file --
+
 fio ships with a few example job files, you can also look there for
 inspiration.
 
@@ -580,7 +607,10 @@ time_based If set, fio will run for the duration of the runtime
 ramp_time=time If set, fio will run the specified workload for this amount
                of time before logging any performance numbers. Useful for
                letting performance settle before logging results, thus
-               minimizing the runtime required for stable results.
+               minimizing the runtime required for stable results. Note
+               that the ramp_time is considered lead in time for a job,
+               thus it will increase the total runtime if a special timeout
+               or runtime is specified.
 
 invalidate=bool        Invalidate the buffer/page cache parts for this file prior
                to starting io. Defaults to true.
@@ -945,6 +975,8 @@ The format is one long line of values, such as:
 client1;0;0;1906777;1090804;1790;0;0;0.000000;0.000000;0;0;0.000000;0.000000;929380;1152890;25.510151%;1078276.333333;128948.113404;0;0;0;0;0;0.000000;0.000000;0;0;0.000000;0.000000;0;0;0.000000%;0.000000;0.000000;100.000000%;0.000000%;324;100.0%;0.0%;0.0%;0.0%;0.0%;0.0%;0.0%;100.0%;0.0%;0.0%;0.0%;0.0%;0.0%
 ;0.0%;0.0%;0.0%;0.0%;0.0%
 
+To enable terse output, use the --minimal command line option.
+
 Split up, the format is as follows:
 
        jobname, groupid, error