File System APIs. More...

Data Structures
struct	fs_mount_t
	File system mount info structure. More...

struct	fs_dirent
	Structure to receive file or directory information. More...

struct	fs_statvfs
	Structure to receive volume statistics. More...

struct	fs_file_t
	File object representing an open file. More...

struct	fs_dir_t
	Directory object representing an open directory. More...

struct	fs_file_system_t
	File System interface structure. More...

Macros
#define	FS_MOUNT_FLAG_NO_FORMAT BIT(0)

#define	FS_MOUNT_FLAG_READ_ONLY BIT(1)

#define	FS_MOUNT_FLAG_AUTOMOUNT BIT(2)

#define	FSTAB_ENTRY_DT_MOUNT_FLAGS(node_id)

#define	FS_FSTAB_ENTRY(node_id) _CONCAT(z_fsmp_, node_id)
	The name under which a zephyr,fstab entry mount structure is defined. More...

#define	FS_FSTAB_DECLARE_ENTRY(node_id) extern struct fs_mount_t FS_FSTAB_ENTRY(node_id)
	Generate a declaration for the externally defined fstab entry. More...

Enumerations
enum	fs_dir_entry_type { FS_DIR_ENTRY_FILE = 0 , FS_DIR_ENTRY_DIR }

enum	{ FS_FATFS = 0 , FS_LITTLEFS , FS_TYPE_EXTERNAL_BASE }
	Enumeration to uniquely identify file system types. More...

Functions
static void	fs_file_t_init (struct fs_file_t *zfp)
	Initialize fs_file_t object. More...

static void	fs_dir_t_init (struct fs_dir_t *zdp)
	Initialize fs_dir_t object. More...

int	fs_open (struct fs_file_t zfp, const char file_name, fs_mode_t flags)
	Open or create file. More...

int	fs_close (struct fs_file_t *zfp)
	Close file. More...

int	fs_unlink (const char *path)
	Unlink file. More...

int	fs_rename (const char from, const char to)
	Rename file or directory. More...

ssize_t	fs_read (struct fs_file_t zfp, void ptr, size_t size)
	Read file. More...

ssize_t	fs_write (struct fs_file_t zfp, const void ptr, size_t size)
	Write file. More...

int	fs_seek (struct fs_file_t *zfp, off_t offset, int whence)
	Seek file. More...

off_t	fs_tell (struct fs_file_t *zfp)
	Get current file position. More...

int	fs_truncate (struct fs_file_t *zfp, off_t length)
	Truncate or extend an open file to a given size. More...

int	fs_sync (struct fs_file_t *zfp)
	Flush cached write data buffers of an open file. More...

int	fs_mkdir (const char *path)
	Directory create. More...

int	fs_opendir (struct fs_dir_t zdp, const char path)
	Directory open. More...

int	fs_readdir (struct fs_dir_t zdp, struct fs_dirent entry)
	Directory read entry. More...

int	fs_closedir (struct fs_dir_t *zdp)
	Directory close. More...

int	fs_mount (struct fs_mount_t *mp)
	Mount filesystem. More...

int	fs_unmount (struct fs_mount_t *mp)
	Unmount filesystem. More...

int	fs_readmount (int index, const char *name)
	Get path of mount point at index. More...

int	fs_stat (const char path, struct fs_dirent entry)
	File or directory status. More...

int	fs_statvfs (const char path, struct fs_statvfs stat)
	Retrieves statistics of the file system volume. More...

int	fs_register (int type, const struct fs_file_system_t *fs)
	Register a file system. More...

int	fs_unregister (int type, const struct fs_file_system_t *fs)
	Unregister a file system. More...

fs_open open and creation mode flags
#define	FS_O_READ 0x01

#define	FS_O_WRITE 0x02

#define	FS_O_RDWR (FS_O_READ \| FS_O_WRITE)

#define	FS_O_MODE_MASK 0x03

#define	FS_O_CREATE 0x10

#define	FS_O_APPEND 0x20

#define	FS_O_FLAGS_MASK 0x30

#define	FS_O_MASK (FS_O_MODE_MASK \| FS_O_FLAGS_MASK)

fs_seek whence parameter values
#define	FS_SEEK_SET 0

#define	FS_SEEK_CUR 1

#define	FS_SEEK_END 2

Detailed Description

File System APIs.

Macro Definition Documentation

◆ FS_FSTAB_DECLARE_ENTRY

#define FS_FSTAB_DECLARE_ENTRY ( node_id ) extern struct fs_mount_t FS_FSTAB_ENTRY(node_id)

#include <include/fs/fs.h>

Generate a declaration for the externally defined fstab entry.

This will evaluate to the name of a struct fs_mount_t object.

◆ FS_FSTAB_ENTRY

#define FS_FSTAB_ENTRY ( node_id ) _CONCAT(z_fsmp_, node_id)

