SdFat

Public Member Functions | Static Public Member Functions | List of all members
FatFile Class Reference

Basic file class. More...

`#include <FatFile.h>`

Inheritance diagram for FatFile:
[legend]

## Public Member Functions
uint32_t | available ()
void | clearError ()
void | clearWriteError ()
bool | close ()
bool | contiguousRange (uint32_t *bgnBlock, uint32_t *endBlock)
bool | createContiguous (FatFile *dirFile, const char *path, uint32_t size)
bool | createContiguous (const char *path, uint32_t size)
uint32_t | curCluster () const
uint32_t | curPosition () const
bool | dirEntry (dir_t *dir)
uint16_t | dirIndex ()
uint32_t | dirSize ()
void | dmpFile (print_t *pr, uint32_t pos, size_t n)
bool | exists (const char *path)
| FatFile ()
| FatFile (const char *path, oflag_t oflag)
int16_t | fgets (char *str, int16_t num, char *delim=0)
uint8_t | fileAttr () const
uint32_t | fileSize () const
uint32_t | firstBlock ()
uint32_t | firstCluster () const
uint8_t | getError ()
bool | getName (char *name, size_t size)
void | getpos (FatPos_t *pos)
bool | getSFN (char *name)
bool | getWriteError ()
bool | isDir () const
bool | isFile () const
bool | isHidden () const
bool | isLFN () const
bool | isOpen () const
bool | isReadOnly () const
bool | isRoot () const
bool | isRoot32 () const
bool | isRootFixed () const
bool | isSubDir () const
bool | isSystem () const
void | ls (uint8_t flags=0)
void | ls (print_t *pr, uint8_t flags=0, uint8_t indent=0)
bool | mkdir (FatFile *dir, const char *path, bool pFlag=true)
bool | open (FatFileSystem *fs, const char *path, oflag_t oflag)
bool | open (FatFile *dirFile, uint16_t index, oflag_t oflag)
bool | open (FatFile *dirFile, const char *path, oflag_t oflag)
bool | open (const char *path, oflag_t oflag=O_RDONLY)
bool | openNext (FatFile *dirFile, oflag_t oflag=O_RDONLY)
bool | openRoot (FatVolume *vol)
int | peek ()
bool | printCreateDateTime (print_t *pr)
int | printField (float value, char term, uint8_t prec=2)
int | printField (int16_t value, char term)
int | printField (uint16_t value, char term)
int | printField (int32_t value, char term)
int | printField (uint32_t value, char term)
size_t | printFileSize (print_t *pr)
bool | printModifyDateTime (print_t *pr)
size_t | printName ()
size_t | printName (print_t *pr)
size_t | printSFN (print_t *pr)
int | read ()
int | read (void *buf, size_t nbyte)
int8_t | readDir (dir_t *dir)
bool | remove ()
bool | rename (FatFile *dirFile, const char *newPath)
void | rewind ()
bool | rmdir ()
bool | rmRfStar ()
bool | seekCur (int32_t offset)
bool | seekEnd (int32_t offset=0)
bool | seekSet (uint32_t pos)
void | setpos (FatPos_t *pos)
bool | sync ()
bool | timestamp (FatFile *file)
bool | timestamp (uint8_t flags, uint16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second)
bool | truncate (uint32_t length)
FatVolume * | volume () const
int | write (const char *str)
int | write (uint8_t b)
int | write (const void *buf, size_t nbyte)

## Static Public Member Functions
static FatFile * | cwd ()
static void | dateTimeCallback (void(*dateTime)(uint16_t *date, uint16_t *time))
static void | dateTimeCallbackCancel ()
static uint8_t | dirName (const dir_t *dir, char *name)
static bool | legal83Char (uint8_t c)
static void | printFatDate (uint16_t fatDate)
static void | printFatDate (print_t *pr, uint16_t fatDate)
static void | printFatTime (uint16_t fatTime)
static void | printFatTime (print_t *pr, uint16_t fatTime)
static bool | remove (FatFile *dirFile, const char *path)
static bool | setCwd (FatFile *dir)

