Skip to contentSkip to conversation

exfat: doc: add documentation

PATCH In review Namjae Jeon 3 participants 7 messages Aug 31 – Sep 1

Subsystems (2)
lore
Share & tools
lore

Namjae Jeon

author maintainer
#0 lore raw

PATCH 1/1 exfat: doc: add documentation

Add documentation for the Linux exFAT filesystem driver, including supported mount options and exfatprogs.

---
 Documentation/filesystems/exfat.rst | 117 ++++++++++++++++++++++++++++
 Documentation/filesystems/index.rst |   1 +
 2 files changed, 118 insertions(+)
 create mode 100644 Documentation/filesystems/exfat.rst
Documentation/filesystems/exfat.rst new file +117 -0
new file mode 100644
index 000000000000..ce5c9344a7b2
@@ -0,0 +1,117 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
+The Linux exFAT filesystem driver
+==================================
+
+
+.. Table of contents
+
+   - Overview
+   - Utilities support
+   - Supported mount options
+
+
+Overview
+========
+
+exFAT is a filesystem designed for removable storage and other devices that
+need to store large files.  The Linux exFAT filesystem driver provides read
+and write support for exFAT volumes.
+
+To mount an exFAT volume, use the ``exfat`` filesystem type::
+
+  mount -t exfat /dev/sdX1 /mnt
+
+
+Utilities support
+=================
+
+The exfatprogs project provides userspace utilities for creating, checking,
+repairing, inspecting, and tuning exFAT filesystems.  Use exfatprogs when
+creating or checking an exFAT filesystem.  For example, use ``mkfs.exfat``
+to create a filesystem and ``fsck.exfat`` to check or repair one.
+
+The project is available at:
+
+  https://github.com/exfatprogs/exfatprogs
+
+
+Supported mount options
+=======================
+
+The exFAT driver supports the following mount options:
+
+======================= ====================================================
+uid=
+gid=                    Set the owner and group of all files and
+                        directories.  The default is the uid and gid of
+                        the process mounting the filesystem.
+
+umask=                  Set the permission mask for files and directories.
+                        The default is the umask of the process mounting
+                        the filesystem.
+
+dmask=                  Set the permission mask for directories.
+
+fmask=                  Set the permission mask for files.
+
+allow_utime=            Control the permission check for changing file
+                        timestamps.  Only permission bits 0022 are used.
+                        Permission bit 0020 allows members of the file's
+                        group to change timestamps, and permission bit 0002
+                        allows other users to change timestamps.  The
+                        default is derived from dmask (``~dmask & 0022``).
+
+iocharset=name          Character set used to convert between user-visible
+                        filenames and the UTF-16 character encoding used by
+                        exFAT.  The default is
+                        CONFIG_EXFAT_DEFAULT_IOCHARSET, which is ``utf8``
+                        unless changed at kernel configuration time.  Use
+                        ``iocharset=utf8`` for UTF-8 filename handling.
+
+errors=                 Specify exFAT behavior on filesystem errors.  The
+                        value must be ``panic``, ``continue``, or
+                        ``remount-ro``.  These respectively panic, continue
+                        without changing the filesystem, or remount the
+                        filesystem read-only.  The default is
+                        ``remount-ro``.
+
+discard                 Issue discard/TRIM requests to the block device
+                        when clusters are freed.  This is disabled by
+                        default.  ``nodiscard`` disables it explicitly.
+
+keep_last_dots          Keep trailing periods in path components during
+                        lookup.  Without this option, trailing periods are
+                        stripped.  Existing entries with trailing periods
+                        can be accessed when this option is enabled, but
+                        creating new entries with trailing periods is
+                        rejected.
+
+sys_tz                  Use the system timezone as the UTC offset when an
+                        exFAT timestamp does not contain a valid timezone
+                        offset.  This takes precedence over time_offset.
+
+time_offset=minutes     Set the UTC offset, in minutes, used when an exFAT
+                        timestamp does not contain a valid timezone offset.
+                        Values from -1440 to 1440 are accepted.  The default
+                        is 0.  This option is ignored when sys_tz is set.
+
+zero_size_dir           Create directories with zero size and without
+                        allocating a cluster.  This is disabled by default;
+                        the default behavior allocates a cluster for a new
+                        directory.  ``nozero_size_dir`` disables it
+                        explicitly.
+======================= ====================================================
+
+
+Deprecated mount options
+------------------------
+
+The following options are accepted for compatibility but should not be used:
+
+``utf8``
+  Deprecated.  Use ``iocharset=utf8`` instead.
+
+``debug``, ``namecase=``, ``codepage=``
+  Deprecated and ignored by the exFAT driver.
Documentation/filesystems/index.rst +1 -0
index 734a45e51667..fbd55915a318 100644
@@ -87,6 +87,7 @@ Documentation for filesystem implementations.
    ecryptfs
    efivarfs
    erofs
