[PATCH] exfat: doc: add documentation

[PATCH] exfat: doc: add documentation

[Namjae Jeon]

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

Signed-off-by: Namjae Jeon <linkinjeon@kernel.org>
---
 Documentation/filesystems/exfat.rst | 117 ++++++++++++++++++++++++++++
 Documentation/filesystems/index.rst |   1 +
 2 files changed, 118 insertions(+)
 create mode 100644 Documentation/filesystems/exfat.rst

diff --git a/Documentation/filesystems/exfat.rst b/Documentation/filesystems/exfat.rst
new file mode 100644
index 000000000000..ce5c9344a7b2
--- /dev/null
+++ b/Documentation/filesystems/exfat.rst
@@ -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.
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 734a45e51667..fbd55915a318 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -87,6 +87,7 @@ Documentation for filesystem implementations.
    ecryptfs
    efivarfs
    erofs
+   exfat
    ext2
    ext3
    ext4/index
-- 
2.25.1

Re: [PATCH] exfat: doc: add documentation

[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.

Thanks,
Zhan Xusheng

Re: [PATCH] exfat: doc: add documentation

[Namjae Jeon]

On Mon, Aug 31, 2026 at 11:49 PM Zhan Xusheng <zhanxusheng1024@gmail.com> wrote:
>
> 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.
I will update them on the v2 version.
Thanks for the review!

Re: [PATCH] exfat: doc: add documentation

[David Timber]

On 8/31/26 14:49, Zhan Xusheng wrote:
> 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
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

Re: [PATCH] exfat: doc: add documentation

[David Timber]

On 8/31/26 10:53, Namjae Jeon wrote:
> Add documentation for the Linux exFAT filesystem driver, including
> supported mount options and exfatprogs.
>
> Signed-off-by: Namjae Jeon <linkinjeon@kernel.org>
> ---
>  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

Re: [PATCH] exfat: doc: add documentation

[Namjae Jeon]

On Tue, Sep 1, 2026 at 3:24 PM David Timber <dxdt@dev.snart.me> wrote:
>
> On 8/31/26 10:53, Namjae Jeon wrote:
> > Add documentation for the Linux exFAT filesystem driver, including
> > supported mount options and exfatprogs.
> >
> > Signed-off-by: Namjae Jeon <linkinjeon@kernel.org>
> > ---
> >  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.
Sure, will do. Thanks for pointing it out:)

Re: [PATCH] exfat: doc: add documentation

[David Timber]

On 9/1/26 06:48, Namjae Jeon wrote:
> On Tue, Sep 1, 2026 at 3:24 PM David Timber <dxdt@dev.snart.me> wrote:
>> On 8/31/26 10:53, Namjae Jeon wrote:
>>> Add documentation for the Linux exFAT filesystem driver, including
>>> supported mount options and exfatprogs.
>>>
>>> Signed-off-by: Namjae Jeon <linkinjeon@kernel.org>
>>> ---
>>>  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.
> 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