File System Component  Version 6.16.6
MDK Middleware for Devices with Flash File System
File Maintenance Routines

File maintenance routines perform file management operations. More...

Functions

fsStatus fdelete (const char *path, const char *options)
 Delete one or multiple files. More...
 
fsStatus ffind (const char *pattern, fsFileInfo *info)
 Find a file or directory matching search pattern. More...
 
fsStatus frename (const char *path, const char *newname)
 Rename a file or directory with given path name to a new name. More...
 
fsStatus fattrib (const char *path, const char *attr)
 Change file attributes. More...
 

Description

File maintenance routines perform file management operations.

The routines are thread safe.

Function Documentation

◆ fattrib()

fsStatus fattrib ( const char *  path,
const char *  attr 
)

Change file attributes.

Parameters
[in]pathstring specifying file or directory path.
[in]attrstring specifying file or directory attributes to be modified. The following characters are allowed within attr string:
  • + Sets an attribute.
  • - Clears an attribute.
  • R Read-only file attribute.
  • A Archive file attribute.
  • S System file attribute.
  • H Hidden file attribute.
Returns
execution status fsStatus
Note
This function supports FAT drives only.

The function fattrib changes file or directory attributes. File specified by the path argument shall not have any active file handle, otherwise the delete will fail and fsAccessDenied status code will be returned.

The path argument is specifying the file or directory path. If the drive prefix is omitted, the Current Drive is used.

The argument attr is specifying file or directory attributes to be modified. The following characters are allowed within par string:

Character Function
+ Sets an attribute
- Clears an attribute
R Read-only file attribute
A Archive file attribute
S System file attribute
H Hidden file attribute

Code Example

void cmd_attrib (void) {
char *arg, *path;
// Set parameters
path = "M0:\\Abstract.txt";
arg = "+R -S";
if (fattrib (path, arg) != fsOK) {
printf ("Failed to change file attributes.\n");
}
else {
printf ("File attributes changed.\n");
}
}

◆ fdelete()

fsStatus fdelete ( const char *  path,
const char *  options 
)

Delete one or multiple files.

Parameters
[in]patha string specifying the file or directory.
[in]optionsa string specifying function options.
Returns
execution status fsStatus

The function fdelete deletes one or more files. If path argument points to the existing file, it is removed. If path argument points to the directory, all files within that directory are removed. File(s) specified by the path argument shall not have any active file handle, otherwise the delete will fail and fsAccessDenied status code will be returned.

The path argument is specifying the file or directory path. If the drive prefix is omitted, the Current Drive is used.

The options argument can be NULL when options are not used or a pointer to a string specifying following options:

Option Description
/S Remove all files within specified directory and all subdirectories.

Code Example

void tst_fdelete (void) {
if (fdelete ("TEST.TXT", NULL) == fsOK) { // Delete a file from current drive.
printf ("Deleted: TEST.TXT\n");
}
if (fdelete ("R:DATA.LOG", NULL) == fsOK) { // Delete a file from RAM drive.
printf ("Deleted: DATA.LOG\n");
}
if (fdelete ("M:\\Work dir\\Temp log.txt", NULL) == fsOK) { // Delete a file from sub-folder.
printf ("Deleted: Temporary log.txt\n");
}
if (fdelete "M0:\\Working folder\\", NULL) == fsOK) { // Delete all files within a directory.
printf ("Deleted: Working folder.\n");
}
if (fdelete "M0:\\Working folder\\", "/S") == fsOK) { // Delete all files within a directory and its subdirectories.
printf ("Deleted: Working folder.\n");
}
}

◆ ffind()

fsStatus ffind ( const char *  pattern,
fsFileInfo info 
)

Find a file or directory matching search pattern.

Parameters
[in]patternstring specifying the pattern.
  • May include drive prefix and the following wildcards:
  • "*" or "*.*" searches for all files in the directory.
  • "abc*" searches for files that begin with abc.
  • "*.htm" searches for files that end with .htm.
  • "abc*.text" searches for files that begin with abc and that end with .text.
[out]infostructure storing information about matching files.
Returns
execution status fsStatus

The function ffind searches for files or directories that match a specific pattern. It can be used for explicit search, when full path is specified or iterative search, when using wildcard character within path.

The argument pattern is specifying the file or directory path. If the drive prefix is omitted, the Current Drive is used. If the drive prefix specifies non-existing drive function returns fsInvalidDrive status code. If targeted drive is not mounted fsAccessDenied is returned. Wildcard character * can be used when searching for multiple files. The following search rules apply:

Pattern Description
"*" or "*.*" Searches for all files in the directory
"abc*" Searches for files that begin with abc
"*.htm" Searches for files that end with .htm
"abc*.text" Searches for files that begin with abc and end with .text

If file or directory matching to the specified pattern is found, fsOK status code is returned and its name, size, attributes and time stamps are returned to the info structure. Status code fsFileNotFound is returned when function fails to find any file or directory that matches to the specified pattern.

If arguments pattern or info are NULL or if pattern specifies only directory path (i.e. ends with slash or backslash) the fsInvalidParameter status code is returned.

Member fileID of the fsFileInfo structure is used to control the file search and must be set to 0 (zero) before starting a new search.

When performing iterative search (using wildcard character), function must be called repeatedly and in that case fileID shall not be changed until the search ends. To re-start the search during iterative operation set fileID to 0 (zero). When performing search using full file name as search pattern (without wildcard character), fileID must be set to 0 (zero) before each search, otherwise fsError status code is returned.

Note
File attributes and time stamps are only supported on FAT drive and will not be returned if EFS drive is specified.

Code Example

void file_directory (void) {
fsFileInfo info;
info.fileID = 0; // info.fileID must be set to 0
while (ffind ("R:*.*", &info) == fsOK) { // find whatever is in drive "R0:"
printf ("\n%-32s %5d bytes, ID: %04d",
info.name,
info.size,
info.fileID);
}
}
bool log_exists (void) {
fsFileInfo info;
info.fileID = 0; // info.fileID must be set to 0
if (ffind ("R:\measure.log", &info) == fsOK) {
return (true); // log file exists
}
return (false); // log file not found
}

◆ frename()

fsStatus frename ( const char *  path,
const char *  newname 
)

Rename a file or directory with given path name to a new name.

Parameters
[in]pathstring specifying the file or directory path.
[in]newnamestring specifying new file or directory name.
Returns
execution status fsStatus

The function frename replaces the name of a file or directory. File specified by the path argument shall not have any active file handle, otherwise the rename will fail and fsAccessDenied status code will be returned.

The path argument is specifying the current name of the file or directory. If the drive prefix is omitted, the Current Drive is used.

The argument newname is specifying the new name of the file or directory. If newname is specifying a file or directory that already exists, function returns with status code fsAlreadyExists.

Code Example

void tst_frename (void) {
if (frename ("F:Test.txt", "New name.txt") == fsOK) {
printf ("Rename Successful.\n");
}
}