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] Operation mode */
);

Parameters

fp
Pointer to the open file 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 _FS_EXFAT.
opt
Operation mode. Prepare only (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 function allocates a contiguous data area to the file. Unlike expansion of file by f_lseek function, the file must be truncated prior to use this function and read/write pointer of the file stays at top of the file after the function. 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.

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

The contiguous file would have an advantage at time-critical read/write operations. It reduces some overheads in the file system and the storage media caused by random access due to fragmented file data. Especially, at the exFAT volume, any FAT access for the contiguous file is completely eliminated and storage media will be accessed sequentially.

Also the contiguous file data can be easily accessed directly via low-level disk functions but it is not recommended in consideration for future compatibility.

QuickInfo

Available when _USE_EXPAND == 1 and _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);
        ...
    }

    /* Alloacte a 100 MiB of contiguous area to the file */
    res = f_expand(fp, 104857600, 1);
    if (res) { /* Check if the file has been expanded */
        ...
        free(fp);
        ...
    }
    /* Now you have a contiguous file accessible with fp */

    /* Accessing the file data directly via low-level disk functions */

    /* Get physical location of the file data */
    drv = fp->obj.fs->drv;
    sect = 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, buffer, sect, 2048);

See Also

f_open, f_lseek, FIL

Return