File System Core API#
FSCore_ConfigureMemSeg()#
Description#
Set the memory segment where file system internal data structures will be allocated.
Files#
fs_core.h/fs_core.c
Prototype#
void FSCore_ConfigureMemSeg (MEM_SEG *p_seg)Arguments#
p_seg
Pointer to a memory segment.
Returned Value#
none.
Notes / Warnings#
None.
FSCore_ConfigureMaxFatObjCnt()#
Description#
Set the maximum number of file system FAT objects.
Files#
fs_core.h/fs_core.c
Prototype#
void FSCore_ConfigureMaxFatObjCnt (FS_CORE_CFG_MAX_FAT_OBJ_CNT max_cnt)Arguments#
max_cnt
Structure containing the maximum number of each FAT object.
Returned Value#
none.
Notes / Warnings#
None.
FSCore_ConfigureMaxObjCnt()#
Description#
Set the maximum number of file system core objects.
Files#
fs_core.h/fs_core.c
Prototype#
void FSCore_ConfigureMaxObjCnt (FS_CORE_CFG_MAX_OBJ_CNT max_cnt)Arguments#
max_cnt
Structure containing the maximum number of each core object.
Returned Value#
none.
Notes / Warnings#
None.
FSCore_Init()#
Description#
Initialize file system.
Files#
fs_core.h/fs_core.c
Prototype#
void FSCore_Init (RTOS_ERR *p_err)Arguments#
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ALREADY_INITRTOS_ERR_NOT_AVAILRTOS_ERR_SEG_OVF
Returned Value#
none.
Notes / Warnings#
None.
FSCache_Create()#
Description#
Create a cache instance.
Files#
fs_core_cache.h/fs_core_cache.c
Prototype#
FS_CACHE *FSCache_Create (const FS_CACHE_CFG *p_cache_cfg,
RTOS_ERR *p_err)Arguments#
p_cache_cfg
Pointer to a cache configuration structure.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_SEG_OVF
Returned Value#
Pointer to a cache instance.
Notes / Warnings#
(1) The cache configuration structure has the following fields:
typedef struct fs_cache_cfg {
CPU_SIZE_T Align; /* Buffer alignment requirement. */
CPU_SIZE_T MinBlkCnt; /* Number of buffers available to cache module. */
CPU_SIZE_T MinLbSize; /* Minimum logical block size to consider. */
CPU_SIZE_T MaxLbSize; /* Maximum logical block size to consider. */
MEM_SEG *BlkMemSegPtr; /* Memory segment where buffers will be allocated from. */
} FS_CACHE_CFG;FSCache_Assign()#
Description#
Bind a block device to a cache instance.
Files#
fs_core_cache.h/fs_core_cache.c
Prototype#
void FSCache_Assign (FS_BLK_DEV_HANDLE blk_dev_handle,
FS_CACHE *p_cache,
RTOS_ERR *p_err)Arguments#
blk_dev_handle
Handle to a block device.
p_cache
Pointer to a cache instance.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_INVALID_STATERTOS_ERR_SIZE_INVALIDRTOS_ERR_BLK_DEV_CLOSED
Returned Value#
none.
Notes / Warnings#
None.
FSCache_DfltAssign()#
Description#
Create a cache instance with default parameters and bind it to a block device.
Files#
fs_core_cache.h/fs_core_cache.c
Prototype#
FS_CACHE *FSCache_DfltAssign (FS_BLK_DEV_HANDLE blk_dev_handle,
CPU_SIZE_T cache_blk_cnt,
RTOS_ERR *p_err)Arguments#
blk_dev_handle
Handle to a block device.
blk_dev_handle
Number of cache blocks to allocate.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_INIT RTOS_ERR_SEG_OVFRTOS_ERR_BLK_DEV_CLOSED
Returned Value#
Pointer to the created default cache.
Notes / Warnings#
(1) This function is a sort of wrapper that uses FSCache_Create() and FSCache_Assign() .
(2) The default cache parameters are:
FS_CACHE_CFG.BlkMemSegPtr = default core memory segment (that is heap region)
FS_CACHE_CFG.Align = default alignment required by block device
FS_CACHE_CFG.MaxLbSize = default block device sector size
FS_CACHE_CFG.MinLbSize = default block device sector sizeFSCache_Get()#
Description#
Get a cache instance from a block device.
Files#
fs_core_cache.h/fs_core_cache.c
Prototype#
FS_CACHE *FSCache_Get (FS_BLK_DEV_HANDLE blk_dev_handle)Arguments#
blk_dev_handle
Handle to a block device.
Returned Value#
Pointer to the associated cache instance or DEF_NULL if cache has not been assigned.
Notes / Warnings#
None.
FSCache_MaxBlkSizeGet()#
Description#
Get the maximum block size supported by the given cache instance.
Files#
fs_core_cache.h/fs_core_cache.c
Prototype#
FS_LB_SIZE FSCache_MaxBlkSizeGet (FS_CACHE *p_cache)Arguments#
p_cache
Pointer to a cache instance.
Returned Value#
Maximum supported block size.
Notes / Warnings#
None.
FSCache_MinBlkSizeGet()#
Description#
Get the minimum block size supported by the given cache instance.
Files#
fs_core_cache.h/fs_core_cache.c
Prototype#
FS_LB_SIZE FSCache_MinBlkSizeGet (FS_CACHE *p_cache)Arguments#
p_cache
Pointer to a cache instance.
Returned Value#
Minimum supported block size.
Notes / Warnings#
None.
FS_FAT_Fmt()#
Description#
Format a partition in FAT.
Files#
fs_fat.h/fs_fat.c
Prototype#
void FS_FAT_Fmt (FS_BLK_DEV_HANDLE blk_dev_handle,
FS_PARTITION_NBR partition_nbr,
FS_FAT_VOL_CFG *p_fat_vol_cfg,
RTOS_ERR *p_err)Arguments#
blk_dev_handle
Handle to a block device.
partition_nbr
Number of the partition to be formatted. The first partition is partition number #1. FS_PARTITION_NBR_VOID to erase the MBR and use the whole media.
p_fat_vol_cfg
Pointer to a FAT volume configuration structure (optional).
DEF_NULLfor default values (see Note #1).
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_VOL_OPENEDRTOS_ERR_PARTITION_INVALIDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
(1) In general, the best option for the FAT volume configuration structure is DEF_NULL. In that case, the File System FAT layer will automatically determine the proper FAT configuration values based in the block device total size. If you want to specify the values, the FAT configuration structure is composed of:
The cluster size expressed in number of sectors.
The reserved area size expressed in number of sectors.
The number of entries in the root directory table.
The type of FAT: FAT 12, 16 or 32.
The number of FAT tables.
You may use these typical values for the FAT configuration structure:
typedef struct fs_fat_vol_cfg {
CPU_SIZE_T ClusSizeInSec;
CPU_SIZE_T RsvdAreaSizeInSec;
CPU_INT16U RootDirEntryCnt;
CPU_INT08U FAT_Type;
CPU_INT08U NbrFATs;
} FS_FAT_VOL_CFG;Configuration | Field | Typical Values |
|---|---|---|
Cluster size | .ClusSizeInSec | 1, 2, 4, 8, 16, 32, 64 |
Reserved area size | .RsvdAreaSizeInSec | FS_FAT_DFLT_RSVD_SEC_CNT_FAT12FS_FAT_DFLT_RSVD_SEC_CNT_FAT16FS_FAT_DFLT_RSVD_SEC_CNT_FAT32 |
Number of entries in the root directory table | .RootDirEntryCnt | FS_FAT_DFLT_ROOT_ENT_CNT_FAT12FS_FAT_DFLT_ROOT_ENT_CNT_FAT16FS_FAT_DFLT_ROOT_ENT_CNT_FAT32 |
Type of FAT | .FAT_Type | FS_FAT_TYPE_FAT12FS_FAT_TYPE_FAT16FS_FAT_TYPE_FAT32 |
Number of FAT tables | .NbrFATs | FS_FAT_DFLT_NBR_FATS_FAT12FS_FAT_DFLT_NBR_FATS_FAT16FS_FAT_DFLT_NBR_FATS_FAT32 |
FSDir_Open()#
Description#
Open a directory.
Files#
fs_core_dir.h/fs_core_dir.c
Prototype#
FS_DIR_HANDLE FSDir_Open ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *path,
FS_FLAGS mode,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory (see Note #1).
path
Path of the directory relative to the give working directory.
mode
Directory access mode; valid bit-wise OR of one or more of the following
FS_DIR_ACCESS_MODE_EXCLDirectory will be opened if and only if it does not already exist.FS_DIR_ACCESS_MODE_CREATEDirectory will be created, if necessary.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_NOT_FOUNDRTOS_ERR_ALREADY_EXISTSRTOS_ERR_TYPE_INVALIDRTOS_ERR_NAME_INVALIDRTOS_ERR_PARENT_NOT_DIRRTOS_ERR_MAX_DEPTH_EXCEEDEDRTOS_ERR_DIR_FULLRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_VOL_FULLRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
Handle to the opened directory.
Notes / Warnings#
If no working directory has been opened with
FSWrkDir_Open(), you can pass a NULL working directory handle using the #defineFS_WRK_DIR_NULL.
FSDir_Close()#
Description#
Close a directory.
Files#
fs_core_dir.h/fs_core_dir.c
Prototype#
void FSDir_Close (FS_DIR_HANDLE dir_handle,
RTOS_ERR *p_err)Arguments#
dir_handle
Handle to a directory.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSED
Returned Value#
none.
Notes / Warnings#
None.
FSDir_Rd()#
Description#
Read a directory entry from a directory table.
Files#
fs_core_dir.h/fs_core_dir.c
Prototype#
CPU_BOOLEAN FSDir_Rd (FS_DIR_HANDLE dir_handle,
FS_ENTRY_INFO *p_entry_info,
CPU_CHAR *p_buf,
CPU_SIZE_T buf_size,
RTOS_ERR *p_err)Arguments#
dir_handle
Handle to a directory.
p_entry_info
Pointer to a structure that will receive the entry information.
p_buf
Pointer to a buffer that will receive the entry name.
buf_size
Size of the given buffer.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_WOULD_OVFRTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
DEF_NO, if there are other available entries.
DEF_YES, if there are no more entry.
Notes / Warnings#
Entries for "dot" (current directory) and "dot-dot" (parent directory) will be returned, if present.
A subsequent call to
FSDir_Rd()will return the next directory entry in the table until there is no more entry to read.
FSDir_Query()#
Description#
Get information about a directory.
Files#
fs_core_dir.h/fs_core_dir.c
Prototype#
void FSDir_Query (FS_DIR_HANDLE dir_handle,
FS_ENTRY_INFO *p_entry_info,
RTOS_ERR *p_err)Arguments#
dir_handle
Handle to a directory.
p_entry_info
Pointer to structure that will receive the entry information.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
If data is stored in the file buffer waiting to be written to the storage medium, the actual file size may need to be adjusted to account for that buffered data.
The entry information structure has the following fields:
typedef struct fs_entry_attrib {
CPU_INT32U Wr:1; /* Bit indicating if entry has write access. */
CPU_INT32U Rd:1; /* Bit indicating if entry has read access. */
CPU_INT32U Hidden:1; /* Bit indicating if entry is hidden. */
CPU_INT32U IsDir:1; /* Bit indicating if entry is a directory or a file. */
CPU_INT32U IsRootDir:1; /* Bit indicating if entry is root directory. */
} FS_ENTRY_ATTRIB;
typedef struct fs_entry_info {
FS_ENTRY_ATTRIB Attrib; /* Entry attributes. */
FS_ID NodeId; /* Entry node id. */
FS_ID DevId; /* Entry device id. */
CPU_SIZE_T Size; /* File size in octets. */
CLK_TS_SEC DateAccess; /* Date of last access. */
FS_LB_QTY BlkCnt; /* Number of blocks allocated for file. */
FS_LB_SIZE BlkSize; /* Block size in octets. */
CLK_TS_SEC DateTimeWr; /* Date/time of last write. */
CLK_TS_SEC DateTimeCreate; /* Date/time of creation. */
} FS_ENTRY_INFO;FSDir_PathGet()#
Description#
Get absolute path to an opened file.
Files#
fs_core_dir.h/fs_core_dir.c
Prototype#
void FSDir_PathGet (FS_DIR_HANDLE dir_handle,
CPU_CHAR *p_buf,
CPU_SIZE_T buf_size,
RTOS_ERR *p_err)Arguments#
dir_handle
Handle to a directory.
p_buf
Pointer to a buffer that will receive the path.
buf_size
Size of the provided buffer.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_WOULD_OVFRTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
None.
FSDir_VolGet()#
Description#
Get volume containing the given directory.
Files#
fs_core_dir.h/fs_core_dir.c
Prototype#
FS_VOL_HANDLE FSDir_VolGet (FS_DIR_HANDLE dir_handle)Arguments#
dir_handle
Handle to a directory.
Returned Value#
Handle to the parent volume or NULL handle if the directory is closed.
Notes / Warnings#
None.
FSEntry_Create()#
Description#
Create a file or directory.
Files#
fs_core_entry.h/fs_core_entry.c
Prototype#
void FSEntry_Create ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *path,
FS_FLAGS entry_type,
CPU_BOOLEAN excl,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory.
p_path
Entry path relative to the given working directory.
entry_type
Indicates whether the new entry is a directory / a file:
FS_ENTRY_TYPE_DIR, if the entry can be a directory.FS_ENTRY_TYPE_FILE, if the entry can be a file.
excl
Indicates whether the creation of new entry will be exclusive :
DEF_YES, if the entry will be created ONLY if the entry does not exist.DEF_NO, if the entry will be created even if the entry does exist.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ALREADY_EXISTSRTOS_ERR_NOT_FOUNDRTOS_ERR_NAME_INVALIDRTOS_ERR_ENTRY_OPENEDRTOS_ERR_ENTRY_ROOT_DIRRTOS_ERR_ENTRY_PARENT_NOT_DIRRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
The function behavior is resumed in the table below.
Entry Type Argument | 'excl' Argument | Entry Already Exists? | Entry Type on Disk | Behavior |
|---|---|---|---|---|
X | X | no | - | Create entry |
FS_ENTRY_TYPE_FILE | DEF_NO | yes | file | Truncate file |
FS_ENTRY_TYPE_FILE | DEF_YES | yes | file | Error: already exists |
FS_ENTRY_TYPE_FILE | X | yes | directory | Error: type mismatch |
FS_ENTRY_TYPE_DIR | X | yes | file | Error: type mismatch |
FS_ENTRY_TYPE_DIR | DEF_NO | yes | directory | Nothing is done |
FS_ENTRY_TYPE_DIR | DEF_YES | yes | directory | Error: already exists |
"X" means "don't care". "-" means "not relevant".
The root directory may NOT be created.
FSEntry_Del()#
Description#
Delete a file or directory.
Files#
fs_core_entry.h/fs_core_entry.c
Prototype#
void FSEntry_Del ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *path,
FS_FLAGS entry_type,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory.
p_path
Entry path relative to the given working directory.
entry_type
Indicates whether the entry to delete is a directory or a file :
FS_ENTRY_TYPE_DIR, if the entry is a directory.FS_ENTRY_TYPE_FILE, if the entry is a file.FS_ENTRY_TYPE_ANY, if the entry is any type.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_ENTRY_OPENEDRTOS_ERR_ENTRY_ROOT_DIRRTOS_ERR_INVALID_TYPERTOS_ERR_NAME_INVALIDRTOS_ERR_DIR_NOT_EMPTYRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
(1) When a file is removed, the space occupied by the file is freed and is no longer accessible.
(2) The root directory cannot be deleted.
(3) A directory can be removed only if it is an empty directory.
FSEntry_Rename()#
Description#
Rename a file or directory.
Files#
fs_core_entry.h/fs_core_entry.c
Prototype#
void FSEntry_Rename ( FS_WRK_DIR_HANDLE src_wrk_dir_handle,
const CPU_CHAR *p_src_path,
FS_WRK_DIR_HANDLE dest_wrk_dir_handle,
const CPU_CHAR *p_dest_path,
CPU_BOOLEAN excl,
RTOS_ERR *p_err)Arguments#
src_wrk_dir_handle
Handle to the source working directory.
p_src_path
Source entry path relative to the given source working directory.
dest_wrk_dir_handle
Handle to the destination working directory.
p_dest_path
Destination entry path relative to the given source working directory.
excl
Indicates whether creation of new entry should be exclusive (see Note #3):
DEF_YES, if the entry will be renamed ONLY if the destination entry does not exist.DEF_NO, if the entry will be renamed even if the destination entry does exist.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_ENTRY_ROOT_DIRRTOS_ERR_ENTRY_PARENT_NOT_DIRRTOS_ERR_ENTRY_OPENEDRTOS_ERR_ALREADY_EXISTSRTOS_ERR_NAME_INVALIDRTOS_ERR_INVALID_TYPERTOS_ERR_DIR_NOT_EMPTYRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
If source and destination entries reside on different volumes, then the source entry must be a file. If the source entry is a directory, an error will be returned.
(a) If the source and destination entries are the same entry, the volume will not be modified and no error will be returned.
(b) If the source entry is a file:
... the destination entry must NOT be a directory.
... if 'excl' is
DEF_NOand the destination entry is a file, the destination entry will be deleted.
(c) If the source entry is a directory:
... the destination entry must NOT be a file.
... if 'excl' is
DEF_NOand the destination entry is a directory, the target entry MUST be empty; if so, it will be deleted.
If 'excl' is
DEF_NO, the destination entry must not exist.The root directory may NOT be renamed.
FSEntry_AttribSet()#
Description#
Set a file or directory's attributes.
Files#
fs_core_entry.h/fs_core_entry.c
Prototype#
void FSEntry_AttribSet ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *path,
FS_FLAGS attrib,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory.
p_path
Entry path relative to the given working directory.
attrib
Entry attributes to set (see Note #2).
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_ENTRY_OPENEDRTOS_ERR_ENTRY_ROOT_DIRRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
If the entry does not exist, an error is returned.
Three entry attributes may be modified by this function :
FS_ENTRY_ATTRIB_RDEntry is readable.FS_ENTRY_ATTRIB_WREntry is writable.FS_ENTRY_ATTRIB_HIDDENEntry is hidden from user-level processes.(a) An attribute will be cleared if its flag is not OR'd into 'attrib'. The attribute will be set otherwise.
(b) If another flag besides these is set, then an error will be returned.
The attributes of the root directory may NOT be set.
FSEntry_TimeSet()#
This function is deprecated and will be replaced by sl_fs_entry_time_set() in a next release. |
|---|
Description#
Set a file or directory's date/time.
Files#
fs_core_entry.h/fs_core_entry.c
Prototype#
void FSEntry_TimeSet ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *path,
CLK_DATE_TIME *p_time,
CPU_INT08U time_type,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory.
p_path
Entry path relative to the given working directory.
p_time
Pointer to date/time.
time_type
Flag to indicate which Date/Time should be set
FS_DATE_TIME_CREATEFS_DATE_TIME_MODIFYFS_DATE_TIME_ACCESSFS_DATE_TIME_ALL
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_ENTRY_OPENEDRTOS_ERR_ENTRY_ROOT_DIRRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
The date/time of the root directory may NOT be set.
The pointer
p_timepoints to a structure of typeCLK_DATE_TIME.
FSEntry_Query()#
Description#
Get information about a file or directory.
Files#
fs_core_entry.h/fs_core_entry.c
Prototype#
void FSEntry_Query ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *path,
FS_ENTRY_INFO *p_entry_info,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory.
p_path
Entry path relative to the given working directory.
p_entry_info
Pointer to structure that will receive the entry information.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
The entry information structure has the following fields:
typedef struct fs_entry_attrib {
CPU_INT32U Wr:1; /* Bit indicating if entry has write access. */
CPU_INT32U Rd:1; /* Bit indicating if entry has read access. */
CPU_INT32U Hidden:1; /* Bit indicating if entry is hidden. */
CPU_INT32U IsDir:1; /* Bit indicating if entry is a directory or a file. */
CPU_INT32U IsRootDir:1; /* Bit indicating if entry is root directory. */
} FS_ENTRY_ATTRIB;
typedef struct fs_entry_info {
FS_ENTRY_ATTRIB Attrib; /* Entry attributes. */
FS_ID NodeId; /* Entry node id. */
FS_ID DevId; /* Entry device id. */
CPU_SIZE_T Size; /* File size in octets. */
CLK_TS_SEC DateAccess; /* Date of last access. */
FS_LB_QTY BlkCnt; /* Number of blocks allocated for file. */
FS_LB_SIZE BlkSize; /* Block size in octets. */
CLK_TS_SEC DateTimeWr; /* Date/time of last write. */
CLK_TS_SEC DateTimeCreate; /* Date/time of creation. */
} FS_ENTRY_INFO;FSFile_Open()#
Description#
Open a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
FS_FILE_HANDLE FSFile_Open ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *path,
FS_FLAGS mode,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory (see Note #1).
path
File path relative to the given working directory.
mode
File access mode; valid bit-wise OR of one or more of the following (see Note #2):
FS_FILE_ACCESS_MODE_RDFile opened for reads.FS_FILE_ACCESS_MODE_WRFile opened for writes.FS_FILE_ACCESS_MODE_CREATEFile will be created, if necessary.FS_FILE_ACCESS_MODE_TRUNCATEFile length will be truncated to 0.FS_FILE_ACCESS_MODE_APPENDAll writes will be performed at EOF.FS_FILE_ACCESS_MODE_EXCLFile will be opened if & only if it does not already exist.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_NOT_FOUNDRTOS_ERR_ALREADY_EXISTSRTOS_ERR_TYPE_INVALIDRTOS_ERR_NAME_INVALIDRTOS_ERR_PARENT_NOT_DIRRTOS_ERR_MAX_DEPTH_EXCEEDEDRTOS_ERR_DIR_FULLRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_FULLRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
Handle to the opened file descriptor.
Notes / Warnings#
If no working directory has been opened with FSWrkDir_Open(), you can pass a NULL working directory handle using the #define FS_WRK_DIR_NULL.
Micrium OS File System native file access modes along with equivalent standard '
fopen()' access modes. Combinations not listed below will generate an error. TheFS_FILE_ACCESS_MODE_EXCLflag is allowed whereverFS_FILE_ACCESS_MODE_CREATEis allowed.Native Access Mode
Posix Access Mode
RD
"r" / "rb"
WR
WR | APPEND
WR | TRUNCATE
WR | TRUNCATE | APPEND
WR | CREATE
WR | CREATE | APPEND
"a" / "ab"
WR | CREATE | TRUNCATE
"w" / "wb"
WR | CREATE | TRUNCATE | APPEND
RD | WR
"r+" / "rb+" / "r+b"
RD | WR | APPEND
RD | WR | TRUNCATE
RD | WR | TRUNCATE | APPEND
RD | WR | CREATE | TRUNCATE
"w+" / "wb+" / "w+b"
RD | WR | CREATE | APPEND
"a+" / "ab+" / "a+b"
RD | WR TRUNCATE | APPEND
RD | WR | CREATE | TRUNCATE | APPEND
The depth of the directory tree may NOT exceed 255, counting from the virtual file system root directory. The '
RTOS_ERR_WOULD_OVF' error is returned whenever this limit is exceeded. This can only happen when the 'FS_FILE_ACCESS_MODE_CREATE' access mode is used.If the entry located at the specified path is a directory, the '
RTOS_ERR_INVALID_TYPE' is returned.
FSFile_Close()#
Description#
Close a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_Close (FS_FILE_HANDLE file_handle,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
None.
FSFile_Rd()#
Description#
Read from a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
CPU_SIZE_T FSFile_Rd (FS_FILE_HANDLE file_handle,
void *p_dest,
CPU_SIZE_T size,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_dest
Pointer to destination buffer.
size
Number of octets to read.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSEDRTOS_ERR_FILE_ERR_STATERTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
Number of bytes read (may be smaller than 'size' if the end of file is encountered).
Notes / Warnings#
(1) All accesses to the file descriptor are atomically performed before the actual I/O's occur. Since FSFile_Rd() may execute concurrently, this means that there is no (guaranteed) relation between the order in which FSFile_Rd() calls return and the order of the returned data chunks inside the file.
(2) If an error occurred in the previous file access, the error indicator must be cleared (with FSFile_ErrClr()) before another access will be allowed. Otherwise, the 'RTOS_ERR_FILE_ERR_STATE' error is set and the function returns.
FSFile_Wr()#
Description#
Write to a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
CPU_SIZE_T FSFile_Wr ( FS_FILE_HANDLE file_handle,
const void *p_src,
CPU_SIZE_T size,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_src
Pointer to source buffer.
size
Number of octets to write.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSEDRTOS_ERR_FILE_ERR_STATERTOS_ERR_FILE_ACCESS_MODE_INVALIDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_FULLRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
Number of octets written.
Notes / Warnings#
(1) The file MUST have been opened in write or update (read/write) mode.
(2) If the file was opened in append mode, all writes are forced to the EOF.
(3) If an error occurred in the previous file access, the error indicator must be cleared (with FSFile_ErrClr()) before another access will be allowed. Otherwise, the 'RTOS_ERR_FILE_ERR_STATE' error will be set and the function will return.
FSFile_Copy()#
Description#
Copy a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_Copy ( FS_WRK_DIR_HANDLE src_wrk_dir_handle,
const CPU_CHAR *src_path,
FS_WRK_DIR_HANDLE dest_wrk_dir_handle,
const CPU_CHAR *dest_path,
CPU_BOOLEAN excl,
RTOS_ERR *p_err)Arguments#
src_wrk_dir_handle
Handle to source working directory.
src_path
Source file path.
dest_wrk_dir_handle
Handle to destination working directory.
dest_path
Destination file path.
excl
Indicates whether creation of new entry should be exclusive :
DEF_YES, if the entry will be copied ONLY if destination entry does not exist.DEF_NO, if the entry will be copied even if destination entry does exist.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_OPENEDRTOS_ERR_ALREADY_EXISTSRTOS_ERR_NOT_FOUNDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_FULLRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
The source file MUST exist, otherwise an error is returned.
If 'excl' is
DEF_NO, the destination entry must either not exist or be an existing file; it may not be an existing directory. If 'excl' isDEF_YES, the destination entry must not exist.
FSFile_Truncate()#
Description#
Truncate or extend a file to a specified length.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_Truncate (FS_FILE_HANDLE file_handle,
FS_FILE_SIZE size,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
size
Size of file after truncation or extension.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSEDRTOS_ERR_FILE_ERR_STATERTOS_ERR_FILE_ACCESS_MODE_INVALIDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_FULLRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
(1) The file MUST be opened in write or read/write mode.
FSFile_PosSet()#
Description#
Set file position indicator.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_PosSet (FS_FILE_HANDLE file_handle,
FS_FILE_OFFSET offset,
FS_FLAGS origin,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
offset
Offset from the file position specified by 'origin'.
origin
Reference position for offset :
FS_FILE_ORIGIN_START Offset is from the beginning of the file.
FS_FILE_ORIGIN_CUR Offset is from current file position.
FS_FILE_ORIGIN_END Offset is from the end of the file.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSED
If a file buffer in write mode is in use, the following error codes may be triggered as well:
RTOS_ERR_VOL_FULLRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
(a) The new file position, measured in bytes from the beginning of the file is obtained by adding '
offset' to......0 (the beginning of the file) if '
origin' isFS_FILE_ORIGIN_START,...the current file position if '
origin' isFS_FILE_ORIGIN_CUR....the file size if '
origin' isFS_FILE_ORIGIN_END.
(b) The end-of-file indicator is cleared.
If the file position indicator is set beyond the file's current data...
(a) ...and data is later written to that point, reads from the gap will read 0.
(b) ...the file MUST be opened in write or read/write mode.
Locking is needed to protect the file buffer from being emptied and/or the current position from being changed while a write operation is being performed.
FSFile_PosGet()#
Description#
Get file position indicator.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
FS_FILE_SIZE FSFile_PosGet (FS_FILE_HANDLE file_handle,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSED
Returned Value#
The current file position measured in bytes from the beginning of the file.
Notes / Warnings#
None.
FSFile_Query()#
Description#
Get information about a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_Query (FS_FILE_HANDLE file_handle,
FS_ENTRY_INFO *p_entry_info,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_entry_info
Pointer to structure that will receive the file information.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
(1) The file information structure has the following fields:
typedef struct fs_entry_attrib {
CPU_INT32U Wr:1; /* Bit indicating if entry has write access. */
CPU_INT32U Rd:1; /* Bit indicating if entry has read access. */
CPU_INT32U Hidden:1; /* Bit indicating if entry is hidden. */
CPU_INT32U IsDir:1; /* Bit indicating if entry is a directory or a file. */
CPU_INT32U IsRootDir:1; /* Bit indicating if entry is root directory. */
} FS_ENTRY_ATTRIB;
typedef struct fs_entry_info {
FS_ENTRY_ATTRIB Attrib; /* Entry attributes. */
FS_ID NodeId; /* Entry node id. */
FS_ID DevId; /* Entry device id. */
CPU_SIZE_T Size; /* File size in octets. */
CLK_TS_SEC DateAccess; /* Date of last access. */
FS_LB_QTY BlkCnt; /* Number of blocks allocated for file. */
FS_LB_SIZE BlkSize; /* Block size in octets. */
CLK_TS_SEC DateTimeWr; /* Date/time of last write. */
CLK_TS_SEC DateTimeCreate; /* Date/time of creation. */
} FS_ENTRY_INFO;FSFile_PathGet()#
Description#
Get absolute path to a opened file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_PathGet (FS_FILE_HANDLE file_handle,
CPU_CHAR *p_buf,
CPU_SIZE_T buf_size,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
buf
Pointer to a buffer that will receive the file path.
buf_size
Size of the provided buffer.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_WOULD_OVFRTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
None.
FSFile_VolGet()#
Description#
Get handle to the volume in which the file is.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
FS_VOL_HANDLE FSFile_VolGet (FS_FILE_HANDLE file_handle)Arguments#
file_handle
Handle to a file.
Returned Value#
Handle to the volume or NULL handle if the file is closed.
Notes / Warnings#
None.
FSFile_BufAssign()#
Description#
Assign buffer to a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_BufAssign (FS_FILE_HANDLE file_handle,
void *p_buf,
FS_FLAGS mode,
CPU_SIZE_T size,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_buf
Pointer to buffer.
mode
Buffer mode :
FS_FILE_BUF_MODE_RDdata buffered for reads.FS_FILE_BUF_MODE_WRdata buffered for writes.FS_FILE_BUF_MODE_RD_WRdata buffered for reads & writes.
size
Size of the given buffer, in octets.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_INVALID_STATERTOS_ERR_SIZE_INVALIDRTOS_ERR_FILE_ACCESS_MODE_INVALIDRTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSED
Returned Value#
none.
Notes / Warnings#
Once a buffer is assigned to a file, a new buffer may not be assigned nor may the assigned buffer be removed. To change the buffer, the file should be closed and re-opened.
'
size' MUST be more than or equal to the size of one sector; it will be rounded DOWN to the nearest size of a multiple of full sectors.Upon power loss, any data stored in file buffers will be lost.
FSFile_BufFlush()#
Description#
Flush buffer contents to file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_BufFlush (FS_FILE_HANDLE file_handle,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_FULLRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
The flush operation is as follows:
(a) If the most recent operation is output (write), all unwritten data is written to the file.
(b) If the most recent operation is input (read), all buffered data is cleared.
(c) If a read or write error occurs, the error indicator is set.
If an error occurred in the previous file access, the error indicator must be cleared (with
FSFile_ErrClr()) before another access will be allowed.
FSFile_ErrClr()#
Description#
Clear file descriptor error state.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_ErrClr (FS_FILE_HANDLE file_handle,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSED
Returned Value#
none.
Notes / Warnings#
None.
FSFile_IsEOF()#
Description#
Test EOF indicator on a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
CPU_BOOLEAN FSFile_IsEOF (FS_FILE_HANDLE file_handle,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSED
Returned Value#
DEF_YES, if EOF indicator is set.DEF_NO, otherwise.
Notes / Warnings#
FSFile_ErrClr()can be used to clear the EOF indicator.
FSFile_IsErr()#
Description#
Check whether a file descriptor is in error state.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
CPU_BOOLEAN FSFile_IsErr (FS_FILE_HANDLE file_handle,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSED
Returned Value#
DEF_YES, if the files descriptor is in error state.DEF_NO, otherwise.
Notes / Warnings#
None.
FSFile_Lock()#
Description#
Acquire task ownership of a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_Lock (FS_FILE_HANDLE file_handle,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSED
Returned Value#
none.
Notes / Warnings#
File locks may be nested.
The file descriptor must be acquired so that it is not freed while holding the lock.
FSFile_TryLock()#
Description#
Acquire task ownership of a file (if available).
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_TryLock (FS_FILE_HANDLE file_handle,
RTOS_ERR *p_err)Arguments#
file_handle
Handle to a file.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ENTRY_CLOSEDRTOS_ERR_WOULD_BLOCK
Returned Value#
none.
Notes / Warnings#
FSFile_TryLock()is the non-blocking version ofFSFile_Lock()If the lock is not available, the function returns an error.File locks may be nested.
FSFile_Unlock()#
Description#
Release task ownership of a file.
Files#
fs_core_file.h/fs_core_file.c
Prototype#
void FSFile_Unlock (FS_FILE_HANDLE file_handle)Arguments#
file_handle
Handle to a file.
Returned Value#
none.
Notes / Warnings#
None.
FSPartition_Init()#
Description#
Initialize the partition structure on a block device (see Note #1).
Files#
fs_core_partition.h/fs_core_partition.c
Prototype#
void FSPartition_Init (FS_BLK_DEV_HANDLE blk_dev_handle,
FS_LB_QTY lb_cnt,
RTOS_ERR *p_err)Arguments#
blk_dev_handle
Handle to a block device.
lb_cnt
Size (in logical blocks) of first partition. 0 if the partition will occupy the entire device (see Note #2).
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_SIZE_INVALIDRTOS_ERR_VOL_OPENEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
(1) This function creates the first partition with index 1. Any subsequent partition is created using the function FSPartition_Add().
(2) If 0 is passed as the number of logical blocks composing the first partition, no MBR (Master Boot Record) sector is created. If non-zero is passed, a MBR sector is created allowing the creation of four partitions.
(2) Function returns an error if a volume is open on the device. All volumes (& files) MUST be closed prior to initializing the partition structure, since it will obliterate any existing file system.
FSPartition_Add()#
Description#
Add a partition to a device.
Files#
fs_core_partition.h/fs_core_partition.c
Prototype#
FS_PARTITION_NBR FSPartition_Add (FS_BLK_DEV_HANDLE blk_dev_handle,
FS_LB_QTY lb_cnt,
RTOS_ERR *p_err)Arguments#
blk_dev_handle
Handle to a block device.
lb_cnt
Size (in logical blocks) of the partition to add.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_SIZE_INVALIDRTOS_ERR_PARTITION_MAX_EXCEEDEDRTOS_ERR_BLK_DEV_CLOSED
Returned Value#
The index of the created partition.
Notes / Warnings#
The first partition on the device has index 1.
If there is no valid partition on the device, the function will automatically initialize a MBR (Master Boot Record) sector and create the first partition.
FSPartition_CntGet()#
Description#
Get number of partitions on a block device.
Files#
fs_core_partition.h/fs_core_partition.c
Prototype#
FS_PARTITION_NBR FSPartition_CntGet (FS_BLK_DEV_HANDLE blk_dev_handle,
RTOS_ERR *p_err)Arguments#
blk_dev_handle
Handle to a block device.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
Number of partitions, if NO errors.
0, otherwise.
Notes / Warnings#
If no Master Boot Record is present on the media's sector #0, a valid formatted partition can still be present. In that case, FSPartition_CntGet() will return 1 partition as the number of partitions since no partition table exists to describe other partitions.
FSPartition_Query()#
Description#
Query partition information.
Files#
fs_core_partition.h/fs_core_partition.c
Prototype#
void FSPartition_Query (FS_BLK_DEV_HANDLE blk_dev_handle,
FS_PARTITION_NBR partition_nbr,
FS_PARTITION_INFO *p_partition_info,
RTOS_ERR *p_err)Arguments#
blk_dev_handle
Handle to a block device.
partition_nbr
Number of the partition to query (first partition is number 1).
p_partition_info
Pointer to variable that will receive the partition information.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
The partition information structure has the following fields:
typedef struct fs_partition_info {
FS_LB_NBR StartSec; /* Sector number where the partition starts. */
FS_LB_QTY SecCnt; /* Number of sectors composing the partition. */
CPU_INT08U Type; /* Partition type found in DOS partition table entry. */
} FS_PARTITION_INFO;The field .Type may have one of the following values listed below. The following page gives additional information about some possible partition types. Also you may refer to the Table 5.3 of the book "File System Forensic Analysis, Carrier Brian, 2005" that gives various values used in the partition type field of DOS partitions.
#define FS_PARTITION_TYPE_FAT12_CHS 0x01u
#define FS_PARTITION_TYPE_FAT16_16_32MB 0x04u
#define FS_PARTITION_TYPE_CHS_MICROSOFT_EXT 0x05u
#define FS_PARTITION_TYPE_FAT16_CHS_32MB_2GB 0x06u
#define FS_PARTITION_TYPE_FAT32_CHS 0x0Bu
#define FS_PARTITION_TYPE_FAT32_LBA 0x0Cu
#define FS_PARTITION_TYPE_FAT16_LBA_32MB_2GB 0x0Eu
#define FS_PARTITION_TYPE_LBA_MICROSOFT_EXT 0x0Fu
#define FS_PARTITION_TYPE_HID_FAT12_CHS 0x11u
#define FS_PARTITION_TYPE_HID_FAT16_16_32MB_CHS 0x14u
#define FS_PARTITION_TYPE_HID_FAT16_CHS_32MB_2GB 0x15u
#define FS_PARTITION_TYPE_HID_CHS_FAT32 0x1Bu
#define FS_PARTITION_TYPE_HID_LBA_FAT32 0x1Cu
#define FS_PARTITION_TYPE_HID_FAT16_LBA_32MB_2GB 0x1Eu
#define FS_PARTITION_TYPE_NTFS 0x07u
#define FS_PARTITION_TYPE_MICROSOFT_MBR 0x42u
#define FS_PARTITION_TYPE_SOLARIS_X86 0x82u
#define FS_PARTITION_TYPE_LINUX_SWAP 0x82u
#define FS_PARTITION_TYPE_LINUX 0x83u
#define FS_PARTITION_TYPE_HIBERNATION_A 0x84u
#define FS_PARTITION_TYPE_LINUX_EXT 0x85u
#define FS_PARTITION_TYPE_NTFS_VOLSETA 0x86u
#define FS_PARTITION_TYPE_NTFS_VOLSETB 0x87u
#define FS_PARTITION_TYPE_HIBERNATION_B 0xA0u
#define FS_PARTITION_TYPE_HIBERNATION_C 0xA1u
#define FS_PARTITION_TYPE_FREE_BSD 0xA5u
#define FS_PARTITION_TYPE_OPEN_BSD 0xA6u
#define FS_PARTITION_TYPE_MAX_OSX 0xA8u
#define FS_PARTITION_TYPE_NET_BSD 0xA9u
#define FS_PARTITION_TYPE_MAC_OSX_BOOT 0xABu
#define FS_PARTITION_TYPE_BSDI 0xB7u
#define FS_PARTITION_TYPE_BSDI_SWAP 0xB8u
#define FS_PARTITION_TYPE_EFI_GPT_DISK 0xEEu
#define FS_PARTITION_TYPE_EFI_SYS_PART 0xEFu
#define FS_PARTITION_TYPE_VMWARE_FILE_SYS 0xFBu
#define FS_PARTITION_TYPE_VMWARE_SWAP 0xFCuFSVol_Open()#
Description#
Open a volume & mount on the file system.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
FS_VOL_HANDLE FSVol_Open ( FS_BLK_DEV_HANDLE blk_dev_handle,
FS_PARTITION_NBR partition_nbr,
const CPU_CHAR *vol_name,
FS_FLAGS open_opt,
RTOS_ERR *p_err)Arguments#
blk_dev_handle
Block device handle.
partition_nbr
Number of the partition to be opened. Maximum of 4 partitions allowed per media.
vol_name
Volume name to be assigned to the opened volume (see Note #1).
open_opt
Open options. Any OR'd combination among:
FS_VOL_OPT_DFLTWrite operations allowed, auto sync disabled, default sys-specific options.FS_VOL_OPT_ACCESS_MODE_RD_ONLYWrite operations disallowed.FS_VOL_OPT_AUTO_SYNCAuto sync enabled.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_VOL_OPENEDRTOS_ERR_NAME_INVALIDRTOS_ERR_VOL_FMT_INVALIDRTOS_ERR_PARTITION_INVALIDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_IO
Returned Value#
Handle to the opened volume.
Notes / Warnings#
(1) Volume name MUST be unique across all opened volumes.
FSVol_Close()#
Description#
Close a volume.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
void FSVol_Close (FS_VOL_HANDLE vol_handle,
RTOS_ERR *p_err)Arguments#
vol_handle
Handle to a volume.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_VOL_CLOSED
Returned Value#
none.
Notes / Warnings#
The volume is closed even when entries are opened.
During the volume close operation, an IO access could happen to the media. In the case of a removable media, if the close operation is performed after the media removal, the IO access will return an IO error. This error condition is expected in that case. Hence the IO error is considered as NO error. In the case of a fixed media or if the device close operation is done before a removable media is disconnected, an IO error means that something important did not work. This condition will be detected by the application when re-opening the volume.
FSVol_Sync()#
Description#
Ensure that all pending write operations reach the underlying physical media.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
void FSVol_Sync (FS_VOL_HANDLE vol_handle,
RTOS_ERR *p_err)Arguments#
vol_handle
Handle to a volume.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_VOL_CLOSEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
None.
FSVol_Query()#
Description#
Obtain information about a volume.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
void FSVol_Query (FS_VOL_HANDLE vol_handle,
FS_VOL_INFO *p_vol_info,
RTOS_ERR *p_err)Arguments#
vol_handle
Volume handle.
p_vol_info
Pointer to structure that will receive volume information.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
(1) The volume information structure has the following fields:
typedef struct fs_vol_info {
FS_LB_QTY BadSecCnt; /* Number of bad sectors. */
FS_LB_QTY FreeSecCnt; /* Number of free sectors. */
FS_LB_QTY UsedSecCnt; /* Number of used sectors. */
FS_LB_QTY TotSecCnt; /* Total number of sectors. */
} FS_VOL_INFO;FSVol_PartitionNbrGet()#
Description#
Get the partition number where the volume resides.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
FS_PARTITION_NBR FSVol_PartitionNbrGet (FS_VOL_HANDLE vol_handle,
RTOS_ERR *p_err)Arguments#
vol_handle
Handle to a volume.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_VOL_CLOSED
Returned Value#
Partition number.
Notes / Warnings#
None.
FSVol_LabelSet()#
Description#
Set volume label.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
void FSVol_LabelSet ( FS_VOL_HANDLE vol_handle,
const CPU_CHAR *p_label,
RTOS_ERR *p_err)Arguments#
vol_handle
Handle to a volume.
p_label
Pointer to volume label.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NAME_INVALIDRTOS_ERR_WOULD_OVFRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
None.
FSVol_LabelGet()#
Description#
Get volume label.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
void FSVol_LabelGet (FS_VOL_HANDLE vol_handle,
CPU_CHAR *p_label,
CPU_SIZE_T label_size,
RTOS_ERR *p_err)Arguments#
vol_handle
Handle to a volume.
p_label
Pointer to a buffer that will receive volume label.
label_size
Size of the give string buffer (see Note #1).
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_WOULD_OVFRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
(1) 'label_size' is the maximum length string that can be stored in the buffer; it does NOT include the final NULL character. The buffer MUST be of at least 'label_size' + 1 characters.
FSVol_NameGet()#
Description#
Get a volume's name.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
void FSVol_NameGet (FS_VOL_HANDLE vol_handle,
CPU_CHAR *p_buf,
CPU_SIZE_T buf_size,
RTOS_ERR *p_err)Arguments#
vol_handle
Handle to a volume.
p_buf
Pointer to a buffer that will receive the volume name.
buf_size
Size of the provided buffer.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_VOL_CLOSEDRTOS_ERR_WOULD_OVF
Returned Value#
none.
Notes / Warnings#
None.
FSVol_Get()#
Description#
Get a volume by name.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
FS_VOL_HANDLE FSVol_Get (const CPU_CHAR *p_vol_name)Arguments#
p_vol_name
Pointer to name of the volume.
Returned Value#
Handle to the found volume
NULL handle if no volume is found.
Notes / Warnings#
None.
FSVol_BlkDevGet()#
Description#
Get parent block device handle.
Files#
fs_core_vol.h/fs_core_vol.c
Prototype#
FS_BLK_DEV_HANDLE FSVol_BlkDevGet (FS_VOL_HANDLE vol_handle)Arguments#
vol_handle
Handle to a volume.
Returned Value#
Handle to the parent block device
NULL handle if the volume closed.
Notes / Warnings#
None.
FSWrkDir_Open()#
Description#
Open a working directory.
Files#
fs_core_working_dir.h/fs_core_working_dir.c
Prototype#
FS_WRK_DIR_HANDLE FSWrkDir_Open ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *p_path,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to the current working directory.
p_path
Pointer to a directory path relative to the given working directory.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_NOT_FOUNDRTOS_ERR_INVALID_TYPERTOS_ERR_ENTRY_MAX_DEPTH_EXCEEDEDRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
Handle to the opened working directory.
Notes / Warnings#
None.
FSWrkDir_Close()#
Description#
Close a working directory.
Files#
fs_core_working_dir.h/fs_core_working_dir.c
Prototype#
void FSWrkDir_Close (FS_WRK_DIR_HANDLE wrk_dir_handle,
RTOS_ERR *p_err)Arguments#
working_dir_handle
Handle to the working directory to be closed.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_WRK_DIR_CLOSED
Returned Value#
none.
Notes / Warnings#
None.
FSWrkDir_TaskBind()#
Description#
Bind a working directory to the current task.
Files#
fs_core_working_dir.h/fs_core_working_dir.c
Prototype#
void FSWrkDir_TaskBind ( FS_WRK_DIR_HANDLE wrk_dir_handle,
const CPU_CHAR *p_path,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory.
p_path
Pointer to a directory path relative to the given working directory.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_INVALID_TYPERTOS_ERR_ENTRY_MAX_DEPTH_EXCEEDEDRTOS_ERR_WRK_DIR_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
None.
FSWrkDir_TaskUnbind()#
Description#
Unbind a working directory from the current task.
Files#
fs_core_working_dir.h/fs_core_working_dir.c
Prototype#
void FSWrkDir_TaskUnbind (RTOS_ERR *p_err)Arguments#
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONE
Returned Value#
none.
Notes / Warnings#
None.
FSWrkDir_Get()#
Description#
Get working directory bound to the current task.
Files#
fs_core_working_dir.h/fs_core_working_dir.c
Prototype#
FS_WRK_DIR_HANDLE FSWrkDir_Get (void)Arguments#
None.
Returned Value#
Working directory handle.
Notes / Warnings#
None.
FSWrkDir_VolGet()#
Description#
Get volume handle associated to given working directory.
Files#
fs_core_working_dir.h/fs_core_working_dir.c
Prototype#
FS_VOL_HANDLE FSWrkDir_VolGet (FS_WRK_DIR_HANDLE wrk_dir_handle)Arguments#
wrk_dir_handle
Handle to a working directory.
Returned Value#
Parent volume handle or NULL handle if working directory is closed.
Notes / Warnings#
None.
FSWrkDir_PathGet()#
Description#
Get the absolute path of a working directory.
Files#
fs_core_working_dir.h/fs_core_working_dir.c
Prototype#
CPU_SIZE_T FSWrkDir_PathGet (FS_WRK_DIR_HANDLE wrk_dir_handle,
CPU_CHAR *p_buf,
CPU_SIZE_T buf_size,
RTOS_ERR *p_err)Arguments#
wrk_dir_handle
Handle to a working directory.
p_buf
Pointer to a buffer that will receive the path.
buf_size
Size of the provided buffer.
p_err
Pointer to variable that will receive the return error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_WOULD_OVFRTOS_ERR_ENTRY_CLOSEDRTOS_ERR_VOL_CLOSEDRTOS_ERR_VOL_CORRUPTEDRTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
The total number of characters in the path.
Notes / Warnings#
None.