1<?xml version="1.0" encoding="utf-8"?> 2<html xml:lang="en-US" lang="en-US"> 3<head> 4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 5 <meta http-equiv="Content-Style-Type" content="text/css" /> 6 <link rel="stylesheet" href="../../../css/page.css" type="text/css" /> 7<title>File System: Archives</title> 8</head> 9<body> 10<h1>File System: Archives</h1> 11 12<h2>Table of Contents</h2> 13 <ul> 14<li><a href="#Summary">Overview</a></li> 15 <ul> 16<li><a href="#Summary_Usage">Using Archives</a></li> 17<li><a href="#Summary_Application">Program Archive Configuration</a></li> 18<li><a href="#Summary_Targets">Purpose</a></li> 19 </ul> 20<li><a href="#Archives">Detailed Information on Archives</a></li> 21 <ul> 22<li><a href="#Archives_RomArchive">ROM Archives</a></li> 23<li><a href="#Archives_SaveDataArchive">Save Data Archives</a></li> 24<li><a href="#Archives_SaveDataArchive_Other">Save Data Archives (Other Programs)</a></li> 25<li><a href="#Archives_ExtSaveDataArchive">Expanded Save Data Archives</a></li> 26<li><a href="#Archives_SdmcArchive">SDMC Archives</a></li> 27<li><a href="#Archives_SdmcWriteOnlyArchive">Write-only SDMC Archives</a></li> 28<li><a href="#Archives_HioArchive">HIO Archives</a></li> 29 </ul> 30<li><a href="#Restrictions">Archive Limitations</a></li> 31 <ul> 32<li><a href="#Restrictions_OperatingFile">File Operations</a></li> 33<li><a href="#Restrictions_Charactors">Character Restrictions</a></li> 34<li><a href="#Restrictions_InvalidCharactors">Unusable Characters in File and Directory Names</a></li> 35<li><a href="#Restrictions_InvalidName">Unusable File and Directory Names</a></li> 36<li><a href="#Restrictions_InvalidArchiveName">Characters Prohibited for Use in Archive Names</a></li> 37<li><a href="#Restrictions_HalfSizeSpace">Single-byte Spaces in File and Directory Names</a></li> 38 </ul> 39<li><a href="#History">Revision History</a></li> 40 </ul> 41 42<a name="Summary"><h2>Overview</h2></a> 43 <div class="section"> 44 <p> 45The CTR file system is a group of archives. Archives contain files and directories, and provide a means of accessing those files and directories. 46 </p> 47 48<a name="Summary_Usage"><h3>Accessing Files</h3></a> 49 <div class="section"> 50 <p> 51The main steps for accessing files or directories using an archive are given below. 52 </p> 53 <p> 54 <ol> 55<li>Creating/formatting the archive (if necessary)</li> 56<li>Mounting the archive</li> 57 <li> 58Accessing files and directories (any number of times) 59 <ol> 60<li>Creating files and directories (if necessary)</li> 61<li>Opening files and directories</li> 62<li>Manipulating file and directories</li> 63<li>Closing files and directories</li> 64 </ol> 65 </li> 66<li>Unmounting the archive</li> 67 </ol> 68 </p> 69 <p> 70 71 </p> 72 <p> 73To access a file or directory, you must first mount an archive that has been created and formatted. <dfn>Mounting</dfn> refers to the act of checking the status of the archive specified by the user, securing required resources such as memory, preparing resources for use, and applying an archive name to the archive. A function specific to each type of archive must be called in order to mount a given archive. These functions have different arguments depending on the archive type, but share a common argument that represents the archive name. The <dfn>archive name</dfn> is used to specify a mounted archive by a name given to that archive. An archive name is made up of an ASCII character string of one to seven characters in length, but must not contain a colon (":"). Also, a dollar sign ("$") may not be used to start an archive name. 74 </p> 75 <p> 76To open a file or directory, use an access class such as <a href="../../../nn/fs/FileStream/Overview.html"><CODE>FileStream</CODE></a>. Note that a path name must be specified in the initial argument to such classes. A <dfn>path name</dfn> is a character string of the form "<var><archive_name></var>:<var><archive_path></var>". The file position inside the archive specified by archive_name is determined based on archive_path. Many archives support a hierarchical directory structure, where directories are delimited by slashes ('/'). 77 </p> 78 <p> 79Archives must be unmounted when you are finished using them. <dfn>Unmount</dfn> allows system resources being used to maintain the mounted status of an archive to be freed. To unmount an archive, first close all files and directories in the archive in question and call the <a href="../../../nn/fs/Unmount.html"><CODE>nn::fs::Unmount</CODE></a> function, passing the archive name as an argument. From that point forward, the archive cannot be accessed, even if an attempt is made to access it by archive name. 80 </p> 81 <p> 82Mounted status is disabled for archives located on removable media, such as an SD Card, when the media is removed. A <a href="../../../nn/fs/ResultArchiveInvalidated/Overview.html"><CODE>ResultArchiveInvalidated</CODE></a> type result is returned in response to attempts to access a disabled archive or file within it. To access the archive again, you must first unmount the disabled archive and then call a function for mounting it again. 83 </p> 84 </div> 85 86<a name="Summary_Application"><h3>Program Archive Configuration</h3></a> 87 <div class="section"> 88 <p> 89CTR programs typically utilize the following archives (all optional) regardless of the application type (CARD application or SD application): 90 </p> 91 <p> 92 <ul> 93<li>ROM Archives</li> 94<li>Save Data Archives</li> 95 </ul> 96 </p> 97 <p> 98 The configuration and size of these archives is determined at build time, based on content written in the RSF file. They are ready for use at time of program execution. (However, save data archives must be formatted before they can be used.) Because these archives are specific to the program, they exist together with the program as a set. Mounting is always enabled and cannot be disabled. 99 </p> 100 <p> 101Furthermore, 102 </p> 103 <p> 104 <ul> 105<li>Expanded Save Data Archives</li> 106 </ul> 107 </p> 108 <p> 109can be used. Since expanded save data archives exist independently from programs, they are specified using a unique ID called an "expanded save data ID." Any expanded save data ID used by a program must be explicitly listed in the RSF file. Also, more than one program can share the same expanded save data. Because expanded save data archives are located on an SD Card, they can be disabled (even while mounted) if the SD Card is removed. 110 </p> 111 <p> 112There are several other types of archives that programs can use. 113 </p> 114 </div> 115 116<a name="Summary_Targets"><h3>Purpose</h3></a> 117 <div class="section"> 118 <p> 119The "archive" concept is used for the following purposes. 120 </p> 121<h4>File or directory specification source</h4> 122 <div class="section"> 123 <p> 124Since files and directories belong to an archive, they must first be mounted by applying an archive name to the archive, and then opened by specifying that archive name and a path name inside the archive. Archives must be closed (unmounted) when you are finished with them, but all open files and directories inside the archive must be closed first. 125 </p> 126 </div> 127<h4>Contents of files and directories</h4> 128 <div class="section"> 129 <p> 130In order to use an expanded save data archive, for example, you must create an expanded save data archive first, before mounting, by calling a special function for creating these archives. You can then create files and directories inside the archive, and read and write data to/from them. 131 </p> 132 <p> 133When using a save data archive, the archive region itself must exist at the time of program execution, but must be formatted by calling a special function for formatting these archives, if the archive region is not formatted. 134 </p> 135 <p> 136ROM archives do not need to be created before mounting, because they always exist at the time of program execution. 137 </p> 138 </div> 139<h4>Abstraction of the interface</h4> 140 <div class="section"> 141 <p> 142Regardless of the archive type, a standardized interface is used to access files and directories once an archive is mounted. This allows functionality like debugging using a different archive, while keeping changes to a minimum. 143 </p> 144 </div> 145<h4>Clarification of archive properties</h4> 146 <div class="section"> 147 <p> 148Archives come in several types. Access characteristics and allowable operations vary for each type. The fact that there are differences is made clear by the fact that each type of archive is mounted using a special function for mounting that type. Furthermore, you can count on sharing code by using the same mounting function for archives that can be used in the same way, regardless of the application type (CARD application or SD application). 149 </p> 150 </div> 151<h4>System resource usage</h4> 152 <div class="section"> 153 <p> 154The CTR file system uses large amounts of resources, including memory, compared to a simple file system in order to achieve sufficient security and robustness. The system load is, therefore, lessened by freeing as many unnecessary resources as possible, at this time. The unit of resource allocation here is at the archive level. Conversely, if you need to access multiple files in an archive consecutively, leaving the archive open during this time can increase performance because the amount of time to access data is decreased. 155 </p> 156 </div> 157<h4>Disabling when removing media</h4> 158 <div class="section"> 159 <p> 160For expanded save data on a removable media (such as an SD Card), if the user removes the media, the data actually accessed may become data on different media entirely (even if mounted using the same parameters and same function for mounting). The file system, therefore, disables the archive when the media containing the archive is removed. It then can no longer be accessed, as-is, even if the media is re-inserted. You must first unmount the original archive, and then mount it again, if you wish to re-enable access. Disabling access due to media removal is performed at the archive level. 161 </p> 162 </div> 163<h4>Commit unit</h4> 164 <div class="section"> 165 <p> 166In the case of duplicated save data archives, data can be committed by calling a special function for committing data. Conversely, if an archive is unmounted by calling the commit function, data will not be committed, and the status of data when the archive was mounted will be restored. Data is either committed or rolled back at the archive level. 167 </p> 168 </div> 169 </div> 170 171 </div> 172 173<a name="Archives"><h2>Detailed Information on Archives</h2></a> 174 <div class="section"> 175<a name="Archives_RomArchive"><h3>ROM Archives</h3></a> 176 <div class="section"> 177 <p> 178<CODE>ROM</CODE> archives are read-only archives for referencing a program-specific <CODE>ROMFS</CODE> created at build time. Because ROM archives are guaranteed to already exist when the program starts, they can be used merely by mounting them, without having to create the archive inside the program. 179 </p> 180 <p> 181To create a ROM archive at build time, specify <CODE>Rom/HostRoot</CODE> and <CODE>Rom/Reject</CODE> (optional) in the RSF file. For details, see the <CODE><a href="../../../../tools/ctr_makerom.html#rsf">ctr_makerom</a></CODE> reference. 182 </p> 183 <p> 184To mount a ROM archive, call the <a href="../../../nn/fs/MountRom.html"><CODE>nn::fs::MountRom</CODE></a> function. You must specify a working memory region when calling this function, because a certain amount of memory is required to work with the ROM archive. The required size of this working memory region can be obtained using the <a href="../../../nn/fs/GetRomRequiredMemorySize.html"><CODE>nn::fs::GetRomRequiredMemorySize</CODE></a> function. 185 </p> 186 <p> 187The number of files and directories that can be opened inside the ROM archive can be specified by argument when mounting. As long as the size returned by the <a href="../../../nn/fs/GetRomRequiredMemorySize.html"><CODE>nn::fs::GetRomRequiredMemorySize</CODE></a> function is acceptable to the program developer, there is no limit on the number of files and directories in a ROM archive that can be opened. Be sure to specify the required number. 188 </p> 189 <p> 190You can also select whether or not to cache file management information for the ROM archive in memory. The value returned by the <a href="../../../nn/fs/GetRomRequiredMemorySize.html"><CODE>nn::fs::GetRomRequiredMemorySize</CODE></a> function varies, depending on this specification. The greater the number of files and directories inside the archive, the larger the size returned. The time required to open files and directories can be reduced by using caching. Caching is recommended in cases where you may be frequently opening a large number of detailed files. Conversely, there is no advantage to caching in cases where only a few files are being handled and open files will remain open for a long period of time. The only advantage to caching, is when opening files or directories for access using file management information. Once a file is open, there is no difference in performance in reading the data after that point. 191 </p> 192 </div> 193<a name="Archives_SaveDataArchive"><h3>Save Data Archives</h3></a> 194 <div class="section"> 195 <p> 196A save data archive is used to access a program-specific save data region that can be read and written. The physical location of this type of archive varies depending on the program type. It is represented by a file on the CARD for CARD applications, and on the SD Card for SD applications. However, developers do not need to be concerned about this difference, because it is handled by the system. The save data region is guaranteed to be placed in the correct position by the system, at the time a program starts. This type of archive is not created during program execution. The content of save data is protected by the system. The data is guaranteed to be free of illegal tampering, if it can be accessed without an error. 197 </p> 198 <p> 199The size of the save data region is determined by information given in the RSF file specified at build time. For details, see the <CODE><a href="../../../../tools/ctr_makerom.html#rsf">ctr_makerom</a></CODE> reference. 200 </p> 201 <p> 202To mount a save data archive, call the <a href="../../../nn/fs/MountSaveData.html"><CODE>nn::fs::MountSaveData</CODE></a> function with only the argument for the archive name. Calls to this function will fail if save data has not been formatted, such as, when using the save data for the first time. The save data region must, therefore, be formatted using the <a href="../../../nn/fs/FormatSaveData.html"><CODE>nn::fs::FormatSaveData</CODE></a> function. For details on handling this type of archive, see <a href="./aboutErrorHandling.html#Mounting_SaveDataArchive"><CODE>Error Handling</CODE></a>. 203 </p> 204 <p> 205You can specify the number of files and directories that can be created inside a save data archive when it is formatted. Be sure to specify a large enough number, because you will not be able to create any more files or directories than specified here. 206 </p> 207 <p> 208You can also select whether to duplicate save data when it is formatted. The amount of data that can actually be used is about half, in the case of duplicated save data, compared to unduplicated data. However, the data is guaranteed to be free of corruption, as long as it has not been intentionally altered (such as by directly editing data on the SD Card using a PC). Conversely, data may be corrupted in the case of unduplicated data, if the power fails or media is removed while writing data. Nintendo recommends that you use duplicated save data, as long as there is no problem with save data capacity. 209 </p> 210 <p> 211Use the <a href="savedata_calc_user.html#CalcSize_SaveData"><CODE>Save Data File System Capacity Calculation Sheet</CODE></a> to calculate the data size that can be used for save data. Note, however, that save data files are handled in blocks of 512 bytes each. Note that even if the actual file size is only 1 byte, the capacity required to maintain it will be 512 bytes. 212 </p> 213 <p> 214Operations performed on a duplicated save data archive (creating and deleting files, writing data to files, and so forth) are not enabled on actual storage until the <a href="../../../nn/fs/CommitSaveData.html"><CODE>nn::fs::CommitSaveData</CODE></a> function is called on the archive name in question. If an archive is unmounted without calling the <a href="../../../nn/fs/CommitSaveData.html"><CODE>nn::fs::CommitSaveData</CODE></a> function and then the save data archive is mounted again, status will be rolled back to the same file and directory structure in place the last time the archive was mounted, and file contents will be identical to what they were at that time. In general, be sure to call the <a href="../../../nn/fs/CommitSaveData.html"><CODE>nn::fs::CommitSaveData</CODE></a> function before showing the user a message such as "Save complete". If you want to intentionally roll back the status of an archive, you can do so by unmounting the archive without calling the <a href="../../../nn/fs/CommitSaveData.html"><CODE>nn::fs::CommitSaveData</CODE></a> function. 215 </p> 216 <p> 217The first 512 byes of a save data archive file newly created using <a href="../../../nn/fs/TryCreateFile.html"><CODE>nn::fs::TryCreateFile</CODE></a> are guaranteed to be padded with zeroes. If a subsequent attempt is made to read an area of this file to which data has not yet been written, either a <a href="../../../nn/fs/ResultVerificationFailed/Overview.html"><CODE>ResultVerificationFailed</CODE></a> type error will be returned or an undefined value will be read. 218 </p> 219 </div> 220 221<a name="Archives_SaveDataArchive_Other"><h3>Save Data Archives (Other Programs)</h3></a> 222 <div class="section"> 223 <p> 224Every program maintains a save data region, and although there are restrictions, it is possible for a given program to access the save data in the possession of other programs. Those other programs are recognized by their unique ID and variation. 225 </p> 226 <p> 227To mount the save data that is in the possession of another program, call the <CODE><a href="../../../nn/fs/MountSaveData.html">nn::fs::MountSaveData</a></CODE> function to get that unique ID and variation. The only unique IDs that can be specified at this time are the unique IDs specified in the RSF files of the programs that call this function call. For details, see <CODE>AccessControlInfo/OtherUserSaveDataIdN</CODE> and <CODE>AccessControlInfo/UseOtherVariationSaveData </CODE> in the <a href="../../../../tools/ctr_makerom.html#rsf">ctr_makerom</a> reference. 228 </p> 229 <p> 230When a program acts to access the save data of another program, there is no ironclad guarantee that the save data actually exists. Moreover, there may be times when the media containing the target save data gets removed while the save data is being accessed. So be aware of the need for error handling for other errors than those that can occur when a program accesses its own save data. For details on how to handle errors, see <a href="./aboutErrorHandling.html#Mounting_ExtSaveDataArchive">Error Handling</a>. 231 </p> 232 <p> 233As for other specifications, they are the same as for a program's own save data archives. In the case of duplicated save data, you need to call the <CODE><a href="../../../nn/fs/CommitSaveData.html">nn::fs::CommitSaveData</a></CODE> function when writing it. 234 </p> 235 </div> 236 237<a name="Archives_ExtSaveDataArchive"><h3>Expanded Save Data Archives</h3></a> 238 <div class="section"> 239 <p> 240An expanded save data archive is a read/write archive created on an SD Card. In order to use an extended save data archive, the program must explicitly create the archive. The content of expanded save data is protected by the system. The data is guaranteed to be free of illegal tampering, if it can be accessed without an error. 241 </p> 242 <p> 243Expanded save data is identified by an expanded save data ID. Expanded save data that can be manipulated by the application is limited to that data specified using <CODE>AccessControlInfo/ExtSaveDataNumber</CODE> in the RSF file specified at build time. Other expanded save data cannot be altered. For details, see the <CODE><a href="../../../../tools/ctr_makerom.html#rsf">ctr_makerom</a></CODE> reference. 244 </p> 245 <p> 246To mount an extended save data archive, call the <a href="../../../nn/fs/MountExtSaveData.html"><CODE>nn::fs::MountExtSaveData</CODE></a> function. Mounting will fail if the archive does not exist. In this case, an archive must be created using the <span>nn::fs::CreateExtSavedData</span> function. For details on handling this type of archive, see <a href="./aboutErrorHandling.html#Mounting_ExtSaveDataArchive"><CODE>Error Handling</CODE></a>. 247 </p> 248 <p> 249As a limitation on the operations that can be performed on files in an expanded save data archive, the size of a file cannot be changed. The size of such a file therefore cannot be changed using the <a href="../../../nn/fs/FileStream/TrySetSize.html"><CODE>nn::fs::FileStream::TrySetSize</CODE></a> function, or automatically extended when using the <a href="../../../nn/fs/FileStream/TryWrite.html"><CODE>nn::fs::FileStream::TryWrite</CODE></a> function. Furthermore, you cannot create files using a function like <a href="../../../nn/fs/FileStream/TryInitialize.html"><CODE>nn::fs::FileStream::TryInitialize</CODE></a>, that does not allow a size specification. You must always create files ahead of time, with a size specification, using the <a href="../../../nn/fs/TryCreateFile.html"><CODE>nn::fs::TryCreateFile</CODE></a> function. 250 </p> 251 <p> 252Because meta data or other data may be added to an expanded save data archive file, SD Card memory is used when the amount of data exceeds the actual usable size. Use the <a href="savedata_calc_user.html#CalcSize_ExtSaveData"><CODE>Save Data File System Capacity Calculation Sheet</CODE></a> to determine how much space to actually procure when creating a file. 253 </p> 254 <p> 255The first 512 byes of a save data archive file newly created using <a href="../../../nn/fs/TryCreateFile.html"><CODE>nn::fs::TryCreateFile</CODE></a> is guaranteed to be padded with zeroes. If a subsequent attempt is made to read an area of this file to which data has not yet been written, either a <a href="../../../nn/fs/ResultVerificationFailed/Overview.html"><CODE>ResultVerificationFailed</CODE></a> type error will be returned, or an undefined value will be read. 256 </p> 257 <p> 258An expanded save data archive may be disabled if the SD Card is unintentionally removed, because it is located on an SD Card, which is removable media. Data may be corrupted at this time. Furthermore, the possibility of unwanted operations by another program increases, because the same expanded save data can be shared by more than one program.<strong>Be sure to perform careful error handling when dealing with expanded save data.</strong> 259 </p> 260 <p> 261It takes a bit longer to perform a given operation on an expanded save data archive, due to needing to handle a large amount of meta data. Write times may be particularly excessive, depending on the SD Card type.<strong>Make sure to perform a thorough performance check during development.</strong> 262 </p> 263 </div> 264 265<a name="Archives_SdmcArchive"><h3>SDMC Archives</h3></a> 266 <div class="section"> 267 <p> 268<CODE>SDMC</CODE> archives are used to directly reference the FAT file system on SD Cards during debugging. 269 </p> 270 <p> 271<CODE>SDMC</CODE> archives cannot be accessed by production versions of software, because they are intended for debugging purposes only. Furthermore, you must list <var>Debug</var> under <CODE>AccessControlInfo/FileSystemAccess</CODE> in the RSF file, even to use this type of archive during debugging. For details, see the <CODE><a href="../../../../tools/ctr_makerom.html#rsf">ctr_makerom</a></CODE> reference. 272 </p> 273 <p> 274To mount an <CODE>SDMC</CODE> archive, call the <a href="../../../nn/fs/MountSdmc.html"><CODE>nn::fs::MountSdmc</CODE></a> function, while the SD Card is inserted. Archives are disabled if the SD Card is removed. Re-mounting then becomes necessary. 275 </p> 276 </div> 277 278<a name="Archives_SdmcWriteOnlyArchive"><h3>Write-only SDMC Archives</h3></a> 279 <div class="section"> 280 <p> 281A write-only <CODE>SDMC</CODE> archive accesses the FAT file system on an SD Card in write-only mode. This type of archive is essentially used in the same manner as an <CODE>SDMC</CODE> archive. 282 </p> 283 <p> 284You must list <var>DirectSdmcWrite</var> under <CODE>AccessControlInfo/FileSystemAccess</CODE> in the RSF file, in order to use a write-only <CODE>SDMC</CODE> archive. For details, see the <CODE><a href="../../../../tools/ctr_makerom.html#rsf">ctr_makerom</a></CODE> reference. 285 </p> 286 </div> 287 288<a name="Archives_HioArchive"><h3>HIO Archives</h3></a> 289 <div class="section"> 290 <p> 291An <CODE>HIO</CODE> archive views the directory specified on the host PC, and everything in it as a single archive. Features of the HIO library can be used to work with these archives using the common interface of the <CODE>FS</CODE> library. Since the <CODE>HIO</CODE> library is used to implement this type of archive, they are subject to the limitations of the <CODE>HIO</CODE> library. 292 </p> 293 <p> 294To mount an <CODE>HIO</CODE> archive, first initialize the <CODE>HIO</CODE> library using the <a href="../../../nn/hio/CTR/Initialize.html"><CODE>nn::hio::CTR::Initialize</CODE></a> function. Then call <a href="../../../nn/fs/hio/MountHioArchive.html"><CODE>nn::fs::hio::MountHioArchive</CODE></a>, while passing the directory path name of the host PC as an argument. 295 </p> 296 <p> 297<CODE>HIO</CODE> archives cannot be accessed by production versions of software, because they are intended for development and debugging purposes only. Also, note that values returned at time of access for return values, such as <CODE>Result</CODE>, are not the same as for other archives. Finally, behavior may change as the SDK and debugger software change. Only use this type of archive to supplement development and debugging. 298 </p> 299 </div> 300 </div> 301 302<a name="Restrictions"><h2>Archive Limitations</h2></a> 303 <div class="section"> 304All archive types entail the following limitations. 305 306<a name="Restrictions_OperatingFile"><h3>File Operations</h3></a> 307 <div class="section"> 308 <table> 309 <thead> 310<th></th><th>Read (R) Write (W)</th><th>Changing Sizes</th><th>Creating files</th><th>Opening multiple files simultaneously</th> 311 </thead> 312 <tr> 313<th>ROM Archives</th><td>R</td><td>Impossible</td><td>Impossible</td><td>Only when all read-only</td> 314 </tr> 315 <tr> 316<th>Save Data Archives</th><td>R/W</td><td>Possible</td><td><a href="../../../nn/fs/FileStream/Overview.html"><CODE>FileStream</CODE></a><br /><a href="../../../nn/fs/FileOutputStream/Overview.html"><CODE>FileOutputStream</CODE></a><br /><a href="../../../nn/fs/TryCreateFile.html"><CODE>nn::fs::TryCreateFile</CODE></a></td><td>Only when all read-only</td> 317 </tr> 318 <tr> 319<th>Expanded Save Data Archives</th><td>R/W</td><td>Impossible</td><td><a href="../../../nn/fs/TryCreateFile.html"><CODE>nn::fs::TryCreateFile</CODE></a> only</td><td>Only when all read-only</td> 320 </tr> 321 <tr> 322<th>SDMC Archives</th><td>R/W</td><td>Possible</td><td><a href="../../../nn/fs/FileStream/Overview.html"><CODE>FileStream</CODE></a><br /><a href="../../../nn/fs/FileOutputStream/Overview.html"><CODE>FileOutputStream</CODE></a><br /><a href="../../../nn/fs/TryCreateFile.html"><CODE>nn::fs::TryCreateFile</CODE></a></td><td>Possible</td> 323 </tr> 324 <tr> 325<th>Write-only SDMC Archives</th><td>W</td><td>Possible</td><td><a href="../../../nn/fs/FileStream/Overview.html"><CODE>FileStream</CODE></a><br /><a href="../../../nn/fs/FileOutputStream/Overview.html"><CODE>FileOutputStream</CODE></a><br /><a href="../../../nn/fs/TryCreateFile.html"><CODE>nn::fs::TryCreateFile</CODE></a></td><td>Impossible</td> 326 </tr> 327 <tr> 328<th>HIO Archives</th><td>R/W</td><td>Possible</td><td><a href="../../../nn/fs/FileStream/Overview.html"><CODE>FileStream</CODE></a><br /><a href="../../../nn/fs/FileOutputStream/Overview.html"><CODE>FileOutputStream</CODE></a><br /><a href="../../../nn/fs/TryCreateFile.html"><CODE>nn::fs::TryCreateFile</CODE></a></td><td>(Operation not guaranteed)</td> 329 </tr> 330 </table> 331 </div> 332 333<a name="Restrictions_Charactors"><h3>Character Restrictions</h3></a> 334 <div class="section"> 335 <table> 336 <thead> 337<th></th><th>Filename Length</th><th>Path Length (See <B>Note 1</B>)</th><th>Case-sensitive</th><th>Forbidden characters</th> 338 </thead> 339 <tr> 340<th>ROM Archives</th><td>-</td><td>253 characters</td><td>Yes</td><td>(※3)</td> 341 </tr> 342 <tr> 343<th>Save Data Archives</th><td>16 characters</td><td>253 characters</td><td>Yes</td><td>(※2)(※3)</td> 344 </tr> 345 <tr> 346<th>Expanded Save Data Archives</th><td>16 characters</td><td>248 characters</td><td>Yes</td><td>(※2)(※3)</td> 347 </tr> 348 <tr> 349<th>SDMC Archives</th><td>253 characters (See <B>Note 4</B>)</td><td>253 characters (See <B>Note 4</B>)</td><td>No</td><td>(※3)</td> 350 </tr> 351 <tr> 352<th>Write-only SDMC Archives</th><td>253 characters (See <B>Note 4</B>)</td><td>253 characters (See <B>Note 4</B>)</td><td>No</td><td>(※3)</td> 353 </tr> 354 <tr> 355<th>HIO Archives</th><td colspan="4">Comply with host PC restrictions</td> 356 </tr> 357 </table> 358 359<B>Note 1:</B> Not including archive names.<br />(※2) <font color="red"><B>Note 2:</B> 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. </font><br /> (※3) <B>Note 3:</B> 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.<br /> <B>Note 4:</B> This is restricted to 251 characters only when a directory is opened.<br /> 360 </div> 361 362<a name="Restrictions_InvalidCharactors"><h3>Unusable Characters in File and Directory Names</h3></a> 363 <div class="section"> 364<pre> 365\ / : * ? " < > | 366</pre> 367 </div> 368 369<a name="Restrictions_InvalidName"><h3>Unusable File and Directory Names</h3></a> 370 <div class="section"> 371<pre> 372CON, PRN, NUL, AUX, LPT1, LPT2, LPT3, LPT4, COM1, COM2, COM3, COM4 373con, prn, nul, aux, lpt1, lpt2, lpt3, lpt4, com1, com2, com3, com4 374</pre> 375 </div> 376 377<a name="Restrictions_InvalidArchiveName"><h3>Characters Prohibited for Use in Archive Names</h3></a> 378 <div class="section"> 379In 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. 380 </div> 381 382<a name="Restrictions_HalfSizeSpace"><h3>Single-byte Spaces in File and Directory Names</h3></a> 383 <div class="section"> 384In SDMC archives, any single-byte spaces specified at the start and/or end of entry names (filenames and directory names) are deleted.<br />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. <br /> 385 <table> 386 <thead> 387<th>Specified entry name</th><th>Actual entry name on which operations are performed (only for SDMC archives)</th> 388 </thead> 389 <tr> 390<td><tt>EntryName</tt></td><td><tt>EntryName</tt></td> 391 </tr> 392 <tr> 393<td><tt>_EntryName</tt></td><td><tt>EntryName</tt></td> 394 </tr> 395 <tr> 396<td><tt>__EntryName</tt></td><td><tt>EntryName</tt></td> 397 </tr> 398 <tr> 399<td><tt>Entry_Name</tt></td><td><tt>Entry_Name</tt></td> 400 </tr> 401 <tr> 402<td><tt>EntryName_</tt></td><td><tt>EntryName</tt></td> 403 </tr> 404 <tr> 405<td><tt>_Entry_Name_</tt></td><td><tt>Entry_Name</tt></td> 406 </tr> 407 </table> 408※ <B>Note:</B> <tt>"_"</tt> indicates a single-byte space. 409 </div> 410 </div> 411 412<a name="History"><h2>Revision History</h2></a> 413 <div class="section"> 414 <dl class="history"> 415 <dt>2012/01/20</dt> 416<dd>Made an overall review of information given.</dd> 417 <dt>2011/06/09</dt> 418<dd>Added information about characters prohibited for use in archive names.</dd> 419 <dt>2011/04/19</dt> 420<dd>Added text about the handling of single-byte spaces in entry names.</dd> 421 <dt>2011/01/07</dt> 422<dd>Added notes about error handling in <B>Expanded Save Data Archives</B>.</dd> 423 <dt>2010/12/11</dt> 424<dd>Added a link to the worksheet for calculating the save data capacity.</dd> 425 <dt>2010/12/02</dt> 426<dd>Removed <CODE>, ; = + [ ]</CODE> and single-byte space from the list of unusable characters.</dd> 427 <dt>2010/11/18</dt> 428<dd>Added "single-byte space" to the list of unusable characters.</dd> 429 <dt>2010/11/13</dt> 430<dd>Initial version.</dd> 431 </dl> 432 </div> 433 434<hr><p>CONFIDENTIAL</p></body> 435</html>