API  2.2
TSmarT Software Library
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

Functions

FRESULT f_open (FIL *fp,const TCHAR *path,BYTE mode)
 f_open function More...
 
FRESULT f_close (FIL *fp)
 f_close function More...
 
FRESULT f_read (FIL *fp,void *buff,UINT btr,UINT *br)
 f_read function More...
 
FRESULT f_write (FIL *fp,const void *buff,UINT btw,UINT *bw)
 f_write function More...
 
FRESULT f_lseek (FIL *fp,DWORD ofs)
 f_lseek function More...
 
FRESULT f_truncate (FIL *fp)
 f_truncate function More...
 
FRESULT f_sync (FIL *fp)
 f_sync function More...
 
FRESULT f_opendir (DIR *dp,const TCHAR *path)
 f_opendir function More...
 
FRESULT f_closedir (DIR *dp)
 f_closedir function More...
 
FRESULT f_readdir (DIR *dp,FILINFO *fno)
 f_readdir function More...
 
FRESULT f_mkdir (const TCHAR *path)
 f_mkdir function More...
 
FRESULT f_unlink (const TCHAR *path)
 f_unlink function More...
 
FRESULT f_rename (const TCHAR *path_old,const TCHAR *path_new)
 f_rename function More...
 
FRESULT f_stat (const TCHAR *path,FILINFO *fno)
 f_stat function More...
 
FRESULT f_chmod (const TCHAR *path,BYTE value,BYTE mask)
 f_chmod function More...
 
FRESULT f_utime (const TCHAR *path,const FILINFO *fno)
 f_utime function More...
 
FRESULT f_getfree (const TCHAR *path,DWORD *nclst,FATFS **fatfs)
 f_getfree function More...
 
FRESULT f_mount (FATFS *fs,const TCHAR *path,BYTE opt)
 f_mount function More...
 

Detailed Description

Function Documentation

FRESULT f_chmod ( const TCHAR *  path,
BYTE  value,
BYTE  mask 
)

f_chmod function

The f_chmod function changes the attribute of a file or sub-directory. The f_chmod() function changes the attribute of a file or sub-directory.

Parameters
pathPointer to the null-terminated string that specifies an object to be changed
valueAttribute flags to be set in one or more combination of the following flags. The specified flags are set and others are cleard.
  • AM_RDO Read only
  • AM_ARC Archive
  • AM_SYS System
  • AM_HID Hidden
maskAttribute mask that specifies which attribute is changed. The specified attributes are set or cleard and others are left unchanged.
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_close ( FIL fp)

f_close function

The f_close function closes an open file. The f_close() 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. Note that if the file object is in read-only mode and _FS_LOCK option is not enabled, the file object can also be discarded without this process. However this is not recommended for future compatibility.

Parameters
fpPointer to the open file object structure to be closed.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
Examples:
sd_fatfs.c.
FRESULT f_closedir ( DIR dp)

f_closedir function

The f_closedir function closes an open directory. The f_closedir() function closes an open directory object. After the function succeeded, the directory object is no longer valid and it can be discarded. Note that the directory object can also be discarded without this process if _FS_LOCK option is not enabled. However this is not recommended for future compatibility.

Parameters
dpPointer to the open directory object structure to be closed.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME, FR_INVALID_OBJECT, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES
FRESULT f_getfree ( const TCHAR *  path,
DWORD *  nclst,
FATFS **  fatfs 
)

f_getfree function

The f_getfree function gets number of the free clusters on the volume. The f_getfree() function gets number of free clusters on the volume. The member csize in the file system object indicates number of sectors per cluster, so that the free space in unit of sector can be calcurated with this information. When FSINFO structure on the FAT32 volume is not in sync, this function can return an incorrect free cluster count. To avoid this problem, FatFs can be forced full FAT scan by _FS_NOFSINFO option.

Parameters
pathPointer to the null-terminated string that specifies the logical drive. A null-string means the default drive.
nclstPointer to the DWORD variable to store number of free clusters.
fatfsPointer to pointer that to store a pointer to the corresponding file system object.
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_lseek ( FIL fp,
DWORD  ofs 
)

f_lseek function

