Mistake on this page?
Report an issue in GitHub or email us
FileSystem.h
1 
2 /* mbed Microcontroller Library
3  * Copyright (c) 2006-2013 ARM Limited
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 #ifndef MBED_FILESYSTEM_H
19 #define MBED_FILESYSTEM_H
20 
21 #include "platform/platform.h"
22 
23 #include "platform/FileBase.h"
24 #include "platform/FileHandle.h"
25 #include "platform/DirHandle.h"
26 #include "platform/FileSystemLike.h"
27 #include "blockdevice/BlockDevice.h"
28 
29 namespace mbed {
30 /** \addtogroup file system */
31 /** @{*/
32 
33 
34 // Opaque pointer representing files and directories.
35 typedef void *fs_file_t;
36 typedef void *fs_dir_t;
37 
38 // Predeclared classes.
39 class Dir;
40 class File;
41 
42 /** A file system object. Provides file system operations and file operations
43  * for the File and Dir classes on a block device.
44  *
45  * Implementations must provide at minimum file operations and mount
46  * operations for block devices.
47  *
48  * @note Synchronization level: Set by subclass
49  */
50 class FileSystem : public FileSystemLike {
51 public:
52 
53  /** File system lifetime.
54  *
55  * @param name Name to add file system to tree as.
56  */
57  FileSystem(const char *name = NULL);
58  virtual ~FileSystem() {}
59 
60  /** Return the default file system.
61  *
62  * Returns the default file system based on the default block device configuration.
63  * Use the components in target.json or application config to change
64  * the default block device and affect the default filesystem.
65  * SD block device => FAT filesystem
66  * QSPIF, SPIF, DATAFLASH or FLAHIAP block device => LITTLE filesystem
67  *
68  * An application can override all target settings by implementing
69  * FileSystem::get_default_instance() - the default
70  * definition is weak, and calls get_target_default_instance().
71  */
73 
74  /** Mount a file system to a block device.
75  *
76  * @param bd Block device to mount to.
77  * @return 0 on success, negative error code on failure.
78  */
79  virtual int mount(BlockDevice *bd) = 0;
80 
81  /** Unmount a file system from the underlying block device.
82  *
83  * @return 0 on success, negative error code on failure.
84  */
85  virtual int unmount() = 0;
86 
87  /** Reformat a file system. Results in an empty and mounted file system.
88  *
89  * @param bd Block device to reformat and mount. If NULL, the mounted
90  * Block device is used.
91  * Note: If mount fails, bd must be provided.
92  * Default: NULL
93  * @return 0 on success, negative error code on failure.
94  */
95  virtual int reformat(BlockDevice *bd = NULL);
96 
97  /** Remove a file from the file system.
98  *
99  * @param path The name of the file to remove.
100  * @return 0 on success, negative error code on failure.
101  */
102  virtual int remove(const char *path);
103 
104  /** Rename a file in the file system.
105  *
106  * @param path The existing name of the file to rename.
107  * @param newpath The new name of the file.
108  * @return 0 on success, negative error code on failure.
109  */
110  virtual int rename(const char *path, const char *newpath);
111 
112  /** Store information about the file in a stat structure.
113  *
114  * @param path The name of the file to find information about.
115  * @param st The stat buffer to write to.
116  * @return 0 on success, negative error code on failure.
117  */
118  virtual int stat(const char *path, struct stat *st);
119 
120  /** Create a directory in the file system.
121  *
122  * @param path The name of the directory to create.
123  * @param mode The permissions with which to create the directory.
124  * @return 0 on success, negative error code on failure.
125  */
126  virtual int mkdir(const char *path, mode_t mode);
127 
128  /** Store information about the mounted file system in a statvfs structure.
129  *
130  * @param path The name of the file to find information about.
131  * @param buf The stat buffer to write to.
132  * @return 0 on success, negative error code on failure.
133  */
134  virtual int statvfs(const char *path, struct statvfs *buf);
135 
136 protected:
137  friend class File;
138  friend class Dir;
139 
140 #if !(DOXYGEN_ONLY)
141  /** Open a file on the file system.
142  *
143  * @param file Destination of the newly created handle to the referenced file.
144  * @param path The name of the file to open.
145  * @param flags The flags that trigger opening of the file. These flags are O_RDONLY, O_WRONLY, and O_RDWR,
146  * with an O_CREAT, O_TRUNC, or O_APPEND bitwise OR operator.
147  * @return 0 on success, negative error code on failure.
148  */
149  virtual int file_open(fs_file_t *file, const char *path, int flags) = 0;
150 
151  /** Close a file.
152  *
153  * @param file File handle.
154  * return 0 on success, negative error code on failure.
155  */
156  virtual int file_close(fs_file_t file) = 0;
157 
158  /** Read the contents of a file into a buffer.
159  *
160  * @param file File handle.
161  * @param buffer The buffer to read in to.
162  * @param size The number of bytes to read.
163  * @return The number of bytes read, 0 at the end of the file, negative error on failure.
164  */
165  virtual ssize_t file_read(fs_file_t file, void *buffer, size_t size) = 0;
166 
167  /** Write the contents of a buffer to a file.
168  *
169  * @param file File handle.
170  * @param buffer The buffer to write from.
171  * @param size The number of bytes to write.
172  * @return The number of bytes written, negative error on failure.
173  */
174  virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t size) = 0;
175 
176  /** Flush any buffers associated with the file.
177  *
178  * @param file File handle.
179  * @return 0 on success, negative error code on failure.
180  */
181  virtual int file_sync(fs_file_t file);
182 
183  /** Check whether the file is an interactive terminal device.
184  * If so, line buffered behavior is used by default.
185  *
186  * @param file File handle.
187  * @return True if the file is a terminal.
188  */
189  virtual int file_isatty(fs_file_t file);
190 
191  /** Move the file position to a given offset from a given location.
192  *
193  * @param file File handle.
194  * @param offset The offset from whence to move to.
195  * @param whence The start of where to seek.
196  * SEEK_SET to start from the beginning of the file,
197  * SEEK_CUR to start from the current position in the file,
198  * SEEK_END to start from the end of the file.
199  * @return The new offset of the file
200  */
201  virtual off_t file_seek(fs_file_t file, off_t offset, int whence) = 0;
202 
203  /** Get the file position of the file.
204  *
205  * @param file File handle.
206  * @return The current offset in the file.
207  */
208  virtual off_t file_tell(fs_file_t file);
209 
210  /** Rewind the file position to the beginning of the file.
211  *
212  * @param file File handle.
213  * @note This is equivalent to file_seek(file, 0, FS_SEEK_SET)
214  */
215  virtual void file_rewind(fs_file_t file);
216 
217  /** Get the size of the file.
218  *
219  * @param file File handle.
220  * @return Size of the file in bytes.
221  */
222  virtual off_t file_size(fs_file_t file);
223 
224  /** Truncate or extend a file.
225  *
226  * The file's length is set to the specified value. The seek pointer is
227  * not changed. If the file is extended, the extended area appears as if
228  * it were zero-filled.
229  *
230  * @param file File handle.
231  * @param length The requested new length for the file.
232  *
233  * @return 0 on success, negative error code on failure.
234  */
235  virtual int file_truncate(fs_file_t file, off_t length);
236 
237  /** Open a directory on the file system.
238  *
239  * @param dir Destination for the handle to the directory.
240  * @param path Name of the directory to open.
241  * @return 0 on success, negative error code on failure.
242  */
243  virtual int dir_open(fs_dir_t *dir, const char *path);
244 
245  /** Close a directory.
246  *
247  * @param dir Dir handle.
248  * @return 0 on success, negative error code on failure.
249  */
250  virtual int dir_close(fs_dir_t dir);
251 
252  /** Read the next directory entry.
253  *
254  * @param dir Dir handle.
255  * @param ent The directory entry to fill out.
256  * @return 1 on reading a filename, 0 at the end of the directory, negative error on failure.
257  */
258  virtual ssize_t dir_read(fs_dir_t dir, struct dirent *ent);
259 
260  /** Set the current position of the directory.
261  *
262  * @param dir Dir handle.
263  * @param offset Offset of the location to seek to,
264  * must be a value returned from dir_tell.
265  */
266  virtual void dir_seek(fs_dir_t dir, off_t offset);
267 
268  /** Get the current position of the directory.
269  *
270  * @param dir Dir handle.
271  * @return Directory position, which can be passed to dir_rewind.
272  */
273  virtual off_t dir_tell(fs_dir_t dir);
274 
275  /** Rewind the current position to the beginning of the directory.
276  *
277  * @param dir Dir handle.
278  */
279  virtual void dir_rewind(fs_dir_t dir);
280 
281  /** Get the size of the directory.
282  *
283  * @param dir Dir handle.
284  * @return Number of files in the directory.
285  */
286  virtual size_t dir_size(fs_dir_t dir);
287 #endif //!defined(DOXYGEN_ONLY)
288 
289 protected:
290  // Hooks for file systemHandle
291  virtual int open(FileHandle **file, const char *path, int flags);
292  virtual int open(DirHandle **dir, const char *path);
293 };
294 
295 
296 /** @}*/
297 } // namespace mbed
298 
299 #endif
virtual int stat(const char *path, struct stat *st)
Store information about the file in a stat structure.
FileSystem(const char *name=NULL)
File system lifetime.
Represents a directory stream.
Definition: DirHandle.h:55
virtual int mount(BlockDevice *bd)=0
Mount a file system to a block device.
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:48
Class FileHandle.
Definition: FileHandle.h:46
virtual int open(FileHandle **file, const char *path, int flags)
defined(DOXYGEN_ONLY)
A filesystem-like object is one that can be used to open file-like objects though it by fopen("/name/...
virtual int mkdir(const char *path, mode_t mode)
Create a directory in the file system.
Dir class.
Definition: Dir.h:31
virtual int reformat(BlockDevice *bd=NULL)
Reformat a file system.
File class.
Definition: File.h:31
A file system object.
Definition: FileSystem.h:50
virtual int rename(const char *path, const char *newpath)
Rename a file in the file system.
virtual int unmount()=0
Unmount a file system from the underlying block device.
static FileSystem * get_default_instance()
Return the default file system.
Definition: ATHandler.h:46
virtual int statvfs(const char *path, struct statvfs *buf)
Store information about the mounted file system in a statvfs structure.
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.