weAut_01 / weAutSys    R 2.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Data Structures | Defines | Enumerations | Functions
File system operations
+ + fatFS -- ChaN's FAT filesystem implementation + +

Overview

The file operations provided by ChaN's fatFS were adapted to weAut_01 like hardware, the use with one slot for small memory cards (SMCs) and the weAutSys runtime. The necessary "cut to size" was quite far-reaching. But it was not so radical, that the restriction to one device and one file system could not be lifted up easily for future upgrading.

Data Structures

struct  DIR
 Directory object structure (DIR) More...
struct  FATFS
 File system object structure (FATFS) More...
struct  FIL
 File object structure (FIL) More...
struct  FILINFO
 File status structure (FILINFO) More...

Defines

#define _FS_TINY
 Tiny FS.
#define _MAX_SS   512
 Maximum sector size to be handled.
#define AM_ARC   0x20
 directory entry attribute bit: archive
#define AM_DIR   0x10
 directory entry attribute bit: directory
#define AM_HID   0x02
 directory entry attribute bit: hidden
#define AM_LFN   0x0F
 directory entry attribute bit: LFN entry
#define AM_MASK   0x3F
 mask of defined directory entry attribute bits
#define AM_RDO   0x01
 directory entry attribute bit: read only
#define AM_SYS   0x04
 directory entry attribute bit: system
#define AM_VOL   0x08
 directory entry attribute bit: Volume label
#define div16SSZ(div)
 Divide (16 bit, unsigned) by fixed sector size.
#define div2SSZ(div)
 Divide (32 bit, unsigned) by 2 times fixed sector size.
#define div32SSZ(div)
 Divide (32 bit, unsigned) by fixed sector size.
#define div4SSZ(div)
 Divide (32 bit, unsigned) by 4 times fixed sector size.
#define divSSZ2(div)
 Divide (32 bit, unsigned) by fixed sector size by 2.
#define divSSZ4(div)
 Divide (32 bit, unsigned) by fixed sector size by 4.
#define f_eof(fp)
 Check EOF.
#define f_error(fp)
 Check error state.
#define f_size(fp)
 Get the size.
#define f_tell(fp)
 Get the current read/write pointer.
#define FA_CREATE_ALWAYS   0x08
 Mode flag: create anyway.
#define FA_CREATE_NEW   0x04
 Mode flag: create a new file.
#define FA_OPEN_ALWAYS   0x10
 Mode flag: open anyway.
#define FA_OPEN_EXISTING   0
 Mode flag: open the existing file object.
#define FA_READ   0x01
 Mode flag: read access to the file object.
#define FA_WRITE   0x02
 Mode flag: write access to the file object.
#define FS_FAT12   1
 FATFS.fs_type value.
#define FS_FAT16   2
 FATFS.fs_type value.
#define FS_FAT32   3
 FATFS.fs_type value.
#define get_fattime()
 Get current local FAT time.
#define LD2PD(vol)
 Each logical drive is bound to the same physical drive number */.
#define LD2PT(vol)
 Always mounts the 1st partition or in SFD.
#define modSSZ(div)
 Modulo (unsigned) by fixed sector size.
#define mul16SSZ(fac)
 Multiply (16 bit, unsigned) with fixed sector size.
#define mul32SSZ(fac)
 Multiply (32 bit, unsigned) with fixed sector size.
#define SSM   511
 Mask for fixed sector size.
#define SSZ   512
 Fixed sector size.

Enumerations

enum  FRESULT {
  FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY,
  FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_DENIED,
  FR_EXIST, FR_INVALID_OBJECT, FR_WRITE_PROTECTED, FR_INVALID_DRIVE,
  FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_MKFS_ABORTED, FR_TIMEOUT,
  FR_LOCKED, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES, FR_INVALID_PARAMETER
}
 File functions return code. More...

Functions

FRESULT checkValidFS (uint8_t vol)
 Check if there's a valid mounted file system on the drive.
