Mistake on this page?
Report an issue in GitHub or email us
FATFileSystem.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2012 ARM Limited
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to deal
6  * in the Software without restriction, including without limitation the rights
7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8  * copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20  * SOFTWARE.
21  */
22 
23 /** \addtogroup storage */
24 /** @{*/
25 
26 #ifndef MBED_FATFILESYSTEM_H
27 #define MBED_FATFILESYSTEM_H
28 
29 #include "FileSystem.h"
30 #include "BlockDevice.h"
31 #include "FileHandle.h"
32 #include "ff.h"
33 #include <stdint.h>
34 #include "PlatformMutex.h"
35 
36 namespace mbed {
37 
38 /**
39  * FAT file system based on ChaN's FAT file system library v0.8
40  *
41  * Synchronization level: Thread safe
42  */
43 class FATFileSystem : public FileSystem {
44 public:
45  /** Lifetime of the FAT file system.
46  *
47  * @param name Name of the file system in the tree.
48  * @param bd Block device to mount. Mounted immediately if not NULL.
49  */
50  FATFileSystem(const char *name = NULL, BlockDevice *bd = NULL);
51  virtual ~FATFileSystem();
52 
53  /** Format a logical drive, FDISK partitioning rule.
54  *
55  * The block device to format should be mounted when this function is called.
56  *
57  * @param bd
58  * This is the block device that will be formatted.
59  *
60  * @param cluster_size
61  * This is the number of bytes per cluster. A larger cluster size decreases
62  * the overhead of the FAT table, but also increases the minimum file size. The
63  * cluster size must be a multiple of the underlying device's allocation unit
64  * and is currently limited to a max of 32,768 bytes. If the cluster size is set to zero, a cluster size
65  * is determined from the device's allocation unit. Defaults to zero.
66  *
67  * @return 0 on success, negative error code on failure.
68  */
69  static int format(BlockDevice *bd, bd_size_t cluster_size = 0);
70 
71  /** Mount a file system to a block device.
72  *
73  * @param bd Block device to mount to.
74  * @return 0 on success, negative error code on failure.
75  */
76  virtual int mount(BlockDevice *bd);
77 
78  /** Unmount a file system from the underlying block device.
79  *
80  * @return 0 on success, negative error code on failure.
81  */
82  virtual int unmount();
83 
84  /** Reformat a file system, results in an empty and mounted file system.
85  *
86  * @param bd
87  * Block device to reformat and mount. If NULL, the mounted
88  * Block device is used.
89  * Note: If mount fails, bd must be provided.
90  * Default: NULL
91  *
92  * @param allocation_unit
93  * This is the number of bytes per cluster size. The valid value is N
94  * times the sector size. N is a power of 2, from 1 to 128, for the FAT
95  * volume, and up to 16MiB for the exFAT volume. If zero is given,
96  * the default allocation unit size is selected by the underlying
97  * file system, which depends on the volume size.
98  *
99  * @return 0 on success, negative error code on failure.
100  */
101  virtual int reformat(BlockDevice *bd, int allocation_unit);
102 
103  /** Reformat a file system, results in an empty and mounted file system.
104  *
105  * @param bd Block device to reformat and mount. If NULL, the mounted
106  * Block device is used.
107  * Note: If mount fails, bd must be provided.
108  * Default: NULL
109  * @return 0 on success, negative error code on failure.
110  */
111  virtual int reformat(BlockDevice *bd = NULL)
112  {
113  // Required for virtual inheritance shenanigans.
114  return reformat(bd, 0);
115  }
116 
117  /** Remove a file from the file system.
118  *
119  * @param path The name of the file to remove.
120  * @return 0 on success, negative error code on failure.
121  */
122  virtual int remove(const char *path);
123 
124  /** Rename a file in the file system.
125  *
126  * @param path The current name of the file to rename.
127  * @param newpath The new name of the file.
128  * @return 0 on success, negative error code on failure.
129  */
130  virtual int rename(const char *path, const char *newpath);
131 
132  /** Store information about the file in a stat structure.
133  *
134  * @param path The name of the file to store information about.
135  * @param st The stat buffer to write to.
136  * @return 0 on success, negative error code on failure.
137  */
138  virtual int stat(const char *path, struct stat *st);
139 
140  /** Create a directory in the file system.
141  *
142  * @param path The name of the directory to create.
143  * @param mode The permissions with which to create the directory.
144  * @return 0 on success, negative error code on failure.
145  */
146  virtual int mkdir(const char *path, mode_t mode);
147 
148  /** Store information about the mounted file system in a statvfs structure.
149  *
150  * @param path The name of the file to store information about.
151  * @param buf The stat buffer to write to.
152  * @return 0 on success, negative error code on failure.
153  */
154  virtual int statvfs(const char *path, struct statvfs *buf);
155 
156 protected:
157 #if !(DOXYGEN_ONLY)
158  /** Open a file on the file system.
159  *
160  * @param file Destination for the handle to a newly created file.
161  * @param path The name of the file to open.
162  * @param flags The flags that trigger opening of the file. These flags are O_RDONLY, O_WRONLY, and O_RDWR,
163  * with an O_CREAT, O_TRUNC, or O_APPEND bitwise OR operator.
164  * @return 0 on success, negative error code on failure.
165  */
166  virtual int file_open(fs_file_t *file, const char *path, int flags);
167 
168  /** Close a file
169  *
170  * @param file File handle.
171  * @return 0 on success, negative error code on failure.
172  */
173  virtual int file_close(fs_file_t file);
174 
175  /** Read the contents of a file into a buffer.
176  *
177  * @param file File handle.
178  * @param buffer The buffer to read into.
179  * @param len The number of bytes to read.
180  * @return The number of bytes read; 0 at the end of the file, negative error on failure.
181  */
182  virtual ssize_t file_read(fs_file_t file, void *buffer, size_t len);
183 
184  /** Write the contents of a buffer to a file.
185  *
186  * @param file File handle.
187  * @param buffer The buffer to write from.
188  * @param len The number of bytes to write.
189  * @return The number of bytes written, negative error on failure.
190  */
191  virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t len);
192 
193  /** Flush any buffers associated with the file.
194  *
195  * @param file File handle.
196  * @return 0 on success, negative error code on failure.
197  */
198  virtual int file_sync(fs_file_t file);
199 
200  /** Move the file position to a given offset from a given location
201  *
202  * @param file File handle.
203  * @param offset The offset from whence to move to.
204  * @param whence The start of where to seek.
205  * SEEK_SET to start from the beginning of the file,
206  * SEEK_CUR to start from the current position in the file,
207  * SEEK_END to start from the end of the file.
208  * @return The new offset of the file.
209  */
210  virtual off_t file_seek(fs_file_t file, off_t offset, int whence);
211 
212  /** Get the file position of the file.
213  *
214  * @param file File handle.
215  * @return The current offset in the file.
216  */
217  virtual off_t file_tell(fs_file_t file);
218 
219  /** Get the size of the file.
220  *
221  * @param file File handle.
222  * @return Size of the file in bytes.
223  */
224  virtual off_t file_size(fs_file_t file);
225 
226  /** Truncate or extend a file.
227  *
228  * The file's length is set to the specified value. The seek pointer is
229  * not changed. If the file is extended, the extended area appears as if
230  * it were zero-filled.
231  *
232  * @param file File handle.
233  * @param length The requested new length for the file.
234  *
235  * @return 0 on success, negative error code on failure.
236  */
237  virtual int file_truncate(mbed::fs_file_t file, off_t length);
238 
239  /** Open a directory on the file system.
240  *
241  * @param dir Destination for the handle to the directory.
242  * @param path Name of the directory to open.
243  * @return 0 on success, negative error code on failure.
244  */
245  virtual int dir_open(fs_dir_t *dir, const char *path);
246 
247  /** Close a directory
248  *
249  * @param dir Dir handle.
250  * @return 0 on success, negative error code on failure.
251  */
252  virtual int dir_close(fs_dir_t dir);
253 
254  /** Read the next directory entry
255  *
256  * @param dir Dir handle.
257  * @param ent The directory entry to fill out.
258  * @return 1 on reading a filename, 0 at the end of the directory, negative error on failure.
259  */
260  virtual ssize_t dir_read(fs_dir_t dir, struct dirent *ent);
261 
262  /** Set the current position of the directory.
263  *
264  * @param dir Dir handle.
265  * @param offset Offset of the location to seek to.
266  * Must be a value returned by dir_tell.
267  */
268  virtual void dir_seek(fs_dir_t dir, off_t offset);
269 
270  /** Get the current position of the directory.
271  *
272  * @param dir Dir handle.
273  * @return Directory position, which can be passed to dir_rewind.
274  */
275  virtual off_t dir_tell(fs_dir_t dir);
276 
277  /** Rewind the current position to the beginning of the directory.
278  *
279  * @param dir Dir handle.
280  */
281  virtual void dir_rewind(fs_dir_t dir);
282 #endif //!(DOXYGEN_ONLY)
283 
284 private:
285  FATFS _fs; // Work area (file system object) for logical drive.
286  char _fsid[sizeof("0:")];
287  int _id;
288 
289 protected:
290  virtual void lock();
291  virtual void unlock();
292  virtual int mount(BlockDevice *bd, bool mount);
293 };
294 
295 } // namespace mbed
296 
297 // Added "using" for backwards compatibility.
298 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
299 using mbed::FATFileSystem;
300 #endif
301 
302 #endif
303 
304 /** @}*/
virtual int rename(const char *path, const char *newpath)
Rename a file in the file system.
virtual int statvfs(const char *path, struct statvfs *buf)
Store information about the mounted file system in a statvfs structure.
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:47
virtual int mkdir(const char *path, mode_t mode)
Create a directory in the file system.
Definition: ff.h:87
static int format(BlockDevice *bd, bd_size_t cluster_size=0)
Format a logical drive, FDISK partitioning rule.
virtual int stat(const char *path, struct stat *st)
Store information about the file in a stat structure.
virtual int reformat(BlockDevice *bd=NULL)
Reformat a file system, results in an empty and mounted file system.
virtual int reformat(BlockDevice *bd, int allocation_unit)
Reformat a file system, results in an empty and mounted file system.
FAT file system based on ChaN&#39;s FAT file system library v0.8.
Definition: FATFileSystem.h:43
A file system object.
Definition: FileSystem.h:49
FATFileSystem(const char *name=NULL, BlockDevice *bd=NULL)
Lifetime of the FAT file system.
virtual int mount(BlockDevice *bd)
Mount a file system to a block device.
Definition: AnalogIn.h:28
virtual int unmount()
Unmount a file system from the underlying block device.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.