## f_lseek

The f_lseek function moves the file read/write pointer of an open file object. It can also be used to expand the file size (cluster pre-allocation).

    FRESULT f_lseek (
      FIL*    fp,  /* [IN] File object */
      FSIZE_t ofs  /* [IN] Offset of file read/write pointer to be set */
    );

    FRESULT f_rewind (
      FIL*    fp   /* [IN] File object */
    );

#### Parameters

fp
  Pointer to the open file object. If a null pointer is given, the function fails with `FR_INVALID_OBJECT`.
ofs
  Byte offset from top of the file to set read/write pointer. 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`.

#### Return Values

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_INVALID_OBJECT, FR_TIMEOUT

#### Description

File read/write ponter in the open file object points the data byte to be read/written at next read/write operation. It advances as the number of bytes read/written. The `f_lseek` function moves the file read/write pointer without read/write operation to the file. The `f_rewind` function is impremented as a macro.

    #define f_rewind(fp) f_lseek((fp), 0)

When an offset beyond the file size is specified in write mode, the file size is expanded to the specified offset in this function. The file data in the expanded part is undefined, because no data is written to the file in this process. Be careful about these behaviours differ from POSIX `fseek` function. This is suitable to pre-allocate a data area to the file for subsequent fast write operation. If a contiguous data area needs to be allocated to the file, use `f_expand` function instead.

After the `f_lseek` function succeeded, the current read/write pointer should be checked in order to make sure the read/write pointer has been moved correctry. In case of the read/write pointer is not pointing expected offset, either of followings has been occured.

- End of file. The specified `ofs` was clipped at end of the file in read-only mode.
- Disk full. There is no free space on the volume to expand the file.

The fast seek feature enables fast backward/long seek operations without FAT access by using an on-memory CLMT (cluster link map table). It is applied to `f_read` and `f_write` function as well, however, the file size cannot be expanded by `f_write`, `f_lseek` function while the file is at fast seek mode.

The fast seek mode is available when `FF_USE_FASTSEEK = 1`. The CLMT must be created into the `DWORD` array prior to use the fast seek mode. To create the CLMT, set address of the `DWORD` array to the member `cltbl` in the open file object, set the size of array in unit of items to the `cltbl[0]` and then call `f_lseek` function with `ofs``= CREATE_LINKMAP`. After the function succeeded, no FAT access is occured in subsequent `f_read`, `f_write`, `f_lseek` function to the file. The number of items used or required is returned into the `cltbl[0]`. The number of items needed is (number of the file fragments + 1) * 2. For example, 12 items in the array will be used for the file fragmented in 5 portions. If the function failed with `FR_NOT_ENOUGH_CORE`, the size of given array is insufficient for the file.

#### QuickInfo

Available when `FF_FS_MINIMIZE <= 2`. To use fast seek function, `FF_USE_FASTSEEK` needs to be set 1 to enable this feature.

#### Example

        /* Open file */
        fp = malloc(sizeof (FIL));
        res = f_open(fp, "file.dat", FA_READ|FA_WRITE);
        if (res) ...

        /* Set read/write pointer to 5000 */
        res = f_lseek(fp, 5000);

        /* Set read/write pointer to end of the file to append data */
        res = f_lseek(fp, f_size(fp));

        /* Advance read/write pointer 3000 bytes */
        res = f_lseek(fp, f_tell(fp) + 3000);

        /* Rewind read/write pointer 2000 bytes (take care on wraparound) */
        res = f_lseek(fp, f_tell(fp) - 2000);

    /* Cluster pre-allocation (to prevent buffer overrun on streaming write) */

        res = f_open(fp, recfile, FA_CREATE_NEW | FA_WRITE);   /* Create a file */

        res = f_lseek(fp, PRE_SIZE);             /* Expand file size (cluster pre-allocation) */
        if (res || f_tell(fp) != PRE_SIZE) ...   /* Check if the file has been expanded successfly */

        res = f_lseek(fp, OFS_DATA);             /* Record data stream with free from cluster allocation delay */
        ...                                      /* Write operation should be aligned to sector boundary to optimize the write throughput */

        res = f_truncate(fp);                    /* Truncate unused area */
        res = f_lseek(fp, OFS_HEADER);           /* Set file header */
        ...

        res = f_close(fp);

    /* Using fast seek mode */

        DWORD clmt[SZ_TBL];                    /* Cluster link map table buffer */

        res = f_open(fp, fname, FA_READ | FA_WRITE);   /* Open a file */

        res = f_lseek(fp, ofs1);               /* This is normal seek (cltbl is nulled on file open) */

        fp->cltbl = clmt;                      /* Enable fast seek mode (cltbl != NULL) */
        clmt[0] = SZ_TBL;                      /* Set table size */
        res = f_lseek(fp, CREATE_LINKMAP);     /* Create CLMT */
        ...

        res = f_lseek(fp, ofs2);               /* This is fast seek */

#### See Also

`f_open, f_truncate, f_expand, FIL`

Return