Difference between revisions of "Bfile OpenFile OS"

From WikiPrizm
Jump to navigationJump to search
(Initial)
 
Line 1: Line 1:
== Synopsis ==
+
{{syscall
 
+
| signature = int Bfile_OpenFile_OS(const unsigned short* filename, int mode);
'''Syscall:'''
+
| synopsis = Opens an existing file in storage memory.
 
+
| parameters =
'''Function declaration:''' int Bfile_OpenFile_OS(const unsigned short* filename, int mode); (See alternative decl.)
+
* '''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]].
This function is used to make a 16 bit string from an 8 bit character array.
+
| 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.
=== Inputs ===
+
}}
* ''const unsigned short*'' '''filename''' - A 16 bit character array, most likely generated by [[Bfile_StrToName_ncpy]].
+
== Modes ==
* ''int'' '''mode''' - The mode of which the file will be opened with.
+
The following table enumerates the known modes which may be passed as the second parameter to this function.
 
+
{|
=== Outputs ===
+
! Mode !! Alias !! Description
* Returns < 0 if an error occurred.
+
|-
* Returns a handle (0 or greater) on success.
+
| 0 || READ || Read-only
 
+
|-
== Comments ==
+
| 1 || READ_SHARE || Read-only and cannot be modified by other add-ins (?)
The following are the open modes that can be used:
+
|-
* 0 - ''READ'' - Opens a file in read-only mode.
+
| 2 || WRITE || Write-only
* 1 - ''READ_SHARE'' - Opens a file in read-only mode and cannot be modified by other add-ins (?)
+
|-
* 2 - ''WRITE'' - Opens a file in write-only mode.
+
| 3 || READWRITE || Both readable and writable
* 3 - ''READWRITE'' - Opens a file in read/write mode.
+
|-
* 4 - ''READWRITE_SHARE'' - Opens a file in read/write mode and cannot be modified by other add-ins (?)
+
| 4 || READWRITE_SHARE || Both readable and writable 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>
 

Revision as of 19:15, 21 May 2012


Synopsis

Header: Not documented
Syscall index: Not documented
Function signature: int Bfile_OpenFile_OS(const unsigned short* filename, int mode);

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.

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.

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 (?)