Directory operations

To organize an SD card, it is possible to create and manage directories. There are some functions related with directories.

Creating a directory

The mkdir() function creates a directory given as a valid directory path (according to short filename format) in the current working directory. The root directory is the default directory each time SD card is initialized.

It returns ‘1’ on creation and ‘0’ on error, activating the flag too.

If a directory name already exists, it will occur an error and the flag will be activated.

Example of use

{
 boolean dirCreation;
 char name[] = ”FOLDER1”;
 char path[] = ”FOLDER3/FOLDER4/FOLDER5”;
 // creates a directory in the current directory called “FOLDER1”
 dirCreation = SD.mkdir(name);
 // creates a directory in the current directory called “FOLDER2”
 dirCreation = SD.mkdir(“FOLDER2”);
 // creates a three-directory path in the current directory
 dirCreation = SD.mkdir(path);
}

Creating and deleting directories example: https://development.libelium.com/sd-05-create-delete-directories/

All directory names must be defined according to 8.3 short filename format (see section “Short filename format”) Be careful when calling this function to create a directory. If it is interrupted, the directory results damaged and it is necessary to delete it as a regular file using SD.del()

Deleting a directory

Empty directories

The rmdir() function deletes the empty directory specified as input. The directory file will be removed only if it is empty and is not the root directory.

It returns ‘1’ if the directory has been erased properly and ‘0’ if error.

It allows erasing a complete path of directories always they are empty.

Example of use

{
 const char name[] = ”FOLDER”;
 char path[] = ”FOLDER3/FOLDER4/FOLDER5”;
 uint8_t delState;
 // deletes the directory in the current directory called “FOLDER”
 delState = SD.rmdir(name);
 //deletes the directory in the current directory called “FOLDER2”
 delState = SD.rmdir (“FOLDER2”);
 //deletes a three-empty-directory path in the current directory
 dirCreation = SD.rmdir(path);
}

Creating and deleting directories example: https://development.libelium.com/sd-05-create-delete-directories/

Non-empty directories

The rmRfDir() function deletes the non-empty directory specified as input and all contained files. It returns ‘1’ if the directory has been erased properly and ‘0’ if error.

Example of use

{
 const char* name = ”FOLDER”;
 char* path = ”FOLDER3/FOLDER4/FOLDER5”;
 boolean delState;
 // deletes the directory in the current directory called “FOLDER”
 delState = SD.rmRfDir(name);
 // deletes the directory in the current directory called “FOLDER2”
 delState = SD.rmRfDir (“FOLDER2”);
 // deletes a three-directory path in the current directory
 dirCreation = SD.rmRfDir (“FOLDER3”);
}

Waspmote must not be switched off or reseted while there are ongoing deleting operations in the SD card. Otherwise, the SD card could be damaged and data could be lost. If you suspect that there may be some ongoing SD operations, wait a while until they are completed.

Directory listing

The ls() function prints through the USB port the contents of the current working directory. It is possible to introduce three different flags which may be an inclusive OR of:

LS_DATE - Print file modification date

LS_SIZE - Print file size.

LS_R - Recursive list of subdirectories.

It returns nothing. The information is printed through the USB port.

Example of use

{
   // lists the name of all the files of the directory indicating the size of the files
SD.ls();
   // lists the name of all files of the directory indicating the size of the files
SD.ls(LS_SIZE);
   // lists the name of all files of the directory indicating the date of the files
SD.ls(LS_DATE);
   // lists the name of all files of the directory and all subdirectories
SD.ls(LS_R);
   //lists the name of the files recursively indicating size and date
SD.ls(LS_R|LS_DATE|LS_SIZE);
}

An example of the output for SD.ls(LS_R|LS_DATE|LS_SIZE); would be:

FILE8 1980-01-01 00:00:00 204 FILE2 1980-01-01 00:00:00 2754 FOLDER/ 2000-01-01 01:00:00 SUBFOLD/ 2000-01-01 01:00:00 FILE.TXT 2012-06-11 11:58:10 811

Listing directories example: Creating and deleting directories example: https://development.libelium.com/sd-06-list-files

Finding a directory

The isDir() function finds a sub-directory in the current directory. If it exists and it is a directory ‘1’ will be returned, ‘0’ will be returned if it exists but it is not a directory and ‘-1’ will be returned if it does not exist.

Example of use

{
 uint8_t isdir;
 const char name[] = ”FOLDER”;
 // tests existence of “FOLDER” in the current directory
 isdir = SD.isDir(name);
 // tests existence of “FOLDER” in the current directory
 isdir = SD.isDir(“FOLDER”);
}

Number of files

The numFiles() function gets the amount of files and subdirectories in the current directory. It returns the number of files or directories found, or zero if there are no files or directories. It does not count ‘.’ and ‘..’ directories, so if there are no directories or files in the current directory, zero will be returned.

If an error occurs, a negative number is returned.

Example of use

{
 int8_t numfiles;
 // returns the number of files in the current directory
 numfiles = SD.numFiles();
}

Changing directory

The cd() functionchanges the current working directory pointer to the directory given as a parameter. It returns ‘0’ if error, and ‘1’ if not.

In root directory it has no sense changing directory to ‘..’, so function will return error when doing that.

Example of use

{
 uint8_t cdState;
 const char command[] = ”FOLDER”;
 // Change to directory specified in ‘command’
 cdState = SD.cd(command);
 // Go one directory up
 cdState = SD.cd(“..”);
}

Change current working directory example: https://development.libelium.com/sd-08-change-directories/

Go directly to root directory

The goRoot() function permits to go to root directory directly. It returns '1' when ok, '0' when error.

Example of use

{
 uint8_t cdState;
 // define the directory path to change
 char path[] = "/FOLD1/FOLD2/FOLD3/FOLD4/FOLD5";
 // Change to 'fold5' directory specified in ‘path’
 cdState = SD.cd(path);
 // Go to root directory
 cdState = SD.goRoot();
}