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_expand</title> 10e6865dcdSopenharmony_ci</head> 11e6865dcdSopenharmony_ci 12e6865dcdSopenharmony_ci<body> 13e6865dcdSopenharmony_ci 14e6865dcdSopenharmony_ci<div class="para func"> 15e6865dcdSopenharmony_ci<h2>f_expand</h2> 16e6865dcdSopenharmony_ci<p>The f_expand function prepares or allocates a contiguous data area to the file.</p> 17e6865dcdSopenharmony_ci 18e6865dcdSopenharmony_ci<pre> 19e6865dcdSopenharmony_ciFRESULT f_expand ( 20e6865dcdSopenharmony_ci FIL* <span class="arg">fp</span>, <span class="c">/* [IN] File object */</span> 21e6865dcdSopenharmony_ci FSIZE_t <span class="arg">fsz</span>, <span class="c">/* [IN] File size expanded to */</span> 22e6865dcdSopenharmony_ci BYTE <span class="arg">opt</span> <span class="c">/* [IN] Allocation mode */</span> 23e6865dcdSopenharmony_ci); 24e6865dcdSopenharmony_ci</pre> 25e6865dcdSopenharmony_ci</div> 26e6865dcdSopenharmony_ci 27e6865dcdSopenharmony_ci<div class="para arg"> 28e6865dcdSopenharmony_ci<h4>Parameters</h4> 29e6865dcdSopenharmony_ci<dl class="par"> 30e6865dcdSopenharmony_ci<dt>fp</dt> 31e6865dcdSopenharmony_ci<dd>Pointer to the open file object.</dd> 32e6865dcdSopenharmony_ci<dt>fsz</dt> 33e6865dcdSopenharmony_ci<dd>Number of bytes in size to prepare or allocate for the file. 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>FF_FS_EXFAT</tt>.</dd> 34e6865dcdSopenharmony_ci<dt>opt</dt> 35e6865dcdSopenharmony_ci<dd>Allocation mode. Prepare to allocate (0) or Allocate now (1).</dd> 36e6865dcdSopenharmony_ci</dl> 37e6865dcdSopenharmony_ci</div> 38e6865dcdSopenharmony_ci 39e6865dcdSopenharmony_ci 40e6865dcdSopenharmony_ci<div class="para ret"> 41e6865dcdSopenharmony_ci<h4>Return Values</h4> 42e6865dcdSopenharmony_ci<p> 43e6865dcdSopenharmony_ci<a href="rc.html#ok">FR_OK</a>, 44e6865dcdSopenharmony_ci<a href="rc.html#de">FR_DISK_ERR</a>, 45e6865dcdSopenharmony_ci<a href="rc.html#ie">FR_INT_ERR</a>, 46e6865dcdSopenharmony_ci<a href="rc.html#io">FR_INVALID_OBJECT</a>, 47e6865dcdSopenharmony_ci<a href="rc.html#dn">FR_DENIED</a>, 48e6865dcdSopenharmony_ci<a href="rc.html#tm">FR_TIMEOUT</a> 49e6865dcdSopenharmony_ci</p> 50e6865dcdSopenharmony_ci</div> 51e6865dcdSopenharmony_ci 52e6865dcdSopenharmony_ci 53e6865dcdSopenharmony_ci<div class="para desc"> 54e6865dcdSopenharmony_ci<h4>Description</h4> 55e6865dcdSopenharmony_ci<p>The <tt>f_expand</tt> function prepares or allocates a contiguous data area to the file. When <tt class="arg">opt</tt> is 1, the data area is allocated to the file in this function. Unlike expansion of file size by <tt>f_lseek</tt> function, the file must be truncated prior to use this function and read/write pointer of the file stays at offset 0 after the function call. The file content allocated with this function is <em>undefined</em>, because no data is written to the file in this process. The function can fail with <tt>FR_DENIED</tt> due to some reasons below.</p> 56e6865dcdSopenharmony_ci<ul> 57e6865dcdSopenharmony_ci<li>No free contiguous space was found.</li> 58e6865dcdSopenharmony_ci<li>Size of the file was not zero.</li> 59e6865dcdSopenharmony_ci<li>The file has been opened in read-only mode.</li> 60e6865dcdSopenharmony_ci<li>Not allowable file size. (>= 4 GB on FAT volume)</li> 61e6865dcdSopenharmony_ci</ul> 62e6865dcdSopenharmony_ci<p>When <tt class="arg">opt</tt> is 0, the function finds a contiguous data area and set it as suggested point for next allocation. The subsequent cluster allocation begins at top of the contiguous area found by this function. Thus the file allocation is guaranteed be contiguous and without allocation delay until the file size reaches this size unless any other changes to the volume is performed.</p> 63e6865dcdSopenharmony_ci<p>The contiguous file has an advantage for time-critical read/write operations. It eliminates some overheads in the filesystem and the storage device caused by random access for fragmented file.</p> 64e6865dcdSopenharmony_ci<p>Also the contiguous file can be easily accessed directly via low-level disk functions. However, this is not recommended in consideration of portability and future compatibility. If the file has not been confirmed be contiguous, use <a href="../res/app5.c">this function</a> to examine if the file is contiguous or not.</p> 65e6865dcdSopenharmony_ci</div> 66e6865dcdSopenharmony_ci 67e6865dcdSopenharmony_ci<div class="para comp"> 68e6865dcdSopenharmony_ci<h4>QuickInfo</h4> 69e6865dcdSopenharmony_ci<p>Available when <tt>FF_USE_EXPAND == 1</tt> and <tt>FF_FS_READONLY == 0</tt>.</p> 70e6865dcdSopenharmony_ci</div> 71e6865dcdSopenharmony_ci 72e6865dcdSopenharmony_ci 73e6865dcdSopenharmony_ci<div class="para use"> 74e6865dcdSopenharmony_ci<h4>Example</h4> 75e6865dcdSopenharmony_ci<pre> 76e6865dcdSopenharmony_ci <span class="c">/* Creating a contiguous file */</span> 77e6865dcdSopenharmony_ci 78e6865dcdSopenharmony_ci <span class="c">/* Create a new file */</span> 79e6865dcdSopenharmony_ci res = f_open(fp = malloc(sizeof (FIL)), "file.dat", FA_WRITE|FA_CREATE_ALWAYS); 80e6865dcdSopenharmony_ci if (res) { <span class="c">/* Check if the file has been opened */</span> 81e6865dcdSopenharmony_ci free(fp); 82e6865dcdSopenharmony_ci die("Failed to open the file."); 83e6865dcdSopenharmony_ci } 84e6865dcdSopenharmony_ci 85e6865dcdSopenharmony_ci <span class="c">/* Alloacte a 100 MiB of contiguous area to the file */</span> 86e6865dcdSopenharmony_ci res = <em>f_expand</em>(fp, 104857600, 1); 87e6865dcdSopenharmony_ci if (res) { <span class="c">/* Check if the file has been expanded */</span> 88e6865dcdSopenharmony_ci f_close(fp); 89e6865dcdSopenharmony_ci free(fp); 90e6865dcdSopenharmony_ci die("Failed to allocate contiguous area."); 91e6865dcdSopenharmony_ci } 92e6865dcdSopenharmony_ci 93e6865dcdSopenharmony_ci <span class="c">/* Now you have a contiguous file accessible with fp */</span> 94e6865dcdSopenharmony_ci 95e6865dcdSopenharmony_ci</pre> 96e6865dcdSopenharmony_ci<pre> 97e6865dcdSopenharmony_ci <span class="c">/* Accessing the contiguous file via low-level disk functions */</span> 98e6865dcdSopenharmony_ci 99e6865dcdSopenharmony_ci <span class="c">/* Get physical location of the file data */</span> 100e6865dcdSopenharmony_ci drv = fp->obj.fs->pdrv; 101e6865dcdSopenharmony_ci lba = fp->obj.fs->database + fp->obj.fs->csize * (fp->obj.sclust - 2); 102e6865dcdSopenharmony_ci 103e6865dcdSopenharmony_ci <span class="c">/* Write 2048 sectors from top of the file at a time */</span> 104e6865dcdSopenharmony_ci res = disk_write(drv, buffer, lba, 2048); 105e6865dcdSopenharmony_ci 106e6865dcdSopenharmony_ci</pre> 107e6865dcdSopenharmony_ci</div> 108e6865dcdSopenharmony_ci 109e6865dcdSopenharmony_ci 110e6865dcdSopenharmony_ci<div class="para ref"> 111e6865dcdSopenharmony_ci<h4>See Also</h4> 112e6865dcdSopenharmony_ci<p><tt><a href="open.html">f_open</a>, <a href="lseek.html">f_lseek</a>, <a href="sfile.html">FIL</a></tt></p> 113e6865dcdSopenharmony_ci</div> 114e6865dcdSopenharmony_ci 115e6865dcdSopenharmony_ci<p class="foot"><a href="../00index_e.html">Return</a></p> 116e6865dcdSopenharmony_ci</body> 117e6865dcdSopenharmony_ci</html> 118