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.

Sample

A sample of how the file system can be used is supplied in samples/subsys/fs.

API Reference

group file_system_api

File System APIs.

Defines

FS_O_READ
FS_O_WRITE
FS_O_RDWR
FS_O_MODE_MASK
FS_O_CREATE
FS_O_APPEND
FS_O_FLAGS_MASK
FS_O_MASK
FS_SEEK_SET
FS_SEEK_CUR
FS_SEEK_END

Enums

enum fs_dir_entry_type

Values:

enumerator FS_DIR_ENTRY_FILE
enumerator FS_DIR_ENTRY_DIR
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

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.

Functions

int fs_open(struct fs_file_t *zfp, const char *file_name, fs_mode_t flags)

File open.

Opens or creates, if does not exist, file depending on flags provided and associates a stream with it.

flags can be empty, or combination of one or more of following flags: FS_O_READ open for read FS_O_WRITE open for write FS_O_RDWR open for read/write (FS_O_READ | FS_O_WRITE) FS_O_CREATE create file if it does not exist FS_O_APPEND move to end of file before each write

Parameters

  • zfp: Pointer to file object

  • file_name: The name of file to open

  • flags: The mode flags

Return Value

  • 0: Success

  • -EINVAL: when bad file name is given

  • -NOENT: when file path is not possible (bad mount point)

  • other: negative error code, depending on file system back-end.

int fs_close(struct fs_file_t *zfp)

File close.

Flushes the associated stream and closes the file.

Parameters

  • zfp: Pointer to the file object

Return Value

  • 0: Success

  • -ERRNO: errno code if error

File unlink.

Deletes the specified file or directory

Parameters

  • path: Path to the file or directory to delete

Return Value

  • 0: Success

  • -ERRNO: errno code if error

int fs_rename(const char *from, const char *to)

File o directory rename.

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).

Parameters

  • from: The source path.

  • to: The destination path.

Return Value

  • 0: Success;

  • -ERRNO: errno code if error

ssize_t fs_read(struct fs_file_t *zfp, void *ptr, size_t size)

File read.

Reads items of data of size bytes long.

Return

Number of bytes read. On success, it will be equal to number of items requested to be read. Returns less than number of bytes requested if there are not enough bytes available in file. Will return -ERRNO code on error.

Parameters

  • zfp: Pointer to the file object

  • ptr: Pointer to the data buffer

  • size: Number of bytes to be read

ssize_t fs_write(struct fs_file_t *zfp, const void *ptr, size_t size)

File write.

Writes items of data of size bytes long.

Return

Number of bytes written. On success, it will be equal to the number of bytes requested to be written. Any other value, indicates an error. Will return -ERRNO code on error. In the case where -ERRNO is returned, the file pointer will not be advanced because it couldn’t start the operation. In the case where it is able to write, but is not able to complete writing all of the requested number of bytes, then it is because the disk got full. In that case, it returns less number of bytes written than requested, but not a negative -ERRNO value as in regular error case.

Parameters

  • zfp: Pointer to the file object

  • ptr: Pointer to the data buffer

  • size: Number of bytes to be write

int fs_seek(struct fs_file_t *zfp, off_t offset, int whence)

File seek.

Moves the file position to a new location in the file. The offset is added to file position based on the ‘whence’ 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 = from beginning of file

    • FS_SEEK_CUR = from current position,

    • FS_SEEK_END = from end of file.

Return Value

  • 0: Success

  • -ERRNO: errno code if error.

off_t fs_tell(struct fs_file_t *zfp)

Get current file position.

Retrieves the current position in the file.

Parameters

  • zfp: Pointer to the file object

Return Value

  • position: Current position in file Current revision does not validate the file object.

int fs_truncate(struct fs_file_t *zfp, off_t length)

Change the size of an open file.

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 returns 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

Return Value

  • 0: Success

  • -ERRNO: errno code if error

int fs_sync(struct fs_file_t *zfp)

Flushes any cached write of an open file.

