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