nn::fs Namespace

Description

The namespace of the file system library.

You must first call the nn::fs::Initialize function to initialize the library before using any of the functions or classes in the nn::fs namespace.

The CTR file system is a collection of archives distinguished by their archive names. Each archive identifies files and directories and carries out the specified operation by receiving archive path name. Archive types differ in various ways such as their available operations, their restrictions on path names, and the number of files that can be opened, but all types can generally be accessed using the same interface.

The method of writing code for error handling is different for the FS library than for other libraries.
In addition, the handling method may differ depending on the returned Result value and the type of archive being manipulated.

If you want to know if this error has occurred based on the content of results displayed on the error display screen, see this page.

The CTR file system allows you to set access priorities. Refer to this page when you use file accesses that must be real-time.

For tips on improving performance when using the CTR file system, see the following section.

Namespace

nn::fs::hio A namespace that includes functions used to directly access files on a PC (for debugging purposes).

Classes

File and Directory Operations
nn::fs::Directory A class used for directory operations.
nn::fs::FileInputStream Class for reading from files.
nn::fs::FileOutputStream Class for writing to files.
nn::fs::FileStream Class for reading from and writing to files.
Result
nn::fs::ResultNotFound A file, archive, or other file-system entry could not be found.
nn::fs::ResultMediaNotFound Could not find or recognize media. Errors associated with nn::fs::ResultNotFound.
nn::fs::ResultAlreadyExists A file, archive, or other file-system entry already exists.
nn::fs::ResultNotEnoughSpace There is no free space.
nn::fs::ResultArchiveInvalidated An archive has become invalid.
nn::fs::ResultOperationDenied An operation was denied.
nn::fs::ResultWriteProtected Write-protected. This error is subsumed by the nn::fs::ResultOperationDenied class.
nn::fs::ResultMediaAccessError An error occurred during media access. This error is subsumed by the nn::fs::ResultOperationDenied class.
nn::fs::ResultNotFormatted Not formatted.
nn::fs::ResultBadFormat Invalid format.
nn::fs::ResultVerificationFailed Either verification failed or some form of tampering was detected.
nn::fs::ResultOutOfResource Insufficient resources. You must not allow this error to occur in retail products.
nn::fs::ResultAccessDenied No access rights. You must not allow this error to occur in retail products.
nn::fs::ResultInvalidArgument The argument is invalid. You must not allow this error to occur in retail products.
nn::fs::ResultNotInitialized A process was called prior to the necessary initialization. You must not allow this error to occur in retail products.
nn::fs::ResultAlreadyInitialized Initialization was run twice. You must not allow this error to occur in retail products.
nn::fs::ResultUnsupportedOperation A feature that is not supported or an operation that is not allowed. You must not allow this error to occur in retail products.

Structures

nn::fs::Attributes Structure that gives attribute information for directory entries.
nn::fs::ShortName Structure that indicates the short name of a directory entry.
nn::fs::DirectoryEntry Structure representing a directory entry.

Enumerated Types

OpenMode Enumerated constant that specifies file open modes.
PositionBase Enumerated constant that indicates the position of file read/write operations.
PriorityForApplication An enumerated type that represents file access priorities.

typedef Definitions

FileReader A typedef for FileInputStream.
FileWriter Typedef for FileOutputStream.
ExtSaveDataId A typedef representing an extended save data number.

Constants

S LATENCY_RECOMMENDED_SD_MAX const s64 This constant is the actual measured maximum time (in milliseconds) it takes in a pure SD Card usage environment when a conflict arises for file system resources with BOSS in the background. This value is the recommended value for the FS Latency Emulation setting to use with the Config tool.
S UI_BLOCK_SIZE const s64 The unit (in bytes) used for the display of save data shown in the Home Menu.

Functions

