File operations

To store data, files can be created and managed. There are some functions related to files operations.

Creating files

The create() function creates a file.

It returns ‘1’ on file creation and ‘0’ if error and it will mark the flag too.

Example of use

{
 const char name[] = ”FILE.TXT”;
 boolean fileCreation;
 // It creates a file named “FILE.TXT”
 fileCreation = SD.create(name);
 // It creates a file named “FILE.TXT”
 fileCreation = SD.create(“FILE.TXT”);
}

Creating and deleting files example: https://development.libelium.com/sd-01-create-delete-file/

All file names must be defined according to 8.3 short filename format (see section “Short filename format”)

The maximum number of files which can be created in the root directory are 341, while a 2nd level directory can store 1.000+ files. Thus, in the case the user needs to create hundreds of files in an SD card, it is highly advised to create them inside a 2nd level directory.

Deleting files

The del() function deletes a file in the current directory. It returns ‘1’ on file delete and ‘0’ if error.

Example of use

{
 const char name[] = ”FILE.TXT”;
 boolean fileDelete;
 // It deletes a file named “FILE.TXT”
 fileDelete = SD.del(name);
 // It deletes previously created file named “FILE.TXT”
 fileDelete = SD.del(“FILE.TXT”);
}

Creating and deleting files example: https://development.libelium.com/sd-01-create-delete-file/

Opening files

The openFile() function opens the filepath if available. It is possible to select a bitwise-inclusive OR of flags from the following list:

O_READ - Open for reading. O_WRITE - Open for writing. O_RDWR - Open for reading and writing. O_APPEND - If set, the file offset shall be set to the end of the file prior to each write. O_CREAT - If the file exists, this flag has no effect except as noted under O_EXCL below. Otherwise, the file shall be created O_EXCL - If O_CREAT and O_EXCL are set, open() shall fail if the file exists. O_SYNC - Synchronous writes

Returns '1' on success, '0' otherwise

Example of use

{
 const char filepath[] = ”FILE.TXT”;
 // declare an SdFile object
 SdFile file;
 // open “FILE” for reading
 SD.openFile( filepath, &file, O_READ);
}

All file names must be defined according to 8.3 short filename format (see section “Short filename format”)

Closing files

The closeFile() function closes the pointer which pointed to the previously defined file.

If a file is opened with previous function and it is not closed before using another file function, it will not work properly. Only one file pointer can be managed at the same time.

Example of use

{
 // previously declared file
 SdFile file;
 // close file, referencing the previously opened file
 SD.closeFile(&file);
}

Finding files

The isFile() function finds a file path in the current directory.

If it exists and it is a file ‘1’ will be returned, ‘0’ will be returned if it exists but it is not a file and ‘-1’ will be returned if it does not exist.

Example of use

{
 const char* name = ”FILE.TXT”;
 int8_t fileFound;
 // looks for “FILE.TXT” in the current directory
 fileFound = SD.isFile(name);
 // looks for “FILE.TXT” in the current directory
 fileFound = SD.isFile(“FILE.TXT”);
}

Reading data

The cat() function stores into the buffer the amount of bytes indicated as input. This function needs three input parameters:

• filename: string which defines the filename

• offset: number of bytes skipped from the beginning of the file to start reading

• scope: number of bytes to read from file from the offset indicated

The catln() function stores into the buffer the amount of lines indicated as input. This function needs three input parameters:

• filename: string which defines the filename

• offset: number of lines skipped from the beginning of the file to start reading

• scope: number of lines to read from file from the offset indicated

The information is returned as a string where each one of the characters are printed one after the next, EOL (‘\n’) will be encoded as EOL, and will be accounted as one byte.

There is a limitation in size, due to buffer size. If the data read was bigger than that, the function will include the characters “>>” at the end and activate the TRUNCATED_DATA value in the flag. It is recommended to check this value to ensure data integrity. If ‘offset’ or ‘scope’, or both of them, are greater than file size, there will be no error but only possible data will be copied into buffer.

