# SdFat: FsBaseFile Class Reference

FsBaseFile Class Reference

FsBaseFile class. More...

`#include <FsFile.h>`

Inheritance diagram for FsBaseFile:
[legend]

## Public Member Functions

int | available ()
void | clearWriteError ()
bool | close ()
uint64_t | curPosition ()
uint32_t | dirIndex ()
bool | exists (const char *path)
void | fgetpos (fspos_t *pos)
int | fgets (char *str, int num, char *delim=nullptr)
uint64_t | fileSize ()
void | flush ()
| FsBaseFile (const FsBaseFile &from)
void | fsetpos (const fspos_t *pos)
uint8_t | getError ()
size_t | getName (char *name, size_t len)
bool | getWriteError ()
bool | isDir ()
bool | isDirectory ()
bool | isHidden ()
bool | isOpen ()
bool | isSubDir ()
bool | ls (print_t *pr)
bool | ls (print_t *pr, uint8_t flags)
bool | mkdir (FsBaseFile *dir, const char *path, bool pFlag=true)
const char * | name () const
bool | open (const char *path, oflag_t oflag=O_RDONLY)
bool | open (FsBaseFile *dir, const char *path, oflag_t oflag=O_RDONLY)
bool | open (FsBaseFile *dir, uint32_t index, oflag_t oflag)
bool | open (FsVolume *vol, const char *path, oflag_t oflag)
bool | openNext (FsBaseFile *dir, oflag_t oflag=O_RDONLY)
| operator bool ()
FsBaseFile & | operator= (const FsBaseFile &from)
int | peek ()
uint64_t | position ()
bool | preAllocate (uint64_t length)
size_t | printAccessDateTime (print_t *pr)
size_t | printCreateDateTime (print_t *pr)
size_t | printField (double value, char term, uint8_t prec=2)
size_t | printField (float value, char term, uint8_t prec=2)
template<typename Type >
size_t | printField (Type value, char term)
size_t | printFileSize (print_t *pr)
size_t | printModifyDateTime (print_t *pr)
size_t | printName (print_t *pr)
int | read ()
int | read (void *buf, size_t count)
bool | remove ()
bool | remove (const char *path)
bool | rename (const char *newPath)
bool | rename (FsBaseFile *dirFile, const char *newPath)
void | rewind ()
void | rewindDirectory ()
bool | rmdir ()
bool | seek (uint64_t pos)
bool | seekCur (int64_t offset)
bool | seekEnd (int64_t offset=0)
bool | seekSet (uint64_t pos)
uint64_t | size ()
bool | sync ()
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 ()
bool | truncate (uint64_t length)
size_t | write (const void *buf, size_t count)
size_t | write (uint8_t b)

## Detailed Description

FsBaseFile class.

## Constructor & Destructor Documentation

## FsBaseFile()

FsBaseFile::FsBaseFile | ( | const FsBaseFile & | from | ) |

Copy constructor.

Parameters

  [in] | from | Object used to initialize this instance.

Copyright (c) 2011-2019 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.

## Member Function Documentation

## available()

int FsBaseFile::available | ( |  | ) |

inline

Returns
  number of bytes available from the current position to EOF or INT_MAX if more than INT_MAX bytes are available.

## clearWriteError()

void FsBaseFile::clearWriteError | ( |  | ) |

inline

Set writeError to zero

## close()

bool FsBaseFile::close | ( |  | ) |

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

Returns
  true for success or false for failure.

## curPosition()

uint64_t FsBaseFile::curPosition | ( |  | ) |

inline

Returns
  The current position for a file or directory.

## dirIndex()

uint32_t FsBaseFile::dirIndex | ( |  | ) |

inline

Returns
  Directory entry index.

## exists()

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

## fgetpos()

void FsBaseFile::fgetpos | ( | fspos_t * | pos | ) |

inline

get position for streams

Parameters

  [out] | pos | struct to receive position

## fgets()

int FsBaseFile::fgets | ( | char * | str,
|  | int | num,
|  | char * | delim = `nullptr`
| ) |  |

inline

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.

## fileSize()

uint64_t FsBaseFile::fileSize | ( |  | ) |

inline

Returns
  The total number of bytes in a file.

## flush()

void FsBaseFile::flush | ( |  | ) |

inline

Ensure that any bytes written to the file are saved to the SD card.

## fsetpos()

void FsBaseFile::fsetpos | ( | const fspos_t * | pos | ) |

inline

set position for streams

Parameters

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

## getError()

uint8_t FsBaseFile::getError | ( |  | ) |

inline

Returns
  All error bits.

## getName()

size_t FsBaseFile::getName | ( | char * | name,
|  | size_t | len
| ) |  |

