man: sync "JOB FILE FORMAT" section with HOWTO

[fio.git] / fio.1

diff --git a/fio.1 b/fio.1
index 39ccd63d3eeb5b7ac353628bd3fcdd5c2f2405a0..b22989a0f46613b459bd48d1c636c941bbd2a429 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -1,4 +1,4 @@
-.TH fio 1 "May 2017" "User Manual"
+.TH fio 1 "July 2017" "User Manual"

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


@@ -14,8 +14,11 @@ one wants to simulate.
 .TP
 .BI \-\-debug \fR=\fPtype
 Enable verbose tracing of various fio actions. May be `all' for all types
 .TP
 .BI \-\-debug \fR=\fPtype
 Enable verbose tracing of various fio actions. May be `all' for all types

-or individual types separated by a comma (eg \-\-debug=io,file). `help' will
-list all available tracing options.
+or individual types separated by a comma (e.g. \-\-debug=file,mem will enable
+file and memory debugging). `help' will list all available tracing options.
+.TP
+.BI \-\-parse-only
+Parse options only, don't start any I/O.

 .TP
 .BI \-\-output \fR=\fPfilename
 Write output to \fIfilename\fR.
 .TP
 .BI \-\-output \fR=\fPfilename
 Write output to \fIfilename\fR.


@@ -39,84 +42,148 @@ Print statistics in a terse, semicolon-delimited format.
 Print statistics in selected mode AND terse, semicolon-delimited format.
 Deprecated, use \-\-output-format instead to select multiple formats.
 .TP
 Print statistics in selected mode AND terse, semicolon-delimited format.
 Deprecated, use \-\-output-format instead to select multiple formats.
 .TP

-.B \-\-version
-Display version information and exit.
-.TP

 .BI \-\-terse\-version \fR=\fPversion
 .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 \-\-version
+Print version information and exit.

 .TP
 .B \-\-help
 .TP
 .B \-\-help

-Display usage information and exit.
+Print a summary of the command line options and exit.

 .TP
 .B \-\-cpuclock-test
 .TP
 .B \-\-cpuclock-test

-Perform test and validation of internal CPU clock
+Perform test and validation of internal CPU clock.

 .TP
 .TP

-.BI \-\-crctest[\fR=\fPtest]
-Test the speed of the builtin checksumming functions. If no argument is given,
-all of them are tested. Or a comma separated list can be passed, in which
+.BI \-\-crctest \fR=\fP[test]
+Test the speed of the built-in checksumming functions. If no argument is given,
+all of them are tested. Alternatively, a comma separated list can be passed, in which

 case the given ones are tested.
 .TP
 .BI \-\-cmdhelp \fR=\fPcommand
 case the given ones are tested.
 .TP
 .BI \-\-cmdhelp \fR=\fPcommand

-Print help information for \fIcommand\fR.  May be `all' for all commands.
+Print help information for \fIcommand\fR. May be `all' for all commands.

 .TP
 .BI \-\-enghelp \fR=\fPioengine[,command]
 List all commands defined by \fIioengine\fR, or print help for \fIcommand\fR defined by \fIioengine\fR.
 .TP
 .BI \-\-enghelp \fR=\fPioengine[,command]
 List all commands defined by \fIioengine\fR, or print help for \fIcommand\fR defined by \fIioengine\fR.

+If no \fIioengine\fR is given, list all available ioengines.

 .TP
 .BI \-\-showcmd \fR=\fPjobfile
 Convert \fIjobfile\fR to a set of command-line options.
 .TP
 .TP
 .BI \-\-showcmd \fR=\fPjobfile
 Convert \fIjobfile\fR to a set of command-line options.
 .TP

+.BI \-\-readonly
+Turn on safety read-only checks, preventing writes. The \-\-readonly
+option is an extra safety guard to prevent users from accidentally starting
+a write workload when that is not desired. Fio will only write if
+`rw=write/randwrite/rw/randrw` is given. This extra safety net can be used
+as an extra precaution as \-\-readonly will also enable a write check in
+the I/O engine core to prevent writes due to unknown user space bug(s).
+.TP

 .BI \-\-eta \fR=\fPwhen
 .BI \-\-eta \fR=\fPwhen

-Specifies when real-time ETA estimate should be printed.  \fIwhen\fR may
-be one of `always', `never' or `auto'.
+Specifies when real-time ETA estimate should be printed. \fIwhen\fR may
+be `always', `never' or `auto'.

 .TP
 .BI \-\-eta\-newline \fR=\fPtime
 .TP
 .BI \-\-eta\-newline \fR=\fPtime

-Force an ETA newline for every `time` period passed.
+Force a new line for every \fItime\fR period passed. When the unit is omitted,
+the value is interpreted in seconds.

 .TP
 .BI \-\-status\-interval \fR=\fPtime
 .TP
 .BI \-\-status\-interval \fR=\fPtime

-Report full output status every `time` period passed.
-.TP
-.BI \-\-readonly
-Turn on safety read-only checks, preventing any attempted write.
-.TP
-.BI \-\-section \fR=\fPsec
-Only run section \fIsec\fR from job file. This option can be used multiple times to add more sections to run.
+Force full status dump every \fItime\fR period passed. When the unit is omitted,
+the value is interpreted in seconds.
+.TP
+.BI \-\-section \fR=\fPname
+Only run specified section \fIname\fR in job file. Multiple sections can be specified.
+The \-\-section option allows one to combine related jobs into one file.
+E.g. one job file could define light, moderate, and heavy sections. Tell
+fio to run only the "heavy" section by giving \-\-section=heavy
+command line option. One can also specify the "write" operations in one
+section and "verify" operation in another section. The \-\-section option
+only applies to job sections. The reserved *global* section is always
+parsed and used.

 .TP
 .BI \-\-alloc\-size \fR=\fPkb
 .TP
 .BI \-\-alloc\-size \fR=\fPkb