#include <include/fs/fs.h>

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

◆ FS_MOUNT_FLAG_AUTOMOUNT

#define FS_MOUNT_FLAG_AUTOMOUNT BIT(2)

#include <include/fs/fs.h>

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_NO_FORMAT

#define FS_MOUNT_FLAG_NO_FORMAT BIT(0)

#include <include/fs/fs.h>

Flag prevents formatting device if requested file system not found

◆ FS_MOUNT_FLAG_READ_ONLY

#define FS_MOUNT_FLAG_READ_ONLY BIT(1)

#include <include/fs/fs.h>

Flag makes mounted file system read-only

◆ FS_O_APPEND

#define FS_O_APPEND 0x20

#include <include/fs/fs.h>

Open/create file for append

◆ FS_O_CREATE

#define FS_O_CREATE 0x10

#include <include/fs/fs.h>

Create file if it does not exist

◆ FS_O_FLAGS_MASK

#define FS_O_FLAGS_MASK 0x30

#include <include/fs/fs.h>

Bitmask for open/create flags

◆ FS_O_MASK

#define FS_O_MASK (FS_O_MODE_MASK | FS_O_FLAGS_MASK)

#include <include/fs/fs.h>

Bitmask for open flags

◆ FS_O_MODE_MASK

#define FS_O_MODE_MASK 0x03

#include <include/fs/fs.h>

Bitmask for read and write flags

◆ FS_O_RDWR

#define FS_O_RDWR (FS_O_READ | FS_O_WRITE)

#include <include/fs/fs.h>

Open for read-write flag combination

◆ FS_O_READ

#define FS_O_READ 0x01

#include <include/fs/fs.h>

Open for read flag

◆ FS_O_WRITE

#define FS_O_WRITE 0x02

#include <include/fs/fs.h>

Open for write flag

◆ FS_SEEK_CUR

#define FS_SEEK_CUR 1

#include <include/fs/fs.h>

Seek from a current position

◆ FS_SEEK_END

#define FS_SEEK_END 2

#include <include/fs/fs.h>

Seek from the end of file

◆ FS_SEEK_SET

#define FS_SEEK_SET 0

#include <include/fs/fs.h>

Seek from the beginning of file

◆ FSTAB_ENTRY_DT_MOUNT_FLAGS

#define FSTAB_ENTRY_DT_MOUNT_FLAGS ( node_id )

#include <include/fs/fs.h>

Value:

        ((DT_PROP(node_id, automount) ? FS_MOUNT_FLAG_AUTOMOUNT : 0)    \
         | (DT_PROP(node_id, read_only) ? FS_MOUNT_FLAG_READ_ONLY : 0)  \
         | (DT_PROP(node_id, no_format) ? FS_MOUNT_FLAG_NO_FORMAT : 0))

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

#include <include/fs/fs.h>

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.

Enumerator
FS_FATFS	Identifier for in-tree FatFS file system.
FS_LITTLEFS	Identifier for in-tree LittleFS file system.
FS_TYPE_EXTERNAL_BASE	Base identifier for external file systems.

◆ fs_dir_entry_type

enum fs_dir_entry_type

#include <include/fs/fs.h>

Enumerator
FS_DIR_ENTRY_FILE	Identifier for file entry
FS_DIR_ENTRY_DIR	Identifier for directory entry

Function Documentation

◆ fs_close()

int fs_close ( struct fs_file_t * zfp )

#include <include/fs/fs.h>

Close file.

Flushes the associated stream and closes the file.

Parameters

zfp	Pointer to the file object

Return values

0	on success;
<0	a negative errno code on error.

◆ fs_closedir()

int fs_closedir ( struct fs_dir_t * zdp )

#include <include/fs/fs.h>

Directory close.

Closes an open directory.

Parameters

zdp	Pointer to the directory object

Return values

0	on success;
<0	a negative errno code on error.

◆ fs_dir_t_init()

static void fs_dir_t_init ( struct fs_dir_t * zdp )

inlinestatic

#include <include/fs/fs.h>

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

◆ fs_file_t_init()

static void fs_file_t_init ( struct fs_file_t * zfp )

inlinestatic

#include <include/fs/fs.h>

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

◆ fs_mkdir()

int fs_mkdir ( const char * path )

#include <include/fs/fs.h>

Directory create.

Creates a new directory using specified path.

Parameters

path	Path to the directory to create

Return values

0	on success;
-ENOTSUP	when not implemented by underlying file system driver;
<0	an other negative errno code on error

◆ fs_mount()

int fs_mount ( struct fs_mount_t * mp )

#include <include/fs/fs.h>

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;
-EROFS	if system requires formatting but `FS_MOUNT_FLAG_READ_ONLY` has been set;
<0	an other negative errno code on error.

