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