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 f491c533272dc85ff685c6cbc74a5e092d905b6a..2f60b5e88559ebf81e9462ae33affce8a513768e 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -25,7 +25,7 @@ Generate per-job latency logs.
 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 @@ 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.  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 @@ Boolean: a true or false value. `0' denotes false, `1' denotes true.
 .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 @@ than `./'.
 .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 @@ Type of I/O pattern.  Accepted values are:
 .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 @@ divided between the available files for the job.
 .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 @@ 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).
+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 @@ Linux native asynchronous I/O.
 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 @@ Doesn't transfer any data, but burns CPU cycles according to \fBcpuload\fR and
 .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 @@ Default: true.
 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 @@ workload. Default: 500ms.
 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 @@ Invalidate buffer-cache for the file prior to starting I/O.  Default: true.
 .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 @@ the system must have free huge pages allocated.  \fBmmaphuge\fR also needs to
 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 @@ Average bandwidth calculations over the given time in milliseconds.  Default:
 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 @@ read them back in a sorted manner.  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
@@ -467,7 +471,7 @@ If true, exit the job on the first observed verification failure.  Default:
 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 @@ with \fBfork\fR\|(2).
 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 @@ If the job is a CPU cycle-eater, split the load into cycles of the
 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 @@ Exited, not reaped by main thread.
 .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 @@ for each thread, each group of threads, and each disk, in that order.
 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 @@ Number of read/write requests issued, and number of short read/write requests.
 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 @@ Minimum average bandwidth a thread saw.
 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 @@ Total time spent in the disk queue.
 .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 @@ Bandwidth:
 .RE
 .RE
 .P
-CPU usage;
+CPU usage:
 .RS
 .B user, system, context switches
 .RE
@@ -738,12 +743,14 @@ IO latency distribution (ms):
 .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.