1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4 <meta http-equiv=
"Content-Type" content=
"text/html; charset=utf-8">
5 <meta http-equiv=
"Content-Style-Type" content=
"text/css">
6 <link rel=
"up" title=
"FatFs" href=
"../00index_e.html">
7 <link rel=
"alternate" hreflang=
"ja" title=
"Japanese" href=
"../ja/lseek.html">
8 <link rel=
"stylesheet" href=
"../css_e.css" type=
"text/css" media=
"screen" title=
"ELM Default">
9 <title>FatFs - f_lseek
</title>
14 <div class=
"para func">
16 <p>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).
</p>
20 FIL*
<span class=
"arg">fp
</span>,
<span class=
"c">/* [IN] File object */
</span>
21 FSIZE_t
<span class=
"arg">ofs
</span> <span class=
"c">/* [IN] Offset of file read/write pointer to be set */
</span>
26 FIL*
<span class=
"arg">fp
</span> <span class=
"c">/* [IN] File object */
</span>
31 <div class=
"para arg">
35 <dd>Pointer to the open file object.
</dd>
37 <dd>Byte offset from top of the file to set read/write pointer. The data type
<tt>FSIZE_t
</tt> is an alias of either
<tt>DWORD
</tt>(
32-bit) or
<tt>QWORD
</tt>(
64-bit) depends on the configuration option
<tt><a href=
"config.html#fs_exfat">FF_FS_EXFAT
</a></tt>.
</dd>
42 <div class=
"para ret">
43 <h4>Return Values
</h4>
45 <a href=
"rc.html#ok">FR_OK
</a>,
46 <a href=
"rc.html#de">FR_DISK_ERR
</a>,
47 <a href=
"rc.html#ie">FR_INT_ERR
</a>,
48 <a href=
"rc.html#io">FR_INVALID_OBJECT
</a>,
49 <a href=
"rc.html#tm">FR_TIMEOUT
</a>
54 <div class=
"para desc">
56 <p>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
<tt>f_lseek
</tt> function moves the file read/write pointer without any read/write operation to the file. The
<tt>f_rewind
</tt> function is impremented as a macro.
</p>
58 #define
<em>f_rewind
</em>(fp) f_lseek((fp),
0)
60 <p>If an offset beyond the file size is specified in write mode, the file size is expanded to the specified offset. The file data in the expanded part is
<em>undefined
</em>, because no data is written to the file in this process. This is suitable to pre-allocate a data area to the file quickly for fast write operation. When a contiguous data area needs to be allocated to the file, use
<tt>f_expand
</tt> function instead. After the
<tt>f_lseek
</tt> 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.
</p>
62 <li>End of file. The specified
<tt class=
"arg">ofs
</tt> was clipped at end of the file in read-only mode.
</li>
63 <li>Disk full. There is no free space on the volume to expand the file.
</li>
65 <p>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
<tt>f_read
</tt> and
<tt>f_write
</tt> function as well, however, the file size cannot be expanded by
<tt>f_write
</tt>,
<tt>f_lseek
</tt> function while the file is at fast seek mode.
</p>
66 <p>The fast seek mode is available when
<tt>FF_USE_FASTSEEK =
1</tt>. The CLMT must be created into the
<tt>DWORD
</tt> array prior to use the fast seek mode. To create the CLMT, set address of the
<tt>DWORD
</tt> array to the member
<tt>cltbl
</tt> in the open file object, set the size of array in unit of items to the
<tt>cltbl[
0]
</tt> and then call
<tt>f_lseek
</tt> function with
<tt class=
"arg">ofs
</tt><tt> = CREATE_LINKMAP
</tt>. After the function succeeded, no FAT access is occured in subsequent
<tt>f_read
</tt>,
<tt>f_write
</tt>,
<tt>f_lseek
</tt> function to the file. The number of items used or required is returned into the
<tt>cltbl[
0]
</tt>. 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
<tt>FR_NOT_ENOUGH_CORE
</tt>, the size of given array is insufficient for the file.
</p>
70 <div class=
"para comp">
72 <p>Available when
<tt><a href=
"config.html#fs_minimize">FF_FS_MINIMIZE
</a> <=
2</tt>. To use fast seek function,
<tt><a href=
"config.html#use_fastseek">FF_USE_FASTSEEK
</a></tt> needs to be set
1 to enable this feature.
</p>
76 <div class=
"para use">
79 <span class=
"c">/* Open file */
</span>
80 fp = malloc(sizeof (FIL));
81 res = f_open(fp,
"file.dat", FA_READ|FA_WRITE);
84 <span class=
"c">/* Set read/write pointer to
5000 */
</span>
85 res =
<em>f_lseek
</em>(fp,
5000);
87 <span class=
"c">/* Set read/write pointer to end of the file to append data */
</span>
88 res =
<em>f_lseek
</em>(fp, f_size(fp));
90 <span class=
"c">/* Advance read/write pointer
3000 bytes */
</span>
91 res =
<em>f_lseek
</em>(fp, f_tell(fp) +
3000);
93 <span class=
"c">/* Rewind read/write pointer
2000 bytes (take care on wraparound) */
</span>
94 res =
<em>f_lseek
</em>(fp, f_tell(fp) -
2000);
97 <span class=
"c">/* Cluster pre-allocation (to prevent buffer overrun on streaming write) */
</span>
99 res = f_open(fp, recfile, FA_CREATE_NEW | FA_WRITE);
<span class=
"c">/* Create a file */
</span>
101 res =
<em>f_lseek
</em>(fp, PRE_SIZE);
<span class=
"c">/* Expand file size (cluster pre-allocation) */
</span>
102 if (res || f_tell(fp) != PRE_SIZE) ...
<span class=
"c">/* Check if the file has been expanded successfly */
</span>
104 res =
<em>f_lseek
</em>(fp, OFS_DATA);
<span class=
"c">/* Record data stream with free from cluster allocation delay */
</span>
105 ...
<span class=
"c">/* Write operation should be aligned to sector boundary to optimize the write throughput */
</span>
107 res = f_truncate(fp);
<span class=
"c">/* Truncate unused area */
</span>
108 res =
<em>f_lseek
</em>(fp, OFS_HEADER);
<span class=
"c">/* Set file header */
</span>
114 <span class=
"c">/* Using fast seek mode */
</span>
116 DWORD clmt[SZ_TBL];
<span class=
"c">/* Cluster link map table buffer */
</span>
118 res = f_open(fp, fname, FA_READ | FA_WRITE);
<span class=
"c">/* Open a file */
</span>
120 res =
<em>f_lseek
</em>(fp, ofs1);
<span class=
"c">/* This is normal seek (cltbl is nulled on file open) */
</span>
122 fp-
>cltbl = clmt;
<span class=
"c">/* Enable fast seek mode (cltbl != NULL) */
</span>
123 clmt[
0] = SZ_TBL;
<span class=
"c">/* Set table size */
</span>
124 res =
<em>f_lseek
</em>(fp, CREATE_LINKMAP);
<span class=
"c">/* Create CLMT */
</span>
127 res =
<em>f_lseek
</em>(fp, ofs2);
<span class=
"c">/* This is fast seek */
</span>
132 <div class=
"para ref">
134 <p><tt><a href=
"open.html">f_open
</a>,
<a href=
"truncate.html">f_truncate
</a>,
<a href=
"expand.html">f_expand
</a>,
<a href=
"sfile.html">FIL
</a></tt></p>
137 <p class=
"foot"><a href=
"../00index_e.html">Return
</a></p>