SD (File Operations)

The File class allows for reading from and writing to individual files on an SD card.

available

Description
Check if there are any bytes available for reading from the file.
Syntax
file.available()
Parameters
file: An instance of the File class (returned by SD.open())
Returns
The number of bytes available (int).

close

Description
Close the file and ensure that any data written to it is physically saved to the SD card.
Syntax
file.close()
Parameters
None
Returns
None

flush

Description
Ensures that any bytes written to the file are physically saved to the SD card. This is done automatically when the file is closed.
Syntax
file.flush()
Parameters
None
Returns
None

peek

Description
Read a byte from the file without advancing to the next one. That is, successive calls to peek() will return the same value, as will the next call to read().
Syntax
file.peek()
Parameters
None
Returns
The next byte (or character), or -1 if none is available.

position

Description
Get the current position within the file (i.e., the location to which the next byte will be read from or written to).
Syntax
file.position()
Parameters
None
Returns
The position within the file (unsigned long)

print

Description
Print data to the file, which must have been opened for writing. Prints numbers as a sequence of digits, each an ASCII character (i.e., The number 123 is sent as the three characters '1', '2', '3').
Syntax
file.print(data)
file.print(data, BASE)
Parameters
data: The data to print (char, byte, int, long, or string)
BASE (optional): The base in which to print numbers: BIN for binary (base 2), DEC for decimal (base 10), OCT for octal (base 8), HEX for hexadecimal (base 16).
Returns
Byte
print() will return the number of bytes written, though reading that number is optional.

println

Description
Print data, followed by a carriage return and newline, to the File, which must have been opened for writing. Prints numbers as a sequence of digits, each an ASCII character (i.e., The number 123 is sent as the three characters '1', '2', '3').
Syntax
file.println(data)
file.println(data, BASE)
Parameters
data: The numbers or character string to print
BASE: The base in which to print numbers (BYTE, BIN, DEC, HEX, OCT)
Returns
Byte
println() will return the number of bytes written, though reading that number is optional.

seek

Description
Seek to a new position in the file, which must be between 0 and the size of the file (inclusive).
Syntax
file.seek(unsigned long pos)
Parameters
pos: The position to which to seek (unsigned long)
Returns
True for success, false for failure (boolean).

size

Description
Get the size of the file.
Syntax
file.size()
Parameters
None
Returns
The size of the file in bytes (unsigned long).

read

Description
Reads a byte from the file.
Syntax
file.read()
Parameters
None
Returns
The next byte (or character), or -1 if none is available (or at the end of a file).

write

Description
Write data or character string to the file.
Syntax
file.write(data)
file.write(buf, len)
Parameters
data: The byte, char, or string (char *) to write
buf: An array of characters or bytes
len: The number of elements in buf.
Returns
Byte
write() will return the number of bytes written, though reading that number is optional.

isDirectory

Description
Directories (or folders) are special kinds of files, this function reports if the current file is a directory or not.
Syntax
file.isDirectory()
Parameters
None
Returns
True if directory, false if file.

openNextFile

Description
Reports the next file or folder in a directory.
Syntax
file.openNextFile()
Parameters
None
Returns
char: The next file or folder in the path.

rewindDirectory

Description
rewindDirectory() will bring you back to the first file in the directory, used in conjunction with openNextFile().
Syntax
file.rewindDirectory()
Parameters
None
Returns
None

Sample Program

This sample program runs a test of all operations (write, read, get size, remove) by accessing the Micro SD on the back of the GR-KAEDE board.


#include <Arduino.h>
#include <SD.h>
    
void setup(){
    Serial.begin(9600);
    while(!Serial.available()); // wait to press key
    Serial.read(); //dummy
        
    if(!SD.begin()){
        Serial.println("Card failed, or not present.");
        while(1);
    }
}
        
void loop(){
    File file = SD.open("sample.txt", FILE_WRITE);
    
    if(file){
        //Write
        Serial.println("Success to open sample.txt and write hello.");
        file.println("Hello, my SD");
        file.close();
            
        //Read
        file = SD.open("sample.txt", FILE_READ);
        Serial.println("Reading file...");
        while(file.available()){
            Serial.print((char)file.read());
            delay(50);
        }
        Serial.println();
            
        //Size
        Serial.print("File Size:");
        Serial.println(file.size());
        file.close();
        digitalWrite(PIN_LED0, 0);
            
        //Remove
        Serial.println("Remove the file? y/n");
        while(!Serial.available());
        if(Serial.read() == 'y'){
            SD.remove("sample.txt");
            Serial.println("sample.txt has been removed");
        }
        delay(400);
    
    } else {
        Serial.println("Failed to open file.");
        digitalWrite(PIN_LED0, 0);
        while(1);
    }
}