projects / z180-stamp.git / blame
| Commit | Line | Data |
|---|---|---|
| 53668523 L |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r |
| 2 | <html lang="en">\r | |
| 3 | <head>\r | |
| 4 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8">\r | |
| 5 | <meta http-equiv="Content-Style-Type" content="text/css">\r | |
| 6 | <link rel="up" title="FatFs" href="../00index_e.html">\r | |
| 7 | <link rel="alternate" hreflang="ja" title="Japanese" href="../ja/filename.html">\r | |
| 8 | <link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">\r | |
| 9 | <title>FatFs - Path Names</title>\r | |
| 10 | </head>\r | |
| 11 | \r | |
| 12 | <body>\r | |
| 13 | <h1>Path Names</h1>\r | |
| 14 | \r | |
| 70702af1 | 15 | <div class="para doc" id="nam">\r |
| 53668523 L |
16 | <h3>Format of the path names</h3>\r |
| 17 | <p>The format of path name on the FatFs module is similer to the filename specs of DOS/Windos as follows:</p>\r | |
| 18 | <pre>"[<em>drive</em>:][/]<em>directory</em>/<em>file</em>"</pre>\r | |
| 70702af1 | 19 | <p>The FatFs module supports long file name (LFN) and 8.3 format file name (SFN). The LFN can be used when (<tt><a href="config.html#use_lfn">_USE_LFN</a> != 0</tt>). The sub directories are separated with a \ or / in the same way as DOS/Windows API. Duplicated separators are skipped and ignored. Only a difference is that the logical drive is specified in a numeral with a colon. When drive number is omitted, the drive number is assumed as <em>default drive</em> (drive 0 or current drive).</p>\r |
| 7b78a5a2 | 20 | <p>Control characters (<tt>'\0'</tt> to <tt>'\x1F'</tt>) are recognized as end of the path name. Leading/embedded spaces in the path name are valid as a part of the name at LFN configuration but the space is recognized as end of the path name at non-LFN configuration. Trailing spaces and dots are ignored at both configurations.</p>\r |
| 70702af1 L |
21 | <p>In default configuration (<tt><a href="config.html#fs_rpath">_FS_RPATH</a> == 0</tt>), it does not have a concept of current directory like OS oriented file system. All objects on the volume are always specified in full path name that follows from the root directory. Dot directory names (<tt>".", ".."</tt>) are not allowed. Heading separator is ignored and it can be exist or omitted. The default drive is fixed to drive 0.</p>\r |
| 22 | <p>When relative path is enabled (<tt>_FS_RPATH >= 1</tt>), specified path is followed from the root directory if a heading separator is exist. If not, it is followed from the current directory of the drive set by <a href="chdir.html">f_chdir</a> function. Dot names are also allowed for the path names. The default drive is the current drive set by <a href="chdrive.html">f_chdrive</a> function.</p>\r | |
| 53668523 | 23 | <table class="lst2">\r |
| 70702af1 | 24 | <tr><td>Path name</td><td>_FS_RPATH == 0</td><td>_FS_RPATH >= 1</td></tr>\r |
| 53668523 L |
25 | <tr class="lst3"><td>file.txt</td><td>A file in the root directory of the drive 0</td><td>A file in the current directory of the current drive</td></tr>\r |
| 26 | <tr><td>/file.txt</td><td>A file in the root directory of the drive 0</td><td>A file in the root directory of the current drive</td></tr>\r | |
| 27 | <tr><td></td><td>The root directory of the drive 0</td><td>The current directory of the current drive</td></tr>\r | |
| 28 | <tr><td>/</td><td>The root directory of the drive 0</td><td>The root directory of the current drive</td></tr>\r | |
| 29 | <tr><td>2:</td><td>The root directory of the drive 2</td><td>The current directory of the drive 2</td></tr>\r | |
| 30 | <tr><td>2:/</td><td>The root directory of the drive 2</td><td>The root directory of the drive 2</td></tr>\r | |
| 31 | <tr><td>2:file.txt</td><td>A file in the root directory of the drive 2</td><td>A file in the current directory of the drive 2</td></tr>\r | |
| 32 | <tr><td>../file.txt</td><td>Invalid name</td><td>A file in the parent directory</td></tr>\r | |
| 33 | <tr><td>.</td><td>Invalid name</td><td>This directory</td></tr>\r | |
| 70702af1 | 34 | <tr><td>..</td><td>Invalid name</td><td>Parent directory of the current directory (*)</td></tr>\r |
| 53668523 L |
35 | <tr><td>dir1/..</td><td>Invalid name</td><td>The current directory</td></tr>\r |
| 36 | <tr><td>/..</td><td>Invalid name</td><td>The root directory (sticks the top level)</td></tr>\r | |
| 37 | </table>\r | |
| 70702af1 L |
38 | <p>When option <tt><a href="config.html#str_volume_id">_STR_VOLUME_ID</a></tt> is specified, also pre-defined strings can be used as drive identifier in the path name instead of a numeral. e.g. <tt>"sd:file1.txt"</tt>, <tt>"ram:swapfile.dat"</tt> and DOS/Windows style drive letter, of course.</p>\r |
| 39 | <p><em>Remark: In this revision, double dot name <tt>".."</tt> cannot follow the parent directory on the exFAT volume. It will work as <tt>"."</tt> and stay there.</em></p>\r | |
| 53668523 L |
40 | </div>\r |
| 41 | \r | |
| 70702af1 L |
42 | <div class="para doc" id="case">\r |
| 43 | <h3>Legal Characters and Case Sensitivity</h3>\r | |
| 44 | <p>On the FAT file system, legal characters for file name are, <tt>0-9 A-Z ! # $ % & ' ( ) - @ ^ _ ` { } ~</tt> and extended characters (<tt>\x80</tt>-<tt>\xFF</tt>). Under LFN supported system, also white space and <tt>+ , ; = [ ]</tt> are legal for the file name and the white spaces and periods can be placed anywhere in the name except for end of the name string.</p>\r | |
| 45 | <p>FAT file system is case-insensitive to the object names on the volume. All object names are compared in case-insensitive. For example, these three names, <tt>file.txt</tt>, <tt>File.Txt</tt> and <tt>FILE.TXT</tt>, are identical. This is applied to also extended charactres. When an object is created on the FAT volume, upper converted name is recorded to the SFN entry, and the raw name is recorded to the LFN entry.</p>\r | |
| 46 | <p>As for the DBCS language MS-DOS, it was case-sensitive to the extended characters. To follow this specification, FatFs works with case-sensitive to the extended characters at only non-LFN with DBCS configuration (DOS/DBCS specs). But at LFN configuration, FatFs works with case-insensitive to all characters (WindowsNT specs). This can cause a problem on compatibility with Windows system when an object with extended characters is created on the volume at non-LFN and DBCS configuration; therfore the object names with DBCS extended characters should not be used on the FAT volume shared by those systems.</p>\r | |
| 47 | </div>\r | |
| 48 | \r | |
| 49 | <div class="para doc" id="uni">\r | |
| 53668523 | 50 | <h3>Unicode API</h3>\r |
| 70702af1 | 51 | <p>The path names are input/output in either ANSI/OEM code or Unicode depends on the configuration options. The type of arguments which specify the path names are defined as <tt>TCHAR</tt>. It is an alias of <tt>char</tt> by default. The code set used to the path name string is ANSI/OEM specifid by <tt><a href="config.html#code_page">_CODE_PAGE</a></tt>. When <tt><a href="config.html#lfn_unicode">_LFN_UNICODE</a></tt> is set to 1, the type of the <tt>TCHAR</tt> is switched to <tt>WCHAR</tt> to support Unicode (UTF-16 encoding). In this case, the full-featured LFN specification is supported and the Unicode specific characters, such as ✝☪✡☸☭, can also be used for the path name. It also affects data types and encoding of the string I/O functions. To define literal strings, <tt>_T(s)</tt> and <tt>_TEXT(s)</tt> macro are available to select either ANSI/OEM or Unicode automatically. The code shown below is an example to define the literal strings.</p>\r |
| 53668523 L |
52 | <pre>\r |
| 53 | f_open(fp, "filename.txt", FA_READ); <span class="c">/* ANSI/OEM string */</span>\r | |
| 54 | f_open(fp, L"filename.txt", FA_READ); <span class="c">/* Unicode string */</span>\r | |
| 55 | f_open(fp, _T("filename.txt"), FA_READ); <span class="c">/* Changed by configuration */</span>\r | |
| 56 | </pre>\r | |
| 57 | </div>\r | |
| 58 | \r | |
| 70702af1 | 59 | <div class="para doc" id="vol">\r |
| 53668523 | 60 | <h3>Volume Management</h3>\r |
| 70702af1 L |
61 | <p>FatFs module needs dynamic work area, <em>file system object</em>, for each volume (logical drive). It is registered/unregistered to the FatFs module by <tt>f_mount</tt> function. By default, each logical drive is bound to the physical drive with the same drive number and an FAT volume on the drive is serched by the volume mount process. It reads boot sectors and checks it if it is an FAT boot sector in order of sector 0 as SFD format, 1st partition, 2nd partition, 3rd partition and 4th partition as FDISK format.</p>\r |
| 62 | <p>When <tt><a href="config.html#multi_partition">_MULTI_PARTITION</a> == 1</tt> is specified by configuration option, each individual logical drive is bound to the partition on the physical drive specified by volume management table. The volume management table must be defined by user to resolve the relationship between logical drives and partitions. Following code is an example of a volume management table.</p>\r | |
| 53668523 | 63 | <pre>\r |
| 70702af1 L |
64 | Example: Logical drive 0-2 are tied to three pri-partitions on the physical drive 0 (fixed drive)\r |
| 65 | Logical drive 3 is tied to an FAT volume on the physical drive 1 (removable drive)\r | |
| 53668523 L |
66 | \r |
| 67 | PARTITION VolToPart[] = {\r | |
| 70702af1 L |
68 | {0, 1}, <span class="c">/* "0:" ==> Physical drive 0, 1st partition */</span>\r |
| 69 | {0, 2}, <span class="c">/* "1:" ==> Physical drive 0, 2nd partition */</span>\r | |
| 70 | {0, 3}, <span class="c">/* "2:" ==> Physical drive 0, 3rd partition */</span>\r | |
| 71 | {1, 0} <span class="c">/* "3:" ==> Physical drive 1, auto detection */</span>\r | |
| 53668523 | 72 | };\r |
| 53668523 | 73 | </pre>\r |
| 70702af1 L |
74 | <div><img src="../res/f7.png" width="828" height="288" alt="relationship between logical drive and physical drive"></div>\r |
| 75 | <p>There are some considerations on using multi-partition configuration.</p>\r | |
| 53668523 | 76 | <ul>\r |
| 53668523 | 77 | <li>The physical drive that has two or more mounted partitions must be non-removable. Media change while a system operation is prohibited.</li>\r |
| 7b78a5a2 | 78 | <li>Only four primary partitions can be specified. Extended partition is not supported.</li>\r |
| 70702af1 | 79 | <li>Windows does not support multiple volumes on the removable storage. Only first parition will be recognized.</li>\r |
| 53668523 L |
80 | </ul>\r |
| 81 | </div>\r | |
| 82 | \r | |
| 70702af1 | 83 | <p class="foot"><a href="../00index_e.html">Return</a></p>\r |
| 53668523 L |
84 | </body>\r |
| 85 | </html>\r |