man page: correct typoe
[fio.git] / fio.1
diff --git a/fio.1 b/fio.1
index 5082bf890fe519eb35f273f047132bed4f88a27d..87bc6a02bfbd856d5f0856a8d1d88098d092b0a0 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -219,12 +219,18 @@ Sequential reads.
 .B write
 Sequential writes.
 .TP
+.B trim
+Sequential trim (Linux block devices only).
+.TP
 .B randread
 Random reads.
 .TP
 .B randwrite
 Random writes.
 .TP
+.B randtrim
+Random trim (Linux block devices only).
+.TP
 .B rw, readwrite
 Mixed sequential reads and writes.
 .TP
@@ -271,7 +277,7 @@ new offset.
 .BI kb_base \fR=\fPint
 The base unit for a kilobyte. The defacto base is 2^10, 1024.  Storage
 manufacturers like to use 10^3 or 1000 as a base ten unit instead, for obvious
-reasons. Allow values are 1024 or 1000, with 1024 being the default.
+reasons. Allowed values are 1024 or 1000, with 1024 being the default.
 .TP
 .BI unified_rw_reporting \fR=\fPbool
 Fio normally reports statistics on a per data direction basis, meaning that
@@ -321,7 +327,7 @@ are likely to be issued. Default: true.
 .TP
 .BI size \fR=\fPint
 Total size of I/O for this job.  \fBfio\fR will run until this many bytes have
-been transfered, unless limited by other options (\fBruntime\fR, for instance).
+been transferred, unless limited by other options (\fBruntime\fR, for instance).
 Unless \fBnrfiles\fR and \fBfilesize\fR options are given, this amount will be
 divided between the available files for the job. If not set, fio will use the
 full size of the given files or devices. If the the files do not exist, size
@@ -344,15 +350,16 @@ that is given). If \fBfilesize\fR is not specified, each created file is the
 same size.
 .TP
 .BI blocksize \fR=\fPint[,int] "\fR,\fB bs" \fR=\fPint[,int]
-Block size for I/O units.  Default: 4k.  Values for reads and writes can be
-specified separately in the format \fIread\fR,\fIwrite\fR, either of
-which may be empty to leave that value at its default.
+Block size for I/O units.  Default: 4k.  Values for reads, writes, and trims
+can be specified separately in the format \fIread\fR,\fIwrite\fR,\fItrim\fR
+either of which may be empty to leave that value at its default. If a trailing
+comma isn't given, the remainder will inherit the last value set.
 .TP
 .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
-separately with a comma seperating the values. Example: bsrange=1k-4k,2k-8k.
+separately with a comma separating the values. Example: bsrange=1k-4k,2k-8k.
 Also (see \fBblocksize\fR).
 .TP
 .BI bssplit \fR=\fPstr
@@ -378,6 +385,12 @@ for using direct IO, though it usually depends on the hardware block size.
 This option is mutually exclusive with using a random map for files, so it
 will turn off that option.
 .TP
+.BI bs_is_seq_rand \fR=\fPbool
+If this option is set, fio will use the normal read,write blocksize settings as
+sequential,random instead. Any random read or write will use the WRITE
+blocksize settings, and any sequential read or write will use the READ
+blocksize setting.
+.TP
 .B zero_buffers
 Initialise buffers with all zeros. Default: fill buffers with random data.
 .TP
@@ -420,10 +433,11 @@ Defines how files to service are selected.  The following types are defined:
 .RS
 .TP
 .B random
-Choose a file at random
+Choose a file at random.
 .TP
 .B roundrobin
 Round robin over open files (default).
+.TP
 .B sequential
 Do each file in the set sequentially.
 .RE
@@ -448,6 +462,9 @@ Basic \fIpread\fR\|(2) or \fIpwrite\fR\|(2) I/O.
 Basic \fIreadv\fR\|(2) or \fIwritev\fR\|(2) I/O. Will emulate queuing by
 coalescing adjacents IOs into a single submission.
 .TP
+.B pvsync
+Basic \fIpreadv\fR\|(2) or \fIpwritev\fR\|(2) I/O.
+.TP
 .B libaio
 Linux native asynchronous I/O. This ioengine defines engine specific options.
 .TP
@@ -566,6 +583,13 @@ that starts at 0 and is incremented for each job. This option is useful if
 there are several jobs which are intended to operate on a file in parallel in
 disjoint segments, with even spacing between the starting points.
 .TP