The f_lseek function moves the file read/write pointer of an open file object. It can also be used to expand the file size (cluster pre-allocation). The f_lseek() 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 f_lseek() 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. End of file. The specified ofs 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. 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 using CLMT (cluster link map table). The fast seek feature is also applied to f_read()/f_write() function, however, the file size cannot be expanded by f_write()/f_lseek() function. The CLMT must be created in the user defined DWORD array prior to use the fast seek feature. To create the CLMT, set address of the DWORD array to the member cltbl in the file object, set the array size in unit of items into the first item and call the f_lseek() function with ofs = CREATE_LINKMAP. After the function succeeded and CLMT is created, no FAT access is occured at subsequent f_read()/f_write()/f_lseek() function to the file. If the function failed with FR_NOT_ENOUGH_CORE, 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.

Parameters
fpPointer to the open file object.
ofsByte offset from top of the file.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
Examples:
sd_fatfs.c.
FRESULT f_mkdir ( const TCHAR *  path)

f_mkdir function

The f_mkdir function creates a new directory. This function creates a new directory.

Parameters
pathPointer to the null-terminated string that specifies the directory name to create.
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_mount ( FATFS fs,
const TCHAR *  path,
BYTE  opt 
)

f_mount function

The f_mount function registers/unregisters file system object to the FatFs module.

Parameters
fsPointer to the new file system object to be registered. Null pointer unregisters the registered file system object.
pathPointer to the null-terminated string that specifies the logical drive. The string with no drive number means the default drive.
optInitialization option. 0: Do not mount now (to be mounted later), 1: Force mounted the volume to check if the FAT volume is available.
Returns
  • FR_OK, FR_INVALID_DRIVE, FR_DISK_ERR, FR_NOT_READY, FR_NO_FILESYSTEM
Examples:
sd_fatfs.c.
FRESULT f_open ( FIL fp,
const TCHAR *  path,
BYTE  mode 
)

f_open function

The f_open function creates a file object to be used to access the file. The f_mount() function registers/unregisters a file system object used for the logical drive to the FatFs module as follows: Determines the logical drive which specified by path. Clears and unregisters the regsitered work area of the drive. Clears and registers the new work area to the drive if fs is not NULL. Performs volume mount process to the drive if forced mount is specified. 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 f_fdisk() function. To unregister a work area, specify a NULL to the fs, and then the work area can be discarded. 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. File system object is not initialized. It is cleared by f_mount(). Physical drive is not initialized. It is de-initialized by system reset or media removal. 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. If implementation of the disk I/O layer lacks media change detection, application program needs to perform a f_mount() after each media change to force cleared the file system object.

Parameters
fpPointer to the blank file object structure to be created.
pathPointer to a null-terminated string that specifies the file name to create or open.
modeMode flags that specifies the type of access and open method for the file. It is specified by a combination of following flags.
  • FA_READ Specifies read access to the object. Data can be read from the file. Combine with FA_WRITE for read-write access.
  • FA_WRITE Specifies write access to the object. Data can be written to the file. Combine with FA_READ for read-write access.
  • FA_OPEN_EXISTING Opens the file. The function fails if the file is not existing. (Default)
  • FA_OPEN_ALWAYS Opens the file if it is existing. If not, a new file is created. To append data to the file, use f_lseek() function after file open in this method.
  • FA_CREATE_NEW Creates a new file. The function fails with FR_EXIST if the file is existing.
  • FA_CREATE_ALWAYS Creates a new file. If the file is existing, it will be truncated and overwritten.
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_INVALID_OBJECT, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_LOCKED, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES
Examples:
sd_fatfs.c.
FRESULT f_opendir ( DIR dp,
const TCHAR *  path 
)

f_opendir function

The f_opendir function opens a directory. The f_opendir() function opens an exsisting directory and creates a directory object for subsequent f_readdir() function.

Parameters
dpPointer to the blank directory object to create a new one
pathPinter to the null-terminated string that specifies the directory name to be opened.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME, FR_INVALID_OBJECT, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES
FRESULT f_read ( FIL fp,
void *  buff,
UINT  btr,
UINT *  br 
)

f_read function

The f_read function reads data from a file. The file read/write pointer of the file object advances number of bytes read. After the function succeeded, *br should be checked to detect the end of file. In case of *br is less than btr, it means the read/write pointer reached end of the file during read operation.

Parameters
fpPointer to the open file object.
buffPointer to the buffer to store read data.
btrNumber of bytes to read in range of UINT type.
brPointer to the UINT variable to return number of bytes read. The value is always valid after the function call regardless of the result.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
FRESULT f_readdir ( DIR dp,
FILINFO fno 
)

f_readdir function

