# FatFs - Path Names

# Path Names

### Format of the path names

The path name format on the FatFs module is similer to the filename specs of DOS/Windos as follows:

`"[drive#:][/]directory/file"`

The FatFs module supports long file name (LFN) and 8.3 format file name (SFN). The LFN can be used when LFN feature is enabled `(_USE_LFN > 0)`. 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 the drive number is omitted, it is assumed as default drive (0 or current drive).

Control characters (\0 to \x1F) are recognized as end of the path name. Leading/embedded spaces in the path name are valid as a part of the name on LFN configuration but they are recognized as end of the path name on non-LFN configuration. Trailing spaces and dots are ignored.

In default configuration `(_FS_RPATH == 0)`, 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 are not allowed. Heading separator is ignored and it can be exist or omitted. The default drive number is fixed to 0.

When relative path feature is enabled `(_FS_RPATH == 1)`, specified path is followed from the root directory if a heading separator is exist. If not, it is followed from the current directory set with f_chdir function. Dot names are also allowed for the path name. The default drive is the current drive set with f_chdrive function.

Path name | _FS_RPATH == 0 | _FS_RPATH == 1
file.txt | A file in the root directory of the drive 0 | A file in the current directory of the current drive
/file.txt | A file in the root directory of the drive 0 | A file in the root directory of the current drive
| The root directory of the drive 0 | The current directory of the current drive
/ | The root directory of the drive 0 | The root directory of the current drive
2: | The root directory of the drive 2 | The current directory of the drive 2
2:/ | The root directory of the drive 2 | The root directory of the drive 2
2:file.txt | A file in the root directory of the drive 2 | A file in the current directory of the drive 2
../file.txt | Invalid name | A file in the parent directory
. | Invalid name | This directory
.. | Invalid name | Parent directory of the current directory
dir1/.. | Invalid name | The current directory
/.. | Invalid name | The root directory (sticks the top level)

### Unicode API

The path names are input/output in either ANSI/OEM code (SBCS/DBCS) or Unicode depends on the configuration options. The type of arguments that specifies the file names are defined as `TCHAR` which is an alias of `char` in default. The code set of the file name string is the ANSI/OEM code set specifid by `_CODE_PAGE`. When `_LFN_UNICODE` is set to 1 under LFN configuration, the type of the `TCHAR` is switched to `unsigned short` (UCS-2 character) to support Unicode. In this case, the LFN feature is fully 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, `_T(s)` and `_TEXT(s)` macro are available to select either ANSI/OEM or Unicode automatically. The code shown below is an example to define the literal strings.

     f_open(fp, "filename.txt", FA_READ);      /* ANSI/OEM only */
     f_open(fp, L"filename.txt", FA_READ);     /* Unicode only */
     f_open(fp, _T("filename.txt"), FA_READ);  /* Changed automatically */

### Correspondence between logical and physical drives

The FatFs module has work areas that called file system object for each volume (logical drive). In default, each logical drive is bound to the physical drive that has same drive number. It attempts to mount a volume as SFD format and first FDISK partition. When `_MULTI_PARTITION >= 1` is specified in configuration option, each individual logical drive is bound to any physical drive/partition. In this case, a volume management table must be defined by user. It is used to resolve relationship between logical drives and partitions as follows:

    Example: Logical drive 0-2 are assigned to three pri-partitions on the physical drive 0 (fixed disk)
             Logical drive 3 is assigned to physical drive 1 (removable disk)

    PARTITION VolToPart[] = {
        {0, 1},     /* Logical drive 0 ==> Physical drive 0, 1st partition */
        {0, 2},     /* Logical drive 1 ==> Physical drive 0, 2nd partition */
        {0, 3},     /* Logical drive 2 ==> Physical drive 0, 3rd partition */
        {1, 0}      /* Logical drive 3 ==> Physical drive 1 (auto detection) */
    };

There are some considerations when use `_MULTI_PARTITION` configuration.

- Only four pri-partitions can be mounted. Extended partition is not supported.
- The physical drive that has two or more partitions must be non-removable class.