Add offset_align option

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 342bad803ac56adc062a153a74543a5d77f85f7c..e7142c57b03df0e6f500b35ad95cf712d4c20617 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -217,6 +217,9 @@ Command line options
 .. option:: --max-jobs=nr
 
        Set the maximum number of threads/processes to support to `nr`.
+       NOTE: On Linux, it may be necessary to increase the shared-memory
+       limit (:file:`/proc/sys/kernel/shmmax`) if fio runs into errors while
+       creating jobs.
 
 .. option:: --server=args
 
@@ -230,7 +233,7 @@ Command line options
 .. option:: --client=hostname
 
        Instead of running the jobs locally, send and run them on the given `hostname`
-       or set of `hostname`s.  See `Client/Server`_ section.
+       or set of `hostname`\s.  See `Client/Server`_ section.
 
 .. option:: --remote-config=file
 
@@ -792,6 +795,13 @@ Target file/device
        named :file:`testfiles.4`. The default of :file:`$jobname.$jobnum.$filenum`
        will be used if no other format specifier is given.
 
+       If you specify a path then the directories will be created up to the
+       main directory for the file.  So for example if you specify
+       ``filename_format=a/b/c/$jobnum`` then the directories a/b/c will be
+       created before the file setup part of the job.  If you specify
+       :option:`directory` then the path will be relative that directory,
+       otherwise it is treated as the absolute path.
+
 .. option:: unique_filename=bool
 
        To avoid collisions between networked clients, fio defaults to prefixing any
@@ -1118,13 +1128,20 @@ I/O type
 .. option:: offset=int
 
        Start I/O at the provided offset in the file, given as either a fixed size in
-       bytes or a percentage. If a percentage is given, the next ``blockalign``-ed
-       offset will be used. Data before the given offset will not be touched. This
+       bytes or a percentage. If a percentage is given, the generated offset will be
+       aligned to the minimum ``blocksize`` or to the value of ``offset_align`` if
+       provided. Data before the given offset will not be touched. This
        effectively caps the file size at `real_size - offset`. Can be combined with
        :option:`size` to constrain the start and end range of the I/O workload.
        A percentage can be specified by a number between 1 and 100 followed by '%',
        for example, ``offset=20%`` to specify 20%.
 
+.. option:: offset_align=int
+
+       If set to non-zero value, the byte offset generated by a percentage ``offset``
+       is aligned upwards to this value. Defaults to 0 meaning that a percentage
+       offset is aligned to the minimum block size.
+
 .. option:: offset_increment=int
 
        If this is provided, then the real offset becomes `offset + offset_increment
@@ -1705,7 +1722,7 @@ I/O engine
                        Doesn't transfer any data, but burns CPU cycles according to the
                        :option:`cpuload` and :option:`cpuchunks` options. Setting
                        :option:`cpuload`\=85 will cause that job to do nothing but burn 85%
-                       of the CPU. In case of SMP machines, use :option:`numjobs`=<nr_of_cpu>
+                       of the CPU. In case of SMP machines, use :option:`numjobs`\=<nr_of_cpu>
                        to get desired CPU usage, as the cpuload only loads a
                        single CPU at the desired rate. A job never finishes unless there is
                        at least one non-cpuio job.
@@ -1797,6 +1814,10 @@ I/O engine
                        absolute or relative. See :file:`engines/skeleton_external.c` for
                        details of writing an external I/O engine.
 
+               **filecreate**
+                       Simply create the files and do no IO to them.  You still need to
+                       set  `filesize` so that all the accounting still occurs, but no
+                       actual IO will be done other than creating the file.
 
 I/O engine specific parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2862,7 +2883,15 @@ Measurements and reporting
 
 .. option:: clat_percentiles=bool
 
-       Enable the reporting of percentiles of completion latencies.
+       Enable the reporting of percentiles of completion latencies.  This
+       option is mutually exclusive with :option:`lat_percentiles`.
+
+.. option:: lat_percentiles=bool
+
+       Enable the reporting of percentiles of IO latencies. This is similar
+       to :option:`clat_percentiles`, except that this includes the
+       submission latency. This option is mutually exclusive with
+       :option:`clat_percentiles`.
 
 .. option:: percentile_list=float_list