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 partition
formatted to LittleFS;
samples/subsys/usb/mass/ example of USB Mass Storage device that uses FAT FS driver with RAM
or SPI connected FLASH, or LittleFS in flash, depending on the sample configuration.

API Reference

Related code samples

File system manipulation: Use file system API with various filesystems and storage devices.
File system shell: Access a LittleFS file system partition in flash using the file system shell.
Format filesystem: Format different storage devices for different file systems.
LittleFS filesystem: Use file system API over LittleFS.
USB Mass Storage: Expose board's RAM or FLASH as a USB disk using USB Mass Storage driver.

group file_system_api

File System APIs.

Since: 1.5
Version: 1.0.0

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.

FS_MOUNT_FLAG_USE_DISK_ACCESS

Flag requests file system driver to use Disk Access API.

When the flag is set to the fs_mount_t.flags prior to fs_mount call, a file system needs to use the Disk Access API, otherwise mount callback for the driver should return -ENOSUP; when the flag is not set the file system driver should use Flash API by default, unless it only supports Disc Access API. When file system will use Disk Access API and the flag is not set, the mount callback for the file system should set the flag on success.

FSTAB_ENTRY_DT_MOUNT_FLAGS(node_id)

Get the common mount flags for an fstab entry.

Parameters:

node_id – the node identifier for a child entry in a zephyr,fstab node.

Returns:

a value suitable for initializing an fs_mount_t flags member.

FS_FSTAB_ENTRY(node_id)

The name under which a zephyr,fstab entry mount structure is defined.

Parameters:

node_id – the node identifier for a child entry in a zephyr,fstab node.

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.

Parameters:

node_id – the node identifier for a child entry in a zephyr,fstab node.

Enums

enum fs_dir_entry_type

Enumeration for directory entry types.

Values:

enumerator FS_DIR_ENTRY_FILE = 0: Identifier for file entry.

enumerator FS_DIR_ENTRY_DIR: Identifier for directory entry.

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_EXT2: Identifier for in-tree Ext2 file system.

enumerator FS_TYPE_EXTERNAL_BASE: Base identifier for external file systems.

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. Successfully opened file, when no longer in use, should be closed with fs_close().

flags can be 0 or a binary combination of one or more of the following identifiers:

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

Warning

If flags are set to 0 the function will open file, if it exists and is accessible, but you will have no read/write access to it.

Parameters:

zfp – Pointer to a file object
file_name – The name of a file to open
flags – The mode flags

Return values:

0 – on success;
-EBUSY – when zfp is already used;
-EINVAL – when a bad file name is given;
-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;
-ENOENT – when the file does not exist at the path;
-ENOTSUP – when not implemented by underlying file system driver;
<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

Return values:

0 – on success;
-ENOTSUP – when not implemented by underlying file system driver;
<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

Return values:

0 – on success;
-EINVAL – when a bad file name is given;
-EROFS – if file is read-only, or when file system has been mounted with the FS_MOUNT_FLAG_READ_ONLY flag;
-ENOTSUP – when not implemented by underlying file system driver;
<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

Return values:

0 – on success;
-EINVAL – when a bad file name is given, or when rename would cause move between mount points;
-EROFS – if file is read-only, or when file system has been mounted with the FS_MOUNT_FLAG_READ_ONLY flag;
-ENOTSUP – when not implemented by underlying file system driver;
<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 to ptr pointed buffer, returns number of bytes read. A returned value may be lower than size 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

Return values:

>=0 – a number of bytes read, on success;
-EBADF – when invoked on zfp that represents unopened/closed file;
-ENOTSUP – when not implemented by underlying file system driver;
<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 than size, the global errno 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

Return values:

>=0 – a number of bytes written, on success;
-EBADF – when invoked on zfp that represents unopened/closed file;
-ENOTSUP – when not implemented by underlying file system driver;
<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 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 for the beginning of the file;
- FS_SEEK_CUR for the current position;
- FS_SEEK_END for the end of the file.

Return values:

0 – on success;
-EBADF – when invoked on zfp that represents unopened/closed file;
-ENOTSUP – if not supported by underlying file system driver;
<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

Return values:

>= – 0 a current position in file;
-EBADF – when invoked on zfp that represents unopened/closed file;
-ENOTSUP – if not supported by underlying file system driver;
<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

Return values:

0 – on success;
-EBADF – when invoked on zfp that represents unopened/closed file;
-ENOTSUP – when not implemented by underlying file system driver;
<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

Return values:

