From: "Daniel W. S. Almeida" <[email protected]>
Converts vfat.txt to the reStructuredText format, improving presentation
without changing the underlying content.
Signed-off-by: Daniel W. S. Almeida <[email protected]>
---
Documentation/filesystems/index.rst | 1 +
Documentation/filesystems/vfat.rst | 389 ++++++++++++++++++++++++++++
Documentation/filesystems/vfat.txt | 347 -------------------------
3 files changed, 390 insertions(+), 347 deletions(-)
create mode 100644 Documentation/filesystems/vfat.rst
delete mode 100644 Documentation/filesystems/vfat.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 2c3a9f761205..aaffaa9042c3 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -47,3 +47,4 @@ Documentation for filesystem implementations.
:maxdepth: 2
virtiofs
+ vfat
diff --git a/Documentation/filesystems/vfat.rst b/Documentation/filesystems/vfat.rst
new file mode 100644
index 000000000000..e24e69a2817d
--- /dev/null
+++ b/Documentation/filesystems/vfat.rst
@@ -0,0 +1,389 @@
+====
+VFAT
+====
+
+USING VFAT
+==========
+
+To use the vfat filesystem, use the filesystem type 'vfat'. i.e.::
+
+ mount -t vfat /dev/fd0 /mnt
+
+
+No special partition formatter is required.
+``mkdosfs`` will work fine if you want to format from within Linux.
+
+VFAT MOUNT OPTIONS
+==================
+
+**uid=###**
+ Set the owner of all files on this filesystem.
+ The default is the *uid* of current process.
+
+**gid=###**
+ Set the group of all files on this filesystem.
+ The default is the *gid* of current process.
+
+**umask=###**
+ The permission mask (for files and directories, see *umask(1)*).
+ The default is the *umask* of current process.
+
+**dmask=###**
+ The permission mask for the directory.
+ The default is the *umask* of current process.
+
+**fmask=###**
+ The permission mask for files.
+ The default is the *umask* of current process.
+
+**allow_utime=###**
+ This option controls the permission check of mtime/atime.
+
+ **-20**: If current process is in group of file's group ID, you can change timestamp.
+
+ **-2**: Other users can change timestamp.
+
+ The default is set from ``dmask`` option. If the directory is
+ writable, *utime(2)* is also allowed. i.e. ``~dmask & 022``.
+
+ Normally ``utime(2)`` checks current process is owner of
+ the file, or it has ``CAP_FOWNER`` capability. But FAT
+ filesystem doesn't have uid/gid on disk, so normal
+ check is too unflexible. With this option you can
+ relax it.
+
+**codepage=###**
+ Sets the codepage number for converting to shortname
+ characters on FAT filesystem.
+ By default, ``FAT_DEFAULT_CODEPAGE`` setting is used.
+
+**iocharset=<name>**
+ Character set to use for converting between the
+ encoding is used for user visible filename and 16 bit
+ Unicode characters. Long filenames are stored on disk
+ in Unicode format, but Unix for the most part doesn't
+ know how to deal with Unicode.
+ By default, ``FAT_DEFAULT_IOCHARSET`` setting is used.
+
+ There is also an option of doing UTF-8 translations
+ with the utf8 option.
+
+.. note:: ``iocharset=utf8`` is not recommended. If unsure, you should consider the utf8 option instead.
+
+**utf8=<bool>**
+ UTF-8 is the filesystem safe version of Unicode that
+ is used by the console. It can be enabled or disabled
+ for the filesystem with this option.
+ If 'uni_xlate' gets set, UTF-8 gets disabled.
+ By default, ``FAT_DEFAULT_UTF8`` setting is used.
+
+**uni_xlate=<bool>**
+ Translate unhandled Unicode characters to special
+ escaped sequences. This would let you backup and
+ restore filenames that are created with any Unicode
+ characters. Until Linux supports Unicode for real,
+ this gives you an alternative. Without this option,
+ a '?' is used when no translation is possible. The
+ escape character is ':' because it is otherwise
+ illegal on the vfat filesystem. The escape sequence
+ that gets used is ':' and the four digits of hexadecimal
+ unicode.
+
+**nonumtail=<bool>**
+ When creating 8.3 aliases, normally the alias will
+ end in '~1' or tilde followed by some number. If this
+ option is set, then if the filename is
+ "longfilename.txt" and "longfile.txt" does not
+ currently exist in the directory, ``longfile.txt`` will
+ be the short alias instead of ``longfi~1.txt``.
+
+**usefree**
+ Use the "free clusters" value stored on ``FSINFO``. It'll
+ be used to determine number of free clusters without
+ scanning disk. But it's not used by default, because
+ recent Windows don't update it correctly in some
+ case. If you are sure the "free clusters" on ``FSINFO`` is
+ correct, by this option you can avoid scanning disk.
+
+**quiet**
+ Stops printing certain warning messages.
+
+**check=s|r|n**
+ Case sensitivity checking setting.
+
+ **s**: strict, case sensitive
+
+ **r**: relaxed, case insensitive
+
+ **n**: normal, default setting, currently case insensitive
+
+**nocase**
+ This was deprecated for vfat. Use ``shortname=win95`` instead.
+
+**shortname=lower|win95|winnt|mixed**
+ Shortname display/create setting.
+
+ **lower**: convert to lowercase for display,
+ emulate the Windows 95 rule for create.
+
+ **win95**: emulate the Windows 95 rule for display/create.
+
+ **winnt**: emulate the Windows NT rule for display/create.
+
+ **mixed**: emulate the Windows NT rule for display,
+ emulate the Windows 95 rule for create.
+
+ Default setting is `mixed`.
+
+**tz=UTC**
+ Interpret timestamps as UTC rather than local time.
+ This option disables the conversion of timestamps
+ between local time (as used by Windows on FAT) and UTC
+ (which Linux uses internally). This is particularly
+ useful when mounting devices (like digital cameras)
+ that are set to UTC in order to avoid the pitfalls of
+ local time.
+
+**time_offset=minutes**
+ Set offset for conversion of timestamps from local time
+ used by FAT to UTC. I.e. <minutes> minutes will be subtracted
+ from each timestamp to convert it to UTC used internally by
+ Linux. This is useful when time zone set in ``sys_tz`` is
+ not the time zone used by the filesystem. Note that this
+ option still does not provide correct time stamps in all
+ cases in presence of DST - time stamps in a different DST
+ setting will be off by one hour.
+
+**showexec**
+ If set, the execute permission bits of the file will be
+ allowed only if the extension part of the name is ``.EXE``,
+ ``.COM``, or ``.BAT``. Not set by default.
+
+**debug**
+ Can be set, but unused by the current implementation.
+
+**sys_immutable**
+ If set, ATTR_SYS attribute on FAT is handled as
+ ``IMMUTABLE`` flag on Linux. Not set by default.
+
+**flush**
+ If set, the filesystem will try to flush to disk more
+ early than normal. Not set by default.
+
+**rodir**
+ FAT has the ``ATTR_RO`` (read-only) attribute. On Windows,
+ the ``ATTR_RO`` of the directory will just be ignored,
+ and is used only by applications as a flag (e.g. it's set
+ for the customized folder).
+
+ If you want to use ``ATTR_RO`` as read-only flag even for
+ the directory, set this option.
+
+**errors=panic|continue|remount-ro**
+ specify FAT behavior on critical errors: panic, continue
+ without doing anything or remount the partition in
+ read-only mode (default behavior).
+
+**discard**
+ If set, issues discard/TRIM commands to the block
+ device when blocks are freed. This is useful for SSD devices
+ and sparse/thinly-provisoned LUNs.
+
+**nfs=stale_rw|nostale_ro**
+ Enable this only if you want to export the FAT filesystem
+ over NFS.
+
+ **stale_rw**: This option maintains an index (cache) of directory
+ *inodes* by *i_logstart* which is used by the nfs-related code to
+ improve look-ups. Full file operations (read/write) over *NFS* is
+ supported but with cache eviction at *NFS* server, this could
+ result in ``ESTALE`` issues.
+
+ **nostale_ro**: This option bases the *inode* number and filehandle
+ on the on-disk location of a file in the MS-DOS directory entry.
+ This ensures that ``ESTALE`` will not be returned after a file is
+ evicted from the *inode* cache. However, it means that operations
+ such as rename, create and unlink could cause filehandles that
+ previously pointed at one file to point at a different file,
+ potentially causing data corruption. For this reason, this
+ option also mounts the filesystem readonly.
+
+ To maintain backward compatibility, ``'-o nfs'`` is also accepted,
+ defaulting to ``stale_rw``
+
+**dos1xfloppy <bool>: 0,1,yes,no,true,false**
+ If set, use a fallback default BIOS Parameter Block
+ configuration, determined by backing device size. These static
+ parameters match defaults assumed by DOS 1.x for 160 kiB,
+ 180 kiB, 320 kiB, and 360 kiB floppies and floppy images.
+
+
+
+LIMITATION
+==========
+The fallocated region of file is discarded at umount/evict time
+when using fallocate with FALLOC_FL_KEEP_SIZE.
+So, User should assume that fallocated region can be discarded at
+last close if there is memory pressure resulting in eviction of
+the inode from the memory. As a result, for any dependency on
+the fallocated region, user should make sure to recheck fallocate
+after reopening the file.
+
+TODO
+====
+Need to get rid of the raw scanning stuff. Instead, always use
+a get next directory entry approach. The only thing left that uses
+raw scanning is the directory renaming code.
+
+
+POSSIBLE PROBLEMS
+=================
+
+- vfat_valid_longname does not properly checked reserved names.
+- When a volume name is the same as a directory name in the root
+ directory of the filesystem, the directory name sometimes shows
+ up as an empty file.
+- autoconv option does not work correctly.
+
+BUG REPORTS
+===========
+If you have trouble with the *VFAT* filesystem, mail bug reports to
[email protected].
+
+Please specify the filename and the operation that gave you trouble.
+
+TEST SUITE
+==========
+If you plan to make any modifications to the vfat filesystem, please
+get the test suite that comes with the vfat distribution at
+
+`<http://web.archive.org/web/*/http://bmrc.berkeley.edu/people/chaffee/vfat.html>`_
+
+This tests quite a few parts of the vfat filesystem and additional
+tests for new features or untested features would be appreciated.
+
+NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM
+=============================================
+This documentation was provided by Galen C. Hunt [email protected] and lightly annotated by Gordon Chaffee.
+
+This document presents a very rough, technical overview of my
+knowledge of the extended FAT file system used in Windows NT 3.5 and
+Windows 95. I don't guarantee that any of the following is correct,
+but it appears to be so.
+
+The extended FAT file system is almost identical to the FAT
+file system used in DOS versions up to and including *6.223410239847*
+:-). The significant change has been the addition of long file names.
+These names support up to *255* characters including spaces and lower
+case characters as opposed to the traditional *8.3* short names.
+
+Here is the description of the traditional *FAT* entry in the current
+Windows 95 filesystem: ::
+
+ struct directory { // Short 8.3 names
+ unsigned char name[8]; // file name
+ unsigned char ext[3]; // file extension
+ unsigned char attr; // attribute byte
+ unsigned char lcase; // Case for base and extension
+ unsigned char ctime_ms; // Creation time, milliseconds
+ unsigned char ctime[2]; // Creation time
+ unsigned char cdate[2]; // Creation date
+ unsigned char adate[2]; // Last access date
+ unsigned char reserved[2]; // reserved values (ignored)
+ unsigned char time[2]; // time stamp
+ unsigned char date[2]; // date stamp
+ unsigned char start[2]; // starting cluster number
+ unsigned char size[4]; // size of the file
+ };
+
+
+The ``lcase`` field specifies if the base and/or the extension of an 8.3
+name should be capitalized. This field does not seem to be used by
+Windows 95 but it is used by Windows NT. The case of filenames is not
+completely compatible from Windows NT to Windows 95. It is not completely
+compatible in the reverse direction, however. Filenames that fit in
+the 8.3 namespace and are written on Windows NT to be lowercase will
+show up as uppercase on Windows 95.
+
+.. note:: Note that the ``start`` and ``size`` values are actually little
+ endian integer values. The descriptions of the fields in this
+ structure are public knowledge and can be found elsewhere.
+
+With the extended FAT system, Microsoft has inserted extra
+directory entries for any files with extended names. (Any name which
+legally fits within the old 8.3 encoding scheme does not have extra
+entries.) I call these extra entries slots. Basically, a slot is a
+specially formatted directory entry which holds up to 13 characters of
+a file's extended name. Think of slots as additional labeling for the
+directory entry of the file to which they correspond. Microsoft
+prefers to refer to the 8.3 entry for a file as its alias and the
+extended slot directory entries as the file name.
+
+The C structure for a slot directory entry follows: ::
+
+ struct slot { // Up to 13 characters of a long name
+ unsigned char id; // sequence number for slot
+ unsigned char name0_4[10]; // first 5 characters in name
+ unsigned char attr; // attribute byte
+ unsigned char reserved; // always 0
+ unsigned char alias_checksum; // checksum for 8.3 alias
+ unsigned char name5_10[12]; // 6 more characters in name
+ unsigned char start[2]; // starting cluster number
+ unsigned char name11_12[4]; // last 2 characters in name
+ };
+
+
+If the layout of the slots looks a little odd, it's only
+because of Microsoft's efforts to maintain compatibility with old
+software. The slots must be disguised to prevent old software from
+panicking. To this end, a number of measures are taken:
+
+ 1) The attribute byte for a slot directory entry is always set
+ to 0x0f. This corresponds to an old directory entry with
+ attributes of "hidden", "system", "read-only", and "volume
+ label". Most old software will ignore any directory
+ entries with the "volume label" bit set. Real volume label
+ entries don't have the other three bits set.
+
+ 2) The starting cluster is always set to 0, an impossible
+ value for a DOS file.
+
+Because the extended FAT system is backward compatible, it is
+possible for old software to modify directory entries. Measures must
+be taken to ensure the validity of slots. An extended FAT system can
+verify that a slot does in fact belong to an 8.3 directory entry by
+the following:
+
+ 1) Positioning. Slots for a file always immediately proceed
+ their corresponding 8.3 directory entry. In addition, each
+ slot has an id which marks its order in the extended file
+ name. Here is a very abbreviated view of an 8.3 directory
+ entry and its corresponding long name slots for the file
+ "My Big File.Extension which is long": ::
+
+ <proceeding files...>
+ <slot #3, id = 0x43, characters = "h is long">
+ <slot #2, id = 0x02, characters = "xtension whic">
+ <slot #1, id = 0x01, characters = "My Big File.E">
+ <directory entry, name = "MYBIGFIL.EXT">
+
+
+ .. note:: Note that the slots are stored from last to first. Slots
+ are numbered from 1 to N. The Nth slot is ``or'ed`` with ``0x40``
+ to mark it as the last one.
+
+ 2) Checksum. Each slot has an ``alias_checksum`` value. The
+ checksum is calculated from the 8.3 name using the
+ following algorithm: ::
+
+ for (sum = i = 0; i < 11; i++) {
+ sum = (((sum&1)<<7)|((sum&0xfe)>>1)) + name[i]
+ }
+
+
+ 3) If there is free space in the final slot, a Unicode ``NULL (0x0000)``
+ is stored after the final character. After that, all unused
+ characters in the final slot are set to Unicode ``0xFFFF``.
+
+Finally, note that the extended name is stored in Unicode. Each Unicode
+character takes either two or four bytes, UTF-16LE encoded.
diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt
deleted file mode 100644
index 91031298beb1..000000000000
--- a/Documentation/filesystems/vfat.txt
+++ /dev/null
@@ -1,347 +0,0 @@
-USING VFAT
-----------------------------------------------------------------------
-To use the vfat filesystem, use the filesystem type 'vfat'. i.e.
- mount -t vfat /dev/fd0 /mnt
-
-No special partition formatter is required. mkdosfs will work fine
-if you want to format from within Linux.
-
-VFAT MOUNT OPTIONS
-----------------------------------------------------------------------
-uid=### -- Set the owner of all files on this filesystem.
- The default is the uid of current process.
-
-gid=### -- Set the group of all files on this filesystem.
- The default is the gid of current process.
-
-umask=### -- The permission mask (for files and directories, see umask(1)).
- The default is the umask of current process.
-
-dmask=### -- The permission mask for the directory.
- The default is the umask of current process.
-
-fmask=### -- The permission mask for files.
- The default is the umask of current process.
-
-allow_utime=### -- This option controls the permission check of mtime/atime.
-
- 20 - If current process is in group of file's group ID,
- you can change timestamp.
- 2 - Other users can change timestamp.
-
- The default is set from `dmask' option. (If the directory is
- writable, utime(2) is also allowed. I.e. ~dmask & 022)
-
- Normally utime(2) checks current process is owner of
- the file, or it has CAP_FOWNER capability. But FAT
- filesystem doesn't have uid/gid on disk, so normal
- check is too unflexible. With this option you can
- relax it.
-
-codepage=### -- Sets the codepage number for converting to shortname
- characters on FAT filesystem.
- By default, FAT_DEFAULT_CODEPAGE setting is used.
-
-iocharset=<name> -- Character set to use for converting between the
- encoding is used for user visible filename and 16 bit
- Unicode characters. Long filenames are stored on disk
- in Unicode format, but Unix for the most part doesn't
- know how to deal with Unicode.
- By default, FAT_DEFAULT_IOCHARSET setting is used.
-
- There is also an option of doing UTF-8 translations
- with the utf8 option.
-
- NOTE: "iocharset=utf8" is not recommended. If unsure,
- you should consider the following option instead.
-
-utf8=<bool> -- UTF-8 is the filesystem safe version of Unicode that
- is used by the console. It can be enabled or disabled
- for the filesystem with this option.
- If 'uni_xlate' gets set, UTF-8 gets disabled.
- By default, FAT_DEFAULT_UTF8 setting is used.
-
-uni_xlate=<bool> -- Translate unhandled Unicode characters to special
- escaped sequences. This would let you backup and
- restore filenames that are created with any Unicode
- characters. Until Linux supports Unicode for real,
- this gives you an alternative. Without this option,
- a '?' is used when no translation is possible. The
- escape character is ':' because it is otherwise
- illegal on the vfat filesystem. The escape sequence
- that gets used is ':' and the four digits of hexadecimal
- unicode.
-
-nonumtail=<bool> -- When creating 8.3 aliases, normally the alias will
- end in '~1' or tilde followed by some number. If this
- option is set, then if the filename is
- "longfilename.txt" and "longfile.txt" does not
- currently exist in the directory, 'longfile.txt' will
- be the short alias instead of 'longfi~1.txt'.
-
-usefree -- Use the "free clusters" value stored on FSINFO. It'll
- be used to determine number of free clusters without
- scanning disk. But it's not used by default, because
- recent Windows don't update it correctly in some
- case. If you are sure the "free clusters" on FSINFO is
- correct, by this option you can avoid scanning disk.
-
-quiet -- Stops printing certain warning messages.
-
-check=s|r|n -- Case sensitivity checking setting.
- s: strict, case sensitive
- r: relaxed, case insensitive
- n: normal, default setting, currently case insensitive
-
-nocase -- This was deprecated for vfat. Use shortname=win95 instead.
-
-shortname=lower|win95|winnt|mixed
- -- Shortname display/create setting.
- lower: convert to lowercase for display,
- emulate the Windows 95 rule for create.
- win95: emulate the Windows 95 rule for display/create.
- winnt: emulate the Windows NT rule for display/create.
- mixed: emulate the Windows NT rule for display,
- emulate the Windows 95 rule for create.
- Default setting is `mixed'.
-
-tz=UTC -- Interpret timestamps as UTC rather than local time.
- This option disables the conversion of timestamps
- between local time (as used by Windows on FAT) and UTC
- (which Linux uses internally). This is particularly
- useful when mounting devices (like digital cameras)
- that are set to UTC in order to avoid the pitfalls of
- local time.
-time_offset=minutes
- -- Set offset for conversion of timestamps from local time
- used by FAT to UTC. I.e. <minutes> minutes will be subtracted
- from each timestamp to convert it to UTC used internally by
- Linux. This is useful when time zone set in sys_tz is
- not the time zone used by the filesystem. Note that this
- option still does not provide correct time stamps in all
- cases in presence of DST - time stamps in a different DST
- setting will be off by one hour.
-
-showexec -- If set, the execute permission bits of the file will be
- allowed only if the extension part of the name is .EXE,
- .COM, or .BAT. Not set by default.
-
-debug -- Can be set, but unused by the current implementation.
-
-sys_immutable -- If set, ATTR_SYS attribute on FAT is handled as
- IMMUTABLE flag on Linux. Not set by default.
-
-flush -- If set, the filesystem will try to flush to disk more
- early than normal. Not set by default.
-
-rodir -- FAT has the ATTR_RO (read-only) attribute. On Windows,
- the ATTR_RO of the directory will just be ignored,
- and is used only by applications as a flag (e.g. it's set
- for the customized folder).
-
- If you want to use ATTR_RO as read-only flag even for
- the directory, set this option.
-
-errors=panic|continue|remount-ro
- -- specify FAT behavior on critical errors: panic, continue
- without doing anything or remount the partition in
- read-only mode (default behavior).
-
-discard -- If set, issues discard/TRIM commands to the block
- device when blocks are freed. This is useful for SSD devices
- and sparse/thinly-provisoned LUNs.
-
-nfs=stale_rw|nostale_ro
- Enable this only if you want to export the FAT filesystem
- over NFS.
-
- stale_rw: This option maintains an index (cache) of directory
- inodes by i_logstart which is used by the nfs-related code to
- improve look-ups. Full file operations (read/write) over NFS is
- supported but with cache eviction at NFS server, this could
- result in ESTALE issues.
-
- nostale_ro: This option bases the inode number and filehandle
- on the on-disk location of a file in the MS-DOS directory entry.
- This ensures that ESTALE will not be returned after a file is
- evicted from the inode cache. However, it means that operations
- such as rename, create and unlink could cause filehandles that
- previously pointed at one file to point at a different file,
- potentially causing data corruption. For this reason, this
- option also mounts the filesystem readonly.
-
- To maintain backward compatibility, '-o nfs' is also accepted,
- defaulting to stale_rw
-
-dos1xfloppy -- If set, use a fallback default BIOS Parameter Block
- configuration, determined by backing device size. These static
- parameters match defaults assumed by DOS 1.x for 160 kiB,
- 180 kiB, 320 kiB, and 360 kiB floppies and floppy images.
-
-
-<bool>: 0,1,yes,no,true,false
-
-LIMITATION
----------------------------------------------------------------------
-* The fallocated region of file is discarded at umount/evict time
- when using fallocate with FALLOC_FL_KEEP_SIZE.
- So, User should assume that fallocated region can be discarded at
- last close if there is memory pressure resulting in eviction of
- the inode from the memory. As a result, for any dependency on
- the fallocated region, user should make sure to recheck fallocate
- after reopening the file.
-
-TODO
-----------------------------------------------------------------------
-* Need to get rid of the raw scanning stuff. Instead, always use
- a get next directory entry approach. The only thing left that uses
- raw scanning is the directory renaming code.
-
-
-POSSIBLE PROBLEMS
-----------------------------------------------------------------------
-* vfat_valid_longname does not properly checked reserved names.
-* When a volume name is the same as a directory name in the root
- directory of the filesystem, the directory name sometimes shows
- up as an empty file.
-* autoconv option does not work correctly.
-
-BUG REPORTS
-----------------------------------------------------------------------
-If you have trouble with the VFAT filesystem, mail bug reports to
[email protected]. Please specify the filename
-and the operation that gave you trouble.
-
-TEST SUITE
-----------------------------------------------------------------------
-If you plan to make any modifications to the vfat filesystem, please
-get the test suite that comes with the vfat distribution at
-
- http://web.archive.org/web/*/http://bmrc.berkeley.edu/
- people/chaffee/vfat.html
-
-This tests quite a few parts of the vfat filesystem and additional
-tests for new features or untested features would be appreciated.
-
-NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM
-----------------------------------------------------------------------
-(This documentation was provided by Galen C. Hunt <[email protected]>
- and lightly annotated by Gordon Chaffee).
-
-This document presents a very rough, technical overview of my
-knowledge of the extended FAT file system used in Windows NT 3.5 and
-Windows 95. I don't guarantee that any of the following is correct,
-but it appears to be so.
-
-The extended FAT file system is almost identical to the FAT
-file system used in DOS versions up to and including 6.223410239847
-:-). The significant change has been the addition of long file names.
-These names support up to 255 characters including spaces and lower
-case characters as opposed to the traditional 8.3 short names.
-
-Here is the description of the traditional FAT entry in the current
-Windows 95 filesystem:
-
- struct directory { // Short 8.3 names
- unsigned char name[8]; // file name
- unsigned char ext[3]; // file extension
- unsigned char attr; // attribute byte
- unsigned char lcase; // Case for base and extension
- unsigned char ctime_ms; // Creation time, milliseconds
- unsigned char ctime[2]; // Creation time
- unsigned char cdate[2]; // Creation date
- unsigned char adate[2]; // Last access date
- unsigned char reserved[2]; // reserved values (ignored)
- unsigned char time[2]; // time stamp
- unsigned char date[2]; // date stamp
- unsigned char start[2]; // starting cluster number
- unsigned char size[4]; // size of the file
- };
-
-The lcase field specifies if the base and/or the extension of an 8.3
-name should be capitalized. This field does not seem to be used by
-Windows 95 but it is used by Windows NT. The case of filenames is not
-completely compatible from Windows NT to Windows 95. It is not completely
-compatible in the reverse direction, however. Filenames that fit in
-the 8.3 namespace and are written on Windows NT to be lowercase will
-show up as uppercase on Windows 95.
-
-Note that the "start" and "size" values are actually little
-endian integer values. The descriptions of the fields in this
-structure are public knowledge and can be found elsewhere.
-
-With the extended FAT system, Microsoft has inserted extra
-directory entries for any files with extended names. (Any name which
-legally fits within the old 8.3 encoding scheme does not have extra
-entries.) I call these extra entries slots. Basically, a slot is a
-specially formatted directory entry which holds up to 13 characters of
-a file's extended name. Think of slots as additional labeling for the
-directory entry of the file to which they correspond. Microsoft
-prefers to refer to the 8.3 entry for a file as its alias and the
-extended slot directory entries as the file name.
-
-The C structure for a slot directory entry follows:
-
- struct slot { // Up to 13 characters of a long name
- unsigned char id; // sequence number for slot
- unsigned char name0_4[10]; // first 5 characters in name
- unsigned char attr; // attribute byte
- unsigned char reserved; // always 0
- unsigned char alias_checksum; // checksum for 8.3 alias
- unsigned char name5_10[12]; // 6 more characters in name
- unsigned char start[2]; // starting cluster number
- unsigned char name11_12[4]; // last 2 characters in name
- };
-
-If the layout of the slots looks a little odd, it's only
-because of Microsoft's efforts to maintain compatibility with old
-software. The slots must be disguised to prevent old software from
-panicking. To this end, a number of measures are taken:
-
- 1) The attribute byte for a slot directory entry is always set
- to 0x0f. This corresponds to an old directory entry with
- attributes of "hidden", "system", "read-only", and "volume
- label". Most old software will ignore any directory
- entries with the "volume label" bit set. Real volume label
- entries don't have the other three bits set.
-
- 2) The starting cluster is always set to 0, an impossible
- value for a DOS file.
-
-Because the extended FAT system is backward compatible, it is
-possible for old software to modify directory entries. Measures must
-be taken to ensure the validity of slots. An extended FAT system can
-verify that a slot does in fact belong to an 8.3 directory entry by
-the following:
-
- 1) Positioning. Slots for a file always immediately proceed
- their corresponding 8.3 directory entry. In addition, each
- slot has an id which marks its order in the extended file
- name. Here is a very abbreviated view of an 8.3 directory
- entry and its corresponding long name slots for the file
- "My Big File.Extension which is long":
-
- <proceeding files...>
- <slot #3, id = 0x43, characters = "h is long">
- <slot #2, id = 0x02, characters = "xtension whic">
- <slot #1, id = 0x01, characters = "My Big File.E">
- <directory entry, name = "MYBIGFIL.EXT">
-
- Note that the slots are stored from last to first. Slots
- are numbered from 1 to N. The Nth slot is or'ed with 0x40
- to mark it as the last one.
-
- 2) Checksum. Each slot has an "alias_checksum" value. The
- checksum is calculated from the 8.3 name using the
- following algorithm:
-
- for (sum = i = 0; i < 11; i++) {
- sum = (((sum&1)<<7)|((sum&0xfe)>>1)) + name[i]
- }
-
- 3) If there is free space in the final slot, a Unicode NULL (0x0000)
- is stored after the final character. After that, all unused
- characters in the final slot are set to Unicode 0xFFFF.
-
-Finally, note that the extended name is stored in Unicode. Each Unicode
-character takes either two or four bytes, UTF-16LE encoded.
--
2.24.0
On Fri, 8 Nov 2019 15:39:41 -0300
"Daniel W. S. Almeida" <[email protected]> wrote:
> From: "Daniel W. S. Almeida" <[email protected]>
>
> Converts vfat.txt to the reStructuredText format, improving presentation
> without changing the underlying content.
>
> Signed-off-by: Daniel W. S. Almeida <[email protected]>
Thanks for doing this conversion! A number of my comments from the FUSE
patch apply here as well:
- Copy the maintainer
- Update MAINTAINERS
- Limit use of markup
- Consider a move to the admin guide. It's less obvious here, though,
because the information about the structure of the filesystem itself
arguably does not belong there. A better place, honestly, might be as a
DOC block in the driver source itself, but that would need to be run past
the maintainer.
A few other minor comments below.
> Documentation/filesystems/index.rst | 1 +
> Documentation/filesystems/vfat.rst | 389 ++++++++++++++++++++++++++++
> Documentation/filesystems/vfat.txt | 347 -------------------------
> 3 files changed, 390 insertions(+), 347 deletions(-)
> create mode 100644 Documentation/filesystems/vfat.rst
> delete mode 100644 Documentation/filesystems/vfat.txt
>
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index 2c3a9f761205..aaffaa9042c3 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -47,3 +47,4 @@ Documentation for filesystem implementations.
> :maxdepth: 2
>
> virtiofs
> + vfat
> diff --git a/Documentation/filesystems/vfat.rst b/Documentation/filesystems/vfat.rst
> new file mode 100644
> index 000000000000..e24e69a2817d
> --- /dev/null
> +++ b/Documentation/filesystems/vfat.rst
> @@ -0,0 +1,389 @@
> +====
> +VFAT
> +====
> +
> +USING VFAT
> +==========
> +
> +To use the vfat filesystem, use the filesystem type 'vfat'. i.e.::
> +
> + mount -t vfat /dev/fd0 /mnt
> +
> +
> +No special partition formatter is required.
> +``mkdosfs`` will work fine if you want to format from within Linux.
> +
> +VFAT MOUNT OPTIONS
> +==================
> +
> +**uid=###**
> + Set the owner of all files on this filesystem.
> + The default is the *uid* of current process.
> +
> +**gid=###**
> + Set the group of all files on this filesystem.
> + The default is the *gid* of current process.
> +
> +**umask=###**
> + The permission mask (for files and directories, see *umask(1)*).
> + The default is the *umask* of current process.
> +
> +**dmask=###**
> + The permission mask for the directory.
> + The default is the *umask* of current process.
> +
> +**fmask=###**
> + The permission mask for files.
> + The default is the *umask* of current process.
> +
> +**allow_utime=###**
> + This option controls the permission check of mtime/atime.
> +
> + **-20**: If current process is in group of file's group ID, you can change timestamp.
This has become a very long line; it will be more readable if you break
it.
> +
> + **-2**: Other users can change timestamp.
> +
> + The default is set from ``dmask`` option. If the directory is
> + writable, *utime(2)* is also allowed. i.e. ``~dmask & 022``.
> +
> + Normally ``utime(2)`` checks current process is owner of
> + the file, or it has ``CAP_FOWNER`` capability. But FAT
> + filesystem doesn't have uid/gid on disk, so normal
> + check is too unflexible. With this option you can
> + relax it.
> +
> +**codepage=###**
> + Sets the codepage number for converting to shortname
> + characters on FAT filesystem.
> + By default, ``FAT_DEFAULT_CODEPAGE`` setting is used.
> +
> +**iocharset=<name>**
> + Character set to use for converting between the
> + encoding is used for user visible filename and 16 bit
> + Unicode characters. Long filenames are stored on disk
> + in Unicode format, but Unix for the most part doesn't
> + know how to deal with Unicode.
> + By default, ``FAT_DEFAULT_IOCHARSET`` setting is used.
> +
> + There is also an option of doing UTF-8 translations
> + with the utf8 option.
> +
> +.. note:: ``iocharset=utf8`` is not recommended. If unsure, you should consider the utf8 option instead.
Here too. This should be something like:
.. note::
``iocharset=utf8`` is not recommended. If unsure, you should consider
the utf8 option instead.
> +
> +**utf8=<bool>**
> + UTF-8 is the filesystem safe version of Unicode that
> + is used by the console. It can be enabled or disabled
> + for the filesystem with this option.
> + If 'uni_xlate' gets set, UTF-8 gets disabled.
> + By default, ``FAT_DEFAULT_UTF8`` setting is used.
> +
> +**uni_xlate=<bool>**
> + Translate unhandled Unicode characters to special
> + escaped sequences. This would let you backup and
> + restore filenames that are created with any Unicode
> + characters. Until Linux supports Unicode for real,
> + this gives you an alternative. Without this option,
> + a '?' is used when no translation is possible. The
> + escape character is ':' because it is otherwise
> + illegal on the vfat filesystem. The escape sequence
> + that gets used is ':' and the four digits of hexadecimal
> + unicode.
> +
> +**nonumtail=<bool>**
> + When creating 8.3 aliases, normally the alias will
> + end in '~1' or tilde followed by some number. If this
> + option is set, then if the filename is
> + "longfilename.txt" and "longfile.txt" does not
> + currently exist in the directory, ``longfile.txt`` will
> + be the short alias instead of ``longfi~1.txt``.
> +
> +**usefree**
> + Use the "free clusters" value stored on ``FSINFO``. It'll
> + be used to determine number of free clusters without
> + scanning disk. But it's not used by default, because
> + recent Windows don't update it correctly in some
> + case. If you are sure the "free clusters" on ``FSINFO`` is
> + correct, by this option you can avoid scanning disk.
> +
> +**quiet**
> + Stops printing certain warning messages.
> +
> +**check=s|r|n**
> + Case sensitivity checking setting.
> +
> + **s**: strict, case sensitive
> +
> + **r**: relaxed, case insensitive
> +
> + **n**: normal, default setting, currently case insensitive
> +
> +**nocase**
> + This was deprecated for vfat. Use ``shortname=win95`` instead.
> +
> +**shortname=lower|win95|winnt|mixed**
> + Shortname display/create setting.
> +
> + **lower**: convert to lowercase for display,
> + emulate the Windows 95 rule for create.
> +
> + **win95**: emulate the Windows 95 rule for display/create.
> +
> + **winnt**: emulate the Windows NT rule for display/create.
> +
> + **mixed**: emulate the Windows NT rule for display,
> + emulate the Windows 95 rule for create.
> +
> + Default setting is `mixed`.
> +
> +**tz=UTC**
> + Interpret timestamps as UTC rather than local time.
> + This option disables the conversion of timestamps
> + between local time (as used by Windows on FAT) and UTC
> + (which Linux uses internally). This is particularly
> + useful when mounting devices (like digital cameras)
> + that are set to UTC in order to avoid the pitfalls of
> + local time.
> +
> +**time_offset=minutes**
> + Set offset for conversion of timestamps from local time
> + used by FAT to UTC. I.e. <minutes> minutes will be subtracted
> + from each timestamp to convert it to UTC used internally by
> + Linux. This is useful when time zone set in ``sys_tz`` is
> + not the time zone used by the filesystem. Note that this
> + option still does not provide correct time stamps in all
> + cases in presence of DST - time stamps in a different DST
> + setting will be off by one hour.
> +
> +**showexec**
> + If set, the execute permission bits of the file will be
> + allowed only if the extension part of the name is ``.EXE``,
> + ``.COM``, or ``.BAT``. Not set by default.
> +
> +**debug**
> + Can be set, but unused by the current implementation.
> +
> +**sys_immutable**
> + If set, ATTR_SYS attribute on FAT is handled as
> + ``IMMUTABLE`` flag on Linux. Not set by default.
> +
> +**flush**
> + If set, the filesystem will try to flush to disk more
> + early than normal. Not set by default.
> +
> +**rodir**
> + FAT has the ``ATTR_RO`` (read-only) attribute. On Windows,
> + the ``ATTR_RO`` of the directory will just be ignored,
> + and is used only by applications as a flag (e.g. it's set
> + for the customized folder).
> +
> + If you want to use ``ATTR_RO`` as read-only flag even for
> + the directory, set this option.
> +
> +**errors=panic|continue|remount-ro**
> + specify FAT behavior on critical errors: panic, continue
> + without doing anything or remount the partition in
> + read-only mode (default behavior).
> +
> +**discard**
> + If set, issues discard/TRIM commands to the block
> + device when blocks are freed. This is useful for SSD devices
> + and sparse/thinly-provisoned LUNs.
> +
> +**nfs=stale_rw|nostale_ro**
> + Enable this only if you want to export the FAT filesystem
> + over NFS.
> +
> + **stale_rw**: This option maintains an index (cache) of directory
> + *inodes* by *i_logstart* which is used by the nfs-related code to
> + improve look-ups. Full file operations (read/write) over *NFS* is
> + supported but with cache eviction at *NFS* server, this could
> + result in ``ESTALE`` issues.
> +
> + **nostale_ro**: This option bases the *inode* number and filehandle
> + on the on-disk location of a file in the MS-DOS directory entry.
> + This ensures that ``ESTALE`` will not be returned after a file is
> + evicted from the *inode* cache. However, it means that operations
> + such as rename, create and unlink could cause filehandles that
> + previously pointed at one file to point at a different file,
> + potentially causing data corruption. For this reason, this
> + option also mounts the filesystem readonly.
> +
> + To maintain backward compatibility, ``'-o nfs'`` is also accepted,
> + defaulting to ``stale_rw``
> +
> +**dos1xfloppy <bool>: 0,1,yes,no,true,false**
> + If set, use a fallback default BIOS Parameter Block
> + configuration, determined by backing device size. These static
> + parameters match defaults assumed by DOS 1.x for 160 kiB,
> + 180 kiB, 320 kiB, and 360 kiB floppies and floppy images.
> +
> +
> +
> +LIMITATION
> +==========
> +The fallocated region of file is discarded at umount/evict time
Put a blank line after the subheading markup.
> +when using fallocate with FALLOC_FL_KEEP_SIZE.
> +So, User should assume that fallocated region can be discarded at
> +last close if there is memory pressure resulting in eviction of
> +the inode from the memory. As a result, for any dependency on
> +the fallocated region, user should make sure to recheck fallocate
> +after reopening the file.
> +
> +TODO
> +====
> +Need to get rid of the raw scanning stuff. Instead, always use
> +a get next directory entry approach. The only thing left that uses
> +raw scanning is the directory renaming code.
> +
> +
> +POSSIBLE PROBLEMS
> +=================
> +
> +- vfat_valid_longname does not properly checked reserved names.
> +- When a volume name is the same as a directory name in the root
> + directory of the filesystem, the directory name sometimes shows
> + up as an empty file.
> +- autoconv option does not work correctly.
> +
> +BUG REPORTS
> +===========
> +If you have trouble with the *VFAT* filesystem, mail bug reports to
> [email protected].
> +
> +Please specify the filename and the operation that gave you trouble.
> +
> +TEST SUITE
> +==========
> +If you plan to make any modifications to the vfat filesystem, please
> +get the test suite that comes with the vfat distribution at
> +
> +`<http://web.archive.org/web/*/http://bmrc.berkeley.edu/people/chaffee/vfat.html>`_
> +
> +This tests quite a few parts of the vfat filesystem and additional
> +tests for new features or untested features would be appreciated.
> +
> +NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM
> +=============================================
> +This documentation was provided by Galen C. Hunt [email protected] and lightly annotated by Gordon Chaffee.
One more time, please avoid these really long lines.
> +
> +This document presents a very rough, technical overview of my
> +knowledge of the extended FAT file system used in Windows NT 3.5 and
> +Windows 95. I don't guarantee that any of the following is correct,
> +but it appears to be so.
A paragraph like that suggests that this information might be a wee bit out
of date - even if VFAT hasn't been changing much. It might be worth asking
the maintainer for an opinion on how current things are and maybe putting
in a warning if it's truly obsolete.
> +The extended FAT file system is almost identical to the FAT
> +file system used in DOS versions up to and including *6.223410239847*
> +:-). The significant change has been the addition of long file names.
> +These names support up to *255* characters including spaces and lower
> +case characters as opposed to the traditional *8.3* short names.
> +
> +Here is the description of the traditional *FAT* entry in the current
> +Windows 95 filesystem: ::
Too many colons, just say "filesystem::". There's a number of these.
I'll stop here, that's enough to work on for now.
Thanks,
jon