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>Error Handling</title>
8</head>
9<body>
10    <h1>File System Error Handling</h1>
11
12    <h2>Overview</h2>
13
14    <h3>Result Handling</h3>
15    <p>
16    FS functions return many different types of <CODE>Result</CODE> values. These are handled by the following mechanism rather than one value at a time. The following example shows how to handle all errors belonging to the <CODE>NotFound</CODE> category.
17    </p>
18<pre>
19if(result &lt;= nn::fs::ResultNotFound())
20{
21    ...
22}
23</pre>
24    <p>
25    <CODE>Result</CODE> objects returned by <CODE>fs</CODE> functions are forbidden from using the arithmetic operators <CODE>==</CODE> or <CODE>!=</CODE>. Using these causes a build error. The following two examples are equivalent.
26    </p>
27<pre>
28if(nn::fs::ResultNotFound::Includes(result))
29{
30    ...
31}
32</pre>
33<pre>
34if(nn::fs::ResultNotFound() &gt;= result)
35{
36    ...
37}
38</pre>
39    <p><font color="red">Do not directly handle any <CODE>Result</CODE> values that are not mentioned in the Function Reference Manual.</font></p>
40
41    <h2>Handling Mount Errors</h2>
42    <p>
43    The following simplified C++ code provides guidelines for handling mount errors.
44    </p>
45
46    <h3>ROM Archives</h3>
47<pre>
48nn::Result result = nn::fs::MountRom();
49if( result.IsFailure() )
50{
51    // A ROM archive never fails to be mounted. Any failure indicates an abnormal condition.
52    // NOTE: When developing an application, confirm that you are passing enough working memory as an argument.
53    //       Also check your Omakefile and RSF file to determine whether a ROMFS is created at build time.
54}
55</pre>
56
57    <h3>Save Data Archives</h3>
58<pre>
59nn::Result result = nn::fs::MountSaveData();
60
61if( result.IsFailure() )
62{
63    if(result &lt;= nn::fs::ResultNotFound())
64    {
65        // The application cannot create a save data region.
66        // However, do not allow the application to stop on this error.
67    }
68    else if(result &lt;= nn::fs::ResultNotFormatted())
69    {
70        // Data must be formatted.
71        // CAUSE: Unformatted save data region.
72        // NOTE: You must format a save data region before mounting it for the first time.
73        result = nn::fs::FormatSaveData();
74    }
75    else if(result &lt;= nn::fs::ResultBadFormat())
76    {
77        // Data must be formatted.
78        // CAUSE: Invalid file format.
79        result = nn::fs::FormatSaveData();
80    }
81    else if(result &lt;= nn::fs::ResultVerificationFailed())
82    {
83        // Data must be formatted.
84        // CAUSE: Corrupted or altered save data.
85        // NOTE: This state is never the result of user operations when data is mirrored (duplicated).
86        //       This error may be caused by user operations (such as removing a card or turning off the system while data is being written) when data is not mirrored.
87        result = nn::fs::FormatSaveData();
88    }
89    else
90    {
91        // Some other error has occurred.
92    }
93
94    // Troubleshooting after data has been formatted
95    if( result.IsFailure() )
96    {
97        // The act of formatting save data never fails.
98        // NOTE: When developing your application, confirm that the maxFiles and maxDirectories arguments are not too big.
99        //       Also confirm that the content of the RSF file is correct.
100    }
101    else
102    {
103        // Re-mount
104        result = nn::fs::MountSaveData();
105        if( result.IsFailure() )
106        {
107            // After data has been successfully formatted, the act of mounting it never fails.
108        }
109    }
110}
111</pre>
112
113    <h3>Expanded Save Data Archives</h3>
114<pre>
115nn::Result result = nn::fs::MountExtSaveData();
116
117if( result.IsFailure() )
118{
119    if(result &lt;= nn::fs::ResultNotFound())
120    {
121        if(result &lt;= nn::fs::ResultMediaNotFound())
122        {
123            // An SD Card has not been inserted.
124        }
125        else
126        {
127            // The specified expanded save data does not exist and must be created.
128            // NOTE: Confirm that the specified ID is correct when developing your application.
129            result = nn::fs::CreateExtSaveData();
130        }
131    }
132    else if(result &lt;= nn::fs::ResultBadFormat())
133    {
134        // You must recreate the expanded save data.
135        // CAUSE: Invalid file format.
136        result = nn::fs::DeleteExtSaveData();
137        if(result.IsSuccess())
138        {
139            result = nn::fs::CreateExtSaveData();
140        }
141    }
142    else if(result &lt;= nn::fs::ResultVerificationFailed())
143    {
144        // You must recreate the expanded save data.
145        // CAUSE: Corrupted or altered save data.
146        // NOTE: This state is never the result of user operations when data is mirrored (duplicated).
147        //       This error may be caused by user operations (such as removing a card or turning off the system while data is being written) when data is not mirrored.
148        result = nn::fs::DeleteExtSaveData();
149        if(result.IsSuccess())
150        {
151            result = nn::fs::CreateExtSaveData();
152        }
153    }
154    else if(result &lt;= nn::fs::ResultArchiveInvalidated())
155    {
156        // The SD Card may have been removed while it was being mounted.
157        // Handle this just like nn::fs::ResultMediaNotFound().
158    }
159    else if(result &lt;= nn::fs::ResultOperationDenied())
160    {
161        // Either the inserted card is not an SD Card or the SD Card is corrupted.
162    }
163    else
164    {
165        // Some other error has occurred.
166    }
167
168    // Troubleshooting after data has been created
169    if( result.IsFailure() )
170    {
171        if(result &lt;= nn::fs::ResultNotEnoughSpace())
172        {
173            // There is no free space on the SD Card.
174        }
175        else
176        {
177            // As long as the SD Card is not removed while data is being created, the operation will not fail.
178            // NOTE: When developing your application, confirm that the entryFile and entryDirectory arguments are not too big.
179            //       Also confirm that valid values are being passed to iconData and iconDataSize.
180        }
181    }
182    else
183    {
184        // Re-mount
185        result = nn::fs::MountExtSaveData();
186        if( result.IsFailure() )
187        {
188            // As long as the SD Card is not removed, the mount operation will not fail immediately after data is created.
189        }
190
191    }
192}
193</pre>
194
195    <h2>Handling Errors During File and Directory Operations</h2>
196<pre>
197if(result.IsFailure())
198{
199    if(result &lt;= nn::fs::ResultNotFound())
200    {
201        if(result &lt;= nn::fs::ResultMediaNotFound())
202        {
203            // An SD Card has not been inserted.
204        }
205        else
206        {
207            // The specified path does not exist.
208            // NOTE: This error is not returned when files and directories are created.
209        }
210    }
211    else if(result &lt;= nn::fs::ResultAlreadyExists())
212    {
213        // The specified path already exists.
214        // NOTE: This error is not returned when files and directories are deleted.
215    }
216    else if(result &lt;= nn::fs::ResultBadFormat())
217    {
218        // You must delete and recreate this file (directory).
219        // CAUSE: Invalid file format.
220        // NOTE: If this does not solve the problem, you need to format or recreate the archive.
221    }
222    else if(result &lt;= nn::fs::ResultVerificationFailed())
223    {
224        // You must delete and recreate this file (directory).
225        // CAUSE: Corrupted or altered save data.
226        // NOTE: This state is never the result of user operations when data is mirrored (duplicated).
227        //       This error may be caused by user operations (such as removing a card or turning off the system while data is being written) when data is not mirrored.
228        // If this does not solve the problem, you need to format or recreate the archive.
229    }
230    else if(result &lt;= nn::fs::ResultArchiveInvalidated())
231    {
232        // You must remount the archive.
233        // CAUSE: The SD Card was removed, making the archive invalid.
234    }
235    else if(result &lt;= nn::fs::ResultOperationDenied())
236    {
237        if(result &lt;= nn::fs::ResultWriteProtected())
238        {
239            // The SD Card is write-locked.
240        }
241        else if(result &lt;= nn::fs::ResultMediaAccessError())
242        {
243            // Either the inserted card is not an SD Card or the SD Card is corrupted.
244            // Backup memory may be corrupted while a CTR Card is being accessed.
245        }
246        else
247        {
248            // Access was denied for some reason other than those above.
249            // EXAMPLES: You attempted to write to a file that cannot be written.
250            //           You attempted to delete a file that was open elsewhere.
251            //           You attempted to move a subdirectory that cannot be moved.
252            //           You attempted to move a file or directory between archives.
253            //           You attempted to delete the root directory.
254        }
255    }
256    else
257    {
258        // Some other error has occurred.
259    }
260}
261</pre>
262
263    <h2>Revision History</h2>
264    <div class="section">
265      <dl class="history">
266        <dt>2010/11/13</dt>
267        <dd>Initial version.</dd>
268      </dl>
269    </div>
270
271<hr><p>CONFIDENTIAL</p></body>
272</html>
273