Difference between revisions of "Bfile CreateEntry OS"

From WikiPrizm
Jump to navigationJump to search
(Initial version)
 
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Synopsis ==
+
{{syscall
 +
|name = Bfile_CreateEntry_OS
 +
|header = fxcg/file.h
 +
|index = 0x1DAE
 +
|signature = int Bfile_CreateEntry_OS(const unsigned short* filename, int mode, int *size)
 +
|synopsis = Creates a file or folder in storage memory.
 +
|parameters =
 +
* '''filename''' - A 16 bit character array, most likely generated by [[Bfile_StrToName_ncpy]].
 +
* '''mode''' - Used to determine whether a file or folder will be made.
 +
* '''size''' - A pointer to the size of the file, NULL if making a folder.
 +
|returns = 0 on success, or a negative error code on failure.
 +
|comments = Does not return a handle for created files.  Use [[Bfile_OpenFile_OS]] after a successful creation.
  
'''Syscall:'''
 
 
'''Function declaration:''' int Bfile_CreateEntry_OS(const unsigned short* filename, int mode, int *size); (See alternative decl.)
 
 
This function is used to create a file or folder in the storage memory.
 
 
=== Inputs ===
 
* ''const unsigned short*'' '''filename''' - A 16 bit character array, most likely generated by [[Bfile_StrToName_ncpy]].
 
* ''int'' '''mode''' - Used to determine whether a file or folder will be made.
 
* ''int*'' '''size''' - A pointer to the size of the file, NULL if making a folder.
 
 
=== Outputs ===
 
* Returns < 0 if an error occurred.
 
* Returns 0 on success.  Does not return a handle for created files.  Use [[Bfile_OpenFile_OS]] after a successful creation.
 
 
== Comments ==
 
 
The following are the modes that can be used:
 
The following are the modes that can be used:
 
* 1 - ''CREATEMODE_FILE'' - Makes a file using the size provided.
 
* 1 - ''CREATEMODE_FILE'' - Makes a file using the size provided.
 
* 5 - ''CREATEMODE_FOLDER'' - Makes a folder.  Size should be NULL.
 
* 5 - ''CREATEMODE_FOLDER'' - Makes a folder.  Size should be NULL.
  
This function is a combination of fopen's file creation and mkdir.  Please note that the size of the file must be set upon creation.  Files are '''not''' dynamically resizable.
+
This function is a combination of fopen's file creation and mkdir.  Please note that the size of the file must be set upon creation.  Files are dynamically expandable (using [[Bfile_WriteFile_OS]] past the end of a file), but currently there's no known way to shrink a file. You can delete and re-create to reduce a file's size; if you expect to do it frequently, using the [[:Category:Syscalls:MCS|main memory]] may be more appropriate.
 
 
== Alternative Declaration ==
 
This is a modified declaration that is more descriptive
 
<nowiki>typedef enum
 
{
 
  CREATEMODE_FILE = 1,
 
  CREATEMODE_FOLDER = 5
 
} CREATE_MODE;
 
  
int Bfile_OpenFile_OS(const unsigned short* filename, CREATE_MODE mode, int* size);
+
{{BfileTimersWarning}}
</nowiki>
+
}}
 +
[[Category:Syscalls:Bfile]]

Latest revision as of 19:27, 29 July 2014


Synopsis

Header: fxcg/file.h
Syscall index: 0x1DAE
Function signature: int Bfile_CreateEntry_OS(const unsigned short* filename, int mode, int *size)

Creates a file or folder in storage memory.

Parameters

  • filename - A 16 bit character array, most likely generated by Bfile_StrToName_ncpy.
  • mode - Used to determine whether a file or folder will be made.
  • size - A pointer to the size of the file, NULL if making a folder.

Returns

0 on success, or a negative error code on failure.

Comments

Does not return a handle for created files. Use Bfile_OpenFile_OS after a successful creation.

The following are the modes that can be used:

  • 1 - CREATEMODE_FILE - Makes a file using the size provided.
  • 5 - CREATEMODE_FOLDER - Makes a folder. Size should be NULL.

This function is a combination of fopen's file creation and mkdir. Please note that the size of the file must be set upon creation. Files are dynamically expandable (using Bfile_WriteFile_OS past the end of a file), but currently there's no known way to shrink a file. You can delete and re-create to reduce a file's size; if you expect to do it frequently, using the main memory may be more appropriate.

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.