File System Component  Version 5.0
MDK-Professional Middleware for Devices with Flash File System
 All Data Structures Files Functions Variables Enumerations Enumerator Macros Groups Pages
Utility Routines

Utility Routines provide analytical operations on drives. More...

Functions

int64_t ffree (const char *drive)
 Find free space on drive.
 
fsStatus fformat (const char *drive, const char *options)
 Format drive.
 
int32_t fanalyse (const char *drive)
 Analyse volume and check for file fragmentation.
 
fsStatus fcheck (const char *drive)
 Analyse volume and check for allocation errors.
 
fsStatus fdefrag (const char *drive)
 Defragment Embedded Flash drive.
 
fsStatus fmedia (const char *drive)
 Check if media present on removable drive.
 
fsStatus finfo (const char *drive, fsDriveInfo *info)
 Read drive information.
 
fsStatus fvol (const char *drive, char *label, uint32_t *serial)
 Read volume label and serial number.
 

Description

You can analyse, format, and defragment drives. Also, reading drive and volume information data is supported.

Function Documentation

int32_t fanalyse ( const char *  drive)
Parameters
[in]drivea string specifying the memory or storage device.
Returns
fragmentation factor or execution status
  • value >= 0 or <= 255: fragmentation factor
  • value < 0: error occurred, -value is execution status as defined with fsStatus
Note
This function supports EFS drives only.

The function fanalyse examines the Embedded File System and checks for file fragmentation.

The argument drive may only use NOR and SPI drives, as well as "" (Default System Drive).

Code Example

void free_space (void) {
printf ("\nFree space before defrag: %d bytes.", ffree(""));
if (fanalyse("") > 50) {
fdefrag ("");
}
printf ("\nFree space after defrag: %d bytes.", ffree(""));
}
fsStatus fcheck ( const char *  drive)
Parameters
[in]drivea string specifying the memory or storage device.
Returns
execution status fsStatus
  • fsOK = Operation successful, no allocation errors
  • fsInvalidDrive = Nonexistent drive letter specified.
  • fsAccessDenied = Unsupported drive.
  • fsTooManyOpenFiles = File cannot be opened due to too many opened files.
  • fsError = Check failed due to allocation errors.
Note
This function supports EFS drives only.

The function fcheck analyses the consistency of the Embedded File System and determines if it has been initialized.

The argument drive may only use NOR and SPI drives, as well as "" (Default System Drive).

Code Example

void tst_files (void) {
if (fcheck ("R:") != fsOK) {
printf ("Flash File System inconsistent, formatting...\n");
if (fformat ("R:") != fsOK) {
printf ("Formatting failed.\n");
}
else {
printf ("Format done.\n");
}
}
}
fsStatus fdefrag ( const char *  drive)
Parameters
[in]drivea string specifying the memory or storage device.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive letter specified.
  • fsAccessDenied = Not all files are closed on specified drive or unsupported drive.
  • fsTooManyOpenFiles = File cannot be opened due to too many opened files.
  • fsNoFreeSpace = Not enough space to complete the defragmentation.
Note
This function supports EFS drives only.

The function fdefrag defragments the Embedded File System.

The argument drive may only use NOR and SPI drives, as well as "" (Default System Drive).

Code Example

void free_space (void) {
printf ("\nFree space before defrag: %d bytes.", ffree("F:"));
if (fanalyse("F:") > 50) {
fdefrag ("F:");
}
printf ("\nFree space after defrag: %d bytes.", ffree("F:"));
}
fsStatus fformat ( const char *  drive,
const char *  options 
)
Parameters
[in]drivea string specifying the memory or storage device.
[in]optionsstring specifying formatting options.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive letter specified.
  • fsTooManyOpenFiles = File cannot be opened due to too many opened files.
  • fsError = Formatting failed.

The function fformat formats an EFS or FAT storage media for using a file system. The function closes all open files on the specified drive. Existing file handles become invalid.