0 – on success;
-EBADF – when invoked on zfp that represents unopened/closed file;
-ENOTSUP – when not implemented by underlying file system driver;
<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

Return values:

0 – on success;
-EEXIST – if entry of given name exists;
-EROFS – if path is within read-only directory, or when file system has been mounted with the FS_MOUNT_FLAG_READ_ONLY flag;
-ENOTSUP – when not implemented by underlying file system driver;
<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

Return values:

0 – on success;
-EINVAL – when a bad directory path is given;
-EBUSY – when zdp is already used;
-ENOTSUP – when not implemented by underlying file system driver;
<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

Return values:

0 – on success or end-of-dir;
-ENOENT – when no such directory found;
-ENOTSUP – when not implemented by underlying file system driver;
<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

Return values:

0 – on success;
-ENOTSUP – when not implemented by underlying file system driver;
<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.

Return values:

0 – on success;
-ENOENT – when file system type has not been registered;
-ENOTSUP – when not supported by underlying file system driver; when FS_MOUNT_FLAG_USE_DISK_ACCESS is set but driver does not support it.
-EROFS – if system requires formatting but FS_MOUNT_FLAG_READ_ONLY has been set;
<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

Return values:

0 – on success;
-EINVAL – if no system has been mounted at given mount point;
-ENOTSUP – when not supported by underlying file system driver;
<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 success index is incremented and name is set to the mount directory name. If a mount point with the given index does not exist, name will be set to NULL.

Parameters:

index – Pointer to mount point index
name – Pointer to pointer to path name

Return values:

0 – on success;
-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.

Return values:

0 – on success;
-EINVAL – when a bad directory or file name is given;
-ENOENT – when no such directory or file is found;
-ENOTSUP – when not supported by underlying file system driver;
<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.

Return values:

0 – on success;
-EINVAL – when a bad path to a directory, or a file, is given;
-ENOTSUP – when not implemented by underlying file system driver;
<0 – an other negative errno code on error.

int fs_mkfs(int fs_type, uintptr_t dev_id, void *cfg, int flags)

Create fresh file system.

Parameters:

fs_type – Type of file system to create.
dev_id – Id of storage device.
cfg – Backend dependent init object. If NULL then default configuration is used.
flags – Additional flags for file system implementation.

Return values:

0 – on success;
<0 – 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. Number of allowed file system types to be registered is controlled with the CONFIG_FILE_SYSTEM_MAX_TYPES Kconfig option.

Parameters:

type – Type of file system (ex: FS_FATFS)
fs – Pointer to File system

Return values:

0 – on success;
-EALREADY – when a file system of a given type has already been registered;
-ENOSCP – when there is no space left, in file system registry, to add this file system type.

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 values:

0 – on success;
-EINVAL – when file system of a given type has not been registered.

struct fs_mount_t

#include <fs.h>

File system mount info structure.

Public Members

sys_dnode_t node: Entry for the fs_mount_list list.

int type: File system type.

const char *mnt_point: Mount point directory name (ex: “/fatfs”)

void *fs_data: Pointer to file system specific data.

void *storage_dev: Pointer to backend storage device.

size_t mountp_len: Length of Mount point string.

const struct fs_file_system_t *fs: Pointer to File system interface of the mount point.

uint8_t flags: Mount flags.

struct fs_dirent

#include <fs.h>

Structure to receive file or directory information.

Used in functions that read the directory entries to get file or directory information.

Public Members

enum fs_dir_entry_type type: File/directory type (FS_DIR_ENTRY_FILE or FS_DIR_ENTRY_DIR)

char name[MAX_FILE_NAME + 1]: Name of file or directory.

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

Public Members

unsigned long f_bsize: Optimal transfer block size.

unsigned long f_frsize: Allocation unit size.

unsigned long f_blocks: Size of FS in f_frsize units.

unsigned long 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 fs_file_t_init().

Public Members

void *filep: Pointer to file object structure.

const struct fs_mount_t *mp: Pointer to mount point structure.

fs_mode_t flags: Open/create flags.

struct fs_dir_t

#include <fs_interface.h>

Directory object representing an open directory.

The object needs to be initialized with fs_dir_t_init().

Public Members

void *dirp: Pointer to directory object structure.

const struct fs_mount_t *mp: Pointer to mount point structure.

struct fs_file_system_t

#include <fs_sys.h>

File System interface structure.

File operations

int (*open)(struct fs_file_t *filp, const char *fs_path, fs_mode_t flags)

Opens or creates a file, depending on flags given.