## Detailed Description

Basic file class.

## Constructor & Destructor Documentation

## ◆ FatFile() [1/2]

FatFile::FatFile | ( |  | ) |
| inline

Create an instance.

## ◆ FatFile() [2/2]

FatFile::FatFile | ( | const char * | path,
|  | oflag_t | oflag
| ) |  |
| inline

Create a file object and open it in the current working directory.

Parameters

  [in] | path | A path with 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 open flags. see FatFile::open(FatFile*, const char*, oflag_t).

## Member Function Documentation

## ◆ available()

uint32_t FatFile::available | ( |  | ) |
| inline

Returns
  The number of bytes available from the current position to EOF for normal files. Zero is returned for directory files.

## ◆ clearError()

void FatFile::clearError | ( |  | ) |
| inline

Clear all error bits.

## ◆ clearWriteError()

void FatFile::clearWriteError | ( |  | ) |
| inline

Set writeError to zero

## ◆ close()

bool FatFile::close | ( |  | ) |

Close a file and force cached data and directory information to be written to the storage device.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ contiguousRange()

bool FatFile::contiguousRange | ( | uint32_t * | bgnBlock,
|  | uint32_t * | endBlock
| ) |  |

Check for contiguous file and return its raw block range.

Parameters

  [out] | bgnBlock | the first block address for the file.
  [out] | endBlock | the last block address for the file.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ createContiguous() [1/2]

bool FatFile::createContiguous | ( | FatFile * | dirFile,
|  | const char * | path,
|  | uint32_t | size
| ) |  |

Create and open a new contiguous file of a specified size.

Parameters

  [in] | dirFile | The directory where the file will be created.
  [in] | path | A path with a validfile name.
  [in] | size | The desired file size.

Returns
  The value true is returned for success and the value false, is returned for failure.

## ◆ createContiguous() [2/2]

bool FatFile::createContiguous | ( | const char * | path,
|  | uint32_t | size
| ) |  |
| inline

Create and open a new contiguous file of a specified size.

Parameters

  [in] | path | A path with a validfile name.
  [in] | size | The desired file size.

Returns
  The value true is returned for success and the value false, is returned for failure.

## ◆ curCluster()

uint32_t FatFile::curCluster | ( |  | ) | const
| inline

Returns
  The current cluster number for a file or directory.

## ◆ curPosition()

uint32_t FatFile::curPosition | ( |  | ) | const
| inline

Returns
  The current position for a file or directory.

## ◆ cwd()

static FatFile* FatFile::cwd | ( |  | ) |
| inline static

Returns
  Current working directory

## ◆ dateTimeCallback()

static void FatFile::dateTimeCallback | ( | void(*)(uint16_t *date, uint16_t *time) | dateTime | ) |
| inline static

Set the date/time callback function

