ExFatFile Class Reference

Basic file class. More...

#include <ExFatFile.h>

Inheritance diagram for ExFatFile:

Public Member Functions
int	available ()
uint64_t	available64 ()
void	clearError ()
void	clearWriteError ()
bool	close ()
uint64_t	curPosition () const
uint64_t	dataLength ()
bool	exists (const ExChar_t *path)
void	fgetpos (fspos_t *pos)
int	fgets (char *str, int num, char *delim=nullptr)
uint64_t	fileSize ()
void	flush ()
void	fsetpos (fspos_t *pos)
uint8_t	getError ()
size_t	getName (ExChar_t *name, size_t size)
bool	getWriteError ()
bool	isContiguous () const
bool	isDir () const
bool	isFile () const
bool	isHidden () const
bool	isOpen () const
bool	isReadable () const
bool	isReadOnly () const
bool	isRoot () const
bool	isSubDir () const
bool	isWritable () const
void	ls (print_t *pr)
void	ls (print_t *pr, uint8_t flags, uint8_t indent=0)
bool	mkdir (ExFatFile *parent, const ExChar_t *path, bool pFlag=true)
int	mprintf (const char *fmt,...)
bool	open (ExFatFile *dirFile, const ExChar_t *path, uint8_t oflag)
bool	open (ExFatVolume *vol, const ExChar_t *path, int oflag)
bool	open (const ExChar_t *path, int oflag=O_READ)
bool	openNext (ExFatFile *dirFile, uint8_t oflag=O_READ)
bool	openRoot (ExFatVolume *vol)
	operator bool ()
int	peek ()
bool	preAllocate (uint64_t length)
size_t	printCreateDateTime (print_t *pr)
int	printf (const char *fmt,...)
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 (print_t *pr)
int	read ()
int	read (void *buf, size_t count)
bool	remove ()
bool	remove (const ExChar_t *path)
bool	rename (const ExChar_t *newPath)
bool	rename (ExFatFile *dirFile, const ExChar_t *newPath)
void	rewind ()
bool	rmdir ()
bool	seekCur (int64_t offset)
bool	seekEnd (int64_t offset=0)
bool	seekSet (uint64_t pos)
bool	sync ()
bool	truncate ()
bool	truncate (uint64_t length)
uint64_t	validLength ()
int	write (const char *str)
size_t	write (uint8_t b)
size_t	write (const void *buf, size_t count)

Friends
class	ExFatVolume

Detailed Description

Basic file class.

Member Function Documentation

int ExFatFile::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.

uint64_t ExFatFile::available64 ( )

inline

Returns

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

void ExFatFile::clearError ( )

inline

Clear all error bits.

void ExFatFile::clearWriteError ( )

inline

Set writeError to zero

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

Copyright (c) 20011-2017 Bill Greiman This file is part of the SdFs 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.

uint64_t ExFatFile::curPosition ( ) const

inline

Returns

The current position for a file or directory.

uint64_t ExFatFile::dataLength ( )

inline

Returns

Total data length for file.

