File System: Archives

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.

• Worksheet for Calculating the Save Data File System Capacity

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. Note that the nn::fs::FileStream::TrySetSize function and similar functions cannot enlarge 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 using the nn::fs::FileStream::TryInitialize function, which does not have a size specification.

Because metadata is added to each file in the expanded save data as the file is created, the actual file is larger than the size of the original data. Use this sheet to determine how much space is actually used when a file is created.

• Worksheet for Calculating the Save Data File System Capacity

Because expanded save data has the following characteristics, there are many errors related to it that must be handled.

• Its content can be modified by other applications. (Normal operation will also cause it to change.）
• Users can use PCs or other devices to tamper with the SD Card data.
• The SD Card might be removed while it is being accessed.

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 the ctr_makerom reference.

An HIO archive recognizes the contents of the directory on the PC specified by the hostPath argument as a single archive. This archive can only be used 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.

	R/W	Changing Sizes	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 Archives	R/W	Impossible	nn::fs::TryCreateFile 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 (See Note 1)	Case-sensitive	Forbidden characters
ROM Archives	-	253 characters	Yes	(See Note 3)
Save Data Archives	16 characters	253 characters	Yes	(See Note 2 and Note 3)
Expanded Save Data Archives	16 characters	248 characters	Yes	(See Note 2 and Note 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.
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.
Note 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 Note 2.
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

In addition to the characters and names that cannot be used for files and directories, "$" cannot be used at the start of an archive name. The reason is that it is used when a CTR_SDK internal library is mounting an archive internally. We recommend not using it in order to prevent archive names being overlapped.

In SDMC archives, any single-byte spaces specified at the start and/or end of entry names (file names and directory names) are deleted.
To simplify debugging and to avoid unnecessary bugs, we recommend that you refrain from using single-byte spaces at the beginning and end of entry names in other archives as well.

Specified entry name	Actual entry name on which operations are performed (only for SDMC archives)
EntryName	EntryName
_EntryName	EntryName
__EntryName	EntryName
Entry_Name	Entry_Name
EntryName_	EntryName
_Entry_Name_	Entry_Name

※ Note: "_" indicates a single-byte space.