File Systems¶
Zephyr RTOS Virtual Filesystem Switch (VFS) allows applications to mount multiple
file systems at different mount points (e.g., /fatfs
and /lfs
). The
mount point data structure contains all the necessary information required
to instantiate, mount, and operate on a file system. The File system Switch
decouples the applications from directly accessing an individual file system’s
specific API or internal functions by introducing file system registration
mechanisms.
In Zephyr, any file system implementation or library can be plugged into or
pulled out through a file system registration API. Each file system
implementation must have a globally unique integer identifier; use
FS_TYPE_EXTERNAL_BASE
to avoid clashes with in-tree identifiers.
int fs_register(int type, const struct fs_file_system_t *fs);
int fs_unregister(int type, const struct fs_file_system_t *fs);
Zephyr RTOS supports multiple instances of a file system by making use of the mount point as the disk volume name, which is used by the file system library while formatting or mounting a disk.
A file system is declared as:
static struct fs_mount_t mp = {
.type = FS_FATFS,
.mnt_point = FATFS_MNTP,
.fs_data = &fat_fs,
};
where
FS_FATFS
is the file system type like FATFS or LittleFS.FATFS_MNTP
is the mount point where the file system will be mounted.fat_fs
is the file system data which will be used by fs_mount() API.
Samples¶
Samples for the VFS are mainly supplied in samples/subsys/fs
, although various examples of the
VFS usage are provided as important functionalities in samples for different subsystems.
Here is the list of samples worth looking at:
samples/subsys/fs/fat_fs
is an example of FAT file system usage with SDHC media;samples/subsys/shell/fs
is an example of Shell fs subsystem, using internal flash partitionformatted to LittleFS;
samples/subsys/usb/mass/
example of USB Mass Storage device that uses FAT FS driver with RAMor SPI connected FLASH, or LittleFS in flash, depending on the sample configuration.
API Reference¶
-
group
file_system_api
File System APIs.
fs_open open and creation mode flags
-
FS_O_READ
¶ Open for read flag
-
FS_O_WRITE
¶ Open for write flag
-
FS_O_RDWR
¶ Open for read-write flag combination
-
FS_O_MODE_MASK
¶ Bitmask for read and write flags
-
FS_O_CREATE
¶ Create file if it does not exist
-
FS_O_APPEND
¶ Open/create file for append
-
FS_O_FLAGS_MASK
¶ Bitmask for open/create flags
-
FS_O_MASK
¶ Bitmask for open flags
fs_seek whence parameter values
-
FS_SEEK_SET
¶ Seek from the beginning of file
-
FS_SEEK_CUR
¶ Seek from a current position
-
FS_SEEK_END
¶ Seek from the end of file
Defines
-
FS_MOUNT_FLAG_NO_FORMAT
¶ Flag prevents formatting device if requested file system not found
-
FS_MOUNT_FLAG_READ_ONLY
¶ Flag makes mounted file system read-only
-
FS_MOUNT_FLAG_AUTOMOUNT
¶ Flag used in pre-defined mount structures that are to be mounted on startup.
This flag has no impact in user-defined mount structures.
-
FSTAB_ENTRY_DT_MOUNT_FLAGS
(node_id)¶
-
FS_FSTAB_ENTRY
(node_id)¶ The name under which a zephyr,fstab entry mount structure is defined.
-
FS_FSTAB_DECLARE_ENTRY
(node_id)¶ Generate a declaration for the externally defined fstab entry.
This will evaluate to the name of a struct fs_mount_t object.
Enums
-
enum
fs_dir_entry_type
¶ Values:
-
enumerator
FS_DIR_ENTRY_FILE
= 0¶ Identifier for file entry
-
enumerator
FS_DIR_ENTRY_DIR
¶ Identifier for directory entry
-
enumerator
-
enum [anonymous]¶
Enumeration to uniquely identify file system types.
Zephyr supports in-tree file systems and external ones. Each requires a unique identifier used to register the file system implementation and to associate a mount point with the file system type. This anonymous enum defines global identifiers for the in-tree file systems.
External file systems should be registered using unique identifiers starting at
FS_TYPE_EXTERNAL_BASE
. It is the responsibility of applications that use external file systems to ensure that these identifiers are unique if multiple file system implementations are used by the application.Values:
-
enumerator
FS_FATFS
= 0¶ Identifier for in-tree FatFS file system.
-
enumerator
FS_LITTLEFS
¶ Identifier for in-tree LittleFS file system.
-
enumerator
FS_TYPE_EXTERNAL_BASE
¶ Base identifier for external file systems.
-
enumerator
Functions
-
static inline void
fs_file_t_init
(struct fs_file_t *zfp)¶ Initialize fs_file_t object.
Initializes the fs_file_t object; the function needs to be invoked on object before first use with fs_open.
- Parameters
zfp – Pointer to file object
-
static inline void
fs_dir_t_init
(struct fs_dir_t *zdp)¶ Initialize fs_dir_t object.
Initializes the fs_dir_t object; the function needs to be invoked on object before first use with fs_opendir.
- Parameters
zdp – Pointer to file object
-
int
fs_open
(struct fs_file_t *zfp, const char *file_name, fs_mode_t flags)¶ Open or create file.
Opens or possibly creates a file and associates a stream with it.
flags
can be 0 or a binary combination of one or more of the following identifiers:FS_O_READ
open for readFS_O_WRITE
open for writeFS_O_RDWR
open for read/write (FS_O_READ | FS_O_WRITE
)FS_O_CREATE
create file if it does not existFS_O_APPEND
move to end of file before each write
If
flags
are set to 0 the function will attempt to open an existing file with no read/write access; this may be used to e.g. check if the file exists.- Parameters
zfp – Pointer to a file object
file_name – The name of a file to open
flags – The mode flags
- Returns 0
on success;
- Returns -EINVAL
when a bad file name is given;
- Returns -EROFS
when opening read-only file for write, or attempting to create a file on a system that has been mounted with the FS_MOUNT_FLAG_READ_ONLY flag;
- Returns -ENOENT
when the file path is not possible (bad mount point);
- Returns <0
an other negative errno code, depending on a file system back-end.
-
int
fs_close
(struct fs_file_t *zfp)¶ Close file.
Flushes the associated stream and closes the file.
- Parameters
zfp – Pointer to the file object
- Returns 0
on success;
- Returns <0
a negative errno code on error.
-
int
fs_unlink
(const char *path)¶ Unlink file.
Deletes the specified file or directory
- Parameters
path – Path to the file or directory to delete
- Returns 0
on success;
- Returns -EROFS
if file is read-only, or when file system has been mounted with the FS_MOUNT_FLAG_READ_ONLY flag;
- Returns -ENOTSUP
when not implemented by underlying file system driver;
- Returns <0
an other negative errno code on error.
-
int
fs_rename
(const char *from, const char *to)¶ Rename file or directory.
Performs a rename and / or move of the specified source path to the specified destination. The source path can refer to either a file or a directory. All intermediate directories in the destination path must already exist. If the source path refers to a file, the destination path must contain a full filename path, rather than just the new parent directory. If an object already exists at the specified destination path, this function causes it to be unlinked prior to the rename (i.e., the destination gets clobbered).
Note
Current implementation does not allow moving files between mount points.
- Parameters
from – The source path
to – The destination path
- Returns 0
on success;
- Returns -ENOTSUP
when not implemented by underlying file system driver;
- Returns <0
an other negative errno code on error.
-
ssize_t
fs_read
(struct fs_file_t *zfp, void *ptr, size_t size)¶ Read file.
Reads up to
size
bytes of data toptr
pointed buffer, returns number of bytes read. A returned value may be lower thansize
if there were fewer bytes available than requested.- Parameters
zfp – Pointer to the file object
ptr – Pointer to the data buffer
size – Number of bytes to be read
- Returns >=0
a number of bytes read, on success;
- Returns <0
a negative errno code on error.
-
ssize_t
fs_write
(struct fs_file_t *zfp, const void *ptr, size_t size)¶ Write file.
Attempts to write
size
number of bytes to the specified file. If a negative value is returned from the function, the file pointer has not been advanced. If the function returns a non-negative number that is lower thansize
, the globalerrno
variable should be checked for an error code, as the device may have no free space for data.- Parameters
zfp – Pointer to the file object
ptr – Pointer to the data buffer
size – Number of bytes to be written
- Returns >=0
a number of bytes written, on success;
- Returns -ENOTSUP
when not implemented by underlying file system driver;
- Returns <0
an other negative errno code on error.
-
int
fs_seek
(struct fs_file_t *zfp, off_t offset, int whence)¶ Seek file.
Moves the file position to a new location in the file. The
offset
is added to file position based on thewhence
parameter.- Parameters
zfp – Pointer to the file object
offset – Relative location to move the file pointer to
whence – Relative location from where offset is to be calculated.
FS_SEEK_SET
for the beginning of the file;FS_SEEK_CUR
for the current position;FS_SEEK_END
for the end of the file.
- Returns 0
on success;
- Returns -ENOTSUP
if not supported by underlying file system driver;
- Returns <0
an other negative errno code on error.
-
off_t
fs_tell
(struct fs_file_t *zfp)¶ Get current file position.
Retrieves and returns the current position in the file stream.
The current revision does not validate the file object.
- Parameters
zfp – Pointer to the file object
- Returns >=
0 a current position in file;
- Returns -ENOTSUP
if not supported by underlying file system driver;
- Returns <0
an other negative errno code on error.
-
int
fs_truncate
(struct fs_file_t *zfp, off_t length)¶ Truncate or extend an open file to a given size.
Truncates the file to the new length if it is shorter than the current size of the file. Expands the file if the new length is greater than the current size of the file. The expanded region would be filled with zeroes.
Note
In the case of expansion, if the volume got full during the expansion process, the function will expand to the maximum possible length and return success. Caller should check if the expanded size matches the requested length.
- Parameters
zfp – Pointer to the file object
length – New size of the file in bytes
- Returns 0
on success;
- Returns -ENOTSUP
when not implemented by underlying file system driver;
- Returns <0
an other negative errno code on error.
-
int
fs_sync
(struct fs_file_t *zfp)¶ Flush cached write data buffers of an open file.
The function flushes the cache of an open file; it can be invoked to ensure data gets written to the storage media immediately, e.g. to avoid data loss in case if power is removed unexpectedly.
Note
Closing a file will cause caches to be flushed correctly so the function need not be called when the file is being closed.
- Parameters
zfp – Pointer to the file object
- Returns 0
on success;
- Returns <0
a negative errno code on error.
-
int
fs_mkdir
(const char *path)¶ Directory create.
Creates a new directory using specified path.
- Parameters
path – Path to the directory to create
- Returns 0
on success;
- Returns -ENOTSUP
when not implemented by underlying file system driver;
- Returns <0
an other negative errno code on error
-
int
fs_opendir
(struct fs_dir_t *zdp, const char *path)¶ Directory open.
Opens an existing directory specified by the path.
- Parameters
zdp – Pointer to the directory object
path – Path to the directory to open
- Returns 0
on success;
- Returns <0
a negative errno code on error.
-
int
fs_readdir
(struct fs_dir_t *zdp, struct fs_dirent *entry)¶ Directory read entry.
Reads directory entries of an open directory. In end-of-dir condition, the function will return 0 and set the
entry->name[0]
to 0.Note
: Most existing underlying file systems do not generate POSIX special directory entries “.” or “..”. For consistency the abstraction layer will remove these from lower layer results so higher layers see consistent results.
- Parameters
zdp – Pointer to the directory object
entry – Pointer to zfs_dirent structure to read the entry into
- Returns 0
on success or end-of-dir;;
- Returns <0
a negative errno code on error.
-
int
fs_closedir
(struct fs_dir_t *zdp)¶ Directory close.
Closes an open directory.
- Parameters
zdp – Pointer to the directory object
- Returns 0
on success;
- Returns <0
a negative errno code on error.
-
int
fs_mount
(struct fs_mount_t *mp)¶ Mount filesystem.
Perform steps needed for mounting a file system like calling the file system specific mount function and adding the mount point to mounted file system list.
Note
Current implementation of ELM FAT driver allows only following mount points: “/RAM:”,”/NAND:”,”/CF:”,”/SD:”,”/SD2:”,”/USB:”,”/USB2:”,”/USB3:” or mount points that consist of single digit, e.g: “/0:”, “/1:” and so forth.
- Parameters
mp – Pointer to the fs_mount_t structure. Referenced object is not changed if the mount operation failed. A reference is captured in the fs infrastructure if the mount operation succeeds, and the application must not mutate the structure contents until fs_unmount is successfully invoked on the same pointer.
- Returns 0
on success;
- Returns -ENOENT
when file system type has not been registered;
- Returns -ENOTSUP
when not supported by underlying file system driver;
- Returns -EROFS
if system requires formatting but
FS_MOUNT_FLAG_READ_ONLY
has been set;- Returns <0
an other negative errno code on error.
-
int
fs_unmount
(struct fs_mount_t *mp)¶ Unmount filesystem.
Perform steps needed to unmount a file system like calling the file system specific unmount function and removing the mount point from mounted file system list.
- Parameters
mp – Pointer to the fs_mount_t structure
- Returns 0
on success;
- Returns -EINVAL
if no system has been mounted at given mount point;
- Returns -ENOTSUP
when not supported by underlying file system driver;
- Returns <0
an other negative errno code on error.
-
int
fs_readmount
(int *index, const char **name)¶ Get path of mount point at index.
This function iterates through the list of mount points and returns the directory name of the mount point at the given
index
. On successindex
is incremented andname
is set to the mount directory name. If a mount point with the givenindex
does not exist,name
will be set toNULL
.- Parameters
index – Pointer to mount point index
name – Pointer to pointer to path name
- Returns 0
on success;
- Returns -ENOENT
if there is no mount point with given index.
-
int
fs_stat
(const char *path, struct fs_dirent *entry)¶ File or directory status.
Checks the status of a file or directory specified by the
path
.Note
The file on a storage device may not be updated until it is closed.
- Parameters
path – Path to the file or directory
entry – Pointer to the zfs_dirent structure to fill if the file or directory exists.
- Returns 0
on success;
- Returns <0
negative errno code on error.
-
int
fs_statvfs
(const char *path, struct fs_statvfs *stat)¶ Retrieves statistics of the file system volume.
Returns the total and available space in the file system volume.
- Parameters
path – Path to the mounted directory
stat – Pointer to the zfs_statvfs structure to receive the fs statistics
- Returns 0
on success;
- Returns -ENOTSUP
when not implemented by underlying file system driver;
- Returns <0
an other negative errno code on error.
-
int
fs_register
(int type, const struct fs_file_system_t *fs)¶ Register a file system.
Register file system with virtual file system.
- Parameters
type – Type of file system (ex:
FS_FATFS
)fs – Pointer to File system
- Returns 0
on success;
- Returns <0
negative errno code on error.
-
int
fs_unregister
(int type, const struct fs_file_system_t *fs)¶ Unregister a file system.
Unregister file system from virtual file system.
- Parameters
type – Type of file system (ex:
FS_FATFS
)fs – Pointer to File system
- Returns 0
on success;
- Returns <0
negative errno code on error.
-
struct
fs_mount_t
¶ - #include <fs.h>
File system mount info structure.
- param node
Entry for the fs_mount_list list
- param type
File system type
- param mnt_point
Mount point directory name (ex: “/fatfs”)
- param fs_data
Pointer to file system specific data
- param storage_dev
Pointer to backend storage device
- param mountp_len
Length of Mount point string
- param fs
Pointer to File system interface of the mount point
- param flags
Mount flags
-
struct
fs_dirent
¶ - #include <fs.h>
Structure to receive file or directory information.
Used in functions that reads the directory entries to get file or directory information.
- param dir_entry_type
Whether file or directory
FS_DIR_ENTRY_FILE
FS_DIR_ENTRY_DIR
- param name
Name of directory or file
- param size
Size of file. 0 if directory
-
struct
fs_statvfs
- #include <fs.h>
Structure to receive volume statistics.
Used to retrieve information about total and available space in the volume.
- param f_bsize
Optimal transfer block size
- param f_frsize
Allocation unit size
- param f_blocks
Size of FS in f_frsize units
- param f_bfree
Number of free blocks
-
struct
fs_file_t
¶ - #include <fs_interface.h>
File object representing an open file.
The object needs to be initialized with function fs_file_t_init().
- param Pointer
to FATFS file object structure
- param mp
Pointer to mount point structure
-
struct
fs_dir_t
¶ - #include <fs_interface.h>
Directory object representing an open directory.
The object needs to be initialized with function fs_dir_t_init().
- param dirp
Pointer to directory object structure
- param mp
Pointer to mount point structure
-
struct
fs_file_system_t
¶ - #include <fs_sys.h>
File System interface structure.
- param open
Opens or creates a file, depending on flags given
- param read
Reads nbytes number of bytes
- param write
Writes nbytes number of bytes
- param lseek
Moves the file position to a new location in the file
- param tell
Retrieves the current position in the file
- param truncate
Truncates/expands the file to the new length
- param sync
Flushes the cache of an open file
- param close
Flushes the associated stream and closes the file
- param opendir
Opens an existing directory specified by the path
- param readdir
Reads directory entries of an open directory
- param closedir
Closes an open directory
- param mount
Mounts a file system
- param unmount
Unmounts a file system
- param unlink
Deletes the specified file or directory
- param rename
Renames a file or directory
- param mkdir
Creates a new directory using specified path
- param stat
Checks the status of a file or directory specified by the path
- param statvfs
Returns the total and available space on the file system volume
-