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