FRESULT checkWriteProtect (uint8_t vol)
 Check if the drive is write protected.
uint8_t extractDrive (const TCHAR **path)
 Extract drive number from path.
FRESULT f_chdir (const TCHAR *)
 Change current directory (not implemented)
FRESULT f_chdrive (uint8_t)
 Change current drive (not implemented)
FRESULT f_chmod (const TCHAR *path, uint8_t value, uint8_t mask)
 Change attribute of the file or directory.
FRESULT f_close (FIL *fp)
 Close an open file object.
FRESULT f_fdisk (uint8_t pdrv, const uint32_t szt[], void *work)
 Divide a physical drive into some partitions.
FRESULT f_getcwd (TCHAR *, uint16_t)
 Get current directory (not implemented)
FRESULT f_getfree (const uint8_t vol, uint32_t *nclst)
 Get the number of free clusters on the drive.
TCHAR * f_gets (TCHAR *, int, FIL *)
 Get a string from the file (not implemented)
FRESULT f_lseek (FIL *fp, uint32_t ofs)
 Move file pointer of a file object, expand file size.
FRESULT f_mkdir (const TCHAR *path)
 Create a new directory.
FRESULT f_mount (uint8_t vol, FATFS *fs)
 Mount / unmount a logical drive.
FRESULT f_open (FIL *fp, const TCHAR *path, uint8_t mode)
 Open or create a file.
FRESULT f_opendir (DIR *dj, const TCHAR *path)
 Open an existing directory.
int f_printf (FIL *, const TCHAR *,...)
 Put a formatted string to the file (not implemented)
int f_putc (TCHAR, FIL *)
 Put a character to the file (not implemented)
int f_puts (const TCHAR *, FIL *)
 Put a string to the file (not implemented)
FRESULT f_read (FIL *fp, void *buff, uint16_t btr, uint16_t *br)
 Read data from a file.
FRESULT f_readdir (DIR *dj, FILINFO *fno)
 Read a directory item.
FRESULT f_rename (const TCHAR *path_old, const TCHAR *path_new)
 Rename or move a file or directory.
FRESULT f_stat (const TCHAR *path, FILINFO *fno)
 Get file status.
FRESULT f_sync (FIL *fp)
 Flush written / cached data to a file.
FRESULT f_truncate (FIL *fp)
 Truncate file.
FRESULT f_unlink (const TCHAR *path)
 Delete an existing file or directory.
FRESULT f_utime (const TCHAR *path, const FILINFO *fno)
 Change time-stamps of a file or directory.
FRESULT f_write (FIL *fp, const void *buff, uint16_t btw, uint16_t *bw)
 Write data to a file.
FRESULT getValidFS (uint8_t vol, FATFS **fatfs)
 Get the file system for the drive.
FRESULT lookForFS (uint8_t vol)
 Look for a recognised file system on the drive.

Define Documentation

#define _MAX_SS   512

Maximum sector size to be handled.

Always set 512 for memory card and hard disk but a larger value may be required for on-board flash memory, floppy disk and optical disk. When _MAX_SS is larger than 512, it configures FatFs to variable sector size and GET_SECTOR_SIZE command must be implemented by the disk_ioctl() function.

Hint: For small memory card (SMC, MMC) implementation GET_SECTOR_SIZE is implemented in disk_ioctl() blindly returning 512.

legal values for original fatFS: 512, 1024, 2048 or 4096 (configurable)
fixed value for this implementation: 512

#define SSZ   512

Fixed sector size.

See also:
_MAX_SS
#define mul32SSZ (   fac)

Multiply (32 bit, unsigned) with fixed sector size.

See also:
SSZ
Parameters:
facthe 32 bit (unsigned) factor
fac's upper 9 bits are ignored and should be 0 to get a arithmetically correct result
Returns:
the product fac * SSZ
See also:
div32SSZ(div)
#define mul16SSZ (   fac)

Multiply (16 bit, unsigned) with fixed sector size.

