Jump to main content

##

# 1.2.7.4.41 SYS_FS_DriveFormat Function

## C

    SYS_FS_RESULT SYS_FS_DriveFormat
    (
        const char *drive,
        const SYS_FS_FORMAT_PARAM *opt,
        void* work,
        uint32_t len
    );

## Summary

Formats a drive.

## Description

This function formats a logic drive (create a FAT file system on the logical drive), as per the format specified.

If the logical drive that has to be formatted has been bound to any partition (1-4) by multiple partition feature, the FAT volume is created into the specified partition. The physical drive must have been partitioned prior to using this function.

## Precondition

At least one disk must be mounted. The physical drive must have already been partitioned.

## Parameters

Param | Description
--- | ---
drive | Pointer to buffer which will hold the name of drive being for which the format is to be done. If this string is NULL, then then current drive will be formatted. It is important to end the drive name with a "/".
opt | Specifies the structure holding format options. If a null pointer is given, fat code gives the function all options in default value
work | Pointer to the working buffer used for the format process.
len | Size of the working buffer in unit of byte. It needs to be the sector size of the corresponding physical drive at least. Plenty of working buffer reduces number of write transactions to the drive and the format process will finish quickly.

## Returns

SYS_FS_RES_SUCCESS - Drive format was successful.

SYS_FS_RES_FAILURE - Drive format was unsucessful. The reason for the failure can be retrieved with SYS_FS_Error.

## Example

    SYS_FS_RESULT res;
    SYS_FS_FORMAT_PARAM opt = { 0 };
    uint8_t CACHE_ALIGN work[512];

    switch(appState)
    {
        case TRY_MOUNT:
        {
            if(SYS_FS_Mount("/dev/mmcblka1", "/mnt/myDrive", FAT, 0, NULL) != SYS_FS_RES_SUCCESS)
            {
                // Failure, try mounting again
            }
            else
            {
                // Mount was successful. Format now.
                if (SYS_FS_Error() == SYS_FS_ERROR_NO_FILESYSTEM)
                {
                    appState = FORMAT_DRIVE;
                }
                else
                {
                    appState = OTHER_TASK;
                }
            }
            break;
        }

        case FORMAT_DRIVE:
        {
            opt.fmt = SYS_FS_FORMAT_FAT;
            opt.au_size = 0;

            res = SYS_FS_DriveFormat("/mnt/myDrive", &opt, (void *)work, 512);
            if(res == SYS_FS_RES_FAILURE)
            {
                // Format of the drive failed.
            }
            break;
        }
    }

## Remarks

None.