Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | USING VFAT |
2 | ---------------------------------------------------------------------- | |
3 | To use the vfat filesystem, use the filesystem type 'vfat'. i.e. | |
4 | mount -t vfat /dev/fd0 /mnt | |
5 | ||
6 | No special partition formatter is required. mkdosfs will work fine | |
7 | if you want to format from within Linux. | |
8 | ||
9 | VFAT MOUNT OPTIONS | |
10 | ---------------------------------------------------------------------- | |
8986ab59 BT |
11 | uid=### -- Set the owner of all files on this filesystem. |
12 | The default is the uid of current process. | |
13 | ||
14 | gid=### -- Set the group of all files on this filesystem. | |
15 | The default is the gid of current process. | |
16 | ||
1da177e4 LT |
17 | umask=### -- The permission mask (for files and directories, see umask(1)). |
18 | The default is the umask of current process. | |
19 | ||
20 | dmask=### -- The permission mask for the directory. | |
21 | The default is the umask of current process. | |
22 | ||
23 | fmask=### -- The permission mask for files. | |
24 | The default is the umask of current process. | |
25 | ||
1ae43f82 OH |
26 | allow_utime=### -- This option controls the permission check of mtime/atime. |
27 | ||
28 | 20 - If current process is in group of file's group ID, | |
29 | you can change timestamp. | |
30 | 2 - Other users can change timestamp. | |
31 | ||
32 | The default is set from `dmask' option. (If the directory is | |
33 | writable, utime(2) is also allowed. I.e. ~dmask & 022) | |
34 | ||
35 | Normally utime(2) checks current process is owner of | |
36 | the file, or it has CAP_FOWNER capability. But FAT | |
37 | filesystem doesn't have uid/gid on disk, so normal | |
38 | check is too unflexible. With this option you can | |
39 | relax it. | |
40 | ||
1da177e4 LT |
41 | codepage=### -- Sets the codepage number for converting to shortname |
42 | characters on FAT filesystem. | |
43 | By default, FAT_DEFAULT_CODEPAGE setting is used. | |
44 | ||
8986ab59 | 45 | iocharset=<name> -- Character set to use for converting between the |
1da177e4 LT |
46 | encoding is used for user visible filename and 16 bit |
47 | Unicode characters. Long filenames are stored on disk | |
48 | in Unicode format, but Unix for the most part doesn't | |
49 | know how to deal with Unicode. | |
50 | By default, FAT_DEFAULT_IOCHARSET setting is used. | |
51 | ||
4de151d8 | 52 | There is also an option of doing UTF-8 translations |
1da177e4 LT |
53 | with the utf8 option. |
54 | ||
55 | NOTE: "iocharset=utf8" is not recommended. If unsure, | |
56 | you should consider the following option instead. | |
57 | ||
4de151d8 | 58 | utf8=<bool> -- UTF-8 is the filesystem safe version of Unicode that |
38739380 MS |
59 | is used by the console. It can be enabled or disabled |
60 | for the filesystem with this option. | |
61 | If 'uni_xlate' gets set, UTF-8 gets disabled. | |
62 | By default, FAT_DEFAULT_UTF8 setting is used. | |
1da177e4 LT |
63 | |
64 | uni_xlate=<bool> -- Translate unhandled Unicode characters to special | |
65 | escaped sequences. This would let you backup and | |
66 | restore filenames that are created with any Unicode | |
67 | characters. Until Linux supports Unicode for real, | |
68 | this gives you an alternative. Without this option, | |
69 | a '?' is used when no translation is possible. The | |
70 | escape character is ':' because it is otherwise | |
71 | illegal on the vfat filesystem. The escape sequence | |
72 | that gets used is ':' and the four digits of hexadecimal | |
73 | unicode. | |
74 | ||
75 | nonumtail=<bool> -- When creating 8.3 aliases, normally the alias will | |
76 | end in '~1' or tilde followed by some number. If this | |
77 | option is set, then if the filename is | |
78 | "longfilename.txt" and "longfile.txt" does not | |
79 | currently exist in the directory, 'longfile.txt' will | |
80 | be the short alias instead of 'longfi~1.txt'. | |
81 | ||
28ec039c OH |
82 | usefree -- Use the "free clusters" value stored on FSINFO. It'll |
83 | be used to determine number of free clusters without | |
84 | scanning disk. But it's not used by default, because | |
85 | recent Windows don't update it correctly in some | |
86 | case. If you are sure the "free clusters" on FSINFO is | |
87 | correct, by this option you can avoid scanning disk. | |
88 | ||
1da177e4 LT |
89 | quiet -- Stops printing certain warning messages. |
90 | ||
91 | check=s|r|n -- Case sensitivity checking setting. | |
92 | s: strict, case sensitive | |
93 | r: relaxed, case insensitive | |
94 | n: normal, default setting, currently case insensitive | |
95 | ||
8986ab59 BT |
96 | nocase -- This was deprecated for vfat. Use shortname=win95 instead. |
97 | ||
1da177e4 LT |
98 | shortname=lower|win95|winnt|mixed |
99 | -- Shortname display/create setting. | |
100 | lower: convert to lowercase for display, | |
101 | emulate the Windows 95 rule for create. | |
102 | win95: emulate the Windows 95 rule for display/create. | |
103 | winnt: emulate the Windows NT rule for display/create. | |
104 | mixed: emulate the Windows NT rule for display, | |
105 | emulate the Windows 95 rule for create. | |
95523475 | 106 | Default setting is `mixed'. |
1da177e4 | 107 | |
41003cde JP |
108 | tz=UTC -- Interpret timestamps as UTC rather than local time. |
109 | This option disables the conversion of timestamps | |
110 | between local time (as used by Windows on FAT) and UTC | |
8986ab59 | 111 | (which Linux uses internally). This is particularly |
41003cde JP |
112 | useful when mounting devices (like digital cameras) |
113 | that are set to UTC in order to avoid the pitfalls of | |
114 | local time. | |
58156c8f JK |
115 | time_offset=minutes |
116 | -- Set offset for conversion of timestamps from local time | |
117 | used by FAT to UTC. I.e. <minutes> minutes will be subtracted | |
118 | from each timestamp to convert it to UTC used internally by | |
119 | Linux. This is useful when time zone set in sys_tz is | |
120 | not the time zone used by the filesystem. Note that this | |
121 | option still does not provide correct time stamps in all | |
122 | cases in presence of DST - time stamps in a different DST | |
123 | setting will be off by one hour. | |
41003cde | 124 | |
8986ab59 BT |
125 | showexec -- If set, the execute permission bits of the file will be |
126 | allowed only if the extension part of the name is .EXE, | |
127 | .COM, or .BAT. Not set by default. | |
128 | ||
129 | debug -- Can be set, but unused by the current implementation. | |
130 | ||
131 | sys_immutable -- If set, ATTR_SYS attribute on FAT is handled as | |
132 | IMMUTABLE flag on Linux. Not set by default. | |
133 | ||
134 | flush -- If set, the filesystem will try to flush to disk more | |
135 | early than normal. Not set by default. | |
136 | ||
19f59460 ML |
137 | rodir -- FAT has the ATTR_RO (read-only) attribute. On Windows, |
138 | the ATTR_RO of the directory will just be ignored, | |
139 | and is used only by applications as a flag (e.g. it's set | |
140 | for the customized folder). | |
dfc209c0 OH |
141 | |
142 | If you want to use ATTR_RO as read-only flag even for | |
143 | the directory, set this option. | |
144 | ||
85c78591 DK |
145 | errors=panic|continue|remount-ro |
146 | -- specify FAT behavior on critical errors: panic, continue | |
147 | without doing anything or remount the partition in | |
148 | read-only mode (default behavior). | |
149 | ||
d65226e2 NJ |
150 | discard -- If set, issues discard/TRIM commands to the block |
151 | device when blocks are freed. This is useful for SSD devices | |
152 | and sparse/thinly-provisoned LUNs. | |
153 | ||
27cf10e1 NJ |
154 | nfs=stale_rw|nostale_ro |
155 | Enable this only if you want to export the FAT filesystem | |
156 | over NFS. | |
157 | ||
158 | stale_rw: This option maintains an index (cache) of directory | |
159 | inodes by i_logstart which is used by the nfs-related code to | |
160 | improve look-ups. Full file operations (read/write) over NFS is | |
161 | supported but with cache eviction at NFS server, this could | |
162 | result in ESTALE issues. | |
163 | ||
164 | nostale_ro: This option bases the inode number and filehandle | |
165 | on the on-disk location of a file in the MS-DOS directory entry. | |
166 | This ensures that ESTALE will not be returned after a file is | |
167 | evicted from the inode cache. However, it means that operations | |
168 | such as rename, create and unlink could cause filehandles that | |
169 | previously pointed at one file to point at a different file, | |
170 | potentially causing data corruption. For this reason, this | |
171 | option also mounts the filesystem readonly. | |
172 | ||
173 | To maintain backward compatibility, '-o nfs' is also accepted, | |
174 | defaulting to stale_rw | |
d65226e2 | 175 | |
190a8843 CM |
176 | dos1xfloppy -- If set, use a fallback default BIOS Parameter Block |
177 | configuration, determined by backing device size. These static | |
178 | parameters match defaults assumed by DOS 1.x for 160 kiB, | |
179 | 180 kiB, 320 kiB, and 360 kiB floppies and floppy images. | |
180 | ||
d65226e2 | 181 | |
1da177e4 LT |
182 | <bool>: 0,1,yes,no,true,false |
183 | ||
28016128 NJ |
184 | LIMITATION |
185 | --------------------------------------------------------------------- | |
186 | * The fallocated region of file is discarded at umount/evict time | |
187 | when using fallocate with FALLOC_FL_KEEP_SIZE. | |
188 | So, User should assume that fallocated region can be discarded at | |
189 | last close if there is memory pressure resulting in eviction of | |
190 | the inode from the memory. As a result, for any dependency on | |
191 | the fallocated region, user should make sure to recheck fallocate | |
192 | after reopening the file. | |
193 | ||
1da177e4 LT |
194 | TODO |
195 | ---------------------------------------------------------------------- | |
196 | * Need to get rid of the raw scanning stuff. Instead, always use | |
197 | a get next directory entry approach. The only thing left that uses | |
198 | raw scanning is the directory renaming code. | |
199 | ||
200 | ||
201 | POSSIBLE PROBLEMS | |
202 | ---------------------------------------------------------------------- | |
203 | * vfat_valid_longname does not properly checked reserved names. | |
204 | * When a volume name is the same as a directory name in the root | |
205 | directory of the filesystem, the directory name sometimes shows | |
206 | up as an empty file. | |
207 | * autoconv option does not work correctly. | |
208 | ||
209 | BUG REPORTS | |
210 | ---------------------------------------------------------------------- | |
211 | If you have trouble with the VFAT filesystem, mail bug reports to | |
212 | chaffee@bmrc.cs.berkeley.edu. Please specify the filename | |
213 | and the operation that gave you trouble. | |
214 | ||
215 | TEST SUITE | |
216 | ---------------------------------------------------------------------- | |
217 | If you plan to make any modifications to the vfat filesystem, please | |
218 | get the test suite that comes with the vfat distribution at | |
219 | ||
0ea6e611 JM |
220 | http://web.archive.org/web/*/http://bmrc.berkeley.edu/ |
221 | people/chaffee/vfat.html | |
1da177e4 LT |
222 | |
223 | This tests quite a few parts of the vfat filesystem and additional | |
224 | tests for new features or untested features would be appreciated. | |
225 | ||
226 | NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM | |
227 | ---------------------------------------------------------------------- | |
228 | (This documentation was provided by Galen C. Hunt <gchunt@cs.rochester.edu> | |
229 | and lightly annotated by Gordon Chaffee). | |
230 | ||
231 | This document presents a very rough, technical overview of my | |
232 | knowledge of the extended FAT file system used in Windows NT 3.5 and | |
233 | Windows 95. I don't guarantee that any of the following is correct, | |
234 | but it appears to be so. | |
235 | ||
236 | The extended FAT file system is almost identical to the FAT | |
237 | file system used in DOS versions up to and including 6.223410239847 | |
238 | :-). The significant change has been the addition of long file names. | |
239 | These names support up to 255 characters including spaces and lower | |
240 | case characters as opposed to the traditional 8.3 short names. | |
241 | ||
242 | Here is the description of the traditional FAT entry in the current | |
243 | Windows 95 filesystem: | |
244 | ||
245 | struct directory { // Short 8.3 names | |
246 | unsigned char name[8]; // file name | |
247 | unsigned char ext[3]; // file extension | |
248 | unsigned char attr; // attribute byte | |
249 | unsigned char lcase; // Case for base and extension | |
250 | unsigned char ctime_ms; // Creation time, milliseconds | |
251 | unsigned char ctime[2]; // Creation time | |
252 | unsigned char cdate[2]; // Creation date | |
253 | unsigned char adate[2]; // Last access date | |
254 | unsigned char reserved[2]; // reserved values (ignored) | |
255 | unsigned char time[2]; // time stamp | |
256 | unsigned char date[2]; // date stamp | |
257 | unsigned char start[2]; // starting cluster number | |
258 | unsigned char size[4]; // size of the file | |
259 | }; | |
260 | ||
261 | The lcase field specifies if the base and/or the extension of an 8.3 | |
262 | name should be capitalized. This field does not seem to be used by | |
263 | Windows 95 but it is used by Windows NT. The case of filenames is not | |
264 | completely compatible from Windows NT to Windows 95. It is not completely | |
265 | compatible in the reverse direction, however. Filenames that fit in | |
266 | the 8.3 namespace and are written on Windows NT to be lowercase will | |
267 | show up as uppercase on Windows 95. | |
268 | ||
269 | Note that the "start" and "size" values are actually little | |
270 | endian integer values. The descriptions of the fields in this | |
271 | structure are public knowledge and can be found elsewhere. | |
272 | ||
273 | With the extended FAT system, Microsoft has inserted extra | |
274 | directory entries for any files with extended names. (Any name which | |
275 | legally fits within the old 8.3 encoding scheme does not have extra | |
276 | entries.) I call these extra entries slots. Basically, a slot is a | |
277 | specially formatted directory entry which holds up to 13 characters of | |
278 | a file's extended name. Think of slots as additional labeling for the | |
279 | directory entry of the file to which they correspond. Microsoft | |
280 | prefers to refer to the 8.3 entry for a file as its alias and the | |
281 | extended slot directory entries as the file name. | |
282 | ||
283 | The C structure for a slot directory entry follows: | |
284 | ||
285 | struct slot { // Up to 13 characters of a long name | |
286 | unsigned char id; // sequence number for slot | |
287 | unsigned char name0_4[10]; // first 5 characters in name | |
288 | unsigned char attr; // attribute byte | |
289 | unsigned char reserved; // always 0 | |
290 | unsigned char alias_checksum; // checksum for 8.3 alias | |
291 | unsigned char name5_10[12]; // 6 more characters in name | |
292 | unsigned char start[2]; // starting cluster number | |
293 | unsigned char name11_12[4]; // last 2 characters in name | |
294 | }; | |
295 | ||
296 | If the layout of the slots looks a little odd, it's only | |
297 | because of Microsoft's efforts to maintain compatibility with old | |
298 | software. The slots must be disguised to prevent old software from | |
299 | panicking. To this end, a number of measures are taken: | |
300 | ||
301 | 1) The attribute byte for a slot directory entry is always set | |
302 | to 0x0f. This corresponds to an old directory entry with | |
303 | attributes of "hidden", "system", "read-only", and "volume | |
304 | label". Most old software will ignore any directory | |
305 | entries with the "volume label" bit set. Real volume label | |
306 | entries don't have the other three bits set. | |
307 | ||
308 | 2) The starting cluster is always set to 0, an impossible | |
309 | value for a DOS file. | |
310 | ||
311 | Because the extended FAT system is backward compatible, it is | |
312 | possible for old software to modify directory entries. Measures must | |
313 | be taken to ensure the validity of slots. An extended FAT system can | |
314 | verify that a slot does in fact belong to an 8.3 directory entry by | |
315 | the following: | |
316 | ||
317 | 1) Positioning. Slots for a file always immediately proceed | |
318 | their corresponding 8.3 directory entry. In addition, each | |
319 | slot has an id which marks its order in the extended file | |
320 | name. Here is a very abbreviated view of an 8.3 directory | |
321 | entry and its corresponding long name slots for the file | |
322 | "My Big File.Extension which is long": | |
323 | ||
324 | <proceeding files...> | |
325 | <slot #3, id = 0x43, characters = "h is long"> | |
965fd296 | 326 | <slot #2, id = 0x02, characters = "xtension whic"> |
1da177e4 LT |
327 | <slot #1, id = 0x01, characters = "My Big File.E"> |
328 | <directory entry, name = "MYBIGFIL.EXT"> | |
329 | ||
330 | Note that the slots are stored from last to first. Slots | |
331 | are numbered from 1 to N. The Nth slot is or'ed with 0x40 | |
332 | to mark it as the last one. | |
333 | ||
334 | 2) Checksum. Each slot has an "alias_checksum" value. The | |
335 | checksum is calculated from the 8.3 name using the | |
336 | following algorithm: | |
337 | ||
338 | for (sum = i = 0; i < 11; i++) { | |
339 | sum = (((sum&1)<<7)|((sum&0xfe)>>1)) + name[i] | |
340 | } | |
341 | ||
342 | 3) If there is free space in the final slot, a Unicode NULL (0x0000) | |
343 | is stored after the final character. After that, all unused | |
344 | characters in the final slot are set to Unicode 0xFFFF. | |
345 | ||
346 | Finally, note that the extended name is stored in Unicode. Each Unicode | |
347 | character takes two bytes. |