inline

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

Parameters

  [out] | name | An array of characters for the file's name.
  [in] | len | 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 length of the returned string.

## getWriteError()

bool FsBaseFile::getWriteError | ( |  | ) |

inline

Returns
  value of writeError

## isDir()

bool FsBaseFile::isDir | ( |  | ) |

inline

Returns
  True if this is a directory else false.

## isDirectory()

bool FsBaseFile::isDirectory | ( |  | ) |

inline

This function reports if the current file is a directory or not.

Returns
  true if the file is a directory.

## isHidden()

bool FsBaseFile::isHidden | ( |  | ) |

inline

Returns
  True if this is a hidden file else false.

## isOpen()

bool FsBaseFile::isOpen | ( |  | ) |

inline

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

## isSubDir()

bool FsBaseFile::isSubDir | ( |  | ) |

inline

Returns
  True if this is a subdirectory file else false.

## ls() [1/2]

bool FsBaseFile::ls | ( | print_t * | pr | ) |

inline

List directory contents.

Parameters

  [in] | pr | Print object.

Returns
  true for success or false for failure.

## ls() [2/2]

bool FsBaseFile::ls | ( | print_t * | pr,
|  | uint8_t | flags
| ) |  |

inline

List directory contents.

Parameters

  [in] | pr | Print object.
  [in] | flags | The inclusive OR of

LS_DATE - Print file modification date

LS_SIZE - Print file size.

LS_R - Recursive list of subdirectories.

Returns
  true for success or false for failure.

## mkdir()

bool FsBaseFile::mkdir | ( | FsBaseFile * | 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
  true for success or false for failure.

## name()

const char* FsBaseFile::name | ( |  | ) | const

inline

No longer implemented due to Long File Names.

Use getName(char* name, size_t size).

Returns
  a pointer to replacement suggestion.

## open() [1/4]

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

inline

Open a file or directory by name.

Parameters

  [in] | path | A path for a file to be opened.
  [in] | oflag | Values for oflag are constructed by a bitwise-inclusive OR of open flags.

Returns
  true for success or false for failure.

## open() [2/4]

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

Open a file or directory by name.

Parameters

  [in] | dir | An open file 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 only..

O_READ - Same as O_RDONLY.

O_WRONLY - Open for writing only.

O_WRITE - Same as O_WRONLY.

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_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 file object or file corruption may occur.

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

Returns
  true for success or false for failure.

## open() [3/4]

bool FsBaseFile::open | ( | FsBaseFile * | dir,
|  | uint32_t | index,
|  | oflag_t | oflag
| ) |  |

Open a file by index.

Parameters

  [in] | dir | An open FsFile 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 flags. See see FsFile::open(FsFile*, const char*, uint8_t).

See open() by path for definition of flags.

Returns
  true for success or false for failure.

## open() [4/4]

bool FsBaseFile::open | ( | FsVolume * | vol,
|  | const char * | path,
|  | oflag_t | oflag
| ) |  |

Open a file or directory by name.

Parameters

  [in] | vol | Volume where the file is located.
  [in] | path | A path for a file to be opened.
  [in] | oflag | Values for oflag are constructed by a bitwise-inclusive OR of open flags.

Returns
  true for success or false for failure.

## openNext()

bool FsBaseFile::openNext | ( | FsBaseFile * | dir,
|  | oflag_t | oflag = `O_RDONLY`
| ) |  |

Opens the next file or folder in a directory.

Parameters

  [in] | dir | directory containing files.
  [in] | oflag | open flags.

Returns
  a file object.

## operator bool()

FsBaseFile::operator bool | ( |  | ) |

inline

The parenthesis operator.

Returns
  true if a file is open.

## operator=()

FsBaseFile & FsBaseFile::operator= | ( | const FsBaseFile & | from | ) |

Copy assignment operator

Parameters

  [in] | from | Object used to initialize this instance.

Returns
  assigned object.

## peek()

int FsBaseFile::peek | ( |  | ) |

inline

Return the next available byte without consuming it.

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

## position()

uint64_t FsBaseFile::position | ( |  | ) |

inline

Returns
  the current file position.

## preAllocate()

bool FsBaseFile::preAllocate | ( | uint64_t | length | ) |

inline

Allocate contiguous clusters to an empty file.

The file must be empty with no clusters allocated.

The file will contain uninitialized data for FAT16/FAT32 files. exFAT files will have zero validLength and dataLength will equal the requested length.

Parameters

  [in] | length | size of the file in bytes.

Returns
  true for success or false for failure.

## printAccessDateTime()

size_t FsBaseFile::printAccessDateTime | ( | print_t * | pr | ) |

inline

Print a file's access date and time

Parameters

  [in] | pr | Print stream for output.

Returns
  true for success or false for failure.

## printCreateDateTime()

size_t FsBaseFile::printCreateDateTime | ( | print_t * | pr | ) |

inline

Print a file's creation date and time

Parameters

  [in] | pr | Print stream for output.

Returns
  true for success or false for failure.

## printField() [1/3]

size_t FsBaseFile::printField | ( | double | value,
|  | char | term,
|  | uint8_t | prec = `2`
| ) |  |

inline

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/3]

