SD (File Operations)

The SD (File Operations) library 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 (e.g. 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 (e.g. 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 a 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.


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