See also:
SSZ
Parameters:
facthe 16 bit (unsigned) factor
fac's upper 9 bits are ignored and should be 0 to get a arithmetically correct result
Returns:
the product fac * SSZ
See also:
mul32SSZ(div)
#define div32SSZ (   div)

Divide (32 bit, unsigned) by fixed sector size.

See also:
SSZ
Parameters:
divthe 32 bit (unsigned) dividend
Returns:
the quotient div / SSZ
See also:
mul32SSZ(fac)
div2SSZ(div)
div4SSZ(div)
#define div16SSZ (   div)

Divide (16 bit, unsigned) by fixed sector size.

See also:
SSZ
Parameters:
divthe 16 bit (unsigned) dividend
Returns:
the quotient div / SSZ
See also:
mul32SSZ(fac)
div32SSZ(div)
#define modSSZ (   div)

Modulo (unsigned) by fixed sector size.

See also:
SSZ
Parameters:
divthe (unsigned) dividend
Returns:
the remainder div % SSZ
See also:
mul32SSZ(fac)
#define div2SSZ (   div)

Divide (32 bit, unsigned) by 2 times fixed sector size.

See also:
SSZ
Parameters:
divthe 32 bit (unsigned) dividend
Returns:
the quotient div / (SSZ * 2)
See also:
mul32SSZ(fac)
#define div4SSZ (   div)

Divide (32 bit, unsigned) by 4 times fixed sector size.

See also:
SSZ
Parameters:
divthe 32 bit (unsigned) dividend
Returns:
the quotient div / (SSZ * 4)
See also:
mul32SSZ(fac)
#define divSSZ4 (   div)

Divide (32 bit, unsigned) by fixed sector size by 4.

This divides a 32 bit number by a quarter of the fixed sector size.

See also:
SSZ
Parameters:
divthe 32 bit (unsigned) dividend
Returns:
the quotient div / (SSZ / 4)
See also:
mul32SSZ(fac)
#define divSSZ2 (   div)

Divide (32 bit, unsigned) by fixed sector size by 2.

This divides a 32 bit number by a quarter of the fixed sector size.

See also:
SSZ
Parameters:
divthe 32 bit (unsigned) dividend
Returns:
the quotient div / (SSZ / 2)
See also:
mul32SSZ(fac)
#define _FS_TINY

Tiny FS.

When _FS_TINY is set to 1, fatFS uses the sector buffer in the file system object instead of the sector buffer in the individual file object for file data transfer. This reduces the memory consumption by 512 bytes for each file object.

Legal values on original fatFS: 0 = normal or 1 = tiny — configurable there but fixed for this implementation.

#define f_eof (   fp)

Check EOF.

Parameters:
fpPointer to the file's object structure (type FIL)
Returns:
1 if EOF reached
#define f_error (   fp)

Check error state.

Parameters:
fpPointer to the file's object structure (type FIL)
Returns:
1 if in an erroneous state
#define f_tell (   fp)

Get the current read/write pointer.

Parameters:
fpPointer to the open file's object structure (type FIL)
Returns:
the current R/W pointer, i.e. byte index (type uint32_t)
#define f_size (   fp)

Get the size.

Parameters:
fpPointer to the open file's object structure (type FIL)
Returns:
the size (type uint32_t)
#define get_fattime ( )

Get current local FAT time.

See also:
getFATtime
#define FA_READ   0x01

Mode flag: read access to the file object.

Combine with FA_WRITE for read-write access.

Examples:
main.c.
#define FA_OPEN_EXISTING   0

Mode flag: open the existing file object.

The function fails if the file is not existing (default).

Examples:
main.c.
#define FA_WRITE   0x02

Mode flag: write access to the file object.

Combine with FA_READ for read-write access.

#define FA_CREATE_NEW   0x04

Mode flag: create a new file.

The function fails with FR_EXIST if the file is existing.

#define FA_CREATE_ALWAYS   0x08

Mode flag: create anyway.

