Expand choices for exitall

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 1c9b2c1020f7e7d53b43926fcb3c3369a1db07f8..41a667af4406a17b215952faa7ef3511bc0bb801 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -222,8 +222,8 @@ Command line options
 
 .. option:: --alloc-size=kb
 
-       Set the internal smalloc pool size to `kb` in KiB.  The
-       ``--alloc-size`` switch allows one to use a larger pool size for smalloc.
+       Allocate additional internal smalloc pools of size `kb` in KiB.  The
+       ``--alloc-size`` option increases shared memory set aside for use by fio.
        If running large jobs with randommap enabled, fio can run out of memory.
        Smalloc is an internal allocator for shared structures from a fixed size
        memory pool and can grow to 16 pools. The pool size defaults to 16MiB.
@@ -1173,6 +1173,10 @@ I/O type
                        Pre-allocate via :manpage:`fallocate(2)` with
                        FALLOC_FL_KEEP_SIZE set.
 
+               **truncate**
+                       Extend file to final size via :manpage:`ftruncate(2)`
+                       instead of allocating.
+
                **0**
                        Backward-compatible alias for **none**.
 
@@ -1182,7 +1186,15 @@ I/O type
        May not be available on all supported platforms. **keep** is only available
        on Linux. If using ZFS on Solaris this cannot be set to **posix**
        because ZFS doesn't support pre-allocation. Default: **native** if any
-       pre-allocation methods are available, **none** if not.
+       pre-allocation methods except **truncate** are available, **none** if not.
+
+       Note that using **truncate** on Windows will interact surprisingly
+       with non-sequential write patterns. When writing to a file that has
+       been extended by setting the end-of-file information, Windows will
+       backfill the unwritten portion of the file up to that offset with
+       zeroes before issuing the new write. This means that a single small
+       write to the end of an extended file will stall until the entire
+       file has been filled with zeroes.
 
 .. option:: fadvise_hint=str
 
@@ -1252,7 +1264,9 @@ I/O type
        is incremented for each sub-job (i.e. when :option:`numjobs` option is
        specified). This option is useful if there are several jobs which are
        intended to operate on a file in parallel disjoint segments, with even
-       spacing between the starting points.
+       spacing between the starting points. Percentages can be used for this option.
+       If a percentage is given, the generated offset will be aligned to the minimum
+       ``blocksize`` or to the value of ``offset_align`` if provided.
 
 .. option:: number_ios=int
 
@@ -1277,7 +1291,7 @@ I/O type
 .. option:: fdatasync=int
 
        Like :option:`fsync` but uses :manpage:`fdatasync(2)` to only sync data and
-       not metadata blocks.  In Windows, FreeBSD, and DragonFlyBSD there is no
+       not metadata blocks. In Windows, FreeBSD, DragonFlyBSD or OSX there is no
        :manpage:`fdatasync(2)` so this falls back to using :manpage:`fsync(2)`.
        Defaults to 0, which means fio does not periodically issue and wait for a
        data-only sync to complete.
@@ -2031,6 +2045,12 @@ with the caveat that when used on the command line, they must come after the
        map and release for each IO. This is more efficient, and reduces the
        IO latency as well.
 
+.. option:: registerfiles : [io_uring]
+       With this option, fio registers the set of files being used with the
+       kernel. This avoids the overhead of managing file counts in the kernel,
+       making the submission and completion part more lightweight. Required
+       for the below :option:`sqthread_poll` option.
+
 .. option:: sqthread_poll : [io_uring]
 
        Normally fio will submit IO by issuing a system call to notify the
@@ -2705,7 +2725,7 @@ Threads, processes and job synchronization
                        Each job will get a unique CPU from the CPU set.
 
        **shared** is the default behavior, if the option isn't specified. If
-       **split** is specified, then fio will will assign one cpu per job. If not
+       **split** is specified, then fio will assign one cpu per job. If not
        enough CPUs are given for the jobs listed, then fio will roundrobin the CPUs
        in the set.
 
@@ -2794,9 +2814,21 @@ Threads, processes and job synchronization
 
 .. option:: exitall
 
-       By default, fio will continue running all other jobs when one job finishes
-       but sometimes this is not the desired action.  Setting ``exitall`` will
-       instead make fio terminate all other jobs when one job finishes.
+       By default, fio will continue running all other jobs when one job finishes.
+       Sometimes this is not the desired action.  Setting ``exitall`` will instead
+       make fio terminate all jobs in the same group, as soon as one job of that
+       group finishes.
+
+.. option:: exit_what
+
+       By default, fio will continue running all other jobs when one job finishes.
+       Sometimes this is not the desired action. Setting ``exit_all`` will
+       instead make fio terminate all jobs in the same group. The option
+        ``exit_what`` allows to control which jobs get terminated when ``exitall`` is
+        enabled. The default is ``group`` and does not change the behaviour of
+        ``exitall``. The setting ``all`` terminates all jobs. The setting ``stonewall``
+        terminates all currently running jobs across all groups and continues execution
+        with the next stonewalled group.
 
 .. option:: exec_prerun=str