+.BI number_ios \fR=\fPint
+Fio will normally perform IOs until it has exhausted the size of the region
+set by \fBsize\fR, or if it exhaust the allocated time (or hits an error
+condition). With this setting, the range/size can be set independently of
+the number of IOs to perform. When fio reaches this number, it will exit
+normally and report status.
+.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.
@@ -574,6 +598,9 @@ How many I/Os to perform before issuing an \fBfsync\fR\|(2) of dirty data.  If
 Like \fBfsync\fR, but uses \fBfdatasync\fR\|(2) instead to only sync the
 data parts of the file. Default: 0.
 .TP
+.BI write_barrier \fR=\fPint
+Make every Nth write a barrier write.
+.TP
 .BI sync_file_range \fR=\fPstr:int
 Use sync_file_range() for every \fRval\fP number of write operations. Fio will
 track range of writes that have happened since the last sync_file_range() call.
@@ -645,10 +672,8 @@ fio will disable use of the random map.
 For a random workload, set how big a percentage should be random. This defaults
 to 100%, in which case the workload is fully random. It can be set from
 anywhere from 0 to 100.  Setting it to 0 would make the workload fully
-sequential.
-.TP
-.BI percentage_sequential \fR=\fPint
-See \fBpercentage_random\fR.
+sequential. It is possible to set different values for reads, writes, and
+trim. To do so, simply use a comma separated list. See \fBblocksize\fR.
 .TP
 .B norandommap
 Normally \fBfio\fR will cover every block of the file when doing random I/O. If
@@ -699,7 +724,12 @@ Pretend to spend CPU time for given number of microseconds, sleeping the rest
 of the time specified by \fBthinktime\fR.  Only valid if \fBthinktime\fR is set.
 .TP
 .BI thinktime_blocks \fR=\fPint
-Number of blocks to issue before waiting \fBthinktime\fR microseconds.
+Only valid if thinktime is set - control how many blocks to issue, before
+waiting \fBthinktime\fR microseconds. If not set, defaults to 1 which will
+make fio wait \fBthinktime\fR microseconds after every block. This
+effectively makes any queue depth setting redundant, since no more than 1 IO
+will be queued before we have to complete it and do our thinktime. In other
+words, this setting effectively caps the queue depth if the latter is larger.
 Default: 1.
 .TP
 .BI rate \fR=\fPint
@@ -718,12 +748,12 @@ as \fBrate\fR is used for read vs write separation.
 .BI rate_iops \fR=\fPint
 Cap the bandwidth to this number of IOPS. Basically the same as rate, just
 specified independently of bandwidth. The same format as \fBrate\fR is used for
-read vs write seperation. If \fBblocksize\fR is a range, the smallest block
+read vs write separation. If \fBblocksize\fR is a range, the smallest block
 size is used as the metric.
 .TP
 .BI rate_iops_min \fR=\fPint
 If this rate of I/O is not met, the job will exit. The same format as \fBrate\fR
-is used for read vs write seperation.
+is used for read vs write separation.
 .TP
 .BI ratecycle \fR=\fPint
 Average bandwidth for \fBrate\fR and \fBratemin\fR over this number of
@@ -901,10 +931,13 @@ written file. If the data direction includes any form of write, the verify will
 be of the newly written data.
 .RE
 .TP
-.BI verify_sort \fR=\fPbool
+.BI verifysort \fR=\fPbool
 If true, written verify blocks are sorted if \fBfio\fR deems it to be faster to
 read them back in a sorted manner.  Default: true.
 .TP
+.BI verifysort_nr \fR=\fPint
+Pre-load and sort verify blocks for a read workload.
+.TP
 .BI verify_offset \fR=\fPint
 Swap the verification header with data somewhere else in the block before
 writing.  It is swapped back before verifying.
@@ -960,6 +993,21 @@ read back and verified).  If \fBverify_backlog_batch\fR is less than
 \fBverify_backlog_batch\fR is larger than \fBverify_backlog\fR,  some blocks
 will be verified more than once.
 .TP
+.BI trim_percentage \fR=\fPint
+Number of verify blocks to discard/trim.
+.TP
+.BI trim_verify_zero \fR=\fPbool
+Verify that trim/discarded blocks are returned as zeroes.
+.TP
+.BI trim_backlog \fR=\fPint
+Trim after this number of blocks are written.
+.TP
+.BI trim_backlog_batch \fR=\fPint
+Trim this number of IO blocks.
+.TP
+.BI experimental_verify \fR=\fPbool
+Enable experimental verification.
+.TP
 .B stonewall "\fR,\fP wait_for_previous"
 Wait for preceding jobs in the job file to exit before starting this one.
 \fBstonewall\fR implies \fBnew_group\fR.
