1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html xmlns="http://www.w3.org/1999/xhtml"> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=windows-1252" /> 5<meta http-equiv="Content-Style-Type" content="text/css" /> 6<title>FS_OpenFileEx[W]</title> 7<link rel="stylesheet" href="../../css/nitro.css" type="text/css" /> 8</head> 9<body> 10 11<h1>FS_OpenFileEx[W] <img src="../../image/NTR.gif"align="middle"><img src="../../image/TWL.gif" align="middle"></h1> 12<h2>Syntax</h2> 13<pre><code> 14#include <nitro/fs.h> 15 16BOOL FS_OpenFileEx(<a href="../fs_file_type.html">FSFile</a> *file, const char *path, u32 mode); 17BOOL FS_OpenFileExW(<a href="../fs_file_type.html">FSFile</a> *file, const u16 *path, u32 mode); 18</code></pre> 19 20<h2>Arguments</h2> 21<table style="width:100%"> 22<tbody> 23<tr> 24<td style="width:13%"><SPAN class="argument">file</SPAN></td> 25<td style="width:87%"><a href="../fs_file_type.html"><CODE>FSFile</CODE></a> structure where the handle should be stored.</td> 26</tr> 27<tr> 28<td style="width:13%"><SPAN class="argument">path</SPAN></td> 29<td style="width:87%">Path name of file.</td> 30</tr> 31<tr> 32<td style="width:13%"><SPAN class="argument">mode</SPAN></td> 33<td style="width:87%">Combination of <a href="../FS_FILEMODE.html"><CODE>FS_FILEMODE_*</CODE></a> flags that indicate the mode for accessing the file.</td> 34</tr> 35</tbody> 36</table> 37 38<h2>Return Values</h2> 39<p><CODE>TRUE</CODE> if the file handle opens properly; <CODE>FALSE</CODE> otherwise. In case of failure, use the <a href="../file/FS_GetResultCode.html"><CODE>FS_GetResultCode</CODE></a> function to get the error details.</p> 40 41<h2>Description</h2> 42<p>Opens the handle for the specified file.<br />You can use the <CODE>FS_OpenFileEx</CODE> function when the path is specified using <CODE>Shift_JIS</CODE> and the <CODE>FS_OpenFileExW</CODE> function when the path is specified using <CODE>UTF16-LE</CODE>. The results that are obtained will be the same. There are several conditions that apply to files that can be opened.</p> 43<ul> 44<li><font color="red">The file must already exist. It will not be created automatically, even if this function is called with <a href="../FS_FILEMODE.html"><CODE>FS_FILEMODE_W</CODE></a> specified.</font><a href="../directory/FS_CreateFile.html"><CODE>FS_CreateFile</CODE></a> must be used to create a new file.</li> 45<li>To avoid unintentional malfunction due to the fact that the functions for file operations supported by the FS library only work for files under 2 GB, <font color="red">this function will always fail and return <a href="../fs_result_const.html"><CODE>FS_RESULT_PERMISSION_DENIED</CODE></a> if you try to open a file 2 GB or larger.</font></li> 46<li>If you attempt to open a <a href="../overview/about_Archive.html#ROM_LTDFILE">TWL-exclusive file</a> while the system is operating in NITRO mode, the function will fail and return <a href="../fs_result_const.html"><CODE>FS_RESULT_PERMISSION_DENIED</CODE></a>.</li> 47</ul> 48<p>The various functions for file access can be called using the handle that is obtained. After using a handle, you must call <a href="FS_CloseFile.html"><CODE>FS_CloseFile</CODE></a> to free it. 49</p> 50 51<h2>Note</h2> 52<ul> 53<li>This function cannot be called from the interrupt handler (IRQ mode). Also, in some cases processing may not end if interrupts are still disabled.</li> 54<li style='color:Red;'>The structures of opened files are associated with system resources so you cannot move or duplicate information even by copying them to other structures as they are. For details, see <a href="../fs_file_type.html"><CODE>FSFile</CODE> structure</a>.</li> 55</ul> 56 57<h2>See Also</h2> 58<p><a href="../fs_file_type.html"><CODE>FSFile</CODE></a><BR> <a href="../FSDirectoryEntryInfo.html"><CODE>FSDirectoryEntryInfo</CODE></a><BR> <a href="FS_ReadFile.html"><CODE>FS_ReadFile</CODE></a><BR> <a href="FS_WriteFile.html"><CODE>FS_WriteFile</CODE></a><BR> <a href="FS_SeekFile.html"><CODE>FS_SeekFile</CODE></a></p> 59 60<h2>Revision History</h2> 61<p> 622009/07/14 Added mention that copying structure values is not guaranteed.<br /> 2009/06/08 Added link to TWL-specific file explanation.<br />2009/01/08 Added an explanation about TWL-exclusive files.<br />2008/09/02 Added notes concerning a Unicode version of the function.<br />2008/07/16 Revised the description to use <CODE>FS_GetResultCode</CODE> for getting the error code in cases of failure. Added size restriction of 2 GB.<br />2008/06/10 Added the fact that files will not be created automatically.<br />2007/09/18 Initial version. 63</p> 64<hr><p>CONFIDENTIAL</p></body> 65</html> 66
