- Fixed a bunch of typos and formatting errors.
- Wrapped some overly-long lines.
- Added a few new default parameter values.
Signed-off-by: Jens Axboe <jens.axboe@oracle.com>
Generate per-job bandwidth logs.
.TP
.B \-\-minimal
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.
.TP
.BI \-\-showcmd \fR=\fPjobfile
Convert \fIjobfile\fR to a set of command-line options.
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
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
+considered a comment and ignored.
job files.
.SS "Global Section"
The global section contains default parameters for jobs specified in the
job files.
.SS "Global Section"
The global section contains default parameters for jobs specified in the
.TP
.I irange
Integer range: a range of integers specified in the format
.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
.SS "Parameter List"
.TP
.BI name \fR=\fPstr
.BI filename \fR=\fPstr
.B fio
normally makes up a file name based on the job name, thread number, and file
.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.
.TP
.BI opendir \fR=\fPstr
Recursively open any files below directory \fIstr\fR.
-Mixed sequential reads and writes
+Mixed sequential reads and writes.
-Mixed random reads and writes
+Mixed random reads and writes.
-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
.RE
.TP
.BI randrepeat \fR=\fPbool
Seed the random number generator in a predictable way so results are repeatable
+across runs. Default: true.
.TP
.BI fadvise_hint \fR=\fPbool
.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 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
.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
Block size for I/O units. Default: 4k. Values for reads and writes can be
.TP
.BI blocksize \fR=\fPsiint "\fR,\fB bs" \fR=\fPsiint
Block size for I/O units. Default: 4k. Values for reads and writes can be
which may be empty to leave that value at its default.
.TP
.BI blocksize_range \fR=\fPirange "\fR,\fB bsrange" \fR=\fPirange
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).
+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, but can be specified seperately (see \fBblocksize\fR).
.TP
.B blocksize_unaligned\fR,\fP bs_unaligned
.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.
.TP
.B zero_buffers
Initialise buffers with all zeros. Default: fill buffers with random data.
glibc POSIX asynchronous I/O using \fIaio_read\fR\|(3) and \fIaio_write\fR\|(3).
.TP
.B mmap
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).
-\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
.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
.TP
.B null
Doesn't transfer any data, just pretends to. Mainly used to exercise \fBfio\fR
.B guasi
The GUASI I/O engine is the Generic Userspace Asynchronous Syscall Interface
approach to asycnronous I/O.
.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
.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
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
.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
.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
.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
.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 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
\fBwrmixwrite\fR are given and do not sum to 100%, the latter of the two
+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
.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,
.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:
.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
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
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
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 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
.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
.TP
.BI verify_interval \fR=\fPsiint
Write the verification header for this number of bytes, which should divide
-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
\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
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
read.
.TP
.BI write_iolog \fR=\fPstr
given time in milliseconds.
.TP
.BI disk_util \fR=\fPbool
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.
-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:
Threads: 1: [_r] [24.8% done] [ 13509/ 8334 kb/s] [eta 00h:01m:31s]
.RE
.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
.B \-
Exited, thread reaped.
.RE
.B \-
Exited, thread reaped.
.RE
.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,
.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
Per-thread statistics first show the threads client number, group-id, and
error code. The remaining figures are as follows:
.RS
.TP
.B io
Number of megabytes of I/O performed.
.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
Distribution of I/O completion latencies. The numbers follow the same pattern
as \fBIO depths\fR.
.RE
.P
The group statistics show:
.P
The group statistics show:
Maximum average bandwidth a thread saw.
.TP
.B mint
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
.TP
.B maxt
Longest runtime of threads in the group.
.RE
.P
Finally, disk statistics are printed with reads first:
.P
Finally, disk statistics are printed with reads first:
.B util
Disk utilization.
.RE
.B util
Disk utilization.
.RE
.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:
.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:
.RS
.B user, system, context switches
.RE
.RS
.B user, system, context switches
.RE
.SH AUTHORS
.B fio
was written by Jens Axboe <jens.axboe@oracle.com>.
.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"
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.
-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.