Example of use

{
 const char name[] = ”FILE.TXT”;
 //It stores in ‘SD.buffer’ 17 characters after jumping 3
 SD.cat(name,3,17);
 //It stores in ‘SD.buffer’ 100 characters from the beginning
 SD.cat(name,0,100);
 //It stores in ‘SD.buffer’ 3 lines after jumping over the 2 first
 SD.catln(name,2,3);
}

• Reading files example: https://development.libelium.com/sd-04-read-file/

Writing data

There are several ways to write data to a file:

• Indicating the position to start writing. Function writeSD(). It is possible to indicate the amount of bytes to write.

• At the end of the file. Function append(). It is possible to indicate the amount of bytes to write.

• At the end of the file including an EOL character. Function appendln()

It returns ‘1’ on success and ‘0’ if error.

Due to buffer size, 256Bytes is the limit for writing data into a file at once. If more data needs to be written, it will have to be divided in blocks of 256Bytes.

Example of use

{
   const char* file = ”FILE.TXT”;
uint8_t writeState;
   // It writes “hello” on file at position 0
   writeState = SD.writeSD(file,”hello”,0);
   // It writes “hello” on file at position 5
   writeState = SD.writeSD(file,”hello”,5);
   // It writes “hel” on file at position 10
   writeState = SD.writeSD(file,”hello”,10,3);
   // It writes “hello” at the end of file
   writeState = SD.append(file,”hello”);
   // It writes “hel” on file at end of file
   writeState = SD.append(file,”hello”,3);
   // It writes “hello” at end of file with EOL
   writeState = SD.appendln(file,”hello”);
}

• Writing and appending data examples: https://development.libelium.com/sd-02-write-file/ https://development.libelium.com/sd-03-append-file/ https://development.libelium.com/sd-07-datalogger/

Number of lines

The numln() function counts the number of lines in a file.

The number of lines are counted as the number of ‘\n’ that are found in a file.

It returns the amount of lines and negative value if an error occurred. If there are no lines in file selected, zero will be returned.

Example of use

{
const char name[] = ”FILE.TXT”;
 int32_t numberLines;
 // counts number of lines in file named “FILE.TXT”
 numberLines = SD.numln(name);
 // counts number of lines in file named “FILE.TXT”
 numberLines = SD.numln(“FILE.TXT”);
}

Getting file size

The getFileSize() function gets the size of the selected file.

It returns its size in Bytes or ‘-1’ if an error occurs.

Example of use

{
 const char name[] = ”FILE.TXT”;
 int32_t sizeFile;
 // gets size of file named “FILE.TXT”
 sizeFile = SD.getFileSize(name);
 // gets size of file named “FILE.TXT”
 sizeFile = SD.getFileSize(“FILE.TXT”);
}

Available Information

A possible value would be: sizeFile=16 , indicating the size file is 16 Bytes.

Finding patterns

The indexOf() function looks into the file for the first occurrence of the pattern after a certain offset. The algorithm will jump over offset bytes before starting to search for the pattern.

It will return the amount of bytes to the pattern from the offset.

The special characters like ‘\n’ (EOL) are accounted as one byte and files are indexed from 0.

Example of use

{
 const char name[] = ”FILE.TXT”;
 int32_t pattern;
 // It returns position at which “11” appears on file jumping over first 17 positions
 pattern = SD.indexOf(name,”11”,17);
 // It returns position at which “11” is on file
 pattern = SD.indexOf(“FILE.TXT”,”11”,0);
}

Example file “FILE.TXT” contains: ‘hola caracola\nhej hej\n hola la[EOF]’

The following table shows the results from searching different patterns:

Function	Answer
SD.indexOf(“FILE.TXT”, “hola”, 0);	0
SD.indexOf(“FILE.TXT”, “hola”, 1);	23
SD.indexOf(“FILE.TXT”, “hej”, 3)	11

• Finding patterns example: https://development.libelium.com/sd-09-indexof-pattern/