## f_expand

The f_expand function prepares or allocates a contiguous data area to the file.

    FRESULT f_expand (
      FIL*    fp,  /* [IN] File object */
      FSIZE_t fsz, /* [IN] File size expanded to */
      BYTE    opt  /* [IN] Allocation mode */
    );

#### Parameters

fp
  Pointer to the open file object. If a null pointer is given, the function fails with `FR_INVALID_OBJECT`.
fsz
  Number of bytes in size to prepare or allocate for the file. The data type `FSIZE_t` is an alias of either `DWORD`(32-bit) or `QWORD`(64-bit) depends on the configuration option `FF_FS_EXFAT`.
opt
  Allocation mode. Prepare to allocate (0) or Allocate now (1).

#### Return Values

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_INVALID_OBJECT, FR_DENIED, FR_TIMEOUT

#### Description

The `f_expand` function prepares or allocates a contiguous data area to the file. When `opt` is 1, the data area is allocated to the file in this function. Unlike expansion of file size by `f_lseek` function, the file must be truncated prior to use this function and read/write pointer of the file stays at offset 0 after the function call. The file content allocated with this function is undefined, because no data is written to the file in this process. The function can fail with `FR_DENIED` due to some reasons below.

- No free contiguous space was found.
- Size of the file was not zero.
- The file has been opened in read-only mode.
- Not allowable file size. (>= 4 GB on FAT volume)

When `opt` is 0, the function finds a contiguous data area and set it as suggested point for next allocation. The subsequent cluster allocation begins at top of the contiguous area found by this function. Thus the file allocation is guaranteed be contiguous and without allocation delay until the file size reaches this size unless any other changes to the volume is performed.

The contiguous file has an advantage for time-critical read/write operations. It eliminates some overheads in the filesystem and the storage device caused by random access for fragmented file.

The contiguou files can easily be accessed via low-level disk functions. However, this is not recommended in consideration of portability and future compatibility. If the file has not been confirmed be contiguous, use this function to examine if the file is contiguous or not.

#### QuickInfo

Available when `FF_USE_EXPAND == 1` and `FF_FS_READONLY == 0`.

#### Example

        /* Creating a contiguous file */

        /* Create a new file */
        res = f_open(fp = malloc(sizeof (FIL)), "file.dat", FA_WRITE|FA_CREATE_ALWAYS);
        if (res) { /* Check if the file has been opened */
            free(fp);
            die("Failed to open the file.");
        }

        /* Allocate a 100 MiB of contiguous area to the file */
        res = f_expand(fp, 104857600, 1);
        if (res) { /* Check if the file has been expanded */
            f_close(fp);
            free(fp);
            die("Failed to allocate contiguous area.");
        }

        /* Now you have a contiguous file accessible with fp */

        /* Accessing the contiguous file via low-level disk functions */

        /* Get physical location of the file data */
        drv = fp->obj.fs->pdrv;
        lba = fp->obj.fs->database + fp->obj.fs->csize * (fp->obj.sclust - 2);

        /* Write 2048 sectors from top of the file at a time */
        res = disk_write(drv, data, lba, 2048);

#### See Also

`f_open, f_lseek, FIL`

Return