X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=1f9fffcf9bf8bfcc97d3a828cf7ddab808523323;hp=b943db2289d66c87ced5bd3b7112cf9b580db8ab;hb=522c29f69a31542170d94611e05e1780e4c08dbd;hpb=9acb08a9957b1111a06fbca6af113fa0c98dbd7c diff --git a/fio.1 b/fio.1 index b943db22..1f9fffcf 100644 --- 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. +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. @@ -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. +.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 @@ -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 -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 +.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 @@ -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 -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 @@ -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 -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 @@ -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. +.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, @@ -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 -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 +.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 -write_lat_log=foo +write_bw_log=foo .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 +.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 -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 -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 @@ -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_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 @@ -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 -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 @@ -2710,7 +2730,7 @@ Thread created. .B I Thread initialized, waiting or generating necessary data. .TP -.B P +.B p 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 -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