1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4 <meta http-equiv=
"Content-Type" content=
"text/html; charset=iso-8859-1">
5 <meta http-equiv=
"Content-Style-Type" content=
"text/css">
6 <link rel=
"up" title=
"FatFs" href=
"../00index_e.html">
7 <link rel=
"stylesheet" href=
"../css_e.css" type=
"text/css" media=
"screen" title=
"ELM Default">
8 <title>FatFs - f_open
</title>
15 <p>The f_open function creates a
<em>file object
</em> to be used to access the file.
</p>
18 FIL*
<em>FileObject
</em>, /* Pointer to the blank file object structure */
19 const XCHAR*
<em>FileName
</em>, /* Pointer to the file neme */
20 BYTE
<em>ModeFlags
</em> /* Mode flags */
29 <dd>Pointer to the file object structure to be created.
</dd>
31 <dd>Pointer to a null-terminated string that specifies the
<a href=
"filename.html">file name
</a> to create or open.
</dd>
33 <dd>Specifies the type of access and open method for the file. It is specified by a combination of following flags.
<br>
35 <tr><th>Value
</th><th>Description
</th></tr>
36 <tr><td>FA_READ
</td><td>Specifies read access to the object. Data can be read from the file.
<br>Combine with FA_WRITE for read-write access.
</td></tr>
37 <tr><td>FA_WRITE
</td><td>Specifies write access to the object. Data can be written to the file.
<br>Combine with FA_READ for read-write access.
</td></tr>
38 <tr><td>FA_OPEN_EXISTING
</td><td>Opens the file. The function fails if the file is not existing. (Default)
</td></tr>
39 <tr><td>FA_OPEN_ALWAYS
</td><td>Opens the file, if it is existing. If not, a new file is created.
</td></tr>
40 <tr><td>FA_CREATE_NEW
</td><td>Creates a new file. The function fails if the file is already existing.
</td></tr>
41 <tr><td>FA_CREATE_ALWAYS
</td><td>Creates a new file. If the file is existing, it is truncated and overwritten.
</td></tr>
49 <h4>Return Values
</h4>
52 <dd>The function succeeded and the file object is valid.
</dd>
54 <dd>Could not find the file.
</dd>
56 <dd>Could not find the path.
</dd>
57 <dt>FR_INVALID_NAME
</dt>
58 <dd>The file name is invalid.
</dd>
59 <dt>FR_INVALID_DRIVE
</dt>
60 <dd>The drive number is invalid.
</dd>
62 <dd>The file is already existing.
</dd>
64 <dd>The required access was denied due to one of the following reasons:
65 <ul><li>Write mode open of a read-only file.
</li>
66 <li>File cannot be created due to a read-only file or same name directory is existing.
</li>
67 <li>File cannot be created due to the directory table or disk is full.
</li></ul></dd>
69 <dd>The disk drive cannot work due to no medium in the drive or any other reason.
</dd>
70 <dt>FR_WRITE_PROTECTED
</dt>
71 <dd>Write mode open or creation under the medium is write protected.
</dd>
73 <dd>The function failed due to an error in the disk function.
</dd>
75 <dd>The function failed due to a wrong FAT structure or an internal error.
</dd>
76 <dt>FR_NOT_ENABLED
</dt>
77 <dd>The logical drive has no work area.
</dd>
78 <dt>FR_NO_FILESYSTEM
</dt>
79 <dd>There is no valid FAT volume on the disk.
</dd>
86 <p>A file object is created when the function succeeded. The file object is used for subsequent read/write functions to refer to the file. When close an open file object, use
<a href=
"close.html">f_close
</a> function. If the modified file is not closed, the file may be collapsed.
</p>
87 <p>Before using any file function, a work area (file system object) must be given to the logical drive with
<a href=
"mount.html">f_mount
</a> function. All file functions can work after this procedure.
</p>
93 <p>Always available. The mode flags,
<tt>FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW, FA_OPEN_ALWAYS
</tt>, are not available when
<tt>_FS_READONLY ==
1</tt>.
</p>
98 <h4>Example (File Copy)
</h4>
102 FATFS fs[
2]; /* Work area (file system object) for logical drives */
103 FIL fsrc, fdst; /* file objects */
104 BYTE buffer[
4096]; /* file copy buffer */
105 FRESULT res; /* FatFs function common result code */
106 UINT br, bw; /* File R/W count */
109 /* Register work area for logical drives */
110 f_mount(
0,
&fs[
0]);
111 f_mount(
1,
&fs[
1]);
113 /* Open source file on the drive
1 */
114 res = f_open(
&fsrc,
"1:srcfile.dat", FA_OPEN_EXISTING | FA_READ);
117 /* Create destination file on the drive
0 */
118 res = f_open(
&fdst,
"0:dstfile.dat", FA_CREATE_ALWAYS | FA_WRITE);
121 /* Copy source to destination */
123 res = f_read(
&fsrc, buffer, sizeof(buffer),
&br);
124 if (res || br ==
0) break; /* error or eof */
125 res = f_write(
&fdst, buffer, br,
&bw);
126 if (res || bw
< br) break; /* error or disk full */
129 /* Close open files */
133 /* Unregister work area prior to discard it */
143 <p><tt><a href=
"read.html">f_read
</a>,
<a href=
"write.html">f_write
</a>,
<a href=
"close.html">f_close
</a>,
<a href=
"sfile.html">FIL
</a>,
<a href=
"sfatfs.html">FATFS
</a></tt></p>
146 <p class=
"foot"><a href=
"../00index_e.html">Return
</a></p>