Parameters

  [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.

## ◆ dateTimeCallbackCancel()

static void FatFile::dateTimeCallbackCancel | ( |  | ) |
| inline static

Cancel the date/time callback function.

## ◆ dirEntry()

bool FatFile::dirEntry | ( | dir_t * | dir | ) |

Return a file's directory entry.

Parameters

  [out] | dir | Location for return of the file's directory entry.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ dirIndex()

uint16_t FatFile::dirIndex | ( |  | ) |
| inline

Returns
  The index of this file in it's directory.

## ◆ dirName()

uint8_t FatFile::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.

Parameters

  [in] | dir | The directory structure containing the name.
  [out] | name | A 13 byte char array for the formatted name.

Returns
  length of the name.

## ◆ dirSize()

uint32_t FatFile::dirSize | ( |  | ) |

Returns
  The number of bytes allocated to a directory or zero if an error occurs.

## ◆ dmpFile()

void FatFile::dmpFile | ( | print_t * | pr,
|  | uint32_t | pos,
|  | size_t | n
| ) |  |

Dump file in Hex

Parameters

  [in] | pr | Print stream for list.
  [in] | pos | Start position in file.
  [in] | n | number of locations to dump.

## ◆ exists()

bool FatFile::exists | ( | const char * | path | ) |
| inline

Test for the existence of a file in a directory

Parameters

  [in] | path | Path of the file to be tested for.

The calling instance must be an open directory file.

dirFile.exists("TOFIND.TXT") searches for "TOFIND.TXT" in the directory dirFile.

Returns
  true if the file exists else false.

## ◆ fgets()

int16_t FatFile::fgets | ( | char * | str,
|  | int16_t | num,
|  | char * | delim = `0`
| ) |  |

Get a string from a file.

fgets() reads bytes from a file into the array pointed to by str, until num - 1 bytes are read, or a delimiter is read and transferred to str, or end-of-file is encountered. The string is then terminated with a null byte.

fgets() deletes CR, '\r', from the string. This insures only a '\n' terminates the string for Windows text files which use CRLF for newline.

Parameters

  [out] | str | Pointer to the array where the string is stored.
  [in] | num | Maximum number of characters to be read (including the final null byte). Usually the length of the array str is used.
  [in] | delim | Optional set of delimiters. The default is "\n".

Returns
  For success fgets() returns the length of the string in str. If no data is read, fgets() returns zero for EOF or -1 if an error occurred.

## ◆ fileAttr()

uint8_t FatFile::fileAttr | ( |  | ) | const
| inline

Type of file. You should use isFile() or isDir() instead of fileType() if possible.

Returns
  The file or directory type.

## ◆ fileSize()

uint32_t FatFile::fileSize | ( |  | ) | const
| inline

Returns
  The total number of bytes in a file.

## ◆ firstBlock()

uint32_t FatFile::firstBlock | ( |  | ) |
| inline

Returns
  first block of file or zero for empty file.

## ◆ firstCluster()

uint32_t FatFile::firstCluster | ( |  | ) | const
| inline

Returns
  The first cluster number for a file or directory.

## ◆ getError()

uint8_t FatFile::getError | ( |  | ) |
| inline

Returns
  All error bits.

## ◆ getName()

bool FatFile::getName | ( | char * | name,
|  | size_t | size
| ) |  |

Get a file's name followed by a zero byte.

Parameters

  [out] | name | An array of characters for the file's name.
  [in] | size | The size of the array in bytes. The array must be at least 13 bytes long. The file's name will be truncated if the file's name is too long.

Returns
  The value true, is returned for success and the value false, is returned for failure.

## ◆ getpos()

void FatFile::getpos | ( | FatPos_t * | pos | ) |

get position for streams

Parameters

  [out] | pos | struct to receive position

## ◆ getSFN()

bool FatFile::getSFN | ( | char * | name | ) |

Get a file's Short File Name followed by a zero byte.

Parameters

  [out] | name | An array of characters for the file's name. The array must be at least 13 bytes long.

Returns
  The value true, is returned for success and the value false, is returned for failure.

Copyright (c) 2011-2018 Bill Greiman This file is part of the SdFat library for SD memory cards.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

## ◆ getWriteError()

bool FatFile::getWriteError | ( |  | ) |
| inline

Returns
  value of writeError

## ◆ isDir()

bool FatFile::isDir | ( |  | ) | const
| inline

Returns
  True if this is a directory else false.

## ◆ isFile()

bool FatFile::isFile | ( |  | ) | const
| inline

Returns
  True if this is a normal file else false.

## ◆ isHidden()

bool FatFile::isHidden | ( |  | ) | const
| inline

Returns
  True if this is a hidden file else false.

## ◆ isLFN()

bool FatFile::isLFN | ( |  | ) | const
| inline

Returns
  true if this file has a Long File Name.

## ◆ isOpen()

bool FatFile::isOpen | ( |  | ) | const
| inline

Returns
  True if this is an open file/directory else false.

## ◆ isReadOnly()

bool FatFile::isReadOnly | ( |  | ) | const
| inline

Returns
  True if file is read-only

## ◆ isRoot()

bool FatFile::isRoot | ( |  | ) | const
| inline

Returns
  True if this is the root directory.

## ◆ isRoot32()

bool FatFile::isRoot32 | ( |  | ) | const
| inline

Returns
  True if this is the FAT32 root directory.

## ◆ isRootFixed()

bool FatFile::isRootFixed | ( |  | ) | const
| inline

Returns
  True if this is the FAT12 of FAT16 root directory.

## ◆ isSubDir()

bool FatFile::isSubDir | ( |  | ) | const
| inline

Returns
  True if this is a subdirectory else false.

## ◆ isSystem()

bool FatFile::isSystem | ( |  | ) | const
| inline

Returns
  True if this is a system file else false.

## ◆ legal83Char()

static bool FatFile::legal83Char | ( | uint8_t | c | ) |
| inline static

Check for a legal 8.3 character.

Parameters

  [in] | c | Character to be checked.

Returns
  true for a legal 8.3 character else false.

## ◆ ls() [1/2]

void FatFile::ls | ( | uint8_t | flags = `0` | ) |
| inline

List directory contents.

Parameters

  [in] | flags | The inclusive OR of

LS_DATE - Print file modification date

LS_SIZE - Print file size.

LS_R - Recursive list of subdirectories.

## ◆ ls() [2/2]

void FatFile::ls | ( | print_t * | pr,
|  | uint8_t | flags = `0`,
|  | uint8_t | indent = `0`
| ) |  |

List directory contents.

Parameters

  [in] | pr | Print stream for list.
  [in] | flags | The inclusive OR of

LS_DATE - Print file modification date

LS_SIZE - Print file size.

LS_R - Recursive list of subdirectories.

Parameters

  [in] | indent | Amount of space before file name. Used for recursive list to indicate subdirectory level.

## ◆ mkdir()

bool FatFile::mkdir | ( | FatFile * | dir,
|  | const char * | path,
|  | bool | pFlag = `true`
| ) |  |

Make a new directory.

Parameters

  [in] | dir | An open FatFile instance for the directory that will contain the new directory.
  [in] | path | A path with a valid 8.3 DOS name for the new directory.
  [in] | pFlag | Create missing parent directories if true.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ open() [1/4]

bool FatFile::open | ( | FatFileSystem * | fs,
|  | const char * | path,
|  | oflag_t | oflag
| ) |  |

Open a file in the volume working directory of a FatFileSystem.

Parameters

  [in] | fs | File System where the file is located.
  [in] | path | with a valid 8.3 DOS name for a file to be opened.
  [in] | oflag | bitwise-inclusive OR of open mode flags. See see FatFile::open(FatFile*, const char*, oflag_t).

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ open() [2/4]

bool FatFile::open | ( | FatFile * | dirFile,
|  | uint16_t | index,
|  | oflag_t | oflag
| ) |  |

Open a file by index.

Parameters

  [in] | dirFile | An open FatFile 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 | bitwise-inclusive OR of open mode flags. See see FatFile::open(FatFile*, const char*, oflag_t).

See open() by path for definition of flags.

Returns
  true for success or false for failure.

## ◆ open() [3/4]

bool FatFile::open | ( | FatFile * | dirFile,
|  | const char * | path,
|  | oflag_t | oflag
| ) |  |

Open a file or directory by name.

Parameters

  [in] | dirFile | An open FatFile instance for the directory containing the file to be opened.
  [in] | path | A path with 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_RDONLY - Open for reading.

O_READ - Same as O_RDONLY (GNU).

O_WRONLY - Open for writing.

O_WRITE - Same as O_WRONLY (GNU).

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_AT_END - Set the initial position at the end of the file.

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) or any functions do character at a time writes since 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.