+   exfat
    ext2
    ext3
    ext4/index
Signature · 1 line
2.25.1
#1 lore raw

The option list and the defaults match fs/exfat/, including the allow_utime derivation and the time_offset range. Three things the table leaves out or implies.

Most of the options cannot be changed on remount. exfat_reconfigure() fails with -EINVAL if iocharset, keep_last_dots, sys_tz, time_offset, uid, gid, fmask, dmask or allow_utime differ from the current values (super.c:789), leaving only errors, discard and zero_size_dir. Nothing is logged on that path, so "mount -o remount,uid=1000" returns a bare EINVAL. The reason sits in the code right above the test: the old values are cached in inodes and dentries.

umask= sets both masks, and the options take effect in the order they are written. Opt_umask assigns fs_fmask and fs_dmask (super.c:289), so "-o umask=0022,dmask=0077" ends up with dmask 0077, while
"-o dmask=0077,umask=0022" silently puts dmask back to 0022. The dmask= and fmask= entries also do not give their default, which is the same current umask that umask= defaults to.

utf8 is ignored rather than an old spelling of iocharset=utf8. It shares a fallthrough with debug, namecase= and codepage= (super.c:331), so "mount -o utf8" selects nothing. exfat_show_options() prints iocharset=utf8 only when opts->utf8 is set (super.c:132), and nothing sets that but iocharset=utf8. Listing utf8 apart from the group described as "Deprecated and ignored" reads as if it still has an effect.

Thanks,
Zhan Xusheng

author maintainer
#2 lore raw
Quoted 20 lines · Zhan Xusheng

The option list and the defaults match fs/exfat/, including the allow_utime derivation and the time_offset range. Three things the table leaves out or implies.

Most of the options cannot be changed on remount. exfat_reconfigure() fails with -EINVAL if iocharset, keep_last_dots, sys_tz, time_offset, uid, gid, fmask, dmask or allow_utime differ from the current values (super.c:789), leaving only errors, discard and zero_size_dir. Nothing is logged on that path, so "mount -o remount,uid=1000" returns a bare EINVAL. The reason sits in the code right above the test: the old values are cached in inodes and dentries.

umask= sets both masks, and the options take effect in the order they are written. Opt_umask assigns fs_fmask and fs_dmask (super.c:289), so "-o umask=0022,dmask=0077" ends up with dmask 0077, while
"-o dmask=0077,umask=0022" silently puts dmask back to 0022. The dmask= and fmask= entries also do not give their default, which is the same current umask that umask= defaults to.

Quoted 6 lines

utf8 is ignored rather than an old spelling of iocharset=utf8. It shares a fallthrough with debug, namecase= and codepage= (super.c:331), so "mount -o utf8" selects nothing. exfat_show_options() prints iocharset=utf8 only when opts->utf8 is set (super.c:132), and nothing sets that but iocharset=utf8. Listing utf8 apart from the group described as "Deprecated and ignored" reads as if it still has an effect.

I will update them on the v2 version.
Thanks for the review!

#3 lore raw
In reply to Zhan Xusheng
Quoted 26 lines · Zhan Xusheng

The option list and the defaults match fs/exfat/, including the allow_utime derivation and the time_offset range. Three things the table leaves out or implies.

