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