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