Most of the options cannot be changed on remount. exfat_reconfigure() fails with -EINVAL if iocharset, keep_last_dots, sys_tz, time_offset, uid, gid, fmask, dmask or allow_utime differ from the current values (super.c:789), leaving only errors, discard and zero_size_dir. Nothing is logged on that path, so "mount -o remount,uid=1000" returns a bare EINVAL. The reason sits in the code right above the test: the old values are cached in inodes and dentries.

umask= sets both masks, and the options take effect in the order they are written. Opt_umask assigns fs_fmask and fs_dmask (super.c:289), so "-o umask=0022,dmask=0077" ends up with dmask 0077, while
"-o dmask=0077,umask=0022" silently puts dmask back to 0022. The dmask= and fmask= entries also do not give their default, which is the same current umask that umask= defaults to.

utf8 is ignored rather than an old spelling of iocharset=utf8. It shares a fallthrough with debug, namecase= and codepage= (super.c:331), so "mount -o utf8" selects nothing. exfat_show_options() prints iocharset=utf8 only when opts->utf8 is set (super.c:132), and nothing sets that but iocharset=utf8. Listing utf8 apart from the group described as "Deprecated and ignored" reads as if it still has an effect.

Quoted 2 lines

Thanks,
Zhan Xusheng

idk.. The proposed documentation says nothing about the remount option as of yet. Reconfiguartion of the most of mount options FAT isn't supported either, but the documentation doesn't really specifically mention that fact because there's little to no actual use case other than remounting ro or rw.

Other than the last paragraph, these are separate issues not really pertaininig to the proposed documentation, if they're valid. I suggest that you submit patches fixing the issues if you'd like to contribute.

The valid point on "utf8", though. Opt_utf8 is ignored. I think this is actually a bug in the implementation rather than a factual error in the doc. "Deprecated" shouldn't mean "it's a no-op". They're totally different things. fs/fat still honors it, so I think fs/exfat should do the same.

Davo

#4 lore raw
In reply to Namjae Jeon
Quoted 9 lines · Namjae Jeon

Add documentation for the Linux exFAT filesystem driver, including supported mount options and exfatprogs.

---
 Documentation/filesystems/exfat.rst | 117 ++++++++++++++++++++++++++++
 Documentation/filesystems/index.rst |   1 +
 2 files changed, 118 insertions(+)
 create mode 100644 Documentation/filesystems/exfat.rst

Don't forget to add

F:    Documentation/filesystems/exfat.rst

in MAINTAINERS

Well, it's ain't much but it's a good start.

Davo

author maintainer
#5 lore raw
Quoted 11 lines · David Timber
Quoted 9 lines · Namjae Jeon

Add documentation for the Linux exFAT filesystem driver, including supported mount options and exfatprogs.

---
 Documentation/filesystems/exfat.rst | 117 ++++++++++++++++++++++++++++
 Documentation/filesystems/index.rst |   1 +
 2 files changed, 118 insertions(+)
 create mode 100644 Documentation/filesystems/exfat.rst
Quoted 7 lines

Don't forget to add

F: Documentation/filesystems/exfat.rst

in MAINTAINERS

Well, it's ain't much but it's a good start.

Sure, will do. Thanks for pointing it out:)

#6 lore raw
Quoted 11 lines · Namjae Jeon
Quoted 10 lines · David Timber
Quoted 9 lines · Namjae Jeon

Add documentation for the Linux exFAT filesystem driver, including supported mount options and exfatprogs.

---
 Documentation/filesystems/exfat.rst | 117 ++++++++++++++++++++++++++++
 Documentation/filesystems/index.rst |   1 +
 2 files changed, 118 insertions(+)
 create mode 100644 Documentation/filesystems/exfat.rst
Quoted 8 lines
Quoted 7 lines

Don't forget to add

F: Documentation/filesystems/exfat.rst

in MAINTAINERS

Well, it's ain't much but it's a good start.

Sure, will do. Thanks for pointing it out:)

Oh, also, if this gets merged, it's worth updating the man page mount(8) of util-linux as well.

I'll cc you when I do, but anyone else snooping this conversation can beat me to it.

Davo