man page: fix bad case for 'pre-reading file' state

[fio.git] / fio.1

diff --git a/fio.1 b/fio.1
index b943db2289d66c87ced5bd3b7112cf9b580db8ab..1f9fffcf9bf8bfcc97d3a828cf7ddab808523323 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -113,6 +113,8 @@ 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.
 .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.
 .TP
 .BI \-\-server \fR=\fPargs
 Start a backend server, with \fIargs\fR specifying what to listen to.


@@ -576,6 +578,12 @@ 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.
 `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
 .RE
 .TP
 .BI unique_filename \fR=\fPbool


@@ -905,13 +913,19 @@ should be associated with them.
 .TP
 .BI offset \fR=\fPint
 Start I/O at the provided offset in the file, given as either a fixed size in
 .TP
 .BI offset \fR=\fPint
 Start I/O at the provided offset in the file, given as either a fixed size in

-bytes or a percentage. If a percentage is given, the next \fBblockalign\fR\-ed
-offset will be used. Data before the given offset will not be touched. This
+bytes or a percentage. If a percentage is given, the generated offset will be
+aligned to the minimum \fBblocksize\fR or to the value of \fBoffset_align\fR if
+provided. Data before the given offset will not be touched. This

 effectively caps the file size at `real_size \- offset'. Can be combined with
 \fBsize\fR to constrain the start and end range of the I/O workload.
 A percentage can be specified by a number between 1 and 100 followed by '%',
 for example, `offset=20%' to specify 20%.
 .TP
 effectively caps the file size at `real_size \- offset'. Can be combined with
 \fBsize\fR to constrain the start and end range of the I/O workload.
 A percentage can be specified by a number between 1 and 100 followed by '%',
 for example, `offset=20%' to specify 20%.
 .TP

+.BI offset_align \fR=\fPint
+If set to non-zero value, the byte offset generated by a percentage \fBoffset\fR
+is aligned upwards to this value. Defaults to 0 meaning that a percentage
+offset is aligned to the minimum block size.
+.TP

 .BI offset_increment \fR=\fPint
 If this is provided, then the real offset becomes `\fBoffset\fR + \fBoffset_increment\fR
 * thread_number', where the thread number is a counter that starts at 0 and
 .BI offset_increment \fR=\fPint
 If this is provided, then the real offset becomes `\fBoffset\fR + \fBoffset_increment\fR
 * thread_number', where the thread number is a counter that starts at 0 and


@@ -1228,8 +1242,8 @@ WRITEs) that compresses to the specified level. Fio does this by providing a
 mix of random data and a fixed pattern. The fixed pattern is either zeros,
 or the pattern specified by \fBbuffer_pattern\fR. If the pattern option
 is used, it might skew the compression ratio slightly. Note that this is per
 mix of random data and a fixed pattern. The fixed pattern is either zeros,
 or the pattern specified by \fBbuffer_pattern\fR. If the pattern option
 is used, it might skew the compression ratio slightly. Note that this is per

-block size unit, for file/disk wide compression level that matches this
-setting, you'll also want to set \fBrefill_buffers\fR.
+block size unit, see \fBbuffer_compress_chunk\fR for setting a finer granularity
+of compressible regions.

 .TP
 .BI buffer_compress_chunk \fR=\fPint
 See \fBbuffer_compress_percentage\fR. This setting allows fio to manage
 .TP
 .BI buffer_compress_chunk \fR=\fPint
 See \fBbuffer_compress_percentage\fR. This setting allows fio to manage


@@ -1237,7 +1251,8 @@ how big the ranges of random data and zeroed data is. Without this set, fio
 will provide \fBbuffer_compress_percentage\fR of blocksize random data,
 followed by the remaining zeroed. With this set to some chunk size smaller
 than the block size, fio can alternate random and zeroed data throughout the
 will provide \fBbuffer_compress_percentage\fR of blocksize random data,
 followed by the remaining zeroed. With this set to some chunk size smaller
 than the block size, fio can alternate random and zeroed data throughout the

-I/O buffer.
+I/O buffer. This is particularly useful when bigger block sizes are used
+for a job. Defaults to 512.

 .TP
 .BI buffer_pattern \fR=\fPstr
 If set, fio will fill the I/O buffers with this pattern or with the contents
 .TP
 .BI buffer_pattern \fR=\fPstr
 If set, fio will fill the I/O buffers with this pattern or with the contents


@@ -1577,6 +1592,11 @@ the engine filename, e.g. `ioengine=external:/tmp/foo.o' to load
 ioengine `foo.o' in `/tmp'. The path can be either
 absolute or relative. See `engines/skeleton_external.c' in the fio source for
 details of writing an external I/O engine.
 ioengine `foo.o' in `/tmp'. The path can be either
 absolute or relative. See `engines/skeleton_external.c' in the fio source for
 details of writing an external I/O engine.

+.TP
+.B filecreate
+Simply create the files and do no I/O to them.  You still need to set
+\fBfilesize\fR so that all the accounting still occurs, but no actual I/O will be
+done other than creating the file.

 .SS "I/O engine specific parameters"
 In addition, there are some parameters which are only valid when a specific
 \fBioengine\fR is in use. These are used identically to normal parameters,
 .SS "I/O engine specific parameters"
 In addition, there are some parameters which are only valid when a specific
 \fBioengine\fR is in use. These are used identically to normal parameters,


@@ -2401,48 +2421,48 @@ the final stat output.
 .TP
 .BI write_bw_log \fR=\fPstr
 If given, write a bandwidth log for this job. Can be used to store data of
 .TP
 .BI write_bw_log \fR=\fPstr
 If given, write a bandwidth log for this job. Can be used to store data of

-the bandwidth of the jobs in their lifetime. The included
-\fBfio_generate_plots\fR script uses gnuplot to turn these
-text files into nice graphs. See \fBwrite_lat_log\fR for behavior of
-given filename. For this option, the postfix is `_bw.x.log', where `x'
-is the index of the job (1..N, where N is the number of jobs). If
-\fBper_job_logs\fR is false, then the filename will not include the job
-index. See \fBLOG FILE FORMATS\fR section.
-.TP
-.BI write_lat_log \fR=\fPstr
-Same as \fBwrite_bw_log\fR, except that this option stores I/O
-submission, completion, and total latencies instead. If no filename is given
-with this option, the default filename of `jobname_type.log' is
-used. Even if the filename is given, fio will still append the type of
-log. So if one specifies:
+the bandwidth of the jobs in their lifetime.

 .RS
 .RS

+.P
+If no str argument is given, the default filename of
+`jobname_type.x.log' is used. Even when the argument is given, fio
+will still append the type of log. So if one specifies:

 .RS
 .P
 .RS
 .P

