1. 文件系統(File Systems)
Zephyr RTOS 的虛擬文件系統開關允許應用程序在不同的掛載點(如:/fatfs 和 /nffs)掛載多個文件系統。掛載點數據結構包含實例化、掛載和操作文件系統所需的所有必要的信息。文件系統開關通過引入文件系統註冊機制,將應用程序從直接訪問一個文件系統指定的 API 或內部函數分離開。
在 Zephyr 中,任何文件系統的實現或庫可以通過一個文件系統註冊 API 插入或拔出。
int fs_register(enum fs_type type, struct fs_file_system_t *fs);
int fs_unregister(enum fs_type type, struct fs_file_system_t *fs);
Zephyr RTOS 通過使用掛載點作爲磁盤卷名來支持一個文件系統的多個實例,文件系統庫在格式化或掛載到一個磁盤時使用這個卷名。
文件系統的聲明如下:
static struct fs_mount_t mp = {
.type = FS_FATFS, // FS_FATFS:文件系統的類型,例如:FATFS 或 NFFS。
.mnt_point = FATFS_MNTP, // FATFS_MNTP:文件系統的掛載點。
.fs_data = &fat_fs, // fat_fs:將被 fs_mount( ) API 使用的文件系統數據。
};
2. 已知限制(Known Limitations)
由於庫內部實現的限制,NFFS 只支持文件系統的一個實例。
3. 示例(Sample)
在 samples/subsys/fs 中提供瞭如何使用文件系統的示例。
4. API 參考(API Reference)
4.1. 定義(Defines)
- FS_SEEK_SET
- FS_SEEK_CUR
- FS_SEEK_END
4.2. 枚舉(Enums)
-
enum fs_dir_entry_type
值:
FS_DIR_ENTRY_FILE = 0
FS_DIR_ENTRY_DIR -
enum fs_type
值:
FS_FATFS = 0
FS_NFFS
FS_TYPE_END
4.3. 函數(Functions)
-
int fs_open(struct fs_file_t * zfp, const char * file_name)
打開文件。
打開一個已存在文件或創建一個新的文件,並將一個流與其關聯。
參數:- zfp:指向文件對象的指針。
- file_name:要打開的文件名。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_close(struct fs_file_t * zfp)
關閉文件。
刷新關聯的流,並關閉文件。
參數:- zfp:指向文件對象的指針。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
fs_unlink(const char * path)
刪除文件鏈接(File unlink)。
刪除指定的文件或目錄。
參數:- path:要刪除的文件或目錄的路徑。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_rename(const char * from, const char * to)
文件或目錄重命名。
執行指定源路徑的重命名和或移動到指定的目的地。源路徑可以引用文件或目錄。目標路徑中的所有中間目錄必須已經存在。如果源路徑引用文件,則目標路徑必須包含完整的文件名路徑,而不僅僅是新的父目錄。如果一個對象已經在指定的目標路徑上存在,這個函數會在重命名之前將其刪除鏈接(即:目標被損毀(the destination gets clobbered))。
參數:- from:源路徑。
- to:目的路徑。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
ssize_t fs_read(struct fs_file_t * zfp, void * ptr, size_t size)
讀文件。
返回:讀取的字節數。如果成功,讀取的字節數將等於要求讀取的字節數。如果文件中沒有足夠的有效字節數,將返回少於要求讀取的字節數。發生錯誤時將返回 -ERRNO。
參數:- zfp:指向文件對象的指針。
- ptr:指向數據緩存區的指針。
- size:要求讀取的字節數。
-
ssize_t fs_write(struct fs_file_t * zfp, const void * ptr, size_t size)
寫文件。
返回:寫入的字節數。如果成功,寫入的字節數將等於要求寫入的字節數。其它任何值都表示出錯。錯誤時將返回 -ERRNO。在返回 -ERRNO 的情況下,由於無法啓動操作,文件指針將不會被提前(will not be advanced)。如果它能夠寫入,但不能寫入所有要求的字節數,這是因爲磁盤已經滿了。這種情況下,它將返回少於要求寫入的字節數,但不像常規錯誤那樣返回 -ERRNO。
參數:- zfp:指向文件對象的指針。
- ptr:指向數據緩存區的指針。
- size:要求寫入的字節數。
-
int fs_seek(struct fs_file_t * zfp, off_t offset, int whence)
偏移文件。
將文件位置移動到文件中的新位置。偏移量是基於 whence 增加到新位置的。
參數:- zfp:指向文件對象的指針。
- offset:要將文件指針移動的相對偏移。
- whence:計算偏移量的相對位置。
- FS_SEEK_SET:從文件起始處開始偏移。
- FS_SEEK_CUR:從當前位置開始偏移。
- FS_SEEK_END:從文件結尾開始偏移。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
off_t fs_tell(struct fs_file_t * zfp)
獲取文件的當前位置。
參數:- zfp:指向文件對象的指針。
返回值:
- position:文件當前的位置,當前修訂不驗證文件對象(Current position in file Current revision does not validate the file object)。
-
int fs_truncate(struct fs_file_t * zfp, off_t length)
更改打開文件的大小。
如果文件的新長度小於當前文件的大小,則將其截斷爲新的長度。如果文件的新長度大於當前文件的大小,則將其擴張爲新的長度。擴張後的區域填充 0。
Note:在擴張的情況下,如果在擴張時卷已經被填滿了,則函數擴張到最大可能的長度並返回成功。調用者應檢查擴張的長度與要求的長度是否一致。
參數:- zfp:指向文件對象的指針。
- length:文件的新長度。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_sync(struct fs_file_t * zfp)
刷新打開文件的寫緩存。
該函數可以用於刷新打開文件的緩存。可以調用該函數來確保數據立刻寫入到存儲介質。這樣做可能是爲了避免在意外斷電時丟失數據。**注意,關閉文件時會進行刷新緩存,因此如果文件正在關閉,則不需要調用該函數。參數:
- zfp:指向文件對象的指針。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_mkdir(const char * path)
創建目錄。
使用指定路徑創建一個新目錄。
參數:- path:要創建新目錄的路徑。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_opendir(struct fs_dir_t * zdp, const char * path)
打開目錄。
使用指定路徑打開一個已存在的目錄。
參數:- zdp:指向目錄對象的指針。
- path:要打開新目錄的路徑。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_readdir(struct fs_dir_t * zdp, struct fs_dirent * entry)
讀取目錄。
讀取打開目錄的目錄項。
返回:在目錄末尾(In end-of-dir)的情況下,將返回 0 並設置 entry->name[0] = 0
參數:- zdp:指向目錄對象的指針。
- entry:指向要讀取目錄項的存放的結構體 zfs_dirent 的指針。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_closedir(struct fs_dir_t * zdp)
關閉目錄。
關閉一個打開的目錄。
參數:- zdp:指向目錄對象的指針。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_mount(struct fs_mount_t * mp)
掛載文件系統。
執行掛載文件系統所需的步驟,如調用文件系統指定掛載函數並將掛載點掛載到文件系統列表中。
參數:- mp:指向結構體 fs_mount_t的指針。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_unmount(struct fs_mount_t * mp)
卸載文件系統。
執行卸載文件系統所需的步驟,如調用文件系統指定卸載函數並將掛載點從文件系統列表中移除。
參數:- mp:指向結構體 fs_mount_t的指針。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_stat(const char * path, struct fs_dirent * entry)
文件或目錄的狀態。
檢查指定路徑的文件或目錄的狀態。
參數:- path:文件或目錄的路徑。
- entry:指向結構體 zfs_dirent 的指針,如果文件或目錄存在時則填充該結構體。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_statvfs(const char * path, struct fs_statvfs * stat)
檢索文件系統卷的統計信息。
返回文件系統卷中總的可用空間。
參數:- path:掛載目錄的路徑。
- stat:指向結構體 zfs_statvfs 的指針,用於接收文件系統的統計信息。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_register(enum fs_type type, struct fs_file_system_t * fs)
註冊一個文件系統。
用虛擬文件系統註冊文件系統。
參數:- type:文件系統的類型(如:FS_FATFS)
- fs:指向文件系統的指針。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
-
int fs_unregister(enum fs_type type, struct fs_file_system_t * fs)
註銷文件系統。
用虛擬文件系統註銷文件系統。
參數:- type:文件系統的類型(如:FS_FATFS)
- fs:指向文件系統的指針。
返回值:
- 0:成功。
- -ERRNO:錯誤代碼。
4.4. 結構體(struct)
-
struct fs_mount_t
文件系統掛載信息結構體。#include <fs.h>
成員:- node:fs_mount_list 列表的入口。
- type:文件系統的類型。
- mnt_point:掛載點目錄名稱(如:“/fatfs”)
- fs_data:指向文件系統特定數據的指針。
- storage_dev:指向後端存儲設備的指針。
- mountp_len:掛載點字符串的長度。
- fs:指向掛載點文件系統接口的指針。
-
struct fs_dirent
結構體用於接收文件或目錄信息。#include <fs.h>
用於讀取目錄項以獲取文件或目錄信息的函數中。
成員:- dir_entry_type:文件或目錄。
- FS_DIR_ENTRY_FILE
- FS_DIR_ENTRY_DIR
- name:文件或目錄的名稱。
- size:文件的大小。如果是目錄則爲 0。
- dir_entry_type:文件或目錄。
-
struct fs_statvfs
結構體用於接收卷的統計信息。
用於檢索卷中總的可用空間信息。
成員:- f_bsize:最優傳遞塊大小。
- f_frsize:分配單位大小。
- f_blocks:FS 以 f_frsize 爲單位的大小。
- f_bfree:空閒塊的個數。
-
struct fs_file_system_t
文件系統接口結構體。 #include <fs.h>
成員:- open:打開一個已存在的文件或創建一個新的文件。
- read:讀取數據項的數字節。
- write:寫入數字節到數據項。
- lseek:將文件位置移動到文件中的新位置。
- tell:檢索在文件中的當前位置。
- truncate:截短文件到新長度。
- sync:刷新打開文件的緩存。
- close:刷新相關流並關閉文件。
- opendir:通過指定路徑打開已存在的目錄。
- readdir:讀取打開目錄的目錄項。
- closedir:關閉一個打開的目錄。
- mount:掛載一個文件系統。
- unmount:卸載一個文件系統。
- unlik:刪除指定的文件或目錄。
- rename:文件或目錄重命名。
- mkdir:使用指定路徑創建一個新的目錄。
- stat:通過指定路徑檢查文件或目錄的狀態。
- statvfs:返回文件系統卷中總的可用空間。