]> cloudbase.mooo.com Git - z180-stamp.git/blame - fatfs/doc/en/open.html
projects / z180-stamp.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Merge branch 'chan-fatfs' into fatfs-integration
[z180-stamp.git] / fatfs / doc / en / open.html
CommitLineData
53668523
L		 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r
2<html lang="en">\r
3<head>\r
4<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">\r
5<meta http-equiv="Content-Style-Type" content="text/css">\r
6<link rel="up" title="FatFs" href="../00index_e.html">\r
7<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/open.html">\r
8<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">\r
9<title>FatFs - f_open</title>\r
10</head>\r
11\r
12<body>\r
13\r
14<div class="para func">\r
15<h2>f_open</h2>\r
16<p>The f_open function creates a <em>file object</em> to be used to access the file.</p>\r
17<pre>\r
18FRESULT f_open (\r
19 FIL* <span class="arg">fp</span>, <span class="c">/* [OUT] Pointer to the file object structure */</span>\r
20 const TCHAR* <span class="arg">path</span>, <span class="c">/* [IN] File name */</span>\r
21 BYTE <span class="arg">mode</span> <span class="c">/* [IN] Mode flags */</span>\r
22);\r
23</pre>\r
24</div>\r
25\r
26<div class="para arg">\r
27<h4>Parameters</h4>\r
28<dl class="par">\r
29<dt>fp</dt>\r
70702af1 30<dd>Pointer to the blank file object structure.</dd>\r
53668523 31<dt>path</dt>\r
70702af1 32<dd>Pointer to the null-terminated string that specifies the <a href="filename.html">file name</a> to open or create.</dd>\r
53668523
L		 33<dt>mode</dt>\r
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>\r
35<table class="lst">\r
70702af1
L		 36<tr><th>Value</th><th>Meaning</th></tr>\r
37<tr><td>FA_READ</td><td>Specifies read access to the object. Data can be read from the file.</tr>\r
53668523
L		 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>\r
39<tr><td>FA_OPEN_EXISTING</td><td>Opens the file. The function fails if the file is not existing. (Default)</td></tr>\r
53668523
L		 40<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>\r
41<tr><td>FA_CREATE_ALWAYS</td><td>Creates a new file. If the file is existing, it will be truncated and overwritten.</td></tr>\r
70702af1
L		 42<tr><td>FA_OPEN_ALWAYS</td><td>Opens the file if it is existing. If not, a new file will be created.</td></tr>\r
43<tr><td>FA_OPEN_APPEND</td><td>Same as <tt>FA_OPEN_ALWAYS</tt> except read/write pointer is set end of the file.</td></tr>\r
53668523
L		 44</table>\r
45</dd>\r
46</dl>\r
47</div>\r
48\r
49\r
50<div class="para ret">\r
51<h4>Return Values</h4>\r
52<p>\r
53<a href="rc.html#ok">FR_OK</a>,\r
54<a href="rc.html#de">FR_DISK_ERR</a>,\r
55<a href="rc.html#ie">FR_INT_ERR</a>,\r
56<a href="rc.html#nr">FR_NOT_READY</a>,\r
57<a href="rc.html#ok">FR_NO_FILE</a>,\r
58<a href="rc.html#np">FR_NO_PATH</a>,\r
59<a href="rc.html#in">FR_INVALID_NAME</a>,\r
60<a href="rc.html#de">FR_DENIED</a>,\r
61<a href="rc.html#ex">FR_EXIST</a>,\r
62<a href="rc.html#io">FR_INVALID_OBJECT</a>,\r
63<a href="rc.html#wp">FR_WRITE_PROTECTED</a>,\r
64<a href="rc.html#id">FR_INVALID_DRIVE</a>,\r
65<a href="rc.html#ne">FR_NOT_ENABLED</a>,\r
66<a href="rc.html#ns">FR_NO_FILESYSTEM</a>,\r
67<a href="rc.html#tm">FR_TIMEOUT</a>,\r
68<a href="rc.html#lo">FR_LOCKED</a>,\r
69<a href="rc.html#nc">FR_NOT_ENOUGH_CORE</a>,\r
70<a href="rc.html#tf">FR_TOO_MANY_OPEN_FILES</a>\r
71</p>\r
72</div>\r
73\r
74\r
75<div class="para desc">\r
76<h4>Description</h4>\r
70702af1
L		 77<p>Before using any file function, a work area (file system object) needs to be registered to the logical drive with <a href="mount.html"><tt>f_mount</tt></a> function. All API functions except for <tt>f_mkfs/f_fdisk</tt> function get ready to work after this procedure.</p>\r
78<p>After <tt>f_open</tt> function succeeded, the file object is valid. The file object is used for subsequent operations to the file to identify the file. Open file must be closed prior to power down, media removal or re-mount, or the file can be collapsed. To close an open file, use <a href="close.html"><tt>f_close</tt></a> function.</p>\r
79<p>If duplicated file open is needed, read <a href="appnote.html#dup">here</a> carefully. However duplicated open of a file with any write mode flag is always prohibited.</p>\r
53668523
L		 80</div>\r
81\r
82\r
83<div class="para comp">\r
84<h4>QuickInfo</h4>\r
70702af1 85<p>Always available. Only <tt>FA_READ</tt> and <tt>FA_OPEN_EXISTING</tt> are supported when <tt>_FS_READONLY == 1</tt>.</p>\r
53668523
L		 86</div>\r
87\r
88\r
89<div class="para use">\r
90<h4>Example</h4>\r
91<pre>\r
92<span class="c">/* Read a text file and display it */</span>\r
93\r
94FATFS FatFs; <span class="c">/* Work area (file system object) for logical drive */</span>\r
95\r
96int main (void)\r
97{\r
98 FIL fil; <span class="c">/* File object */</span>\r
99 char line[82]; <span class="c">/* Line buffer */</span>\r
100 FRESULT fr; <span class="c">/* FatFs return code */</span>\r
101\r
102\r
103 <span class="c">/* Register work area to the default drive */</span>\r
104 f_mount(&amp;FatFs, "", 0);\r
105\r
106 <span class="c">/* Open a text file */</span>\r
107 fr = f_open(&amp;fil, "message.txt", FA_READ);\r
108 if (fr) return (int)fr;\r
109\r
110 <span class="c">/* Read all lines and display it */</span>\r
111 while (f_gets(line, sizeof line, &amp;fil))\r
112 printf(line);\r
113\r
114 <span class="c">/* Close the file */</span>\r
115 f_close(&amp;fil);\r
116\r
117 return 0;\r
118}\r
119</pre>\r
120<pre>\r
121<span class="c">/* Copy a file "file.bin" on the drive 1 to drive 0 */</span>\r
122\r
123int main (void)\r
124{\r
125 FATFS fs[2]; <span class="c">/* Work area (file system object) for logical drives */</span>\r
126 FIL fsrc, fdst; <span class="c">/* File objects */</span>\r
127 BYTE buffer[4096]; <span class="c">/* File copy buffer */</span>\r
128 FRESULT fr; <span class="c">/* FatFs function common result code */</span>\r
129 UINT br, bw; <span class="c">/* File read/write count */</span>\r
130\r
131\r
132 <span class="c">/* Register work area for each logical drive */</span>\r
133 f_mount(&amp;fs[0], "0:", 0);\r
134 f_mount(&amp;fs[1], "1:", 0);\r
135\r
136 <span class="c">/* Open source file on the drive 1 */</span>\r
70702af1 137 fr = f_open(&amp;fsrc, "1:file.bin", FA_READ);\r
53668523
L		 138 if (fr) return (int)fr;\r
139\r
140 <span class="c">/* Create destination file on the drive 0 */</span>\r
70702af1 141 fr = f_open(&amp;fdst, "0:file.bin", FA_WRITE | FA_CREATE_ALWAYS);\r
53668523
L		 142 if (fr) return (int)fr;\r
143\r
144 <span class="c">/* Copy source to destination */</span>\r
145 for (;;) {\r
146 fr = f_read(&amp;fsrc, buffer, sizeof buffer, &amp;br); <span class="c">/* Read a chunk of source file */</span>\r
147 if (fr || br == 0) break; <span class="c">/* error or eof */</span>\r
148 fr = f_write(&amp;fdst, buffer, br, &amp;bw); <span class="c">/* Write it to the destination file */</span>\r
149 if (fr || bw &lt; br) break; <span class="c">/* error or disk full */</span>\r
150 }\r
151\r
152 <span class="c">/* Close open files */</span>\r
153 f_close(&amp;fsrc);\r
154 f_close(&amp;fdst);\r
155\r
156 <span class="c">/* Unregister work area prior to discard it */</span>\r
157 f_mount(NULL, "0:", 0);\r
158 f_mount(NULL, "1:", 0);\r
159\r
160 return (int)fr;\r
161}\r
162</pre>\r
163</div>\r
164\r
165\r
166<div class="para ref">\r
167<h4>See Also</h4>\r
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>\r
169</div>\r
170\r
171<p class="foot"><a href="../00index_e.html">Return</a></p>\r
172</body>\r
173</html>\r
Z180 Stamp Monitor