ROM Archives
GetRomRequiredMemorySize Gets the size of memory needed to mount a ROM archive.
MountRom Mounts a ROM archive.
Save Data Archives
FormatSaveData Formats a save data region.
GetSaveDataFormatInfo Gets the format parameter for the save data region.
MountSaveData Mounts a save data archive.
MountDemoSaveData Mounts the save data archive for a demo application.
CommitSaveData Commits a change to the save data.
Expanded Save Data Archives
CreateExtSaveData Creates an expanded save data memory region.
GetExtSaveDataFormatInfo Gets the format parameter for the extended save data region.
MountExtSaveData Mounts expanded save data.
DeleteExtSaveData Deletes expanded save data.
For Debugging Purposes
MountSdmc Mounts an archive that directly accesses the SD Card (for debugging only).
InitializeLatencyEmulation Initializes the feature for emulating the operations of a non-volatile memory device that has become degraded, and the operations when a conflict arises for FS resources with a process in the background.
ForceEnableLatencyEmulation This function can no longer be used to enable or disable latency emulation. At present, this function only calls the InitializeLatencyEmulation function internally.
ForceDisableLatencyEmulation This function can no longer be used to enable or disable latency emulation. At present, this function only calls the InitializeLatencyEmulation function internally.
Priority Settings
SetArchivePriority Sets an archive's priority.
SetPriority Sets the priority of the entire file system.
Support for Preventing Rollback of Save Data
SetSaveDataSecureValue Writes the specified bit64 value to a secure region for use with the save data rollback prevention feature.
VerifySaveDataSecureValue Verifies a value stored in a secure region for use with the save data rollback prevention feature.
VerifySaveDataSecureValueLoosely Performs the comparison with an application-linked, 64-bit value.
Initialization
Initialize Initializes the fs library.
SD Card
RegisterSdmcInsertedEvent Registers the nn::os::LightEvent object that is signaled when an SD Card is inserted.
UnregisterSdmcInsertedEvent Unregisters the nn::fs::RegisterSdmcInsertedEvent object.
RegisterSdmcEjectedEvent Registers the nn::os::LightEvent object that is signaled when an SD Card is pulled out.
UnregisterSdmcEjectedEvent Unregisters the nn::fs::RegisterSdmcEjectedEvent object.
IsSdmcInserted Returns a value indicating whether an SD Card has been inserted.
IsSdmcWritable Returns a value indicating whether an SD Card is writable.
GetSdmcSize Gets the total capacity and amount of free space on an SD Card.
MountSdmcWriteOnly Mounts the archive that directly accesses the SD Memory Card. This is a write-only archive. File read operations are not permitted. Directory read operations are also not permitted.
File and Directory Operations
DeleteFile Deletes a file.
TryDeleteFile Deletes a file.
RenameFile Renames a file.
TryRenameFile Renames a file.
DeleteDirectory Deletes a directory.
TryDeleteDirectory Deletes a directory.
TryDeleteDirectoryRecursively Deletes directories recursively.
CreateFile Creates a file.
TryCreateFile Creates a file.
CreateDirectory Creates a directory.
TryCreateDirectory Creates a directory.
RenameDirectory Renames a directory.
TryRenameDirectory Renames a directory.
Other
Unmount Unmounts an archive.
CreateArchiveAlias Enables an archive to be accessed using a different archive name.
GetArchiveFreeBytes Gets the amount of free space in the archive.
SetAnalysisLog Enables or disables output of a log for analyzing file access.

Revision History

2012/04/26
Deleted the nn::fs::GetSaveDataSecureValue function.
2012/01/23
Added a description of improving file access efficiency.
2011/10/12
Added functions for setting access priorities.
2011/03/24
Added a definition of UI_BLOCK_SIZE.
2011/02/21
Added the MountSdmcWriteOnly function.
2011/02/10
Added a link to the List of Descriptions.
2011/01/21
Added the GetSaveDataFormatInfo and GetExtSaveDataFormatInfo functions.
2010/12/09
Listed Result values that must be removed during development and added information about the nn::fs::Attributes and nn::fs::DirectoryEntry structures.
2010/11/25
Published the GetSdmcSize function.
2010/11/13
Added the CommitSaveData and DeleteExtSaveData functions.
2010/11/09
Removed the GetFileSystemSize and ReadExtSaveDataIcon functions.
2010/10/30
Added archive limitations, and an explanation of Result objects.
2010/09/22
Added a description of expanded save data.
2010/09/10
Added the MountSdmc function.
2010/09/09
Deleted the InitializeForFileSystemEvent, WaitForInsertSdmc, and WaitForEjectSdmc functions. Added the RegisterSdmcInsertedEvent, UnregisterSdmcInsertedEvent, RegisterSdmcEjectedEvent, and UnregisterSdmcEjectedEvent functions.
2010/01/07
Initial version.

CONFIDENTIAL