.. option:: numjobs=int
- Create the specified number of clones of this job. May be used to setup a
+ 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
:option:`group_reporting` in conjunction with :option:`new_group`.
Fio normally makes up a `filename` based on the job name, thread number, and
file number. If you want to share files between threads in a job or several
- jobs, specify a `filename` 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 :file:`/dev/sda` and
- :file:`/dev/sdb` as the two working files, you would use
- ``filename=/dev/sda:/dev/sdb``.
+ jobs with fixed file paths, specify a `filename` 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
+ :file:`/dev/sda` and :file:`/dev/sdb` as the two working files, you would use
+ ``filename=/dev/sda:/dev/sdb``. This also means that whenever this option is
+ specified, :option:`nrfiles` is ignored. The size of regular files specified
+ by this option will be :option:`size` divided by number of files unless
+ explicit size is specified by :option:`filesize`.
+
On Windows, disk devices are accessed as :file:`\\\\.\\PhysicalDrive0` for
the first device, :file:`\\\\.\\PhysicalDrive1` for the second etc.
Note: Windows and FreeBSD prevent write access to areas
.. option:: nrfiles=int
- Number of files to use for this job. Defaults to 1.
+ Number of files to use for this job. Defaults to 1. The size of files
+ will be :option:`size` divided by this unless explicit size is specified by
+ :option:`filesize`. Files are created for each thread separately, and each
+ file will have a file number within its name by default, as explained in
+ :option:`filename` section.
+
.. option:: openfiles=int
.. option:: size=int
- The total size of file I/O for this job. Fio will run until this many bytes
- has been transferred, unless runtime is limited by other options (such as
- :option:`runtime`, for instance, or increased/decreased by
- :option:`io_size`). Unless specific :option:`nrfiles` and :option:`filesize`
- options are given, fio will divide this size between the available files
- specified by the job. If not set, fio will use the full size of the given
+ The total size of file I/O for each thread of this job. Fio will run until
+ this many bytes has been transferred, unless runtime is limited by other options
+ (such as :option:`runtime`, for instance, or increased/decreased by :option:`io_size`).
+ Fio will divide this size between the available files determined by options
+ such as :option:`nrfiles`, :option:`filename`, unless :option:`filesize` is
+ specified by the job. If the result of division happens to be 0, the size is
+ set to the physical size of the given files or devices.
+ If this option is not specified, 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.
Individual file sizes. May be a range, in which case fio will select sizes
for files at random within the given range and limited to :option:`size` in
total (if that is given). If not given, each created file is the same size.
+ This option overrides :option:`size` in terms of file size, which means
+ this value is used as a fixed size or possible range of each file.
.. option:: file_append=bool
.. option:: thread
Fio defaults to forking jobs, however if this option is given, fio will use
- :manpage:`pthread_create(3)` to create threads instead.
+ POSIX Threads function :manpage:`pthread_create(3)` to create threads instead
+ of forking processes.
.. option:: wait_for=str
}
#endif /* CONFIG_POSIX_FALLOCATE */
+ /*
+ * If our jobs don't require regular files initially, we're done.
+ */
if (!new_layout)
goto done;
return 1; /* avoid offset extends end error message */
}
+ /*
+ * Leave ->real_file_size with 0 since it could be expectation
+ * of initial setup for regular files.
+ */
if (ret)
return ret;
return 0;
}
+/*
+ * This function i.e. get_file_size() is the default .get_file_size
+ * implementation of majority of I/O engines.
+ */
int generic_get_file_size(struct thread_data *td, struct fio_file *f)
{
return get_file_size(td, f);
clear_error(td);
}
+ /*
+ * There are corner cases where we end up with -1 for
+ * ->real_file_size due to unsupported file type, etc.
+ * We then just set to size option value divided by number
+ * of files, similar to the way file ->io_size is set.
+ * stat(2) failure doesn't set ->real_file_size to -1.
+ */
if (f->real_file_size == -1ULL && td->o.size)
f->real_file_size = td->o.size / td->o.nr_files;
}
goto done;
/*
- * if ioengine defines a setup() method, it's responsible for
+ * Find out physical size of files or devices for this thread,
+ * before we determine I/O size and range of our targets.
+ * If ioengine defines a setup() method, it's responsible for
* opening the files and setting f->real_file_size to indicate
* the valid range for that file.
*/
/*
* Calculate per-file size and potential extra size for the
- * first files, if needed.
+ * first files, if needed (i.e. if we don't have a fixed size).
*/
if (!o->file_size_low && o->nr_files) {
uint64_t all_fs;
for_each_file(td, f, i) {
f->file_offset = get_start_offset(td, f);
+ /*
+ * Update ->io_size depending on options specified.
+ * ->file_size_low being 0 means filesize option isn't set.
+ * Non zero ->file_size_low equals ->file_size_high means
+ * filesize option is set in a fixed size format.
+ * Non zero ->file_size_low not equals ->file_size_high means
+ * filesize option is set in a range format.
+ */
if (!o->file_size_low) {
/*
- * no file size range given, file size is equal to
+ * no file size or range given, file size is equal to
* total size divided by number of files. If that is
* zero, set it to the real file size. If the size
* doesn't divide nicely with the min blocksize,
}
/*
- * See if we need to extend some files
+ * See if we need to extend some files, typically needed when our
+ * target regular files don't exist yet, but our jobs require them
+ * initially due to read I/Os.
*/
if (need_extend) {
temp_stall_ts = 1;