From 02dd2689885c6d64d9d01a92e67d40f73c0afc72 Mon Sep 17 00:00:00 2001 From: Sitsofe Wheeler Date: Thu, 22 Jun 2017 07:22:38 +0100 Subject: [PATCH] HOWTO: update directory and filename option descriptions - Minor grammar changes. - Explictly note that '\' and ':' need escaping. - Turn reference to filename_format into link. - Split escaping into two paragraphs and add another Windows example. - Make it clearer '-' can be a filename - Markup stdin/stdout. Signed-off-by: Sitsofe Wheeler --- HOWTO | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/HOWTO b/HOWTO index efafc88f..e0c869fc 100644 --- a/HOWTO +++ b/HOWTO @@ -725,36 +725,41 @@ Target file/device Prefix filenames with this directory. Used to place files in a different location than :file:`./`. You can specify a number of directories by separating the names with a ':' character. These directories will be - assigned equally distributed to job clones creates with :option:`numjobs` as + assigned equally distributed to job clones created by :option:`numjobs` as long as they are using generated filenames. If specific `filename(s)` are set fio will use the first listed directory, and thereby matching the `filename` semantic which generates a file each clone if not specified, but let all clones use the same if set. - See the :option:`filename` option for escaping certain characters. + See the :option:`filename` option for information on how to escape "``:``" and + "``\``" characters within the directory path itself. .. option:: filename=str 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 + file number (see :option:`filename_format`). If you want to share files + between threads in a job or several 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 + by this option will be :option:`size` divided by number of files unless an explicit size is specified by :option:`filesize`. + Each colon and backslash in the wanted path must be escaped with a ``\`` + character. For instance, if the path is :file:`/dev/dsk/foo@3,0:c` then you + would use ``filename=/dev/dsk/foo@3,0\:c`` and if the path is + :file:`F:\\filename` then you would use ``filename=F\:\\filename``. + 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 - 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 :file:`/dev/dsk/foo@3,0:c`, - then you would use ``filename="/dev/dsk/foo@3,0\:c"``. The - :file:`-` is a reserved name, meaning stdin or stdout. Which of the two - depends on the read/write direction set. + of the disk containing in-use data (e.g. filesystems). + + The filename "`-`" is a reserved name, meaning *stdin* or *stdout*. Which + of the two depends on the read/write direction set. .. option:: filename_format=str -- 2.25.1