Access FAT16 and FAT32 files on SD and SDHC cards. More...
#include <SdFat.h>
Public Member Functions | |
SdFile (void) | |
Create an instance of SdFile. | |
void | clearUnbufferedRead (void) |
Cancel unbuffered reads for this file. | |
uint8_t | close (void) |
Close a file and force cached data and directory information to be written to the storage device. | |
uint8_t | contiguousRange (uint32_t *bgnBlock, uint32_t *endBlock) |
Check for contiguous file and return its raw block range. | |
uint8_t | createContiguous (SdFile *dirFile, const char *fileName, uint32_t size) |
Create and open a new contiguous file of a specified size. | |
uint32_t | curCluster (void) const |
uint32_t | curPosition (void) const |
uint32_t | dirBlock (void) const |
uint8_t | dirEntry (dir_t *dir) |
Return a files directory entry. | |
uint8_t | dirIndex (void) const |
uint32_t | fileSize (void) const |
uint32_t | firstCluster (void) const |
uint8_t | isDir (void) const |
uint8_t | isFile (void) const |
uint8_t | isOpen (void) const |
uint8_t | isSubDir (void) const |
uint8_t | isRoot (void) const |
void | ls (uint8_t flags=0, uint8_t indent=0) |
List directory contents to Serial. | |
uint8_t | makeDir (SdFile *dir, const char *dirName) |
Make a new directory. | |
uint8_t | open (SdFile *dirFile, uint16_t index, uint8_t oflag) |
Open a file by index. | |
uint8_t | open (SdFile *dirFile, const char *fileName, uint8_t oflag) |
Open a file or directory by name. | |
uint8_t | openRoot (SdVolume *vol) |
Open a volume's root directory. | |
int16_t | read (void) |
Read the next byte from a file. | |
int16_t | read (void *buf, uint16_t nbyte) |
Read data from a file starting at the current position. | |
int8_t | readDir (dir_t *dir) |
Read the next directory entry from a directory file. | |
uint8_t | remove (void) |
Remove a file. | |
void | rewind (void) |
Set the file's current position to zero. | |
uint8_t | rmDir (void) |
Remove a directory file. | |
uint8_t | rmRfStar (void) |
Recursively delete a directory and all contained files. | |
uint8_t | seekCur (uint32_t pos) |
Set the files position to current position + pos. | |
uint8_t | seekEnd (void) |
Set the files current position to end of file. | |
uint8_t | seekSet (uint32_t pos) |
Sets a file's position. | |
void | setUnbufferedRead (void) |
Use unbuffered reads to access this file. | |
uint8_t | timestamp (uint8_t flag, uint16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second) |
Set a file's timestamps in its directory entry. | |
uint8_t | sync (void) |
The sync() call causes all modified data and directory fields to be written to the storage device. | |
uint8_t | type (void) const |
Type of this SdFile. | |
uint8_t | truncate (uint32_t size) |
Truncate a file to a specified length. | |
uint8_t | unbufferedRead (void) const |
SdVolume * | volume (void) const |
void | write (uint8_t b) |
Write a byte to a file. | |
int16_t | write (const void *buf, uint16_t nbyte) |
Write data to an open file. | |
void | write (const char *str) |
Write a string to a file. | |
void | write_P (PGM_P str) |
Write a PROGMEM string to a file. | |
void | writeln_P (PGM_P str) |
Write a PROGMEM string followed by CR/LF to a file. | |
uint8_t | contiguousRange (uint32_t &bgnBlock, uint32_t &endBlock) |
uint8_t | createContiguous (SdFile &dirFile, const char *fileName, uint32_t size) |
uint8_t | dirEntry (dir_t &dir) |
uint8_t | makeDir (SdFile &dir, const char *dirName) |
uint8_t | open (SdFile &dirFile, const char *fileName, uint8_t oflag) |
uint8_t | open (SdFile &dirFile, const char *fileName) |
uint8_t | open (SdFile &dirFile, uint16_t index, uint8_t oflag) |
uint8_t | openRoot (SdVolume &vol) |
int8_t | readDir (dir_t &dir) |
Static Public Member Functions | |
static void | dateTimeCallback (void(*dateTime)(uint16_t *date, uint16_t *time)) |
Set the date/time callback function. | |
static void | dateTimeCallbackCancel (void) |
Cancel the date/time callback function. | |
static void | dirName (const dir_t &dir, char *name) |
Format the name field of dir into the 13 byte array name in standard 8.3 short name format. | |
static void | printDirName (const dir_t &dir, uint8_t width) |
Print the name field of a directory entry in 8.3 format to Serial. | |
static void | printFatDate (uint16_t fatDate) |
Print a directory date field to Serial. | |
static void | printFatTime (uint16_t fatTime) |
Print a directory time field to Serial. | |
static void | printTwoDigits (uint8_t v) |
Print a value as two digits to Serial. | |
static uint8_t | remove (SdFile *dirFile, const char *fileName) |
Remove a file. | |
static void | dateTimeCallback (void(*dateTime)(uint16_t &date, uint16_t &time)) |
static uint8_t | remove (SdFile &dirFile, const char *fileName) |
Public Attributes | |
bool | writeError |
writeError is set to true if an error occurs during a write(). |
SdFile::SdFile | ( | void | ) | [inline] |
void SdFile::clearUnbufferedRead | ( | void | ) | [inline] |
Cancel unbuffered reads for this file.
uint8_t SdFile::close | ( | void | ) |
Close a file and force cached data and directory information to be written to the storage device.
Definition at line 74 of file SdFile.cpp.
uint8_t SdFile::contiguousRange | ( | uint32_t * | bgnBlock, |
uint32_t * | endBlock | ||
) |
Check for contiguous file and return its raw block range.
[out] | bgnBlock | the first block address for the file. |
[out] | endBlock | the last block address for the file. |
Definition at line 91 of file SdFile.cpp.
uint8_t SdFile::contiguousRange | ( | uint32_t & | bgnBlock, |
uint32_t & | endBlock | ||
) | [inline] |
uint8_t SdFile::createContiguous | ( | SdFile * | dirFile, |
const char * | fileName, | ||
uint32_t | size | ||
) |
Create and open a new contiguous file of a specified size.
[in] | dirFile | The directory where the file will be created. |
[in] | fileName | A valid DOS 8.3 file name. |
[in] | size | The desired file size. |
Definition at line 129 of file SdFile.cpp.
uint8_t SdFile::createContiguous | ( | SdFile & | dirFile, |
const char * | fileName, | ||
uint32_t | size | ||
) | [inline] |
uint32_t SdFile::curCluster | ( | void | ) | const [inline] |
uint32_t SdFile::curPosition | ( | void | ) | const [inline] |
static void SdFile::dateTimeCallback | ( | void(*)(uint16_t &date, uint16_t &time) | dateTime | ) | [inline, static] |
static void SdFile::dateTimeCallback | ( | void(*)(uint16_t *date, uint16_t *time) | dateTime | ) | [inline, static] |
Set the date/time callback function.
[in] | dateTime | The user's call back function. The callback function is of the form: |
void dateTime(uint16_t* date, uint16_t* time) { uint16_t year; uint8_t month, day, hour, minute, second; // User gets date and time from GPS or real-time clock here // return date using FAT_DATE macro to format fields *date = FAT_DATE(year, month, day); // return time using FAT_TIME macro to format fields *time = FAT_TIME(hour, minute, second); }
Sets the function that is called when a file is created or when a file's directory entry is modified by sync(). All timestamps, access, creation, and modify, are set when a file is created. sync() maintains the last access date and last modify date/time.
See the timestamp() function.
uint32_t SdFile::dirBlock | ( | void | ) | const [inline] |
uint8_t SdFile::dirEntry | ( | dir_t * | dir | ) |
Return a files directory entry.
[out] | dir | Location for return of the files directory entry. |
Definition at line 158 of file SdFile.cpp.
uint8_t SdFile::dirEntry | ( | dir_t & | dir | ) | [inline] |
uint8_t SdFile::dirIndex | ( | void | ) | const [inline] |
void SdFile::dirName | ( | const dir_t & | dir, |
char * | name | ||
) | [static] |
Format the name field of dir into the 13 byte array name in standard 8.3 short name format.
[in] | dir | The directory structure containing the name. |
[out] | name | A 13 byte char array for the formatted name. |
Definition at line 178 of file SdFile.cpp.
uint32_t SdFile::fileSize | ( | void | ) | const [inline] |
uint32_t SdFile::firstCluster | ( | void | ) | const [inline] |
uint8_t SdFile::isDir | ( | void | ) | const [inline] |
uint8_t SdFile::isFile | ( | void | ) | const [inline] |
uint8_t SdFile::isOpen | ( | void | ) | const [inline] |
uint8_t SdFile::isRoot | ( | void | ) | const [inline] |
uint8_t SdFile::isSubDir | ( | void | ) | const [inline] |
void SdFile::ls | ( | uint8_t | flags = 0 , |
uint8_t | indent = 0 |
||
) |
List directory contents to Serial.
[in] | flags | The inclusive OR of |
LS_DATE - Print file modification date
LS_SIZE - Print file size.
LS_R - Recursive list of subdirectories.
[in] | indent | Amount of space before file name. Used for recursive list to indicate subdirectory level. |
Definition at line 201 of file SdFile.cpp.
uint8_t SdFile::makeDir | ( | SdFile * | dir, |
const char * | dirName | ||
) |
Make a new directory.
[in] | dir | An open SdFat instance for the directory that will containing the new directory. |
[in] | dirName | A valid 8.3 DOS name for the new directory. |
Definition at line 284 of file SdFile.cpp.
uint8_t SdFile::makeDir | ( | SdFile & | dir, |
const char * | dirName | ||
) | [inline] |
uint8_t SdFile::open | ( | SdFile & | dirFile, |
const char * | fileName, | ||
uint8_t | oflag | ||
) | [inline] |
uint8_t SdFile::open | ( | SdFile & | dirFile, |
uint16_t | index, | ||
uint8_t | oflag | ||
) | [inline] |
uint8_t SdFile::open | ( | SdFile * | dirFile, |
uint16_t | index, | ||
uint8_t | oflag | ||
) |
Open a file by index.
[in] | dirFile | An open SdFat instance for the directory. |
[in] | index | The index of the directory entry for the file to be opened. The value for index is (directory file position)/32. |
[in] | oflag | Values for oflag are constructed by a bitwise-inclusive OR of flags O_READ, O_WRITE, O_TRUNC, and O_SYNC. |
See open() by fileName for definition of flags and return values.
Definition at line 476 of file SdFile.cpp.
uint8_t SdFile::open | ( | SdFile * | dirFile, |
const char * | fileName, | ||
uint8_t | oflag | ||
) |
Open a file or directory by name.
[in] | dirFile | An open SdFat instance for the directory containing the file to be opened. |
[in] | fileName | A valid 8.3 DOS name for a file to be opened. |
[in] | oflag | Values for oflag are constructed by a bitwise-inclusive OR of flags from the following list |
O_READ - Open for reading.
O_RDONLY - Same as O_READ.
O_WRITE - Open for writing.
O_WRONLY - Same as O_WRITE.
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 - Call sync() after each write. This flag should not be used with write(uint8_t), write_P(PGM_P), writeln_P(PGM_P), or the Arduino Print class. These functions do character at a time writes so sync() will be called after each byte.
O_TRUNC - If the file exists and is a regular file, and the file is successfully opened and is not read only, its length shall be truncated to 0.
Definition at line 384 of file SdFile.cpp.
uint8_t SdFile::open | ( | SdFile & | dirFile, |
const char * | fileName | ||
) | [inline] |
uint8_t SdFile::openRoot | ( | SdVolume * | vol | ) |
Open a volume's root directory.
[in] | vol | The FAT volume containing the root directory to be opened. |
Definition at line 550 of file SdFile.cpp.
uint8_t SdFile::openRoot | ( | SdVolume & | vol | ) | [inline] |
void SdFile::printDirName | ( | const dir_t & | dir, |
uint8_t | width | ||
) | [static] |
Print the name field of a directory entry in 8.3 format to Serial.
[in] | dir | The directory structure containing the name. |
[in] | width | Blank fill name if length is less than width. |
Definition at line 585 of file SdFile.cpp.
void SdFile::printFatDate | ( | uint16_t | fatDate | ) | [static] |
Print a directory date field to Serial.
Format is yyyy-mm-dd.
[in] | fatDate | The date field from a directory entry. |
Definition at line 612 of file SdFile.cpp.
void SdFile::printFatTime | ( | uint16_t | fatTime | ) | [static] |
Print a directory time field to Serial.
Format is hh:mm:ss.
[in] | fatTime | The time field from a directory entry. |
Definition at line 626 of file SdFile.cpp.
void SdFile::printTwoDigits | ( | uint8_t | v | ) | [static] |
Print a value as two digits to Serial.
[in] | v | Value to be printed, 0 <= v <= 99 |
Definition at line 638 of file SdFile.cpp.
int16_t SdFile::read | ( | void | ) | [inline] |
int16_t SdFile::read | ( | void * | buf, |
uint16_t | nbyte | ||
) |
Read data from a file starting at the current position.
[out] | buf | Pointer to the location that will receive the data. |
[in] | nbyte | Maximum number of bytes to read. |
Definition at line 660 of file SdFile.cpp.
int8_t SdFile::readDir | ( | dir_t & | dir | ) | [inline] |
int8_t SdFile::readDir | ( | dir_t * | dir | ) |
Read the next directory entry from a directory file.
[out] | dir | The dir_t struct that will receive the data. |
Definition at line 724 of file SdFile.cpp.
static uint8_t SdFile::remove | ( | SdFile & | dirFile, |
const char * | fileName | ||
) | [inline, static] |
uint8_t SdFile::remove | ( | SdFile * | dirFile, |
const char * | fileName | ||
) | [static] |
Remove a file.
The directory entry and all data for the file are deleted.
[in] | dirFile | The directory that contains the file. |
[in] | fileName | The name of the file to be removed. |
Definition at line 810 of file SdFile.cpp.
uint8_t SdFile::remove | ( | void | ) |
Remove a file.
The directory entry and all data for the file are deleted.
Definition at line 774 of file SdFile.cpp.
void SdFile::rewind | ( | void | ) | [inline] |
uint8_t SdFile::rmDir | ( | void | ) |
Remove a directory file.
The directory file will be removed only if it is empty and is not the root directory. rmDir() follows DOS and Windows and ignores the read-only attribute for the directory.
Definition at line 831 of file SdFile.cpp.
uint8_t SdFile::rmRfStar | ( | void | ) |
Recursively delete a directory and all contained files.
This is like the Unix/Linux 'rm -rf *' if called with the root directory hence the name.
Warning - This will remove all contents of the directory including subdirectories. The directory will then be removed if it is not root. The read-only attribute for files will be ignored.
Definition at line 869 of file SdFile.cpp.
uint8_t SdFile::seekCur | ( | uint32_t | pos | ) | [inline] |
uint8_t SdFile::seekEnd | ( | void | ) | [inline] |
uint8_t SdFile::seekSet | ( | uint32_t | pos | ) |
Sets a file's position.
[in] | pos | The new position in bytes from the beginning of the file. |
Definition at line 916 of file SdFile.cpp.
void SdFile::setUnbufferedRead | ( | void | ) | [inline] |
Use unbuffered reads to access this file.
Used with Wave Shield ISR. Used with Sd2Card::partialBlockRead() in WaveRP.
Not recommended for normal applications.
uint8_t SdFile::sync | ( | void | ) |
The sync() call causes all modified data and directory fields to be written to the storage device.
Definition at line 957 of file SdFile.cpp.
uint8_t SdFile::timestamp | ( | uint8_t | flags, |
uint16_t | year, | ||
uint8_t | month, | ||
uint8_t | day, | ||
uint8_t | hour, | ||
uint8_t | minute, | ||
uint8_t | second | ||
) |
Set a file's timestamps in its directory entry.
[in] | flags | Values for flags are constructed by a bitwise-inclusive OR of flags from the following list |
T_ACCESS - Set the file's last access date.
T_CREATE - Set the file's creation date and time.
T_WRITE - Set the file's last write/modification date and time.
[in] | year | Valid range 1980 - 2107 inclusive. |
[in] | month | Valid range 1 - 12 inclusive. |
[in] | day | Valid range 1 - 31 inclusive. |
[in] | hour | Valid range 0 - 23 inclusive. |
[in] | minute | Valid range 0 - 59 inclusive. |
[in] | second | Valid range 0 - 59 inclusive |
Definition at line 1017 of file SdFile.cpp.
uint8_t SdFile::truncate | ( | uint32_t | length | ) |
Truncate a file to a specified length.
The current file position will be maintained if it is less than or equal to length otherwise it will be set to end of file.
[in] | length | The desired length for the file. |
Definition at line 1065 of file SdFile.cpp.
uint8_t SdFile::type | ( | void | ) | const [inline] |
uint8_t SdFile::unbufferedRead | ( | void | ) | const [inline] |
SdVolume* SdFile::volume | ( | void | ) | const [inline] |
int16_t SdFile::write | ( | const void * | buf, |
uint16_t | nbyte | ||
) |
Write data to an open file.
[in] | buf | Pointer to the location of the data to be written. |
[in] | nbyte | Number of bytes to write. |
Definition at line 1124 of file SdFile.cpp.
void SdFile::write | ( | uint8_t | b | ) |
Write a byte to a file.
Required by the Arduino Print class.
Use SdFile::writeError to check for errors.
Definition at line 1222 of file SdFile.cpp.
void SdFile::write | ( | const char * | str | ) |
Write a string to a file.
Used by the Arduino Print class.
Use SdFile::writeError to check for errors.
Definition at line 1231 of file SdFile.cpp.
void SdFile::write_P | ( | PGM_P | str | ) |
Write a PROGMEM string to a file.
Use SdFile::writeError to check for errors.
Definition at line 1240 of file SdFile.cpp.
void SdFile::writeln_P | ( | PGM_P | str | ) |
Write a PROGMEM string followed by CR/LF to a file.
Use SdFile::writeError to check for errors.
Definition at line 1249 of file SdFile.cpp.
bool SdFile::writeError |