◆ fs_open()

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

#include <include/fs/fs.h>

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

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

Return values

0	on success;
-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 path is not possible (bad mount point);
<0	an other negative errno code, depending on a file system back-end.

◆ fs_opendir()

int fs_opendir	(	struct fs_dir_t *	zdp,
		const char *	path
	)

#include <include/fs/fs.h>

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;
<0	a negative errno code on error.

◆ fs_read()

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

#include <include/fs/fs.h>

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;
<0	a negative errno code on error.

◆ fs_readdir()

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

#include <include/fs/fs.h>

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;;
<0	a negative errno code on error.

◆ fs_readmount()

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

#include <include/fs/fs.h>

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.

◆ fs_register()

int fs_register	(	int	type,
		const struct fs_file_system_t *	fs
	)

#include <include/fs/fs.h>

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 values

0	on success;
<0	negative errno code on error.

◆ fs_rename()

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

#include <include/fs/fs.h>

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;
-ENOTSUP	when not implemented by underlying file system driver;
<0	an other negative errno code on error.

◆ fs_seek()

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

#include <include/fs/fs.h>

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;
-ENOTSUP	if not supported by underlying file system driver;
<0	an other negative errno code on error.

◆ fs_stat()

int fs_stat	(	const char *	path,
		struct fs_dirent *	entry
	)

#include <include/fs/fs.h>

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;
<0	negative errno code on error.

◆ fs_statvfs()

int fs_statvfs	(	const char *	path,
		struct fs_statvfs *	stat
	)

#include <include/fs/fs.h>

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;
-ENOTSUP	when not implemented by underlying file system driver;
<0	an other negative errno code on error.

◆ fs_sync()

int fs_sync ( struct fs_file_t * zfp )

#include <include/fs/fs.h>

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;
<0	a negative errno code on error.

◆ fs_tell()

off_t fs_tell ( struct fs_file_t * zfp )

#include <include/fs/fs.h>

Get current file position.

Retrieves and returns the current position in the file stream.

Parameters

zfp	Pointer to the file object

Return values

>=	0 a current position in file;
-ENOTSUP	if not supported by underlying file system driver;
<0	an other negative errno code on error.

The current revision does not validate the file object.

◆ fs_truncate()

int fs_truncate	(	struct fs_file_t *	zfp,
		off_t	length
	)

#include <include/fs/fs.h>

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;
-ENOTSUP	when not implemented by underlying file system driver;
<0	an other negative errno code on error.

◆ fs_unlink()

int fs_unlink ( const char * path )

#include <include/fs/fs.h>

Unlink file.

Deletes the specified file or directory

Parameters

path	Path to the file or directory to delete

Return values

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

◆ fs_unmount()

int fs_unmount ( struct fs_mount_t * mp )

#include <include/fs/fs.h>

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.

◆ fs_unregister()

int fs_unregister	(	int	type,
		const struct fs_file_system_t *	fs
	)

#include <include/fs/fs.h>

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;
<0	negative errno code on error.

◆ fs_write()

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

#include <include/fs/fs.h>

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;
-ENOTSUP	when not implemented by underlying file system driver;
<0	an other negative errno code on error.

Data Structures

Macros

Enumerations

Functions

fs_open open and creation mode flags

fs_seek whence parameter values

Detailed Description

Macro Definition Documentation

◆ FS_FSTAB_DECLARE_ENTRY

◆ FS_FSTAB_ENTRY

◆ FS_MOUNT_FLAG_AUTOMOUNT

◆ FS_MOUNT_FLAG_NO_FORMAT

◆ FS_MOUNT_FLAG_READ_ONLY

◆ FS_O_APPEND

◆ FS_O_CREATE

◆ FS_O_FLAGS_MASK

◆ FS_O_MASK

◆ FS_O_MODE_MASK

◆ FS_O_RDWR

◆ FS_O_READ

◆ FS_O_WRITE

◆ FS_SEEK_CUR

◆ FS_SEEK_END

◆ FS_SEEK_SET

◆ FSTAB_ENTRY_DT_MOUNT_FLAGS

Enumeration Type Documentation

◆ anonymous enum

◆ fs_dir_entry_type

Function Documentation

◆ fs_close()

◆ fs_closedir()

◆ fs_dir_t_init()

◆ fs_file_t_init()

◆ fs_mkdir()

◆ fs_mount()

◆ fs_open()

◆ fs_opendir()

◆ fs_read()

◆ fs_readdir()

◆ fs_readmount()

◆ fs_register()

◆ fs_rename()

◆ fs_seek()

◆ fs_stat()

◆ fs_statvfs()

◆ fs_sync()

◆ fs_tell()

◆ fs_truncate()

◆ fs_unlink()

◆ fs_unmount()

◆ fs_unregister()

◆ fs_write()