Use the format "<archive name>:<archive path>" to specify path name for file and directory operations. For archives with a hierarchical directory structure, slashes ("/") are used as the directory delimiter.
Archives must be mounted before they can be accessed. Each archive type has its own mount function, and the arguments of those functions differ. You specify an archive name when mounting an archive, and then you can then access that archive using a path that begins with the archive name. Once you no longer need the archive, you can unmount it by calling nn::fs::Unmount function.
A ROM archive is a read-only archive used to access a ROMFS created at build time. When ROM archives are used, they require a working memory region to be passed by the user application. These archives therefore require that a working memory region be passed as an argument when calling the nn::fs::MountRom function. The number of files and the number of directories that can be opened in ROM archives are passed as arguments to the nn::fs::MountRom function, and the only restriction on these numbers is the amount of available memory. We recommend passing the required number for arguments to the nn::fs::MountRom function.
You can also choose whether to cache metadata such as the ROM filenames and directory names. If you enable caching, a larger working region will be required, but your application will be able to open files and work with directories more quickly.
Save data archives are for referencing program-specific save data regions. For programs launched from a CTR card (emulation memory during development), these archives access backup memory on the CTR card. For programs launched from NAND memory, these archives access save data created in NAND memory.
Save data archives use a file system with a hierarchical directory structure, so they support the same types of file and directory operations that typical file systems do.
Although the nn::fs::MountSaveData function is used to mount save data archives, you must format the save data region with the nn::fs::FormatSaveData function before you use save data for the first time. When you format a save data region, you can specify the maximum number of files and directories that can be created in it.
You can also decide whether to duplicate data in a save data archive as a means of preventing data loss due to corruption. However, using data duplication reduces the amount of actual writable data in the save data archive to 40% of the total save data region size.
Expanded save data archives are archives created on an SD Card where the data memory region is managed separately from save data. In order to use an extended save data archive, the application must explicitly create one.
SDMC archives are for directly referencing SD Cards for debugging purposes. An inserted SD Card can be mounted using the nn::fs::MountSdmc function. To mount a previously mounted SD Card that has been pulled out and then re-inserted, you must first unmount the card using the nn::fs::Unmount function, then call the nn::fs::MountSdmc function again.
Note that SDMC archives are generally only for debugging and cannot be accessed from retail versions.
An HIO archive recognizes the contents of a specific directory (on the PC specified by the hostPath argument) as a single archive. This feature is provided only for debugging purposes.
HIO archives are only for debugging and cannot be accessed from retail versions. The Result values returned by the HIO archive may not always match those of other archives. Also, behavior could differ depending on the SDK version. Consider this only as an auxiliary feature when debugging.
All archive types entail the following limitations.
| R/W | Changing the Size of Docking Windows | Creation | Opening Multiple Instances | |
|---|---|---|---|---|
| ROM Archives | R | Impossible | Impossible | Only when all read-only |
| Save Data Archives | R/W | Possible | FileStream FileOutputStream nn::fs::TryCreateFile | Only when all read-only |
| Expanded Save Data Archive | R/W | Impossible | nn::fs::TryCreateFile Function only | Only when all read-only |
| SDMC Archives | R/W | Possible | FileStream FileOutputStream nn::fs::TryCreateFile | Possible |
| HIO Archives | R/W | Possible | FileStream FileOutputStream nn::fs::TryCreateFile | (Operation not guaranteed) |
| Filename Length | Path Length (*1) | Case-sensitive | Forbidden characters | |
|---|---|---|---|---|
| ROM Archives | - | 253 characters | Yes | （※3） |
| Save Data Archives | 16 characters | 253 characters | Yes | （※2）（※3） |
| Expanded Save Data Archive | 16 characters | 248 characters | Yes | （※2）（※3） |
| SDMC Archives | According to VFAT limitations | 253 characters | No | （※3） |
| HIO Archives | According to host PC limitations | |||
*1: Not including archive names.
（※2） No error will occur if symbols other than "/" are included in the path. But if any of the following characters or names is included in a file name or directory name, operation is not guaranteed.
（※3） Although the Function Reference Manual for CTR-SDK 0.14 and earlier had a section called Usable Characters for VFAT, note that if any of the following characters or names is included in a file name or directory name, operation is not guaranteed.
\ / : * ? " < > | , ; = + [ ] and single-byte spaces
CON, PRN, NUL, AUX, LPT1, LPT2, LPT3, LPT4, COM1, COM2, COM3, COM4
con, prn, nul, aux, lpt1, lpt2, lpt3, lpt4, com1, com2, com3, com4
CONFIDENTIAL