This function can be used to flush the cache of an open file. This can be called to ensure data gets written to the storage media immediately. This may be done to avoid data loss if power is removed unexpectedly. Note that closing a file will cause caches to be flushed correctly so it need not be called if the file is being closed.

Parameters

  • zfp: Pointer to the file object

Return Value

  • 0: Success

  • -ERRNO: errno code if error

int fs_mkdir(const char *path)

Directory create.

Creates a new directory using specified path.

Parameters

  • path: Path to the directory to create

Return Value

  • 0: Success

  • -ERRNO: errno code if 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

Return Value

  • 0: Success

  • -ERRNO: errno code if error

int fs_readdir(struct fs_dir_t *zdp, struct fs_dirent *entry)

Directory read entry.

Reads directory entries of a open directory.

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.

Return

In end-of-dir condition, this will return 0 and set entry->name[0] = 0

Parameters

  • zdp: Pointer to the directory object

  • entry: Pointer to zfs_dirent structure to read the entry into

Return Value

  • 0: Success

  • -ERRNO: errno code if error

int fs_closedir(struct fs_dir_t *zdp)

Directory close.

Closes an open directory.

Parameters

  • zdp: Pointer to the directory object

Return Value

  • 0: Success

  • -ERRNO: errno code if 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.

Parameters
Return Value

  • 0: Success

  • -ERRNO: errno code if error

int fs_unmount(struct fs_mount_t *mp)

Unmount filesystem.

Perform steps needed for unmounting a file system like calling the file system specific unmount function and removing the mount point from mounted file system list.

Parameters
Return Value

  • 0: Success

  • -ERRNO: errno code if error

int fs_readmount(int *number, const char **name)

Mount point read entry.

Read mount point entry

Return

On success number is incremented and name is set to mount point name. In case no mount point exists for the given number -ENOENT is returned and name is set to NULL.

Parameters

  • number: Pointer to mount point number

  • name: Pointer to mount point name

Return Value

  • 0: Success

  • -ERRNO: errno code if error

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

Parameters

  • path: Path to the file or directory

  • entry: Pointer to zfs_dirent structure to fill if file or directory exists.

Return Value

  • 0: Success

  • -ERRNO: errno code if 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 zfs_statvfs structure to receive the fs statistics

Return Value

  • 0: Success

  • -ERRNO: errno code if 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

Return Value

  • 0: Success

  • -ERRNO: errno code if 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

Return Value

  • 0: Success

  • -ERRNO: errno code if error

struct fs_mount_t
#include <fs.h>

File system mount info structure.

Parameters

  • node: Entry for the fs_mount_list list

  • type: File system type

  • mnt_point: Mount point directory name (ex: “/fatfs”)

  • fs_data: Pointer to file system specific data

  • storage_dev: Pointer to backend storage device

  • mountp_len: Length of Mount point string

  • fs: Pointer to File system interface of the mount point

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.

Parameters

  • dir_entry_type: Whether file or directory

    • FS_DIR_ENTRY_FILE

    • FS_DIR_ENTRY_DIR

  • name: Name of directory or file

  • 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.

Parameters

  • f_bsize: Optimal transfer block size

  • f_frsize: Allocation unit size

  • f_blocks: Size of FS in f_frsize units

  • f_bfree: Number of free blocks

struct fs_file_system_t
#include <fs.h>

File System interface structure.

Parameters

  • open: Opens or creates a file, depending on flags given

  • read: Reads items of data of size bytes long

  • write: Writes items of data of size bytes long

  • lseek: Moves the file position to a new location in the file

  • tell: Retrieves the current position in the file

  • truncate: Truncates the file to the new length

  • sync: Flush the cache of an open file

  • close: Flushes the associated stream and closes the file

  • opendir: Opens an existing directory specified by the path

  • readdir: Reads directory entries of a open directory

  • closedir: Closes an open directory

  • mount: Mount a file system

  • unmount: Unmount a file system

  • unlink: Deletes the specified file or directory

  • rename: Renames a file or directory

  • mkdir: Creates a new directory using specified path

  • stat: Checks the status of a file or directory specified by the path

  • statvfs: Returns the total and available space in the filesystem volume