Use the format "<archive name>:<archive path>" to specify the 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 the nn::fs::Unmount function.
ROM archives are read-only archives for referencing the ROMFS created at build time. When ROM archives are used, they require a working memory region to be passed by the user application. You must therefore pass a working memory region as an argument when you call the nn::fs::MountRom function. The number of files and the number of directories that can be opened in a ROM archive are passed as arguments to the nn::fs::MountRom function, and the only restriction on these numbers is the amount of available memory. Pass no more than the required numbers as 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 (or 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 automatically duplicate data in save data archives. This automatic redundancy prevents data loss due to corruption. However, using automatic redundancy reduces the amount of actual writable data in the save data archive to roughly 40% of the total save data region size.
Use the following worksheet to determine the amount of data that can actually be written in a save data archive.
Note that save data is managed in fixed-size chunks of 512 bytes. As a result, creating a 1-byte file will still consume 512 bytes.
Expanded save data archives are data regions that are managed separately from save data. These archives are created on the SD Card. To use an expanded save data archive, the application must explicitly create one.
Note: One characteristic of files created in expanded save data memory is that the size of these files cannot be changed. Be aware that the nn::fs::FileStream::TrySetSize function and similar functions cannot increase the size of these files.
Use the nn::fs::TryCreateFile function, which can specify file size, to create such files. You will get an error if you try creating such files with a function like nn::fs::FileStream::TryInitialize, which does not have a size specification.
Because metadata is added to expanded save data for each file that is created, the actual file size is larger than the data size. Use this sheet to determine how much space is actually used when a file is created.
Because expanded save data has the following characteristics, there are many errors related to it that must be handled.
These possibilities cannot be prevented by any actions during development. You must implement solid and reliable error handling while keeping these possibilities in mind.
SDMC archives are for directly referencing SD Cards for debugging purposes. Mount the inserted SD Card using the nn::fs::MountSdmc function. When a mounted SD Card is removed and re-inserted, you must unmount it using the nn::fs::Unmount function and then call the nn::fs::MountSdmc function again to re-mount it.
Note: SDMC archives are only for debugging and cannot be accessed from retail versions.
To use this archive, you must add the "- Debug" attribute to the file system access permissions in your RSF file. For details, see ctr_makerom.
An HIO archive recognizes the contents of a specific directory (on the PC specified by the hostPath argument) as a single archive. These archives can be used only for debugging purposes.
Note: HIO archives are only for debugging and cannot be accessed from retail versions.
The Result values returned by HIO archives may not always match those of other archives. Also, their behavior could differ depending on the version of the SDK or the debugger software. Consider these only as an auxiliary feature when debugging.
All archive types entail the following limitations.
| R/W | Changing Sizes | Creation | Opening Multiple Instances | |
|---|---|---|---|---|
| ROM Archives | R | Impossible | Impossible | Only when all read-only |
| Save Data Archives | R/W | Possible | FileStreamFileOutputStreamnn::fs::TryCreateFile | Only when all read-only |
| Expanded Save Data Archives | R/W | Impossible | nn::fs::TryCreateFile only | Only when all read-only |
| SDMC Archives | R/W | Possible | FileStreamFileOutputStreamnn::fs::TryCreateFile | Possible |
| HIO Archives | R/W | Possible | FileStreamFileOutputStreamnn::fs::TryCreateFile | (Operation not guaranteed) |
| Filename Length | Path Length (See Note 1) | Case-sensitive | Forbidden characters | |
|---|---|---|---|---|
| ROM Archives | - | 253 characters | Yes | （※3） |
| Save Data Archives | 16 characters | 253 characters | Yes | （※2）（※3） |
| Expanded Save Data Archives | 16 characters | 248 characters | Yes | （※2）（※3） |
| SDMC Archives | 253 characters (See Note 4) | 253 characters (See Note 4) | No | （※3） |
| HIO Archives | Comply with host PC restrictions | |||
Note 1: Not including archive names.
（※2） Note 2: Although using a symbol other than "/" in a pathname does not result in an error, operations are not guaranteed when a pathname includes any of the unusable characters or names given later.
*3: Although the Function Reference Manual for CTR-SDK 0.14 and earlier had a section called Usable Characters for VFAT, actual specifications are as described above in *2, above.
Note 4: This is restricted to 251 characters only when a directory is opened.
\ / : * ? " < > |
CON, PRN, NUL, AUX, LPT1, LPT2, LPT3, LPT4, COM1, COM2, COM3, COM4
con, prn, nul, aux, lpt1, lpt2, lpt3, lpt4, com1, com2, com3, com4
, ; = + [ ] and single-byte space from the list of unusable characters.CONFIDENTIAL