WARNING: A given file must not be opened by more than one FatFile object or file corruption may occur.

Note
  Directory files must be opened read only. Write and truncation is not allowed for directory files.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ open() [4/4]

bool FatFile::open | ( | const char * | path,
|  | oflag_t | oflag = `O_RDONLY`
| ) |  |
| inline

Open a file in the current working directory.

Parameters

  [in] | path | A path with a valid 8.3 DOS name for a file to be opened.
  [in] | oflag | bitwise-inclusive OR of open mode flags. See see FatFile::open(FatFile*, const char*, oflag_t).

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ openNext()

bool FatFile::openNext | ( | FatFile * | dirFile,
|  | oflag_t | oflag = `O_RDONLY`
| ) |  |

Open the next file or subdirectory in a directory.

Parameters

  [in] | dirFile | An open FatFile instance for the directory containing the file to be opened.
  [in] | oflag | bitwise-inclusive OR of open mode flags. See see FatFile::open(FatFile*, const char*, oflag_t).

Returns
  true for success or false for failure.

## ◆ openRoot()

bool FatFile::openRoot | ( | FatVolume * | vol | ) |

Open a volume's root directory.

Parameters

  [in] | vol | The FAT volume containing the root directory to be opened.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ peek()

int FatFile::peek | ( |  | ) |

