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.
fsStatus	ffind (const char *pattern, fsFileInfo *info)
	Find a file or directory matching search pattern.
fsStatus	frename (const char *path, const char *newname)
	Rename a file or directory with given path name to a new name.
fsStatus	fattrib (const char *path, const char *attr)
	Change file attributes.

Description

The routines are thread safe.

Function Documentation

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

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 parameter
  arg  = "+R -S";
  path = "M0:\\Abstract.txt";

  if (fattrib (arg, path) != fsOK) {
    printf ("Failed to change file attributes.\n");
  }
  else {
    printf ("File attributes changed.\n");
  }
}

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

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");
  }
}

fsStatus ffind	(	const char *	pattern,
		fsFileInfo *	info
	)

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 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. 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

When file or directory matching 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 specified pattern.

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, function must be called repeatedly and in that case fileID shall not be changed until the search ends.

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
}

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

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.

Code Example

void tst_frename (void)  {

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