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]	path	string specifying file or directory path.
[in]	attr	string 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]	path	a string specifying the file or directory.
[in]	options	a 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]	pattern	string 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]	info	structure 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]	path	string specifying the file or directory path.
[in]	newname	string 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");
  }
}

Functions

Description

Function Documentation

◆ fattrib()

◆ fdelete()

◆ ffind()

◆ frename()