General fio.1 improvements
- 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>
diff --git a/fio.1 b/fio.1
index f491c53..2f60b5e 100644
--- a/fio.1
+++ b/fio.1
@@ -25,7 +25,7 @@
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.
@@ -52,7 +52,7 @@
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
@@ -80,9 +80,10 @@
.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
@@ -100,12 +101,13 @@
.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.
@@ -116,36 +118,36 @@
.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
@@ -155,8 +157,9 @@
.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
@@ -164,13 +167,13 @@
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
-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.
@@ -213,19 +216,20 @@
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
@@ -247,8 +251,8 @@
.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
@@ -277,18 +281,18 @@
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
@@ -298,9 +302,9 @@
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
@@ -369,7 +373,7 @@
.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:
@@ -399,7 +403,7 @@
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
@@ -411,7 +415,7 @@
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.
@@ -456,7 +460,7 @@
.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
@@ -467,7 +471,7 @@
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
@@ -490,7 +494,7 @@
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
@@ -528,16 +532,19 @@
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
@@ -579,7 +586,7 @@
.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,
@@ -591,7 +598,6 @@
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.
@@ -629,10 +635,9 @@
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
@@ -648,15 +653,15 @@
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
@@ -674,7 +679,7 @@
.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:
@@ -718,7 +723,7 @@
.RE
.RE
.P
-CPU usage;
+CPU usage:
.RS
.B user, system, context switches
.RE
@@ -738,12 +743,14 @@
.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.