Return the next available byte without consuming it.

Returns
  The byte if no error and not at eof else -1;

## ◆ printCreateDateTime()

bool FatFile::printCreateDateTime | ( | print_t * | pr | ) |

Print a file's creation date and time

Parameters

  [in] | pr | Print stream for output.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ printFatDate() [1/2]

static void FatFile::printFatDate | ( | uint16_t | fatDate | ) |
| inline static

Print a directory date field.

Format is yyyy-mm-dd.

Parameters

  [in] | fatDate | The date field from a directory entry.

## ◆ printFatDate() [2/2]

void FatFile::printFatDate | ( | print_t * | pr,
|  | uint16_t | fatDate
| ) |  |
| static

Print a directory date field.

Format is yyyy-mm-dd.

Parameters

  [in] | pr | Print stream for output.
  [in] | fatDate | The date field from a directory entry.

## ◆ printFatTime() [1/2]

static void FatFile::printFatTime | ( | uint16_t | fatTime | ) |
| inline static

Print a directory time field.

Format is hh:mm:ss.

Parameters

  [in] | fatTime | The time field from a directory entry.

## ◆ printFatTime() [2/2]

void FatFile::printFatTime | ( | print_t * | pr,
|  | uint16_t | fatTime
| ) |  |
| static

Print a directory time field.

Format is hh:mm:ss.

Parameters

  [in] | pr | Print stream for output.
  [in] | fatTime | The time field from a directory entry.

## ◆ printField() [1/5]

int FatFile::printField | ( | float | value,
|  | char | term,
|  | uint8_t | prec = `2`
| ) |  |

Print a number followed by a field terminator.

Parameters

  [in] | value | The number to be printed.
  [in] | term | The field terminator. Use '\n' for CR LF.
  [in] | prec | Number of digits after decimal point.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printField() [2/5]

int FatFile::printField | ( | int16_t | value,
|  | char | term
| ) |  |

Print a number followed by a field terminator.

Parameters

  [in] | value | The number to be printed.
  [in] | term | The field terminator. Use '\n' for CR LF.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printField() [3/5]

int FatFile::printField | ( | uint16_t | value,
|  | char | term
| ) |  |

Print a number followed by a field terminator.

Parameters

  [in] | value | The number to be printed.
  [in] | term | The field terminator. Use '\n' for CR LF.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printField() [4/5]

int FatFile::printField | ( | int32_t | value,
|  | char | term
| ) |  |

Print a number followed by a field terminator.

