## f_mkfs

The f_mkfs function creates an FAT/exFAT volume on the logical drive.

    FRESULT f_mkfs (
      const TCHAR* path,   /* [IN] Logical drive number */
      const MKFS_PARM* opt,/* [IN] Format options */
      void* work,          /* [-]  Working buffer */
      UINT len             /* [IN] Size of working buffer */
    );

#### Parameters

path
  Pointer to the null-terminated string specifies the logical drive to be formatted. If it does not have a drive number in it, it means to specify the default drive. The logical drive may or may not have been mounted for the format process.
opt
  Specifies the format option structure `MKFS_PARM` holding format options. If a null pointer is given, it gives the function every option in default value. The structure has five members in order of described below:
  BYTE fmt
    Specifies a combination of FAT type flags, `FM_FAT`, `FM_FAT32`, `FM_EXFAT` and bitwise-or of these three, `FM_ANY`. `FM_EXFAT` is ignored when exFAT is not enabled. These flags specify which type of FAT volume to be created. If two or more types are specified, one out of them will be selected depends on the volume size and `au_size`. The flag `FM_SFD` specifies to create the volume on the drive in SFD format. The default value is `FM_ANY`.
  BYTE n_fat
    Specifies number of FAT copies on the FAT/FAT32 volume. Valid value for this member is 1 or 2. The default value (0) and any invaid value gives 1. If the FAT type is exFAT, this member has no effect.
  UINT align
    Specifies alignment of the volume data area (file allocation pool, usually erase block boundary of flash memory media) in unit of sector. The valid value for this member is between 1 and 32768 inclusive in power of 2. If a zero (the default value) or any invalid value is given, the function obtains the block size from lower layer with `disk_ioctl` function.
  UINT n_root
    Specifies number of root directory entries on the FAT volume. Valid value for this member is up to 32768 and aligned to sector size / 32. The default value (0) and any invaid value gives 512. If the FAT type is FAT32 or exFAT, this member has no effect.
  DWORD au_size
    Specifies size of the cluster (allocation unit) in unit of byte. The valid value for this member is between sector size and 128 * sector size inclusive in power of 2 for FAT/FAT32 volume and up to 16 MB in power of 2 for exFAT volume. If a zero (default value) or any invalid value is given, the function uses a default cluster size depends on the volume size.
work
  Pointer to the working buffer used for the format process. If a null pointer is given with `FF_USE_LFN == 3`, the function uses a `len` bytes of heap memory in this function.
len
  Size of the working buffer in unit of byte. It needs to be `FF_MAX_SS` at least. Plenty of working buffer reduces number of write transactions to the drive, thus the format process will finish quickly.

#### Return Values

FR_OK, FR_DISK_ERR, FR_NOT_READY, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_MKFS_ABORTED, FR_INVALID_PARAMETER, FR_NOT_ENOUGH_CORE

#### Description

The FAT sub-type, FAT12/FAT16/FAT32, of FAT volume except exFAT is determined by only number of clusters on the volume and nothing else, according to the FAT specification issued by Microsoft. Thus the FAT sub-type of created volume depends on the volume size and the cluster size. In case of the combination of FAT type and cluter size specified by argument is not valid for the volume size, the function will fail with `FR_MKFS_ABORTED`.

The allocation unit, also known as cluster, is a unit of disk space allocation for files. When the size of allocation unit is 32768 bytes, a file with 100 bytes in size occupies 32768 bytes of disk space. The space efficiency of disk usage gets worse as increasing size of allocation unit, but, on the other hand, the read/write performance increases. Therefore the size of allocation unit is a trade-off between space efficiency and performance. For the large volumes in GB order, 32768 bytes or larger, automatically selected by default, is recommended for most case unless extremely many small files are created in the volume.

When the logical drive to be formatted is associated with a physical drive (`FF_MULTI_PARTITION == 0` or `VolToPart[].pt == 0`) and `FM_SFD` flag is not specified, a partition occupies entire drive space is created and then the FAT volume is created in the partition. When `FM_SFD` flag is specified, the FAT volume is created without any disk partitioning.

When the logical drive to be formatted is associated with a specific partition by multiple partition feature (`FF_MULTI_PARTITION == 1` and `VolToPart[].pt > 0`), the FAT volume is created in the partition of the physical drive specified by volume mapping table and `FM_SFD` flag is ignored. The hosting physical drive needs to be partitioned with `f_fdisk` function or some partitioning tool prior to create the FAT volume with this function. If the partition is not exist, the function fails with `FR_MKFS_ABORTED`.

There are three standard disk partitioning formats, MBR, GPT and SFD. The MBR format, also known as FDISK format, is usually used for harddisk, memory card and U disk. It can divide a physical drive into one or more partitions with a partition table. The GPT, GUID Partition Table, is a newly defined patitioning format for large storage devices. FatFs suppors the GPT only when 64-bit LBA is enabled. The SFD, Super-Floppy Disk, is non-partitioned disk format. The FAT volume is located at LBA 0 and occupies the entire physical drive without any disk partitioning. It is usually used for floppy disk, optical disk and most super-floppy media. Some combination of systems and media support only either partitioned format or non-partitioned format and the other is not supported.

Some systems manage the partitions in the on-board storage in non-standard format. The partitions are mapped as physical drives identified by `pdrv` in `disk_*` functions. For such systems, SFD format is suitable to create the FAT volume in the partition.

#### QuickInfo

Available when `FF_FS_READOLNY == 0` and `FF_USE_MKFS == 1`.

#### Example

    /* Format default drive and create a file */
    int main (void)
    {
        FATFS fs;           /* Filesystem object */
        FIL fil;            /* File object */
        FRESULT res;        /* API result code */
        UINT bw;            /* Bytes written */
        BYTE work[FF_MAX_SS]; /* Work area (larger is better for processing time) */

        /* Format the default drive with default parameters */
        res = f_mkfs("", 0, work, sizeof work);
        if (res) ...

        /* Give a work area to the default drive */
        f_mount(&fs, "", 0);

        /* Create a file as new */
        res = f_open(&fil, "hello.txt", FA_CREATE_NEW | FA_WRITE);
        if (res) ...

        /* Write a message */
        f_write(&fil, "Hello, World!\r\n", 15, &bw);
        if (bw != 15) ...

        /* Close the file */
        f_close(&fil);

        /* Unregister work area */
        f_mount(0, "", 0);

        ...

#### See Also

Example of volume size and format parameters, Volume management, `f_fdisk`

Return