filesetup: add native fallocate

[fio.git] / fio.1

diff --git a/fio.1 b/fio.1
index 3348513678780b6d86b6be67d2c22be9b5233bd6..9783646d752988a455b24a2fc029f1725c848e48 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -1,4 +1,4 @@
-.TH fio 1 "March 2017" "User Manual"
+.TH fio 1 "June 2017" "User Manual"

 .SH NAME
 fio \- flexible I/O tester
 .SH SYNOPSIS
 .SH NAME
 fio \- flexible I/O tester
 .SH SYNOPSIS


@@ -43,7 +43,7 @@ Deprecated, use \-\-output-format instead to select multiple formats.
 Display version information and exit.
 .TP
 .BI \-\-terse\-version \fR=\fPversion
 Display version information and exit.
 .TP
 .BI \-\-terse\-version \fR=\fPversion

-Set terse version output format (Current version 3, or older version 2).
+Set terse version output format (default 3, or 2, 4, 5)

 .TP
 .B \-\-help
 Display usage information and exit.
 .TP
 .B \-\-help
 Display usage information and exit.


@@ -436,6 +436,10 @@ are:
 .B none
 Do not pre-allocate space.
 .TP
 .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
 .B posix
 Pre-allocate via \fBposix_fallocate\fR\|(3).
 .TP


@@ -450,8 +454,9 @@ Backward-compatible alias for 'posix'.
 .RE
 .P
 May not be available on all supported platforms. 'keep' is only
 .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
 .RE
 .TP
 .BI fadvise_hint \fR=\fPstr


@@ -533,7 +538,7 @@ bs=256k    means 256k for reads, writes and trims
 bs=8k,32k  means 8k for reads, 32k for writes and trims
 bs=8k,32k, means 8k for reads, 32k for writes, and default for trims
 bs=,8k     means default for reads, 8k for writes and trims
 bs=8k,32k  means 8k for reads, 32k for writes and trims
 bs=8k,32k, means 8k for reads, 32k for writes, and default for trims
 bs=,8k     means default for reads, 8k for writes and trims

-bs=,8k,    means default for reads, 8k for writes, and default for writes
+bs=,8k,    means default for reads, 8k for writes, and default for trims

 .fi
 .TP
 .BI blocksize_range \fR=\fPirange[,irange][,irange] "\fR,\fB bsrange" \fR=\fPirange[,irange][,irange]
 .fi
 .TP
 .BI blocksize_range \fR=\fPirange[,irange][,irange] "\fR,\fB bsrange" \fR=\fPirange[,irange][,irange]


@@ -611,13 +616,20 @@ the remaining zeroed. With this set to some chunk size smaller than the block
 size, fio can alternate random and zeroed data throughout the IO buffer.
 .TP
 .BI buffer_pattern \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
 .RS

+\fBbuffer_pattern\fR='filename'

 .RS
 .RS

+or
+.RE

 \fBbuffer_pattern\fR="abcd"
 .RS
 or
 \fBbuffer_pattern\fR="abcd"
 .RS
 or


@@ -632,7 +644,7 @@ or
 Also you can combine everything together in any order:
 .LP
 .RS
 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
 .RE
 .RE
 .TP


@@ -669,8 +681,11 @@ Use a zipfian distribution to decide what file to access.
 .B pareto
 Use a pareto distribution to decide what file to access.
 .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
 .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
 .RE
 .P
 For \fBrandom\fR, \fBroundrobin\fR, and \fBsequential\fR, a postfix can be


@@ -904,7 +919,13 @@ If true, use buffered I/O.  This is the opposite of the \fBdirect\fR parameter.
 Default: true.
 .TP
 .BI offset \fR=\fPint
 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
 .TP
 .BI offset_increment \fR=\fPint
 If this is provided, then the real offset becomes the


@@ -991,8 +1012,8 @@ Zipf distribution
 .B pareto
 Pareto distribution
 .TP
 .B pareto
 Pareto distribution
 .TP

-.B gauss
-Normal (gaussian) distribution
+.B normal
+Normal (Gaussian) distribution

 .TP
 .B zoned
 Zoned random distribution
 .TP
 .B zoned
 Zoned random distribution


@@ -1004,8 +1025,8 @@ For \fBpareto\fR, it's the pareto power. Fio includes a test program, genzipf,
 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,
 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
 .P
 .RS
 For a \fBzoned\fR distribution, fio supports specifying percentages of IO


@@ -1309,6 +1330,9 @@ Same as \fBmmap\fR, but use huge files as backing.
 .TP
 .B mmapshared
 Same as \fBmmap\fR, but use a MMAP_SHARED mapping.
 .TP
 .B mmapshared
 Same as \fBmmap\fR, but use a MMAP_SHARED mapping.

+.TP
+.B cudamalloc
+Use GPU memory as the buffers for GPUDirect RDMA benchmark. The ioengine must be \fBrdma\fR.

 .RE
 .P
 The amount of memory allocated is the maximum allowed \fBblocksize\fR for the
 .RE
 .P
 The amount of memory allocated is the maximum allowed \fBblocksize\fR for the


@@ -1548,6 +1572,10 @@ Wait for preceding jobs in the job file to exit before starting this one.
 Start a new reporting group.  If not given, all jobs in a file will be part
 of the same reporting group, unless separated by a stonewall.
 .TP
 Start a new reporting group.  If not given, all jobs in a file will be part
 of the same reporting group, unless separated by a stonewall.
 .TP

+.BI stats \fR=\fPbool
+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.
+.TP

 .BI numjobs \fR=\fPint
 Number of clones (processes/threads performing the same workload) of this job.
 Default: 1.
 .BI numjobs \fR=\fPint
 Number of clones (processes/threads performing the same workload) of this job.
 Default: 1.


@@ -2143,10 +2171,11 @@ scripted use.
 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
 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
 .P
 .RS

-.B terse version, fio version, jobname, groupid, error
+.B terse version, fio version [v3], jobname, groupid, error

 .P
 Read status:
 .RS
 .P
 Read status:
 .RS


@@ -2170,7 +2199,11 @@ Total latency:
 .RE
 Bandwidth:
 .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
 .RE
 .P


@@ -2196,10 +2229,19 @@ Total latency:
 .RE
 Bandwidth:
 .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
 .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
 CPU usage:
 .RS
 .B user, system, context switches, major page faults, minor page faults


@@ -2222,7 +2264,7 @@ Milliseconds:
 .RE
 .RE
 .P
 .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
 .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


@@ -2234,6 +2276,15 @@ Error Info (dependent on continue_on_error, default off):
 .P
 .B text description (if provided in config - appears on newline)
 .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
 .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


@@ -2587,7 +2638,7 @@ Sample jobfiles are available in the \fBexamples\fR directory.
 .br
 These are typically located under /usr/share/doc/fio.
 
 .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
 .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
 .br