Parameters

  [in] | value | The number to be printed.
  [in] | term | The field terminator. Use '\n' for CR LF.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printField() [5/5]

int FatFile::printField | ( | uint32_t | value,
|  | char | term
| ) |  |

Print a number followed by a field terminator.

Parameters

  [in] | value | The number to be printed.
  [in] | term | The field terminator. Use '\n' for CR LF.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printFileSize()

size_t FatFile::printFileSize | ( | print_t * | pr | ) |

Print a file's size.

Parameters

  [in] | pr | Print stream for output.

Returns
  The number of characters printed is returned for success and zero is returned for failure.

## ◆ printModifyDateTime()

bool FatFile::printModifyDateTime | ( | print_t * | pr | ) |

Print a file's modify date and time

Parameters

  [in] | pr | Print stream for output.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ printName() [1/2]

size_t FatFile::printName | ( |  | ) |
| inline

Print a file's name.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ printName() [2/2]

size_t FatFile::printName | ( | print_t * | pr | ) |

Print a file's name

Parameters

  [in] | pr | Print stream for output.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ printSFN()

size_t FatFile::printSFN | ( | print_t * | pr | ) |

Print a file's Short File Name.

Parameters

  [in] | pr | Print stream for output.

Returns
  The number of characters printed is returned for success and zero is returned for failure.

## ◆ read() [1/2]

int FatFile::read | ( |  | ) |
| inline

Read the next byte from a file.

Returns
  For success read returns the next byte in the file as an int. If an error occurs or end of file is reached -1 is returned.

## ◆ read() [2/2]

int FatFile::read | ( | void * | buf,
|  | size_t | nbyte
| ) |  |

Read data from a file starting at the current position.

Parameters

  [out] | buf | Pointer to the location that will receive the data.
  [in] | nbyte | Maximum number of bytes to read.

Returns
  For success read() returns the number of bytes read. A value less than nbyte, including zero, will be returned if end of file is reached. If an error occurs, read() returns -1. Possible errors include read() called before a file has been opened, corrupt file system or an I/O error occurred.

## ◆ readDir()

int8_t FatFile::readDir | ( | dir_t * | dir | ) |

Read the next directory entry from a directory file.

Parameters

  [out] | dir | The dir_t struct that will receive the data.

Returns
  For success readDir() returns the number of bytes read. A value of zero will be returned if end of file is reached. If an error occurs, readDir() returns -1. Possible errors include readDir() called before a directory has been opened, this is not a directory file or an I/O error occurred.

## ◆ remove() [1/2]

bool FatFile::remove | ( |  | ) |

Remove a file.

The directory entry and all data for the file are deleted.

Note
  This function should not be used to delete the 8.3 version of a file that has a long name. For example if a file has the long name "New Text Document.txt" you should not delete the 8.3 name "NEWTEX~1.TXT".

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ remove() [2/2]

bool FatFile::remove | ( | FatFile * | dirFile,
|  | const char * | path
| ) |  |
| static

Remove a file.

The directory entry and all data for the file are deleted.

Parameters

  [in] | dirFile | The directory that contains the file.
  [in] | path | Path for the file to be removed.

Note
  This function should not be used to delete the 8.3 version of a file that has a long name. For example if a file has the long name "New Text Document.txt" you should not delete the 8.3 name "NEWTEX~1.TXT".

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ rename()

bool FatFile::rename | ( | FatFile * | dirFile,
|  | const char * | newPath
| ) |  |

Rename a file or subdirectory.

Parameters

  [in] | dirFile | Directory for the new path.
  [in] | newPath | New path name for the file/directory.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ rewind()

void FatFile::rewind | ( |  | ) |
| inline

Set the file's current position to zero.

## ◆ rmdir()

bool FatFile::rmdir | ( |  | ) |

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.

Note
  This function should not be used to delete the 8.3 version of a directory that has a long name. For example if a directory has the long name "New folder" you should not delete the 8.3 name "NEWFOL~1".

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ rmRfStar()