Opens the file if it is existing. If not, a new file is created.

#define FA_OPEN_ALWAYS   0x10

Mode flag: open anyway.

Opens the file if it is existing. If not, a new file is created. To append data to the file, use f_lseek after file opening with this mode.


Enumeration Type Documentation

enum FRESULT

File functions return code.

Enumerator:
FR_OK 

(0) Succeeded

FR_DISK_ERR 

(1) A hard error occurred in the low level disk I/O layer

FR_INT_ERR 

(2) Assertion failed

FR_NOT_READY 

(3) The physical drive cannot work

FR_NO_FILE 

(4) Could not find the file

FR_NO_PATH 

(5) Could not find the path

FR_INVALID_NAME 

(6) The path name format is invalid

FR_DENIED 

(7) Access denied due to prohibited access or directory full

FR_EXIST 

(8) Access denied due to prohibited access as already existing

FR_INVALID_OBJECT 

(9) The file/directory object is invalid

FR_WRITE_PROTECTED 

(10) The physical drive is write protected

FR_INVALID_DRIVE 

(11) The logical drive number is invalid

FR_NOT_ENABLED 

(12) The volume has no work area

FR_NO_FILESYSTEM 

(13) There is no valid FAT volume

FR_MKFS_ABORTED 

(14) The f_mkfs() aborted due to any parameter error

FR_TIMEOUT 

(15) Could not get a grant to access the volume within defined period

FR_LOCKED 

(16) The operation is rejected according to the file sharing policy

FR_NOT_ENOUGH_CORE 

(17) LFN working buffer could not be allocated

FR_TOO_MANY_OPEN_FILES 

(18) Number of open files > _FS_SHARE

FR_INVALID_PARAMETER 

(19) Given parameter is invalid


Function Documentation

FRESULT f_mount ( uint8_t  vol,
FATFS fs 
)

Mount / unmount a logical drive.

This function registers / unregisters a work area, i.e. FATFS structure, assigning it to a drive number (0...) respectively volume. A work area must be assigned to the a volume before the use of any other file function. To unregister a work area use NULL as parameter fs.

This function always succeeds for a legal vol value regardless of the drive's status. No media is accessed by this function. It only clears the given work area and registers it.

The "real" volume mount process is performed

  1. once on first file access after calling f_mount or
  2. once on first file access after after a media change.
Parameters:
volLogical drive number to be mounted / unmounted
fsPointer to new file system object (NULL for unmount only)
Returns:
FR_OK, FR_INVALID_DRIVE
See also:
fileSystSMC
fMountSMC()
uint8_t extractDrive ( const TCHAR **  path)

Extract drive number from path.

This function checks if **path points to character sequence starting with "x:" where x may be '0..9', 'a..j' or 'A..J'. If so, *path is incremented by 2 (to point past the :) and 0.. 9 is returned according to the first character. Otherwise 0 is returned (respectively the current drive if enabled).

Parameters:
pathPointer to pointer to the path name ([d:]path)
Returns:
drive / volume number in the range 0..9 (default 0)
FRESULT checkValidFS ( uint8_t  vol)

Check if there's a valid mounted file system on the drive.

This function checks if drive number vol is ready and has a valid recognised file system. In that case FR_OK is returned and file system operations can be used without further preparations or delays.

FR_NO_FILESYSTEM means, of course, no file system has been detected yet. That means it has either not yet been looked for (and all else is OK) or the medium is not formatted with a file system usable by this fatFS implementation.

FR_INVALID_DRIVE means no valid volume number.
FR_NOT_ENABLED means no FS structure assigned.
FR_NOT_READY means drive down or medium removed

Parameters:
voldrive number 0.. (at present only 0 is valid)
Returns:
FR_OK (0); FR_INVALID_DRIVE FR_NOT_ENABLED FR_NO_FILESYSTEM FR_NOT_READY
See also:
getValidFS
FRESULT getValidFS ( uint8_t  vol,
FATFS **  fatfs 
)

