# FSResult

## Definition

    #include <nitro/fs.h>

    typedef	enum FSResult
    {
        FS_RESULT_SUCCESS = 0,
        FS_RESULT_FAILURE = 1,
        FS_RESULT_BUSY = 2,
        FS_RESULT_CANCELED = 3,
        FS_RESULT_UNSUPPORTED = 4,
        FS_RESULT_ERROR = 5,
        FS_RESULT_INVALID_PARAMETER = 6,
        FS_RESULT_NO_MORE_RESOURCE = 7,
        FS_RESULT_ALREADY_DONE = 8,
        FS_RESULT_PERMISSION_DENIED = 9,
        FS_RESULT_MEDIA_FATAL = 10,
        FS_RESULT_NO_ENTRY = 11,
        FS_RESULT_MEDIA_NOTHING = 12,
        FS_RESULT_MEDIA_UNKNOWN = 13,
        FS_RESULT_BAD_FORMAT = 14,

        FS_RESULT_PROC_ASYNC = 256,
        FS_RESULT_PROC_DEFAULT,
        FS_RESULT_PROC_UNKNOWN,

        FS_RESULT_CANCELLED = FS_RESULT_CANCELED
    }
    FSResult;

## Description

These enumerator types represent the results of the file system API and the user procedures of the archive.
They are defined as follows.

The following values can be returned as results from the FS library functions.
FS_RESULT_SUCCESS | Indicates success as a result of the function's correct processing. Example: Suppose that `FS_ReadFile` attempts to read 100 bytes of data, but reaches the end of the file after only reading 50 bytes. This is normal behavior and is recorded as successful.
FS_RESULT_FAILURE | Indicates failure as a result of the function's correct processing. Example: This indicates a failure as one of the expected return values for the process when you have read to the end using the `FS_ReadDir` function.
FS_RESULT_BUSY | Indicates that the current command is busy. Strictly speaking, this is not an error because the operation is incomplete. However, we have included this with the errors for the sake of convenience.
FS_RESULT_CANCELED | Indicates that the command was canceled. There are two types of cancels: (1) explicit command cancels by the user, and (2) forced cancel when the archive is unloaded.
FS_RESULT_UNSUPPORTED | Indicates that the archive is not supported by the specified command. This error occurs when the archive that ignores certain commands explicitly returns this as a return value of a user procedure. If this error gets returned unexpectedly, you should double-check for any unique specifications of the archive in question.
FS_RESULT_INVALID_PARAMETER | Indicates that one of the arguments provided is invalid or outside the allowed range. This mostly occurs with NULL pointers or when an invalid handle is specified.
FS_RESULT_NO_MORE_RESOURCE | Indicates that certain resources required for the operation turned out to be insufficient internally. The number of handles that can be opened simultaneously, as well as the upper limit for dynamic memory consumed internally, are different for each archive.
FS_RESULT_ALREADY_DONE | Indicates that the requested operation has already been performed. This will occur if the file specified to `FS_CreateFile()` already exists, for example, or if the directory specified to `FS_DeleteDirectory()` didn't exist to begin with.

FS_RESULT_PERMISSION_DENIED

Indicates that the requested process failed due to a problem of access rights.
This primarily happens in the following cases:

- An attempt is made to open with write permission a read-only file
- An attempt is made to delete a directory that is not empty
- An attempt is made to open a TWL-exclusive file (as specified by the `Put` parameter of the `makerom` tool) in the NITRO environment
- An SD Card is write-protected
- An attempt is made to open a file that is larger than 2 GB, which is not supported by the FS library

FS_RESULT_MEDIA_FATAL | Indicates that a fatal device error is detected in writable media such as a NAND archive or an SD Card archive. Processing cannot continue. Prompt the user to replace or re-insert the SD card, or, if the error is in system save memory (NAND), to have the system repaired.
FS_RESULT_BAD_FORMAT | This will occur if corruption in the file system is detected in writable media such as a NAND archive or an SD Card library. Processing cannot continue. Prompt the user to replace or re-insert the SD card, or, if the error is in system save memory (NAND), reformat the archive using the `NA_FormatTitleArchive` function.
FS_RESULT_NO_ENTRY | Indicates that the specified path does not exist. This error will also occur when trying to create a file under a directory that doesn't exist.
FS_RESULT_MEDIA_NOTHING | The specified archive is located on removable media, and that device was not inserted. Currently, this error is only returned by SD Card archives.
FS_RESULT_MEDIA_UNKNOWN | The specified archive is located on removable media, and an unknown device has been inserted that doesn't have a known file system. Currently, this error is only returned by SD Card archives.
FS_RESULT_ERROR | Indicates that some other detectable error occurred during an operation.
The following are used only as user procedure return values:
FS_RESULT_PROC_ASYNC | Return value when the user procedure returns a temporary control for asynchronous processing. When this value is returned, you must notify the read/write callback as well as the process completion using the `FS_NotifyArchiveAsyncEnd` function.
FS_RESULT_PROC_DEFAULT | The default return value passed to a user procedure. This is the value passed unless a different value/type is called explicitly. The user procedure for the corresponding command will be called the next time as well. If you simply want to hook an existing command, this value is returned every time.
FS_RESULT_PROC_UNKNOWN | The default return value passed to a user procedure when the procedure call flag to the associated command is canceled. The command will not be called again.
FS_RESULT_SUCCESS | You must follow the rules described above to determine about the specific archive in question and return from the procedure accordingly.
FS_RESULT_FAILURE
FS_RESULT_UNSUPPORTED
FS_RESULT_INVALID_PARAMETER
FS_RESULT_NO_MORE_RESOURCE
FS_RESULT_ALREADY_DONE
FS_RESULT_PERMISSION_DENIED
FS_RESULT_MEDIA_FATAL
FS_RESULT_NO_ENTRY
FS_RESULT_ERROR

## See Also

`FSArchive
FS_ARCHIVE_PROC_FUNC
FS_SetArchiveProc`

## Revision History

2009/06/08 Added link to explanation of TWL-exclusive files.
2009/02/05 Expanded explanation of FS_RESULT_PERMISSION_DENIED.
2008/10/21 Added a detailed description of FS_RESULT_MEDIA_FATAL and FS_RESULT_BAD_FORMAT.
2008/07/16 Added conditions for issuing `FS_RESULT_PERMISSION_DENIED`.
2008/06/25 Added `FS_RESULT_MEDIA_NOTHING`, `FS_RESULT_MEDIA_UNKNOWN`, and `FS_RESULT_BAD_FORMAT`.
2008/05/13 Added `FS_RESULT_NO_ENTRY`.
2008/04/42 Clarified the correspondence between error codes and numerical values.
2008/03/12 Added `FS_RESULT_MEDIA_FATAL`.
2007/09/18 Added a value and its description to the enumerated type.
2004/07/12 Added a value and its description to the enumerated type.
2004/07/01 Initial version.

CONFIDENTIAL