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=
"alternate" hreflang=
"ja" title=
"Japanese" href=
"../ja/open.html">
8 <link rel=
"stylesheet" href=
"../css_e.css" type=
"text/css" media=
"screen" title=
"ELM Default">
9 <title>FatFs - f_open
</title>
14 <div class=
"para func">
16 <p>The f_open function creates a
<em>file object
</em> to be used to access the file.
</p>
19 FIL*
<span class=
"arg">fp
</span>,
<span class=
"c">/* [OUT] Pointer to the file object structure */
</span>
20 const TCHAR*
<span class=
"arg">path
</span>,
<span class=
"c">/* [IN] File name */
</span>
21 BYTE
<span class=
"arg">mode
</span> <span class=
"c">/* [IN] Mode flags */
</span>
26 <div class=
"para arg">
30 <dd>Pointer to the blank file object structure to be created.
</dd>
32 <dd>Pointer to a null-terminated string that specifies the
<a href=
"filename.html">file name
</a> to open or create.
</dd>
34 <dd>Mode flags that specifies the type of access and open method for the file. It is specified by a combination of following flags.
<br>
36 <tr><th>Value
</th><th>Description
</th></tr>
37 <tr><td>FA_READ
</td><td>Specifies read access to the object. Data can be read from the file. Combine with
<tt>FA_WRITE
</tt> for read-write access.
</td></tr>
38 <tr><td>FA_WRITE
</td><td>Specifies write access to the object. Data can be written to the file. Combine with
<tt>FA_READ
</tt> for read-write access.
</td></tr>
39 <tr><td>FA_OPEN_EXISTING
</td><td>Opens the file. The function fails if the file is not existing. (Default)
</td></tr>
40 <tr><td>FA_OPEN_ALWAYS
</td><td>Opens the file if it is existing. If not, a new file is created.
<br>
41 To append data to the file, use
<a href=
"lseek.html"><tt>f_lseek()
</tt></a> function after file open in this method.
</td></tr>
42 <tr><td>FA_CREATE_NEW
</td><td>Creates a new file. The function fails with
<tt>FR_EXIST
</tt> if the file is existing.
</td></tr>
43 <tr><td>FA_CREATE_ALWAYS
</td><td>Creates a new file. If the file is existing, it will be truncated and overwritten.
</td></tr>
50 <div class=
"para ret">
51 <h4>Return Values
</h4>
53 <a href=
"rc.html#ok">FR_OK
</a>,
54 <a href=
"rc.html#de">FR_DISK_ERR
</a>,
55 <a href=
"rc.html#ie">FR_INT_ERR
</a>,
56 <a href=
"rc.html#nr">FR_NOT_READY
</a>,
57 <a href=
"rc.html#ok">FR_NO_FILE
</a>,
58 <a href=
"rc.html#np">FR_NO_PATH
</a>,
59 <a href=
"rc.html#in">FR_INVALID_NAME
</a>,
60 <a href=
"rc.html#de">FR_DENIED
</a>,
61 <a href=
"rc.html#ex">FR_EXIST
</a>,
62 <a href=
"rc.html#io">FR_INVALID_OBJECT
</a>,
63 <a href=
"rc.html#wp">FR_WRITE_PROTECTED
</a>,
64 <a href=
"rc.html#id">FR_INVALID_DRIVE
</a>,
65 <a href=
"rc.html#ne">FR_NOT_ENABLED
</a>,
66 <a href=
"rc.html#ns">FR_NO_FILESYSTEM
</a>,
67 <a href=
"rc.html#tm">FR_TIMEOUT
</a>,
68 <a href=
"rc.html#lo">FR_LOCKED
</a>,
69 <a href=
"rc.html#nc">FR_NOT_ENOUGH_CORE
</a>,
70 <a href=
"rc.html#tf">FR_TOO_MANY_OPEN_FILES
</a>
75 <div class=
"para desc">
77 <p>After
<tt>f_open()
</tt> function succeeded, the file object is valid. The file object is used for subsequent read/write functions to identify the file. To close an open file, use
<a href=
"close.html"><tt>f_close()
</tt></a> function. If the file is modified and not closed properly, the file data will be collapsed.
</p>
78 <p>If duplicated file open is needed, read
<a href=
"appnote.html#dup">here
</a> carefully. However duplicated open of a file with write mode flag is always prohibited.
</p>
79 <p>Before using any file function, a work area (file system object) must be registered to the logical drive with
<a href=
"mount.html"><tt>f_mount()
</tt></a> function. All API functions except for
<a href=
"fdisk.html"><tt>f_fdisk()
</tt></a> function can work after this procedure.
</p>
83 <div class=
"para comp">
85 <p>Always available. The mode flags,
<tt>FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW and FA_OPEN_ALWAYS
</tt>, are not available when
<tt>_FS_READONLY ==
1</tt>.
</p>
89 <div class=
"para use">
92 <span class=
"c">/* Read a text file and display it */
</span>
94 FATFS FatFs;
<span class=
"c">/* Work area (file system object) for logical drive */
</span>
98 FIL fil;
<span class=
"c">/* File object */
</span>
99 char line[
82];
<span class=
"c">/* Line buffer */
</span>
100 FRESULT fr;
<span class=
"c">/* FatFs return code */
</span>
103 <span class=
"c">/* Register work area to the default drive */
</span>
104 f_mount(
&FatFs,
"",
0);
106 <span class=
"c">/* Open a text file */
</span>
107 fr = f_open(
&fil,
"message.txt", FA_READ);
108 if (fr) return (int)fr;
110 <span class=
"c">/* Read all lines and display it */
</span>
111 while (f_gets(line, sizeof line,
&fil))
114 <span class=
"c">/* Close the file */
</span>
121 <span class=
"c">/* Copy a file
"file.bin" on the drive
1 to drive
0 */
</span>
125 FATFS fs[
2];
<span class=
"c">/* Work area (file system object) for logical drives */
</span>
126 FIL fsrc, fdst;
<span class=
"c">/* File objects */
</span>
127 BYTE buffer[
4096];
<span class=
"c">/* File copy buffer */
</span>
128 FRESULT fr;
<span class=
"c">/* FatFs function common result code */
</span>
129 UINT br, bw;
<span class=
"c">/* File read/write count */
</span>
132 <span class=
"c">/* Register work area for each logical drive */
</span>
133 f_mount(
&fs[
0],
"0:",
0);
134 f_mount(
&fs[
1],
"1:",
0);
136 <span class=
"c">/* Open source file on the drive
1 */
</span>
137 fr = f_open(
&fsrc,
"1:file.bin", FA_OPEN_EXISTING | FA_READ);
138 if (fr) return (int)fr;
140 <span class=
"c">/* Create destination file on the drive
0 */
</span>
141 fr = f_open(
&fdst,
"0:file.bin", FA_CREATE_ALWAYS | FA_WRITE);
142 if (fr) return (int)fr;
144 <span class=
"c">/* Copy source to destination */
</span>
146 fr = f_read(
&fsrc, buffer, sizeof buffer,
&br);
<span class=
"c">/* Read a chunk of source file */
</span>
147 if (fr || br ==
0) break;
<span class=
"c">/* error or eof */
</span>
148 fr = f_write(
&fdst, buffer, br,
&bw);
<span class=
"c">/* Write it to the destination file */
</span>
149 if (fr || bw
< br) break;
<span class=
"c">/* error or disk full */
</span>
152 <span class=
"c">/* Close open files */
</span>
156 <span class=
"c">/* Unregister work area prior to discard it */
</span>
157 f_mount(NULL,
"0:",
0);
158 f_mount(NULL,
"1:",
0);
166 <div class=
"para ref">
168 <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>
171 <p class=
"foot"><a href=
"../00index_e.html">Return
</a></p>