If the option accepts an upper and lower range, use a colon ':' or
minus '-' to separate such values. See :ref:`irange <irange>`.
+ If the lower value specified happens to be larger than the upper value,
+ two values are swapped.
.. _bool:
.. option:: numjobs=int
- Create the specified number of clones of this job. May be used to setup a
+ Create the specified number of clones of this job. Each clone of job
+ is spawned as an independent thread or process. May be used to setup a
larger number of threads/processes doing the same thing. Each thread is
reported separately; to see statistics for all clones as a whole, use
:option:`group_reporting` in conjunction with :option:`new_group`.
Fio normally makes up a `filename` based on the job name, thread number, and
file number. If you want to share files between threads in a job or several
- jobs, specify a `filename` for each of them to override the default. If the
- ioengine is file based, you can specify a number of files by separating the
- names with a ':' colon. So if you wanted a job to open :file:`/dev/sda` and
- :file:`/dev/sdb` as the two working files, you would use
- ``filename=/dev/sda:/dev/sdb``.
+ jobs with fixed file paths, specify a `filename` for each of them to override
+ the default. If the ioengine is file based, you can specify a number of files
+ by separating the names with a ':' colon. So if you wanted a job to open
+ :file:`/dev/sda` and :file:`/dev/sdb` as the two working files, you would use
+ ``filename=/dev/sda:/dev/sdb``. This also means that whenever this option is
+ specified, :option:`nrfiles` is ignored. The size of regular files specified
+ by this option will be :option:`size` divided by number of files unless
+ explicit size is specified by :option:`filesize`.
+
On Windows, disk devices are accessed as :file:`\\\\.\\PhysicalDrive0` for
the first device, :file:`\\\\.\\PhysicalDrive1` for the second etc.
Note: Windows and FreeBSD prevent write access to areas
.. option:: nrfiles=int
- Number of files to use for this job. Defaults to 1.
+ Number of files to use for this job. Defaults to 1. The size of files
+ will be :option:`size` divided by this unless explicit size is specified by
+ :option:`filesize`. Files are created for each thread separately, and each
+ file will have a file number within its name by default, as explained in
+ :option:`filename` section.
+
.. option:: openfiles=int
If this isn't set, fio will abort jobs that are destructive (e.g. that write)
to what appears to be a mounted device or partition. This should help catch
creating inadvertently destructive tests, not realizing that the test will
- destroy data on the mounted file system. Default: false.
+ destroy data on the mounted file system. Note that some platforms don't allow
+ writing against a mounted device regardless of this option. Default: false.
.. option:: pre_read=bool
blocks given. For example, if you give 32 as a parameter, fio will sync the
file for every 32 writes issued. If fio is using non-buffered I/O, we may
not sync the file. The exception is the sg I/O engine, which synchronizes
- the disk cache anyway.
+ the disk cache anyway. Defaults to 0, which means no sync every certain
+ number of writes.
.. option:: fdatasync=int
Like :option:`fsync` but uses :manpage:`fdatasync(2)` to only sync data and
- not metadata blocks. In FreeBSD and Windows there is no
+ not metadata blocks. In Windows, FreeBSD, and DragonFlyBSD there is no
:manpage:`fdatasync(2)`, this falls back to using :manpage:`fsync(2)`.
+ Defaults to 0, which means no sync data every certain number of writes.
.. option:: write_barrier=int
means default for reads, 8k for writes and trims.
**bs=,8k,**
- means default for reads, 8k for writes, and default for writes.
+ means default for reads, 8k for writes, and default for trims.
.. option:: blocksize_range=irange[,irange][,irange], bsrange=irange[,irange][,irange]
.. option:: invalidate=bool
Invalidate the buffer/page cache parts for this file prior to starting
- I/O. Defaults to true.
+ I/O if the platform and file type support it. Defaults to true.
+ This will be ignored if :option:`pre_read` is also specified for the
+ same job.
.. option:: sync=bool
**mmapshared**
Same as mmap, but use a MMAP_SHARED mapping.
+ **cudamalloc**
+ Use GPU memory as the buffers for GPUDirect RDMA benchmark.
+
The area allocated is a function of the maximum allowed bs size for the job,
multiplied by the I/O depth given. Note that for **shmhuge** and
**mmaphuge** to work, the system must have free huge pages allocated. This
.. option:: size=int
- The total size of file I/O for this job. Fio will run until this many bytes
- has been transferred, unless runtime is limited by other options (such as
- :option:`runtime`, for instance, or increased/decreased by
- :option:`io_size`). Unless specific :option:`nrfiles` and :option:`filesize`
- options are given, fio will divide this size between the available files
- specified by the job. If not set, fio will use the full size of the given
+ The total size of file I/O for each thread of this job. Fio will run until
+ this many bytes has been transferred, unless runtime is limited by other options
+ (such as :option:`runtime`, for instance, or increased/decreased by :option:`io_size`).
+ Fio will divide this size between the available files determined by options
+ such as :option:`nrfiles`, :option:`filename`, unless :option:`filesize` is
+ specified by the job. If the result of division happens to be 0, the size is
+ set to the physical size of the given files or devices if they exist.
+ If this option is not specified, fio will use the full size of the given
files or devices. If the files do not exist, size must be given. It is also
possible to give size as a percentage between 1 and 100. If ``size=20%`` is
given, fio will use 20% of the full size of the given files or devices.
Individual file sizes. May be a range, in which case fio will select sizes
for files at random within the given range and limited to :option:`size` in
total (if that is given). If not given, each created file is the same size.
+ This option overrides :option:`size` in terms of file size, which means
+ this value is used as a fixed size or possible range of each file.
.. option:: file_append=bool
**sync**
Basic :manpage:`read(2)` or :manpage:`write(2)`
I/O. :manpage:`lseek(2)` is used to position the I/O location.
+ See :option:`fsync` and :option:`fdatasync` for syncing write I/Os.
**psync**
Basic :manpage:`pread(2)` or :manpage:`pwrite(2)` I/O. Default on
DDIR_TRIM
does fallocate(,mode = FALLOC_FL_KEEP_SIZE|FALLOC_FL_PUNCH_HOLE).
+ **ftruncate**
+ I/O engine that sends :manpage:`ftruncate(2)` operations in response
+ to write (DDIR_WRITE) events. Each ftruncate issued sets the file's
+ size to the current block offset. Block size is ignored.
+
**e4defrag**
I/O engine that does regular EXT4_IOC_MOVE_EXT ioctls to simulate
defragment activity in request to DDIR_WRITE event.
.. option:: cpuload=int : [cpuio]
- Attempt to use the specified percentage of CPU cycles.
+ Attempt to use the specified percentage of CPU cycles. This is a mandatory
+ option when using cpuio I/O engine.
.. option:: cpuchunks=int : [cpuio]
.. option:: thread
Fio defaults to forking jobs, however if this option is given, fio will use
- :manpage:`pthread_create(3)` to create threads instead.
+ POSIX Threads function :manpage:`pthread_create(3)` to create threads instead
+ of forking processes.
.. option:: wait_for=str
**sha1**
Use optimized sha1 as the checksum function.
+ **sha3-224**
+ Use optimized sha3-224 as the checksum function.
+
+ **sha3-256**
+ Use optimized sha3-256 as the checksum function.
+
+ **sha3-384**
+ Use optimized sha3-384 as the checksum function.
+
+ **sha3-512**
+ Use optimized sha3-512 as the checksum function.
+
**meta**
This option is deprecated, since now meta information is included in
generic verification header and meta verification happens by
all jobs in a file will be part of the same reporting group, unless
separated by a :option:`stonewall`.
+.. option:: stats
+
+ By default, fio collects and shows final output results for all jobs
+ that run. If this option is set to 0, then fio will ignore it in
+ the final stat output.
+
.. option:: write_bw_log=str
If given, write a bandwidth log for this job. Can be used to store data of
projects / fio.git / blobdiff