Utility Routines

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

Functions
fsStatus	fchdrive (const char *drive)
	Change current drive.
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 change current drive, print working directory, analyse, format, and defragment drives. Also, reading drive and volume information data is supported.

Function Documentation

int32_t fanalyse

(

const char *

drive

)

Parameters

[in]

drive

a 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 specifies the Drives, Memory Devices and Drivers to be analysed. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

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 fchdrive

(

const char *

drive

)

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

The function fchdrive changes the Current Drive.

The argument drive specifies the Drives, Memory Devices and Drivers to be selected as the Current Drive. A NULL pointer is not allowed and will be rejected.

fsStatus fcheck

(

const char *

drive

)

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful, no allocation errors.
• fsInvalidDrive = Nonexistent drive letter specified.
• fsUnsupported = FAT drive was specified.
• 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 specifies the Drives, Memory Devices and Drivers to be checked. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

Code Example

void tst_files (void) {

  if (fcheck ("F:") != fsOK) {
    printf ("Embedded File System inconsistent, formatting...\n");

    if (fformat ("F:") != fsOK) {
      printf ("Formatting failed.\n");
    }
    else {
      printf ("Format done.\n");
    }
  }
}

fsStatus fdefrag

(

const char *

drive

)

Parameters

[in]

drive

a 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.
• fsNoFreeSpace = Not enough space to complete the defragmentation.

Note

This function supports EFS drives only.

The function fdefrag de-fragments the Embedded File System. Drive is examined for used blocks which are without valid file allocation records. Such blocks are erased and marked as empty. Fragmented files are consolidated. The result of file consolidation is faster file access and increased overall performance.

The argument drive specifies the Drives, Memory Devices and Drivers to be de-fragmented. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

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]	drive	a string specifying the memory or storage device.
[in]	options	string specifying formatting options.

Returns

execution status fsStatus

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 specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

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

FAT drive formatting options:

Option	Description
/L label	Specifies volume label. If /L option is not specified or if label is not given, then volume label will not be written. Terminating character for label can be slash (/) or NUL character. Trailing spaces will be ignored.
/FAT32	Formats the media for using the FAT32 file system. FAT32 can be used on media devices with size >= 256MB.
/W	Clears all data. Erases all available data sectors.
/LL	Clears all data. Performs low-level formatting first (NAND drive only).
/LLEB	Clears all data. Performs low-level formatting and erases bad blocks first (NAND drive only). /LLEB has higher priority than /LL in case if both options are specified.
/<other>	Unknown options are ignored.

When formatting option /FAT32 is not used, the media device will be formatted using default, predefined settings. The file system type depends then on media device size and will be chosen as follows:

• FAT12 for devices with < 128MB
• FAT16 for devices with >= 128MB and <= 2GB
• FAT32 for devices with > 2GB

EFS drive formatting options:

There are no special formatting options available for the Embedded File System. Argument options is ignored.

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]

drive

a 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 specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

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]	drive	a string specifying the memory or storage device.
[out]	info	drive 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 specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

fsStatus fmedia

(

const char *

drive

)

Parameters

[in]

drive

a 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 specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

fsStatus fvol	(	const char *	drive,
		char *	label,
		uint32_t *	serial
	)

Parameters

[in]	drive	a string specifying the memory or storage device.
[out]	label	buffer 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]	serial	pointer 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 specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

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");
  }
}