Merge branch 'for-linus' of git://git.alsa-project.org/alsa-kernel
[pandora-kernel.git] / Documentation / filesystems / vfat.txt
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 ----------------------------------------------------------------------
11 umask=###     -- The permission mask (for files and directories, see umask(1)).
12                  The default is the umask of current process.
13
14 dmask=###     -- The permission mask for the directory.
15                  The default is the umask of current process.
16
17 fmask=###     -- The permission mask for files.
18                  The default is the umask of current process.
19
20 allow_utime=### -- This option controls the permission check of mtime/atime.
21
22                   20 - If current process is in group of file's group ID,
23                        you can change timestamp.
24                    2 - Other users can change timestamp.
25
26                  The default is set from `dmask' option. (If the directory is
27                  writable, utime(2) is also allowed. I.e. ~dmask & 022)
28
29                  Normally utime(2) checks current process is owner of
30                  the file, or it has CAP_FOWNER capability.  But FAT
31                  filesystem doesn't have uid/gid on disk, so normal
32                  check is too unflexible. With this option you can
33                  relax it.
34
35 codepage=###  -- Sets the codepage number for converting to shortname
36                  characters on FAT filesystem.
37                  By default, FAT_DEFAULT_CODEPAGE setting is used.
38
39 iocharset=name -- Character set to use for converting between the
40                  encoding is used for user visible filename and 16 bit
41                  Unicode characters. Long filenames are stored on disk
42                  in Unicode format, but Unix for the most part doesn't
43                  know how to deal with Unicode.
44                  By default, FAT_DEFAULT_IOCHARSET setting is used.
45
46                  There is also an option of doing UTF-8 translations
47                  with the utf8 option.
48
49                  NOTE: "iocharset=utf8" is not recommended. If unsure,
50                  you should consider the following option instead.
51
52 utf8=<bool>   -- UTF-8 is the filesystem safe version of Unicode that
53                  is used by the console.  It can be enabled for the
54                  filesystem with this option. If 'uni_xlate' gets set,
55                  UTF-8 gets disabled.
56
57 uni_xlate=<bool> -- Translate unhandled Unicode characters to special
58                  escaped sequences.  This would let you backup and
59                  restore filenames that are created with any Unicode
60                  characters.  Until Linux supports Unicode for real,
61                  this gives you an alternative.  Without this option,
62                  a '?' is used when no translation is possible.  The
63                  escape character is ':' because it is otherwise
64                  illegal on the vfat filesystem.  The escape sequence
65                  that gets used is ':' and the four digits of hexadecimal
66                  unicode.
67
68 nonumtail=<bool> -- When creating 8.3 aliases, normally the alias will
69                  end in '~1' or tilde followed by some number.  If this
70                  option is set, then if the filename is 
71                  "longfilename.txt" and "longfile.txt" does not
72                  currently exist in the directory, 'longfile.txt' will
73                  be the short alias instead of 'longfi~1.txt'. 
74                   
75 usefree       -- Use the "free clusters" value stored on FSINFO. It'll
76                  be used to determine number of free clusters without
77                  scanning disk. But it's not used by default, because
78                  recent Windows don't update it correctly in some
79                  case. If you are sure the "free clusters" on FSINFO is
80                  correct, by this option you can avoid scanning disk.
81
82 quiet         -- Stops printing certain warning messages.
83
84 check=s|r|n   -- Case sensitivity checking setting.
85                  s: strict, case sensitive
86                  r: relaxed, case insensitive
87                  n: normal, default setting, currently case insensitive
88
89 shortname=lower|win95|winnt|mixed
90               -- Shortname display/create setting.
91                  lower: convert to lowercase for display,
92                         emulate the Windows 95 rule for create.
93                  win95: emulate the Windows 95 rule for display/create.
94                  winnt: emulate the Windows NT rule for display/create.
95                  mixed: emulate the Windows NT rule for display,
96                         emulate the Windows 95 rule for create.
97                  Default setting is `lower'.
98
99 <bool>: 0,1,yes,no,true,false
100
101 TODO
102 ----------------------------------------------------------------------
103 * Need to get rid of the raw scanning stuff.  Instead, always use
104   a get next directory entry approach.  The only thing left that uses
105   raw scanning is the directory renaming code.
106
107
108 POSSIBLE PROBLEMS
109 ----------------------------------------------------------------------
110 * vfat_valid_longname does not properly checked reserved names.
111 * When a volume name is the same as a directory name in the root
112   directory of the filesystem, the directory name sometimes shows
113   up as an empty file.
114 * autoconv option does not work correctly.
115
116 BUG REPORTS
117 ----------------------------------------------------------------------
118 If you have trouble with the VFAT filesystem, mail bug reports to
119 chaffee@bmrc.cs.berkeley.edu.  Please specify the filename
120 and the operation that gave you trouble.
121
122 TEST SUITE
123 ----------------------------------------------------------------------
124 If you plan to make any modifications to the vfat filesystem, please
125 get the test suite that comes with the vfat distribution at
126
127   http://bmrc.berkeley.edu/people/chaffee/vfat.html
128
129 This tests quite a few parts of the vfat filesystem and additional
130 tests for new features or untested features would be appreciated.
131
132 NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM
133 ----------------------------------------------------------------------
134 (This documentation was provided by Galen C. Hunt <gchunt@cs.rochester.edu>
135  and lightly annotated by Gordon Chaffee).
136
137 This document presents a very rough, technical overview of my
138 knowledge of the extended FAT file system used in Windows NT 3.5 and
139 Windows 95.  I don't guarantee that any of the following is correct,
140 but it appears to be so.
141
142 The extended FAT file system is almost identical to the FAT
143 file system used in DOS versions up to and including 6.223410239847
144 :-).  The significant change has been the addition of long file names.
145 These names support up to 255 characters including spaces and lower
146 case characters as opposed to the traditional 8.3 short names.
147
148 Here is the description of the traditional FAT entry in the current
149 Windows 95 filesystem:
150
151         struct directory { // Short 8.3 names 
152                 unsigned char name[8];          // file name 
153                 unsigned char ext[3];           // file extension 
154                 unsigned char attr;             // attribute byte 
155                 unsigned char lcase;            // Case for base and extension
156                 unsigned char ctime_ms;         // Creation time, milliseconds
157                 unsigned char ctime[2];         // Creation time
158                 unsigned char cdate[2];         // Creation date
159                 unsigned char adate[2];         // Last access date
160                 unsigned char reserved[2];      // reserved values (ignored) 
161                 unsigned char time[2];          // time stamp 
162                 unsigned char date[2];          // date stamp 
163                 unsigned char start[2];         // starting cluster number 
164                 unsigned char size[4];          // size of the file 
165         };
166
167 The lcase field specifies if the base and/or the extension of an 8.3
168 name should be capitalized.  This field does not seem to be used by
169 Windows 95 but it is used by Windows NT.  The case of filenames is not
170 completely compatible from Windows NT to Windows 95.  It is not completely
171 compatible in the reverse direction, however.  Filenames that fit in
172 the 8.3 namespace and are written on Windows NT to be lowercase will
173 show up as uppercase on Windows 95.
174
175 Note that the "start" and "size" values are actually little
176 endian integer values.  The descriptions of the fields in this
177 structure are public knowledge and can be found elsewhere.
178
179 With the extended FAT system, Microsoft has inserted extra
180 directory entries for any files with extended names.  (Any name which
181 legally fits within the old 8.3 encoding scheme does not have extra
182 entries.)  I call these extra entries slots.  Basically, a slot is a
183 specially formatted directory entry which holds up to 13 characters of
184 a file's extended name.  Think of slots as additional labeling for the
185 directory entry of the file to which they correspond.  Microsoft
186 prefers to refer to the 8.3 entry for a file as its alias and the
187 extended slot directory entries as the file name. 
188
189 The C structure for a slot directory entry follows:
190
191         struct slot { // Up to 13 characters of a long name 
192                 unsigned char id;               // sequence number for slot 
193                 unsigned char name0_4[10];      // first 5 characters in name 
194                 unsigned char attr;             // attribute byte
195                 unsigned char reserved;         // always 0 
196                 unsigned char alias_checksum;   // checksum for 8.3 alias 
197                 unsigned char name5_10[12];     // 6 more characters in name
198                 unsigned char start[2];         // starting cluster number
199                 unsigned char name11_12[4];     // last 2 characters in name
200         };
201
202 If the layout of the slots looks a little odd, it's only
203 because of Microsoft's efforts to maintain compatibility with old
204 software.  The slots must be disguised to prevent old software from
205 panicking.  To this end, a number of measures are taken:
206
207         1) The attribute byte for a slot directory entry is always set
208            to 0x0f.  This corresponds to an old directory entry with
209            attributes of "hidden", "system", "read-only", and "volume
210            label".  Most old software will ignore any directory
211            entries with the "volume label" bit set.  Real volume label
212            entries don't have the other three bits set.
213
214         2) The starting cluster is always set to 0, an impossible
215            value for a DOS file.
216
217 Because the extended FAT system is backward compatible, it is
218 possible for old software to modify directory entries.  Measures must
219 be taken to ensure the validity of slots.  An extended FAT system can
220 verify that a slot does in fact belong to an 8.3 directory entry by
221 the following:
222
223         1) Positioning.  Slots for a file always immediately proceed
224            their corresponding 8.3 directory entry.  In addition, each
225            slot has an id which marks its order in the extended file
226            name.  Here is a very abbreviated view of an 8.3 directory
227            entry and its corresponding long name slots for the file
228            "My Big File.Extension which is long":
229
230                 <proceeding files...>
231                 <slot #3, id = 0x43, characters = "h is long">
232                 <slot #2, id = 0x02, characters = "xtension whic">
233                 <slot #1, id = 0x01, characters = "My Big File.E">
234                 <directory entry, name = "MYBIGFIL.EXT">
235
236            Note that the slots are stored from last to first.  Slots
237            are numbered from 1 to N.  The Nth slot is or'ed with 0x40
238            to mark it as the last one.
239
240         2) Checksum.  Each slot has an "alias_checksum" value.  The
241            checksum is calculated from the 8.3 name using the
242            following algorithm:
243
244                 for (sum = i = 0; i < 11; i++) {
245                         sum = (((sum&1)<<7)|((sum&0xfe)>>1)) + name[i]
246                 }
247
248         3) If there is free space in the final slot, a Unicode NULL (0x0000) 
249            is stored after the final character.  After that, all unused 
250            characters in the final slot are set to Unicode 0xFFFF.
251
252 Finally, note that the extended name is stored in Unicode.  Each Unicode
253 character takes two bytes.