1e6865dcdSopenharmony_ci<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2e6865dcdSopenharmony_ci<html lang="en">
3e6865dcdSopenharmony_ci<head>
4e6865dcdSopenharmony_ci<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
5e6865dcdSopenharmony_ci<meta http-equiv="Content-Style-Type" content="text/css">
6e6865dcdSopenharmony_ci<link rel="up" title="FatFs" href="../00index_e.html">
7e6865dcdSopenharmony_ci<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/lseek.html">
8e6865dcdSopenharmony_ci<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">
9e6865dcdSopenharmony_ci<title>FatFs - f_lseek</title>
10e6865dcdSopenharmony_ci</head>
11e6865dcdSopenharmony_ci
12e6865dcdSopenharmony_ci<body>
13e6865dcdSopenharmony_ci
14e6865dcdSopenharmony_ci<div class="para func">
15e6865dcdSopenharmony_ci<h2>f_lseek</h2>
16e6865dcdSopenharmony_ci<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>
17e6865dcdSopenharmony_ci
18e6865dcdSopenharmony_ci<pre>
19e6865dcdSopenharmony_ciFRESULT f_lseek (
20e6865dcdSopenharmony_ci  FIL*    <span class="arg">fp</span>,  <span class="c">/* [IN] File object */</span>
21e6865dcdSopenharmony_ci  FSIZE_t <span class="arg">ofs</span>  <span class="c">/* [IN] Offset of file read/write pointer to be set */</span>
22e6865dcdSopenharmony_ci);
23e6865dcdSopenharmony_ci</pre>
24e6865dcdSopenharmony_ci<pre>
25e6865dcdSopenharmony_ciFRESULT f_rewind (
26e6865dcdSopenharmony_ci  FIL*    <span class="arg">fp</span>   <span class="c">/* [IN] File object */</span>
27e6865dcdSopenharmony_ci);
28e6865dcdSopenharmony_ci</pre>
29e6865dcdSopenharmony_ci</div>
30e6865dcdSopenharmony_ci
31e6865dcdSopenharmony_ci<div class="para arg">
32e6865dcdSopenharmony_ci<h4>Parameters</h4>
33e6865dcdSopenharmony_ci<dl class="par">
34e6865dcdSopenharmony_ci<dt>fp</dt>
35e6865dcdSopenharmony_ci<dd>Pointer to the open file object.</dd>
36e6865dcdSopenharmony_ci<dt>ofs</dt>
37e6865dcdSopenharmony_ci<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>
38e6865dcdSopenharmony_ci</dl>
39e6865dcdSopenharmony_ci</div>
40e6865dcdSopenharmony_ci
41e6865dcdSopenharmony_ci
42e6865dcdSopenharmony_ci<div class="para ret">
43e6865dcdSopenharmony_ci<h4>Return Values</h4>
44e6865dcdSopenharmony_ci<p>
45e6865dcdSopenharmony_ci<a href="rc.html#ok">FR_OK</a>,
46e6865dcdSopenharmony_ci<a href="rc.html#de">FR_DISK_ERR</a>,
47e6865dcdSopenharmony_ci<a href="rc.html#ie">FR_INT_ERR</a>,
48e6865dcdSopenharmony_ci<a href="rc.html#io">FR_INVALID_OBJECT</a>,
49e6865dcdSopenharmony_ci<a href="rc.html#tm">FR_TIMEOUT</a>
50e6865dcdSopenharmony_ci</p>
51e6865dcdSopenharmony_ci</div>
52e6865dcdSopenharmony_ci
53e6865dcdSopenharmony_ci
54e6865dcdSopenharmony_ci<div class="para desc">
55e6865dcdSopenharmony_ci<h4>Description</h4>
56e6865dcdSopenharmony_ci<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>
57e6865dcdSopenharmony_ci<pre>
58e6865dcdSopenharmony_ci#define <em>f_rewind</em>(fp) f_lseek((fp), 0)
59e6865dcdSopenharmony_ci</pre>
60e6865dcdSopenharmony_ci<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>
61e6865dcdSopenharmony_ci<ul>
62e6865dcdSopenharmony_ci<li>End of file. The specified <tt class="arg">ofs</tt> was clipped at end of the file in read-only mode.</li>
63e6865dcdSopenharmony_ci<li>Disk full. There is no free space on the volume to expand the file.</li>
64e6865dcdSopenharmony_ci</ul>
65e6865dcdSopenharmony_ci<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>
66e6865dcdSopenharmony_ci<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>
67e6865dcdSopenharmony_ci</div>
68e6865dcdSopenharmony_ci
69e6865dcdSopenharmony_ci
70e6865dcdSopenharmony_ci<div class="para comp">
71e6865dcdSopenharmony_ci<h4>QuickInfo</h4>
72e6865dcdSopenharmony_ci<p>Available when <tt><a href="config.html#fs_minimize">FF_FS_MINIMIZE</a> &lt;= 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>
73e6865dcdSopenharmony_ci</div>
74e6865dcdSopenharmony_ci
75e6865dcdSopenharmony_ci
76e6865dcdSopenharmony_ci<div class="para use">
77e6865dcdSopenharmony_ci<h4>Example</h4>
78e6865dcdSopenharmony_ci<pre>
79e6865dcdSopenharmony_ci    <span class="c">/* Open file */</span>
80e6865dcdSopenharmony_ci    fp = malloc(sizeof (FIL));
81e6865dcdSopenharmony_ci    res = f_open(fp, "file.dat", FA_READ|FA_WRITE);
82e6865dcdSopenharmony_ci    if (res) ...
83e6865dcdSopenharmony_ci
84e6865dcdSopenharmony_ci    <span class="c">/* Set read/write pointer to 5000 */</span>
85e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, 5000);
86e6865dcdSopenharmony_ci
87e6865dcdSopenharmony_ci    <span class="c">/* Set read/write pointer to end of the file to append data */</span>
88e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, f_size(fp));
89e6865dcdSopenharmony_ci
90e6865dcdSopenharmony_ci    <span class="c">/* Advance read/write pointer 3000 bytes */</span>
91e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, f_tell(fp) + 3000);
92e6865dcdSopenharmony_ci
93e6865dcdSopenharmony_ci    <span class="c">/* Rewind read/write pointer 2000 bytes (take care on wraparound) */</span>
94e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, f_tell(fp) - 2000);
95e6865dcdSopenharmony_ci</pre>
96e6865dcdSopenharmony_ci<pre>
97e6865dcdSopenharmony_ci<span class="c">/* Cluster pre-allocation (to prevent buffer overrun on streaming write) */</span>
98e6865dcdSopenharmony_ci
99e6865dcdSopenharmony_ci    res = f_open(fp, recfile, FA_CREATE_NEW | FA_WRITE);   <span class="c">/* Create a file */</span>
100e6865dcdSopenharmony_ci
101e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, PRE_SIZE);             <span class="c">/* Expand file size (cluster pre-allocation) */</span>
102e6865dcdSopenharmony_ci    if (res || f_tell(fp) != PRE_SIZE) ...   <span class="c">/* Check if the file has been expanded successfly */</span>
103e6865dcdSopenharmony_ci
104e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, OFS_DATA);             <span class="c">/* Record data stream with free from cluster allocation delay */</span>
105e6865dcdSopenharmony_ci    ...                                      <span class="c">/* Write operation should be aligned to sector boundary to optimize the write throughput */</span>
106e6865dcdSopenharmony_ci
107e6865dcdSopenharmony_ci    res = f_truncate(fp);                    <span class="c">/* Truncate unused area */</span>
108e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, OFS_HEADER);           <span class="c">/* Set file header */</span>
109e6865dcdSopenharmony_ci    ...
110e6865dcdSopenharmony_ci
111e6865dcdSopenharmony_ci    res = f_close(fp);
112e6865dcdSopenharmony_ci</pre>
113e6865dcdSopenharmony_ci<pre>
114e6865dcdSopenharmony_ci<span class="c">/* Using fast seek mode */</span>
115e6865dcdSopenharmony_ci
116e6865dcdSopenharmony_ci    DWORD clmt[SZ_TBL];                    <span class="c">/* Cluster link map table buffer */</span>
117e6865dcdSopenharmony_ci
118e6865dcdSopenharmony_ci    res = f_open(fp, fname, FA_READ | FA_WRITE);   <span class="c">/* Open a file */</span>
119e6865dcdSopenharmony_ci
120e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, ofs1);               <span class="c">/* This is normal seek (cltbl is nulled on file open) */</span>
121e6865dcdSopenharmony_ci
122e6865dcdSopenharmony_ci    fp-&gt;cltbl = clmt;                      <span class="c">/* Enable fast seek mode (cltbl != NULL) */</span>
123e6865dcdSopenharmony_ci    clmt[0] = SZ_TBL;                      <span class="c">/* Set table size */</span>
124e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, CREATE_LINKMAP);     <span class="c">/* Create CLMT */</span>
125e6865dcdSopenharmony_ci    ...
126e6865dcdSopenharmony_ci
127e6865dcdSopenharmony_ci    res = <em>f_lseek</em>(fp, ofs2);               <span class="c">/* This is fast seek */</span>
128e6865dcdSopenharmony_ci</pre>
129e6865dcdSopenharmony_ci</div>
130e6865dcdSopenharmony_ci
131e6865dcdSopenharmony_ci
132e6865dcdSopenharmony_ci<div class="para ref">
133e6865dcdSopenharmony_ci<h4>See Also</h4>
134e6865dcdSopenharmony_ci<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>
135e6865dcdSopenharmony_ci</div>
136e6865dcdSopenharmony_ci
137e6865dcdSopenharmony_ci<p class="foot"><a href="../00index_e.html">Return</a></p>
138e6865dcdSopenharmony_ci</body>
139e6865dcdSopenharmony_ci</html>
140