FAT | RFS | XFS

format()

PROTOTYPE

#include <posix.h>

int format(const char *name);

DESCRIPTION

format() creates a volume image that contains nothing but an empty root directory. A volume must be formatted before it can be mounted, so format() can be used to prepare a new volume for initial use or it may be used to “start over” with a previously used volume, erasing all its prior files. name must match the root name of an added but unmounted volume.

If an FTL is used, format() erases every good block that holds FTL metadata and flags every block as free. This improves performance because no old data (pre format) will be copied off blocks before garbage collection. The FTL will have no used pages but may have dirty pages.

format() returns 0 if successful, else it sets errno to the appropriate error code and returns -1.

ERROR CODES

EFAULT	name equals NULL.
EINVAL	The specified volume is currently mounted.
ENOENT	No attached volume matches the specified name.

EXAMPLE

  /*-------------------------------------------------------------------*/
  /* Try to mount volume. Format volume if unformatted.                */
  /*-------------------------------------------------------------------*/
  printf("Mounting \"" VOL_NAME "\" volume, ");
  measStart();
  rc = mount(VOL_NAME);
  if (rc == 0)
    puts("successful");
  else if (errno == EEXIST)
    puts("was already mounted");
  else if (errno != EINVAL)
    error("unexpected mount error");
  else
  {
    /*-----------------------------------------------------------------*/
    /* Mount failed because volume is unformatted.                     */
    /*-----------------------------------------------------------------*/
    puts("is unformatted");
    measStop();

    /*-----------------------------------------------------------------*/
    /* Format the volume.                                              */
    /*-----------------------------------------------------------------*/
    printf("Formatting \"%s\" volume", VOL_NAME);
    measStart();
    if (format(VOL_NAME))
      error(", failed");
    measStop();
    measReportTime(", took %s");
    putchar('\n');

    /*-----------------------------------------------------------------*/
    /* Restart the mount timing and repeat the mount attempt.          */
    /*-----------------------------------------------------------------*/
    measStart();
    rc = mount(VOL_NAME);
    if (rc)
      error("Second mount attempt failed");
  }
  measStop();
  if (rc == 0)
    measReportTime("Time for mount is %s\n");