Get the file system for the drive.

Exactly like checkValidFS() this function checks if drive number vol is ready and has a valid recognised file system. In that sense getValidFS() is a substitute for checkValidFS().

Additionally it returns the (pointer to the) file system structure assigned with drive vol in parameter fatfs if that is possible.

Parameters:
voldrive number 0.. (at present only 0 is valid)
fatfsPointer to pointer to the file system object to return
Returns:
FR_OK (0); FR_INVALID_DRIVE FR_NOT_ENABLED FR_NO_FILESYSTEM FR_NOT_READY
See also:
checkValidFS()
FRESULT checkWriteProtect ( uint8_t  vol)

Check if the drive is write protected.

This function checks if drive number vol is writable. In that case FR_OK is returned. This result only makes sense it / respectively requires that the drive is been checked / initialised as usable. Otherwise FR_NOT_READY may be returned.

For a usable but write protected drive and file FR_WRITE_PROTECTED will be returned. At present this will not happen on weAutSys / weAut_01 Communication with a small memory card (via SPI) SMC implementations as those slots do not have write protect switches. Nevertheless later versions may add write protect as software feature.

Parameters:
voldrive number 0.. (at present only 0 is valid)
Returns:
FR_OK (0); FR_NOT_READY FR_WRITE_PROTECTED
FRESULT lookForFS ( uint8_t  vol)

Look for a recognised file system on the drive.

This function checks if drive number vol is ready and looks for a valid recognised file system on it. If that is or was discovered FR_OK is returned and file system operations can be used without further preparations or delays.

FR_NO_FILESYSTEM means all else is OK but no file system can be detected on that drive respectively medium. The only remedy (on present weAutSys / weAut_01 Communication with a small memory card (via SPI) SMC implementations) is to remove the medium and format it with a suitable file system (preferably FAT32).

FR_INVALID_DRIVE means no valid volume number.
FR_NOT_ENABLED means no FS structure assigned.
FR_NOT_READY means drive down or medium removed

Parameters:
voldrive number 0.. (at present only 0 is valid)
Returns:
FR_OK (0); FR_INVALID_DRIVE FR_NOT_ENABLED FR_NO_FILESYSTEM FR_NOT_READY
FRESULT f_open ( FIL fp,
const TCHAR *  path,
uint8_t  mode 
)

Open or create a file.

If this function f_open 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 f_close(). If the modified file is not closed, the file data can be corrupted.

Before using any file function, a work area (file system object) must be registered to the logical drive with f_mount(). All functions except f_fdisk function can work after this procedure.

The parameter mode can be ORed using the predefined mode flags:

Examples:
main.c.
FRESULT f_read ( FIL fp,
void *  buff,
uint16_t  btr,
uint16_t *  br 
)

Read data from a file.

This function reads file data to the buffer supplied. The file object's file pointer increases by the number of bytes read. After the function succeeded, *br should be checked to detect the end of file. In the case of *br < btr the read/write pointer reached end of the file during the read operation.

Parameters:
fpPointer to file object
buffPointer to data buffer
btrNumber of bytes to read
brPointer to result: number of bytes read
This number must not be greater than the sector size (512)
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
Examples:
main.c.
FRESULT f_close ( FIL fp)

Close an open file object.

This function closes an open file. If any data have been written to the file, the cached information is written back to the medium (SMC). After the function succeeded, the file object is no longer valid.

Parameters:
fpPointer to file object
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
Examples:
main.c.
FRESULT f_lseek ( FIL fp,
uint32_t  ofs 
)

Move file pointer of a file object, expand file size.

This function moves the file read/write pointer of an open file. The offset is absolute, i.e. from file origin resp. top of file. When an offset above the file size is specified in write mode, the file size is increased and the data in the expanded area are undefined. Thereby is is possible to create a large file quickly. After the f_lseek function succeeded, current read/write pointer should be checked to make sure the read/write pointer has been moved correctly. In case of the current read/write pointer is not the expected value, either of followings has occured:

  • End of file. The specified Offset was clipped at end of the file because the file has been opened in read-only mode.
  • Disk full. There is insufficient free space on the volume to expand the file size.

