Synopsis #

Header: fxcg/file.h
Syscall index: 0x1DA3
Function signature: int Bfile_OpenFile_OS(const unsigned short* filename, int mode, int zero)

Opens an existing file in storage memory.

Parameters #

• filename - A 16 bit character array specifying the name of the desired file, most likely generated by Bfile_StrToName_ncpy.
• mode - The mode of which the file will be opened with. See #Modes.
• zero - Meaning unknown, must be set to zero (that’s what the OS does). Otherwise there will be unpredictable results.

Returns #

A handle to the opened file, or a negative number on failure.

Comments #

Unlike the standard library’s fopen, this function returns with a file not found error if attempting to open a nonexistent file in write mode. Use Bfile_CreateEntry_OS to create a new file, then open it to write.

Using Bfile functions while user timers are installed can cause SYSTEM ERRORs and other undefined behavior, especially with functions that change data on the file system. Make sure to stop and uninstall all timers before using Bfile functions (and optionally restore them later). See Incompatibility_between_Bfile_Syscalls_and_Timers for more information.

The OS supports up to 16 simultaneously open files and file finding handles, but strange behavior (most likely a OS bug) occurs if files other than the one in the first handle slot are located in directories (other than the root). This is why the file copying function of the Utilities add-in, which opens both the source and the destination file at once, uses a temporary file in the filesystem root as the destination file, and only moves it to the intended correct destination path in the end.

Modes #

The following table enumerates the known modes which may be passed as the second parameter to this function.