Generate per-job bandwidth logs.
.TP
.B \-\-minimal
-Print statistics in a terse, semicolon\-delimited format.
+Print statistics in a terse, semicolon-delimited format.
.TP
.BI \-\-showcmd \fR=\fPjobfile
Convert \fIjobfile\fR to a set of command-line options.
Specifies when real-time ETA estimate should be printed. \fIwhen\fR may
be one of `always', `never' or `auto'.
.TP
+.BI \-\-section \fR=\fPsec
+Only run section \fIsec\fR from job file.
+.TP
.BI \-\-cmdhelp \fR=\fPcommand
Print help information for \fIcommand\fR. May be `all' for all commands.
.TP
+.BI \-\-debug \fR=\fPtype
+Enable verbose tracing of various fio actions. May be `all' for all types
+or individual types seperated by a comma (eg --debug=io,file). `help' will
+list all available tracing options.
+.TP
.B \-\-help
Display usage information and exit.
.TP
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. See section EXAMPLES for sample
-job files.
+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,
.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'.
+\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'.
.SS "Parameter List"
.TP
.BI name \fR=\fPstr
-May be used to override the job name. On the command line, this paramter
+May be used to override the job name. On the command line, this parameter
has the special purpose of signalling the start of a new job.
.TP
.BI description \fR=\fPstr
.BI filename \fR=\fPstr
.B fio
normally makes up a file name based on the job name, thread number, and file
-number. If you want to share files between threads in a job or several jobs, specify
-a \fIfilename\fR for each of them to override the default. If the I/O engine used is
-`net', \fIfilename\fR is the host and port to connect to in the format
-\fIhost\fR/\fIport\fR. If the I/O engine is file-based, you can specify a number of
-files by separating the names with a `:' character. `-' is a reserved name, meaning
-stdin or stdout, depending on the read/write direction set.
+number. If you want to share files between threads in a job or several jobs,
+specify a \fIfilename\fR for each of them to override the default. If the I/O
+engine used is `net', \fIfilename\fR is the host and port to connect to in the
+format \fIhost\fR/\fIport\fR. If the I/O engine is file-based, you can specify
+a number of files by separating the names with a `:' character. `\-' is a
+reserved name, meaning stdin or stdout, depending on the read/write direction
+set.
.TP
.BI opendir \fR=\fPstr
Recursively open any files below directory \fIstr\fR.
.RS
.TP
.B read
-Sequential reads
+Sequential reads.
.TP
.B write
-Sequential writes
+Sequential writes.
.TP
.B randread
-Random reads
+Random reads.
.TP
.B randwrite
-Random writes
+Random writes.
.TP
.B rw
-Mixed sequential reads and writes
+Mixed sequential reads and writes.
.TP
.B randrw
-Mixed random reads and writes
+Mixed random reads and writes.
.RE
.P
-For mixed I/O, the default split is 50/50. For random I/O, the number of I/Os to
-perform before getting a new offset can be specified by appending `:\fIint\fR' to
-the pattern type. The default is 1.
+For mixed I/O, the default split is 50/50. For random I/O, the number of I/Os
+to perform before getting a new offset can be specified by appending
+`:\fIint\fR' to the pattern type. The default is 1.
.RE
.TP
.BI randrepeat \fR=\fPbool
Seed the random number generator in a predictable way so results are repeatable
-across runs.
+across runs. Default: true.
.TP
.BI fadvise_hint \fR=\fPbool
-Disable use of \fIposix_fadvise\fR\|(2) to advise the kernel what I/O patters are
-likely to be issued. Default: true.
+Disable use of \fIposix_fadvise\fR\|(2) to advise the kernel what I/O patterns
+are likely to be issued. Default: true.
.TP
.BI size \fR=\fPsiint
Total size of I/O for this job. \fBfio\fR will run until this many bytes have
.TP
.BI filesize \fR=\fPirange
Individual file sizes. May be a range, in which case \fBfio\fR will select sizes
-for files at random within the given range, limited to \fBsize\fR in total (if that
-is given). If \fBfilesize\fR is not specified, each created file is the same size.
+for files at random within the given range, limited to \fBsize\fR in total (if
+that is given). If \fBfilesize\fR is not specified, each created file is the
+same size.
.TP
-.BI blocksize \fR=\fPsiint "\fR,\fB bs" \fR=\fPsiint
+.BI blocksize \fR=\fPsiint[,siint] "\fR,\fB bs" \fR=\fPsiint[,siint]
Block size for I/O units. Default: 4k. Values for reads and writes can be
specified seperately in the format \fIread\fR,\fIwrite\fR, either of
which may be empty to leave that value at its default.
.TP
-.BI blocksize_range \fR=\fPirange "\fR,\fB bsrange" \fR=\fPirange
-Specify a range of I/O block sizes. The issued I/O unit will always be a multiple
-of the minimum size, unless \fBblocksize_unaligned\fR is set. Applied to both reads
-and writes, but can be specified seperately (see \fBblocksize\fR).
+.BI blocksize_range \fR=\fPirange[,irange] "\fR,\fB bsrange" \fR=\fPirange[,irange]
+Specify a range of I/O block sizes. The issued I/O unit will always be a
+multiple of the minimum size, unless \fBblocksize_unaligned\fR is set. Applies
+to both reads and writes if only one range is given, but can be specified
+seperately with a comma seperating the values. Example: bsrange=1k-4k,2k-8k.
+Also (see \fBblocksize\fR).
+.TP
+.BI bssplit \fR=\fPstr
+This option allows even finer grained control of the block sizes issued,
+not just even splits between them. With this option, you can weight various
+block sizes for exact control of the issued IO for a job that has mixed
+block sizes. The format of the option is bssplit=blocksize/percentage,
+optionally adding as many definitions as needed seperated by a colon.
+Example: bssplit=4k/10:64k/50:32k/40 would issue 50% 64k blocks, 10% 4k
+blocks and 40% 32k blocks.
.TP
.B blocksize_unaligned\fR,\fP bs_unaligned
-If set, any size in \fBblocksize_range\fR may be used. This typically won't work
-with direct I/O, as that normally requires sector alignment.
+If set, any size in \fBblocksize_range\fR may be used. This typically won't
+work with direct I/O, as that normally requires sector alignment.
.TP
.B zero_buffers
Initialise buffers with all zeros. Default: fill buffers with random data.
Basic \fIread\fR\|(2) or \fIwrite\fR\|(2) I/O. \fIfseek\fR\|(2) is used to
position the I/O location.
.TP
+.B psync
+Basic \fIpread\fR\|(2) or \fIpwrite\fR\|(2) I/O.
+.TP
+.B vsync
+Basic \fIreadv\fR\|(2) or \fIwritev\fR\|(2) I/O. Will emulate queuing by
+coalescing adjacents IOs into a single submission.
+.TP
.B libaio
Linux native asynchronous I/O.
.TP
glibc POSIX asynchronous I/O using \fIaio_read\fR\|(3) and \fIaio_write\fR\|(3).
.TP
.B mmap
-File is memory mapped with \fImmap\fR\|(2) and data coped using \fImemcpy\fR\|(3).
+File is memory mapped with \fImmap\fR\|(2) and data copied using
+\fImemcpy\fR\|(3).
.TP
.B splice
-\fIsplice\fR\|(2) is used to transfer the data and \fIvmsplice\fR\|(2) to transfer
-data from user-space to the kernel.
+\fIsplice\fR\|(2) is used to transfer the data and \fIvmsplice\fR\|(2) to
+transfer data from user-space to the kernel.
.TP
.B syslet-rw
Use the syslet system calls to make regular read/write asynchronous.
.TP
.B sg
SCSI generic sg v3 I/O. May be either synchronous using the SG_IO ioctl, or if
-the target is an sg character device, we use \fIread\fR\|(2) and \fIwrite\fR\|(2)
-for asynchronous I/O.
+the target is an sg character device, we use \fIread\fR\|(2) and
+\fIwrite\fR\|(2) for asynchronous I/O.
.TP
.B null
Doesn't transfer any data, just pretends to. Mainly used to exercise \fBfio\fR
Like \fBnet\fR, but uses \fIsplice\fR\|(2) and \fIvmsplice\fR\|(2) to map data
and send/receive.
.TP
-.B cpu
+.B cpuio
Doesn't transfer any data, but burns CPU cycles according to \fBcpuload\fR and
\fBcpucycles\fR parameters.
.TP
.B guasi
The GUASI I/O engine is the Generic Userspace Asynchronous Syscall Interface
approach to asycnronous I/O.
-
-See <http://www.xmailserver.org/guasi-lib.html>.
+.br
+See <http://www.xmailserver.org/guasi\-lib.html>.
.TP
.B external
Loads an external I/O engine object file. Append the engine filename as
Offset in the file to start I/O. Data before the offset will not be touched.
.TP
.BI fsync \fR=\fPint
-How many I/Os to perform before issuing an \fBfsync\fR\|(2) of dirty data. If 0, don't
-sync. Default: 0.
+How many I/Os to perform before issuing an \fBfsync\fR\|(2) of dirty data. If
+0, don't sync. Default: 0.
.TP
.BI overwrite \fR=\fPbool
-If writing, setup the file first and do overwrites.
+If writing, setup the file first and do overwrites. Default: false.
.TP
.BI end_fsync \fR=\fPbool
-If true, sync file contents when job exits.
+Sync file contents when job exits. Default: false.
.TP
.BI fsync_on_close \fR=\fPbool
If true, sync file contents on close. This differs from \fBend_fsync\fR in that
-it will happen on every close, not just at the end of the job.
+it will happen on every close, not just at the end of the job. Default: false.
.TP
.BI rwmixcycle \fR=\fPint
How many milliseconds before switching between reads and writes for a mixed
Percentage of a mixed workload that should be reads. Default: 50.
.TP
.BI rwmixwrite \fR=\fPint
-Percentage of a mixed workload that would be writes. If \fBrwmixread\fR and
+Percentage of a mixed workload that should be writes. If \fBrwmixread\fR and
\fBwrmixwrite\fR are given and do not sum to 100%, the latter of the two
-overrides the first.
+overrides the first. Default: 50.
.TP
.B norandommap
Normally \fBfio\fR will cover every block of the file when doing random I/O. If
.TP
.BI sync \fR=\fPbool
Use synchronous I/O for buffered writes. For the majority of I/O engines,
-this means using O_SYNC.
+this means using O_SYNC. Default: false.
.TP
.BI iomem \fR=\fPstr "\fR,\fP mem" \fR=\fPstr
Allocation method for I/O unit buffer. Allowed values are:
have hugetlbfs mounted, and \fIfile\fR must point there.
.RE
.TP
-.BI hugepage-size \fR=\fPsiint
+.BI hugepage\-size \fR=\fPsiint
Defines the size of a huge page. Must be at least equal to the system setting.
Should be a multiple of 1MiB. Default: 4MiB.
.TP
500ms.
.TP
.BI create_serialize \fR=\fPbool
-If true, serialize file creation for the jobs.
+If true, serialize file creation for the jobs. Default: true.
.TP
.BI create_fsync \fR=\fPbool
\fIfsync\fR\|(2) data file after creation. Default: true.
.TP
.BI verify_offset \fR=\fPsiint
Swap the verification header with data somewhere else in the block before
-writing. It it swapped back before verifying.
+writing. It is swapped back before verifying.
.TP
.BI verify_interval \fR=\fPsiint
Write the verification header for this number of bytes, which should divide
false.
.TP
.B stonewall
-Wait for precedding jobs in the job file to exit before starting this one.
+Wait for preceeding jobs in the job file to exit before starting this one.
\fBstonewall\fR implies \fBnew_group\fR.
.TP
.B new_group
Divide file into zones of the specified size in bytes. See \fBzoneskip\fR.
.TP
.BI zoneskip \fR=\fPsiint
-Skip the specified number of bytes when \fBzonesize\fR bytes of data has been
+Skip the specified number of bytes when \fBzonesize\fR bytes of data have been
read.
.TP
.BI write_iolog \fR=\fPstr
given time in milliseconds.
.TP
.BI disk_util \fR=\fPbool
-Generate disk utilization statistics if the platform supports it. Default: true.
+Generate disk utilization statistics if the platform supports it. Default: true.
.SH OUTPUT
-While running, \fBfio\fR will display the status of the created jobs. For example:
+While running, \fBfio\fR will display the status of the created jobs. For
+example:
.RS
+.P
Threads: 1: [_r] [24.8% done] [ 13509/ 8334 kb/s] [eta 00h:01m:31s]
.RE
.P
-The characters in the first set of brackets denote the current status of each threads.
-The possible values are:
-.RS
+The characters in the first set of brackets denote the current status of each
+threads. The possible values are:
+.P
+.PD 0
.RS
.TP
.B P
.B \-
Exited, thread reaped.
.RE
-.RE
+.PD
.P
The second set of brackets shows the estimated completion percentage of
the current group. The third set shows the read and write I/O rate,
Per-thread statistics first show the threads client number, group-id, and
error code. The remaining figures are as follows:
.RS
-.RS
.TP
.B io
Number of megabytes of I/O performed.
Distribution of I/O completion latencies. The numbers follow the same pattern
as \fBIO depths\fR.
.RE
-.RE
.P
The group statistics show:
-.RS
+.PD 0
.RS
.TP
.B io
Maximum average bandwidth a thread saw.
.TP
.B mint
-Smallest runtime of threads in the group.
+Shortest runtime of threads in the group.
.TP
.B maxt
Longest runtime of threads in the group.
.RE
-.RE
+.PD
.P
Finally, disk statistics are printed with reads first:
-.RS
+.PD 0
.RS
.TP
.B ios
.B util
Disk utilization.
.RE
-.RE
+.PD
.SH TERSE OUTPUT
If the \fB\-\-minimal\fR option is given, the results will be printed in a
semicolon-delimited format suitable for scripted use. The fields are:
.RE
.RE
.P
-CPU usage;
+CPU usage:
.RS
.B user, system, context switches
.RE
.SH AUTHORS
.B fio
was written by Jens Axboe <jens.axboe@oracle.com>.
-This man page was
-written by Aaron Carroll <aaronc@cse.unsw.edu.au> based
+.br
+This man page was written by Aaron Carroll <aaronc@cse.unsw.edu.au> based
on documentation by Jens Axboe.
.SH "REPORTING BUGS"
-Report bugs to the \fBfio\fR mailing list <fio-devel@kernel.dk>. See \fBREADME\fR.
+Report bugs to the \fBfio\fR mailing list <fio-devel@kernel.dk>.
+See \fBREADME\fR.
.SH "SEE ALSO"
-Further documentation is available in \fBfio\fR's \fBHOWTO\fR and \fBREADME\fR.
-Sample jobfiles are available in \fBfio\fR's \fBexamples/\fR directory.
+For further documentation see \fBHOWTO\fR and \fBREADME\fR.
+.br
+Sample jobfiles are available in the \fBexamples\fR directory.