@@ -983,6 +1031,9 @@ with \fBfork\fR\|(2).
 .BI zonesize \fR=\fPint
 Divide file into zones of the specified size in bytes.  See \fBzoneskip\fR.
 .TP
+.BI zonerange \fR=\fPint
+Give size of an IO zone.  See \fBzoneskip\fR.
+.TP
 .BI zoneskip \fR=\fPint
 Skip the specified number of bytes when \fBzonesize\fR bytes of data have been
 read.
@@ -1012,7 +1063,7 @@ single specified device regardless of the device it was recorded from.
 If given, write a bandwidth log of the jobs in this job file. Can be used to
 store data of the bandwidth of the jobs in their lifetime. The included
 fio_generate_plots script uses gnuplot to turn these text files into nice
-graphs. See \fBwrite_log_log\fR for behaviour of given filename. For this
+graphs. See \fBwrite_lat_log\fR for behaviour of given filename. For this
 option, the postfix is _bw.log.
 .TP
 .BI write_lat_log \fR=\fPstr
@@ -1053,9 +1104,15 @@ simulate a smaller amount of memory. The amount specified is per worker.
 .TP
 .BI exec_prerun \fR=\fPstr
 Before running the job, execute the specified command with \fBsystem\fR\|(3).
+.RS
+Output is redirected in a file called \fBjobname.prerun.txt\fR
+.RE
 .TP
 .BI exec_postrun \fR=\fPstr
 Same as \fBexec_prerun\fR, but the command is executed after the job completes.
+.RS
+Output is redirected in a file called \fBjobname.postrun.txt\fR
+.RE
 .TP
 .BI ioscheduler \fR=\fPstr
 Attempt to switch the device hosting the file to the specified I/O scheduler.
@@ -1125,6 +1182,9 @@ This option will ignore EAGAIN from READ, and ENOSPC and 122(EDQUOT) from WRITE.
 If set dump every error even if it is non fatal, true by default. If disabled
 only fatal error will be dumped
 .TP
+.BI profile \fR=\fPstr
+Select a specific builtin performance test.
+.TP
 .BI cgroup \fR=\fPstr
 Add job to this control group. If it doesn't exist, it will be created.
 The system must have a mounted cgroup blkio mount point for this to work. If
@@ -1149,6 +1209,21 @@ the thread/process does any work.
 .BI gid \fR=\fPint
 Set group ID, see \fBuid\fR.
 .TP
+.BI unit_base \fR=\fPint
+Base unit for reporting.  Allowed values are:
+.RS
+.TP
+.B 0
+Use auto-detection (default).
+.TP
+.B 8
+Byte based.
+.TP
+.B 1
+Bit based.
+.RE
+.P
+.TP
 .BI flow_id \fR=\fPint
 The ID of the flow. If not specified, it defaults to being a global flow. See
 \fBflow\fR.
@@ -1202,11 +1277,18 @@ iodepth_batch_complete=0).
 .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
-used and must be omitted.
+used and must be omitted unless it is a valid UDP multicast address.
 .TP
 .BI (net,netsplice)port \fR=\fPint
 The TCP or UDP port to bind to or connect to.
 .TP
+.BI (net,netsplice)interface \fR=\fPstr
+The IP address of the network interface used to send or receive UDP multicast
+packets.
+.TP
+.BI (net,netsplice)ttl \fR=\fPint
+Time-to-live value for outgoing UDP multicast packets. Default: 1
+.TP
 .BI (net,netsplice)nodelay \fR=\fPbool
 Set TCP_NODELAY on TCP connections.
 .TP
@@ -1237,13 +1319,14 @@ connections rather than initiating an outgoing connection. The
 hostname must be omitted if this option is used.
 .TP
 .BI (net, pingpong) \fR=\fPbool
-Normal a network writer will just continue writing data, and a network reader
+Normaly a network writer will just continue writing data, and a network reader
 will just consume packages. 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.
 This allows fio to measure network latencies. The submission and completion
 latencies then measure local time spent sending or receiving, and the
 completion latency measures how long it took for the other end to receive and
-send 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 (e4defrag,donorname) \fR=\fPstr
 File will be used as a block donor (swap extents between files)