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_RomArchive">ROM Archives</a></li> 17<li><a href="#Summary_SaveDataArchive">Save Data Archives</a></li> 18<li><a href="#Summary_ExtSaveDataArchive">Expanded Save Data Archives</a></li> 19<li><a href="#Summary_SdmcArchive">SDMC Archives</a></li> 20<li><a href="#Summary_HioArchive">HIO Archives</a></li> 21 </ul> 22<li><a href="#Restrictions">Archive Limitations</a></li> 23 <ul> 24<li><a href="#Restrictions_OperatingFile">File Operations</a></li> 25<li><a href="#Restrictions_Charactors">Character Restrictions</a></li> 26<li><a href="#Restrictions_InvalidCharactors">Unusable Characters in File and Directory Names</a></li> 27<li><a href="#Restrictions_InvalidName">Unusable File and Directory Names</a></li> 28<li><a href="#Restrictions_HalfSizeSpace">Single-Byte Spaces in File and Directory Names</a></li> 29 </ul> 30<li><a href="#History">Revision History</a></li> 31 </ul> 32 33<a name="Summary"><h2>Overview</h2></a> 34 <div class="section"> 35Use the format <CODE>"<archive name>:<archive path>"</CODE> to specify the path name for file and directory operations. For archives with a hierarchical directory structure, slashes (<CODE>"/"</CODE>) are used as the directory delimiter.<br /><br /> 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 <a href="../../../nn/fs/Unmount.html"><CODE>nn::fs::Unmount</CODE></a> function. 36 37<a name="Summary_RomArchive"><h3>ROM Archives</h3></a> 38 <div class="section"> 39ROM 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 <a href="../../../nn/fs/MountRom.html"><CODE>nn::fs::MountRom</CODE></a> function. The number of files and the number of directories that can be opened in a ROM archive are passed as arguments to the <a href="../../../nn/fs/MountRom.html"><CODE>nn::fs::MountRom</CODE></a> function, and the only restriction on these numbers is the amount of available memory. Pass only the required numbers as arguments to the <a href="../../../nn/fs/MountRom.html"><CODE>nn::fs::MountRom</CODE></a> function.<br /><br /> 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. 40 </div> 41 42<a name="Summary_SaveDataArchive"><h3>Save Data Archives</h3></a> 43 <div class="section"> 44Save 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.<br /> 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.<br /> <br />Although the <a href="../../../nn/fs/MountSaveData.html"><CODE>nn::fs::MountSaveData</CODE></a> function is used to mount save data archives, you must format the save data region with the <a href="../../../nn/fs/FormatSaveData.html"><CODE>nn::fs::FormatSaveData</CODE></a> 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.<br /> Use the following worksheet to determine the amount of data that can actually be written in a save data archive.<br /> <br /> 45 <ul> 46<li><a href="savedata_calc_user.html#CalcSize_SaveData">Worksheet for Calculating the Save Data File System Capacity</a></li> 47 </ul> 48Note 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. 49 </div> 50 51<a name="Summary_ExtSaveDataArchive"><h3>Expanded Save Data Archives</h3></a> 52 <div class="section"> 53Expanded 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.<br /> <B>Note:</B> One characteristic of files created in expanded save data memory is that the size of these files cannot be changed. Be aware that the <a href="../../../nn/fs/FileStream/TrySetSize.html"><CODE>nn::fs::FileStream::TrySetSize</CODE></a> function and similar functions cannot enlarge the size of these files. Use the <CODE><a href="../../../nn/fs/TryCreateFile.html">nn::fs::TryCreateFile</a></CODE> 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 <CODE><a href="../../../nn/fs/FileStream/TryInitialize.html">nn::fs::FileStream::TryInitialize</a></CODE>, which does not have a size specification.<br /><br /> 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. <br /> 54 <ul> 55<li><a href="savedata_calc_user.html#CalcSize_ExtSaveData">Worksheet for Calculating the Save Data File System Capacity</a></li> 56 </ul> 57<br /> Because expanded save data has the following characteristics, there are many errors related to it that must be handled.<br /> <br /> 58 <ul> 59<li>Its content can be modified by other applications. (Normal operation will also cause it to change.）</li> 60<li>Users can use PCs or other devices to tamper with the SD Card data.</li> 61<li>The SD Card might be removed while it is being accessed.</li> 62 </ul> 63These possibilities cannot be prevented by any actions during development. You must implement solid and reliable error handling while keeping these possibilities in mind. 64 </div> 65 66<a name="Summary_SdmcArchive"><h3>SDMC Archives</h3></a> 67 <div class="section"> 68SDMC archives are for directly referencing SD Cards for debugging purposes. Mount the inserted SD Card using the <a href="../../../nn/fs/MountSdmc.html"><CODE>nn::fs::MountSdmc</CODE></a> function. When a mounted SD Card is removed and re-inserted, you must unmount it using the <a href="../../../nn/fs/Unmount.html"><CODE>nn::fs::Unmount</CODE></a> function and then call the <a href="../../../nn/fs/MountSdmc.html"><CODE>nn::fs::MountSdmc</CODE></a> function again to re-mount it.<br /><br /> <B>Note:</B> SDMC archives are only for debugging and cannot be accessed from retail versions. To use this archive, you must add the <CODE>"- Debug"</CODE> attribute to the file system access permissions in your RSF file. For details, see <a href="../../../tools/ctr_makerom.html"><CODE>ctr_makerom</CODE></a>. 69 </div> 70 71<a name="Summary_HioArchive"><h3>HIO Archives</h3></a> 72 <div class="section"> 73An HIO archive recognizes the content of a specific directory (on the computer specified by the <SPAN class="argument">hostPath</SPAN> argument) as a single archive. These archives can be used only for debugging purposes.<br /><br /><br /> <B>Note:</B> HIO archives are only for debugging and cannot be accessed from retail versions. <br />The <CODE>Result</CODE> 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. 74 </div> 75 </div> 76 77<a name="Restrictions"><h2>Archive Limitations</h2></a> 78 <div class="section"> 79All archive types entail the following limitations. 80 81<a name="Restrictions_OperatingFile"><h3>File Operations</h3></a> 82 <div class="section"> 83 <table> 84 <thead> 85<th></th><th>R/W</th><th>Changing Sizes</th><th>Creation</th><th>Opening Multiple Instances</th> 86 </thead> 87 <tr> 88<th>ROM Archives</th><td>R</td><td>Impossible</td><td>Impossible</td><td>Only when all read-only</td> 89 </tr> 90 <tr> 91<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> 92 </tr> 93 <tr> 94<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> 95 </tr> 96 <tr> 97<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> 98 </tr> 99 <tr> 100<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> 101 </tr> 102 </table> 103 </div> 104 105<a name="Restrictions_Charactors"><h3>Character Restrictions</h3></a> 106 <div class="section"> 107 <table> 108 <thead> 109<th></th><th>Filename Length</th><th>Path Length (See Note 1)</th><th>Case-sensitive</th><th>Forbidden characters</th> 110 </thead> 111 <tr> 112<th>ROM Archives</th><td>-</td><td>253 characters</td><td>Yes</td><td>（※3）</td> 113 </tr> 114 <tr> 115<th>Save Data Archives</th><td>16 characters</td><td>253 characters</td><td>Yes</td><td>（※2）（※3）</td> 116 </tr> 117 <tr> 118<th>Expanded Save Data Archives</th><td>16 characters</td><td>248 characters</td><td>Yes</td><td>（※2）（※3）</td> 119 </tr> 120 <tr> 121<th>SDMC Archives</th><td>253 characters (See Note 4)</td><td>253 characters (See Note 4)</td><td>No</td><td>（※3）</td> 122 </tr> 123 <tr> 124<th>HIO Archives</th><td colspan="4">Comply with host PC restrictions</td> 125 </tr> 126 </table> 127 128<B>Note 1:</B> Not including archive names.<br />（※2） <font color="red">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. </font><br /> *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.<br /> <B>Note 4:</B> This is restricted to 251 characters only when a directory is opened.<br /> 129 </div> 130 131<a name="Restrictions_InvalidCharactors"><h3>Unusable Characters in File and Directory Names</h3></a> 132 <div class="section"> 133<pre> 134\ / : * ? " < > | 135</pre> 136 </div> 137 138<a name="Restrictions_InvalidName"><h3>Unusable File and Directory Names</h3></a> 139 <div class="section"> 140<pre> 141CON, PRN, NUL, AUX, LPT1, LPT2, LPT3, LPT4, COM1, COM2, COM3, COM4 142con, prn, nul, aux, lpt1, lpt2, lpt3, lpt4, com1, com2, com3, com4 143</pre> 144 </div> 145 146<a name="Restrictions_HalfSizeSpace"><h3>Single-Byte Spaces in File and Directory Names</h3></a> 147 <div class="section"> 148In SDMC archives, any single-byte spaces specified at the beginning and end of entry names (file names 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 /> <br /> 149 <table> 150 <thead> 151<th>Specified entry name</th><th>Entry name that is the target of actual operation (for SDMC archived only)</th> 152 </thead> 153 <tr> 154<td><tt>EntryName</tt></td><td><tt>EntryName</tt></td> 155 </tr> 156 <tr> 157<td><tt>_EntryName</tt></td><td><tt>EntryName</tt></td> 158 </tr> 159 <tr> 160<td><tt>__EntryName</tt></td><td><tt>EntryName</tt></td> 161 </tr> 162 <tr> 163<td><tt>Entry_Name</tt></td><td><tt>Entry_Name</tt></td> 164 </tr> 165 <tr> 166<td><tt>EntryName_</tt></td><td><tt>EntryName</tt></td> 167 </tr> 168 <tr> 169<td><tt>_Entry_Name_</tt></td><td><tt>Entry_Name</tt></td> 170 </tr> 171 </table> 172<B>Note:</B> The symbol <tt>"_"</tt> represents a single-byte space. 173 </div> 174 </div> 175 176<a name="History"><h2>Revision History</h2></a> 177 <div class="section"> 178 <dl class="history"> 179 <dt>2011/04/19</dt> 180<dd>Added text about the handling of single-byte spaces in entry names.</dd> 181 <dt>2011/01/07</dt> 182<dd>Added notes about error handling in <B>Expanded Save Data Archives</B>.</dd> 183 <dt>2010/12/11</dt> 184<dd>Added a link to the worksheet for calculating the save data capacity.</dd> 185 <dt>2010/12/02</dt> 186<dd>Removed <CODE>, ; = + [ ]</CODE> and single-byte space from the list of unusable characters.</dd> 187 <dt>2010/11/18</dt> 188<dd>Added "single-byte space" to the list of unusable characters.</dd> 189 <dt>2010/11/13</dt> 190<dd>Initial version.</dd> 191 </dl> 192 </div> 193 194<hr><p>CONFIDENTIAL</p></body> 195</html>