size_t FsBaseFile::printField | ( | float | value,
|  | char | term,
|  | uint8_t | prec = `2`
| ) |  |

inline

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() [3/3]

template<typename Type >

size_t FsBaseFile::printField | ( | Type | value,
|  | char | term
| ) |  |

inline

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 FsBaseFile::printFileSize | ( | print_t * | pr | ) |

inline

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()

size_t FsBaseFile::printModifyDateTime | ( | print_t * | pr | ) |

inline

Print a file's modify date and time

Parameters

  [in] | pr | Print stream for output.

Returns
  true for success or false for failure.

## printName()

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

inline

Print a file's name

Parameters

  [in] | pr | Print stream for output.

Returns
  true for success or false for failure.

## read() [1/2]

int FsBaseFile::read | ( |  | ) |

inline

Read the next byte from a file.

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

## read() [2/2]

int FsBaseFile::read | ( | void * | buf,
|  | size_t | count
| ) |  |

inline

Read data from a file starting at the current position.

Parameters

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

Returns
  For success read() returns the number of bytes read. A value less than count, 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.

## remove() [1/2]

bool FsBaseFile::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
  true for success or false for failure.

## remove() [2/2]

bool FsBaseFile::remove | ( | const char * | path | ) |

inline

Remove a file.

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

Parameters

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

Example use: dirFile.remove(filenameToRemove);

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
  true for success or false for failure.

## rename() [1/2]

bool FsBaseFile::rename | ( | const char * | newPath | ) |

inline

Rename a file or subdirectory.

Parameters

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

Returns
  true for success or false for failure.

## rename() [2/2]

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

inline

Rename a file or subdirectory.

Parameters

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

Returns
  true for success or false for failure.

## rewind()

void FsBaseFile::rewind | ( |  | ) |

inline

Set the file's current position to zero.

## rewindDirectory()

void FsBaseFile::rewindDirectory | ( |  | ) |

inline

Rewind a file if it is a directory

## rmdir()

bool FsBaseFile::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
  true for success or false for failure.

## seek()

bool FsBaseFile::seek | ( | uint64_t | pos | ) |

inline

Seek to a new position in the file, which must be between 0 and the size of the file (inclusive).

Parameters

  [in] | pos | the new file position.

Returns
  true for success or false for failure.

## seekCur()

bool FsBaseFile::seekCur | ( | int64_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 FsBaseFile::seekEnd | ( | int64_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 FsBaseFile::seekSet | ( | uint64_t | pos | ) |

inline

Sets a file's position.

Parameters

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

Returns
  true for success or false for failure.

## size()

uint64_t FsBaseFile::size | ( |  | ) |

inline

Returns
  the file's size.

## sync()

bool FsBaseFile::sync | ( |  | ) |

inline

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

Returns
  true for success or false for failure.

## timestamp()

bool FsBaseFile::timestamp | ( | uint8_t | flags,
|  | uint16_t | year,
|  | uint8_t | month,
|  | uint8_t | day,
|  | uint8_t | hour,
|  | uint8_t | minute,
|  | uint8_t | second
| ) |  |

inline

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
  true for success or false for failure.

## truncate() [1/2]

bool FsBaseFile::truncate | ( |  | ) |

inline

Truncate a file to the current position.

Returns
  true for success or false for failure.

## truncate() [2/2]

bool FsBaseFile::truncate | ( | uint64_t | length | ) |

inline

Truncate a file to a specified length. The current file position will be set to end of file.

Parameters

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

Returns
  true for success or false for failure.

## write() [1/2]

size_t FsBaseFile::write | ( | const void * | buf,
|  | size_t | count
| ) |  |

inline

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] | count | 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.

## write() [2/2]

size_t FsBaseFile::write | ( | uint8_t | b | ) |

inline

Write a byte to a file. Required by the Arduino Print class.

Parameters

  [in] | b | the byte to be written. Use getWriteError to check for errors.

Returns
  1 for success and 0 for failure.

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

- ArduinoSdFat/libraries/SdFat/src/FsLib/FsFile.h
- ArduinoSdFat/libraries/SdFat/src/FsLib/FsFile.cpp