X-Git-Url: http://cloudbase.mooo.com/gitweb/z180-stamp.git/blobdiff_plain/e1deb7c3bc0500aabf5d099adb231f6d1d27f01d..b30c4e8f1aef96f6fdc93da9f125545f5f74d06e:/fatfs/doc/en/lseek.html diff --git a/fatfs/doc/en/lseek.html b/fatfs/doc/en/lseek.html index 0f22cf9..cf4f47e 100644 --- a/fatfs/doc/en/lseek.html +++ b/fatfs/doc/en/lseek.html @@ -17,8 +17,8 @@
 FRESULT f_lseek (
-  FIL* fp,   /* [IN] File object */
-  DWORD ofs  /* [IN] File read/write pointer */
+  FIL*    fp,  /* [IN] File object */
+  FSIZE_t ofs  /* [IN] File read/write pointer */
 );
 
@@ -29,7 +29,7 @@ FRESULT f_lseek (
fp
Pointer to the open file object.
ofs
-
Byte offset from top of the file.
+
Byte offset from top of 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.
@@ -40,7 +40,6 @@ FRESULT f_lseek ( FR_OK, FR_DISK_ERR, FR_INT_ERR, -FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT

@@ -49,19 +48,19 @@ FRESULT f_lseek (

Description

-

The f_lseek() function moves the file read/write pointer of an open file. The offset can be specified in only origin from top of the file. When an offset beyond the file size is specified at write mode, the file size is expanded to the specified offset. The file data in the expanded area is undefined because no data is written to the file. This is suitable to pre-allocate a cluster chain quickly, for fast write operation. 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 current read/write pointer is not the expected value, either of followings has been occured.

+

The f_lseek function moves the file read/write pointer of an open file. The offset can be specified in only origin from top of the file. When an offset beyond the file size is specified at write mode, the file size is expanded to the specified offset. The file data in the expanded area is undefined because no data is written to the file in this process. This is suitable to pre-allocate a cluster chain quickly, for fast write operation. When 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 the expected value, either of followings has been occured.

-

Fast seek feature is enabled when _USE_FASTSEEK is set to 1 and the member cltbl in the file object is not NULL. This feature enables fast backward/long seek operations without FAT access by using CLMT (cluster link map table). The fast seek feature is also applied to f_read()/f_write() function, however, the file size cannot be expanded by f_write()/f_lseek() function.

-

The CLMT must be created in the user defined DWORD array prior to use the fast seek feature. To create the CLMT, set address of the DWORD array to the member cltbl in the file object, set the array size in unit of items into the first item and call the f_lseek() function with ofs = CREATE_LINKMAP. After the function succeeded and CLMT is created, no FAT access is occured at subsequent f_read()/f_write()/f_lseek() function to the file. If the function failed with FR_NOT_ENOUGH_CORE, the given array size is insufficient for the file and number of items required is returned into the first item of the array. The required array size is (number of fragments + 1) * 2 items. For example, when the file is fragmented in 5, 12 items will be required for the CLMT.

+

The fast seek function 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 in fast seek mode.

+

The fast seek function is enabled when the member cltbl in the file object is not NULL. The CLMT must be created into the DWORD array prior to use the fast seek function. 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 first item and call the f_lseek function with ofs = CREATE_LINKMAP. After the function succeeded and CLMT is created, 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 first item of the array. The number of items to be used is (number of the file fragments + 1) * 2. For example, when the file is fragmented in 5, 12 items in the array will be used. If the function failed with FR_NOT_ENOUGH_CORE, the given array size is insufficient for the file.

QuickInfo

-

Available when _FS_MINIMIZE <= 2.

+

Available when _FS_MINIMIZE <= 2. To use fast seek function, _USE_FASTSEEK needs to be set 1.

@@ -94,7 +93,7 @@ FRESULT f_lseek ( if (res || f_tell(fp) != PRE_SIZE) ... /* Check if the file has been expanded */ res = f_lseek(fp, DATA_START); /* Record data stream WITHOUT cluster allocation delay */ - ... /* DATA_START and write block size should be aligned to sector boundary */ + ... /* Write operation should be aligned to sector boundary to optimize the write throughput */ res = f_truncate(fp); /* Truncate unused area */ res = f_lseek(fp, 0); /* Put file header */ @@ -103,13 +102,15 @@ FRESULT f_lseek ( res = f_close(fp);
-/* Using fast seek feature */
+/* Using fast seek function */
 
     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 feature (cltbl != NULL) */
+    fp->cltbl = clmt;                      /* Enable fast seek function (cltbl != NULL) */
     clmt[0] = SZ_TBL;                      /* Set table size */
     res = f_lseek(fp, CREATE_LINKMAP);     /* Create CLMT */
     ...
@@ -121,7 +122,7 @@ FRESULT f_lseek (
 
 

See Also

-

f_open, f_truncate, FIL

+

f_open, f_truncate, f_expand, FIL

Return