-write_lat_log=foo
+write_bw_log=foo

 .RE
 .P
 .RE
 .P

-The actual log names will be `foo_slat.x.log', `foo_clat.x.log',
-and `foo_lat.x.log', where `x' is the index of the job (1..N, where N
-is the number of jobs). This helps \fBfio_generate_plots\fR find the
-logs automatically. If \fBper_job_logs\fR is false, then the filename
-will not include the job index. See \fBLOG FILE FORMATS\fR section.
+The actual log name will be `foo_bw.x.log' where `x' is the index
+of the job (1..N, where N is the number of jobs). If
+\fBper_job_logs\fR is false, then the filename will not include the
+`.x` job index.
+.P
+The included \fBfio_generate_plots\fR script uses gnuplot to turn these
+text files into nice graphs. See the \fBLOG FILE FORMATS\fR section for how data is
+structured within the file.

 .RE
 .TP
 .RE
 .TP

+.BI write_lat_log \fR=\fPstr
+Same as \fBwrite_bw_log\fR, except this option creates I/O
+submission (e.g., `name_slat.x.log'), completion (e.g.,
+`name_clat.x.log'), and total (e.g., `name_lat.x.log') latency
+files instead. See \fBwrite_bw_log\fR for details about the
+filename format and the \fBLOG FILE FORMATS\fR section for how data is structured
+within the files.
+.TP

 .BI write_hist_log \fR=\fPstr
 .BI write_hist_log \fR=\fPstr

