Zephyr API Documentation
3.7.0
A Scalable Open Source RTOS
|
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) |
Flag prevents formatting device if requested file system not found. | |
#define | FS_MOUNT_FLAG_READ_ONLY BIT(1) |
Flag makes mounted file system read-only. | |
#define | FS_MOUNT_FLAG_AUTOMOUNT BIT(2) |
Flag used in pre-defined mount structures that are to be mounted on startup. | |
#define | FS_MOUNT_FLAG_USE_DISK_ACCESS BIT(3) |
Flag requests file system driver to use Disk Access API. | |
#define | FSTAB_ENTRY_DT_MOUNT_FLAGS(node_id) |
Get the common mount flags for an fstab entry. | |
#define | FS_FSTAB_ENTRY(node_id) _CONCAT(z_fsmp_, node_id) |
The name under which a zephyr,fstab entry mount structure is defined. | |
#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. | |
Enumerations | |
enum | fs_dir_entry_type { FS_DIR_ENTRY_FILE = 0 , FS_DIR_ENTRY_DIR } |
Enumeration for directory entry types. More... | |
enum | { FS_FATFS = 0 , FS_LITTLEFS , FS_EXT2 , 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. | |
static void | fs_dir_t_init (struct fs_dir_t *zdp) |
Initialize fs_dir_t object. | |
int | fs_open (struct fs_file_t *zfp, const char *file_name, fs_mode_t flags) |
Open or create file. | |
int | fs_close (struct fs_file_t *zfp) |
Close file. | |
int | fs_unlink (const char *path) |
Unlink file. | |
int | fs_rename (const char *from, const char *to) |
Rename file or directory. | |
ssize_t | fs_read (struct fs_file_t *zfp, void *ptr, size_t size) |
Read file. | |
ssize_t | fs_write (struct fs_file_t *zfp, const void *ptr, size_t size) |
Write file. | |
int | fs_seek (struct fs_file_t *zfp, off_t offset, int whence) |
Seek file. | |
off_t | fs_tell (struct fs_file_t *zfp) |
Get current file position. | |
int | fs_truncate (struct fs_file_t *zfp, off_t length) |
Truncate or extend an open file to a given size. | |
int | fs_sync (struct fs_file_t *zfp) |
Flush cached write data buffers of an open file. | |
int | fs_mkdir (const char *path) |
Directory create. | |
int | fs_opendir (struct fs_dir_t *zdp, const char *path) |
Directory open. | |
int | fs_readdir (struct fs_dir_t *zdp, struct fs_dirent *entry) |
Directory read entry. | |
int | fs_closedir (struct fs_dir_t *zdp) |
Directory close. | |
int | fs_mount (struct fs_mount_t *mp) |
Mount filesystem. | |
int | fs_unmount (struct fs_mount_t *mp) |
Unmount filesystem. | |
int | fs_readmount (int *index, const char **name) |
Get path of mount point at index. | |
int | fs_stat (const char *path, struct fs_dirent *entry) |
File or directory status. | |
int | fs_statvfs (const char *path, struct fs_statvfs *stat) |
Retrieves statistics of the file system volume. | |
int | fs_mkfs (int fs_type, uintptr_t dev_id, void *cfg, int flags) |
Create fresh file system. | |
int | fs_register (int type, const struct fs_file_system_t *fs) |
Register a file system. | |
int | fs_unregister (int type, const struct fs_file_system_t *fs) |
Unregister a file system. | |
fs_open open and creation mode flags | |
#define | FS_O_READ 0x01 |
Open for read flag. | |
#define | FS_O_WRITE 0x02 |
Open for write flag. | |
#define | FS_O_RDWR (FS_O_READ | FS_O_WRITE) |
Open for read-write flag combination. | |
#define | FS_O_MODE_MASK 0x03 |
Bitmask for read and write flags. | |
#define | FS_O_CREATE 0x10 |
Create file if it does not exist. | |
#define | FS_O_APPEND 0x20 |
Open/create file for append. | |
#define | FS_O_TRUNC 0x40 |
Truncate the file while opening. | |
#define | FS_O_FLAGS_MASK 0x70 |
Bitmask for open/create flags. | |
#define | FS_O_MASK (FS_O_MODE_MASK | FS_O_FLAGS_MASK) |
Bitmask for open flags. | |
fs_seek whence parameter values | |
#define | FS_SEEK_SET 0 |
Seek from the beginning of file. | |
#define | FS_SEEK_CUR 1 |
Seek from a current position. | |
#define | FS_SEEK_END 2 |
Seek from the end of file. | |
File System APIs.
#define FS_FSTAB_DECLARE_ENTRY | ( | node_id | ) | extern struct fs_mount_t FS_FSTAB_ENTRY(node_id) |
#include <zephyr/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.
node_id | the node identifier for a child entry in a zephyr,fstab node. |
#define FS_FSTAB_ENTRY | ( | node_id | ) | _CONCAT(z_fsmp_, node_id) |
#include <zephyr/fs/fs.h>
The name under which a zephyr,fstab entry mount structure is defined.
node_id | the node identifier for a child entry in a zephyr,fstab node. |
#define FS_MOUNT_FLAG_AUTOMOUNT BIT(2) |
#include <zephyr/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.
#define FS_MOUNT_FLAG_NO_FORMAT BIT(0) |
#include <zephyr/fs/fs.h>
Flag prevents formatting device if requested file system not found.
#define FS_MOUNT_FLAG_READ_ONLY BIT(1) |
#include <zephyr/fs/fs.h>
Flag makes mounted file system read-only.
#define FS_MOUNT_FLAG_USE_DISK_ACCESS BIT(3) |
#include <zephyr/fs/fs.h>
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.
#define FS_O_APPEND 0x20 |
#include <zephyr/fs/fs.h>
Open/create file for append.
#define FS_O_CREATE 0x10 |
#include <zephyr/fs/fs.h>
Create file if it does not exist.
#define FS_O_FLAGS_MASK 0x70 |
#include <zephyr/fs/fs.h>
Bitmask for open/create flags.
#define FS_O_MASK (FS_O_MODE_MASK | FS_O_FLAGS_MASK) |
#include <zephyr/fs/fs.h>
Bitmask for open flags.
#define FS_O_MODE_MASK 0x03 |
#include <zephyr/fs/fs.h>
Bitmask for read and write flags.
#define FS_O_RDWR (FS_O_READ | FS_O_WRITE) |
#include <zephyr/fs/fs.h>
Open for read-write flag combination.
#define FS_O_READ 0x01 |
#include <zephyr/fs/fs.h>
Open for read flag.
#define FS_O_TRUNC 0x40 |
#include <zephyr/fs/fs.h>
Truncate the file while opening.
#define FS_O_WRITE 0x02 |
#include <zephyr/fs/fs.h>
Open for write flag.
#define FS_SEEK_CUR 1 |
#include <zephyr/fs/fs.h>
Seek from a current position.
#define FS_SEEK_END 2 |
#include <zephyr/fs/fs.h>
Seek from the end of file.
#define FS_SEEK_SET 0 |
#include <zephyr/fs/fs.h>
Seek from the beginning of file.
#define FSTAB_ENTRY_DT_MOUNT_FLAGS | ( | node_id | ) |
#include <zephyr/fs/fs.h>
Get the common mount flags for an fstab entry.
node_id | the node identifier for a child entry in a zephyr,fstab node. |
anonymous enum |
#include <zephyr/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.
enum fs_dir_entry_type |
#include <zephyr/fs/fs.h>
Enumeration for directory entry types.
Enumerator | |
---|---|
FS_DIR_ENTRY_FILE | Identifier for file entry. |
FS_DIR_ENTRY_DIR | Identifier for directory entry. |
int fs_close | ( | struct fs_file_t * | zfp | ) |
#include <zephyr/fs/fs.h>
Close file.
Flushes the associated stream and closes the file.
zfp | Pointer to the file object |
0 | on success; |
-ENOTSUP | when not implemented by underlying file system driver; |
<0 | a negative errno code on error. |
int fs_closedir | ( | struct fs_dir_t * | zdp | ) |
#include <zephyr/fs/fs.h>
Directory close.
Closes an open directory.
zdp | Pointer to the directory object |
0 | on success; |
-ENOTSUP | when not implemented by underlying file system driver; |
<0 | a negative errno code on error. |
|
inlinestatic |
#include <zephyr/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.
zdp | Pointer to file object |
|
inlinestatic |
#include <zephyr/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.
zfp | Pointer to file object |
int fs_mkdir | ( | const char * | path | ) |
#include <zephyr/fs/fs.h>
Directory create.
Creates a new directory using specified path.
path | Path to the directory to create |
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_mkfs | ( | int | fs_type, |
uintptr_t | dev_id, | ||
void * | cfg, | ||
int | flags | ||
) |
#include <zephyr/fs/fs.h>
Create fresh file system.
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. |
0 | on success; |
<0 | negative errno code on error. |
int fs_mount | ( | struct fs_mount_t * | mp | ) |
#include <zephyr/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.
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. |
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. |
#include <zephyr/fs/fs.h>
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 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 writeFS_O_TRUNC
truncate the fileflags
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.zfp | Pointer to a file object |
file_name | The name of a file to open |
flags | The mode flags |
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; |
-EACCES | when trying to truncate a file without opening it for write. |
<0 | an other negative errno code, depending on a file system back-end. |
int fs_opendir | ( | struct fs_dir_t * | zdp, |
const char * | path | ||
) |
#include <zephyr/fs/fs.h>
Directory open.
Opens an existing directory specified by the path.
zdp | Pointer to the directory object |
path | Path to the directory to open |
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. |
#include <zephyr/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.
zfp | Pointer to the file object |
ptr | Pointer to the data buffer |
size | Number of bytes to be read |
>=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. |
#include <zephyr/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.
zdp | Pointer to the directory object |
entry | Pointer to zfs_dirent structure to read the entry into |
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_readmount | ( | int * | index, |
const char ** | name | ||
) |
#include <zephyr/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
.
index | Pointer to mount point index |
name | Pointer to pointer to path name |
0 | on success; |
-ENOENT | if there is no mount point with given index. |
int fs_register | ( | int | type, |
const struct fs_file_system_t * | fs | ||
) |
#include <zephyr/fs/fs.h>
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.
type | Type of file system (ex: FS_FATFS ) |
fs | Pointer to File system |
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_rename | ( | const char * | from, |
const char * | to | ||
) |
#include <zephyr/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).
from | The source path |
to | The destination path |
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. |
#include <zephyr/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.
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.
|
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. |
int fs_stat | ( | const char * | path, |
struct fs_dirent * | entry | ||
) |
#include <zephyr/fs/fs.h>
File or directory status.
Checks the status of a file or directory specified by the path
.
path | Path to the file or directory |
entry | Pointer to the zfs_dirent structure to fill if the file or directory exists. |
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 | ||
) |
#include <zephyr/fs/fs.h>
Retrieves statistics of the file system volume.
Returns the total and available space in the file system volume.
path | Path to the mounted directory |
stat | Pointer to the zfs_statvfs structure to receive the fs statistics. |
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_sync | ( | struct fs_file_t * | zfp | ) |
#include <zephyr/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.
zfp | Pointer to the file object |
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. |
#include <zephyr/fs/fs.h>
Get current file position.
Retrieves and returns the current position in the file stream.
zfp | Pointer to the file object |
>= | 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. |
The current revision does not validate the file object.
#include <zephyr/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.
zfp | Pointer to the file object |
length | New size of the file in bytes |
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_unlink | ( | const char * | path | ) |
#include <zephyr/fs/fs.h>
Unlink file.
Deletes the specified file or directory
path | Path to the file or directory to delete |
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_unmount | ( | struct fs_mount_t * | mp | ) |
#include <zephyr/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.
mp | Pointer to the fs_mount_t structure |
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_unregister | ( | int | type, |
const struct fs_file_system_t * | fs | ||
) |
#include <zephyr/fs/fs.h>
Unregister a file system.
Unregister file system from virtual file system.
type | Type of file system (ex: FS_FATFS ) |
fs | Pointer to File system |
0 | on success; |
-EINVAL | when file system of a given type has not been registered. |
#include <zephyr/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.
zfp | Pointer to the file object |
ptr | Pointer to the data buffer |
size | Number of bytes to be written |
>=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. |