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:
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
.. option:: offset=int
- Start I/O at the given offset in the file. The 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 that I/O will be done within.
+ Start I/O at the provided offset in the file, given as either a fixed size 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
+ 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.
.. option:: offset_increment=int
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:: buffer_pattern=str
- If set, fio will fill the I/O buffers with this pattern. If not set, the
- contents of I/O buffers is defined by the other options related to buffer
- contents. The setting can be any pattern of bytes, and can be prefixed with
- 0x for hex values. It may also be a string, where the string must then be
- wrapped with ``""``, e.g.::
+ If set, fio will fill the I/O buffers with this pattern or with the contents
+ of a file. If not set, the contents of I/O buffers are defined by the other
+ options related to buffer contents. The setting can be any pattern of bytes,
+ and can be prefixed with 0x for hex values. It may also be a string, where
+ the string must then be wrapped with ``""``. Or it may also be a filename,
+ where the filename must be wrapped with ``''`` in which case the file is
+ opened and read. Note that not all the file contents will be read if that
+ would cause the buffers to overflow. So, for example::
+
+ buffer_pattern='filename'
+
+ or::
buffer_pattern="abcd"
Also you can combine everything together in any order::
- buffer_pattern=0xdeadface"abcd"-12
+ buffer_pattern=0xdeadface"abcd"-12'filename'
.. option:: dedupe_percentage=int
.. 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
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.
+ 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
**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]
**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
contents to one or more separate threads. If using this offload option, even
sync I/O engines can benefit from using an :option:`iodepth` setting higher
than 1, as it allows them to have I/O in flight while verifies are running.
+ Defaults to 0 async threads, i.e. verification is not asynchronous.
.. option:: verify_async_cpus=str
<type> is "local" for a local run, "sock" for a client/server socket
connection, and "ip" (192.168.0.1, for instance) for a networked
- client/server connection.
+ client/server connection. Defaults to true.
.. option:: verify_state_load=bool
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
.. option:: ignore_error=str
Sometimes you want to ignore some errors during test in that case you can
- specify error list for each error type.
+ specify error list for each error type, instead of only being able to
+ ignore the default 'non-fatal error' using :option:`continue_on_error`.
``ignore_error=READ_ERR_LIST,WRITE_ERR_LIST,VERIFY_ERR_LIST`` errors for
given error type is separated with ':'. Error may be symbol ('ENOSPC',
'ENOMEM') or integer. Example::
ignore_error=EAGAIN,ENOSPC:122
This option will ignore EAGAIN from READ, and ENOSPC and 122(EDQUOT) from
- WRITE.
+ WRITE. This option works by overriding :option:`continue_on_error` with
+ the list of errors for each error type if any.
.. option:: error_dump=bool
Total IO (KiB), bandwidth (KiB/sec), IOPS, runtime (msec)
Submission latency: min, max, mean, stdev (usec)
- Completion latency: min, max, mean, stdev(usec)
+ Completion latency: min, max, mean, stdev (usec)
Completion latency percentiles: 20 fields (see below)
Total latency: min, max, mean, stdev (usec)
Bw (KiB/s): min, max, aggregate percentage of total, mean, stdev
For disk utilization, all disks used by fio are shown. So for each disk there
will be a disk utilization section.
+Below is a single line containing short names for each of the fields in the
+minimal output v3, separated by semicolons:
+
+terse_version_3;fio_version;jobname;groupid;error;read_kb;read_bandwidth;read_iops;read_runtime_ms;read_slat_min;read_slat_max;read_slat_mean;read_slat_dev;read_clat_max;read_clat_min;read_clat_mean;read_clat_dev;read_clat_pct01;read_clat_pct02;read_clat_pct03;read_clat_pct04;read_clat_pct05;read_clat_pct06;read_clat_pct07;read_clat_pct08;read_clat_pct09;read_clat_pct10;read_clat_pct11;read_clat_pct12;read_clat_pct13;read_clat_pct14;read_clat_pct15;read_clat_pct16;read_clat_pct17;read_clat_pct18;read_clat_pct19;read_clat_pct20;read_tlat_min;read_lat_max;read_lat_mean;read_lat_dev;read_bw_min;read_bw_max;read_bw_agg_pct;read_bw_mean;read_bw_dev;write_kb;write_bandwidth;write_iops;write_runtime_ms;write_slat_min;write_slat_max;write_slat_mean;write_slat_dev;write_clat_max;write_clat_min;write_clat_mean;write_clat_dev;write_clat_pct01;write_clat_pct02;write_clat_pct03;write_clat_pct04;write_clat_pct05;write_clat_pct06;write_clat_pct07;write_clat_pct08;write_clat_pct09;write_clat_pct10;write_clat_pct11;write_clat_pct12;write_clat_pct13;write_clat_pct14;write_clat_pct15;write_clat_pct16;write_clat_pct17;write_clat_pct18;write_clat_pct19;write_clat_pct20;write_tlat_min;write_lat_max;write_lat_mean;write_lat_dev;write_bw_min;write_bw_max;write_bw_agg_pct;write_bw_mean;write_bw_dev;cpu_user;cpu_sys;cpu_csw;cpu_mjf;pu_minf;iodepth_1;iodepth_2;iodepth_4;iodepth_8;iodepth_16;iodepth_32;iodepth_64;lat_2us;lat_4us;lat_10us;lat_20us;lat_50us;lat_100us;lat_250us;lat_500us;lat_750us;lat_1000us;lat_2ms;lat_4ms;lat_10ms;lat_20ms;lat_50ms;lat_100ms;lat_250ms;lat_500ms;lat_750ms;lat_1000ms;lat_2000ms;lat_over_2000ms;disk_name;disk_read_iops;disk_write_iops;disk_read_merges;disk_write_merges;disk_read_ticks;write_ticks;disk_queue_time;disk_util
+
Trace file format
-----------------
projects / fio.git / blobdiff