System Routines

System Routines initialize the File System or Drive. More...

Functions
fsStatus	finit (const char *drive)
	Initialize File System and drive related driver.
fsStatus	funinit (const char *drive)
	Uninitialize File System.
fsStatus	fmount (const char *drive)
	Mount drive.
fsStatus	funmount (const char *drive)
	Unmount drive.

Description

The following diagram shows the basic flow of how to call the system routines to get access to a drive and a drive's media:

1. Call finit to initialize the drive itself.
2. Call fmount to get access to the drive's media.
3. Work with the media.
4. Call funmount to give up access to the media.
5. Call funinit to uninitialize the drive.

Basic Flow Diagram for Calling System Routines

The routines are thread safe.

Code Example

void main (void) {
  FILE *f;

  // Initialize the M: drive.
  if (finit ("M:") != fsOK) {
    // error handling
    ...
  }
  // Mount the M: drive.
  if (fmount ("M:") != fsOK) {
    // error handling
    ...
  }
  // Update a log file on SD card.
  f = fopen ("M:\\Logs\\Test_file.log","a");
  if (f == NULL) {
    // error handling
    ...
  }
  else {
    // write data to file
    fclose (f);
  }
  // The drive is no more needed.
  funmount ("M:");
  funinit ("M:");
  ..
}

Function Documentation

fsStatus finit

(

const char *

drive

)

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful.
• fsInvalidParameter = Input parameter invalid.
• fsInvalidDrive = Nonexistent drive letter specified.
• fsDriverError = Failed to initialize the driver.

The function finit initializes the software library resources required for a certain drive, including the File System and the related driver. It must be called before invoking any other function accessing the file system of the drive. Calling finit does not access the actual media on the specified drive. Before working with the drive's media, a call to fmount is required. fmount checks if the media is present and formatted. finit fails if the File System Component in general or the driver cannot be initialized.

The argument drive specifies the Drives, Memory Devices and Drivers to be initialized. Every drive that is used in the system must be initialized separately using this function. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

fsStatus fmount

(

const char *

drive

)

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful.
• fsUninitializedDrive = Media driver not initialized.
• fsInvalidParameter = Input parameter invalid.
• fsInvalidDrive = Nonexistent drive letter specified.
• fsDriverError = Media driver operation failed.
• fsMediaError = Failed to initialize the media.
• fsNoMedia = Media device is not insterted.
• fsNoFileSystem = No filesystem on the volume.

The function fmount is used to mount the File System of the specified Drives, Memory Devices and Drivers. It initializes memory media, media management layer and the file system on top of it. Mounting means that it will be checked if the drive's media is attached and formatted. After a successful mount, drive is ready for file I/O operations (such as fread, fwrite, etc.).

The argument drive specifies the Drives, Memory Devices and Drivers to be mounted. Every drive that is used in the system must be mounted separately using this function. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

fsStatus funinit

(

const char *

drive

)

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful.
• fsInvalidParameter = Input parameter invalid.
• fsInvalidDrive = Nonexistent drive letter specified.

The funinit function uninitializes the File System. This is necessary if during application run time the drive volume needs to be disabled (for example for lowering power consumption). To reinitialize the drive afterwards, finit needs to be called again.

The argument drive specifies the Drives, Memory Devices and Drivers to be uninitialized. Every drive that is used in the system must be uninitialized separately using this function. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

fsStatus funmount

(

const char *

drive

)

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful.
• fsInvalidParameter = Input parameter invalid.
• fsInvalidDrive = Nonexistent drive letter specified.

The function funmount is used to unmount a File System volume. When called, it flushes the data from internal file system buffers, closes all opened file handlers associated with the specified drive and disconnects the memory media. In case when removable memory media is not present only file handlers associated with the specified drive are closed.

The argument drive specifies the Drives, Memory Devices and Drivers to be unmounted. Every drive that is used in the system must be unmounted separately using this function. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.