Fast seek feature is enabled when _USE_FASTSEEK is set to 1 and the member .cltbl in the file object is not NULL. This feature enables fast backward/long seek operations without FAT access by cluster link map table (CLMT) stored in the user defined table. It is also applied to the functions f_read() and f_write(). In this mode, the file size cannot be increased by f_write() or f_lseek(). The CLMT must be created in the user defined DWORD array prior to use fast seek feature. To create the CLMT, let the member .cltbl in the file object pointer to the DWORD array. Set the array size in unit of items into the first item and call the f_lseek function with Offset = CREATE_LINKMAP. After the function succeeded and CLMT is created, no FAT access will occur in subsequent f_read(), f_write() or f_lseek() calls on that file. If the function failed with FR_NOT_ENOUGH_CORE, the given array size is insufficient for the file and the required items 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.

Parameters:
fpPointer to the file object
ofsFile pointer from top of file
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
FRESULT f_opendir ( DIR dj,
const TCHAR *  path 
)

Open an existing directory.

This function opens an existing directory and creates the directory object for subsequent calls of directory related functions. The directory object can be discarded at any time.

Parameters:
pathPointer to the directory's file name (0-terminated)
djPointer to directory object to create
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE
FRESULT f_readdir ( DIR dj,
FILINFO fno 
)

Read a directory item.

This function reads directory entries in sequence. All items in the directory can be read by repeated calls. When all directory entries have been thus visited the function just puts a null string into fno.f_name[]. When a null pointer is given to the FileInfo, the read index of the directory object will be rewound.

When LFN feature is enabled, lfname and lfsize in the file information structure must be initialized with valid value prior to use the f_readdir function. The lfname is a pointer to the string buffer to return the long file name. The lfsize is the size of the string buffer in unit of TCHAR. If either the size of read buffer or LFN working buffer is insufficient for the LFN or the object has no LFN, a null string will be returned to the LFN read buffer. If the LFN contains any character that cannot be converted to OEM code, a null string will be returned but this is not the case on Unicode API configuration. When lfname is NULL, nothing of the LFN is returned. When the object has no LFN, some small capitals can be contained in the SFN.

When relative path feature is enabled (_FS_RPATH == 1), "." and ".." entries are not filtered out and it will appear in the read entries.

This function is available if _FS_MINIMIZE <= 1.

Parameters:
djPointer to the open directory object
fnoPointer to the file information to be set with next entry's information; fno == NUL means reset to first directory entry
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT, FR_NOT_ENOUGH_CORE
FRESULT f_stat ( const TCHAR *  path,
FILINFO fno 
)

Get file status.

This function gets the size, timestamp and attribute of a file or directory. For details of the information, refer to the FILINFO structure and f_readdir().

This function is not available in minimization level of >= 1.

Parameters:
pathPointer to the directory's file name (0-terminated)
fnoPointer to the file information
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE
FRESULT f_write ( FIL fp,
const void *  buff,
uint16_t  btw,
uint16_t *  bw 
)

Write data to a file.

The read/write pointer in the file object is increased by the number of bytes written. After the function succeeded, *bw should be checked to detect the disk full condition. In case of *bw < btw there was not enough space for the (complete) write operation.

The function may require more time when the volume is full or nearly so.

Parameters:
fpPointer to the file object
buffPointer to data buffer
btwNumber of bytes to write
This number must not be greater than the sector size (512)
bwPointer to result: number of bytes written
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
FRESULT f_getfree ( const uint8_t  vol,
uint32_t *  nclst 
)

Get the number of free clusters on the drive.

This function gets number of free clusters on the drive. The member csize in the file system object is the number of sectors per cluster, so that the free space in unit of sector can be calculated. When FSInfo structure on FAT32 volume is not in sync, this function may return an incorrect free cluster count.