The f_readdir function reads directory entries. The f_readdir() function reads directory items, file and directory, in sequence. All items in the directory can be read by calling f_readdir() function repeatedly. When relative path feature is enabled (_FS_RPATH >= 1), dot entries ("." and "..") are not filtered out and they will appear in the read items. When all directory items have been read and no item to read, a null string is returned into the fname[] without any error. When a null pointer is given to the fno, the read index of the directory object is rewinded. When LFN feature is enabled, lfname and lfsize in the file information structure must be initialized with valid value prior to use it. The lfname is a pointer to the LFN read buffer. The lfsize is size of the LFN read buffer in unit of TCHAR. If the LFN is not needed, set a null pointer to the lfname and the LFN is not returned. A null string will be returned into the LFN read buffer in case of following conditions. The directory item has no LFN information. Either the size of read buffer or LFN working buffer is insufficient for the LFN. The LFN contains any Unicode character that cannot be converted to OEM code. (not the case at Unicode API cfg.) When the directory item has no LFN information, lower case characters can be contained in the fname[].

Parameters
dpPointer to the open directory object.
fnoPointer to the file information structure to store the read item.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT, FR_NOT_ENOUGH_CORE
FRESULT f_rename ( const TCHAR *  path_old,
const TCHAR *  path_new 
)

f_rename function

Renames a file or sub-directory. Renames a file or sub-directory and can also move it to other directory within the same logical drive. Do not rename open objects or directry table can be broken.

Parameters
path_oldPointer to a null-terminated string that specifies an existing file or sub-directory to be renamed.
path_newPointer to a null-terminated string that specifies the new object name. The drive number specified in this string is ignored and one determined by old_name is used instead.
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_stat ( const TCHAR *  path,
FILINFO fno 
)

f_stat function

The f_stat function checks the existence of a file or sub-directory. The f_stat() function checks the existence of a file or sub-directory. If not exist, the function returns with FR_NO_FILE. If exist, the function returns with FR_OK 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 FILINFO structure and f_readdir() function.

Parameters
pathPointer to the null-terminated string that specifies the object to get its information.
fnoPointer to the blank FILINFO structure to store the information of the object. Set null pointer if it is not needed.
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_sync ( FIL fp)

f_sync function

The f_sync function flushes the cached information of a writing file. The f_sync() function performs the same process as f_close() 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 f_sync() function of periodic or immediataly after f_write() function can minimize the risk of data loss due to a sudden blackout or an unintentional media removal. For more information, refer to application note. However there is no sense in f_sync() function immediataly before f_close() function because it performs f_sync() function in it. In other words, the differnce between those functions is that the file object is invalidated or not.

Parameters
fpPointer to the open file object to be flushed.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
FRESULT f_truncate ( FIL fp)

f_truncate function

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

Parameters
fpPointer to the open file object to be truncated.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT
FRESULT f_unlink ( const TCHAR *  path)

f_unlink function

The f_unlink function removes a file or sub-directory. If condition of the object to be removed is applicable to the following terms, the function will be rejected. The file/sub-directory must not have read-only attribute (AM_RDO), or the function will be rejected with FR_DENIED. The sub-directory must be empty and must not be current directory, or the function will be rejected with FR_DENIED. The file/sub-directory must not be opened, or the FAT volume can be collapsed. It can be rejected with FR_LOCKED when file lock feature is enabled.

Parameters
pathPointer to the null-terminated string that specifies an object to be removed.
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_utime ( const TCHAR *  path,
const FILINFO fno 
)

f_utime function

The f_utime function changes the timestamp of a file or sub-directory. The The f_utime() function changes the timestamp of a file or sub-directory

Parameters
pathPointer to the null-terminated string that specifies an object to be changed.
fnoPointer to the file information structure that has a timestamp to be set in member fdate and ftime. Do not care any other members.
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_write ( FIL fp,
const void *  buff,
UINT  btw,
UINT *  bw 
)

f_write function

The f_write writes data to a file. The read/write pointer of the file object advances number of bytes written. After the function succeeded, *bw should be checked to detect the disk full. In case of *bw is less than btw, it means the volume got full during the write operation. The function can take a time when the volume is full or close to full.

Parameters
fpPointer to the open file object structure.
buffPointer to the data to be written.
btwSpecifies number of bytes to write in range of UINT type..
bwPointer to the UINT variable to return the number of bytes written. The value is always valid after the function call regardless of the result.
Returns
  • FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT