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  * FATFileSystem based on ChaN's Fat Filesystem library v0.8
40  *
41  * Synchronization level: Thread safe
42  */
43 class FATFileSystem : public FileSystem {
44 public:
45  /** Lifetime of the FATFileSystem
46  *
47  * @param name Name to add filesystem to tree as
48  * @param bd BlockDevice to mount, may be passed instead to mount call
49  */
50  FATFileSystem(const char *name = NULL, BlockDevice *bd = NULL);
51  virtual ~FATFileSystem();
52 
53  /** Formats 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 will decrease
62  * the overhead of the FAT table, but also increase 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 zero, a cluster size
65  * will be 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  /** Mounts a filesystem to a block device
72  *
73  * @param bd BlockDevice to mount to
74  * @return 0 on success, negative error code on failure
75  */
76  virtual int mount(BlockDevice *bd);
77 
78  /** Unmounts a filesystem from the underlying block device
79  *
80  * @return 0 on success, negative error code on failure
81  */
82  virtual int unmount();
83 
84  /** Reformats a filesystem, results in an empty and mounted filesystem
85  *
86  * @param bd
87  * BlockDevice to reformat and mount. If NULL, the mounted
88  * block device will be 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 FAT
95  * volume and upto 16MiB for exFAT volume. If zero is given,
96  * the default allocation unit size is selected by the underlying
97  * filesystem, 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  /** Reformats a filesystem, results in an empty and mounted filesystem
104  *
105  * @param bd BlockDevice to reformat and mount. If NULL, the mounted
106  * block device will be 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 filesystem.
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 filesystem.
125  *
126  * @param path The name of the file to rename.
127  * @param newpath The name to rename it to
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 find 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 filesystem.
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 filesystem in a statvfs structure
149  *
150  * @param path The name of the file to find 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  /** Open a file on the filesystem
158  *
159  * @param file Destination for the handle to a newly created file
160  * @param path The name of the file to open
161  * @param flags The flags to open the file in, one of O_RDONLY, O_WRONLY, O_RDWR,
162  * bitwise or'd with one of O_CREAT, O_TRUNC, O_APPEND
163  * @return 0 on success, negative error code on failure
164  */
165  virtual int file_open(fs_file_t *file, const char *path, int flags);
166 
167  /** Close a file
168  *
169  * @param file File handle
170  * @return 0 on success, negative error code on failure
171  */
172  virtual int file_close(fs_file_t file);
173 
174  /** Read the contents of a file into a buffer
175  *
176  * @param file File handle
177  * @param buffer The buffer to read in to
178  * @param len The number of bytes to read
179  * @return The number of bytes read, 0 at end of file, negative error on failure
180  */
181  virtual ssize_t file_read(fs_file_t file, void *buffer, size_t len);
182 
183  /** Write the contents of a buffer to a file
184  *
185  * @param file File handle
186  * @param buffer The buffer to write from
187  * @param len The number of bytes to write
188  * @return The number of bytes written, negative error on failure
189  */
190  virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t len);
191 
192  /** Flush any buffers associated with the file
193  *
194  * @param file File handle
195  * @return 0 on success, negative error code on failure
196  */
197  virtual int file_sync(fs_file_t file);
198 
199  /** Move the file position to a given offset from from a given location
200  *
201  * @param file File handle
202  * @param offset The offset from whence to move to
203  * @param whence The start of where to seek
204  * SEEK_SET to start from beginning of file,
205  * SEEK_CUR to start from current position in file,
206  * SEEK_END to start from end of file
207  * @return The new offset of the file
208  */
209  virtual off_t file_seek(fs_file_t file, off_t offset, int whence);
210 
211  /** Get the file position of the file
212  *
213  * @param file File handle
214  * @return The current offset in the file
215  */
216  virtual off_t file_tell(fs_file_t file);
217 
218  /** Get the size of the file
219  *
220  * @param file File handle
221  * @return Size of the file in bytes
222  */
223  virtual off_t file_size(fs_file_t file);
224 
225  /** Open a directory on the filesystem
226  *
227  * @param dir Destination for the handle to the directory
228  * @param path Name of the directory to open
229  * @return 0 on success, negative error code on failure
230  */
231  virtual int dir_open(fs_dir_t *dir, const char *path);
232 
233  /** Close a directory
234  *
235  * @param dir Dir handle
236  * @return 0 on success, negative error code on failure
237  */
238  virtual int dir_close(fs_dir_t dir);
239 
240  /** Read the next directory entry
241  *
242  * @param dir Dir handle
243  * @param ent The directory entry to fill out
244  * @return 1 on reading a filename, 0 at end of directory, negative error on failure
245  */
246  virtual ssize_t dir_read(fs_dir_t dir, struct dirent *ent);
247 
248  /** Set the current position of the directory
249  *
250  * @param dir Dir handle
251  * @param offset Offset of the location to seek to,
252  * must be a value returned from dir_tell
253  */
254  virtual void dir_seek(fs_dir_t dir, off_t offset);
255 
256  /** Get the current position of the directory
257  *
258  * @param dir Dir handle
259  * @return Position of the directory that can be passed to dir_rewind
260  */
261  virtual off_t dir_tell(fs_dir_t dir);
262 
263  /** Rewind the current position to the beginning of the directory
264  *
265  * @param dir Dir handle
266  */
267  virtual void dir_rewind(fs_dir_t dir);
268 
269 private:
270  FATFS _fs; // Work area (file system object) for logical drive
271  char _fsid[sizeof("0:")];
272  int _id;
273 
274 protected:
275  virtual void lock();
276  virtual void unlock();
277  virtual int mount(BlockDevice *bd, bool mount);
278 };
279 
280 } // namespace mbed
281 
282 // Added "using" for backwards compatibility
283 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
284 using mbed::FATFileSystem;
285 #endif
286 
287 #endif
288 
289 /** @}*/
virtual int dir_close(fs_dir_t dir)
Close a directory.
virtual int rename(const char *path, const char *newpath)
Rename a file in the filesystem.
virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t len)
Write the contents of a buffer to a file.
virtual int dir_open(fs_dir_t *dir, const char *path)
Open a directory on the filesystem.
virtual void dir_seek(fs_dir_t dir, off_t offset)
Set the current position of the directory.
virtual int statvfs(const char *path, struct statvfs *buf)
Store information about the mounted filesystem in a statvfs structure.
virtual off_t file_tell(fs_file_t file)
Get the file position of the file.
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 filesystem.
Definition: ff.h:87
virtual off_t file_seek(fs_file_t file, off_t offset, int whence)
Move the file position to a given offset from from a given location.
virtual int file_sync(fs_file_t file)
Flush any buffers associated with the file.
virtual int file_close(fs_file_t file)
Close a file.
static int format(BlockDevice *bd, bd_size_t cluster_size=0)
Formats 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)
Reformats a filesystem, results in an empty and mounted filesystem.
virtual void dir_rewind(fs_dir_t dir)
Rewind the current position to the beginning of the directory.
virtual off_t dir_tell(fs_dir_t dir)
Get the current position of the directory.
virtual int reformat(BlockDevice *bd, int allocation_unit)
Reformats a filesystem, results in an empty and mounted filesystem.
FATFileSystem based on ChaN&#39;s Fat Filesystem library v0.8.
Definition: FATFileSystem.h:43
A filesystem object provides filesystem operations and file operations for the File and Dir classes o...
Definition: FileSystem.h:49
virtual off_t file_size(fs_file_t file)
Get the size of the file.
virtual ssize_t dir_read(fs_dir_t dir, struct dirent *ent)
Read the next directory entry.
virtual int file_open(fs_file_t *file, const char *path, int flags)
Open a file on the filesystem.
FATFileSystem(const char *name=NULL, BlockDevice *bd=NULL)
Lifetime of the FATFileSystem.
virtual ssize_t file_read(fs_file_t file, void *buffer, size_t len)
Read the contents of a file into a buffer.
virtual int mount(BlockDevice *bd)
Mounts a filesystem to a block device.
Definition: AnalogIn.h:28
virtual int unmount()
Unmounts a filesystem 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.