## f_lseek

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

    FRESULT f_lseek (
      FIL* FileObject,   /* Pointer to the file object structure */
      DWORD Offset       /* File offset in unit of byte */
    );

#### Parameters

FileObject
  Pointer to the open file object.
Offset
  Number of bytes where from start of file

#### Return Values

FR_OK (0)
  The function succeeded.
FR_DISK_ERR
  The function failed due to an error in the disk function.
FR_INT_ERR
  The function failed due to a wrong FAT structure or an internal error.
FR_NOT_READY
  The disk drive cannot work due to no medium in the drive or any other reason.
FR_INVALID_OBJECT
  The file object is invalid.

#### Description

The f_lseek function moves the file R/W pointer of an open file. The offset can be specified in only origin from top of the file. When an offset above the file size is specified in write mode, the file size is extended to the offset and the data in the extended area is undefined. This is suitable to create a large file quickly, for fast write operation. After the f_lseek function succeeded, member fptr in the file object should be checked in order to make sure the R/W pointer has been moved correctry. In case of fptr is less than expected value, any of the followings has been occured.

- In read-only mode, the Offset was clipped in file size.
- The drive gets full during the file extending process.

This function is not supported in minimization level of >= 3.

#### Example

        // Move to offset of 5000 from top of the file.
        res = f_lseek(&file, 5000);

        // Forward 3000 bytes
        res = f_lseek(&file, file.fptr + 3000);

        // Rewind 2000 bytes (take care on overflow)
        res = f_lseek(&file, file.fptr - 2000);

        // Move to end of the file to append data
        res = f_lseek(&file, file.fsize);

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

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

        res = f_lseek(&file, PRE_SIZE);    // Pre-allocate clusters
        if (res || file.fptr != PRE_SIZE) .... // Check if the file is extended corrctly

        res = f_lseek(&file, DATA_START);  // Record data stream without cluster allocation delay
        ...

        res = f_truncate(&file);           // Truncate unused area
        res = f_lseek(&file, 0);           // Put file header
        ...

        res = f_close(&file);

#### References

`f_open, f_truncate, FIL`

Return