-Set the internal smalloc pool size to \fIkb\fP kilobytes.
+Set the internal smalloc pool size to \fIkb\fP in KiB. The
+\-\-alloc-size switch allows one to use a larger pool size for smalloc.
+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.
+NOTE: While running .fio_smalloc.* backing store files are visible
+in /tmp.

 .TP
 .BI \-\-warnings\-fatal
 All fio parser warnings are fatal, causing fio to exit with an error.
 .TP
 .BI \-\-max\-jobs \fR=\fPnr
 .TP
 .BI \-\-warnings\-fatal
 All fio parser warnings are fatal, causing fio to exit with an error.
 .TP
 .BI \-\-max\-jobs \fR=\fPnr

-Set the maximum allowed number of jobs (threads/processes) to support.
+Set the maximum number of threads/processes to support.

 .TP
 .BI \-\-server \fR=\fPargs
 .TP
 .BI \-\-server \fR=\fPargs

-Start a backend server, with \fIargs\fP specifying what to listen to. See client/server section.
+Start a backend server, with \fIargs\fP specifying what to listen to. See Client/Server section.

 .TP
 .BI \-\-daemonize \fR=\fPpidfile
 .TP
 .BI \-\-daemonize \fR=\fPpidfile

-Background a fio server, writing the pid to the given pid file.
+Background a fio server, writing the pid to the given \fIpidfile\fP file.
+.TP
+.BI \-\-client \fR=\fPhostname
+Instead of running the jobs locally, send and run them on the given host or set of hosts. See Client/Server section.

 .TP
 .TP

-.BI \-\-client \fR=\fPhost
-Instead of running the jobs locally, send and run them on the given host or set of hosts.  See client/server section.
+.BI \-\-remote-config \fR=\fPfile
+Tell fio server to load this local file.

 .TP
 .BI \-\-idle\-prof \fR=\fPoption
 .TP
 .BI \-\-idle\-prof \fR=\fPoption

-Report cpu idleness on a system or percpu basis (\fIoption\fP=system,percpu) or run unit work calibration only (\fIoption\fP=calibrate).
+Report CPU idleness. \fIoption\fP is one of the following:
+.RS
+.RS
+.TP
+.B calibrate
+Run unit work calibration only and exit.
+.TP
+.B system
+Show aggregate system idleness and unit work.
+.TP
+.B percpu
+As "system" but also show per CPU idleness.
+.RE
+.RE
+.TP
+.BI \-\-inflate-log \fR=\fPlog
+Inflate and output compressed log.
+.TP
+.BI \-\-trigger-file \fR=\fPfile
+Execute trigger cmd when file exists.
+.TP
+.BI \-\-trigger-timeout \fR=\fPt
+Execute trigger at this time.
+.TP
+.BI \-\-trigger \fR=\fPcmd
+Set this command as local trigger.
+.TP
+.BI \-\-trigger-remote \fR=\fPcmd
+Set this command as remote trigger.
+.TP
+.BI \-\-aux-path \fR=\fPpath
+Use this path for fio state generated files.

 .SH "JOB FILE FORMAT"
 .SH "JOB FILE FORMAT"

-Job files are in `ini' format. They consist of one or more
-job definitions, which begin with a job name in square brackets and
-extend to the next job name.  The job name can be any ASCII string
-except `global', which has a special meaning.  Following the job name is
-a sequence of zero or more parameters, one per line, that define the
-behavior of the job.  Any line starting with a `;' or `#' character is
-considered a comment and ignored.
-.P
-If \fIjobfile\fR is specified as `-', the job file will be read from
-standard input.
-.SS "Global Section"
-The global section contains default parameters for jobs specified in the
-job file.  A job is only affected by global sections residing above it,
-and there may be any number of global sections.  Specific job definitions
-may override any parameter set in global sections.
+Any parameters following the options will be assumed to be job files, unless
+they match a job file parameter. Multiple job files can be listed and each job
+file will be regarded as a separate group. Fio will `stonewall` execution
+between each group.
+
+Fio accepts one or more job files describing what it is
+supposed to do. The job file format is the classic ini file, where the names
+enclosed in [] brackets define the job name. You are free to use any ASCII name
+you want, except *global* which has special meaning. Following the job name is
+a sequence of zero or more parameters, one per line, that define the behavior of
+the job. If the first character in a line is a ';' or a '#', the entire line is
+discarded as a comment.
+
+A *global* section sets defaults for the jobs described in that file. A job may
+override a *global* section parameter, and a job file may even have several
+*global* sections if so desired. A job is only affected by a *global* section
+residing above it.
+
+The \-\-cmdhelp option also lists all options. If used with an `option`
+argument, \-\-cmdhelp will detail the given `option`.
+
+See the `examples/` directory in the fio source for inspiration on how to write
+job files. Note the copyright and license requirements currently apply to
+`examples/` files.

 .SH "JOB PARAMETERS"
 .SS Types
 Some parameters may take arguments of a specific type.
 .SH "JOB PARAMETERS"
 .SS Types
 Some parameters may take arguments of a specific type.


@@ -436,6 +503,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 +521,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


@@ -611,13 +683,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 +711,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 +748,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,11 +986,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

-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 \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.
+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


@@ -995,8 +1079,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


@@ -1008,8 +1092,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


@@ -2154,10 +2238,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


@@ -2181,7 +2266,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


@@ -2207,8 +2296,17 @@ 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
 .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:
 .RE
 .P
 CPU usage:


@@ -2233,7 +2331,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


@@ -2245,6 +2343,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