-Same as \fBwrite_lat_log\fR, but writes I/O completion latency
-histograms. If no filename is given with this option, the default filename
-of `jobname_clat_hist.x.log' is used, where `x' is the index of the
-job (1..N, where N is the number of jobs). Even if the filename is given,
-fio will still append the type of log. If \fBper_job_logs\fR is false,
-then the filename will not include the job index. See \fBLOG FILE FORMATS\fR section.
+Same as \fBwrite_bw_log\fR but writes an I/O completion latency
+histogram file (e.g., `name_hist.x.log') instead. Note that this
+file will be empty unless \fBlog_hist_msec\fR has also been set.
+See \fBwrite_bw_log\fR for details about the filename format and
+the \fBLOG FILE FORMATS\fR section for how data is structured
+within the file.

 .TP
 .BI write_iops_log \fR=\fPstr
 .TP
 .BI write_iops_log \fR=\fPstr

-Same as \fBwrite_bw_log\fR, but writes IOPS. If no filename is given
-with this option, the default filename of `jobname_type.x.log' is
-used, where `x' is the index of the job (1..N, where N is the number of
-jobs). Even if the filename is given, fio will still append the type of
-log. If \fBper_job_logs\fR is false, then the filename will not include
-the job index. See \fBLOG FILE FORMATS\fR section.
+Same as \fBwrite_bw_log\fR, but writes an IOPS file (e.g.
+`name_iops.x.log') instead. See \fBwrite_bw_log\fR for
+details about the filename format and the \fBLOG FILE FORMATS\fR section for how data
+is structured within the file.

 .TP
 .BI log_avg_msec \fR=\fPint
 By default, fio will log an entry in the iops, latency, or bw log for every
 .TP
 .BI log_avg_msec \fR=\fPint
 By default, fio will log an entry in the iops, latency, or bw log for every


@@ -2458,8 +2478,8 @@ histograms. Computing latency percentiles from averages of intervals using
 \fBlog_avg_msec\fR is inaccurate. Setting this option makes fio log
 histogram entries over the specified period of time, reducing log sizes for
 high IOPS devices while retaining percentile accuracy. See
 \fBlog_avg_msec\fR is inaccurate. Setting this option makes fio log
 histogram entries over the specified period of time, reducing log sizes for
 high IOPS devices while retaining percentile accuracy. See

-\fBlog_hist_coarseness\fR as well. Defaults to 0, meaning histogram
-logging is disabled.
+\fBlog_hist_coarseness\fR and \fBwrite_hist_log\fR as well.
+Defaults to 0, meaning histogram logging is disabled.

 .TP
 .BI log_hist_coarseness \fR=\fPint
 Integer ranging from 0 to 6, defining the coarseness of the resolution of
 .TP
 .BI log_hist_coarseness \fR=\fPint
 Integer ranging from 0 to 6, defining the coarseness of the resolution of


@@ -2549,7 +2569,7 @@ Enable the reporting of percentiles of completion latencies. This option is
 mutually exclusive with \fBlat_percentiles\fR.
 .TP
 .BI lat_percentiles \fR=\fPbool
 mutually exclusive with \fBlat_percentiles\fR.
 .TP
 .BI lat_percentiles \fR=\fPbool

-Enable the reporting of percentiles of IO latencies. This is similar to
+Enable the reporting of percentiles of I/O latencies. This is similar to

 \fBclat_percentiles\fR, except that this includes the submission latency.
 This option is mutually exclusive with \fBclat_percentiles\fR.
 .TP
 \fBclat_percentiles\fR, except that this includes the submission latency.
 This option is mutually exclusive with \fBclat_percentiles\fR.
 .TP


@@ -2710,7 +2730,7 @@ Thread created.
 .B I
 Thread initialized, waiting or generating necessary data.
 .TP
 .B I
 Thread initialized, waiting or generating necessary data.
 .TP

-.B P
+.B p

 Thread running pre\-reading file(s).
 .TP
 .B /
 Thread running pre\-reading file(s).
 .TP
 .B /


@@ -2897,7 +2917,7 @@ The number of \fBread/write/trim\fR requests issued, and how many of them were
 short or dropped.
 .TP
 .B IO latency
 short or dropped.
 .TP
 .B IO latency

-These values are for \fBlatency-target\fR and related options. When
+These values are for \fBlatency_target\fR and related options. When

 these options are engaged, this section describes the I/O depth required
 to meet the specified latency target.
 .RE
 these options are engaged, this section describes the I/O depth required
 to meet the specified latency target.
 .RE