Github/fatfs
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

FatFS R0.10b, released May 19, 2014

Browse Source
This commit is contained in:
Christopher Williams
2015-01-31 09:24:04 -07:00
parent 935031e4e5
commit 762b341574
75 changed files with 812 additions and 704 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/en/appnote.html
+33 -30
View File
@@ -23,7 +23,7 @@
<li><a href="#fs1">Performance Effective File Access</a></li>
<li><a href="#fs2">Considerations on Flash Memory Media</a></li>
<li><a href="#critical">Critical Section</a></li>
<li><a href="#fs3">Extended Use of APIs</a></li>
<li><a href="#fs3">Extended Use of FatFs API</a></li>
<li><a href="#license">About FatFs License</a></li>
</ol>
<hr>
@@ -43,17 +43,19 @@ The FatFs module assumes that size of char/short/long are 8/16/32 bit and int is
<h4>System organizations</h4>
<p>The dependency diagram shown below is a typical configuration of the embedded system with FatFs module.</p>
<p><img src="../img/modules.png" width="580" height="280" alt="dependency diagram"></p>
<p>(a) If a working disk module with FatFs API is provided, no additional function is needed. (b) To attach existing disk drivers with different API, glue functions are needed to translate the APIs between FatFs and the drivers.</p>
<p><img src="../img/funcs.png" width="680" height="430" alt="functional diagram"></p>
<h4>Which function is required?</h4>
<p>You need to provide only low level disk I/O functions that required by FatFs module and nothing else. If a working disk module for the target is already existing, you need to write only glue functions to attach it to the FatFs module. If not, you need to port any other disk module or write it from scratch. Most of defined functions are not that always required. For example, disk write function is not required in read-only configuration. Following table shows which function is required depends on configuration options.</p>
<table class="lst2">
<tr><th>Function</th><th>Required when:</th><th>Note</th></tr>
<tr><td>disk_initialize<br>disk_status<br>disk_read</td><td>Always</td><td rowspan="5">Disk I/O functions.<br>Samples available in ffsample.zip.<br>There are many implementations on the web.</td></tr>
<tr><td>disk_status<br>disk_initialize<br>disk_read</td><td>Always</td><td rowspan="5">Disk I/O functions.<br>Samples available in ffsample.zip.<br>There are many implementations on the web.</td></tr>
<tr><td>disk_write<br>get_fattime<br>disk_ioctl (CTRL_SYNC)</td><td>_FS_READONLY == 0</td></tr>
<tr><td>disk_ioctl (GET_SECTOR_COUNT)<br>disk_ioctl (GET_BLOCK_SIZE)</td><td>_USE_MKFS == 1</td></tr>
<tr><td>disk_ioctl (GET_SECTOR_SIZE)</td><td>_MAX_SS != _MIN_SS</td></tr>
<tr><td>disk_ioctl (CTRL_ERASE_SECTOR)</td><td>_USE_ERASE == 1</td></tr>
<tr><td>ff_convert<br>ff_wtoupper</td><td>_USE_LFN &gt;= 1</td><td>Unicode support functions.<br>Available in option/cc*.c.</td></tr>
<tr><td>disk_ioctl (CTRL_TRIM)</td><td>_USE_TRIM == 1</td></tr>
<tr><td>ff_convert<br>ff_wtoupper</td><td>_USE_LFN &gt;= 1</td><td>Unicode support functions.<br>Available in option/unicode.c.</td></tr>
<tr><td>ff_cre_syncobj<br>ff_del_syncobj<br>ff_req_grant<br>ff_rel_grant</td><td>_FS_REENTRANT == 1</td><td rowspan="2">O/S dependent functions.<br>Samples available in option/syscall.c.</td></tr>
<tr><td>ff_mem_alloc<br>ff_mem_free</td><td>_USE_LFN == 3</td></tr>
</table>
@@ -65,10 +67,10 @@ The FatFs module assumes that size of char/short/long are 8/16/32 bit and int is
<li>FAT sub-types: FAT12, FAT16 and FAT32.</li>
<li>Number of open files: Unlimited, depends on available memory.</li>
<li>Number of volumes: Upto 10.</li>
<li>File size: Depends on FAT specs. (upto 4G-1 bytes)</li>
<li>Volume size: Depends on FAT specs. (upto 2T bytes at 512 bytes/sector)</li>
<li>Cluster size: Depends on FAT specs. (upto 64K bytes at 512 bytes/sector)</li>
<li>Sector size: Depends on FAT specs. (512..4096 bytes)</li>
<li>File size: Depends on the FAT specs. (upto 4G-1 bytes)</li>
<li>Volume size: Depends on the FAT specs. (upto 2T bytes at 512 bytes/sector)</li>
<li>Cluster size: Depends on the FAT specs. (upto 64K bytes at 512 bytes/sector)</li>
<li>Sector size: Depends on the FAT specs. (512, 1024, 2048 and 4096 bytes)</li>
</ul>
</div>
@@ -149,7 +151,7 @@ _FS_LOCK 0 (Disable file lock control)
<div class="para" id="lfn">
<h3>Long File Name</h3>
<p>The FatFs module has started to support long file name (LFN) at revision 0.07. The two different file names, SFN and LFN, of a file is transparent in the file functions except for f_readdir function. To enable LFN feature, set <tt>_USE_LFN</tt> to 1, 2 or 3, and add a Unicode code conversion function <tt>ff_convert()</tt> and <tt>ff_wtoupper()</tt> to the project. The LFN feature requiers a certain working buffer in addition. The buffer size can be configured by <tt>_MAX_LFN</tt> corresponding to the available memory size. The size of long file name will reach up to 255 characters, so that the <tt>_MAX_LFN</tt> should be set to 255 for full featured LFN operation. If the size of working buffer is insufficient for the given file name, the file function fails with <tt>FR_INVALID_NAME</tt>. When enable the LFN feature with re-entrant feature, <tt>_USE_LFN</tt> must be set to 2 or 3. In this case, the file function allocates the working buffer on the stack or heap. The working buffer occupies <tt>(_MAX_LFN + 1) * 2</tt> bytes.</p>
<p>FatFs module supports LFN (long file name). The two different file names, SFN (short file name) and LFN, of a file is transparent on the API except for <tt>f_readdir()</tt> function. The LFN feature is disabled by default. To enable it, set <tt>_USE_LFN</tt> to 1, 2 or 3, and add <tt>option/unicode.c</tt> to the project. The LFN feature requiers a certain working buffer in addition. The buffer size can be configured by <tt>_MAX_LFN</tt> according to the available memory. The length of an LFN will reach up to 255 characters, so that the <tt>_MAX_LFN</tt> should be set to 255 for full featured LFN operation. If the size of working buffer is insufficient for the input file name, the file function fails with <tt>FR_INVALID_NAME</tt>. When enable the LFN feature with re-entrant configuration, <tt>_USE_LFN</tt> must be set to 2 or 3. In this case, the file function allocates the working buffer on the stack or heap. The working buffer occupies <tt>(_MAX_LFN + 1) * 2</tt> bytes.</p>
<table class="lst2 rset">
<caption>LFN cfg on ARM7TDMI</caption>
<tr><th>Code page</th><th>Program size</th></tr>
@@ -165,56 +167,56 @@ _FS_LOCK 0 (Disable file lock control)
<div class="para" id="unicode">
<h3>Unicode API</h3>
<p>By default, FatFs uses ANSI/OEM code set on the API under LFN configuration. FatFs can also switch the character encoding to Unicode on the API (<tt>_LFN_UNICODE</tt>). This means the FatFs supports the True-LFN feature. For more information, refer to the description in the <a href="filename.html">file name</a>.</p>
<p>By default, FatFs uses ANSI/OEM code set on the API under LFN configuration. FatFs can also switch the character encoding to Unicode on the API by <tt>_LFN_UNICODE</tt> option. This means that the FatFs supports the True-LFN feature. For more information, refer to the description in the <a href="filename.html">file name</a>.</p>
</div>
<div class="para" id="reentrant">
<h3>Re-entrancy</h3>
<p>The file operations to the different volume is always re-entrant and can work simultaneously. The file operations to the same volume is not re-entrant but it can also be configured to thread-safe with <tt>_FS_REENTRANT</tt> option. In this case, also the OS dependent synchronization object control functions, <tt>ff_cre_syncobj(), ff_del_syncobj(), ff_req_grant() and ff_rel_grant()</tt> must be added to the project.</p>
<p>When a file function is called while the volume is in use by any other task, the file function is suspended until that task leaves file function. If wait time exceeded a period defined by <tt>_TIMEOUT</tt>, the file function will abort with <tt>FR_TIMEOUT</tt>. The timeout feature might not be supported by some RTOS.</p>
<p>The file operations to the different volume is always re-entrant and can work simultaneously. The file operations to the same volume is not re-entrant but it can also be configured to thread-safe by <tt>_FS_REENTRANT</tt> option. In this case, also the OS dependent synchronization object control functions, <tt>ff_cre_syncobj(), ff_del_syncobj(), ff_req_grant() and ff_rel_grant()</tt> must be added to the project. There are some examples in the <tt>option/syscall.c</tt>.</p>
<p>When a file function is called while the volume is in use by any other task, the file function is suspended until that task leaves the file function. If wait time exceeded a period defined by <tt>_TIMEOUT</tt>, the file function will abort with <tt>FR_TIMEOUT</tt>. The timeout feature might not be supported by some RTOS.</p>
<p>There is an exception for <tt>f_mount(), f_mkfs(), f_fdisk()</tt> function. These functions are not re-entrant to the same volume or corresponding physical drive. When use these functions, all other tasks must unmount the volume and avoid to access the volume.</p>
<p>Note that this section describes on the re-entrancy of the FatFs module itself but also the low level disk I/O layer will need to be re-entrant.</p>
</div>
<div class="para" id="dup">
<h3>Duplicated File Access</h3>
<p>FatFs module does not support the read/write collision control of duplicated open to a file. The duplicated open is permitted only when each of open method to a file is read mode. The duplicated open with one or more write mode to a file is always prohibited, and also open file must not be renamed and deleted. A violation of these rules can cause data corruption.</p>
<p>The file lock control can also be available by <tt>_FS_LOCK</tt> option. The value defines the number of open objects to manage simultaneously. In this case, if any open, rename or remove that violating the file shareing rule that described above is attempted, the file function will fail with <tt>FR_LOCKED</tt>. If number of open objects gets larger than <tt>_FS_LOCK</tt>, the open function will fail with <tt>FR_TOO_MANY_OPEN_FILES</tt>.</p>
<p>FatFs module does not support the read/write collision control of duplicated open to a file. The duplicated open is permitted only when each of open method to a file is read mode. The duplicated open with one or more write mode to a file is always prohibited, and also open file must not be renamed and deleted. A violation of these rules can cause data colluption.</p>
<p>The file lock control can be enabled by <tt>_FS_LOCK</tt> option. The value of option defines the number of open objects to manage simultaneously. In this case, if any open, rename or remove that violating the file shareing rule that described above is attempted, the file function will fail with <tt>FR_LOCKED</tt>. If number of open objects, files and sub-directories, is equal to <tt>_FS_LOCK</tt>, an extra <tt>f_open(), f_optndir()</tt> function will fail with <tt>FR_TOO_MANY_OPEN_FILES</tt>.</p>
</div>
<div class="para" id="fs1">
<h3>Performance Effective File Access</h3>
<p>For good performance to read/write files on the small embedded system, application programmer should consider what process is done in the FatFs module. The file data on the volume is transferred in following sequence by <tt>f_read()</tt> function.</p>
<p>Figure 1. Sector miss-aligned read (short)<br>
<p>For good read/write throughput on the small embedded systems with limited size of memory, application programmer should consider what process is done in the FatFs module. The file data on the volume is transferred in following sequence by <tt>f_read()</tt> function.</p>
<p>Figure 1. Sector misaligned read (short)<br>
<img src="../img/f1.png" width="490" height="110" alt="">
</p>
<p>Figure 2. Sector miss-aligned read (long)<br>
<p>Figure 2. Sector misaligned read (long)<br>
<img src="../img/f2.png" width="490" height="140" alt="">
</p>
<p>Figure 3. Sector aligned read<br>
<p>Figure 3. Fully sector aligned read<br>
<img src="../img/f3.png" width="490" height="119" alt="">
</p>
<p>The file I/O buffer is a sector buffer to read/write a partial data on the sector. The sector buffer is either file private sector buffer on each file object or shared sector buffer in the file system object. The buffer configuration option <tt>_FS_TINY</tt> determins which sector buffer is used for the file data transfer. When tiny buffer (1) is selected, data memory consumption is reduced 512 bytes each file object. In this case, FatFs module uses only a sector buffer in the file system object for file data transfer and FAT/directory access. The disadvantage of the tiny buffer configuration is: the FAT data cached in the sector buffer will be lost by file data transfer and it must be reloaded at every cluster boundary. However it will be suitable for most application from view point of the decent performance and low memory comsumption.</p>
<p>Figure 1 shows that a partial sector, sector mis-aligned part of the file, is transferred via the file I/O buffer. On long data transfer shown in Figure 2, middle of transfer data that covers one or more sector is transferred to the application buffer directly. Figure 3 shows that the case of entier transfer data is aligned to the sector boundary. In this case, file I/O buffer is not used. On the direct transfer, the maximum extent of sectors are read with <tt>disk_read()</tt> function at a time but the multiple sector transfer never across the cluster boundary even if it is contiguous.</p>
<p>Therefore taking effort to sector aligned read/write accesss avoids buffered data transfer and the read/write performance will be improved. Besides the effect, cached FAT data will not be flushed by file data transfer at the tiny configuration, so that it can achieve same performance as non-tiny configuration with small memory footprint.</p>
<p>The file I/O buffer is a sector buffer to read/write a partial data on the sector. The sector buffer is either file private sector buffer on each file object or shared sector buffer in the file system object. The buffer configuration option <tt>_FS_TINY</tt> determins which sector buffer is used for the file data transfer. When tiny buffer configuration (1) is selected, data memory consumption is reduced <tt>_MAX_SS</tt> bytes each file object. In this case, FatFs module uses only a sector buffer in the file system object for file data transfer and FAT/directory access. The disadvantage of the tiny buffer configuration is: the FAT data cached in the sector buffer will be lost by file data transfer and it must be reloaded at every cluster boundary. However it will be suitable for most application from view point of the decent performance and low memory comsumption.</p>
<p>Figure 1 shows that a partial sector, sector misaligned part of the file, is transferred via the file I/O buffer. At long data transfer shown in Figure 2, middle of transfer data that covers one or more sector is transferred to the application buffer directly. Figure 3 shows that the case of entier transfer data is aligned to the sector boundary. In this case, file I/O buffer is not used. On the direct transfer, the maximum extent of sectors are read with <tt>disk_read()</tt> function at a time but the multiple sector transfer is divided at cluster boundary even if it is contiguous.</p>
<p>Therefore taking effort to sector aligned read/write accesss eliminates buffered data transfer and the read/write performance will be improved. Besides the effect, cached FAT data will not be flushed by file data transfer at the tiny configuration, so that it can achieve same performance as non-tiny configuration with small memory footprint.</p>
</div>
<div class="para" id="fs2">
<h3>Considerations on Flash Memory Media</h3>
<p>To maximize the write performance of flash memory media, such as SDC and CFC, it must be controlled in consideration of its characteristitcs.</p>
<p>To maximize the write performance of flash memory media, such as SDC, CFC and U Disk, it must be controlled in consideration of its characteristitcs.</p>
<h4>Using Mutiple-Sector Write</h4>
<div class="rset">
Figure 6. Comparison between Multiple/Single Sector Write<br>
<img src="../img/f6.png" width="630" height="148" alt="fig.6">
</div>
<p>The write throughput of the flash memory media becomes the worst at single sector write and it increases proportional to the number of sectors per a write transaction. This effect more appers at more fast bus clock and its ratio often becomes grater than ten. The number of write transaction also affects the life time of the media. Therefore the application program should write the data in large block as possible. The ideal block size is cluster size or power of 2 bytes and the byte offset should be aligned to the block. Of course all layers between the application and the media must support multiple sector write feature, however most of open-source disk drivers lack it. Do not split a multiple sector write request into single sector writes or the write throughput gets poor. Note that FatFs module and its sample disk drivers supprt multiple sector read/write feature.</p>
<p>The write throughput of the flash memory media becomes the worst at single sector write transaction. The write throughput increases as the number of sectors per a write transaction. This effect more appers at faster interface speed and the performance ratio often becomes grater than ten. <a href="../img/rwtest2.png">This graph</a> is clearly explaining how fast is multiple block write (W:16K, 32 sectors) than single block write (W:100, 1 sector), and also larger card tends to be slow at single block write. The number of write transactions also affects the life time of the flash memory media. Therefore the application program should write the data in large block as possible. The ideal write chunk size and alighment is size of sector, and size of cluster is the best. Of course all layers between the application and the storage device must have consideration on multiple sector write, however most of open-source disk drivers lack it. Do not split a multiple sector write request into single sector write transactions or the write throughput gets poor. Note that FatFs module and its sample disk drivers supprt multiple sector read/write feature. </p>
<h4>Forcing Memory Erase</h4>
<p>When remove a file with <tt>f_remove()</tt> function, the data clusters occupied by the file are marked 'free' on the FAT. But the data sectors containing the file data are not that applied any process, so that the file data left occupies a part of the flash memory array as 'live block'. If the file data is forced erased on removing the file, the number of free blocks on the flash memory will be increased. This may skip internal block erase operation to the data block on next write. As the result the write performance might be improved. To enable this feature, set <tt>_USE_ERASE</tt> to 1. Note that this is a feature with expectation of internal process of the flash memory media. It may not always effective and <tt>f_remove()</tt> function will take a time to remove a large file. Most applications will not need this feature.</p>
<p>When remove a file with <tt>f_remove()</tt> function, the data clusters occupied by the file are marked 'free' on the FAT. But the data sectors containing the file data are not that applied any process, so that the file data left occupies a part of the flash memory array as 'live block'. If the file data is forced erased on removing the file, those data blocks will be turned in to the free block pool. This may skip internal block erase operation to the data block on next write operation. As the result the write performance might be improved. FatFs can manage this feature by setting <tt>_USE_ERASE</tt> to 1. Note that this is an expectation of internal process of the flash memory storage and not that always effective. Also <tt>f_remove()</tt> function will take a time when remove a large file. Most applications will not need this feature.</p>
</div>
<div class="para" id="critical">
<h3>Critical Section</h3>
<p>If a write operation to the FAT volume is interrupted due to any accidental failure, such as sudden blackout, incorrect disk removal and unrecoverable disk error, the FAT structure on the volume can be collapted. Following images shows the critical section of the FatFs module.</p>
<p>If a write operation to the FAT volume is interrupted due to any accidental failure, such as sudden blackout, incorrect disk removal and unrecoverable disk error, the FAT structure on the volume can be broken. Following images shows the critical section of the FatFs module.</p>
<div class="lset">
Figure 4. Long critical section<br>
<img src="../img/f4.png" width="320" height="436" alt="fig.4">
@@ -226,7 +228,7 @@ Figure 5. Minimized critical section<br>
<br class="clr">
<p>An interruption in the red section can cause a cross link; as a result, the object being changed can be lost. If an interruption in the yellow section is occured, there is one or more possibility listed below.</p>
<ul>
<li>The file data being rewrited is collapted.</li>
<li>The file data being rewrited is collapsed.</li>
<li>The file being appended returns initial state.</li>
<li>The file created as new is gone.</li>
<li>The file created as new or overwritten remains but no content.</li>
@@ -236,21 +238,22 @@ Figure 5. Minimized critical section<br>
</div>
<div class="para" id="fs3">
<h3>Extended Use of APIs</h3>
<h3>Extended Use of FatFs API</h3>
<p>These are examples of extended use of FatFs APIs. New item will be added whenever a useful code is found.</p>
<ol>
<li><a href="../img/app1.c">Open or create a file for append</a></li>
<li><a href="../img/app2.c">Empty a directory</a></li>
<li><a href="../img/app3.c">Allocate contiguous area to the file</a></li>
<li><a href="../img/app4.c">Function/Compatible checker for low level disk I/O module</a></li>
<li><a href="../img/mkfatimg.zip">FAT image creator</a></li>
</ol>
</div>
<div class="para" id="license">
<h3>About FatFs License</h3>
<p>This is a copy of the FatFs license document that included in the source codes.</p>
<p>FatFs has being developped as a personal project of author, ChaN. It is free from the code anyone else wrote. Following code block shows a copy of the FatFs license document that included in the source files.</p>
<pre>/*----------------------------------------------------------------------------/
/ FatFs - FAT file system module R0.10a (C)ChaN, 2014
/ FatFs - FAT file system module R0.10b (C)ChaN, 2014
/-----------------------------------------------------------------------------/
/ FatFs module is a generic FAT file system module for small embedded systems.
/ This is a free software that opened for education, research and commercial
@@ -264,7 +267,7 @@ Figure 5. Minimized critical section<br>
/ * Redistributions of source code must retain the above copyright notice.
/
/-----------------------------------------------------------------------------/</pre>
<p>Therefore FatFs license is one of the BSD-style licenses but there is a significant feature. Because FatFs is for embedded projects, the conditions of redistributions in binary form, such as embedded code, hex file and binary library, are not specified to increase its usability. The documentation of the distributions need not include about FatFs and its license document, and it may also. This is equivalent to the BSD 1-Clause License. Of course FatFs is compatible with the projects under GNU GPL. When redistribute the FatFs with any modification, the license can also be changed to GNU GPL or BSD-style license.</p>
<p>Therefore FatFs license is one of the BSD-style licenses but there is a significant feature. Because FatFs is for embedded projects, the conditions of redistributions in binary form, such as embedded code, hex file, binary library or any forms without source code, are not specified in order to extend usability for commercial products. The documentation of the distributions need not include about FatFs and its license document, and it may also. This is equivalent to the BSD 1-Clause License. Of course FatFs is compatible with the projects under GNU GPL. When redistribute the FatFs with any modification or branch it as a fork, the license can also be changed to GNU GPL, BSD-style license or any free software licenses that not conflict with FatFs license.</p>
</div>
<p class="foot"><a href="../00index_e.html">Return</a></p>
doc/en/close.html
+1 -1
View File
@@ -46,7 +46,7 @@ FRESULT f_close (
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_close()</tt> function closes an open file object. If any data has been written to the file, the cached information of the file is written back to the volume. After the function succeeded, the file object is no longer valid and it can be discarded.</p>
<p>Note that if the file object is in read-only mode and <tt>_FS_LOCK</tt> option is not enabled, the file object can also be discarded without this process. However it is not recommended for future compatibility.</p>
<p>Note that if the file object is in read-only mode and <tt>_FS_LOCK</tt> option is not enabled, the file object can also be discarded without this process. However this is not recommended for future compatibility.</p>
</div>
doc/en/closedir.html
+2 -2
View File
@@ -43,8 +43,8 @@ FRESULT f_closedir (
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_closedir()</tt> function closes an open directory object. After the function succeeded, the file object is no longer valid and it can be discarded.</p>
<p>Note that the directory object can also be discarded without this process unless <tt>_FS_LOCK</tt> option is not enabled. However it is not recommended for future compatibility.</p>
<p>The <tt>f_closedir()</tt> function closes an open directory object. After the function succeeded, the directory object is no longer valid and it can be discarded.</p>
<p>Note that the directory object can also be discarded without this process if <tt>_FS_LOCK</tt> option is not enabled. However this is not recommended for future compatibility.</p>
</div>
doc/en/dinit.html
+4 -4
View File
@@ -13,7 +13,7 @@
<div class="para func">
<h2>disk_initialize</h2>
<p>The disk_initialize function initializes the disk drive.</p>
<p>The disk_initialize function initializes the storage device.</p>
<pre>
DSTATUS disk_initialize (
BYTE <span class="arg">pdrv</span> <span class="c">/* [IN] Physical drive number */</span>
@@ -25,7 +25,7 @@ DSTATUS disk_initialize (
<h4>Parameter</h4>
<dl class="par">
<dt>pdrv</dt>
<dd>Specifies the physical drive number to initialize.</dd>
<dd>Physical drive number to identify the target device.</dd>
</dl>
</div>
@@ -37,8 +37,8 @@ DSTATUS disk_initialize (
<div class="para desc">
<h4>Description</h4>
<p>This function initializes a physical drive and put it ready to generic read/write data. When the function succeeded, <tt>STA_NOINIT</tt> flag in the return value is cleared.</p>
<p><em>Application program MUST NOT call this function while FatFs is in use, or FAT structure on the volume can be corrapted. To re-initialize the file system, use <tt>f_mount()</tt> function instead.</em> This function is called on volume mount process by FatFs module to manage the media change.</p>
<p>This function initializes a storage device and put it ready to generic read/write data. When the function succeeded, <tt>STA_NOINIT</tt> flag in the return value is cleared.</p>
<p><em>Application program MUST NOT call this function, or FAT structure on the volume can be broken. To re-initialize the file system, use <tt>f_mount()</tt> function instead.</em> This function is called at volume mount process by FatFs module to manage the media change.</p>
</div>
<p class="foot"><a href="../00index_e.html">Return</a></p>
doc/en/dioctl.html
+33 -12
View File
@@ -27,11 +27,11 @@ DRESULT disk_ioctl (
<h4>Parameters</h4>
<dl class="par">
<dt>pdrv</dt>
<dd>Specifies the drive number (0-9).</dd>
<dd>Physical drive number to identify the target device.</dd>
<dt>cmd</dt>
<dd>Specifies the command code.</dd>
<dd>Command code.</dd>
<dt>buff</dt>
<dd>Pointer to the parameter buffer depends on the command code. Set NULL if not used.</dd>
<dd>Pointer to the parameter depends on the command code. Do not care if no parameter to be passed.</dd>
</dl>
</div>
@@ -42,25 +42,46 @@ DRESULT disk_ioctl (
<dt>RES_OK (0)</dt>
<dd>The function succeeded.</dd>
<dt>RES_ERROR</dt>
<dd>Any error occured.</dd>
<dd>An error occured.</dd>
<dt>RES_PARERR</dt>
<dd>Invalid command code or parameter.</dd>
<dd>The command code or parameter is invalid.</dd>
<dt>RES_NOTRDY</dt>
<dd>The disk drive has not been initialized.</dd>
<dd>The device has not been initialized.</dd>
</dl>
</div>
<div class="para desc">
<h4>Description</h4>
<p>The FatFs module uses only device independent commands described below. Any device dependent functions and user defined functions are not used.</p>
<p>The FatFs module requires only five device independent commands described below.</p>
<table class="lst">
<caption>Standard ioctl command used by FatFs</caption>
<tr><th>Command</th><th>Description</th></tr>
<tr><td>CTRL_SYNC</td><td>Make sure that the disk drive has finished pending write process. When the disk I/O module has a write back cache, the dirty sectors must be written back immediately. This command is not used at read-only configuration.</td></tr>
<tr><td>GET_SECTOR_COUNT</td><td>Returns number of available sectors on the drive into the <tt>DWORD</tt> variable pointed by <tt class="arg">buff</tt>. This command is used by only <tt>f_mkfs()</tt> and <tt>f_fdisk()</tt> function to determine the volume/partition size to be created.</td></tr>
<tr><td>GET_SECTOR_SIZE</td><td>Returns sector size of the media into the <tt>WORD</tt> variable pointed by <tt class="arg">buff</tt>. Valid return values of this command are 512, 1024, 2048 or 4096. This command is never used at fixed sector size configuration, <tt>_MAX_SS == _MIN_SS</tt>, and it must work at that sector size.</td></tr>
<tr><td>GET_BLOCK_SIZE</td><td>Returns erase block size of the flash memory in unit of sector into the <tt>DWORD</tt> variable pointed by <tt class="arg">buff</tt>. The allowable value is from 1 to 32768 in power of 2. Return 1 if the erase block size is unknown or disk devices. This command is used by only <tt>f_mkfs()</tt> function and it attempts to align data area to the erase block boundary.</td></tr>
<tr><td>CTRL_ERASE_SECTOR</td><td>Erases a part of the flash memory specified by a <tt>DWORD</tt> array {&lt;start sector&gt;, &lt;end sector&gt;} pointed by <tt class="arg">buff</tt>. This is similar command to Trim command of ATA command set. When this feature is not supported or not a flash memory media, this command has no effect and can be ignored. The FatFs does not check the result code and the file function is not affected even if the sectors ware not erased well. This command is called on removing a cluster chain when <tt>_USE_ERASE</tt> is 1.</td></tr>
<tr><td>CTRL_SYNC</td><td>Make sure that the device has finished pending write process. If the disk I/O module has a write back cache, the dirty buffers must be written back to the media immediately. Nothing to do for this command if each write operation to the media is completed within the <tt>disk_write()</tt> function. Required at <tt>_FS_READONLY == 0</tt>.</td></tr>
<tr><td>GET_SECTOR_COUNT</td><td>Returns number of available sectors on the drive into the <tt>DWORD</tt> variable pointed by <tt class="arg">buff</tt>. This command is used by only <tt>f_mkfs()</tt> and <tt>f_fdisk()</tt> function to determine the volume/partition size to be created. Required at <tt>_USE_MKFS == 1</tt> or <tt>_MULTI_PARTITION == 1</tt>.</td></tr>
<tr><td>GET_SECTOR_SIZE</td><td>Returns sector size of the media into the <tt>WORD</tt> variable pointed by <tt class="arg">buff</tt>. Valid return values of this command are 512, 1024, 2048 or 4096. This command is required at variable sector size configuration, <tt>_MAX_SS &gt; _MIN_SS</tt>. Never used at fixed sector size configuration, <tt>_MAX_SS == _MIN_SS</tt>, and it must work at that sector size.</td></tr>
<tr><td>GET_BLOCK_SIZE</td><td>Returns erase block size of the flash memory in unit of sector into the <tt>DWORD</tt> variable pointed by <tt class="arg">buff</tt>. The allowable value is from 1 to 32768 in power of 2. Return 1 if the erase block size is unknown or disk media. This command is used by only <tt>f_mkfs()</tt> function and it attempts to align data area to the erase block boundary. Required at <tt>_USE_MKFS == 1</tt>.</td></tr>
<tr><td>CTRL_ERASE_SECTOR</td><td>Informs device that the data on the block of sectors specified by a <tt>DWORD</tt> array {&lt;start sector&gt;, &lt;end sector&gt;} pointed by <tt class="arg">buff</tt> is no longer needed and may be erased. The device would force erased the memory block. This is a command similar to Trim command of ATA device. When this feature is not supported or not a flash memory media, nothing to do for this command. The FatFs does not check the result code and the file function is not affected even if the sectors ware not erased well. This command is called on removing a cluster chain and <tt>f_mkfs()</tt> function. Required at <tt>_USE_ERASE == 1</tt>.</td></tr>
</table>
<p>FatFs never uses any device dependent command and user defined command. Following table shows an example of non-standard commands usable for some applications.</p>
<table class="lst">
<caption>Example of optional ioctl command</caption>
<tr><th>Command</th><th>Description</th></tr>
<tr><td>CTRL_FORMAT</td><td>Create a physical format on the media. If <tt class="arg">buff</tt> is not null, it is pointer to the call-back function for progress notification.</td></tr>
<tr><td>CTRL_POWER_IDLE</td><td>Put the device idle state. <tt>STA_NOINIT</tt> in status flag may not be set if the device would go active state by generic read/write function.</td></tr>
<tr><td>CTRL_POWER_OFF</td><td>Put the device off state. Shut-down the power to the device and deinitialize the device interface if needed. <tt>STA_NOINIT</tt> in status flag must be set. The device goes active state by <tt>disk_initialize()</tt> function.</td></tr>
<tr><td>CTRL_LOCK</td><td>Lock media eject mechanism.</td></tr>
<tr><td>CTRL_UNLOCK</td><td>Unlock media eject mechanism.</td></tr>
<tr><td>CTRL_EJECT</td><td>Eject media cartridge. <tt>STA_NOINIT</tt> and <tt>STA_NODISK</tt> in status flag are set after the function succeeded.</td></tr>
<tr><td>MMC_GET_TYPE</td><td>Get card type. The type flags, bit0:MMCv3, bit1:SDv1, bit2:SDv2+ and bit3:LBA, is stored to a BYTE variable pointed by <tt class="arg">buff</tt>. (MMC/SDC specific command)</td></tr>
<tr><td>MMC_GET_CSD</td><td>Get CSD register into a 16-byte buffer pointed by <tt class="arg">buff</tt>. (MMC/SDC specific command)</td></tr>
<tr><td>MMC_GET_CID</td><td>Get CID register into a 16-byte buffer pointed by <tt class="arg">buff</tt>. (MMC/SDC specific command)</td></tr>
<tr><td>MMC_GET_OCR</td><td>Get OCR register into a 4-byte buffer pointed by <tt class="arg">buff</tt>. (MMC/SDC specific command)</td></tr>
<tr><td>MMC_GET_SDSTAT</td><td>Get SDSTATUS register into a 64-byte buffer pointed by <tt class="arg">buff</tt>. (SDC specific command)</td></tr>
<tr><td>ATA_GET_REV</td><td>Get the revision string into a 16-byte buffer pointed by <tt class="arg">buff</tt>. (ATA/CFC specific command)</td></tr>
<tr><td>ATA_GET_MODEL</td><td>Get the model string into a 40-byte buffer pointed by <tt class="arg">buff</tt>. (ATA/CFC specific command)</td></tr>
<tr><td>ATA_GET_SN</td><td>Get the serial number string into a 20-byte buffer pointed by <tt class="arg">buff</tt>. (ATA/CFC specific command)</td></tr>
</table>
</div>
doc/en/dread.html
+7 -6
View File
@@ -13,7 +13,7 @@
<div class="para func">
<h2>disk_read</h2>
<p>The disk_read function reads sector(s) from the disk drive.</p>
<p>The disk_read function reads sector(s) from the storage device.</p>
<pre>
DRESULT disk_read (
BYTE <span class="arg">pdrv</span>, <span class="c">/* [IN] Physical drive number */</span>
@@ -28,13 +28,13 @@ DRESULT disk_read (
<h4>Parameters</h4>
<dl class="par">
<dt>pdrv</dt>
<dd>Specifies the physical drive number.</dd>
<dd>Physical drive number to identify the target device.</dd>
<dt>buff</dt>
<dd>Pointer to the <em>byte array</em> to store the read data. The size of buffer must be in sector size * sector count.</dd>
<dd>Pointer to the <em>byte array</em> to store the read data.</dd>
<dt>sector</dt>
<dd>Specifies the start sector number in logical block address (LBA).</dd>
<dd>Start sector number in logical block address (LBA).</dd>
<dt>count</dt>
<dd>Specifies number of sectors to read. FatFs specifis with 1 to 128. Generally, a multiple sector transfer request must not be split into single sector transactions to the device, or you may not get good read performance.</dd>
<dd>Number of sectors to read. FatFs specifis it in range of from 1 to 128.</dd>
</dl>
</div>
@@ -49,7 +49,7 @@ DRESULT disk_read (
<dt>RES_PARERR</dt>
<dd>Invalid parameter.</dd>
<dt>RES_NOTRDY</dt>
<dd>The disk drive has not been initialized.</dd>
<dd>The device has not been initialized.</dd>
</dl>
</div>
@@ -62,6 +62,7 @@ DRESULT disk_read (
<li>For <tt>f_read()</tt>, avoid long read request that includes a whole of sector. - Direct transfer will never occure.</li>
<li>For <tt>f_read(fp, buff, btr, &amp;br)</tt>, make sure that <tt>(((UINT)buff &amp; 3) == (f_tell(fp) &amp; 3))</tt> is true. - Word aligned direct transfer is guaranteed.</li>
</ul>
<p>Generally, a multiple sector transfer request must not be split into single sector transactions to the storage device, or you will not get good read throughput.</p>
</div>
doc/en/dstat.html
+5 -5
View File
@@ -25,21 +25,21 @@ DSTATUS disk_status (
<h4>Parameter</h4>
<dl class="par">
<dt>pdrv</dt>
<dd>Specifies the physical drive number to be confirmed.</dd>
<dd>Physical drive number to identify the target device.</dd>
</dl>
</div>
<div class="para ret">
<h4>Return Values</h4>
<p>The disk status is returned in combination of following flags. FatFs refers only <tt>STA_NOINIT</tt> and <tt>STA_PROTECTED</tt>.</p>
<p>The disk status is returned in combination of following flags. FatFs refers only <tt>STA_NOINIT</tt> and <tt>STA_PROTECT</tt>.</p>
<dl class="ret">
<dt>STA_NOINIT</dt>
<dd>Indicates that the disk drive is not initialized. This flag is set on system reset, media removal or failure of <tt>disk_initialize()</tt> function. It is cleared on <tt>disk_initialize()</tt> function succeeded. Media change that occurs asynchronously must be captured and reflect it to the status flags, or auto-mount feature will not work correctly. When media change detection feature is not supported, application program needs to de-initialize the file system object with <tt>f_mount()</tt> function after the media change.</dd>
<dd>Indicates that the device is not initialized. This flag is set on system reset, media removal or failure of <tt>disk_initialize()</tt> function. It is cleared on <tt>disk_initialize()</tt> function succeeded. Media change that occurs asynchronously must be captured and reflect it to the status flags, or auto-mount feature will not work correctly. When media change detection feature is not supported, application program needs to de-initialize the file system object with <tt>f_mount()</tt> function after the media change.</dd>
<dt>STA_NODISK</dt>
<dd>Indicates that no medium in the drive. This is always cleared on fixed disk drive. Note that FatFs does not refer this flag.</dd>
<dt>STA_PROTECTED</dt>
<dd>Indicates that the medium is write protected. This is always cleared on the drive that does not support write protect notch. Not valid while no medium in the drive.</dd>
<dt>STA_PROTECT</dt>
<dd>Indicates that the medium is write protected. This is always cleared on the drives without write protect feature. Not valid while no medium in the drive.</dd>
</dl>
</div>
doc/en/dwrite.html
+18 -10
View File
@@ -13,12 +13,12 @@
<div class="para func">
<h2>disk_write</h2>
<p>The disk_write writes sector(s) to the disk.</p>
<p>The disk_write writes sector(s) to the storage device.</p>
<pre>
DRESULT disk_write (
BYTE <span class="arg">drv</span>, <span class="c">/* [IN] Physical drive number */</span>
const BYTE* <span class="arg">buff</span>, <span class="c">/* [IN] Write data (may be non aligned) */</span>
DWORD <span class="arg">sector</span>, <span class="c">/* [IN] Sector number to write */</span>
const BYTE* <span class="arg">buff</span>, <span class="c">/* [IN] Pointer to the data to be written */</span>
DWORD <span class="arg">sector</span>, <span class="c">/* [IN] Sector number to write from */</span>
UINT <span class="arg">count</span> <span class="c">/* [IN] Number of sectors to write */</span>
);
</pre>
@@ -28,13 +28,13 @@ DRESULT disk_write (
<h4>Parameters</h4>
<dl class="par">
<dt>pdrv</dt>
<dd>Specifies the physical drive number.</dd>
<dd>Physical drive number to identify the target device.</dd>
<dt>buff</dt>
<dd>Pointer to the <em>byte array</em> to be written.</dd>
<dd>Pointer to the <em>byte array</em> to be written. The size of data to be written is sector size * <tt class="arg">count</tt> bytes.</dd>
<dt>sector</dt>
<dd>Specifies the start sector number in logical block address (LBA).</dd>
<dd>Start sector number in logical block address (LBA).</dd>
<dt>count</dt>
<dd>Specifies the number of sectors to write. FatFs specifis 1 to 128. Generally, a multiple sector transfer request must not be split into single sector transactions to the device, or you will never get good write performance.</dd>
<dd>Number of sectors to write. FatFs specifis it in range of from 1 to 128.</dd>
</dl>
</div>
@@ -51,15 +51,23 @@ DRESULT disk_write (
<dt>RES_PARERR</dt>
<dd>Invalid parameter.</dd>
<dt>RES_NOTRDY</dt>
<dd>The disk drive has not been initialized.</dd>
<dd>The device has not been initialized.</dd>
</dl>
</div>
<div class="para desc">
<h4>Description</h4>
<p>This function is not required in read only configuration. The specified memory address is not that always aligned to word boundary because the type of pointer is defined as <tt>BYTE</tt>. For more information, read <a href="dread.html">description in disk_read function</a>.</p>
<p><em>Application program MUST NOT call this function while FatFs is in use, or FAT structure on the volume can be corrapted.</em></p>
<p>The specified memory address is not that always aligned to word boundary because the type of pointer is defined as <tt>BYTE*</tt>. For more information, refer to the description of <a href="dread.html"><tt>disk_read()</tt></a> function.</p>
<p>Generally, a multiple sector transfer request must not be split into single sector transactions to the storage device, or you will never get good write throughput.</p>
<p>FatFs expects delayed write feature of the disk functions. The write operation to the media need not to be completed due to write operation is in progress or only stored it into the cache buffer when return from this function. But data on the <tt class="arg">buff</tt> is invalid after return from this function. The write completion request is done by <tt>CTRL_SYNC</tt> command of <tt><a href="dioctl.html">disk_ioctl()</a></tt> function. Therefore, if delayed write feature is implemented, the write throughput may be improved.</p>
<p><em>Application program MUST NOT call this function, or FAT structure on the volume can be collapsed.</em></p>
</div>
<div class="para comp">
<h4>QuickInfo</h4>
<p>This function is not needed when <tt>_FS_READONLY == 1</tt>.</p>
</div>
doc/en/fattime.html
+9 -3
View File
@@ -25,11 +25,11 @@ DWORD get_fattime (void);
<p>Currnet time is returned with packed into a <tt>DWORD</tt> value. The bit field is as follows:</p>
<dl class="ret">
<dt>bit31:25</dt>
<dd>Year from 1980 (0..127)</dd>
<dd>Year origin from the 1980 (0..127)</dd>
<dt>bit24:21</dt>
<dd>Month (1..12)</dd>
<dt>bit20:16</dt>
<dd>Day in month(1..31)</dd>
<dd>Day of the month(1..31)</dd>
<dt>bit15:11</dt>
<dd>Hour (0..23)</dd>
<dt>bit10:5</dt>
@@ -42,7 +42,13 @@ DWORD get_fattime (void);
<div class="para desc">
<h4>Description</h4>
<p>The <tt>get_fattime()</tt> function must return any valid time even if the system does not support a real time clock. If a zero is returned, the file will not have a valid time. This fucntion is not required in read only configuration.</p>
<p>The <tt>get_fattime()</tt> function shall return any valid time even if the system does not support a real time clock. If a zero is returned, the file will not have a valid timestamp.</p>
</div>
<div class="para comp">
<h4>QuickInfo</h4>
<p>This function is not needed when <tt>_FS_READONLY == 1</tt>.</p>
</div>
doc/en/fdisk.html
+3 -3
View File
@@ -48,7 +48,7 @@ FRESULT f_fdisk (
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_fdisk()</tt> function creates a partition table into the MBR of the physical drive. The partitioning rule is in generic FDISK format, so that it can create upto four primary partitions. Extended partition is not supported. The <tt class="arg">part[]</tt> array with four items specifies how to divide the physical drive. The first item specifies the size of first primary partition and fourth item specifies the fourth primary partition. If the value is less than or equal to 100, it means percentage of the partition in the entire disk space. If it is larger than 100, it means partition size in unit of sector.</p>
<p>The <tt>f_fdisk()</tt> function creates a partition table into the MBR of the physical drive. The partitioning rule is in generic FDISK format, so that it can create upto four primary partitions. Logical volumes in the extended partition is not supported. The <tt class="arg">part[]</tt> with four items specifies how to divide the physical drive. The first item specifies the size of first primary partition and fourth item specifies the fourth primary partition. If the value is less than or equal to 100, it specifies percentage of the partition in the entire disk space. If it is larger than 100, it specifies the partition size in unit of sector.</p>
</div>
<div class="para comp">
@@ -76,11 +76,11 @@ FRESULT f_fdisk (
f_fdisk(0, plist, work); <span class="c">/* Divide physical drive 0 */</span>
f_mount(&amp;fs, "0:", 0); <span class="c">/* Register work area to the logical drive 0 */</span>
f_mount(&amp;fs, "0:", 0); <span class="c">/* Register work area to the logical drive 0 */</span>
f_mkfs("0:", 0, 0); <span class="c">/* Create FAT volume on the logical drive 0. 2nd argument is ignored. */</span>
f_mount(0, "0:", 0); <span class="c">/* Unregister work area from the logical drive 0 */</span>
f_mount(&amp;fs, "1:", 0); <span class="c">/* Give a work area to the logical drive 1 */</span>
f_mount(&amp;fs, "1:", 0); <span class="c">/* Register a work area to the logical drive 1 */</span>
f_mkfs("1:", 0, 0); <span class="c">/* Create FAT volume on the logical drive 1. 2nd argument is ignored. */</span>
f_mount(0, "1:", 0); <span class="c">/* Unregister work area from the logical drive 1 */</span>
doc/en/filename.html
+4 -4
View File
@@ -15,11 +15,11 @@
<div class="para" id="nam">
<h3>Format of the path names</h3>
<p>The format of path name on the FatFs module is similer to the filename specs of DOS/Windos as follows:</p>
<pre>"[drive#:][/]directory/file"</pre>
<p>The FatFs module supports long file name (LFN) and 8.3 format file name (SFN). The LFN can be used when LFN feature is enabled (<tt>_USE_LFN &gt; 0</tt>). The sub directories are separated with a \ or / in the same way as DOS/Windows API. Duplicated separators are skipped and ignored. Only a difference is that the logical drive is specified in a numeral with a colon. When the drive number is omitted, it is assumed as <em>default drive</em> (drive 0 or current drive).</p>
<pre>"[<em>drive</em>:][/]<em>directory</em>/<em>file</em>"</pre>
<p>The FatFs module supports long file name (LFN) and 8.3 format file name (SFN). The LFN can be used when LFN feature is enabled (<tt>_USE_LFN &gt; 0</tt>). The sub directories are separated with a \ or / in the same way as DOS/Windows API. Duplicated separators are skipped and ignored. Only a difference is that the logical drive is specified in a numeral with a colon. When drive number is omitted, the drive number is assumed as <em>default drive</em> (drive 0 or current drive).</p>
<p>Control characters (<tt>'\0'</tt> to <tt>'\x1F'</tt>) are recognized as end of the path name. Leading/embedded spaces in the path name are valid as a part of the name at LFN configuration but they are recognized as end of the path name at non-LFN configuration. Trailing spaces and dots are ignored.</p>
<p>In default configuration (<tt>_FS_RPATH == 0</tt>), it does not have a concept of current directory like OS oriented file system. All objects on the volume are always specified in full path name that follows from the root directory. Dot directory names are not allowed. Heading separator is ignored and it can be exist or omitted. The default drive number is fixed to 0.</p>
<p>When relative path feature is enabled (<tt>_FS_RPATH == 1</tt>), specified path is followed from the root directory if a heading separator is exist. If not, it is followed from the current directory set with <a href="chdir.html">f_chdir</a> function. Dot names are also allowed for the path name. The default drive is the current drive set with <a href="chdrive.html">f_chdrive</a> function.</p>
<p>In default configuration (<tt>_FS_RPATH == 0</tt>), it does not have a concept of current directory like OS oriented file system. All objects on the volume are always specified in full path name that follows from the root directory. Dot directory names are not allowed. Heading separator is ignored and it can be exist or omitted. The default drive is fixed to drive 0.</p>
<p>When relative path feature is enabled (<tt>_FS_RPATH == 1</tt>), specified path is followed from the root directory if a heading separator is exist. If not, it is followed from the current directory of the drive set with <a href="chdir.html">f_chdir</a> function. Dot names are also allowed for the path name. The default drive is the current drive set with <a href="chdrive.html">f_chdrive</a> function.</p>
<table class="lst2">
<tr><td>Path name</td><td>_FS_RPATH == 0</td><td>_FS_RPATH == 1</td></tr>
<tr class="lst3"><td>file.txt</td><td>A file in the root directory of the drive 0</td><td>A file in the current directory of the current drive</td></tr>
doc/en/getfree.html
+1 -1
View File
@@ -13,7 +13,7 @@
<div class="para func">
<h2>f_getfree</h2>
<p>The f_getfree function gets number of the free clusters.</p>
<p>The f_getfree function gets number of the free clusters on the volume.</p>
<pre>
FRESULT f_getfree (
const TCHAR* <span class="arg">path</span>, <span class="c">/* [IN] Logical drive number */</span>
doc/en/getlabel.html
+4 -4
View File
@@ -17,8 +17,8 @@
<pre>
FRESULT f_getlabel (
const TCHAR* <span class="arg">path</span>, <span class="c">/* [IN] Drive number */</span>
TCHAR* <span class="arg">buff</span>, <span class="c">/* [OUT] Volume label */</span>
DWORD* <span class="arg">sn</span> <span class="c">/* [OUT] Volume serial number */</span>
TCHAR* <span class="arg">label</span>, <span class="c">/* [OUT] Volume label */</span>
DWORD* <span class="arg">vsn</span> <span class="c">/* [OUT] Volume serial number */</span>
);
</pre>
</div>
@@ -28,9 +28,9 @@ FRESULT f_getlabel (
<dl class="par">
<dt>path</dt>
<dd>Pointer to the null-terminated string that specifies the <a href="filename.html">logical drive</a>. Null-string specifies the default drive.</dd>
<dt>buff</dt>
<dt>label</dt>
<dd>Pointer to the buffer to store the volume label. The buffer size must be at least 12 items. If the volume has no label, a null-string will be returned. Set null pointer if this information is not needed.</dd>
<dt>sn</dt>
<dt>vsn</dt>
<dd>Pointer to the <tt>DWORD</tt> variable to store the volume serial number. Set null pointer if this information is not needed.</dd>
</dl>
</div>
doc/en/lseek.html
+3 -3
View File
@@ -49,13 +49,13 @@ FRESULT f_lseek (
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_lseek()</tt> function moves the file read/write pointer of an open file. The offset can be specified in only origin from top of the file. When 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 area is undefined because no data is written to the file. This is suitable to pre-allocate a cluster chain quickly, for fast write operation. 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 current read/write pointer is not the expected value, either of followings has been occured.</p>
<p>The <tt>f_lseek()</tt> function moves the file read/write pointer of an open file. The offset can be specified in only origin from top of the file. 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 undefined because no data is written to the file. This is suitable to pre-allocate a cluster chain quickly, for fast write operation. 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 current read/write pointer is not the expected value, either of followings has been occured.</p>
<ul>
<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>
<li>Disk full. There is insufficient free space on the volume to expand the file.</li>
</ul>
<p>Fast seek feature is enabled when <tt>_USE_FASTSEEK</tt> is set to 1 and the member <tt>cltbl</tt> in the file object is not NULL. This feature enables fast backward/long seek operations without FAT access by using cluster link map table (CLMT). It is also applied to <tt>f_read()/f_write()</tt> function. In this mode, the file cannot be expanded by <tt>f_write()/f_lseek()</tt> function.</p>
<p>The CLMT must be created in the user defined <tt>DWORD</tt> array prior to use the fast seek feature. To create the CLMT, set address of the <tt>DWORD</tt> array to the member <tt>cltbl</tt> in the file object, set the array size in unit of items into 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()/f_write()/f_lseek()</tt> function to the file. If the function failed with <tt>FR_NOT_ENOUGH_CORE</tt>, the given array size is insufficient for the file and number of items required is returned into the first item of the array. The required array size is (number of fragments + 1) * 2 items. For example, when the file is fragmented in 5, 12 items will be required for the CLMT.</p>
<p>Fast seek feature is enabled when <tt>_USE_FASTSEEK</tt> is set to 1 and the member <tt>cltbl</tt> in the file object is not NULL. This feature enables fast backward/long seek operations without FAT access by using CLMT (cluster link map table). The fast seek feature is also applied to <tt>f_read()/f_write()</tt> function, however, the file size cannot be expanded by <tt>f_write()/f_lseek()</tt> function.</p>
<p>The CLMT must be created in the user defined <tt>DWORD</tt> array prior to use the fast seek feature. To create the CLMT, set address of the <tt>DWORD</tt> array to the member <tt>cltbl</tt> in the file object, set the array size in unit of items into 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 at subsequent <tt>f_read()/f_write()/f_lseek()</tt> function to the file. If the function failed with <tt>FR_NOT_ENOUGH_CORE</tt>, the given array size is insufficient for the file and number of items required is returned into the first item of the array. The required array size is (number of fragments + 1) * 2 items. For example, when the file is fragmented in 5, 12 items will be required for the CLMT.</p>
</div>
doc/en/mount.html
+11 -11
View File
@@ -13,10 +13,10 @@
<div class="para func">
<h2>f_mount</h2>
<p>The f_mount fucntion registers/unregisters file system object (work area) to the FatFs module.</p>
<p>The f_mount fucntion registers/unregisters file system object to the FatFs module.</p>
<pre>
FRESULT f_mount (
FATFS* <span class="arg">fatfs</span>, <span class="c">/* [IN] File system object */</span>
FATFS* <span class="arg">fs</span>, <span class="c">/* [IN] File system object */</span>
const TCHAR* <span class="arg">path</span>, <span class="c">/* [IN] Logical drive number */</span>
BYTE <span class="arg">opt</span> <span class="c">/* [IN] Initialization option */</span>
);
@@ -26,12 +26,12 @@ FRESULT f_mount (
<div class="para arg">
<h4>Parameters</h4>
<dl class="par">
<dt>fatfs</dt>
<dd>Pointer to the file system object to be registered. Null pointer unregisters the registered file system object.</dd>
<dt>fs</dt>
<dd>Pointer to the new file system object to be registered. Null pointer unregisters the registered file system object.</dd>
<dt>path</dt>
<dd>Pointer to the null-terminated string that specifies the <a href="filename.html">logical drive</a>. If there is no drive number, it means the default drive.</dd>
<dd>Pointer to the null-terminated string that specifies the <a href="filename.html">logical drive</a>. The string with no drive number means the default drive.</dd>
<dt>opt</dt>
<dd>Initialization option. 0: Do not mount now (to be mounted later), 1: Force mounted the volume to check if the volume is available.</dd>
<dd>Initialization option. 0: Do not mount now (to be mounted later), 1: Force mounted the volume to check if the FAT volume is available.</dd>
</dl>
</div>
@@ -53,17 +53,17 @@ FRESULT f_mount (
<ol>
<li>Determines the logical drive which specified by <tt class="arg">path</tt>.</li>
<li>Clears and unregisters the regsitered work area of the drive.</li>
<li>Clears and registers the work area to the drive if <tt class="arg">fatfs</tt> is not NULL.</li>
<li>Clears and registers the new work area to the drive if <tt class="arg">fs</tt> is not NULL.</li>
<li>Performs volume mount process to the drive if forced mount is specified.</li>
</ol>
<p>The file system object is the work area needed for each logical drive. It must be given to the logical drive with this function prior to use any other file functions. To unregister a work area, specify a NULL to the <tt class="arg">fatfs</tt>, and then the work area can be discarded. </p>
<p>The file system object is the work area needed for each logical drive. It must be given to the logical drive with this function prior to use any other file functions except for <tt>f_fdisk()</tt> function. To unregister a work area, specify a NULL to the <tt class="arg">fs</tt>, and then the work area can be discarded.</p>
<p>If forced mount is not specified, this function always succeeds regardless of the physical drive status due to delayed mount feature. It only clears (de-initializes) the given work area and registers its address to the internal table. No activity of the physical drive in this function. It can also be used to force de-initialized the registered work area of a logical drive. The volume mount processes, initialize the corresponding physical drive, find the FAT volume in it and initialize the work area, is performed in the subsequent file access functions when either or both of following condition is true.</p>
<ul>
<li>File system object is not initialized. It is cleared by <tt>f_mount()</tt>.</li>
<li>Physical drive is not initialized. It is de-initialized by system reset or media change.</li>
<li>Physical drive is not initialized. It is de-initialized by system reset or media removal.</li>
</ul>
<p>If the function with forced mount failed, it means that the file system object is registered but the volume is currently not available. Mount process will also be attempted in subsequent file access functions.</p>
<p>If implementation of the disk I/O layer lacks media change detection, application program needs to perform a <tt>f_mount()</tt> after media change to force cleared the file system object.</p>
<p>If the function with forced mount failed, it means that the file system object has been registered successfully but the volume is currently not ready to use. Mount process will also be attempted in subsequent file access functions.</p>
<p>If implementation of the disk I/O layer lacks media change detection, application program needs to perform a <tt>f_mount()</tt> after each media change to force cleared the file system object.</p>
</div>
doc/en/open.html
+5 -5
View File
@@ -29,7 +29,7 @@ FRESULT f_open (
<dt>fp</dt>
<dd>Pointer to the blank file object structure to be created.</dd>
<dt>path</dt>
<dd>Pointer to a null-terminated string that specifies the <a href="filename.html">file name</a> to create or open.</dd>
<dd>Pointer to a null-terminated string that specifies the <a href="filename.html">file name</a> to open or create.</dd>
<dt>mode</dt>
<dd>Mode flags that specifies the type of access and open method for the file. It is specified by a combination of following flags.<br>
<table class="lst">
@@ -74,7 +74,7 @@ To append data to the file, use <a href="lseek.html"><tt>f_lseek()</tt></a> func
<div class="para desc">
<h4>Description</h4>
<p>After <tt>f_open()</tt> function succeeded, the file object is valid. The file object is used for subsequent read/write functions to identify the file. To close an open file, use <a href="close.html"><tt>f_close()</tt></a> function. If the file is modified and not closed properly, the file data will be collapted.</p>
<p>After <tt>f_open()</tt> function succeeded, the file object is valid. The file object is used for subsequent read/write functions to identify the file. To close an open file, use <a href="close.html"><tt>f_close()</tt></a> function. If the file is modified and not closed properly, the file data will be collapsed.</p>
<p>If duplicated file open is needed, read <a href="appnote.html#dup">here</a> carefully. However duplicated open of a file with write mode flag is always prohibited.</p>
<p>Before using any file function, a work area (file system object) must be registered to the logical drive with <a href="mount.html"><tt>f_mount()</tt></a> function. All API functions except for <a href="fdisk.html"><tt>f_fdisk()</tt></a> function can work after this procedure.</p>
</div>
@@ -104,15 +104,15 @@ int main (void)
f_mount(&amp;FatFs, "", 0);
<span class="c">/* Open a text file */</span>
fr = f_open(&fil, "message.txt", FA_READ);
fr = f_open(&amp;fil, "message.txt", FA_READ);
if (fr) return (int)fr;
<span class="c">/* Read all lines and display it */</span>
while (f_gets(line, sizeof line, &fil))
while (f_gets(line, sizeof line, &amp;fil))
printf(line);
<span class="c">/* Close the file */</span>
f_close(&fil);
f_close(&amp;fil);
return 0;
}
doc/en/opendir.html
+1 -1
View File
@@ -55,7 +55,7 @@ FRESULT f_opendir (
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_opendir()</tt> function opens an exsisting directory and creates the directory object for subsequent calls.</p>
<p>The <tt>f_opendir()</tt> function opens an exsisting directory and creates a directory object for subsequent <tt>f_readdir()</tt> function.</p>
</div>
doc/en/printf.html
+93 -90
View File
@@ -1,90 +1,93 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="up" title="FatFs" href="../00index_e.html">
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/printf.html">
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">
<title>FatFs - f_printf</title>
</head>
<body>
<div class="para func">
<h2>f_printf</h2>
<p>The f_printf function writes formatted string to the file.</p>
<pre>
int f_printf (
FIL* <span class="arg">fp</span>, <span class="c">/* [IN] File object */</span>
const TCHAR* <span class="arg">fmt</span>, <span class="c">/* [IN] Format stirng */</span>
...
);
</pre>
</div>
<div class="para arg">
<h4>Parameters</h4>
<dl class="par">
<dt>fp</dt>
<dd>Pointer to the open file object structure.</dd>
<dt>fmt</dt>
<dd>Pointer to the null terminated format string.</dd>
<dt>...</dt>
<dd>Optional arguments.</dd>
</dl>
</div>
<div class="para ret">
<h4>Return Values</h4>
<p>When the function succeeded, it returns number of characters written. When the function failed due to disk full or any error, an <tt>EOF (-1)</tt> will be returned.</p>
</div>
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_printf()</tt> is a wrapper function of <a href="write.html"><tt>f_write()</tt></a>. The format control directive is a sub-set of standard library shown as follos:</p>
<ul>
<li>Type: <tt>c C s S d D u U x X b B</tt></li>
<li>Size: <tt>l L</tt></li>
<li>Flag: <tt>0 -</tt></li>
</ul>
</div>
<div class="para comp">
<h4>QuickInfo</h4>
<p>Available when <tt>_FS_READONLY == 0</tt> and <tt>_USE_STRFUNC</tt> is 1 or 2. When it is set to 2, <tt>'\n'</tt>s contained in the output are converted to <tt>"\r\n"</tt>.</p>
<p>When FatFs is configured to Unicode API (<tt>_LFN_UNICODE == 1</tt>), data types on the srting fuctions, <tt>f_putc()</tt>, <tt>f_puts()</tt>, <tt>f_printf()</tt> and <tt>f_gets()</tt>, is also switched to Unicode. The character encoding on the file to be read/written via those functions is selected by <tt>_STRF_ENCODE</tt> option.</p>
</div>
<div class="para use">
<h4>Example</h4>
<pre>
f_printf(&amp;fil, "%d", 1234); <span class="c">/* "1234" */</span>
f_printf(&amp;fil, "%6d,%3d%%", -200, 5); <span class="c">/* " -200, 5%" */</span>
f_printf(&amp;fil, "%-6u", 100); <span class="c">/* "100 " */</span>
f_printf(&amp;fil, "%ld", 12345678L); <span class="c">/* "12345678" */</span>
f_printf(&amp;fil, "%04x", 0xAB); <span class="c">/* "00ab" */</span>
f_printf(&amp;fil, "%08LX", 0x123ABCL); <span class="c">/* "00123ABC" */</span>
f_printf(&amp;fil, "%016b", 0x550F); <span class="c">/* "0101010100001111" */</span>
f_printf(&amp;fil, "%s", "String"); <span class="c">/* "String" */</span>
f_printf(&amp;fil, "%5s", "abc"); <span class="c">/* " abc" */</span>
f_printf(&amp;fil, "%-5s", "abc"); <span class="c">/* "abc " */</span>
f_printf(&amp;fil, "%c", 'a'); <span class="c">/* "a" */</span>
f_printf(&amp;fil, "%f", 10.0); <span class="c">/* f_printf lacks floating point support */</span>
</pre>
</div>
<div class="para ref">
<h4>See Also</h4>
<p><tt><a href="open.html">f_open</a>, <a href="putc.html">f_putc</a>, <a href="puts.html">f_puts</a>, <a href="gets.html">f_gets</a>, <a href="close.html">f_close</a>, <a href="sfile.html">FIL</a></tt></p>
</div>
<p class="foot"><a href="../00index_e.html">Return</a></p>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="up" title="FatFs" href="../00index_e.html">
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/printf.html">
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">
<title>FatFs - f_printf</title>
</head>
<body>
<div class="para func">
<h2>f_printf</h2>
<p>The f_printf function writes formatted string to the file.</p>
<pre>
int f_printf (
FIL* <span class="arg">fp</span>, <span class="c">/* [IN] File object */</span>
const TCHAR* <span class="arg">fmt</span>, <span class="c">/* [IN] Format stirng */</span>
...
);
</pre>
</div>
<div class="para arg">
<h4>Parameters</h4>
<dl class="par">
<dt>fp</dt>
<dd>Pointer to the open file object structure.</dd>
<dt>fmt</dt>
<dd>Pointer to the null terminated format string. The terminator charactor will not be written.</dd>
<dt>...</dt>
<dd>Optional arguments...</dd>
</dl>
</div>
<div class="para ret">
<h4>Return Values</h4>
<p>When the function succeeded, it returns number of characters written. When the function failed due to disk full or any error, an <tt>EOF (-1)</tt> will be returned.</p>
</div>
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_printf()</tt> is a wrapper function of <a href="write.html"><tt>f_write()</tt></a>. The format control directive is a sub-set of standard library shown as follos:</p>
<ul>
<li>Type: <tt>c C s S d D u U x X b B</tt></li>
<li>Size: <tt>l L</tt></li>
<li>Flag: <tt>0 -</tt></li>
</ul>
</div>
<div class="para comp">
<h4>QuickInfo</h4>
<p>Available when <tt>_FS_READONLY == 0</tt> and <tt>_USE_STRFUNC</tt> is 1 or 2. When it is set to 2, <tt>'\n'</tt>s contained in the output are converted to <tt>'\r'+'\n'</tt>.</p>
<p>When FatFs is configured to Unicode API (<tt>_LFN_UNICODE == 1</tt>), data types on the srting fuctions, <tt>f_putc()</tt>, <tt>f_puts()</tt>, <tt>f_printf()</tt> and <tt>f_gets()</tt>, is also switched to Unicode. The character encoding on the file to be read/written via those functions is selected by <tt>_STRF_ENCODE</tt> option.</p>
</div>
<div class="para use">
<h4>Example</h4>
<pre>
f_printf(&amp;fil, "%d", 1234); <span class="c">/* "1234" */</span>
f_printf(&amp;fil, "%6d,%3d%%", -200, 5); <span class="c">/* " -200, 5%" */</span>
f_printf(&amp;fil, "%ld", 12345L); <span class="c">/* "12345" */</span>
f_printf(&amp;fil, "%06d", 25); <span class="c">/* "000025" */</span>
f_printf(&amp;fil, "%06d", -25); <span class="c">/* "000-25" */</span>
f_printf(&amp;fil, "%-6d", 25); <span class="c">/* "25 " */</span>
f_printf(&amp;fil, "%u", -1); <span class="c">/* "65535" or "4294967295" */</span>
f_printf(&amp;fil, "%04x", 0xAB3); <span class="c">/* "0ab3" */</span>
f_printf(&amp;fil, "%08LX", 0x123ABCL); <span class="c">/* "00123ABC" */</span>
f_printf(&amp;fil, "%016b", 0x550F); <span class="c">/* "0101010100001111" */</span>
f_printf(&amp;fil, "%s", "String"); <span class="c">/* "String" */</span>
f_printf(&amp;fil, "%8s", "abc"); <span class="c">/* " abc" */</span>
f_printf(&amp;fil, "%-8s", "abc"); <span class="c">/* "abc " */</span>
f_printf(&amp;fil, "%c", 'a'); <span class="c">/* "a" */</span>
f_printf(&amp;fil, "%f", 10.0); <span class="c">/* f_printf lacks floating point support */</span>
</pre>
</div>
<div class="para ref">
<h4>See Also</h4>
<p><tt><a href="open.html">f_open</a>, <a href="putc.html">f_putc</a>, <a href="puts.html">f_puts</a>, <a href="gets.html">f_gets</a>, <a href="close.html">f_close</a>, <a href="sfile.html">FIL</a></tt></p>
</div>
<p class="foot"><a href="../00index_e.html">Return</a></p>
</body>
</html>
doc/en/putc.html
+1 -1
View File
@@ -48,7 +48,7 @@ int f_putc (
<div class="para comp">
<h4>QuickInfo</h4>
<p>Available when <tt>_FS_READONLY == 0</tt> and <tt>_USE_STRFUNC</tt> is 1 or 2. When it is set to 2, a <tt>'\n'</tt> is converted to <tt>"\r\n"</tt>.</p>
<p>Available when <tt>_FS_READONLY == 0</tt> and <tt>_USE_STRFUNC</tt> is 1 or 2. When it is set to 2, a <tt>'\n'</tt> is converted to <tt>'\r'+'\n'</tt>.</p>
</div>
doc/en/puts.html
+2 -2
View File
@@ -26,7 +26,7 @@ int f_puts (
<h4>Parameters</h4>
<dl class="par">
<dt>str</dt>
<dd>Pointer to the null terminated string to be written. The null character will not be written.</dd>
<dd>Pointer to the null terminated string to be written. The terminator character will not be written.</dd>
<dt>fp</dt>
<dd>Pointer to the open file object structure.</dd>
</dl>
@@ -48,7 +48,7 @@ int f_puts (
<div class="para comp">
<h4>QuickInfo</h4>
<p>Available when <tt>_FS_READONLY == 0</tt> and <tt>_USE_STRFUNC</tt> is 1 or 2. When it is set to 2, <tt>'\n'</tt>s contained in the string are converted to <tt>"\r\n"</tt>.</p>
<p>Available when <tt>_FS_READONLY == 0</tt> and <tt>_USE_STRFUNC</tt> is 1 or 2. When it is set to 2, <tt>'\n'</tt>s contained in the string are converted to <tt>'\r'+'\n'</tt>.</p>
</div>
doc/en/rc.html
+5 -5
View File
@@ -17,14 +17,14 @@
<dt id="ok">FR_OK (0)</dt>
<dd>The function succeeded.</dd>
<dt id="de">FR_DISK_ERR</dt>
<dd>An unrecoverable hard error occured in the lower layer, <tt>disk_read()</tt>, <tt>disk_write()</tt> or <tt>disk_ioctl()</tt> function.</dd>
<dd>An unrecoverable hard error occured in the lower layer, <tt>disk_read()</tt>, <tt>disk_write()</tt> or <tt>disk_ioctl()</tt> function.<br>Note that if once this error occured at any operation to an open file, the file object is aborted and all operations to the file except for close will be rejected.</dd>
<dt id="ie">FR_INT_ERR</dt>
<dd>Assertion failed. An insanity is detected in the internal process. One of the following possibilities are suspected.
<dd>Assertion failed. An insanity is detected in the internal process. One of the following possibilities is suspected.
<ul>
<li>There is any error of the FAT structure on the volume.</li>
<li>Work area (file system object, file object or etc...) is broken by stack overflow or any other application. This is the reason in most case.</li>
<li>An <tt>FR_DISK_ERR</tt> has occured on the file object.</li>
<li>There is any error of the FAT structure on the volume.</li>
</ul>
Note that if once this error occured at any operation to an open file, the file object is aborted and all operations to the file except for close will be rejected.
</dd>
<dt id="nr">FR_NOT_READY</dt>
<dd>The disk drive cannot work due to incorrect medium removal or <tt>disk_initialize()</tt> function failed.</dd>
@@ -69,7 +69,7 @@
<dt id="tm">FR_TIMEOUT</dt>
<dd>The function was canceled due to a timeout of <a href="appnote.html#reentrant">thread-safe control</a>. (Related option: <tt>_TIMEOUT</tt>)</dd>
<dt id="lo">FR_LOCKED</dt>
<dd>The function was rejected by <a href="appnote.html#dup">file sharing control</a>. (Related option: <tt>_FS_LOCK</tt>)</dd>
<dd>The operation to the object was rejected by <a href="appnote.html#dup">file sharing control</a>. (Related option: <tt>_FS_LOCK</tt>)</dd>
<dt id="nc">FR_NOT_ENOUGH_CORE</dt>
<dd>Not enough memory for the operation. There is one of the following reasons:
<ul>
doc/en/read.html
+1 -1
View File
@@ -54,7 +54,7 @@ FRESULT f_read (
<div class="para desc">
<h4>Description</h4>
<p>The file read/write pointer of the file object advances number of bytes read. After the function succeeded, <tt class="arg">*br</tt> should be checked to detect the end of file. In case of <tt class="arg">*br</tt> is less than <tt class="arg">btr</tt>, it means the read/write pointer reached end of the file during read operation.</p>
<p>The file read/write pointer of the file object advances number of bytes read. After the function succeeded, <tt class="arg">*br</tt> should be checked to detect end of the file. In case of <tt class="arg">*br</tt> is less than <tt class="arg">btr</tt>, it means the read/write pointer reached end of the file during read operation.</p>
</div>
doc/en/readdir.html
+1 -1
View File
@@ -54,7 +54,7 @@ FRESULT f_readdir (
<ul>
<li>The directory item has no LFN information.</li>
<li>Either the size of read buffer or LFN working buffer is insufficient for the LFN.</li>
<li>The LFN contains any Unicode charactrer that cannot be converted to OEM code. (not the case at Unicode API cfg.)</li>
<li>The LFN contains any Unicode character that cannot be converted to OEM code. (not the case at Unicode API cfg.)</li>
</ul>
<p>When the directory item has no LFN information, lower case characters can be contained in the <tt>fname[]</tt>.</p>
</div>
doc/en/rename.html
+1 -1
View File
@@ -58,7 +58,7 @@ FRESULT f_rename (
<div class="para desc">
<h4>Description</h4>
<p>Renames a file or sub-directory and can also move it to other directory within the same logical drive. <em>Do not rename open objects</em> or directry table can be collapted.</p>
<p>Renames a file or sub-directory and can also move it to other directory within the same logical drive. <em>Do not rename open objects</em> or directry table can be broken.</p>
</div>
doc/en/sdir.html
+3 -3
View File
@@ -23,13 +23,13 @@
DWORD clust; <span class="c">/* Current cluster */</span>
DWORD sect; <span class="c">/* Current sector */</span>
BYTE* dir; <span class="c">/* Pointer to the current SFN entry in the win[] */</span>
BYTE* fn; <span class="c">/* Pointer to the SFN (in/out) {file[8],ext[3],status[1]} */</span>
BYTE* fn; <span class="c">/* Pointer to the SFN buffer (in/out) {file[8],ext[3],status[1]} */</span>
<span class="k">#if</span> _FS_LOCK
UINT lockid; <span class="c">/* Sub-directory lock ID (0:Root directory) */</span>
<span class="k">#endif</span>
<span class="k">#if</span> _USE_LFN
WCHAR* lfn; <span class="c">/* Pointer to the LFN working buffer */</span>
WORD lfn_idx; <span class="c">/* Index of top of last matched LFN entris (0xFFFF:No LFN) */</span>
WCHAR* lfn; <span class="c">/* Pointer to the LFN buffer (in/out) */</span>
WORD lfn_idx; <span class="c">/* Index of the LFN entris (0xFFFF:No LFN) */</span>
<span class="k">#endif</span>
} DIR;
</pre>
doc/en/setlabel.html
+5 -5
View File
@@ -16,7 +16,7 @@
<p>The f_setlabel function sets/removes the label of a volume.</p>
<pre>
FRESULT f_setlabel (
const TCHAR* <span class="arg">name</span> <span class="c">/* [IN] Volume label to be set */</span>
const TCHAR* <span class="arg">label</span> <span class="c">/* [IN] Volume label to be set */</span>
);
</pre>
</div>
@@ -24,7 +24,7 @@ FRESULT f_setlabel (
<div class="para arg">
<h4>Parameters</h4>
<dl class="par">
<dt>name</dt>
<dt>label</dt>
<dd>Pointer to the null-terminated string that specifies the volume label to be set.</dd>
</dl>
</div>
@@ -49,11 +49,11 @@ FRESULT f_setlabel (
<div class="para desc">
<h4>Description</h4>
<p>When the string has a drive number, the volume label will be set to the volume specified by the drive number. If the volume label is a null-string, the volume label on the volume will be removed. The format of the volume label is similar to the SFN but there are some differences shown below:</p>
<p>When the string has a drive number, the volume label will be set to the volume specified by the drive number. If not, the label will be set to the default drive. If the given string is a null-string, the volume label on the volume will be removed. The format of the volume label is similar to the short file name but there are some differences shown below:</p>
<ul>
<li>11 bytes or less in length as local character code.</li>
<li>11 bytes or less in length as local character code. LFN extention is not applied to the volume label.</li>
<li>Cannot contain period.</li>
<li>Can contain spaces anywhere in the name.</li>
<li>Can contain spaces anywhere in the volume label. Trailing spaces are truncated off.</li>
</ul>
</div>
doc/en/sfatfs.html
+1 -1
View File
@@ -24,7 +24,7 @@
BYTE fsi_flag; <span class="c">/* FSINFO flags (b7:Disabled, b0:Dirty) */</span>
WORD id; <span class="c">/* File system mount ID */</span>
WORD n_rootdir; <span class="c">/* Number of root directory entries (FAT12/16) */</span>
<span class="k">#if</span> _MAX_SS != 512
<span class="k">#if</span> _MAX_SS != _MIN_SS
WORD ssize; <span class="c">/* Sector size (512,1024,2048 or 4096) */</span>
<span class="k">#endif</span>
<span class="k">#if</span> _FS_REENTRANT
doc/en/sfileinfo.html
+1 -1
View File
@@ -60,7 +60,7 @@
<dt>fname[]</dt>
<dd>Indicates the file/directory name in 8.3 format null-terminated string. It is always returnd with upper case in non-LFN configuration but it can be returned with lower case in LFN configuration.</dd>
<dt>lfname</dt>
<dd>Pointer to the LFN buffer to store the read LFN. This member must be initialized by application prior to use this structure. Not available in non-LFN configuration.</dd>
<dd>Pointer to the LFN buffer to store the read LFN. This member must be initialized by application prior to use this structure. Set null pointer if LFN is not needed. Not available in non-LFN configuration.</dd>
<dt>lfsize</dt>
<dd>Size of the LFN buffer in unit of TCHAR. This member must be initialized by application prior to use this structure. Not available in non-LFN configuration.</dd>
</dl>
doc/en/stat.html
+1 -1
View File
@@ -54,7 +54,7 @@ FRESULT f_stat (
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_stat()</tt> function checks the existence of a file or sub-directory. If exist, the function returns with <tt>FR_OK</tt> and the information of the object is stored to the file information structure. If not exist, the function returns with <tt>FR_NO_FILE</tt>. For details, refer to the <tt>FILINFO</tt> structure and <a href="readdir.html"><tt>f_readdir()</tt></a> function.</p>
<p>The <tt>f_stat()</tt> function checks the existence of a file or sub-directory. If not exist, the function returns with <tt>FR_NO_FILE</tt>. If exist, the function returns with <tt>FR_OK</tt> and the informations of the object, file size, timestamp, attribute and SFN, are stored to the file information structure. For details of the file information, refer to the <tt>FILINFO</tt> structure and <a href="readdir.html"><tt>f_readdir()</tt></a> function.</p>
</div>
doc/en/sync.html
+1 -1
View File
@@ -46,7 +46,7 @@ FRESULT f_sync (
<div class="para desc">
<h4>Description</h4>
<p>The <tt>f_sync()</tt> function performs the same process as <tt>f_close()</tt> function but the file is left opened and can continue read/write/seek operations to the file. This is suitable for the applications that open files for a long time in write mode, such as data logger. Performing <tt>f_sync()</tt> function of periodic or immediataly after <tt>f_write()</tt> function can minimize the risk of data loss due to a sudden blackout or an unintentional media removal. For more information, refer to <a href="appnote.html#critical">application note</a>.</p>
<p>However the <tt>f_sync()</tt> function immediataly before <tt>f_close()</tt> function has no advantage because it performs <tt>f_sync()</tt> function in it. In other words, the differnce between those functions is that the file object is invalidated or not.</p>
<p>However there is no sense in <tt>f_sync()</tt> function immediataly before <tt>f_close()</tt> function because it performs <tt>f_sync()</tt> function in it. In other words, the differnce between those functions is that the file object is invalidated or not.</p>
</div>
doc/en/unlink.html
+3 -3
View File
@@ -57,9 +57,9 @@ FRESULT f_unlink (
<h4>Description</h4>
<p>
If condition of the object to be removed is applicable to the following terms, the function will be rejected.<ul>
<li>The file/sub-directory must not have read-only attribute (<tt>AM_RDO</tt>) or the function will be rejected with <tt>FR_DENIED</tt>.</li>
<li>The sub-directory must be empty and must not be current directory or the function will be rejected with <tt>FR_DENIED</tt>.</li>
<li>The file/sub-directory must not has been opened or the <em>FAT volume can be collapted</em>. It will able to be rejected with <tt>FR_LOCKED</tt> when <a href="appnote.html#dup">file lock feature</a> is enabled.</li>
<li>The file/sub-directory must not have read-only attribute (<tt>AM_RDO</tt>), or the function will be rejected with <tt>FR_DENIED</tt>.</li>
<li>The sub-directory must be empty and must not be current directory, or the function will be rejected with <tt>FR_DENIED</tt>.</li>
<li>The file/sub-directory must not be opened, or the <em>FAT volume can be collapsed</em>. It can be rejected with <tt>FR_LOCKED</tt> when <a href="appnote.html#dup">file lock feature</a> is enabled.</li>
</ul>
</div>