[z180-stamp.git] / fatfs / documents / doc / lseek.html

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