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_NONE

  • RTOS_ERR_ALREADY_INIT

  • RTOS_ERR_NOT_AVAIL

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_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_NONE

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_SIZE_INVALID

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT RTOS_ERR_SEG_OVF

  • RTOS_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 size

FSCache_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_NULL for default values (see Note #1).

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_VOL_OPENED

  • RTOS_ERR_PARTITION_INVALID

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_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_EXCL Directory will be opened if and only if it does not already exist.

  • FS_DIR_ACCESS_MODE_CREATE Directory will be created, if necessary.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_TYPE_INVALID

  • RTOS_ERR_NAME_INVALID

  • RTOS_ERR_PARENT_NOT_DIR

  • RTOS_ERR_MAX_DEPTH_EXCEEDED

  • RTOS_ERR_DIR_FULL

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_VOL_FULL

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

Handle to the opened directory.

Notes / Warnings#

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

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_NONE

  • RTOS_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_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

DEF_NO, if there are other available entries.

DEF_YES, if there are no more entry.

Notes / Warnings#

  1. Entries for "dot" (current directory) and "dot-dot" (parent directory) will be returned, if present.

  2. 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_NONE

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

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

  2. 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_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NAME_INVALID

  • RTOS_ERR_ENTRY_OPENED

  • RTOS_ERR_ENTRY_ROOT_DIR

  • RTOS_ERR_ENTRY_PARENT_NOT_DIR

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. 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".

  1. 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_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ENTRY_OPENED

  • RTOS_ERR_ENTRY_ROOT_DIR

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NAME_INVALID

  • RTOS_ERR_DIR_NOT_EMPTY

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ENTRY_ROOT_DIR

  • RTOS_ERR_ENTRY_PARENT_NOT_DIR

  • RTOS_ERR_ENTRY_OPENED

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NAME_INVALID

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_DIR_NOT_EMPTY

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

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

  2. (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:

    1. ... the destination entry must NOT be a directory.

    2. ... if 'excl' is DEF_NO and the destination entry is a file, the destination entry will be deleted.

    (c) If the source entry is a directory:

    1. ... the destination entry must NOT be a file.

    2. ... if 'excl' is DEF_NO and the destination entry is a directory, the target entry MUST be empty; if so, it will be deleted.

  3. If 'excl' is DEF_NO, the destination entry must not exist.

  4. 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_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ENTRY_OPENED

  • RTOS_ERR_ENTRY_ROOT_DIR

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. If the entry does not exist, an error is returned.

  2. Three entry attributes may be modified by this function :

  • FS_ENTRY_ATTRIB_RD Entry is readable.

  • FS_ENTRY_ATTRIB_WR Entry is writable.

  • FS_ENTRY_ATTRIB_HIDDEN Entry 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.

  1. 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_CREATE

  • FS_DATE_TIME_MODIFY

  • FS_DATE_TIME_ACCESS

  • FS_DATE_TIME_ALL

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ENTRY_OPENED

  • RTOS_ERR_ENTRY_ROOT_DIR

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. The date/time of the root directory may NOT be set.

  2. The pointer p_time points to a structure of type CLK_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_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. 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_RD File opened for reads.

  • FS_FILE_ACCESS_MODE_WR File opened for writes.

  • FS_FILE_ACCESS_MODE_CREATE File will be created, if necessary.

  • FS_FILE_ACCESS_MODE_TRUNCATE File length will be truncated to 0.

  • FS_FILE_ACCESS_MODE_APPEND All writes will be performed at EOF.

  • FS_FILE_ACCESS_MODE_EXCL File 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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_TYPE_INVALID

  • RTOS_ERR_NAME_INVALID

  • RTOS_ERR_PARENT_NOT_DIR

  • RTOS_ERR_MAX_DEPTH_EXCEEDED

  • RTOS_ERR_DIR_FULL

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_FULL

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

Handle to the opened file descriptor.

Notes / Warnings#

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

  2. Micrium OS File System native file access modes along with equivalent standard 'fopen()' access modes. Combinations not listed below will generate an error. The FS_FILE_ACCESS_MODE_EXCL flag is allowed wherever FS_FILE_ACCESS_MODE_CREATE is 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

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

  4. 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_NONE

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_FILE_ERR_STATE

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_FILE_ERR_STATE

  • RTOS_ERR_FILE_ACCESS_MODE_INVALID

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_FULL

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_ENTRY_OPENED

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_FULL

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. The source file MUST exist, otherwise an error is returned.

  2. 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' is DEF_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_NONE

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_FILE_ERR_STATE

  • RTOS_ERR_FILE_ACCESS_MODE_INVALID

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_FULL

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_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_FULL

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. (a) The new file position, measured in bytes from the beginning of the file is obtained by adding 'offset' to...

    1. ...0 (the beginning of the file) if 'origin' is FS_FILE_ORIGIN_START,

    2. ...the current file position if 'origin' is FS_FILE_ORIGIN_CUR.

    3. ...the file size if 'origin' is FS_FILE_ORIGIN_END.

    (b) The end-of-file indicator is cleared.

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

  3. 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_NONE

  • RTOS_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_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_RD data buffered for reads.

  • FS_FILE_BUF_MODE_WR data buffered for writes.

  • FS_FILE_BUF_MODE_RD_WR data 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_NONE

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_SIZE_INVALID

  • RTOS_ERR_FILE_ACCESS_MODE_INVALID

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_VOL_CLOSED

Returned Value#

none.

Notes / Warnings#

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

  2. '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.

  3. 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_NONE

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_FULL

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

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

  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.

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_NONE

  • RTOS_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_NONE

  • RTOS_ERR_ENTRY_CLOSED

Returned Value#

  • DEF_YES, if EOF indicator is set.

  • DEF_NO, otherwise.

Notes / Warnings#

  1. 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_NONE

  • RTOS_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_NONE

  • RTOS_ERR_ENTRY_CLOSED

Returned Value#

none.

Notes / Warnings#

  1. File locks may be nested.

  2. 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_NONE

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_WOULD_BLOCK

Returned Value#

none.

Notes / Warnings#

  1. FSFile_TryLock() is the non-blocking version of FSFile_Lock() If the lock is not available, the function returns an error.

  2. 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_NONE

  • RTOS_ERR_SIZE_INVALID

  • RTOS_ERR_VOL_OPENED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_SIZE_INVALID

  • RTOS_ERR_PARTITION_MAX_EXCEEDED

  • RTOS_ERR_BLK_DEV_CLOSED

Returned Value#

The index of the created partition.

Notes / Warnings#

  1. The first partition on the device has index 1.

  2. 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_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

Number of partitions, if NO errors.

0, otherwise.

Notes / Warnings#

  1. 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_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. 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                  0xFCu

FSVol_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_DFLT Write operations allowed, auto sync disabled, default sys-specific options.

  • FS_VOL_OPT_ACCESS_MODE_RD_ONLY Write operations disallowed.

  • FS_VOL_OPT_AUTO_SYNC Auto sync enabled.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_VOL_OPENED

  • RTOS_ERR_NAME_INVALID

  • RTOS_ERR_VOL_FMT_INVALID

  • RTOS_ERR_PARTITION_INVALID

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_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_NONE

  • RTOS_ERR_VOL_CLOSED

Returned Value#

none.

Notes / Warnings#

  1. The volume is closed even when entries are opened.

  2. 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_NONE

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_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_NONE

  • RTOS_ERR_NAME_INVALID

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_VOL_CLOSED

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_ENTRY_MAX_DEPTH_EXCEEDED

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_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_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_ENTRY_MAX_DEPTH_EXCEEDED

  • RTOS_ERR_WRK_DIR_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_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_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_ENTRY_CLOSED

  • RTOS_ERR_VOL_CLOSED

  • RTOS_ERR_VOL_CORRUPTED

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

The total number of characters in the path.

Notes / Warnings#

None.