Param filp:: File to open/create.
Param fs_path:: Path to the file.
Param flags:: Flags for opening/creating the file.
Return:: 0 on success, negative errno code on fail.

ssize_t (*read)(struct fs_file_t *filp, void *dest, size_t nbytes)

Reads nbytes number of bytes.

Param filp:: File to read from.
Param dest:: Destination buffer.
Param nbytes:: Number of bytes to read.
Return:: Number of bytes read on success, negative errno code on fail.

ssize_t (*write)(struct fs_file_t *filp, const void *src, size_t nbytes)

Writes nbytes number of bytes.

Param filp:: File to write to.
Param src:: Source buffer.
Param nbytes:: Number of bytes to write.
Return:: Number of bytes written on success, negative errno code on fail.

int (*lseek)(struct fs_file_t *filp, off_t off, int whence)

Moves the file position to a new location in the file.

Param filp:: File to move.
Param off:: Relative offset from the position specified by whence.
Param whence:: Position in the file. Possible values: SEEK_CUR, SEEK_SET, SEEK_END.
Return:: New position in the file or negative errno code on fail.

off_t (*tell)(struct fs_file_t *filp)

Retrieves the current position in the file.

Param filp:: File to get the current position from.
Return:: Current position in the file or negative errno code on fail.

int (*truncate)(struct fs_file_t *filp, off_t length)

Truncates/expands the file to the new length.

Param filp:: File to truncate/expand.
Param length:: New length of the file.
Return:: 0 on success, negative errno code on fail.

int (*sync)(struct fs_file_t *filp)

Flushes the cache of an open file.

Param filp:: File to flush.
Return:: 0 on success, negative errno code on fail.

int (*close)(struct fs_file_t *filp)

Flushes the associated stream and closes the file.

Param filp:: File to close.
Return:: 0 on success, negative errno code on fail.

Directory operations

int (*opendir)(struct fs_dir_t *dirp, const char *fs_path)

Opens an existing directory specified by the path.

Param dirp:: Directory to open.
Param fs_path:: Path to the directory.
Return:: 0 on success, negative errno code on fail.

int (*readdir)(struct fs_dir_t *dirp, struct fs_dirent *entry)

Reads directory entries of an open directory.

Param dirp:: Directory to read from.
Param entry:: Next directory entry in the dirp directory.
Return:: 0 on success, negative errno code on fail.

int (*closedir)(struct fs_dir_t *dirp)

Closes an open directory.

Param dirp:: Directory to close.
Return:: 0 on success, negative errno code on fail.

File system level operations

int (*mount)(struct fs_mount_t *mountp)

Mounts a file system.

Param mountp:: Mount point.
Return:: 0 on success, negative errno code on fail.

int (*unmount)(struct fs_mount_t *mountp)

Unmounts a file system.

Param mountp:: Mount point.
Return:: 0 on success, negative errno code on fail.

int (*unlink)(struct fs_mount_t *mountp, const char *name)

Deletes the specified file or directory.

Param mountp:: Mount point.
Param name:: Path to the file or directory to delete.
Return:: 0 on success, negative errno code on fail.

int (*rename)(struct fs_mount_t *mountp, const char *from, const char *to)

Renames a file or directory.

Param mountp:: Mount point.
Param from:: Path to the file or directory to rename.
Param to:: New name of the file or directory.
Return:: 0 on success, negative errno code on fail.

int (*mkdir)(struct fs_mount_t *mountp, const char *name)

Creates a new directory using specified path.

Param mountp:: Mount point.
Param name:: Path to the directory to create.
Return:: 0 on success, negative errno code on fail.

int (*stat)(struct fs_mount_t *mountp, const char *path, struct fs_dirent *entry)

Checks the status of a file or directory specified by the path.

Param mountp:: Mount point.
Param path:: Path to the file or directory.
Param entry:: Directory entry.
Return:: 0 on success, negative errno code on fail.

int (*statvfs)(struct fs_mount_t *mountp, const char *path, struct fs_statvfs *stat)

Returns the total and available space on the file system volume.

Param mountp:: Mount point.
Param path:: Path to the file or directory.
Param stat:: File system statistics.
Return:: 0 on success, negative errno code on fail.

int (*mkfs)(uintptr_t dev_id, void *cfg, int flags)

Formats a device to specified file system type.

Available only if CONFIG_FILE_SYSTEM_MKFS is enabled.

Note

This operation destroys existing data on the target device.

Param dev_id:: Device identifier.
Param cfg:: File system configuration.
Param flags:: Formatting flags.
Return:: 0 on success, negative errno code on fail.