-.TH fio 1 "March 2017" "User Manual"
+.TH fio 1 "June 2017" "User Manual"
.SH NAME
fio \- flexible I/O tester
.SH SYNOPSIS
Display version information and exit.
.TP
.BI \-\-terse\-version \fR=\fPversion
-Set terse version output format (default 3, or 2 or 4)
+Set terse version output format (default 3, or 2, 4, 5)
.TP
.B \-\-help
Display usage information and exit.
.B none
Do not pre-allocate space.
.TP
+.B native
+Use a platform's native pre-allocation call but fall back to 'none' behavior if
+it fails/is not implemented.
+.TP
.B posix
Pre-allocate via \fBposix_fallocate\fR\|(3).
.TP
.RE
.P
May not be available on all supported platforms. 'keep' is only
-available on Linux. If using ZFS on Solaris this must be set to 'none'
-because ZFS doesn't support it. Default: 'posix'.
+available on Linux. If using ZFS on Solaris this cannot be set to 'posix'
+because ZFS doesn't support it. Default: 'native' if any pre-allocation methods
+are available, 'none' if not.
.RE
.TP
.BI fadvise_hint \fR=\fPstr
size, fio can alternate random and zeroed data throughout the IO buffer.
.TP
.BI buffer_pattern \fR=\fPstr
-If set, fio will fill the IO buffers with this pattern. If not set, the contents
-of IO 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:
+.RS
.RS
+\fBbuffer_pattern\fR='filename'
.RS
+or
+.RE
\fBbuffer_pattern\fR="abcd"
.RS
or
Also you can combine everything together in any order:
.LP
.RS
-\fBbuffer_pattern\fR=0xdeadface"abcd"-12
+\fBbuffer_pattern\fR=0xdeadface"abcd"-12'filename'
.RE
.RE
.TP
.B pareto
Use a pareto distribution to decide what file to access.
.TP
+.B normal
+Use a Gaussian (normal) distribution to decide what file to access.
+.TP
.B gauss
-Use a gaussian (normal) distribution to decide what file to access.
+Alias for normal.
.RE
.P
For \fBrandom\fR, \fBroundrobin\fR, and \fBsequential\fR, a postfix can be
Default: true.
.TP
.BI offset \fR=\fPint
-Offset in the file to start I/O. Data before the offset will not be touched.
+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 \fBblockalign\fR-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
+\fBsize\fR 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%.
.TP
.BI offset_increment \fR=\fPint
If this is provided, then the real offset becomes the
.B pareto
Pareto distribution
.TP
-.B gauss
-Normal (gaussian) distribution
+.B normal
+Normal (Gaussian) distribution
.TP
.B zoned
Zoned random distribution
that can be used visualize what the given input values will yield in terms of
hit rates. If you wanted to use \fBzipf\fR with a theta of 1.2, you would use
random_distribution=zipf:1.2 as the option. If a non-uniform model is used,
-fio will disable use of the random map. For the \fBgauss\fR distribution, a
-normal deviation is supplied as a value between 0 and 100.
+fio will disable use of the random map. For the \fBnormal\fR distribution, a
+normal (Gaussian) deviation is supplied as a value between 0 and 100.
.P
.RS
For a \fBzoned\fR distribution, fio supports specifying percentages of IO
A job description (if provided) follows on a new line. Note that the first
number in the line is the version number. If the output has to be changed
for some reason, this number will be incremented by 1 to signify that
-change. The fields are:
+change. Numbers in brackets (e.g. "[v3]") indicate which terse version
+introduced a field. The fields are:
.P
.RS
-.B terse version, fio version, jobname, groupid, error
+.B terse version, fio version [v3], jobname, groupid, error
.P
Read status:
.RS
.RE
Bandwidth:
.RS
-.B min, max, aggregate percentage of total, mean, standard deviation
+.B min, max, aggregate percentage of total, mean, standard deviation, number of samples [v5]
+.RE
+IOPS [v5]:
+.RS
+.B min, max, mean, standard deviation, number of samples
.RE
.RE
.P
.RE
Bandwidth:
.RS
-.B min, max, aggregate percentage of total, mean, standard deviation
+.B min, max, aggregate percentage of total, mean, standard deviation, number of samples [v5]
+.RE
+IOPS [v5]:
+.RS
+.B min, max, mean, standard deviation, number of samples
.RE
.RE
.P
+Trim status [all but version 3]:
+.RS
+Similar to Read/Write status but for trims.
+.RE
+.P
CPU usage:
.RS
.B user, system, context switches, major page faults, minor page faults
.RE
.RE
.P
-Disk utilization (1 for each disk used):
+Disk utilization (1 for each disk used) [v3]:
.RS
.B name, read ios, write ios, read merges, write merges, read ticks, write ticks, read in-queue time, write in-queue time, disk utilization percentage
.RE
.P
.B text description (if provided in config - appears on newline)
.RE
+.P
+Below is a single line containing short names for each of the fields in
+the minimal output v3, separated by semicolons:
+.RS
+.P
+.nf
+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
+.fi
+.RE
.SH TRACE FILE FORMAT
There are two trace file format that you can encounter. The older (v1) format
is unsupported since version 1.20-rc3 (March 2008). It will still be described
.br
These are typically located under /usr/share/doc/fio.
-\fBHOWTO\fR: http://git.kernel.dk/?p=fio.git;a=blob_plain;f=HOWTO
+\fBHOWTO\fR: http://git.kernel.dk/cgit/fio/plain/HOWTO
.br
-\fBREADME\fR: http://git.kernel.dk/?p=fio.git;a=blob_plain;f=README
+\fBREADME\fR: http://git.kernel.dk/cgit/fio/plain/README
.br
projects / fio.git / blobdiff