1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="up" title="FatFs" href="../00index_e.html">
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">
<title>FatFs - f_open</title>
</head>
<body>
<div class="para">
<h2>f_open</h2>
<p>The f_open function creates a <em>file object</em> to be used to access the file.</p>
<pre>
FRESULT f_open (
FIL* <em>FileObject</em>, /* Pointer to the blank file object structure */
const XCHAR* <em>FileName</em>, /* Pointer to the file neme */
BYTE <em>ModeFlags</em> /* Mode flags */
);
</pre>
</div>
<div class="para">
<h4>Parameters</h4>
<dl class="par">
<dt>FileObject</dt>
<dd>Pointer to the file object structure to be created.</dd>
<dt>FileName</dt>
<dd>Pointer to a null-terminated string that specifies the <a href="filename.html">file name</a> to create or open.</dd>
<dt>ModeFlags</dt>
<dd>Specifies the type of access and open method for the file. It is specified by a combination of following flags.<br>
<table class="lst">
<tr><th>Value</th><th>Description</th></tr>
<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>
<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>
<tr><td>FA_OPEN_EXISTING</td><td>Opens the file. The function fails if the file is not existing. (Default)</td></tr>
<tr><td>FA_OPEN_ALWAYS</td><td>Opens the file, if it is existing. If not, a new file is created.</td></tr>
<tr><td>FA_CREATE_NEW</td><td>Creates a new file. The function fails if the file is already existing.</td></tr>
<tr><td>FA_CREATE_ALWAYS</td><td>Creates a new file. If the file is existing, it is truncated and overwritten.</td></tr>
</table>
</dd>
</dl>
</div>
<div class="para">
<h4>Return Values</h4>
<dl class="ret">
<dt>FR_OK (0)</dt>
<dd>The function succeeded and the file object is valid.</dd>
<dt>FR_NO_FILE</dt>
<dd>Could not find the file.</dd>
<dt>FR_NO_PATH</dt>
<dd>Could not find the path.</dd>
<dt>FR_INVALID_NAME</dt>
<dd>The file name is invalid.</dd>
<dt>FR_INVALID_DRIVE</dt>
<dd>The drive number is invalid.</dd>
<dt>FR_EXIST</dt>
<dd>The file is already existing.</dd>
<dt>FR_DENIED</dt>
<dd>The required access was denied due to one of the following reasons:
<ul><li>Write mode open of a read-only file.</li>
<li>File cannot be created due to a read-only file or same name directory is existing.</li>
<li>File cannot be created due to the directory table or disk is full.</li></ul></dd>
<dt>FR_NOT_READY</dt>
<dd>The disk drive cannot work due to no medium in the drive or any other reason.</dd>
<dt>FR_WRITE_PROTECTED</dt>
<dd>Write mode open or creation under the medium is write protected.</dd>
<dt>FR_DISK_ERR</dt>
<dd>The function failed due to an error in the disk function.</dd>
<dt>FR_INT_ERR</dt>
<dd>The function failed due to a wrong FAT structure or an internal error.</dd>
<dt>FR_NOT_ENABLED</dt>
<dd>The logical drive has no work area.</dd>
<dt>FR_NO_FILESYSTEM</dt>
<dd>There is no valid FAT volume on the disk.</dd>
</dl>
</div>
<div class="para">
<h4>Description</h4>
<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>
<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>
</div>
<div class="para">
<h4>QuickInfo</h4>
<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>
</div>
<div class="para">
<h4>Example (File Copy)</h4>
<pre>
void main (void)
{
FATFS fs[2]; /* Work area (file system object) for logical drives */
FIL fsrc, fdst; /* file objects */
BYTE buffer[4096]; /* file copy buffer */
FRESULT res; /* FatFs function common result code */
UINT br, bw; /* File R/W count */
/* Register work area for logical drives */
f_mount(0, &fs[0]);
f_mount(1, &fs[1]);
/* Open source file on the drive 1 */
res = f_open(&fsrc, "1:srcfile.dat", FA_OPEN_EXISTING | FA_READ);
if (res) die(res);
/* Create destination file on the drive 0 */
res = f_open(&fdst, "0:dstfile.dat", FA_CREATE_ALWAYS | FA_WRITE);
if (res) die(res);
/* Copy source to destination */
for (;;) {
res = f_read(&fsrc, buffer, sizeof(buffer), &br);
if (res || br == 0) break; /* error or eof */
res = f_write(&fdst, buffer, br, &bw);
if (res || bw < br) break; /* error or disk full */
}
/* Close open files */
f_close(&fsrc);
f_close(&fdst);
/* Unregister work area prior to discard it */
f_mount(0, NULL);
f_mount(1, NULL);
}
</pre>
</div>
<div class="para">
<h4>See Also</h4>
<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>
</div>
<p class="foot"><a href="../00index_e.html">Return</a></p>
</body>
</html>
|
