Add option for io_limit

[fio.git] / fio.1

diff --git a/fio.1 b/fio.1
index 863b0e093b38add8f5c86997e62f8b066f07b1bf..eeb036e486957e0c9dbfe8d4c3b27a1e8370cfed 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -166,7 +166,9 @@ character. These directories will be assigned equally distributed to job clones
 creates with \fInumjobs\fR as long as they are using generated filenames.
 If specific \fIfilename(s)\fR are set fio will use the first listed directory,
 and thereby matching the  \fIfilename\fR semantic which generates a file each
-clone if not specified, but let all clones use the same if set.
+clone if not specified, but let all clones use the same if set. See
+\fIfilename\fR for considerations regarding escaping certain characters on
+some platforms.
 .TP
 .BI filename \fR=\fPstr
 .B fio
@@ -176,7 +178,12 @@ specify a \fIfilename\fR for each of them to override the default.
 If the I/O engine is file-based, you can specify
 a number of files by separating the names with a `:' character. `\-' is a
 reserved name, meaning stdin or stdout, depending on the read/write direction
-set.
+set. 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). If the wanted filename does need to include a colon, then
+escape that with a '\' character. For instance, if the filename is
+"/dev/dsk/foo@3,0:c", then you would use filename="/dev/dsk/foo@3,0\:c".
 .TP
 .BI filename_format \fR=\fPstr
 If sharing multiple files between jobs, it is usually necessary to have
@@ -362,8 +369,16 @@ Unless \fBnrfiles\fR and \fBfilesize\fR options are given, this amount will be
 divided between the available files for the job. If not set, fio will use the
 full size of the given files or devices. If the files do not exist, size
 must be given. It is also possible to give size as a percentage between 1 and
-100. If size=20% is given, fio will use 20% of the full size of the given files
-or devices.
+100. If size=20% is given, fio will use 20% of the full size of the given
+files or devices.
+.TP
+.BI io_limit \fR=\fPint
+Normally fio operates within the region set by \fBsize\fR, which means that
+the \fBsize\fR option sets both the region and size of IO to be performed.
+Sometimes that is not what you want. With this option, it is possible to
+define just the amount of IO that fio should do. For instance, if \fBsize\fR
+is set to 20G and \fBio_limit\fR is set to 5G, fio will perform IO within
+the first 20G but exit when 5G have been done.
 .TP
 .BI fill_device \fR=\fPbool "\fR,\fB fill_fs" \fR=\fPbool
 Sets size to something really large and waits for ENOSPC (no space left on
@@ -379,6 +394,12 @@ for files at random within the given range, limited to \fBsize\fR in total (if
 that is given). If \fBfilesize\fR is not specified, each created file is the
 same size.
 .TP
+.BI file_append \fR=\fPbool
+Perform IO after the end of the file. Normally fio will operate within the
+size of a file. If this option is set, then fio will append to the file
+instead. This has identical behavior to setting \fRoffset\fP to the size
+of a file. This option is ignored on non-regular files.
+.TP
 .BI blocksize \fR=\fPint[,int] "\fR,\fB bs" \fR=\fPint[,int]
 Block size for I/O units.  Default: 4k.  Values for reads, writes, and trims
 can be specified separately in the format \fIread\fR,\fIwrite\fR,\fItrim\fR
@@ -423,6 +444,8 @@ blocksize setting.
 .TP
 .B zero_buffers
 Initialise buffers with all zeros. Default: fill buffers with random data.
+The resulting IO buffers will not be completely zeroed, unless
+\fPscramble_buffers\fR is also turned off.
 .TP
 .B refill_buffers
 If this option is given, fio will refill the IO buffers on every submit. The
@@ -847,8 +870,9 @@ Each job will get a unique CPU from the CPU set.
 .RE
 .P
 \fBshared\fR is the default behaviour, if the option isn't specified. If
-\fBsplit\fR is specified, then fio will error out if there are more jobs
-defined than CPUs given in the set.
+\fBsplit\fR is specified, then fio will assign one cpu per job. If not enough
+CPUs are given for the jobs listed, then fio will roundrobin the CPUs in
+the set.
 .RE
 .P
 .TP
@@ -1210,14 +1234,6 @@ Output is redirected in a file called \fBjobname.postrun.txt\fR
 .BI ioscheduler \fR=\fPstr
 Attempt to switch the device hosting the file to the specified I/O scheduler.
 .TP
-.BI cpuload \fR=\fPint
-If the job is a CPU cycle-eater, attempt to use the specified percentage of
-CPU cycles.
-.TP
-.BI cpuchunks \fR=\fPint
-If the job is a CPU cycle-eater, split the load into cycles of the
-given time in milliseconds.
-.TP
 .BI disk_util \fR=\fPbool
 Generate disk utilization statistics if the platform supports it. Default: true.
 .TP
@@ -1359,6 +1375,9 @@ Attempt to use the specified percentage of CPU cycles.
 .BI (cpu)cpuchunks \fR=\fPint
 Split the load into cycles of the given time. In microseconds.
 .TP
+.BI (cpu)exit_on_io_done \fR=\fPbool
+Detect when IO threads are done, then exit.
+.TP
 .BI (libaio)userspace_reap
 Normally, with the libaio engine in use, fio will use
 the io_getevents system call to reap newly returned events.