€•C      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ4/translations/zh_CN/filesystems/bcachefs/casefolding”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/zh_TW/filesystems/bcachefs/casefolding”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/it_IT/filesystems/bcachefs/casefolding”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/ja_JP/filesystems/bcachefs/casefolding”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/ko_KR/filesystems/bcachefs/casefolding”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/sp_SP/filesystems/bcachefs/casefolding”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒN/var/lib/git/docbuild/linux/Documentation/filesystems/bcachefs/casefolding.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒCasefolding”h]”hŒCasefolding”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hŒ›bcachefs has support for case-insensitive file and directory
lookups using the regular `chattr +F` (`S_CASEFOLD`, `FS_CASEFOLD_FL`)
casefolding attributes.”h]”(hŒWbcachefs has support for case-insensitive file and directory
lookups using the regular ”…””}”(hhËhžhhŸNh NubhŒtitle_reference”“”)”}”(hŒ`chattr +F`”h]”hŒ	chattr +F”…””}”(hhÕhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhhËubhŒ (”…””}”(hhËhžhhŸNh NubhÔ)”}”(hŒ`S_CASEFOLD`”h]”hŒ
S_CASEFOLD”…””}”(hhçhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhhËubhŒ, ”…””}”(hhËhžhhŸNh NubhÔ)”}”(hŒ`FS_CASEFOLD_FL`”h]”hŒFS_CASEFOLD_FL”…””}”(hhùhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhhËubhŒ)
casefolding attributes.”…””}”(hhËhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hX  The main usecase for casefolding is compatibility with software written
against other filesystems that rely on casefolded lookups
(eg. NTFS and Wine/Proton).
Taking advantage of file-system level casefolding can lead to great
loading time gains in many applications and games.”h]”hX  The main usecase for casefolding is compatibility with software written
against other filesystems that rely on casefolded lookups
(eg. NTFS and Wine/Proton).
Taking advantage of file-system level casefolding can lead to great
loading time gains in many applications and games.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K
hh¶hžhubhÊ)”}”(hXg  Casefolding support requires a kernel with the `CONFIG_UNICODE` enabled.
Once a directory has been flagged for casefolding, a feature bit
is enabled on the superblock which marks the filesystem as using
casefolding.
When the feature bit for casefolding is enabled, it is no longer possible
to mount that filesystem on kernels without `CONFIG_UNICODE` enabled.”h]”(hŒ/Casefolding support requires a kernel with the ”…””}”(hj  hžhhŸNh NubhÔ)”}”(hŒ`CONFIG_UNICODE`”h]”hŒCONFIG_UNICODE”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhj  ubhX   enabled.
Once a directory has been flagged for casefolding, a feature bit
is enabled on the superblock which marks the filesystem as using
casefolding.
When the feature bit for casefolding is enabled, it is no longer possible
to mount that filesystem on kernels without ”…””}”(hj  hžhhŸNh NubhÔ)”}”(hŒ`CONFIG_UNICODE`”h]”hŒCONFIG_UNICODE”…””}”(hj9  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhj  ubhŒ	 enabled.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hŒ©On the lookup/query side: casefolding is implemented by allocating a new
string of `BCH_NAME_MAX` length using the `utf8_casefold` function to
casefold the query string.”h]”(hŒSOn the lookup/query side: casefolding is implemented by allocating a new
string of ”…””}”(hjQ  hžhhŸNh NubhÔ)”}”(hŒ`BCH_NAME_MAX`”h]”hŒBCH_NAME_MAX”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjQ  ubhŒ length using the ”…””}”(hjQ  hžhhŸNh NubhÔ)”}”(hŒ`utf8_casefold`”h]”hŒutf8_casefold”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjQ  ubhŒ' function to
casefold the query string.”…””}”(hjQ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hŒ»On the dirent side: casefolding is implemented by ensuring the `bkey`'s
hash is made from the casefolded string and storing the cached casefolded
name with the regular name in the dirent.”h]”(hŒ?On the dirent side: casefolding is implemented by ensuring the ”…””}”(hjƒ  hžhhŸNh NubhÔ)”}”(hŒ`bkey`”h]”hŒbkey”…””}”(hj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjƒ  ubhŒxâ€™s
hash is made from the casefolded string and storing the cached casefolded
name with the regular name in the dirent.”…””}”(hjƒ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hŒThe structure looks like this:”h]”hŒThe structure looks like this:”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ4Regular:    [dirent data][regular name][nul][nul]...”h]”hÊ)”}”(hjº  h]”hŒ4Regular:    [dirent data][regular name][nul][nul]...”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K!hj¸  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¶  hj³  hžhhŸh³h Nubj·  )”}”(hŒWCasefolded: [dirent data][reg len][cf len][regular name][casefolded name][nul][nul]...
”h]”hÊ)”}”(hŒVCasefolded: [dirent data][reg len][cf len][regular name][casefolded name][nul][nul]...”h]”hŒVCasefolded: [dirent data][reg len][cf len][regular name][casefolded name][nul][nul]...”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K"hjÏ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¶  hj³  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1j±  hŸh³h K!hh¶hžhubhÊ)”}”(hŒ¥(Do note, the number of NULs here is merely for illustration; their count can
vary per-key, and they may not even be present if the key is aligned to
`sizeof(u64)`.)”h]”(hŒ–(Do note, the number of NULs here is merely for illustration; their count can
vary per-key, and they may not even be present if the key is aligned to
”…””}”(hjï  hžhhŸNh NubhÔ)”}”(hŒ`sizeof(u64)`”h]”hŒsizeof(u64)”…””}”(hj÷  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjï  ubhŒ.)”…””}”(hjï  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K$hh¶hžhubhÊ)”}”(hŒ±This is efficient as it means that for all file lookups that require casefolding,
it has identical performance to a regular lookup:
a hash comparison and a `memcmp` of the name.”h]”(hŒœThis is efficient as it means that for all file lookups that require casefolding,
it has identical performance to a regular lookup:
a hash comparison and a ”…””}”(hj  hžhhŸNh NubhÔ)”}”(hŒ`memcmp`”h]”hŒmemcmp”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhj  ubhŒ of the name.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K(hh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒ	Rationale”h]”hŒ	Rationale”…””}”(hj2  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj/  hžhhŸh³h K-ubhÊ)”}”(hX  Several designs were considered for this system:
One was to introduce a dirent_v2, however that would be painful especially as
the hash system only has support for a single key type. This would also need
`BCH_NAME_MAX` to change between versions, and a new feature bit.”h]”(hŒÌSeveral designs were considered for this system:
One was to introduce a dirent_v2, however that would be painful especially as
the hash system only has support for a single key type. This would also need
”…””}”(hj@  hžhhŸNh NubhÔ)”}”(hŒ`BCH_NAME_MAX`”h]”hŒBCH_NAME_MAX”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhj@  ubhŒ3 to change between versions, and a new feature bit.”…””}”(hj@  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K/hj/  hžhubhÊ)”}”(hX+  Another option was to store without the two lengths, and just take the length of
the regular name and casefolded name contiguously / 2 as the length. This would
assume that the regular length == casefolded length, but that could potentially
not be true, if the uppercase unicode glyph had a different UTF-8 encoding than
the lowercase unicode glyph.
It would be possible to disregard the casefold cache for those cases, but it was
decided to simply encode the two string lengths in the key to avoid random
performance issues if this edgecase was ever hit.”h]”hX+  Another option was to store without the two lengths, and just take the length of
the regular name and casefolded name contiguously / 2 as the length. This would
assume that the regular length == casefolded length, but that could potentially
not be true, if the uppercase unicode glyph had a different UTF-8 encoding than
the lowercase unicode glyph.
It would be possible to disregard the casefold cache for those cases, but it was
decided to simply encode the two string lengths in the key to avoid random
performance issues if this edgecase was ever hit.”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K4hj/  hžhubhÊ)”}”(hŒéThe option settled on was to use a free-bit in d_type to mark a dirent as having
a casefold cache, and then treat the first 4 bytes the name block as lengths.
You can see this in the `d_cf_name_block` member of union in `bch_dirent`.”h]”(hŒ·The option settled on was to use a free-bit in d_type to mark a dirent as having
a casefold cache, and then treat the first 4 bytes the name block as lengths.
You can see this in the ”…””}”(hjn  hžhhŸNh NubhÔ)”}”(hŒ`d_cf_name_block`”h]”hŒd_cf_name_block”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjn  ubhŒ member of union in ”…””}”(hjn  hžhhŸNh NubhÔ)”}”(hŒ`bch_dirent`”h]”hŒ
bch_dirent”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjn  ubhŒ.”…””}”(hjn  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K=hj/  hžhubhÊ)”}”(hXP  The feature bit was used to allow casefolding support to be enabled for the majority
of users, but some allow users who have no need for the feature to still use bcachefs as
`CONFIG_UNICODE` can increase the kernel side a significant amount due to the tables used,
which may be decider between using bcachefs for eg. embedded platforms.”h]”(hŒ®The feature bit was used to allow casefolding support to be enabled for the majority
of users, but some allow users who have no need for the feature to still use bcachefs as
”…””}”(hj   hžhhŸNh NubhÔ)”}”(hŒ`CONFIG_UNICODE`”h]”hŒCONFIG_UNICODE”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhj   ubhŒ’ can increase the kernel side a significant amount due to the tables used,
which may be decider between using bcachefs for eg. embedded platforms.”…””}”(hj   hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KAhj/  hžhubhÊ)”}”(hX/  Other filesystems like ext4 and f2fs have a super-block level option for casefolding
encoding, but bcachefs currently does not provide this. ext4 and f2fs do not expose
any encodings than a single UTF-8 version. When future encodings are desirable,
they will be added trivially using the opts mechanism.”h]”hX/  Other filesystems like ext4 and f2fs have a super-block level option for casefolding
encoding, but bcachefs currently does not provide this. ext4 and f2fs do not expose
any encodings than a single UTF-8 version. When future encodings are desirable,
they will be added trivially using the opts mechanism.”…””}”(hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KFhj/  hžhubeh}”(h]”Œ	rationale”ah ]”h"]”Œ	rationale”ah$]”h&]”uh1h´hh¶hžhhŸh³h K-ubhµ)”}”(hhh]”(hº)”}”(hŒdentry/dcache considerations”h]”hŒdentry/dcache considerations”…””}”(hjÙ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÖ  hžhhŸh³h KLubhÊ)”}”(hŒiCurrently, in casefolded directories, bcachefs (like other filesystems) will not cache
negative dentry's.”h]”hŒkCurrently, in casefolded directories, bcachefs (like other filesystems) will not cache
negative dentryâ€™s.”…””}”(hjç  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KNhjÖ  hžhubhÊ)”}”(hŒPThis is because currently doing so presents a problem in the following scenario:”h]”hŒPThis is because currently doing so presents a problem in the following scenario:”…””}”(hjõ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KQhjÖ  hžhubhŒblock_quote”“”)”}”(hŒ’- Lookup file "blAH" in a casefolded directory
- Creation of file "BLAH" in a casefolded directory
- Lookup file "blAH" in a casefolded directory
”h]”j²  )”}”(hhh]”(j·  )”}”(hŒ,Lookup file "blAH" in a casefolded directory”h]”hÊ)”}”(hj  h]”hŒ0Lookup file â€œblAHâ€ in a casefolded directory”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KShj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¶  hj	  ubj·  )”}”(hŒ1Creation of file "BLAH" in a casefolded directory”h]”hÊ)”}”(hj%  h]”hŒ5Creation of file â€œBLAHâ€ in a casefolded directory”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KThj#  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¶  hj	  ubj·  )”}”(hŒ-Lookup file "blAH" in a casefolded directory
”h]”hÊ)”}”(hŒ,Lookup file "blAH" in a casefolded directory”h]”hŒ0Lookup file â€œblAHâ€ in a casefolded directory”…””}”(hj>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KUhj:  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¶  hj	  ubeh}”(h]”h ]”h"]”h$]”h&]”jí  Œ-”uh1j±  hŸh³h KShj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KShjÖ  hžhubhÊ)”}”(hŒ1This would fail if negative dentry's were cached.”h]”hŒ3This would fail if negative dentryâ€™s were cached.”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KWhjÖ  hžhubhÊ)”}”(hŒMThis is slightly suboptimal, but could be fixed in future with some vfs work.”h]”hŒMThis is slightly suboptimal, but could be fixed in future with some vfs work.”…””}”(hjm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KYhjÖ  hžhubeh}”(h]”Œdentry-dcache-considerations”ah ]”h"]”Œdentry/dcache considerations”ah$]”h&]”uh1h´hh¶hžhhŸh³h KLubeh}”(h]”Œcasefolding”ah ]”h"]”Œcasefolding”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j®  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jˆ  j…  jÓ  jÐ  j€  j}  uŒ	nametypes”}”(jˆ  ‰jÓ  ‰j€  ‰uh}”(j…  h¶jÐ  j/  j}  jÖ  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.