Difference between revisions of "Bfile OpenFile OS"

From WikiPrizm
Jump to navigationJump to search
(Initial)
 
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Synopsis ==
+
{{syscall
 +
| name = Bfile_OpenFile_OS
 +
| signature = int Bfile_OpenFile_OS(const unsigned short* filename, int mode, int zero)
 +
| synopsis = Opens an existing file in storage memory.
 +
| header = fxcg/file.h
 +
| index = 0x1DA3
 +
| 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.
  
'''Syscall:'''
+
{{BfileTimersWarning}}
  
'''Function declaration:''' int Bfile_OpenFile_OS(const unsigned short* filename, int mode); (See alternative decl.)
+
{{BfileMultipleFilesWarning}}
 
+
}}
This function is used to make a 16 bit string from an 8 bit character array.
+
== Modes ==
 
+
The following table enumerates the known modes which may be passed as the second parameter to this function.
=== Inputs ===
+
{|
* ''const unsigned short*'' '''filename''' - A 16 bit character array, most likely generated by [[Bfile_StrToName_ncpy]].
+
! Mode !! Alias !! Description
* ''int'' '''mode''' - The mode of which the file will be opened with.
+
|-
 
+
| 0 || READ || Read-only
=== Outputs ===
+
|-
* Returns < 0 if an error occurred.
+
| 1 || READ_SHARE || Read-only and cannot be modified by other add-ins (?)
* Returns a handle (0 or greater) on success.
+
|-
 
+
| 2 || WRITE || Write-only
== Comments ==
+
|-
The following are the open modes that can be used:
+
| 3 || READWRITE || Both readable and writable
* 0 - ''READ'' - Opens a file in read-only mode.
+
|-
* 1 - ''READ_SHARE'' - Opens a file in read-only mode and cannot be modified by other add-ins (?)
+
| 4 || READWRITE_SHARE || Both readable and writable and cannot be modified by other add-ins (?)
* 2 - ''WRITE'' - Opens a file in write-only mode.
+
|}
* 3 - ''READWRITE'' - Opens a file in read/write mode.
+
[[Category:Syscalls:Bfile]]
* 4 - ''READWRITE_SHARE'' - Opens a file in read/write mode and cannot be modified by other add-ins (?)
 
 
 
As opposed to fopen, if you attempt to open a file in write mode that does not exist, this function will return a file not found error.  You must use [[Bfile_CreateEntry_OS]].
 
 
 
== Alternative Declaration ==
 
This is a modified declaration that is more descriptive
 
<nowiki>typedef enum
 
{
 
  OPENMODE_READ = 0,
 
  OPENMODE_READ_SHARE,
 
  OPENMODE_WRITE,
 
  OPENMODE_READWRITE,
 
  OPENMODE_READWRITE_SHARE
 
} FILE_MODE;
 
 
 
int Bfile_OpenFile_OS(const unsigned short* filename, FILE_MODE mode);
 
</nowiki>
 

Latest revision as of 18:25, 3 August 2014


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.

Mode Alias Description
0 READ Read-only
1 READ_SHARE Read-only and cannot be modified by other add-ins (?)
2 WRITE Write-only
3 READWRITE Both readable and writable
4 READWRITE_SHARE Both readable and writable and cannot be modified by other add-ins (?)