.BI \-\-aux-path \fR=\fPpath
Use this path for fio state generated files.
.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.
-.SH "JOB PARAMETERS"
-.SS Types
-Some parameters may take arguments of a specific type.
-Anywhere a numeric value is required, an arithmetic expression may be used,
-provided it is surrounded by parentheses. Supported operators are:
+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 FILE PARAMETERS"
+Some parameters take an option of a given type, such as an integer or a
+string. Anywhere a numeric value is required, an arithmetic expression may be
+used, provided it is surrounded by parentheses. Supported operators are:
.RS
.RS
.TP
.P
For time values in expressions, units are microseconds by default. This is
different than for time values not in expressions (not enclosed in
-parentheses). The types used are:
+parentheses).
+.SH "PARAMETER TYPES"
+The following parameter types are used.
.TP
.I str
-String: a sequence of alphanumeric characters.
+String. A sequence of alphanumeric characters.
+.TP
+.I time
+Integer with possible time suffix. Without a unit value is interpreted as
+seconds unless otherwise specified. Accepts a suffix of 'd' for days, 'h' for
+hours, 'm' for minutes, 's' for seconds, 'ms' (or 'msec') for milliseconds and 'us'
+(or 'usec') for microseconds. For example, use 10m for 10 minutes.
.TP
.I int
Integer. A whole number value, which may contain an integer prefix
and an integer suffix.
-[integer prefix]number[integer suffix]
+[*integer prefix*] **number** [*integer suffix*]
+
+The optional *integer prefix* specifies the number's base. The default
+is decimal. *0x* specifies hexadecimal.
-The optional integer prefix specifies the number's base. The default
-is decimal. 0x specifies hexadecimal.
+The optional *integer suffix* specifies the number's units, and includes an
+optional unit prefix and an optional unit. For quantities of data, the
+default unit is bytes. For quantities of time, the default unit is seconds
+unless otherwise specified.
-The optional integer suffix specifies the number's units, and includes
-an optional unit prefix and an optional unit. For quantities
-of data, the default unit is bytes. For quantities of time,
-the default unit is seconds.
+With \fBkb_base=1000\fR, fio follows international standards for unit
+prefixes. To specify power-of-10 decimal values defined in the
+International System of Units (SI):
-With \fBkb_base=1000\fR, fio follows international standards for unit prefixes.
-To specify power-of-10 decimal values defined in the International
-System of Units (SI):
.nf
ki means kilo (K) or 1000
mi means mega (M) or 1000**2
.fi
To specify power-of-2 binary values defined in IEC 80000-13:
+
.nf
k means kibi (Ki) or 1024
m means mebi (Mi) or 1024**2
p means pebi (Pi) or 1024**5
.fi
-With \fBkb_base=1024\fR (the default), the unit prefixes are opposite from
-those specified in the SI and IEC 80000-13 standards to provide
-compatibility with old scripts. For example, 4k means 4096.
+With \fBkb_base=1024\fR (the default), the unit prefixes are opposite
+from those specified in the SI and IEC 80000-13 standards to provide
+compatibility with old scripts. For example, 4k means 4096.
+
+For quantities of data, an optional unit of 'B' may be included
+(e.g., 'kB' is the same as 'k').
+
+The *integer suffix* is not case sensitive (e.g., m/mi mean mebi/mega,
+not milli). 'b' and 'B' both mean byte, not bit.
-.nf
Examples with \fBkb_base=1000\fR:
+
+.nf
4 KiB: 4096, 4096b, 4096B, 4k, 4kb, 4kB, 4K, 4KB
1 MiB: 1048576, 1m, 1024k
1 MB: 1000000, 1mi, 1000ki
1 TB: 1000000000, 1ti, 1000mi, 1000000ki
.fi
-.nf
Examples with \fBkb_base=1024\fR (default):
+
+.nf
4 KiB: 4096, 4096b, 4096B, 4k, 4kb, 4kB, 4K, 4KB
1 MiB: 1048576, 1m, 1024k
1 MB: 1000000, 1mi, 1000ki
1 TB: 1000000000, 1ti, 1000mi, 1000000ki
.fi
-For quantities of data, an optional unit of 'B' may be included
-(e.g., 'kb' is the same as 'k').
-
-The integer suffix is not case sensitive (e.g., m/mi mean mebi/mega,
-not milli). 'b' and 'B' both mean byte, not bit.
-
To specify times (units are not case sensitive):
+
.nf
D means days
H means hours
us or usec means microseconds
.fi
+If the option accepts an upper and lower range, use a colon ':' or
+minus '-' to separate such values. See `irange` parameter type.
+If the lower value specified happens to be larger than the upper value
+the two values are swapped.
.TP
.I bool
-Boolean: a true or false value. `0' denotes false, `1' denotes true.
+Boolean. Usually parsed as an integer, however only defined for
+true and false (1 and 0).
.TP
.I irange
-Integer range: a range of integers specified in the format
-\fIlower\fR:\fIupper\fR or \fIlower\fR\-\fIupper\fR. \fIlower\fR and
-\fIupper\fR may contain a suffix as described above. If an option allows two
-sets of ranges, they are separated with a `,' or `/' character. For example:
-`8\-8k/8M\-4G'.
+Integer range with suffix. Allows value range to be given, such as
+1024-4096. A colon may also be used as the separator, e.g. 1k:4k. If the
+option allows two sets of ranges, they can be specified with a ',' or '/'
+delimiter: 1k-4k/8k-32k. Also see `int` parameter type.
.TP
.I float_list
-List of floating numbers: A list of floating numbers, separated by
-a ':' character.
-.SS "Parameter List"
+A list of floating point numbers, separated by a ':' character.
+.SH "JOB DESCRIPTION"
+With the above in mind, here follows the complete list of fio job parameters.
.TP
.BI name \fR=\fPstr
May be used to override the job name. On the command line, this parameter
Fio defaults to read if the option is not specified.
For mixed I/O, the default split is 50/50. For certain types of io the result
may still be skewed a bit, since the speed may be different. It is possible to
-specify a number of IO's to do before getting a new offset, this is done by
+specify a number of IOs to do before getting a new offset, this is done by
appending a `:\fI<nr>\fR to the end of the string given. For a random read, it
would look like \fBrw=randread:8\fR for passing in an offset modifier with a
value of 8. If the postfix is used with a sequential IO pattern, then the value
.P
\fBsequential\fR is only useful for random IO, where fio would normally
generate a new random offset for every IO. If you append eg 8 to randread, you
-would get a new random offset for every 8 IO's. The result would be a seek for
-only every 8 IO's, instead of for every IO. Use \fBrw=randread:8\fR to specify
+would get a new random offset for every 8 IOs. The result would be a seek for
+only every 8 IOs, instead of for every IO. Use \fBrw=randread:8\fR to specify
that. As sequential IO is already sequential, setting \fBsequential\fR for that
would not result in any differences. \fBidentical\fR behaves in a similar
fashion, except it sends the same offset 8 number of times before generating a
.RE
.RE
.TP
-.BI fadvise_stream \fR=\fPint
-Use \fBposix_fadvise\fR\|(2) to advise the kernel what stream ID the
-writes issued belong to. Only supported on Linux. Note, this option
-may change going forward.
+.BI write_hint \fR=\fPstr
+Use \fBfcntl\fR\|(2) to advise the kernel what life time to expect from a write.
+Only supported on Linux, as of version 4.13. The values are all relative to
+each other, and no absolute meaning should be associated with them. Accepted
+values are:
+.RS
+.RS
+.TP
+.B none
+No particular life time associated with this file.
+.TP
+.B short
+Data written to this file has a short life time.
+.TP
+.B medium
+Data written to this file has a medium life time.
+.TP
+.B long
+Data written to this file has a long life time.
+.TP
+.B extreme
+Data written to this file has a very long life time.
+.RE
+.RE
.TP
.BI size \fR=\fPint
Total size of I/O for this job. \fBfio\fR will run until this many bytes have
SYNC_FILE_RANGE_WRITE
.TP
.B wait_after
-SYNC_FILE_RANGE_WRITE
+SYNC_FILE_RANGE_WAIT_AFTER
.TP
.RE
.P
30% of accesses should be to the next 20%
.RE
.RS
-8% of accesses should be to to the next 30%
+8% of accesses should be to the next 30%
.RE
.RS
2% of accesses should be to the next 40%
.TP
.BI log_offset \fR=\fPbool
If this is set, the iolog options will include the byte offset for the IO
-entry as well as the other data values.
+entry as well as the other data values. Defaults to 0 meaning that offsets are
+not present in logs. See the \fBLOG FILE FORMATS\fR section.
.TP
.BI log_compression \fR=\fPint
If this is set, fio will compress the IO logs as it goes, to keep the memory
Set RWF_HIPRI on IO, indicating to the kernel that it's of
higher priority than normal.
.TP
+.BI (pvsync2)hipri_percentage
+When hipri is set this determines the probability of a pvsync2 IO being high
+priority. The default is 100%.
+.TP
.BI (net,netsplice)hostname \fR=\fPstr
The host name or IP address to use for TCP or UDP based IO.
If the job is a TCP listener or UDP reader, the hostname is not
connections rather than initiating an outgoing connection. The
hostname must be omitted if this option is used.
.TP
-.BI (net, pingpong) \fR=\fPbool
+.BI (net,netsplice)pingpong \fR=\fPbool
Normally a network writer will just continue writing data, and a network reader
will just consume packets. If pingpong=1 is set, a writer will send its normal
payload to the reader, then wait for the reader to send the same payload back.
send back. For UDP multicast traffic pingpong=1 should only be set for a single
reader when multiple readers are listening to the same address.
.TP
-.BI (net, window_size) \fR=\fPint
+.BI (net,netsplice)window_size \fR=\fPint
Set the desired socket buffer size for the connection.
.TP
-.BI (net, mss) \fR=\fPint
+.BI (net,netsplice)mss \fR=\fPint
Set the TCP maximum segment size (TCP_MAXSEG).
.TP
-.BI (e4defrag,donorname) \fR=\fPstr
+.BI (e4defrag)donorname \fR=\fPstr
File will be used as a block donor (swap extents between files)
.TP
-.BI (e4defrag,inplace) \fR=\fPint
+.BI (e4defrag)inplace \fR=\fPint
Configure donor file block allocation strategy
.RS
.BI 0(default) :
Number of I/Os performed by all groups.
.TP
.B merge
-Number of merges in the I/O scheduler.
+Number of merges performed by the I/O scheduler.
.TP
.B ticks
Number of ticks we kept the disk busy.
Fio supports a variety of log file formats, for logging latencies, bandwidth,
and IOPS. The logs share a common format, which looks like this:
-.B time (msec), value, data direction, offset
+.B time (msec), value, data direction, block size (bytes), offset (bytes)
Time for the log entry is always in milliseconds. The value logged depends
on the type of log, it will be one of the following:
.PD
.P
-The \fIoffset\fR is the offset, in bytes, from the start of the file, for that
-particular IO. The logging of the offset can be toggled with \fBlog_offset\fR.
+The entry's *block size* is always in bytes. The \fIoffset\fR is the offset, in
+bytes, from the start of the file, for that particular IO. The logging of the
+offset can be toggled with \fBlog_offset\fR.
If windowed logging is enabled through \fBlog_avg_msec\fR, then fio doesn't log
individual IOs. Instead of logs the average values over the specified
-period of time. Since \fIdata direction\fR and \fIoffset\fR are per-IO values,
-they aren't applicable if windowed logging is enabled. If windowed logging
-is enabled and \fBlog_max_value\fR is set, then fio logs maximum values in
-that window instead of averages.
+period of time. Since \fIdata direction\fR, \fIblock size\fR and \fIoffset\fR
+are per-IO values, if windowed logging is enabled they aren't applicable and
+will be 0. If windowed logging is enabled and \fBlog_max_value\fR is set, then
+fio logs maximum values in that window instead of averages.
For histogram logging the logs look like this:
on documentation by Jens Axboe.
.SH "REPORTING BUGS"
Report bugs to the \fBfio\fR mailing list <fio@vger.kernel.org>.
-See \fBREADME\fR.
+.br
+See \fBREPORTING-BUGS\fR.
+
+\fBREPORTING-BUGS\fR: http://git.kernel.dk/cgit/fio/plain/REPORTING-BUGS
.SH "SEE ALSO"
For further documentation see \fBHOWTO\fR and \fBREADME\fR.
.br
projects / fio.git / blobdiff