1fio(1) General Commands Manual fio(1)
2
6 fio - flexible I/O tester
7
9 fio [options] [jobfile]...
10
12 fio is a tool that will spawn a number of threads or processes doing a
13 particular type of I/O action as specified by the user. The typical
14 use of fio is to write a job file matching the I/O load one wants to
15 simulate.
16
18 --output=filename
19 Write output to filename.
20 --timeout=timeout
22 Limit run time to timeout seconds.
23 --latency-log
25 Generate per-job latency logs.
26 --bandwidth-log
28 Generate per-job bandwidth logs.
29 --minimal
31 Print statistics in a terse, semicolon-delimited format.
32 --showcmd=jobfile
34 Convert jobfile to a set of command-line options.
35 --readonly
37 Enable read-only safety checks.
38 --eta=when
40 Specifies when real-time ETA estimate should be printed. when
41 may be one of `always', `never' or `auto'.
42 --section=sec
44 Only run section sec from job file.
45 --cmdhelp=command
47 Print help information for command. May be `all' for all com‐
48 mands.
49 --debug=type
51 Enable verbose tracing of various fio actions. May be `all' for
52 all types or individual types seperated by a comma (eg
53 --debug=io,file). `help' will list all available tracing
54 options.
55 --help Display usage information and exit.
57 --version
59 Display version information and exit.
60
62 Job files are in `ini' format. They consist of one or more job defini‐
63 tions, which begin with a job name in square brackets and extend to the
64 next job name. The job name can be any ASCII string except `global',
65 which has a special meaning. Following the job name is a sequence of
66 zero or more parameters, one per line, that define the behavior of the
67 job. Any line starting with a `;' or `#' character is considered a
68 comment and ignored.
69 If jobfile is specified as `-', the job file will be read from standard
71 input.
72 Global Section
74 The global section contains default parameters for jobs specified in
75 the job file. A job is only affected by global sections residing above
76 it, and there may be any number of global sections. Specific job defi‐
77 nitions may override any parameter set in global sections.
78
80 Types
81 Some parameters may take arguments of a specific type. The types used
82 are:
83 str String: a sequence of alphanumeric characters.
85 int SI integer: a whole number, possibly containing a suffix denot‐
87 ing the base unit of the value. Accepted suffixes are `k', 'M',
88 'G', 'T', and 'P', denoting kilo (1024), mega (1024^2), giga
89 (1024^3), tera (1024^4), and peta (1024^5) respectively. The
90 suffix is not case sensitive. If prefixed with '0x', the value
91 is assumed to be base 16 (hexadecimal). A suffix may include a
92 trailing by using 'KiB', 'MiB', 'GiB', etc. This is useful for
93 disk drives where values are often given in base 10 values.
94 Specifying '30GiB' will get you 30*1000^3 bytes.
95 bool Boolean: a true or false value. `0' denotes false, `1' denotes
97 true.
98 irange Integer range: a range of integers specified in the format
100 lower:upper or lower-upper. lower and upper may contain a suffix
101 as described above. If an option allows two sets of ranges,
102 they are separated with a `,' or `/' character. For example:
103 `8-8k/8M-4G'.
104 Parameter List
106 name=str
107 May be used to override the job name. On the command line, this
108 parameter has the special purpose of signalling the start of a
109 new job.
110 description=str
112 Human-readable description of the job. It is printed when the
113 job is run, but otherwise has no special purpose.
114 directory=str
116 Prefix filenames with this directory. Used to place files in a
117 location other than `./'.
118 filename=str
120 fio normally makes up a file name based on the job name, thread
121 number, and file number. If you want to share files between
122 threads in a job or several jobs, specify a filename for each of
123 them to override the default. If the I/O engine used is `net',
124 filename is the host and port to connect to in the format
125 host/port. If the I/O engine is file-based, you can specify a
126 number of files by separating the names with a `:' character.
127 `-' is a reserved name, meaning stdin or stdout, depending on
128 the read/write direction set.
129 lockfile=str
131 Fio defaults to not locking any files before it does IO to them.
132 If a file or file descriptor is shared, fio can serialize IO to
133 that file to make the end result consistent. This is usual for
134 emulating real workloads that share files. The lock modes are:
135 none No locking. This is the default.
137 exclusive
139 Only one thread or process may do IO at the time,
140 excluding all others.
141 readwrite
143 Read-write locking on the file. Many readers may
144 access the file at the same time, but writes get
145 exclusive access.
146 The option may be post-fixed with a lock batch number. If set,
148 then each thread/process may do that amount of IOs to the file
149 before giving up the lock. Since lock acquisition is expensive,
150 batching the lock/unlocks will speed up IO.
151 opendir=str Recursively open any files below directory str.
153 readwrite=str, rw=str
155 Type of I/O pattern. Accepted values are:
156 read Sequential reads.
158 write Sequential writes.
160 randread
162 Random reads.
163 randwrite
165 Random writes.
166 rw Mixed sequential reads and writes.
168 randrw Mixed random reads and writes.
170 For mixed I/O, the default split is 50/50. For random I/O, the
172 number of I/Os to perform before getting a new offset can be
173 specified by appending `:int' to the pattern type. The default
174 is 1.
175 kb_base=int
177 The base unit for a kilobyte. The defacto base is 2^10, 1024.
178 Storage manufacturers like to use 10^3 or 1000 as a base ten
179 unit instead, for obvious reasons. Allow values are 1024 or
180 1000, with 1024 being the default.
181 randrepeat=bool
183 Seed the random number generator in a predictable way so results
184 are repeatable across runs. Default: true.
185 fallocate=bool
187 By default, fio will use fallocate() to advise the system of the
188 size of the file we are going to write. This can be turned off
189 with fallocate=0. May not be available on all supported plat‐
190 forms.
191 fadvise_hint=bool
193 Disable use of posix_fadvise(2) to advise the kernel what I/O
194 patterns are likely to be issued. Default: true.
195 size=int
197 Total size of I/O for this job. fio will run until this many
198 bytes have been transfered, unless limited by other options
199 (runtime, for instance). Unless nr_files and filesize options
200 are given, this amount will be divided between the available
201 files for the job. If not set, fio will use the full size of the
202 given files or devices. If the the files do not exist, size must
203 be given.
204 fill_device=bool
206 Sets size to something really large and waits for ENOSPC (no
207 space left on device) as the terminating condition. Only makes
208 sense with sequential write. For a read workload, the mount
209 point will be filled first then IO started on the result.
210 filesize=irange
212 Individual file sizes. May be a range, in which case fio will
213 select sizes for files at random within the given range, limited
214 to size in total (if that is given). If filesize is not speci‐
215 fied, each created file is the same size.
216 blocksize=int[,int], bs=int[,int]
218 Block size for I/O units. Default: 4k. Values for reads and
219 writes can be specified separately in the format read,write,
220 either of which may be empty to leave that value at its default.
221 blocksize_range=irange[,irange], bsrange=irange[,irange]
223 Specify a range of I/O block sizes. The issued I/O unit will
224 always be a multiple of the minimum size, unless block‐
225 size_unaligned is set. Applies to both reads and writes if only
226 one range is given, but can be specified separately with a comma
227 seperating the values. Example: bsrange=1k-4k,2k-8k. Also (see
228 blocksize).
229 bssplit=str
231 This option allows even finer grained control of the block sizes
232 issued, not just even splits between them. With this option, you
233 can weight various block sizes for exact control of the issued
234 IO for a job that has mixed block sizes. The format of the
235 option is bssplit=blocksize/percentage, optionally adding as
236 many definitions as needed seperated by a colon. Example: bss‐
237 plit=4k/10:64k/50:32k/40 would issue 50% 64k blocks, 10% 4k
238 blocks and 40% 32k blocks. bssplit also supports giving separate
239 splits to reads and writes. The format is identical to what the
240 bs option accepts, the read and write parts are separated with a
241 comma.
242 blocksize_unaligned, bs_unaligned
244 If set, any size in blocksize_range may be used. This typically
245 won't work with direct I/O, as that normally requires sector
246 alignment.
247 blockalign=int[,int], ba=int[,int]
249 At what boundary to align random IO offsets. Defaults to the
250 same as 'blocksize' the minimum blocksize given. Minimum align‐
251 ment is typically 512b for using direct IO, though it usually
252 depends on the hardware block size. This option is mutually
253 exclusive with using a random map for files, so it will turn off
254 that option.
255 zero_buffers
257 Initialise buffers with all zeros. Default: fill buffers with
258 random data.
259 refill_buffers
261 If this option is given, fio will refill the IO buffers on every
262 submit. The default is to only fill it at init time and reuse
263 that data. Only makes sense if zero_buffers isn't specified,
264 naturally. If data verification is enabled, refill_buffers is
265 also automatically enabled.
266 nrfiles=int
268 Number of files to use for this job. Default: 1.
269 openfiles=int
271 Number of files to keep open at the same time. Default:
272 nrfiles.
273 file_service_type=str
275 Defines how files to service are selected. The following types
276 are defined:
277 random Choose a file at random
279 roundrobin
281 Round robin over open files (default). sequential
282 Do each file in the set sequentially.
283 The number of I/Os to issue before switching a new file can be
285 specified by appending `:int' to the service type.
286 ioengine=str
288 Defines how the job issues I/O. The following types are
289 defined:
290 sync Basic read(2) or write(2) I/O. fseek(2) is used
292 to position the I/O location.
293 psync Basic pread(2) or pwrite(2) I/O.
295 vsync Basic readv(2) or writev(2) I/O. Will emulate
297 queuing by coalescing adjacents IOs into a single
298 submission.
299 libaio Linux native asynchronous I/O.
301 posixaio
303 glibc POSIX asynchronous I/O using aio_read(3) and
304 aio_write(3).
305 mmap File is memory mapped with mmap(2) and data copied
307 using memcpy(3).
308 splice [22msplice(2) is used to transfer the data and
310 vmsplice(2) to transfer data from user-space to
311 the kernel.
312 syslet-rw
314 Use the syslet system calls to make regular
315 read/write asynchronous.
316 sg SCSI generic sg v3 I/O. May be either synchronous
318 using the SG_IO ioctl, or if the target is an sg
319 character device, we use read(2) and write(2) for
320 asynchronous I/O.
321 null Doesn't transfer any data, just pretends to.
323 Mainly used to exercise fio itself and for debug‐
324 ging and testing purposes.
325 net Transfer over the network. filename must be set
327 appropriately to `host/port' regardless of data
328 direction. If receiving, only the port argument
329 is used.
330 netsplice
332 Like net, but uses splice(2) and vmsplice(2) to
333 map data and send/receive.
334 cpuio Doesn't transfer any data, but burns CPU cycles
336 according to cpuload and cpucycles parameters.
337 guasi The GUASI I/O engine is the Generic Userspace
339 Asynchronous Syscall Interface approach to asycn‐
340 ronous I/O.
341 See <http://www.xmailserver.org/guasi-lib.html>.
342 external
344 Loads an external I/O engine object file. Append
345 the engine filename as `:enginepath'.
346 iodepth=int
348 Number of I/O units to keep in flight against the file.
349 Default: 1.
350 iodepth_batch=int
352 Number of I/Os to submit at once. Default: iodepth.
353 iodepth_batch_complete=int
355 This defines how many pieces of IO to retrieve at once. It
356 defaults to 1 which
357 means that we'll ask for a minimum of 1 IO in the retrieval
358 process from the kernel. The IO retrieval will go on until we
359 hit the limit set by iodepth_low. If this variable is set to 0,
360 then fio will always check for completed events before queuing
361 more IO. This helps reduce IO latency, at the cost of more
362 retrieval system calls.
363 iodepth_low=int
365 Low watermark indicating when to start filling the queue again.
366 Default: iodepth.
367 direct=bool
369 If true, use non-buffered I/O (usually O_DIRECT). Default:
370 false.
371 buffered=bool
373 If true, use buffered I/O. This is the opposite of the direct
374 parameter. Default: true.
375 offset=int
377 Offset in the file to start I/O. Data before the offset will not
378 be touched.
379 fsync=int
381 How many I/Os to perform before issuing an fsync(2) of dirty
382 data. If 0, don't sync. Default: 0.
383 fdatasync=int
385 Like fsync, but uses fdatasync(2) instead to only sync the data
386 parts of the file. Default: 0.
387 sync_file_range=str:int
389 Use sync_file_range() for every val number of write operations.
390 Fio will track range of writes that have happened since the last
391 sync_file_range() call. str can currently be one or more of:
392 wait_before
394 SYNC_FILE_RANGE_WAIT_BEFORE
395 write SYNC_FILE_RANGE_WRITE
397 wait_after
399 SYNC_FILE_RANGE_WRITE
400 So if you do sync_file_range=wait_before,write:8, fio
403 would use
404 SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE for every 8
405 writes. Also see the sync_file_range(2) man page. This option
406 is Linux specific.
407 overwrite=bool
409 If writing, setup the file first and do overwrites. Default:
410 false.
411 end_fsync=bool
413 Sync file contents when job exits. Default: false.
414 fsync_on_close=bool
416 If true, sync file contents on close. This differs from
417 end_fsync in that it will happen on every close, not just at the
418 end of the job. Default: false.
419 rwmixcycle=int
421 How many milliseconds before switching between reads and writes
422 for a mixed workload. Default: 500ms.
423 rwmixread=int
425 Percentage of a mixed workload that should be reads. Default:
426 50.
427 rwmixwrite=int
429 Percentage of a mixed workload that should be writes. If
430 rwmixread and rwmixwrite are given and do not sum to 100%, the
431 latter of the two overrides the first. This may interfere with a
432 given rate setting, if fio is asked to limit reads or writes to
433 a certain rate. If that is the case, then the distribution may
434 be skewed. Default: 50.
435 norandommap
437 Normally fio will cover every block of the file when doing ran‐
438 dom I/O. If this parameter is given, a new offset will be chosen
439 without looking at past I/O history. This parameter is mutually
440 exclusive with verify.
441 softrandommap
443 See norandommap. If fio runs with the random block map enabled
444 and it fails to allocate the map, if this option is set it will
445 continue without a random block map. As coverage will not be as
446 complete as with random maps, this option is disabled by
447 default.
448 nice=int
450 Run job with given nice value. See nice(2).
451 prio=int
453 Set I/O priority value of this job between 0 (highest) and 7
454 (lowest). See ionice(1).
455 prioclass=int
457 Set I/O priority class. See ionice(1).
458 thinktime=int
460 Stall job for given number of microseconds between issuing I/Os.
461 thinktime_spin=int
463 Pretend to spend CPU time for given number of microseconds,
464 sleeping the rest of the time specified by thinktime. Only
465 valid if thinktime is set.
466 thinktime_blocks=int
468 Number of blocks to issue before waiting thinktime microseconds.
469 Default: 1.
470 rate=int
472 Cap bandwidth used by this job. The number is in bytes/sec, the
473 normal postfix rules apply. You can use rate=500k to limit reads
474 and writes to 500k each, or you can specify read and writes sep‐
475 arately. Using rate=1m,500k would limit reads to 1MB/sec and
476 writes to 500KB/sec. Capping only reads or writes can be done
477 with rate=,500k or rate=500k,. The former will only limit writes
478 (to 500KB/sec), the latter will only limit reads.
479 ratemin=int
481 Tell fio to do whatever it can to maintain at least the given
482 bandwidth. Failing to meet this requirement will cause the job
483 to exit. The same format as rate is used for read vs write sepa‐
484 ration.
485 rate_iops=int
487 Cap the bandwidth to this number of IOPS. Basically the same as
488 rate, just specified independently of bandwidth. The same format
489 as rate is used for read vs write seperation. If blocksize is a
490 range, the smallest block size is used as the metric.
491 rate_iops_min=int
493 If this rate of I/O is not met, the job will exit. The same for‐
494 mat as rate is used for read vs write seperation.
495 ratecycle=int
497 Average bandwidth for rate and ratemin over this number of mil‐
498 liseconds. Default: 1000ms.
499 cpumask=int
501 Set CPU affinity for this job. int is a bitmask of allowed CPUs
502 the job may run on. See sched_setaffinity(2).
503 cpus_allowed=str
505 Same as cpumask, but allows a comma-delimited list of CPU num‐
506 bers.
507 startdelay=int
509 Delay start of job for the specified number of seconds.
510 runtime=int
512 Terminate processing after the specified number of seconds.
513 time_based
515 If given, run for the specified runtime duration even if the
516 files are completely read or written. The same workload will be
517 repeated as many times as runtime allows.
518 ramp_time=int
520 If set, fio will run the specified workload for this amount of
521 time before logging any performance numbers. Useful for letting
522 performance settle before logging results, thus minimizing the
523 runtime required for stable results. Note that the ramp_time is
524 considered lead in time for a job, thus it will increase the
525 total runtime if a special timeout or runtime is specified.
526 invalidate=bool
528 Invalidate buffer-cache for the file prior to starting I/O.
529 Default: true.
530 sync=bool
532 Use synchronous I/O for buffered writes. For the majority of
533 I/O engines, this means using O_SYNC. Default: false.
534 iomem=str, mem=str
536 Allocation method for I/O unit buffer. Allowed values are:
537 malloc Allocate memory with malloc(3).
539 shm Use shared memory buffers allocated through
541 shmget(2).
542 shmhuge
544 Same as shm, but use huge pages as backing.
545 mmap Use mmap(2) for allocation. Uses anonymous memory
547 unless a filename is given after the option in the
548 format `:file'.
549 mmaphuge
551 Same as mmap, but use huge files as backing.
552 The amount of memory allocated is the maximum allowed blocksize
554 for the job multiplied by iodepth. For shmhuge or mmaphuge to
555 work, the system must have free huge pages allocated. mmaphuge
556 also needs to have hugetlbfs mounted, and file must point there.
557 At least on Linux, huge pages must be manually allocated. See
558 /proc/sys/vm/nr_hugehages and the documentation for that. Nor‐
559 mally you just need to echo an appropriate number, eg echoing 8
560 will ensure that the OS has 8 huge pages ready for use.
561 iomem_align=int
563 This indiciates the memory alignment of the IO memory buffers.
564 Note that the given alignment is applied to the first IO unit
565 buffer, if using iodepth the alignment of the following buffers
566 are given by the bs used. In other words, if using a bs that is
567 a multiple of the page sized in the system, all buffers will be
568 aligned to this value. If using a bs that is not page aligned,
569 the alignment of subsequent IO memory buffers is the sum of the
570 iomem_align and bs used.
571 hugepage-size=int
573 Defines the size of a huge page. Must be at least equal to the
574 system setting. Should be a multiple of 1MB. Default: 4MB.
575 exitall
577 Terminate all jobs when one finishes. Default: wait for each
578 job to finish.
579 bwavgtime=int
581 Average bandwidth calculations over the given time in millisec‐
582 onds. Default: 500ms.
583 create_serialize=bool
585 If true, serialize file creation for the jobs. Default: true.
586 create_fsync=bool
588 fsync(2) data file after creation. Default: true.
589 create_on_open=bool
591 If true, the files are not created until they are opened for IO
592 by the job.
593 pre_read=bool
595 If this is given, files will be pre-read into memory before
596 starting the given IO operation. This will also clear the
597 invalidate flag, since it is pointless to pre-read and then drop
598 the cache. This will only work for IO engines that are seekable,
599 since they allow you to read the same data multiple times. Thus
600 it will not work on eg network or splice IO.
601 unlink=bool
603 Unlink job files when done. Default: false.
604 loops=int
606 Specifies the number of iterations (runs of the same workload)
607 of this job. Default: 1.
608 do_verify=bool
610 Run the verify phase after a write phase. Only valid if verify
611 is set. Default: true.
612 verify=str
614 Method of verifying file contents after each iteration of the
615 job. Allowed values are:
616 md5 crc16 crc32 crc32c crc32c-intel crc64 crc7 sha256
618 sha512 sha1
619 Store appropriate checksum in the header of each
620 block. crc32c-intel is hardware accelerated SSE4.2
621 driven, falls back to regular crc32c if not sup‐
622 ported by the system.
623 meta Write extra information about each I/O (timestamp,
625 block number, etc.). The block number is verified.
626 See verify_pattern as well.
627 null Pretend to verify. Used for testing internals.
629 This option can be used for repeated burn-in tests of a system
631 to make sure that the written data is also correctly read back.
632 If the data direction given is a read or random read, fio will
633 assume that it should verify a previously written file. If the
634 data direction includes any form of write, the verify will be of
635 the newly written data.
636 verify_sort=bool
638 If true, written verify blocks are sorted if fio deems it to be
639 faster to read them back in a sorted manner. Default: true.
640 verify_offset=int
642 Swap the verification header with data somewhere else in the
643 block before writing. It is swapped back before verifying.
644 verify_interval=int
646 Write the verification header for this number of bytes, which
647 should divide blocksize. Default: blocksize.
648 verify_pattern=str
650 If set, fio will fill the io buffers with this pattern. Fio
651 defaults to filling with totally random bytes, but sometimes
652 it's interesting to fill with a known pattern for io verifica‐
653 tion purposes. Depending on the width of the pattern, fio will
654 fill 1/2/3/4 bytes of the buffer at the time(it can be either a
655 decimal or a hex number). The verify_pattern if larger than a
656 32-bit quantity has to be a hex number that starts with either
657 "0x" or "0X". Use with verify=meta.
658 verify_fatal=bool
660 If true, exit the job on the first observed verification fail‐
661 ure. Default: false.
662 verify_async=int
664 Fio will normally verify IO inline from the submitting thread.
665 This option takes an integer describing how many async offload
666 threads to create for IO verification instead, causing fio to
667 offload the duty of verifying IO contents to one or more sepa‐
668 rate threads. If using this offload option, even sync IO
669 engines can benefit from using an iodepth setting higher than 1,
670 as it allows them to have IO in flight while verifies are run‐
671 ning.
672 verify_async_cpus=str
674 Tell fio to set the given CPU affinity on the async IO verifica‐
675 tion threads. See cpus_allowed for the format used.
676 verify_backlog=int
678 Fio will normally verify the written contents of a job that uti‐
679 lizes verify once that job has completed. In other words, every‐
680 thing is written then everything is read back and verified. You
681 may want to verify continually instead for a variety of reasons.
682 Fio stores the meta data associated with an IO block in memory,
683 so for large verify workloads, quite a bit of memory would be
684 used up holding this meta data. If this option is enabled, fio
685 will verify the previously written blocks before continuing to
686 write new ones.
687 verify_backlog_batch=int
689 Control how many blocks fio will verify if verify_backlog is
690 set. If not set, will default to the value of verify_backlog
691 (meaning the entire queue is read back and verified).
692 stonewall
694 Wait for preceeding jobs in the job file to exit before starting
695 this one. stonewall implies new_group.
696 new_group
698 Start a new reporting group. If not given, all jobs in a file
699 will be part of the same reporting group, unless separated by a
700 stonewall.
701 numjobs=int
703 Number of clones (processes/threads performing the same work‐
704 load) of this job. Default: 1.
705 group_reporting
707 If set, display per-group reports instead of per-job when
708 numjobs is specified.
709 thread Use threads created with pthread_create(3) instead of processes
711 created with fork(2).
712 zonesize=int
714 Divide file into zones of the specified size in bytes. See
715 zoneskip.
716 zoneskip=int
718 Skip the specified number of bytes when zonesize bytes of data
719 have been read.
720 write_iolog=str
722 Write the issued I/O patterns to the specified file.
723 read_iolog=str
725 Replay the I/O patterns contained in the specified file gener‐
726 ated by write_iolog, or may be a blktrace binary file.
727 write_bw_log =str
729 If given, write a bandwidth log of the jobs in this job file.
730 Can be used to store data of the bandwidth of the jobs in their
731 lifetime. The included fio_generate_plots script uses gnuplot to
732 turn these text files into nice graphs. See write_log_log for
733 behaviour of given filename. For this option, the postfix is
734 _bw.log.
735 write_lat_log
737 Same as write_bw_log, but writes I/O completion latencies. If
738 no filename is given with this option, the default filename of
739 "jobname_type.log" is used. Even if the filename is given, fio
740 will still append the type of log.
741 disable_lat =bool
743 Disable measurements of total latency numbers. Useful only for
744 cutting back the number of calls to gettimeofday, as that does
745 impact performance at really high IOPS rates. Note that to
746 really get rid of a large amount of these calls, this option
747 must be used with disable_slat and disable_bw as well.
748 disable_clat =bool
750 Disable measurements of submission latency numbers. See dis‐
751 able_lat.
752 disable_slat =bool
754 Disable measurements of submission latency numbers. See dis‐
755 able_lat.
756 disable_bw_measurement =bool
758 Disable measurements of throughput/bandwidth numbers. See dis‐
759 able_lat.
760 lockmem=int
762 Pin the specified amount of memory with mlock(2). Can be used
763 to simulate a smaller amount of memory.
764 exec_prerun=str
766 Before running the job, execute the specified command with sys‐
767 tem(3).
768 exec_postrun=str
770 Same as exec_prerun, but the command is executed after the job
771 completes.
772 ioscheduler=str
774 Attempt to switch the device hosting the file to the specified
775 I/O scheduler.
776 cpuload=int
778 If the job is a CPU cycle-eater, attempt to use the specified
779 percentage of CPU cycles.
780 cpuchunks=int
782 If the job is a CPU cycle-eater, split the load into cycles of
783 the given time in milliseconds.
784 disk_util=bool
786 Generate disk utilization statistics if the platform supports
787 it. Default: true.
788 gtod_reduce=bool
790 Enable all of the gettimeofday() reducing options (disable_clat,
791 disable_slat, disable_bw) plus reduce precision of the timeout
792 somewhat to really shrink the gettimeofday() call count. With
793 this option enabled, we only do about 0.4% of the gtod() calls
794 we would have done if all time keeping was enabled.
795 gtod_cpu=int
797 Sometimes it's cheaper to dedicate a single thread of execution
798 to just getting the current time. Fio (and databases, for
799 instance) are very intensive on gettimeofday() calls. With this
800 option, you can set one CPU aside for doing nothing but logging
801 current time to a shared memory location. Then the other
802 threads/processes that run IO workloads need only copy that seg‐
803 ment, instead of entering the kernel with a gettimeofday() call.
804 The CPU set aside for doing these time calls will be excluded
805 from other uses. Fio will manually clear it from the CPU mask of
806 other jobs.
807 cgroup=str
809 Add job to this control group. If it doesn't exist, it will be
810 created. The system must have a mounted cgroup blkio mount
811 point for this to work. If your system doesn't have it mounted,
812 you can do so with:
813 # mount -t cgroup -o blkio none /cgroup
815 cgroup_weight=int
817 Set the weight of the cgroup to this value. See the documenta‐
818 tion that comes with the kernel, allowed values are in the range
819 of 100..1000.
820 cgroup_nodelete=bool
822 Normally fio will delete the cgroups it has created after the
823 job completion. To override this behavior and to leave cgroups
824 around after the job completion, set cgroup_nodelete=1. This can
825 be useful if one wants to inspect various cgroup files after job
826 completion. Default: false
827 uid=int
829 Instead of running as the invoking user, set the user ID to this
830 value before the thread/process does any work.
831 gid=int
833 Set group ID, see uid.
834
836 While running, fio will display the status of the created jobs. For
837 example:
838 Threads: 1: [_r] [24.8% done] [ 13509/ 8334 kb/s] [eta
840 00h:01m:31s]
841 The characters in the first set of brackets denote the current status
843 of each threads. The possible values are:
844 P Setup but not started.
846 C Thread created.
847 I Initialized, waiting.
848 R Running, doing sequential reads.
849 r Running, doing random reads.
850 W Running, doing sequential writes.
851 w Running, doing random writes.
852 M Running, doing mixed sequential reads/writes.
853 m Running, doing mixed random reads/writes.
854 F Running, currently waiting for fsync(2).
855 V Running, verifying written data.
856 E Exited, not reaped by main thread.
857 - Exited, thread reaped.
858 The second set of brackets shows the estimated completion percentage of
860 the current group. The third set shows the read and write I/O rate,
861 respectively. Finally, the estimated run time of the job is displayed.
862 When fio completes (or is interrupted by Ctrl-C), it will show data for
864 each thread, each group of threads, and each disk, in that order.
865 Per-thread statistics first show the threads client number, group-id,
867 and error code. The remaining figures are as follows:
868 io Number of megabytes of I/O performed.
870 bw Average data rate (bandwidth).
872 runt Threads run time.
874 slat Submission latency minimum, maximum, average and standard
876 deviation. This is the time it took to submit the I/O.
877 clat Completion latency minimum, maximum, average and standard
879 deviation. This is the time between submission and com‐
880 pletion.
881 bw Bandwidth minimum, maximum, percentage of aggregate band‐
883 width received, average and standard deviation.
884 cpu CPU usage statistics. Includes user and system time, num‐
886 ber of context switches this thread went through and num‐
887 ber of major and minor page faults.
888 IO depths
890 Distribution of I/O depths. Each depth includes every‐
891 thing less than (or equal) to it, but greater than the
892 previous depth.
893 IO issued
895 Number of read/write requests issued, and number of short
896 read/write requests.
897 IO latencies
899 Distribution of I/O completion latencies. The numbers
900 follow the same pattern as IO depths.
901 The group statistics show:
903 io Number of megabytes I/O performed.
904 aggrb Aggregate bandwidth of threads in the group.
905 minb Minimum average bandwidth a thread saw.
906 maxb Maximum average bandwidth a thread saw.
907 mint Shortest runtime of threads in the group.
908 maxt Longest runtime of threads in the group.
909 Finally, disk statistics are printed with reads first:
911 ios Number of I/Os performed by all groups.
912 merge Number of merges in the I/O scheduler.
913 ticks Number of ticks we kept the disk busy.
914 io_queue
915 Total time spent in the disk queue.
916 util Disk utilization.
917
919 If the --minimal option is given, the results will be printed in a
920 semicolon-delimited format suitable for scripted use. The fields are:
921 jobname, groupid, error
923 Read status:
925 KB I/O, bandwidth (KB/s), runtime (ms)
926 Submission latency:
928 min, max, mean, standard deviation
929 Completion latency:
930 min, max, mean, standard deviation
931 Bandwidth:
932 min, max, aggregate percentage of total, mean,
933 standard deviation
934 Write status:
936 KB I/O, bandwidth (KB/s), runtime (ms)
937 Submission latency:
939 min, max, mean, standard deviation
940 Completion latency:
941 min, max, mean, standard deviation
942 Bandwidth:
943 min, max, aggregate percentage of total, mean,
944 standard deviation
945 CPU usage:
947 user, system, context switches, major page faults, minor
948 page faults
949 IO depth distribution:
951 <=1, 2, 4, 8, 16, 32, >=64
952 IO latency distribution (ms):
954 <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, >=2000
955 text description
957
959 fio was written by Jens Axboe <jens.axboe@oracle.com>, now Jens Axboe
960 <jaxboe@fusionio.com>.
961 This man page was written by Aaron Carroll <aaronc@cse.unsw.edu.au>
962 based on documentation by Jens Axboe.
963
965 Report bugs to the fio mailing list <fio@vger.kernel.org>. See README.
966
968 For further documentation see HOWTO and README.
969 Sample jobfiles are available in the examples directory.
970User Manual September 2007 fio(1)