bool ExFatFile::exists ( const ExChar_t *  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.

void ExFatFile::fgetpos

(

fspos_t *

pos

)

get position for streams

Parameters

[out]

pos

struct to receive position

int ExFatFile::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.

uint64_t ExFatFile::fileSize ( )

inline

Returns

The total number of bytes in a file.

void ExFatFile::flush ( )

inline

Arduino name for sync()

void ExFatFile::fsetpos

(

fspos_t *

pos

)

set position for streams

Parameters

[out]

pos

struct with value for new position

uint8_t ExFatFile::getError ( )

inline

Returns

All error bits.

size_t ExFatFile::getName	(	ExChar_t *	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 characters.

Returns

the name length.

bool ExFatFile::getWriteError ( )

inline

Returns

value of writeError

bool ExFatFile::isContiguous ( ) const

inline

Returns

True if the file is contiguous.

bool ExFatFile::isDir ( ) const

inline

Returns

True if this is a directory.

bool ExFatFile::isFile ( ) const

inline

Returns

True if this is a normal file.

bool ExFatFile::isHidden ( ) const

inline

Returns

True if this is a hidden.

bool ExFatFile::isOpen ( ) const

inline

Returns

true if the file is open.

bool ExFatFile::isReadable ( ) const

inline

Returns

True file is writable.

bool ExFatFile::isReadOnly ( ) const

inline

Returns

True if file is read-only

bool ExFatFile::isRoot ( ) const

inline

Returns

True if this is the root directory.

bool ExFatFile::isSubDir ( ) const

inline

Returns

True if this is a subdirectory.

bool ExFatFile::isWritable ( ) const

inline

Returns

True file is writable.

void ExFatFile::ls

(

print_t *

pr

)

List directory contents.

Parameters

[in]

pr

Print stream for list.

void ExFatFile::ls	(	print_t *	pr,
		uint8_t	flags,
		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 ExFatFile::mkdir	(	ExFatFile *	parent,
		const ExChar_t *	path,
		bool	pFlag = true
	)

Make a new directory.

Parameters

[in]	parent	An open directory file 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 ExFatFile::mprintf	(	const char *	fmt,
			...
	)

Formatted print.

Parameters

[in]

fmt

format string.

Returns

number of character printed for success else a negative value.

bool ExFatFile::open	(	ExFatFile *	dirFile,
		const ExChar_t *	path,
		uint8_t	oflag
	)

Open a file or directory by name.

Parameters

[in]	dirFile	An open directory containing the file to be opened.
[in]	path	The path 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 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

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

bool ExFatFile::open	(	ExFatVolume *	vol,
		const ExChar_t *	path,
		int	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 open(ExFatFile*, const char*, uint8_t).

Returns

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

bool ExFatFile::open	(	const ExChar_t *	path,
		int	oflag = O_READ
	)

Open a file in the current working directory.

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 ExFatFile::openNext	(	ExFatFile *	dirFile,
		uint8_t	oflag = O_READ
	)

Open the next file or subdirectory in a directory.

Parameters

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

Returns

true for success or false for failure.

bool ExFatFile::openRoot

(

ExFatVolume *

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.

ExFatFile::operator bool ( )

inline

The parenthesis operator.

Returns

true if a file is open.

int ExFatFile::peek

(

)

Return the next available byte without consuming it.

Returns

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

bool ExFatFile::preAllocate

(

uint64_t

length

)

Allocate contiguous clusters to an empty file.

The file must be empty with no clusters allocated.

The file will have zero validLength and dataLength will equal the requested length.

Parameters

[in]

length

size of allocated space in bytes.

Returns

true for success else false.

size_t ExFatFile::printCreateDateTime

(

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.

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

Formatted print.

Parameters

[in]

fmt

format string.

Returns

number of character printed for success else a negative value.

int ExFatFile::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.

int ExFatFile::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.

int ExFatFile::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.

int ExFatFile::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.

size_t ExFatFile::printFileSize

(

print_t *

pr

)

Print a file's size in bytes.

Parameters

[in]

pr

Prtin stream for the output.

Returns

The number of bytes printed.

Copyright (c) 20011-2017 Bill Greiman This file is part of the SdFs 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.

size_t ExFatFile::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.

size_t ExFatFile::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.

int ExFatFile::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.

int ExFatFile::read	(	void *	buf,
		size_t	count
	)

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 nbyte, including zero, will be returned if end of file is reached. If an error occurs, read() returns -1.

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

bool ExFatFile::remove

(

const ExChar_t *

path

)

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

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

bool ExFatFile::rename

(

const ExChar_t *

newPath

)

Rename a file or subdirectory.

Parameters

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

bool ExFatFile::rename	(	ExFatFile *	dirFile,
		const ExChar_t *	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.

void ExFatFile::rewind ( )

inline

Set the file's current position to zero.

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

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

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

bool ExFatFile::seekSet

(

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

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

bool ExFatFile::truncate

(

)

Truncate a file at the current file position.

Returns

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

bool ExFatFile::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

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

uint64_t ExFatFile::validLength ( )

inline

Returns

The valid number of bytes in a file.

int ExFatFile::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.

size_t ExFatFile::write ( uint8_t  b )

inline

Write a single byte.

Parameters

[in]

b

The byte to be written.

Returns

+1 for success or zero for failure.

size_t ExFatFile::write	(	const void *	buf,
		size_t	count
	)

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

---

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

• ArduinoSdFs/libraries/SdFs/src/ExFatLib/ExFatFile.h
• ArduinoSdFs/libraries/SdFs/src/ExFatLib/ExFatFile.cpp
• ArduinoSdFs/libraries/SdFs/src/ExFatLib/ExFatFilePrint.cpp
• ArduinoSdFs/libraries/SdFs/src/ExFatLib/ExFatFileWrite.cpp