This function is available if _FS_READONLY == 0 and _FS_MINIMIZE == 0.

Parameters:
volthe drive's volume number (0..9); to extract form a path name use extractDrive(&path)
nclstPointer to result: number of free clusters (not NULL!)
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT
FRESULT f_truncate ( FIL fp)

Truncate file.

This function truncates the file size to the current file read/write point. This function has no effect if the file read/write pointer is already pointing end of the file.

This function is available if _FS_READONLY == 0 and _FS_MINIMIZE == 0.

Parameters:
fpPointer to the file object
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
FRESULT f_sync ( FIL fp)

Flush written / cached data to a file.

This function transfers write data caches in memory / sector buffers to the device. (The process and the related functions is normally called flush.) The function f_close() does, of course, the same before discarding the file object.

Calling this function periodically or after every f_write() can reduce the risk of data loss due to power failure or SMC removal at all costs of otherwise unnecessary device accesses.

Parameters:
fpPointer to the file object
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
FRESULT f_unlink ( const TCHAR *  path)

Delete an existing file or directory.

If the object to be erased / removed has a read-only attribute (AM_RDO) the operation will be rejected with FR_DENIED.

To remove a directory it must be empty and must not be current directory or the operation will be rejected with FR_DENIED.

A file to be removed must not be open or the FAT volume can collapse.

This function is available if _FS_READONLY == 0 and _FS_MINIMIZE == 0.

Parameters:
pathPointer to the directory's file name (0-terminated)
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_DENIED, FR_EXIST, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_LOCKED, FR_NOT_ENOUGH_CORE
FRESULT f_mkdir ( const TCHAR *  path)

Create a new directory.

This function is available if _FS_READONLY == 0 and _FS_MINIMIZE == 0.

Parameters:
pathPointer to the directory's file name (0-terminated)
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME, FR_DENIED, FR_EXIST, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE
FRESULT f_chmod ( const TCHAR *  path,
uint8_t  value,
uint8_t  mask 
)

Change attribute of the file or directory.

This function will set and/or clear the attributes AM_RDO (read only), AM_ARC (archive), AM_SYS (system) and AM_HID (hidden) of the file or directory specified. The parameters value and mask are OR expressions of the attribute masks named. Setting (value ) has preference over clearing (mask ).

This function is available if _FS_READONLY == 0 and _FS_MINIMIZE == 0.

Parameters:
pathPointer to the file name (0-terminated)
valueAttribute flags to be set
maskAttribute flag to be cleared
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE
FRESULT f_utime ( const TCHAR *  path,
const FILINFO fno 
)

Change time-stamps of a file or directory.

Parameters:
pathPointer to the file/directory name
fnoPointer to a FILINFO structure with .fdate and .ftime values to be set to the file respectively directory
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE
FRESULT f_rename ( const TCHAR *  path_old,
const TCHAR *  path_new 
)

Rename or move a file or directory.

This function renames an object (file or directory) and can also move it to other directory. The logical drive number is determined by old name, new name must not contain a logical drive number.

Do not rename open objects.

This function is available if _FS_READONLY == 0 and _FS_MINIMIZE == 0.

Parameters:
path_oldPointer to the current name / path
path_newPointer to the new name / path
Returns:
FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_DENIED, FR_EXIST, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_LOCKED, FR_NOT_ENOUGH_CORE
FRESULT f_fdisk ( uint8_t  pdrv,
const uint32_t  szt[],
void *  work 
)

Divide a physical drive into some partitions.

This 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 up to four primary partitions. Extended partition is not supported. The parameter szt 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.

This function is available if _MULTI_PARTITION == 2

Parameters:
pdrvPhysical drive number
sztPointer to the size table for each partition
workPointer to the working buffer. The size must be at least _MAX_SS bytes.
Returns:
FR_OK, FR_DISK_ERR, FR_NOT_READY, FR_WRITE_PROTECTED, FR_INVALID_PARAMETER