blob: aacee101d0efa247eea771a19902496ab7284ff8 [file] [log] [blame]
Aaron Carrolld60e92d2007-09-17 10:32:59 +02001.TH fio 1 "September 2007" "User Manual"
2.SH NAME
3fio \- flexible I/O tester
4.SH SYNOPSIS
5.B fio
6[\fIoptions\fR] [\fIjobfile\fR]...
7.SH DESCRIPTION
8.B fio
9is a tool that will spawn a number of threads or processes doing a
10particular type of I/O action as specified by the user.
11The typical use of fio is to write a job file matching the I/O load
12one wants to simulate.
13.SH OPTIONS
14.TP
15.BI \-\-output \fR=\fPfilename
16Write output to \fIfilename\fR.
17.TP
18.BI \-\-timeout \fR=\fPtimeout
19Limit run time to \fItimeout\fR seconds.
20.TP
21.B \-\-latency\-log
22Generate per-job latency logs.
23.TP
24.B \-\-bandwidth\-log
25Generate per-job bandwidth logs.
26.TP
27.B \-\-minimal
Aaron Carrolld1429b52007-09-18 08:10:57 +020028Print statistics in a terse, semicolon-delimited format.
Aaron Carrolld60e92d2007-09-17 10:32:59 +020029.TP
30.BI \-\-showcmd \fR=\fPjobfile
31Convert \fIjobfile\fR to a set of command-line options.
32.TP
33.B \-\-readonly
34Enable read-only safety checks.
35.TP
36.BI \-\-eta \fR=\fPwhen
37Specifies when real-time ETA estimate should be printed. \fIwhen\fR may
38be one of `always', `never' or `auto'.
39.TP
40.BI \-\-cmdhelp \fR=\fPcommand
41Print help information for \fIcommand\fR. May be `all' for all commands.
42.TP
43.B \-\-help
44Display usage information and exit.
45.TP
46.B \-\-version
47Display version information and exit.
48.SH "JOB FILE FORMAT"
49Job files are in `ini' format. They consist of one or more
50job definitions, which begin with a job name in square brackets and
51extend to the next job name. The job name can be any ASCII string
52except `global', which has a special meaning. Following the job name is
53a sequence of zero or more parameters, one per line, that define the
54behavior of the job. Any line starting with a `;' or `#' character is
Aaron Carrolld1429b52007-09-18 08:10:57 +020055considered a comment and ignored.
Aaron Carrolld60e92d2007-09-17 10:32:59 +020056job files.
57.SS "Global Section"
58The global section contains default parameters for jobs specified in the
59job file. A job is only affected by global sections residing above it,
60and there may be any number of global sections. Specific job definitions
61may override any parameter set in global sections.
62.SH "JOB PARAMETERS"
63.SS Types
64Some parameters may take arguments of a specific type. The types used are:
65.TP
66.I str
67String: a sequence of alphanumeric characters.
68.TP
69.I int
70Integer: a whole number, possibly negative. If prefixed with `0x', the value
71is assumed to be base 16 (hexadecimal).
72.TP
73.I siint
74SI integer: a whole number, possibly containing a suffix denoting the base unit
75of the value. Accepted suffixes are `k', 'M' and 'G', denoting kilo (1024),
76mega (1024*1024) and giga (1024*1024*1024) respectively.
77.TP
78.I bool
79Boolean: a true or false value. `0' denotes false, `1' denotes true.
80.TP
81.I irange
82Integer range: a range of integers specified in the format
Aaron Carrolld1429b52007-09-18 08:10:57 +020083\fIlower\fR:\fIupper\fR or \fIlower\fR\-\fIupper\fR. \fIlower\fR and
84\fIupper\fR may contain a suffix as described above. If an option allows two
85sets of ranges, they are separated with a `,' or `/' character. For example:
86`8\-8k/8M\-4G'.
Aaron Carrolld60e92d2007-09-17 10:32:59 +020087.SS "Parameter List"
88.TP
89.BI name \fR=\fPstr
90May be used to override the job name. On the command line, this paramter
91has the special purpose of signalling the start of a new job.
92.TP
93.BI description \fR=\fPstr
94Human-readable description of the job. It is printed when the job is run, but
95otherwise has no special purpose.
96.TP
97.BI directory \fR=\fPstr
98Prefix filenames with this directory. Used to place files in a location other
99than `./'.
100.TP
101.BI filename \fR=\fPstr
102.B fio
103normally makes up a file name based on the job name, thread number, and file
Aaron Carrolld1429b52007-09-18 08:10:57 +0200104number. If you want to share files between threads in a job or several jobs,
105specify a \fIfilename\fR for each of them to override the default. If the I/O
106engine used is `net', \fIfilename\fR is the host and port to connect to in the
107format \fIhost\fR/\fIport\fR. If the I/O engine is file-based, you can specify
108a number of files by separating the names with a `:' character. `\-' is a
109reserved name, meaning stdin or stdout, depending on the read/write direction
110set.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200111.TP
112.BI opendir \fR=\fPstr
113Recursively open any files below directory \fIstr\fR.
114.TP
115.BI readwrite \fR=\fPstr "\fR,\fP rw" \fR=\fPstr
116Type of I/O pattern. Accepted values are:
117.RS
118.RS
119.TP
120.B read
Aaron Carrolld1429b52007-09-18 08:10:57 +0200121Sequential reads.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200122.TP
123.B write
Aaron Carrolld1429b52007-09-18 08:10:57 +0200124Sequential writes.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200125.TP
126.B randread
Aaron Carrolld1429b52007-09-18 08:10:57 +0200127Random reads.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200128.TP
129.B randwrite
Aaron Carrolld1429b52007-09-18 08:10:57 +0200130Random writes.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200131.TP
132.B rw
Aaron Carrolld1429b52007-09-18 08:10:57 +0200133Mixed sequential reads and writes.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200134.TP
135.B randrw
Aaron Carrolld1429b52007-09-18 08:10:57 +0200136Mixed random reads and writes.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200137.RE
138.P
Aaron Carrolld1429b52007-09-18 08:10:57 +0200139For mixed I/O, the default split is 50/50. For random I/O, the number of I/Os
140to perform before getting a new offset can be specified by appending
141`:\fIint\fR' to the pattern type. The default is 1.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200142.RE
143.TP
144.BI randrepeat \fR=\fPbool
145Seed the random number generator in a predictable way so results are repeatable
Aaron Carrolld1429b52007-09-18 08:10:57 +0200146across runs. Default: true.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200147.TP
148.BI fadvise_hint \fR=\fPbool
Aaron Carrolld1429b52007-09-18 08:10:57 +0200149Disable use of \fIposix_fadvise\fR\|(2) to advise the kernel what I/O patterns
150are likely to be issued. Default: true.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200151.TP
152.BI size \fR=\fPsiint
153Total size of I/O for this job. \fBfio\fR will run until this many bytes have
154been transfered, unless limited by other options (\fBruntime\fR, for instance).
155Unless \fBnr_files\fR and \fBfilesize\fR options are given, this amount will be
156divided between the available files for the job.
157.TP
158.BI filesize \fR=\fPirange
159Individual file sizes. May be a range, in which case \fBfio\fR will select sizes
Aaron Carrolld1429b52007-09-18 08:10:57 +0200160for files at random within the given range, limited to \fBsize\fR in total (if
161that is given). If \fBfilesize\fR is not specified, each created file is the
162same size.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200163.TP
164.BI blocksize \fR=\fPsiint "\fR,\fB bs" \fR=\fPsiint
165Block size for I/O units. Default: 4k. Values for reads and writes can be
166specified seperately in the format \fIread\fR,\fIwrite\fR, either of
167which may be empty to leave that value at its default.
168.TP
169.BI blocksize_range \fR=\fPirange "\fR,\fB bsrange" \fR=\fPirange
Aaron Carrolld1429b52007-09-18 08:10:57 +0200170Specify a range of I/O block sizes. The issued I/O unit will always be a
171multiple of the minimum size, unless \fBblocksize_unaligned\fR is set. Applies
172to both reads and writes, but can be specified seperately (see \fBblocksize\fR).
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200173.TP
174.B blocksize_unaligned\fR,\fP bs_unaligned
Aaron Carrolld1429b52007-09-18 08:10:57 +0200175If set, any size in \fBblocksize_range\fR may be used. This typically won't
176work with direct I/O, as that normally requires sector alignment.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200177.TP
178.B zero_buffers
179Initialise buffers with all zeros. Default: fill buffers with random data.
180.TP
181.BI nrfiles \fR=\fPint
182Number of files to use for this job. Default: 1.
183.TP
184.BI openfiles \fR=\fPint
185Number of files to keep open at the same time. Default: \fBnrfiles\fR.
186.TP
187.BI file_service_type \fR=\fPstr
188Defines how files to service are selected. The following types are defined:
189.RS
190.RS
191.TP
192.B random
193Choose a file at random
194.TP
195.B roundrobin
196Round robin over open files (default).
197.RE
198.P
199The number of I/Os to issue before switching a new file can be specified by
200appending `:\fIint\fR' to the service type.
201.RE
202.TP
203.BI ioengine \fR=\fPstr
204Defines how the job issues I/O. The following types are defined:
205.RS
206.RS
207.TP
208.B sync
209Basic \fIread\fR\|(2) or \fIwrite\fR\|(2) I/O. \fIfseek\fR\|(2) is used to
210position the I/O location.
211.TP
212.B libaio
213Linux native asynchronous I/O.
214.TP
215.B posixaio
216glibc POSIX asynchronous I/O using \fIaio_read\fR\|(3) and \fIaio_write\fR\|(3).
217.TP
218.B mmap
Aaron Carrolld1429b52007-09-18 08:10:57 +0200219File is memory mapped with \fImmap\fR\|(2) and data copied using
220\fImemcpy\fR\|(3).
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200221.TP
222.B splice
Aaron Carrolld1429b52007-09-18 08:10:57 +0200223\fIsplice\fR\|(2) is used to transfer the data and \fIvmsplice\fR\|(2) to
224transfer data from user-space to the kernel.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200225.TP
226.B syslet-rw
227Use the syslet system calls to make regular read/write asynchronous.
228.TP
229.B sg
230SCSI generic sg v3 I/O. May be either synchronous using the SG_IO ioctl, or if
Aaron Carrolld1429b52007-09-18 08:10:57 +0200231the target is an sg character device, we use \fIread\fR\|(2) and
232\fIwrite\fR\|(2) for asynchronous I/O.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200233.TP
234.B null
235Doesn't transfer any data, just pretends to. Mainly used to exercise \fBfio\fR
236itself and for debugging and testing purposes.
237.TP
238.B net
239Transfer over the network. \fBfilename\fR must be set appropriately to
240`\fIhost\fR/\fIport\fR' regardless of data direction. If receiving, only the
241\fIport\fR argument is used.
242.TP
243.B netsplice
244Like \fBnet\fR, but uses \fIsplice\fR\|(2) and \fIvmsplice\fR\|(2) to map data
245and send/receive.
246.TP
gurudas pai53aec0a2007-10-05 13:20:18 +0200247.B cpuio
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200248Doesn't transfer any data, but burns CPU cycles according to \fBcpuload\fR and
249\fBcpucycles\fR parameters.
250.TP
251.B guasi
252The GUASI I/O engine is the Generic Userspace Asynchronous Syscall Interface
253approach to asycnronous I/O.
Aaron Carrolld1429b52007-09-18 08:10:57 +0200254.br
255See <http://www.xmailserver.org/guasi\-lib.html>.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200256.TP
257.B external
258Loads an external I/O engine object file. Append the engine filename as
259`:\fIenginepath\fR'.
260.RE
261.RE
262.TP
263.BI iodepth \fR=\fPint
264Number of I/O units to keep in flight against the file. Default: 1.
265.TP
266.BI iodepth_batch \fR=\fPint
267Number of I/Os to submit at once. Default: \fBiodepth\fR.
268.TP
269.BI iodepth_low \fR=\fPint
270Low watermark indicating when to start filling the queue again. Default:
271\fBiodepth\fR.
272.TP
273.BI direct \fR=\fPbool
274If true, use non-buffered I/O (usually O_DIRECT). Default: false.
275.TP
276.BI buffered \fR=\fPbool
277If true, use buffered I/O. This is the opposite of the \fBdirect\fR parameter.
278Default: true.
279.TP
280.BI offset \fR=\fPsiint
281Offset in the file to start I/O. Data before the offset will not be touched.
282.TP
283.BI fsync \fR=\fPint
Aaron Carrolld1429b52007-09-18 08:10:57 +0200284How many I/Os to perform before issuing an \fBfsync\fR\|(2) of dirty data. If
2850, don't sync. Default: 0.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200286.TP
287.BI overwrite \fR=\fPbool
Aaron Carrolld1429b52007-09-18 08:10:57 +0200288If writing, setup the file first and do overwrites. Default: false.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200289.TP
290.BI end_fsync \fR=\fPbool
Aaron Carrolld1429b52007-09-18 08:10:57 +0200291Sync file contents when job exits. Default: false.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200292.TP
293.BI fsync_on_close \fR=\fPbool
294If true, sync file contents on close. This differs from \fBend_fsync\fR in that
Aaron Carrolld1429b52007-09-18 08:10:57 +0200295it will happen on every close, not just at the end of the job. Default: false.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200296.TP
297.BI rwmixcycle \fR=\fPint
298How many milliseconds before switching between reads and writes for a mixed
299workload. Default: 500ms.
300.TP
301.BI rwmixread \fR=\fPint
302Percentage of a mixed workload that should be reads. Default: 50.
303.TP
304.BI rwmixwrite \fR=\fPint
Aaron Carrolld1429b52007-09-18 08:10:57 +0200305Percentage of a mixed workload that should be writes. If \fBrwmixread\fR and
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200306\fBwrmixwrite\fR are given and do not sum to 100%, the latter of the two
Aaron Carrolld1429b52007-09-18 08:10:57 +0200307overrides the first. Default: 50.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200308.TP
309.B norandommap
310Normally \fBfio\fR will cover every block of the file when doing random I/O. If
311this parameter is given, a new offset will be chosen without looking at past
312I/O history. This parameter is mutually exclusive with \fBverify\fR.
313.TP
314.BI nice \fR=\fPint
315Run job with given nice value. See \fInice\fR\|(2).
316.TP
317.BI prio \fR=\fPint
318Set I/O priority value of this job between 0 (highest) and 7 (lowest). See
319\fIionice\fR\|(1).
320.TP
321.BI prioclass \fR=\fPint
322Set I/O priority class. See \fIionice\fR\|(1).
323.TP
324.BI thinktime \fR=\fPint
325Stall job for given number of microseconds between issuing I/Os.
326.TP
327.BI thinktime_spin \fR=\fPint
328Pretend to spend CPU time for given number of microseconds, sleeping the rest
329of the time specified by \fBthinktime\fR. Only valid if \fBthinktime\fR is set.
330.TP
331.BI thinktime_blocks \fR=\fPint
332Number of blocks to issue before waiting \fBthinktime\fR microseconds.
333Default: 1.
334.TP
335.BI rate \fR=\fPint
336Cap bandwidth used by this job to this number of KiB/s.
337.TP
338.BI ratemin \fR=\fPint
339Tell \fBfio\fR to do whatever it can to maintain at least the given bandwidth.
340Failing to meet this requirement will cause the job to exit.
341.TP
342.BI rate_iops \fR=\fPint
343Cap the bandwidth to this number of IOPS. If \fBblocksize\fR is a range, the
344smallest block size is used as the metric.
345.TP
346.BI rate_iops_min \fR=\fPint
347If this rate of I/O is not met, the job will exit.
348.TP
349.BI ratecycle \fR=\fPint
350Average bandwidth for \fBrate\fR and \fBratemin\fR over this number of
351milliseconds. Default: 1000ms.
352.TP
353.BI cpumask \fR=\fPint
354Set CPU affinity for this job. \fIint\fR is a bitmask of allowed CPUs the job
355may run on. See \fBsched_setaffinity\fR\|(2).
356.TP
357.BI cpus_allowed \fR=\fPstr
358Same as \fBcpumask\fR, but allows a comma-delimited list of CPU numbers.
359.TP
360.BI startdelay \fR=\fPint
361Delay start of job for the specified number of seconds.
362.TP
363.BI runtime \fR=\fPint
364Terminate processing after the specified number of seconds.
365.TP
366.B time_based
367If given, run for the specified \fBruntime\fR duration even if the files are
368completely read or written. The same workload will be repeated as many times
369as \fBruntime\fR allows.
370.TP
371.BI invalidate \fR=\fPbool
372Invalidate buffer-cache for the file prior to starting I/O. Default: true.
373.TP
374.BI sync \fR=\fPbool
375Use synchronous I/O for buffered writes. For the majority of I/O engines,
Aaron Carrolld1429b52007-09-18 08:10:57 +0200376this means using O_SYNC. Default: false.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200377.TP
378.BI iomem \fR=\fPstr "\fR,\fP mem" \fR=\fPstr
379Allocation method for I/O unit buffer. Allowed values are:
380.RS
381.RS
382.TP
383.B malloc
384Allocate memory with \fImalloc\fR\|(3).
385.TP
386.B shm
387Use shared memory buffers allocated through \fIshmget\fR\|(2).
388.TP
389.B shmhuge
390Same as \fBshm\fR, but use huge pages as backing.
391.TP
392.B mmap
393Use \fImmap\fR\|(2) for allocation. Uses anonymous memory unless a filename
394is given after the option in the format `:\fIfile\fR'.
395.TP
396.B mmaphuge
397Same as \fBmmap\fR, but use huge files as backing.
398.RE
399.P
400The amount of memory allocated is the maximum allowed \fBblocksize\fR for the
401job multiplied by \fBiodepth\fR. For \fBshmhuge\fR or \fBmmaphuge\fR to work,
402the system must have free huge pages allocated. \fBmmaphuge\fR also needs to
403have hugetlbfs mounted, and \fIfile\fR must point there.
404.RE
405.TP
Aaron Carrolld1429b52007-09-18 08:10:57 +0200406.BI hugepage\-size \fR=\fPsiint
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200407Defines the size of a huge page. Must be at least equal to the system setting.
408Should be a multiple of 1MiB. Default: 4MiB.
409.TP
410.B exitall
411Terminate all jobs when one finishes. Default: wait for each job to finish.
412.TP
413.BI bwavgtime \fR=\fPint
414Average bandwidth calculations over the given time in milliseconds. Default:
415500ms.
416.TP
417.BI create_serialize \fR=\fPbool
Aaron Carrolld1429b52007-09-18 08:10:57 +0200418If true, serialize file creation for the jobs. Default: true.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200419.TP
420.BI create_fsync \fR=\fPbool
421\fIfsync\fR\|(2) data file after creation. Default: true.
422.TP
423.BI unlink \fR=\fPbool
424Unlink job files when done. Default: false.
425.TP
426.BI loops \fR=\fPint
427Specifies the number of iterations (runs of the same workload) of this job.
428Default: 1.
429.TP
430.BI do_verify \fR=\fPbool
431Run the verify phase after a write phase. Only valid if \fBverify\fR is set.
432Default: true.
433.TP
434.BI verify \fR=\fPstr
435Method of verifying file contents after each iteration of the job. Allowed
436values are:
437.RS
438.RS
439.TP
440.B md5 crc16 crc32 crc64 crc7 sha256 sha512
441Store appropriate checksum in the header of each block.
442.TP
443.B meta
444Write extra information about each I/O (timestamp, block number, etc.). The
445block number is verified.
446.TP
447.B pattern
448Fill I/O buffers with a specific pattern that is used to verify. The pattern is
449specified by appending `:\fIint\fR' to the parameter. \fIint\fR cannot be larger
450than 32-bits.
451.TP
452.B null
453Pretend to verify. Used for testing internals.
454.RE
455.RE
456.TP
457.BI verify_sort \fR=\fPbool
458If true, written verify blocks are sorted if \fBfio\fR deems it to be faster to
459read them back in a sorted manner. Default: true.
460.TP
461.BI verify_offset \fR=\fPsiint
462Swap the verification header with data somewhere else in the block before
Aaron Carrolld1429b52007-09-18 08:10:57 +0200463writing. It is swapped back before verifying.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200464.TP
465.BI verify_interval \fR=\fPsiint
466Write the verification header for this number of bytes, which should divide
467\fBblocksize\fR. Default: \fBblocksize\fR.
468.TP
469.BI verify_fatal \fR=\fPbool
470If true, exit the job on the first observed verification failure. Default:
471false.
472.TP
473.B stonewall
Aaron Carrolld1429b52007-09-18 08:10:57 +0200474Wait for preceeding jobs in the job file to exit before starting this one.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200475\fBstonewall\fR implies \fBnew_group\fR.
476.TP
477.B new_group
478Start a new reporting group. If not given, all jobs in a file will be part
479of the same reporting group, unless separated by a stonewall.
480.TP
481.BI numjobs \fR=\fPint
482Number of clones (processes/threads performing the same workload) of this job.
483Default: 1.
484.TP
485.B group_reporting
486If set, display per-group reports instead of per-job when \fBnumjobs\fR is
487specified.
488.TP
489.B thread
490Use threads created with \fBpthread_create\fR\|(3) instead of processes created
491with \fBfork\fR\|(2).
492.TP
493.BI zonesize \fR=\fPsiint
494Divide file into zones of the specified size in bytes. See \fBzoneskip\fR.
495.TP
496.BI zoneskip \fR=\fPsiint
Aaron Carrolld1429b52007-09-18 08:10:57 +0200497Skip the specified number of bytes when \fBzonesize\fR bytes of data have been
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200498read.
499.TP
500.BI write_iolog \fR=\fPstr
501Write the issued I/O patterns to the specified file.
502.TP
503.BI read_iolog \fR=\fPstr
504Replay the I/O patterns contained in the specified file generated by
505\fBwrite_iolog\fR, or may be a \fBblktrace\fR binary file.
506.TP
507.B write_bw_log
508If given, write bandwidth logs of the jobs in this file.
509.TP
510.B write_lat_log
511Same as \fBwrite_bw_log\fR, but writes I/O completion latencies.
512.TP
513.BI lockmem \fR=\fPsiint
514Pin the specified amount of memory with \fBmlock\fR\|(2). Can be used to
515simulate a smaller amount of memory.
516.TP
517.BI exec_prerun \fR=\fPstr
518Before running the job, execute the specified command with \fBsystem\fR\|(3).
519.TP
520.BI exec_postrun \fR=\fPstr
521Same as \fBexec_prerun\fR, but the command is executed after the job completes.
522.TP
523.BI ioscheduler \fR=\fPstr
524Attempt to switch the device hosting the file to the specified I/O scheduler.
525.TP
526.BI cpuload \fR=\fPint
527If the job is a CPU cycle-eater, attempt to use the specified percentage of
528CPU cycles.
529.TP
530.BI cpuchunks \fR=\fPint
531If the job is a CPU cycle-eater, split the load into cycles of the
532given time in milliseconds.
533.TP
534.BI disk_util \fR=\fPbool
Aaron Carrolld1429b52007-09-18 08:10:57 +0200535Generate disk utilization statistics if the platform supports it. Default: true.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200536.SH OUTPUT
Aaron Carrolld1429b52007-09-18 08:10:57 +0200537While running, \fBfio\fR will display the status of the created jobs. For
538example:
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200539.RS
Aaron Carrolld1429b52007-09-18 08:10:57 +0200540.P
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200541Threads: 1: [_r] [24.8% done] [ 13509/ 8334 kb/s] [eta 00h:01m:31s]
542.RE
543.P
Aaron Carrolld1429b52007-09-18 08:10:57 +0200544The characters in the first set of brackets denote the current status of each
545threads. The possible values are:
546.P
547.PD 0
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200548.RS
549.TP
550.B P
551Setup but not started.
552.TP
553.B C
554Thread created.
555.TP
556.B I
557Initialized, waiting.
558.TP
559.B R
560Running, doing sequential reads.
561.TP
562.B r
563Running, doing random reads.
564.TP
565.B W
566Running, doing sequential writes.
567.TP
568.B w
569Running, doing random writes.
570.TP
571.B M
572Running, doing mixed sequential reads/writes.
573.TP
574.B m
575Running, doing mixed random reads/writes.
576.TP
577.B F
578Running, currently waiting for \fBfsync\fR\|(2).
579.TP
580.B V
581Running, verifying written data.
582.TP
583.B E
584Exited, not reaped by main thread.
585.TP
586.B \-
587Exited, thread reaped.
588.RE
Aaron Carrolld1429b52007-09-18 08:10:57 +0200589.PD
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200590.P
591The second set of brackets shows the estimated completion percentage of
592the current group. The third set shows the read and write I/O rate,
593respectively. Finally, the estimated run time of the job is displayed.
594.P
595When \fBfio\fR completes (or is interrupted by Ctrl-C), it will show data
596for each thread, each group of threads, and each disk, in that order.
597.P
598Per-thread statistics first show the threads client number, group-id, and
599error code. The remaining figures are as follows:
600.RS
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200601.TP
602.B io
603Number of megabytes of I/O performed.
604.TP
605.B bw
606Average data rate (bandwidth).
607.TP
608.B runt
609Threads run time.
610.TP
611.B slat
612Submission latency minimum, maximum, average and standard deviation. This is
613the time it took to submit the I/O.
614.TP
615.B clat
616Completion latency minimum, maximum, average and standard deviation. This
617is the time between submission and completion.
618.TP
619.B bw
620Bandwidth minimum, maximum, percentage of aggregate bandwidth received, average
621and standard deviation.
622.TP
623.B cpu
624CPU usage statistics. Includes user and system time, number of context switches
625this thread went through and number of major and minor page faults.
626.TP
627.B IO depths
628Distribution of I/O depths. Each depth includes everything less than (or equal)
629to it, but greater than the previous depth.
630.TP
631.B IO issued
632Number of read/write requests issued, and number of short read/write requests.
633.TP
634.B IO latencies
635Distribution of I/O completion latencies. The numbers follow the same pattern
636as \fBIO depths\fR.
637.RE
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200638.P
639The group statistics show:
Aaron Carrolld1429b52007-09-18 08:10:57 +0200640.PD 0
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200641.RS
642.TP
643.B io
644Number of megabytes I/O performed.
645.TP
646.B aggrb
647Aggregate bandwidth of threads in the group.
648.TP
649.B minb
650Minimum average bandwidth a thread saw.
651.TP
652.B maxb
653Maximum average bandwidth a thread saw.
654.TP
655.B mint
Aaron Carrolld1429b52007-09-18 08:10:57 +0200656Shortest runtime of threads in the group.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200657.TP
658.B maxt
659Longest runtime of threads in the group.
660.RE
Aaron Carrolld1429b52007-09-18 08:10:57 +0200661.PD
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200662.P
663Finally, disk statistics are printed with reads first:
Aaron Carrolld1429b52007-09-18 08:10:57 +0200664.PD 0
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200665.RS
666.TP
667.B ios
668Number of I/Os performed by all groups.
669.TP
670.B merge
671Number of merges in the I/O scheduler.
672.TP
673.B ticks
674Number of ticks we kept the disk busy.
675.TP
676.B io_queue
677Total time spent in the disk queue.
678.TP
679.B util
680Disk utilization.
681.RE
Aaron Carrolld1429b52007-09-18 08:10:57 +0200682.PD
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200683.SH TERSE OUTPUT
684If the \fB\-\-minimal\fR option is given, the results will be printed in a
685semicolon-delimited format suitable for scripted use. The fields are:
686.P
687.RS
688.B jobname, groupid, error
689.P
690Read status:
691.RS
692.B KiB I/O, bandwidth \fR(KiB/s)\fP, runtime \fR(ms)\fP
693.P
694Submission latency:
695.RS
696.B min, max, mean, standard deviation
697.RE
698Completion latency:
699.RS
700.B min, max, mean, standard deviation
701.RE
702Bandwidth:
703.RS
704.B min, max, aggregate percentage of total, mean, standard deviation
705.RE
706.RE
707.P
708Write status:
709.RS
710.B KiB I/O, bandwidth \fR(KiB/s)\fP, runtime \fR(ms)\fP
711.P
712Submission latency:
713.RS
714.B min, max, mean, standard deviation
715.RE
716Completion latency:
717.RS
718.B min, max, mean, standard deviation
719.RE
720Bandwidth:
721.RS
722.B min, max, aggregate percentage of total, mean, standard deviation
723.RE
724.RE
725.P
Aaron Carrolld1429b52007-09-18 08:10:57 +0200726CPU usage:
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200727.RS
728.B user, system, context switches
729.RE
730.P
731IO depth distribution:
732.RS
733.B <=1, 2, 4, 8, 16, 32, >=64
734.RE
735.P
736IO latency distribution (ms):
737.RS
738.B <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, >=2000
739.RE
740.P
741.B text description
742.RE
743.SH AUTHORS
744.B fio
745was written by Jens Axboe <jens.axboe@oracle.com>.
Aaron Carrolld1429b52007-09-18 08:10:57 +0200746.br
747This man page was written by Aaron Carroll <aaronc@cse.unsw.edu.au> based
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200748on documentation by Jens Axboe.
749.SH "REPORTING BUGS"
Aaron Carrolld1429b52007-09-18 08:10:57 +0200750Report bugs to the \fBfio\fR mailing list <fio-devel@kernel.dk>.
751See \fBREADME\fR.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200752.SH "SEE ALSO"
Aaron Carrolld1429b52007-09-18 08:10:57 +0200753For further documentation see \fBHOWTO\fR and \fBREADME\fR.
754.br
755Sample jobfiles are available in the \fBexamples\fR directory.
Aaron Carrolld60e92d2007-09-17 10:32:59 +0200756