Basic file class. More...

#include <FatFile.h>

Inheritance diagram for FatFile:

[legend]

Public Member Functions
int	available ()

uint32_t	available32 ()

void	clearError ()

void	clearWriteError ()

bool	close ()

bool	contiguousRange (uint32_t bgnSector, uint32_t endSector)

uint32_t	curPosition () const

bool	dirEntry (dir_t *dir)

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

bool	exists (const char *path)

	FatFile ()

void	fgetpos (fspos_t *pos)

int	fgets (char str, int num, char delim=nullptr)

uint32_t	fileSize () const

void	flush ()

void	fsetpos (fspos_t *pos)

uint8_t	getError ()

bool	getName (char *name, size_t size)

bool	getSFN (char *name)

bool	getWriteError ()

bool	isDir () const

bool	isFile () const

bool	isHidden () const

bool	isLFN () const

bool	isOpen () const

bool	isReadable () const

bool	isReadOnly () const

bool	isRoot () const

bool	isRoot32 () const

bool	isRootFixed () const

bool	isSubDir () const

bool	isSystem () const

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

int	mprintf (const char *fmt,...)

int	mprintf (const __FlashStringHelper *ifsh,...)

bool	open (FatVolume vol, const char path, uint8_t oflag)

bool	open (FatFile *dirFile, uint16_t index, uint8_t oflag)

bool	open (FatFile dirFile, const char path, uint8_t oflag)

bool	open (const char *path, uint8_t oflag=O_READ)

bool	openNext (FatFile *dirFile, uint8_t oflag=O_READ)

bool	openRoot (FatVolume *vol)

	operator bool ()

int	peek ()

bool	preAllocate (uint32_t length)

size_t	printCreateDateTime (print_t *pr)

int	printf (const char *fmt,...)

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)

size_t	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 count)

int8_t	readDir (dir_t *dir)

bool	remove ()

bool	remove (const char *path)

bool	rename (const char *newPath)

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)

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

size_t	write (const char *str)

size_t	write (uint8_t b)

size_t	write (const void *buf, size_t count)

Static Public Member Functions
static bool	legal83Char (uint8_t c)

static void	printFatDate (print_t *pr, uint16_t fatDate)

static void	printFatTime (print_t *pr, uint16_t fatTime)

Friends
class	FatVolume

Detailed Description

Basic file class.

Constructor & Destructor Documentation

FatFile::FatFile ( )

inline

Create an instance.

Member Function Documentation

int FatFile::available ( )

inline

Returns: The number of bytes available from the current position to EOF for normal files. INT_MAX is returned for very large files.

available64() is recomended for very large files.

Zero is returned for directory files.

uint32_t FatFile::available32 ( )

inline

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

void FatFile::clearError ( )

inline

Clear all error bits.

void FatFile::clearWriteError ( )

inline

Set writeError to zero

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.

bool FatFile::contiguousRange	(	uint32_t *	bgnSector,
		uint32_t *	endSector
	)

Check for contiguous file and return its raw sector range.

Parameters

[out]	bgnSector	the first sector address for the file.
[out]	endSector	the last sector address for the file.

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

uint32_t FatFile::curPosition ( ) const

inline

Returns: The current position for a file or directory.

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.

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.

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.

void FatFile::fgetpos ( fspos_t * pos )

get position for streams

Parameters

[out] pos struct to receive position

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

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.

uint32_t FatFile::fileSize ( ) const

inline

Returns: The total number of bytes in a file.

void FatFile::flush ( )

inline

Arduino name for sync()

void FatFile::fsetpos ( fspos_t * pos )

set position for streams

Parameters

[out] pos struct with value for new position

uint8_t FatFile::getError ( )

inline

Returns: All error bits.

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.

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.

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.

bool FatFile::getWriteError ( )

inline

Returns: value of writeError

bool FatFile::isDir ( ) const

inline

Returns: True if this is a directory.

bool FatFile::isFile ( ) const

inline

Returns: True if this is a normal file.

bool FatFile::isHidden ( ) const

inline

Returns: True if this is a hidden file.

bool FatFile::isLFN ( ) const

inline

Returns: true if this file has a Long File Name.

bool FatFile::isOpen ( ) const

inline

Returns: True if this is an open file/directory.

bool FatFile::isReadable ( ) const

inline

Returns: True file is writable.

bool FatFile::isReadOnly ( ) const

inline

Returns: True if file is read-only

bool FatFile::isRoot ( ) const

inline

Returns: True if this is the root directory.

bool FatFile::isRoot32 ( ) const

inline

Returns: True if this is the FAT32 root directory.

bool FatFile::isRootFixed ( ) const

inline

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

bool FatFile::isSubDir ( ) const

inline

Returns: True if this is a subdirectory.

bool FatFile::isSystem ( ) const

inline

Returns: True if this is a system file.

bool FatFile::isWritable ( ) const

inline

Returns: True file is writable.

static bool FatFile::legal83Char ( uint8_t c )

inlinestatic

Check for a legal 8.3 character.

Parameters

[in] c Character to be checked.

Returns: true for a legal 8.3 character.

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.

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.

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

int FatFile::mprintf	(	const char *	fmt,
			...
	)

Formatted print.

Parameters

[in] fmt format string.

Returns: number of character printed for success else a negative value.

int FatFile::mprintf	(	const __FlashStringHelper *	ifsh,
			...
	)

Minimal formatted print.

Parameters

[in] ifsh format string in flash using F() macro.

Returns: number of character printed for success else a negative value.

bool FatFile::open	(	FatVolume *	vol,
		const char *	path,
		uint8_t	oflag
	)

Open a file in the volume root directory.

Parameters

[in]	vol	Volume where the file is located.
[in]	path	with a valid name for a file to be opened.
[in]	oflag	bitwise-inclusive OR of open mode flags. See see FatFile::open(FatFile, const char, uint8_t).

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

bool FatFile::open	(	FatFile *	dirFile,
		uint16_t	index,
		uint8_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, uint8_t).

See open() by path for definition of flags.

Returns: true for success or false for failure.

bool FatFile::open	(	FatFile *	dirFile,
		const char *	path,
		uint8_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 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_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 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.

bool FatFile::open	(	const char *	path,
		uint8_t	oflag = `O_READ`
	)

Open a file in the current working volume.

Parameters

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

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

bool FatFile::openNext	(	FatFile *	dirFile,
		uint8_t	oflag = `O_READ`
	)

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, uint8_t).

Returns: true for success or false for failure.

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.

FatFile::operator bool ( )

inline

The parenthesis operator.

Returns: true if a file is open.

int FatFile::peek ( )

Return the next available byte without consuming it.

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

bool FatFile::preAllocate ( uint32_t length )

Allocate contiguous clusters to an empty file.

The file must be empty with no clusters allocated.

The file will contain uninitialized data.

Parameters

[in] length size of the file in bytes.

Returns: true for success else false.

size_t FatFile::printCreateDateTime ( print_t * pr )

Print a file's creation date and time

Parameters

[in] pr Print stream for output.

Returns: The number of bytes printed.

int FatFile::printf	(	const char *	fmt,
			...
	)

Formatted print.

Parameters

[in] fmt format string.

Returns: number of character printed for success else a negative value.

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

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

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