bool FatFile::rmRfStar | ( |  | ) |

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.

Note
  This function should not be used to delete the 8.3 version of a directory that has a long name. See remove() and rmdir().

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ seekCur()

bool FatFile::seekCur | ( | int32_t | offset | ) |
| inline

Set the files position to current position + pos. See seekSet().

Parameters

  [in] | offset | The new position in bytes from the current position.

Returns
  true for success or false for failure.

## ◆ seekEnd()

bool FatFile::seekEnd | ( | int32_t | offset = `0` | ) |
| inline

Set the files position to end-of-file + offset. See seekSet(). Can't be used for directory files since file size is not defined.

Parameters

  [in] | offset | The new position in bytes from end-of-file.

Returns
  true for success or false for failure.

## ◆ seekSet()

bool FatFile::seekSet | ( | uint32_t | pos | ) |

Sets a file's position.

Parameters

  [in] | pos | The new position in bytes from the beginning of the file.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ setCwd()

static bool FatFile::setCwd | ( | FatFile * | dir | ) |
| inline static

Set the current working directory.

Parameters

  [in] | dir | New current working directory.

Returns
  true for success else false.

## ◆ setpos()

void FatFile::setpos | ( | FatPos_t * | pos | ) |

set position for streams

Parameters

  [out] | pos | struct with value for new position

## ◆ sync()

bool FatFile::sync | ( |  | ) |

The sync() call causes all modified data and directory fields to be written to the storage device.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ timestamp() [1/2]

bool FatFile::timestamp | ( | FatFile * | file | ) |

Copy a file's timestamps

Parameters

  [in] | file | File to copy timestamps from.

Note
  Modify and access timestamps may be overwritten if a date time callback function has been set by dateTimeCallback().

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ timestamp() [2/2]

bool FatFile::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.

Parameters

  [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.

Parameters

  [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

Note
  It is possible to set an invalid date since there is no check for the number of days in a month.
  Modify and access timestamps may be overwritten if a date time callback function has been set by dateTimeCallback().

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ truncate()

bool FatFile::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.

Parameters

  [in] | length | The desired length for the file.

Returns
  The value true is returned for success and the value false is returned for failure.

## ◆ volume()

FatVolume* FatFile::volume | ( |  | ) | const
| inline

Returns
  FatVolume that contains this file.

## ◆ write() [1/3]

int FatFile::write | ( | const char * | str | ) |
| inline

Write a string to a file. Used by the Arduino Print class.

Parameters

  [in] | str | Pointer to the string. Use getWriteError to check for errors.

Returns
  count of characters written for success or -1 for failure.

## ◆ write() [2/3]

int FatFile::write | ( | uint8_t | b | ) |
| inline

Write a single byte.

Parameters

  [in] | b | The byte to be written.

Returns
  +1 for success or -1 for failure.

## ◆ write() [3/3]

int FatFile::write | ( | const void * | buf,
|  | size_t | nbyte
| ) |  |

Write data to an open file.

Note
  Data is moved to the cache but may not be written to the storage device until sync() is called.

Parameters

  [in] | buf | Pointer to the location of the data to be written.
  [in] | nbyte | Number of bytes to write.

Returns
  For success write() returns the number of bytes written, always nbyte. If an error occurs, write() returns -1. Possible errors include write() is called before a file has been opened, write is called for a read-only file, device is full, a corrupt file system or an I/O error.

The documentation for this class was generated from the following files:

- Arduino/libraries/SdFat/src/FatLib/FatFile.h
- Arduino/libraries/SdFat/src/FatLib/FatFile.cpp
- Arduino/libraries/SdFat/src/FatLib/FatFileLFN.cpp
- Arduino/libraries/SdFat/src/FatLib/FatFilePrint.cpp
- Arduino/libraries/SdFat/src/FatLib/FatFileSFN.cpp