forked from axboe/fio
-
Notifications
You must be signed in to change notification settings - Fork 0
/
fio.1
4936 lines (4914 loc) · 185 KB
/
fio.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.TH fio 1 "August 2017" "User Manual"
.SH NAME
fio \- flexible I/O tester
.SH SYNOPSIS
.B fio
[\fIoptions\fR] [\fIjobfile\fR]...
.SH DESCRIPTION
.B fio
is a tool that will spawn a number of threads or processes doing a
particular type of I/O action as specified by the user.
The typical use of fio is to write a job file matching the I/O load
one wants to simulate.
.SH OPTIONS
.TP
.BI \-\-debug \fR=\fPtype
Enable verbose tracing \fItype\fR of various fio actions. May be `all' for all \fItype\fRs
or individual types separated by a comma (e.g. `\-\-debug=file,mem' will enable
file and memory debugging). `help' will list all available tracing options.
.TP
.BI \-\-parse\-only
Parse options only, don't start any I/O.
.TP
.BI \-\-merge\-blktrace\-only
Merge blktraces only, don't start any I/O.
.TP
.BI \-\-output \fR=\fPfilename
Write output to \fIfilename\fR.
.TP
.BI \-\-output\-format \fR=\fPformat
Set the reporting \fIformat\fR to `normal', `terse', `json', or
`json+'. Multiple formats can be selected, separate by a comma. `terse'
is a CSV based format. `json+' is like `json', except it adds a full
dump of the latency buckets.
.TP
.BI \-\-bandwidth\-log
Generate aggregate bandwidth logs.
.TP
.BI \-\-minimal
Print statistics in a terse, semicolon\-delimited format.
.TP
.BI \-\-append\-terse
Print statistics in selected mode AND terse, semicolon\-delimited format.
\fBDeprecated\fR, use \fB\-\-output\-format\fR instead to select multiple formats.
.TP
.BI \-\-terse\-version \fR=\fPversion
Set terse \fIversion\fR output format (default `3', or `2', `4', `5').
.TP
.BI \-\-version
Print version information and exit.
.TP
.BI \-\-help
Print a summary of the command line options and exit.
.TP
.BI \-\-cpuclock\-test
Perform test and validation of internal CPU clock.
.TP
.BI \-\-crctest \fR=\fP[test]
Test the speed of the built\-in checksumming functions. If no argument is given,
all of them are tested. Alternatively, a comma separated list can be passed, in which
case the given ones are tested.
.TP
.BI \-\-cmdhelp \fR=\fPcommand
Print help information for \fIcommand\fR. May be `all' for all commands.
.TP
.BI \-\-enghelp \fR=\fP[ioengine[,command]]
List all commands defined by \fIioengine\fR, or print help for \fIcommand\fR
defined by \fIioengine\fR. If no \fIioengine\fR is given, list all
available ioengines.
.TP
.BI \-\-showcmd
Convert given \fIjobfile\fRs to a set of command\-line options.
.TP
.BI \-\-readonly
Turn on safety read\-only checks, preventing writes and trims. The \fB\-\-readonly\fR
option is an extra safety guard to prevent users from accidentally starting
a write or trim workload when that is not desired. Fio will only modify the
device under test if `rw=write/randwrite/rw/randrw/trim/randtrim/trimwrite'
is given. This safety net can be used as an extra precaution.
.TP
.BI \-\-eta \fR=\fPwhen
Specifies when real\-time ETA estimate should be printed. \fIwhen\fR may
be `always', `never' or `auto'. `auto' is the default, it prints ETA when
requested if the output is a TTY. `always' disregards the output type, and
prints ETA when requested. `never' never prints ETA.
.TP
.BI \-\-eta\-interval \fR=\fPtime
By default, fio requests client ETA status roughly every second. With this
option, the interval is configurable. Fio imposes a minimum allowed time to
avoid flooding the console, less than 250 msec is not supported.
.TP
.BI \-\-eta\-newline \fR=\fPtime
Force a new line for every \fItime\fR period passed. When the unit is omitted,
the value is interpreted in seconds.
.TP
.BI \-\-status\-interval \fR=\fPtime
Force a full status dump of cumulative (from job start) values at \fItime\fR
intervals. This option does *not* provide per-period measurements. So
values such as bandwidth are running averages. When the time unit is omitted,
\fItime\fR is interpreted in seconds. Note that using this option with
`\-\-output-format=json' will yield output that technically isn't valid json,
since the output will be collated sets of valid json. It will need to be split
into valid sets of json after the run.
.TP
.BI \-\-section \fR=\fPname
Only run specified section \fIname\fR in job file. Multiple sections can be specified.
The \fB\-\-section\fR option allows one to combine related jobs into one file.
E.g. one job file could define light, moderate, and heavy sections. Tell
fio to run only the "heavy" section by giving `\-\-section=heavy'
command line option. One can also specify the "write" operations in one
section and "verify" operation in another section. The \fB\-\-section\fR option
only applies to job sections. The reserved *global* section is always
parsed and used.
.TP
.BI \-\-alloc\-size \fR=\fPkb
Allocate additional internal smalloc pools of size \fIkb\fR in KiB. The
\fB\-\-alloc\-size\fR option increases shared memory set aside for use by fio.
If running large jobs with randommap enabled, fio can run out of memory.
Smalloc is an internal allocator for shared structures from a fixed size
memory pool and can grow to 16 pools. The pool size defaults to 16MiB.
NOTE: While running `.fio_smalloc.*' backing store files are visible
in `/tmp'.
.TP
.BI \-\-warnings\-fatal
All fio parser warnings are fatal, causing fio to exit with an error.
.TP
.BI \-\-max\-jobs \fR=\fPnr
Set the maximum number of threads/processes to support to \fInr\fR.
NOTE: On Linux, it may be necessary to increase the shared-memory limit
(`/proc/sys/kernel/shmmax') if fio runs into errors while creating jobs.
.TP
.BI \-\-server \fR=\fPargs
Start a backend server, with \fIargs\fR specifying what to listen to.
See \fBCLIENT/SERVER\fR section.
.TP
.BI \-\-daemonize \fR=\fPpidfile
Background a fio server, writing the pid to the given \fIpidfile\fR file.
.TP
.BI \-\-client \fR=\fPhostname
Instead of running the jobs locally, send and run them on the given \fIhostname\fR
or set of \fIhostname\fRs. See \fBCLIENT/SERVER\fR section.
.TP
.BI \-\-remote\-config \fR=\fPfile
Tell fio server to load this local \fIfile\fR.
.TP
.BI \-\-idle\-prof \fR=\fPoption
Report CPU idleness. \fIoption\fR is one of the following:
.RS
.RS
.TP
.B calibrate
Run unit work calibration only and exit.
.TP
.B system
Show aggregate system idleness and unit work.
.TP
.B percpu
As \fBsystem\fR but also show per CPU idleness.
.RE
.RE
.TP
.BI \-\-inflate\-log \fR=\fPlog
Inflate and output compressed \fIlog\fR.
.TP
.BI \-\-trigger\-file \fR=\fPfile
Execute trigger command when \fIfile\fR exists.
.TP
.BI \-\-trigger\-timeout \fR=\fPtime
Execute trigger at this \fItime\fR.
.TP
.BI \-\-trigger \fR=\fPcommand
Set this \fIcommand\fR as local trigger.
.TP
.BI \-\-trigger\-remote \fR=\fPcommand
Set this \fIcommand\fR as remote trigger.
.TP
.BI \-\-aux\-path \fR=\fPpath
Use the directory specified by \fIpath\fP for generated state files instead
of the current working directory.
.SH "JOB FILE FORMAT"
Any parameters following the options will be assumed to be job files, unless
they match a job file parameter. Multiple job files can be listed and each job
file will be regarded as a separate group. Fio will \fBstonewall\fR execution
between each group.
Fio accepts one or more job files describing what it is
supposed to do. The job file format is the classic ini file, where the names
enclosed in [] brackets define the job name. You are free to use any ASCII name
you want, except *global* which has special meaning. Following the job name is
a sequence of zero or more parameters, one per line, that define the behavior of
the job. If the first character in a line is a ';' or a '#', the entire line is
discarded as a comment.
A *global* section sets defaults for the jobs described in that file. A job may
override a *global* section parameter, and a job file may even have several
*global* sections if so desired. A job is only affected by a *global* section
residing above it.
The \fB\-\-cmdhelp\fR option also lists all options. If used with an \fIcommand\fR
argument, \fB\-\-cmdhelp\fR will detail the given \fIcommand\fR.
See the `examples/' directory for inspiration on how to write job files. Note
the copyright and license requirements currently apply to
`examples/' files.
Note that the maximum length of a line in the job file is 8192 bytes.
.SH "JOB FILE PARAMETERS"
Some parameters take an option of a given type, such as an integer or a
string. Anywhere a numeric value is required, an arithmetic expression may be
used, provided it is surrounded by parentheses. Supported operators are:
.RS
.P
.B addition (+)
.P
.B subtraction (\-)
.P
.B multiplication (*)
.P
.B division (/)
.P
.B modulus (%)
.P
.B exponentiation (^)
.RE
.P
For time values in expressions, units are microseconds by default. This is
different than for time values not in expressions (not enclosed in
parentheses).
.SH "PARAMETER TYPES"
The following parameter types are used.
.TP
.I str
String. A sequence of alphanumeric characters.
.TP
.I time
Integer with possible time suffix. Without a unit value is interpreted as
seconds unless otherwise specified. Accepts a suffix of 'd' for days, 'h' for
hours, 'm' for minutes, 's' for seconds, 'ms' (or 'msec') for milliseconds and 'us'
(or 'usec') for microseconds. For example, use 10m for 10 minutes.
.TP
.I int
Integer. A whole number value, which may contain an integer prefix
and an integer suffix.
.RS
.RS
.P
[*integer prefix*] **number** [*integer suffix*]
.RE
.P
The optional *integer prefix* specifies the number's base. The default
is decimal. *0x* specifies hexadecimal.
.P
The optional *integer suffix* specifies the number's units, and includes an
optional unit prefix and an optional unit. For quantities of data, the
default unit is bytes. For quantities of time, the default unit is seconds
unless otherwise specified.
.P
With `kb_base=1000', fio follows international standards for unit
prefixes. To specify power-of-10 decimal values defined in the
International System of Units (SI):
.RS
.P
.PD 0
K means kilo (K) or 1000
.P
M means mega (M) or 1000**2
.P
G means giga (G) or 1000**3
.P
T means tera (T) or 1000**4
.P
P means peta (P) or 1000**5
.PD
.RE
.P
To specify power-of-2 binary values defined in IEC 80000-13:
.RS
.P
.PD 0
Ki means kibi (Ki) or 1024
.P
Mi means mebi (Mi) or 1024**2
.P
Gi means gibi (Gi) or 1024**3
.P
Ti means tebi (Ti) or 1024**4
.P
Pi means pebi (Pi) or 1024**5
.PD
.RE
.P
For Zone Block Device Mode:
.RS
.P
.PD 0
z means Zone
.P
.PD
.RE
.P
With `kb_base=1024' (the default), the unit prefixes are opposite
from those specified in the SI and IEC 80000-13 standards to provide
compatibility with old scripts. For example, 4k means 4096.
.P
For quantities of data, an optional unit of 'B' may be included
(e.g., 'kB' is the same as 'k').
.P
The *integer suffix* is not case sensitive (e.g., m/mi mean mebi/mega,
not milli). 'b' and 'B' both mean byte, not bit.
.P
Examples with `kb_base=1000':
.RS
.P
.PD 0
4 KiB: 4096, 4096b, 4096B, 4k, 4kb, 4kB, 4K, 4KB
.P
1 MiB: 1048576, 1m, 1024k
.P
1 MB: 1000000, 1mi, 1000ki
.P
1 TiB: 1073741824, 1t, 1024m, 1048576k
.P
1 TB: 1000000000, 1ti, 1000mi, 1000000ki
.PD
.RE
.P
Examples with `kb_base=1024' (default):
.RS
.P
.PD 0
4 KiB: 4096, 4096b, 4096B, 4k, 4kb, 4kB, 4K, 4KB
.P
1 MiB: 1048576, 1m, 1024k
.P
1 MB: 1000000, 1mi, 1000ki
.P
1 TiB: 1073741824, 1t, 1024m, 1048576k
.P
1 TB: 1000000000, 1ti, 1000mi, 1000000ki
.PD
.RE
.P
To specify times (units are not case sensitive):
.RS
.P
.PD 0
D means days
.P
H means hours
.P
M mean minutes
.P
s or sec means seconds (default)
.P
ms or msec means milliseconds
.P
us or usec means microseconds
.PD
.RE
.P
`z' suffix specifies that the value is measured in zones.
Value is recalculated once block device's zone size becomes known.
.P
If the option accepts an upper and lower range, use a colon ':' or
minus '\-' to separate such values. See \fIirange\fR parameter type.
If the lower value specified happens to be larger than the upper value
the two values are swapped.
.RE
.TP
.I bool
Boolean. Usually parsed as an integer, however only defined for
true and false (1 and 0).
.TP
.I irange
Integer range with suffix. Allows value range to be given, such as
1024\-4096. A colon may also be used as the separator, e.g. 1k:4k. If the
option allows two sets of ranges, they can be specified with a ',' or '/'
delimiter: 1k\-4k/8k\-32k. Also see \fIint\fR parameter type.
.TP
.I float_list
A list of floating point numbers, separated by a ':' character.
.SH "JOB PARAMETERS"
With the above in mind, here follows the complete list of fio job parameters.
.SS "Units"
.TP
.BI kb_base \fR=\fPint
Select the interpretation of unit prefixes in input parameters.
.RS
.RS
.TP
.B 1000
Inputs comply with IEC 80000-13 and the International
System of Units (SI). Use:
.RS
.P
.PD 0
\- power-of-2 values with IEC prefixes (e.g., KiB)
.P
\- power-of-10 values with SI prefixes (e.g., kB)
.PD
.RE
.TP
.B 1024
Compatibility mode (default). To avoid breaking old scripts:
.P
.RS
.PD 0
\- power-of-2 values with SI prefixes
.P
\- power-of-10 values with IEC prefixes
.PD
.RE
.RE
.P
See \fBbs\fR for more details on input parameters.
.P
Outputs always use correct prefixes. Most outputs include both
side-by-side, like:
.P
.RS
bw=2383.3kB/s (2327.4KiB/s)
.RE
.P
If only one value is reported, then kb_base selects the one to use:
.P
.RS
.PD 0
1000 \-\- SI prefixes
.P
1024 \-\- IEC prefixes
.PD
.RE
.RE
.TP
.BI unit_base \fR=\fPint
Base unit for reporting. Allowed values are:
.RS
.RS
.TP
.B 0
Use auto-detection (default).
.TP
.B 8
Byte based.
.TP
.B 1
Bit based.
.RE
.RE
.SS "Job description"
.TP
.BI name \fR=\fPstr
ASCII name of the job. This may be used to override the name printed by fio
for this job. Otherwise the job name is used. On the command line this
parameter has the special purpose of also signaling the start of a new job.
.TP
.BI description \fR=\fPstr
Text description of the job. Doesn't do anything except dump this text
description when this job is run. It's not parsed.
.TP
.BI loops \fR=\fPint
Run the specified number of iterations of this job. Used to repeat the same
workload a given number of times. Defaults to 1.
.TP
.BI numjobs \fR=\fPint
Create the specified number of clones of this job. Each clone of job
is spawned as an independent thread or process. May be used to setup a
larger number of threads/processes doing the same thing. Each thread is
reported separately; to see statistics for all clones as a whole, use
\fBgroup_reporting\fR in conjunction with \fBnew_group\fR.
See \fB\-\-max\-jobs\fR. Default: 1.
.SS "Time related parameters"
.TP
.BI runtime \fR=\fPtime
Limit runtime. The test will run until it completes the configured I/O
workload or until it has run for this specified amount of time, whichever
occurs first. It can be quite hard to determine for how long a specified
job will run, so this parameter is handy to cap the total runtime to a
given time. When the unit is omitted, the value is interpreted in
seconds.
.TP
.BI time_based
If set, fio will run for the duration of the \fBruntime\fR specified
even if the file(s) are completely read or written. It will simply loop over
the same workload as many times as the \fBruntime\fR allows.
.TP
.BI startdelay \fR=\fPirange(int)
Delay the start of job for the specified amount of time. Can be a single
value or a range. When given as a range, each thread will choose a value
randomly from within the range. Value is in seconds if a unit is omitted.
.TP
.BI ramp_time \fR=\fPtime
If set, fio will run the specified workload for this amount of time before
logging any performance numbers. Useful for letting performance settle
before logging results, thus minimizing the runtime required for stable
results. Note that the \fBramp_time\fR is considered lead in time for a job,
thus it will increase the total runtime if a special timeout or
\fBruntime\fR is specified. When the unit is omitted, the value is
given in seconds.
.TP
.BI clocksource \fR=\fPstr
Use the given clocksource as the base of timing. The supported options are:
.RS
.RS
.TP
.B gettimeofday
\fBgettimeofday\fR\|(2)
.TP
.B clock_gettime
\fBclock_gettime\fR\|(2)
.TP
.B cpu
Internal CPU clock source
.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.
.RE
.TP
.BI gtod_reduce \fR=\fPbool
Enable all of the \fBgettimeofday\fR\|(2) reducing options
(\fBdisable_clat\fR, \fBdisable_slat\fR, \fBdisable_bw_measurement\fR) plus
reduce precision of the timeout somewhat to really shrink the
\fBgettimeofday\fR\|(2) call count. With this option enabled, we only do
about 0.4% of the \fBgettimeofday\fR\|(2) calls we would have done if all
time keeping was enabled.
.TP
.BI gtod_cpu \fR=\fPint
Sometimes it's cheaper to dedicate a single thread of execution to just
getting the current time. Fio (and databases, for instance) are very
intensive on \fBgettimeofday\fR\|(2) calls. With this option, you can set
one CPU aside for doing nothing but logging current time to a shared memory
location. Then the other threads/processes that run I/O workloads need only
copy that segment, instead of entering the kernel with a
\fBgettimeofday\fR\|(2) call. The CPU set aside for doing these time
calls will be excluded from other uses. Fio will manually clear it from the
CPU mask of other jobs.
.TP
.BI job_start_clock_id \fR=\fPint
The clock_id passed to the call to \fBclock_gettime\fR used to record job_start
in the \fBjson\fR output format. Default is 0, or CLOCK_REALTIME.
.SS "Target file/device"
.TP
.BI directory \fR=\fPstr
Prefix \fBfilename\fRs with this directory. Used to place files in a different
location than `./'. You can specify a number of directories by
separating the names with a ':' character. These directories will be
assigned equally distributed to job clones created by \fBnumjobs\fR as
long as they are using generated filenames. If specific \fBfilename\fR(s) are
set fio will use the first listed directory, and thereby matching the
\fBfilename\fR semantic (which generates a file for each clone if not
specified, but lets all clones use the same file if set).
.RS
.P
See the \fBfilename\fR option for information on how to escape ':'
characters within the directory path itself.
.P
Note: To control the directory fio will use for internal state files
use \fB\-\-aux\-path\fR.
.RE
.TP
.BI filename \fR=\fPstr
Fio normally makes up a \fBfilename\fR based on the job name, thread number, and
file number (see \fBfilename_format\fR). If you want to share files
between threads in a job or several
jobs with fixed file paths, specify a \fBfilename\fR for each of them to override
the default. If the ioengine is file based, you can specify a number of files
by separating the names with a ':' colon. So if you wanted a job to open
`/dev/sda' and `/dev/sdb' as the two working files, you would use
`filename=/dev/sda:/dev/sdb'. This also means that whenever this option is
specified, \fBnrfiles\fR is ignored. The size of regular files specified
by this option will be \fBsize\fR divided by number of files unless an
explicit size is specified by \fBfilesize\fR.
.RS
.P
Each colon in the wanted path must be escaped with a '\e'
character. For instance, if the path is `/dev/dsk/foo@3,0:c' then you
would use `filename=/dev/dsk/foo@3,0\\:c' and if the path is
`F:\\filename' then you would use `filename=F\\:\\filename'.
.P
On Windows, disk devices are accessed as `\\\\.\\PhysicalDrive0' for
the first device, `\\\\.\\PhysicalDrive1' for the second etc.
Note: Windows and FreeBSD prevent write access to areas
of the disk containing in-use data (e.g. filesystems).
.P
The filename `\-' is a reserved name, meaning *stdin* or *stdout*. Which
of the two depends on the read/write direction set.
.RE
.TP
.BI filename_format \fR=\fPstr
If sharing multiple files between jobs, it is usually necessary to have fio
generate the exact names that you want. By default, fio will name a file
based on the default file format specification of
`jobname.jobnumber.filenumber'. With this option, that can be
customized. Fio will recognize and replace the following keywords in this
string:
.RS
.RS
.TP
.B $jobname
The name of the worker thread or process.
.TP
.B $clientuid
IP of the fio process when using client/server mode.
.TP
.B $jobnum
The incremental number of the worker thread or process.
.TP
.B $filenum
The incremental number of the file for that worker thread or process.
.RE
.P
To have dependent jobs share a set of files, this option can be set to have
fio generate filenames that are shared between the two. For instance, if
`testfiles.$filenum' is specified, file number 4 for any job will be
named `testfiles.4'. The default of `$jobname.$jobnum.$filenum'
will be used if no other format specifier is given.
.P
If you specify a path then the directories will be created up to the main
directory for the file. So for example if you specify `a/b/c/$jobnum` then the
directories a/b/c will be created before the file setup part of the job. If you
specify \fBdirectory\fR then the path will be relative that directory, otherwise
it is treated as the absolute path.
.RE
.TP
.BI unique_filename \fR=\fPbool
To avoid collisions between networked clients, fio defaults to prefixing any
generated filenames (with a directory specified) with the source of the
client connecting. To disable this behavior, set this option to 0.
.TP
.BI opendir \fR=\fPstr
Recursively open any files below directory \fIstr\fR. This accepts only a
single directory and unlike related options, colons appearing in the path must
not be escaped.
.TP
.BI lockfile \fR=\fPstr
Fio defaults to not locking any files before it does I/O to them. If a file
or file descriptor is shared, fio can serialize I/O to that file to make the
end result consistent. This is usual for emulating real workloads that share
files. The lock modes are:
.RS
.RS
.TP
.B none
No locking. The default.
.TP
.B exclusive
Only one thread or process may do I/O at a time, excluding all others.
.TP
.B readwrite
Read\-write locking on the file. Many readers may
access the file at the same time, but writes get exclusive access.
.RE
.RE
.TP
.BI nrfiles \fR=\fPint
Number of files to use for this job. Defaults to 1. The size of files
will be \fBsize\fR divided by this unless explicit size is specified by
\fBfilesize\fR. Files are created for each thread separately, and each
file will have a file number within its name by default, as explained in
\fBfilename\fR section.
.TP
.BI openfiles \fR=\fPint
Number of files to keep open at the same time. Defaults to the same as
\fBnrfiles\fR, can be set smaller to limit the number simultaneous
opens.
.TP
.BI file_service_type \fR=\fPstr
Defines how fio decides which file from a job to service next. The following
types are defined:
.RS
.RS
.TP
.B random
Choose a file at random.
.TP
.B roundrobin
Round robin over opened files. This is the default.
.TP
.B sequential
Finish one file before moving on to the next. Multiple files can
still be open depending on \fBopenfiles\fR.
.TP
.B zipf
Use a Zipf distribution to decide what file to access.
.TP
.B pareto
Use a Pareto distribution to decide what file to access.
.TP
.B normal
Use a Gaussian (normal) distribution to decide what file to access.
.TP
.B gauss
Alias for normal.
.RE
.P
For \fBrandom\fR, \fBroundrobin\fR, and \fBsequential\fR, a postfix can be appended to
tell fio how many I/Os to issue before switching to a new file. For example,
specifying `file_service_type=random:8' would cause fio to issue
8 I/Os before selecting a new file at random. For the non-uniform
distributions, a floating point postfix can be given to influence how the
distribution is skewed. See \fBrandom_distribution\fR for a description
of how that would work.
.RE
.TP
.BI ioscheduler \fR=\fPstr
Attempt to switch the device hosting the file to the specified I/O scheduler
before running. If the file is a pipe, a character device file or if device
hosting the file could not be determined, this option is ignored.
.TP
.BI create_serialize \fR=\fPbool
If true, serialize the file creation for the jobs. This may be handy to
avoid interleaving of data files, which may greatly depend on the filesystem
used and even the number of processors in the system. Default: true.
.TP
.BI create_fsync \fR=\fPbool
\fBfsync\fR\|(2) the data file after creation. This is the default.
.TP
.BI create_on_open \fR=\fPbool
If true, don't pre-create files but allow the job's open() to create a file
when it's time to do I/O. Default: false \-\- pre-create all necessary files
when the job starts.
.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. Default: false.
.TP
.BI allow_file_create \fR=\fPbool
If true, fio is permitted to create files as part of its workload. If this
option is false, then fio will error out if
the files it needs to use don't already exist. Default: true.
.TP
.BI allow_mounted_write \fR=\fPbool
If this isn't set, fio will abort jobs that are destructive (e.g. that write)
to what appears to be a mounted device or partition. This should help catch
creating inadvertently destructive tests, not realizing that the test will
destroy data on the mounted file system. Note that some platforms don't allow
writing against a mounted device regardless of this option. Default: false.
.TP
.BI pre_read \fR=\fPbool
If this is given, files will be pre-read into memory before starting the
given I/O operation. This will also clear the \fBinvalidate\fR flag,
since it is pointless to pre-read and then drop the cache. This will only
work for I/O engines that are seek-able, since they allow you to read the
same data multiple times. Thus it will not work on non-seekable I/O engines
(e.g. network, splice). Default: false.
.TP
.BI unlink \fR=\fPbool
Unlink the job files when done. Not the default, as repeated runs of that
job would then waste time recreating the file set again and again. Default:
false.
.TP
.BI unlink_each_loop \fR=\fPbool
Unlink job files after each iteration or loop. Default: false.
.TP
.BI zonemode \fR=\fPstr
Accepted values are:
.RS
.RS
.TP
.B none
The \fBzonerange\fR, \fBzonesize\fR \fBzonecapacity\fR and \fBzoneskip\fR
parameters are ignored.
.TP
.B strided
I/O happens in a single zone until \fBzonesize\fR bytes have been transferred.
After that number of bytes has been transferred processing of the next zone
starts. The \fBzonecapacity\fR parameter is ignored.
.TP
.B zbd
Zoned block device mode. I/O happens sequentially in each zone, even if random
I/O has been selected. Random I/O happens across all zones instead of being
restricted to a single zone.
Trim is handled using a zone reset operation. Trim only considers non-empty
sequential write required and sequential write preferred zones.
.RE
.RE
.TP
.BI zonerange \fR=\fPint
For \fBzonemode\fR=strided, this is the size of a single zone. See also
\fBzonesize\fR and \fBzoneskip\fR.
For \fBzonemode\fR=zbd, this parameter is ignored.
.TP
.BI zonesize \fR=\fPint
For \fBzonemode\fR=strided, this is the number of bytes to transfer before
skipping \fBzoneskip\fR bytes. If this parameter is smaller than
\fBzonerange\fR then only a fraction of each zone with \fBzonerange\fR bytes
will be accessed. If this parameter is larger than \fBzonerange\fR then each
zone will be accessed multiple times before skipping to the next zone.
For \fBzonemode\fR=zbd, this is the size of a single zone. The
\fBzonerange\fR parameter is ignored in this mode. For a job accessing a
zoned block device, the specified \fBzonesize\fR must be 0 or equal to the
device zone size. For a regular block device or file, the specified
\fBzonesize\fR must be at least 512B.
.TP
.BI zonecapacity \fR=\fPint
For \fBzonemode\fR=zbd, this defines the capacity of a single zone, which is
the accessible area starting from the zone start address. This parameter only
applies when using \fBzonemode\fR=zbd in combination with regular block devices.
If not specified it defaults to the zone size. If the target device is a zoned
block device, the zone capacity is obtained from the device information and this
option is ignored.
.TP
.BI zoneskip \fR=\fPint[z]
For \fBzonemode\fR=strided, the number of bytes to skip after \fBzonesize\fR
bytes of data have been transferred.
For \fBzonemode\fR=zbd, the \fBzonesize\fR aligned number of bytes to skip
once a zone is fully written (write workloads) or all written data in the
zone have been read (read workloads). This parameter is valid only for
sequential workloads and ignored for random workloads. For read workloads,
see also \fBread_beyond_wp\fR.
.TP
.BI read_beyond_wp \fR=\fPbool
This parameter applies to \fBzonemode=zbd\fR only.
Zoned block devices are block devices that consist of multiple zones. Each
zone has a type, e.g. conventional or sequential. A conventional zone can be
written at any offset that is a multiple of the block size. Sequential zones
must be written sequentially. The position at which a write must occur is
called the write pointer. A zoned block device can be either host managed or
host aware. For host managed devices the host must ensure that writes happen
sequentially. Fio recognizes host managed devices and serializes writes to
sequential zones for these devices.
If a read occurs in a sequential zone beyond the write pointer then the zoned
block device will complete the read without reading any data from the storage
medium. Since such reads lead to unrealistically high bandwidth and IOPS
numbers fio only reads beyond the write pointer if explicitly told to do
so. Default: false.
.TP
.BI max_open_zones \fR=\fPint
When a zone of a zoned block device is partially written (i.e. not all sectors
of the zone have been written), the zone is in one of three
conditions: 'implicit open', 'explicit open' or 'closed'. Zoned block devices
may have a limit called 'max_open_zones' (same name as the parameter) on the
total number of zones that can simultaneously be in the 'implicit open'
or 'explicit open' conditions. Zoned block devices may have another limit
called 'max_active_zones', on the total number of zones that can simultaneously
be in the three conditions. The \fBmax_open_zones\fR parameter limits
the number of zones to which write commands are issued by all fio jobs, that is,
limits the number of zones that will be in the conditions. When the device has
the max_open_zones limit and does not have the max_active_zones limit, the
\fBmax_open_zones\fR parameter limits the number of zones in the two open
conditions up to the limit. In this case, fio includes zones in the two open
conditions to the write target zones at fio start. When the device has both the
max_open_zones and the max_active_zones limits, the \fBmax_open_zones\fR
parameter limits the number of zones in the three conditions up to the limit.
In this case, fio includes zones in the three conditions to the write target
zones at fio start.
This parameter is relevant only if the \fBzonemode=zbd\fR is used. The default
value is always equal to the max_open_zones limit of the target zoned block
device and a value higher than this limit cannot be specified by users unless
the option \fBignore_zone_limits\fR is specified. When \fBignore_zone_limits\fR
is specified or the target device does not have the max_open_zones limit,
\fBmax_open_zones\fR can specify 0 to disable any limit on the number of zones
that can be simultaneously written to by all jobs.
.TP
.BI job_max_open_zones \fR=\fPint
In the same manner as \fBmax_open_zones\fR, limit the number of open zones per
fio job, that is, the number of zones that a single job can simultaneously write
to. A value of zero indicates no limit. Default: zero.
.TP
.BI ignore_zone_limits \fR=\fPbool
If this option is used, fio will ignore the maximum number of open zones limit
of the zoned block device in use, thus allowing the option \fBmax_open_zones\fR
value to be larger than the device reported limit. Default: false.
.TP
.BI zone_reset_threshold \fR=\fPfloat
A number between zero and one that indicates the ratio of written bytes in the
zones with write pointers in the IO range to the size of the IO range. When
current ratio is above this ratio, zones are reset periodically as
\fBzone_reset_frequency\fR specifies. If there are multiple jobs when using this
option, the IO range for all write jobs has to be the same.
.TP
.BI zone_reset_frequency \fR=\fPfloat
A number between zero and one that indicates how often a zone reset should be
issued if the zone reset threshold has been exceeded. A zone reset is
submitted after each (1 / zone_reset_frequency) write requests. This and the
previous parameter can be used to simulate garbage collection activity.
.SS "I/O type"
.TP
.BI direct \fR=\fPbool
If value is true, use non-buffered I/O. This is usually O_DIRECT. Note that
OpenBSD and ZFS on Solaris don't support direct I/O. On Windows the synchronous
ioengines don't support direct I/O. Default: false.
.TP
.BI buffered \fR=\fPbool
If value is true, use buffered I/O. This is the opposite of the
\fBdirect\fR option. Defaults to true.
.TP
.BI readwrite \fR=\fPstr "\fR,\fP rw" \fR=\fPstr
Type of I/O pattern. Accepted values are:
.RS
.RS
.TP
.B read
Sequential reads.
.TP
.B write
Sequential writes.
.TP
.B trim
Sequential trims (Linux block devices and SCSI character devices only).
.TP
.B randread
Random reads.
.TP
.B randwrite
Random writes.
.TP
.B randtrim
Random trims (Linux block devices and SCSI character devices only).
.TP
.B rw,readwrite
Sequential mixed reads and writes.
.TP
.B randrw
Random mixed reads and writes.
.TP
.B trimwrite
Sequential trim+write sequences. Blocks will be trimmed first,
then the same blocks will be written to. So if `io_size=64K' is specified,
Fio will trim a total of 64K bytes and also write 64K bytes on the same
trimmed blocks. This behaviour will be consistent with `number_ios' or
other Fio options limiting the total bytes or number of I/O's.
.TP
.B randtrimwrite
Like
.B trimwrite ,
but uses random offsets rather than sequential writes.
.RE
.P
Fio defaults to read if the option is not specified. For the mixed I/O
types, the default is to split them 50/50. For certain types of I/O the
result may still be skewed a bit, since the speed may be different.
.P
It is possible to specify the number of I/Os to do before getting a new
offset by appending `:<nr>' to the end of the string given. For a
random read, it would look like `rw=randread:8' for passing in an offset
modifier with a value of 8. If the suffix is used with a sequential I/O
pattern, then the `<nr>' value specified will be added to the generated
offset for each I/O turning sequential I/O into sequential I/O with holes.
For instance, using `rw=write:4k' will skip 4k for every write. Also see
the \fBrw_sequencer\fR option.
.RE
.TP
.BI rw_sequencer \fR=\fPstr
If an offset modifier is given by appending a number to the `rw=\fIstr\fR'
line, then this option controls how that number modifies the I/O offset
being generated. Accepted values are:
.RS
.RS
.TP
.B sequential
Generate sequential offset.
.TP
.B identical
Generate the same offset.
.RE
.P
\fBsequential\fR is only useful for random I/O, where fio would normally
generate a new random offset for every I/O. If you append e.g. 8 to randread,
i.e. `rw=randread:8' you would get a new random offset for every 8 I/Os. The
result would be a sequence of 8 sequential offsets with a random starting
point. However this behavior may change if a sequential I/O reaches end of the
file. As sequential I/O is already sequential, setting \fBsequential\fR for
that would not result in any difference. \fBidentical\fR behaves in a similar
fashion, except it sends the same offset 8 number of times before generating a
new offset.
.P
.P
Example #1:
.RS
.P
.PD 0
rw=randread:8
.P
rw_sequencer=sequential
.P
bs=4k
.PD
.RE
.P
The generated sequence of offsets will look like this:
4k, 8k, 12k, 16k, 20k, 24k, 28k, 32k, 92k, 96k, 100k, 104k, 108k, 112k, 116k,
120k, 48k, 52k ...
.P
.P
Example #2:
.RS
.P