Add support for reserved keywords

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 2d155aa0ef929aa75a6dad7527b11b5d790bf29e..662ebe32acf2e10c1956f8f768171da2f92de244 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -158,6 +158,9 @@ specify:
 
 $ fio --name=random-writers --ioengine=libaio --iodepth=4 --rw=randwrite --bs=32k --direct=0 --size=64m --numjobs=4
 
+4.1 Environment variables
+-------------------------
+
 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
@@ -188,6 +191,20 @@ numjobs=4
 fio ships with a few example job files, you can also look there for
 inspiration.
 
+4.2 Reserved keywords
+---------------------
+
+Additionally, fio has a set of reserved keywords that will be replaced
+internally with the appropriate value. Those keywords are:
+
+$pagesize      The architecture page size of the running system
+$mb_memory     Megabytes of total memory in the system
+$ncpus         Number of online available CPUs
+
+These can be used on the command line or in the job file, and will be
+automatically substituted with the current system values when the job
+is run.
+
 
 5.0 Detailed list of parameters
 -------------------------------
@@ -197,21 +214,21 @@ Some parameters take an option of a given type, such as an integer or
 a string. The following types are used:
 
 str    String. This is a sequence of alpha characters.
-time   Integer with possible time postfix. In seconds unless otherwise
+time   Integer with possible time suffix. In seconds unless otherwise
        specified, use eg 10m for 10 minutes. Accepts s/m/h for seconds,
        minutes, and hours.
-int    SI integer. A whole number value, which may contain a postfix
-       describing the base of the number. Accepted postfixes are k/m/g,
-       meaning kilo, mega, and giga. So if you want to specify 4096,
-       you could either write out '4096' or just give 4k. The postfixes
-       signify base 2 values, so 1024 is 1k and 1024k is 1m and so on.
-       If the option accepts an upper and lower range, use a colon ':'
-       or minus '-' to separate such values. May also include a prefix
-       to indicate numbers base. If 0x is used, the number is assumed to
-       be hexadecimal. See irange.
+int    SI integer. A whole number value, which may contain a suffix
+       describing the base of the number. Accepted suffixes are k/m/g/t/p,
+       meaning kilo, mega, giga, tera, and peta. The suffix is not case
+       sensitive. So if you want to specify 4096, you could either write
+       out '4096' or just give 4k. The suffixes signify base 2 values, so
+       1024 is 1k and 1024k is 1m and so on. If the option accepts an upper
+       and lower range, use a colon ':' or minus '-' to separate such values.
+       May also include a prefix to indicate numbers base. If 0x is used,
+       the number is assumed to be hexadecimal. See irange.
 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
+irange Integer range with suffix. Allows value range to be given, such
        as 1024-4096. A colon may also be used as the separator, 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
@@ -243,8 +260,11 @@ filename=str       Fio normally makes up a filename based on the job name,
                can specify a number of files by separating the names with a
                ':' colon. So if you wanted a job to open /dev/sda and /dev/sdb
                as the two working files, you would use
-               filename=/dev/sda:/dev/sdb. '-' is a reserved name, meaning
-               stdin or stdout. Which of the two depends on the read/write
+               filename=/dev/sda:/dev/sdb. If the wanted filename does need to
+               include a colon, then escape that with a '\' character. For
+               instance, if the filename is "/dev/dsk/foo@3,0:c", then you would
+               use filename="/dev/dsk/foo@3,0\:c". '-' is a reserved name,
+               meaning stdin or stdout. Which of the two depends on the read/write
                direction set.
 
 opendir=str    Tell fio to recursively add any file it can find in this
@@ -290,6 +310,11 @@ rw=str             Type of io pattern. Accepted values are:
                IO's, instead of for every IO. Use rw=randread:8 to specify
                that.
 
+kb_base=int    The base unit for a kilobyte. The defacto base is 2^10, 1024.
+               Storage manufacturers like to use 10^3 or 1000 as a base
+               ten unit instead, for obvious reasons. Allow values are
+               1024 or 1000, with 1024 being the default.
+
 randrepeat=bool        For random IO workloads, seed the generator in a predictable
                way so that results are repeatable across repetitions.
 
@@ -595,7 +620,7 @@ thinktime_blocks
                after every block.
 
 rate=int       Cap the bandwidth used by this job. The number is in bytes/sec,
-               the normal postfix rules apply. You can use rate=500k to limit
+               the normal suffix rules apply. You can use rate=500k to limit
                reads and writes to 500k each, or you can specify read and
                writes separately. Using rate=1m,500k would limit reads to
                1MB/sec and writes to 500KB/sec. Capping only reads or