.BI \-\-output \fR=\fPfilename
Write output to \fIfilename\fR.
.TP
-.BI \-\-timeout \fR=\fPtimeout
-Limit run time to \fItimeout\fR seconds.
+.BI \-\-runtime \fR=\fPruntime
+Limit run time to \fIruntime\fR seconds.
.TP
.B \-\-latency\-log
Generate per-job latency logs.
.BI \-\-showcmd \fR=\fPjobfile
Convert \fIjobfile\fR to a set of command-line options.
.TP
-.B \-\-readonly
-Enable read-only safety checks.
-.TP
.BI \-\-eta \fR=\fPwhen
Specifies when real-time ETA estimate should be printed. \fIwhen\fR may
be one of `always', `never' or `auto'.
All fio parser warnings are fatal, causing fio to exit with an error.
.TP
.BI \-\-max\-jobs \fR=\fPnr
-Set the maximum allowed number of jobs (threads/processes) to suport.
+Set the maximum allowed number of jobs (threads/processes) to support.
.TP
.BI \-\-server \fR=\fPargs
Start a backend server, with \fIargs\fP specifying what to listen to. See client/server section.
.TP
.BI \-\-client \fR=\fPhost
Instead of running the jobs locally, send and run them on the given host.
+.TP
+.BI \-\-idle\-prof \fR=\fPoption
+Report cpu idleness on a system or percpu basis (\fIoption\fP=system,percpu) or run unit work calibration only (\fIoption\fP=calibrate).
.SH "JOB FILE FORMAT"
Job files are in `ini' format. They consist of one or more
job definitions, which begin with a job name in square brackets and
time, but writes get exclusive access.
.RE
.P
-The option may be post-fixed with a lock batch number. If set, then each
-thread/process may do that amount of IOs to the file before giving up the lock.
-Since lock acquisition is expensive, batching the lock/unlocks will speed up IO.
-.RE
-.P
.BI opendir \fR=\fPstr
Recursively open any files below directory \fIstr\fR.
.TP
.B randwrite
Random writes.
.TP
-.B rw
+.B rw, readwrite
Mixed sequential reads and writes.
.TP
.B randrw
.P
For mixed I/O, the default split is 50/50. For certain types of io the result
may still be skewed a bit, since the speed may be different. It is possible to
-specify a number of IO's to do before getting a new offset, this is one by
+specify a number of IO's to do before getting a new offset, this is done by
appending a `:\fI<nr>\fR to the end of the string given. For a random read, it
would look like \fBrw=randread:8\fR for passing in an offset modifier with a
value of 8. If the postfix is used with a sequential IO pattern, then the value
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.
.TP
+.BI unified_rw_reporting \fR=\fPbool
+Fio normally reports statistics on a per data direction basis, meaning that
+read, write, and trim are accounted and reported separately. If this option is
+set, the fio will sum the results and report them as "mixed" instead.
+.TP
.BI randrepeat \fR=\fPbool
Seed the random number generator in a predictable way so results are repeatable
across runs. Default: true.
.B external
Loads an external I/O engine object file. Append the engine filename as
`:\fIenginepath\fR'.
+.TP
+.B falloc
+ IO engine that does regular linux native fallocate callt to simulate data
+transfer as fio ioengine
+.br
+ DDIR_READ does fallocate(,mode = FALLOC_FL_KEEP_SIZE,)
+.br
+ DIR_WRITE does fallocate(,mode = 0)
+.br
+ DDIR_TRIM does fallocate(,mode = FALLOC_FL_KEEP_SIZE|FALLOC_FL_PUNCH_HOLE)
+.TP
+.B e4defrag
+IO engine that does regular EXT4_IOC_MOVE_EXT ioctls to simulate defragment activity
+request to DDIR_WRITE event
.RE
+.P
.RE
.TP
.BI iodepth \fR=\fPint
If writing, setup the file first and do overwrites. Default: false.
.TP
.BI end_fsync \fR=\fPbool
-Sync file contents when job exits. Default: false.
+Sync file contents when a write stage has completed. 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. Default: false.
.TP
-.BI rwmixcycle \fR=\fPint
-How many milliseconds before switching between reads and writes for a mixed
-workload. Default: 500ms.
-.TP
.BI rwmixread \fR=\fPint
Percentage of a mixed workload that should be reads. Default: 50.
.TP
asked to limit reads or writes to a certain rate. If that is the case, then
the distribution may be skewed. Default: 50.
.TP
+.BI random_distribution \fR=\fPstr:float
+By default, fio will use a completely uniform random distribution when asked
+to perform random IO. Sometimes it is useful to skew the distribution in
+specific ways, ensuring that some parts of the data is more hot than others.
+Fio includes the following distribution models:
+.RS
+.TP
+.B random
+Uniform random distribution
+.TP
+.B zipf
+Zipf distribution
+.TP
+.B pareto
+Pareto distribution
+.TP
+.RE
+.P
+When using a zipf or pareto distribution, an input value is also needed to
+define the access pattern. For zipf, this is the zipf theta. For pareto,
+it's the pareto power. Fio includes a test program, genzipf, that can be
+used visualize what the given input values will yield in terms of hit rates.
+If you wanted to use zipf with a theta of 1.2, you would use
+random_distribution=zipf:1.2 as the option. If a non-uniform model is used,
+fio will disable use of the random map.
+.TP
.B norandommap
Normally \fBfio\fR will cover every block of the file when doing random I/O. If
this parameter is given, a new offset will be chosen without looking at past
random block map. As coverage will not be as complete as with random maps, this
option is disabled by default.
.TP
+.BI random_generator \fR=\fPstr
+Fio supports the following engines for generating IO offsets for random IO:
+.RS
+.TP
+.B tausworthe
+Strong 2^88 cycle random number generator
+.TP
+.B lfsr
+Linear feedback shift register generator
+.TP
+.RE
+.P
+Tausworthe is a strong random number generator, but it requires tracking on the
+side if we want to ensure that blocks are only read or written once. LFSR
+guarantees that we never generate the same offset twice, and it's also less
+computationally expensive. It's not a true random generator, however, though
+for IO purposes it's typically good enough. LFSR only works with single block
+sizes, not with workloads that use multiple block sizes. If used with such a
+workload, fio may read or write some blocks multiple times.
+.TP
.BI nice \fR=\fPint
Run job with given nice value. See \fInice\fR\|(2).
.TP
Average bandwidth for \fBrate\fR and \fBratemin\fR over this number of
milliseconds. Default: 1000ms.
.TP
+.BI max_latency \fR=\fPint
+If set, fio will exit the job if it exceeds this maximum latency. It will exit
+with an ETIME error.
+.TP
.BI cpumask \fR=\fPint
Set CPU affinity for this job. \fIint\fR is a bitmask of allowed CPUs the job
may run on. See \fBsched_setaffinity\fR\|(2).
.BI cpus_allowed \fR=\fPstr
Same as \fBcpumask\fR, but allows a comma-delimited list of CPU numbers.
.TP
+.BI numa_cpu_nodes \fR=\fPstr
+Set this job running on spcified NUMA nodes' CPUs. The arguments allow
+comma delimited list of cpu numbers, A-B ranges, or 'all'.
+.TP
+.BI numa_mem_policy \fR=\fPstr
+Set this job's memory policy and corresponding NUMA nodes. Format of
+the argements:
+.RS
+.TP
+.B <mode>[:<nodelist>]
+.TP
+.B mode
+is one of the following memory policy:
+.TP
+.B default, prefer, bind, interleave, local
+.TP
+.RE
+For \fBdefault\fR and \fBlocal\fR memory policy, no \fBnodelist\fR is
+needed to be specified. For \fBprefer\fR, only one node is
+allowed. For \fBbind\fR and \fBinterleave\fR, \fBnodelist\fR allows
+comma delimited list of numbers, A-B ranges, or 'all'.
+.TP
.BI startdelay \fR=\fPint
Delay start of job for the specified number of seconds.
.TP
.BI create_on_open \fR=\fPbool
If true, the files are not created until they are opened for IO by the job.
.TP
+.BI create_only \fR=\fPbool
+If true, fio will only run the setup phase of the job. If files need to be
+laid out or updated on disk, only that will be done. The actual job contents
+are not executed.
+.TP
.BI pre_read \fR=\fPbool
If this is given, files will be pre-read into memory before starting the given
IO operation. This will also clear the \fR \fBinvalidate\fR flag, since it is
.BI disk_util \fR=\fPbool
Generate disk utilization statistics if the platform supports it. Default: true.
.TP
+.BI clocksource \fR=\fPstr
+Use the given clocksource as the base of timing. The supported options are:
+.RS
+.TP
+.B gettimeofday
+gettimeofday(2)
+.TP
+.B clock_gettime
+clock_gettime(2)
+.TP
+.B cpu
+Internal CPU clock source
+.TP
+.RE
+.P
+\fBcpu\fR is the preferred clocksource if it is reliable, as it is very fast
+(and fio is heavy on time calls). Fio will automatically use this clocksource
+if it's supported and considered reliable on the system it is running on,
+unless another clocksource is specifically set. For x86/x86-64 CPUs, this
+means supporting TSC Invariant.
+.TP
.BI gtod_reduce \fR=\fPbool
Enable all of the gettimeofday() reducing options (disable_clat, disable_slat,
disable_bw) plus reduce precision of the timeout somewhat to really shrink the
these time calls will be excluded from other uses. Fio will manually clear it
from the CPU mask of other jobs.
.TP
+.BI ignore_error \fR=\fPstr
+Sometimes you want to ignore some errors during test in that case you can specify
+error list for each error type.
+.br
+ignore_error=READ_ERR_LIST,WRITE_ERR_LIST,VERIFY_ERR_LIST
+.br
+errors for given error type is separated with ':'.
+Error may be symbol ('ENOSPC', 'ENOMEM') or an integer.
+.br
+Example: ignore_error=EAGAIN,ENOSPC:122 .
+.br
+This option will ignore EAGAIN from READ, and ENOSPC and 122(EDQUOT) from WRITE.
+.TP
+.BI error_dump \fR=\fPbool
+If set dump every error even if it is non fatal, true by default. If disabled
+only fatal error will be dumped
+.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
used identically to normal parameters, with the caveat that when used on the
command line, the must come after the ioengine that defines them is selected.
.TP
+.BI (cpu)cpuload \fR=\fPint
+Attempt to use the specified percentage of CPU cycles.
+.TP
+.BI (cpu)cpuchunks \fR=\fPint
+Split the load into cycles of the given time. In microseconds.
+.TP
.BI (libaio)userspace_reap
Normally, with the libaio engine in use, fio will use
the io_getevents system call to reap newly returned events.
.BI (net,netsplice)port \fR=\fPint
The TCP or UDP port to bind to or connect to.
.TP
+.BI (net,netsplice)nodelay \fR=\fPbool
+Set TCP_NODELAY on TCP connections.
+.TP
.BI (net,netsplice)protocol \fR=\fPstr "\fR,\fP proto" \fR=\fPstr
The network protocol to use. Accepted values are:
.RS
Transmission control protocol
.TP
.B udp
-Unreliable datagram protocol
+User datagram protocol
.TP
.B unix
UNIX domain socket
For TCP network connections, tell fio to listen for incoming
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
+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.
+.TP
+.BI (e4defrag,donorname) \fR=\fPstr
+File will be used as a block donor (swap extents between files)
+.TP
+.BI (e4defrag,inplace) \fR=\fPint
+Configure donor file block allocation strategy
+.RS
+.BI 0(default) :
+Preallocate donor's file on init
+.TP
+.BI 1:
+allocate space immidietly inside defragment event, and free right after event
+.RE
+.TP
.SH OUTPUT
While running, \fBfio\fR will display the status of the created jobs. For
example:
Disk utilization.
.RE
.PD
+.P
+It is also possible to get fio to dump the current output while it is
+running, without terminating the job. To do that, send fio the \fBUSR1\fR
+signal.
.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 - a job description
on that machine, where args defines what fio listens to. The arguments
are of the form 'type:hostname or IP:port'. 'type' is either 'ip' (or ip4)
-for TCP/IP v4, 'ip6' for TCP/IP v6, or 'sock' for a local unix domain socket.
-'hostname' is either a hostname or IP address, and 'port' is the port to
+for TCP/IP v4, 'ip6' for TCP/IP v6, or 'sock' for a local unix domain
+socket. 'hostname' is either a hostname or IP address, and 'port' is the port to
listen to (only valid for TCP/IP, not a local socket). Some examples:
-1) fio --server
+1) fio \-\-server
Start a fio server, listening on all interfaces on the default port (8765).
-2) fio --server=ip:hostname,4444
+2) fio \-\-server=ip:hostname,4444
Start a fio server, listening on IP belonging to hostname and on port 4444.
-3) fio --server=ip6:::1,4444
+3) fio \-\-server=ip6:::1,4444
Start a fio server, listening on IPv6 localhost ::1 and on port 4444.
-4) fio --server=,4444
+4) fio \-\-server=,4444
Start a fio server, listening on all interfaces on port 4444.
-5) fio --server=1.2.3.4
+5) fio \-\-server=1.2.3.4
Start a fio server, listening on IP 1.2.3.4 on the default port.
-6) fio --server=sock:/tmp/fio.sock
+6) fio \-\-server=sock:/tmp/fio.sock
Start a fio server, listening on the local socket /tmp/fio.sock.
When a server is running, you can connect to it from a client. The client
is run with:
-fio --local-args --client=server --remote-args <job file(s)>
+fio \-\-local-args \-\-client=server \-\-remote-args <job file(s)>
-where --local-args are arguments that are local to the client where it is
-running, 'server' is the connect string, and --remote-args and <job file(s)>
+where \-\-local-args are arguments that are local to the client where it is
+running, 'server' is the connect string, and \-\-remote-args and <job file(s)>
are sent to the server. The 'server' string follows the same format as it
does on the server side, to allow IP/hostname/socket and port strings.
You can connect to multiple clients as well, to do that you could run:
-fio --client=server2 --client=server2 <job file(s)>
+fio \-\-client=server2 \-\-client=server2 <job file(s)>
.SH AUTHORS
.B fio
projects / fio.git / blobdiff