The argument drive is specifying the drive. In addition, you may also use "" (Default System Drive).

The argument options can be NULL when formatting options are not used or a pointer to a string specifying following options:

Option Description
/L label Specifies volume label for a FAT drive. If /L option is not specified or if label is not given, then volume label will not be written.
/FAT32 Formats the media for using the FAT32 file system.
/W Clears all data. Erases all available data sectors.
/LL Clears all data. Performs low-level formatting first.
/LLEB Clears all data. Performs low-level formatting and erases bad blocks first.

Code Example

void format_drive (void) {
char *opt;
// Set formatting options
opt = "/L SD Card /FAT32";
if (fformat ("M:", opt) != fsOK) {
printf ("Formatting failed!\n");
}
else {
printf ("Drive formatted using FAT 32 with label SD Card.\n");
}
}
int64_t ffree ( const char *  drive)
Parameters
[in]drivea string specifying the memory or storage device.
Returns
free space or execution status
  • value >= 0: free space on drive in bytes.
  • value < 0: error occurred, -value is execution status as defined with fsStatus

The function ffree calculates the free space on a device.

The argument drive is specifying a drive.

Code Example

void free_space (void) {
printf ("Flash Drive free: %lld bytes.\n", ffree("F:"));
printf ("Ram Drive free: %lld bytes.\n", ffree("R:"));
printf ("SD Card Drive 1 free: %lld bytes.\n", ffree("M0:"));
printf ("SD Card Drive 2 free: %lld bytes.\n", ffree("M1:"));
}
fsStatus finfo ( const char *  drive,
fsDriveInfo info 
)
Parameters
[in]drivea string specifying the memory or storage device.
[out]infodrive information structure.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidParameter = Input parameters invalid.
  • fsInvalidDrive = Nonexistent drive letter specified.

The function finfo reads general drive informations from the volume and puts them into the info structure.

The argument drive is specifying a FAT volume drive. The Default System Drive is used, if an empty string "" is provided.

fsStatus fmedia ( const char *  drive)
Parameters
[in]drivea string specifying the memory or storage device.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsNoMedia = Media not present.
  • fsAccessDenied = Tried to access non-removable drive.
Note
This function supports FAT drives only.

The function fmedia checks the presence of a removable drive in the system (such as SD/MMC cards or USB Flash drives). If a media device interface driver is not able to detect the presence of the associated media this function always returns fsOK.

The argument drive may only use Memory Card and USB Flash drives, as well as "" (for using the Default System Drive).

fsStatus fvol ( const char *  drive,
char *  label,
uint32_t *  serial 
)
Parameters
[in]drivea string specifying the memory or storage device.
[out]labelbuffer for storing label as a null terminated string. When volume has no label an empty string is returned. This parameter can be NULL meaning label will not be read.
[out]serialpointer to variable where serial number will be stored. This parameter can be NULL meaning serial number will not be read.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive letter specified.
  • fsAccessDenied = Trying to read label and serial from EFS drive.
  • fsDriverError = Read/write error.
Note
This function supports FAT drives only.

The function fvol reads the volume label.

The argument drive is specifying a FAT volume drive. The Default System Drive is used, if an empty string "" is provided.

The argument label specifies a buffer where the volume label will be stored as a null terminated string. Its size must be at least 12 bytes to prevent buffer overflow. If volume has no label an empty string is returned.

The argument serial specifies a pointer to a 32-bit variable where the volume serial number will be stored. The serial number is usually written when the volume is formatted and can be used to distinguish between volumes on removable devices.

Code Example

void tst_fvol (void) {
char label[12];
uint32_t ser_num;
if (fvol("U0:", label, &ser_num) == fsOK) {
if (label_buf[0]) {
printf ("Volume in drive U0 is %s\n", label);
}
else {
printf ("Volume in drive U0 has no label.\n");
}
printf ("Volume serial number is %x\n", ser_num);
}
else {
printf ("Volume access error!\n");
}
}