Access file system. More...

Typedefs
typedef signed short	file_t
	File handle. More...

Enumerations
enum	FileOpenFlags { eFO_ReadOnly = SPIFFS_RDONLY, eFO_WriteOnly = SPIFFS_WRONLY, eFO_ReadWrite = eFO_ReadOnly \| eFO_WriteOnly, eFO_CreateIfNotExist = SPIFFS_CREAT, eFO_Append = SPIFFS_APPEND, eFO_Truncate = SPIFFS_TRUNC, eFO_CreateNewAlways = eFO_CreateIfNotExist \| eFO_Truncate }
	File open flags. More...

enum	SeekOriginFlags { eSO_FileStart = SPIFFS_SEEK_SET, eSO_CurrentPos = SPIFFS_SEEK_CUR, eSO_FileEnd = SPIFFS_SEEK_END }
	File seek flags. More...

Functions
static FileOpenFlags	operator\| (FileOpenFlags lhs, FileOpenFlags rhs)

file_t	fileOpen (const String &name, FileOpenFlags flags)
	Open file. More...

void	fileClose (file_t file)
	Clode file. More...

int	fileWrite (file_t file, const void *data, size_t size)
	Write to file. More...

int	fileRead (file_t file, void *data, size_t size)
	Read from file. More...

int	fileSeek (file_t file, int offset, SeekOriginFlags origin)
	Position file cursor. More...

bool	fileIsEOF (file_t file)
	Check if at end of file. More...

int32_t	fileTell (file_t file)
	Get position in file. More...

int	fileFlush (file_t file)
	Flush pending writes. More...

int	fileLastError (file_t fd)
	Get last file system error code. More...

void	fileClearLastError (file_t fd)
	Clear last file system error. More...

int	fileSetContent (const String &fileName, const char *content, int length=-1)
	Create or replace file with defined content. More...

int	fileSetContent (const String &fileName, const String &content)
	Create or replace file with defined content. More...

uint32_t	fileGetSize (const String &fileName)
	Get size of file. More...

int	fileTruncate (file_t file, size_t newSize)
	Truncate (reduce) the size of an open file. More...

int	fileTruncate (file_t file)
	Truncate an open file at the current cursor position. More...

int	fileTruncate (const String &fileName, size_t newSize)
	Truncate (reduce) the size of a file. More...

int	fileRename (const String &oldName, const String &newName)
	Rename file. More...

Vector< String >	fileList ()
	Get list of files on file system. More...

String	fileGetContent (const String &fileName)
	Read content of a file. More...

size_t	fileGetContent (const String &fileName, char *buffer, size_t bufSize)
	Read content of a file. More...

int	fileStats (const String &name, spiffs_stat *stat)

int	fileStats (file_t file, spiffs_stat *stat)

int	fileDelete (const String &name)
	Delete file. More...

int	fileDelete (file_t file)
	Delete file. More...

bool	fileExist (const String &name)
	Check if a file exists on file system. More...

Detailed Description

Access file system.

Typedef Documentation

◆ file_t

typedef signed short file_t

File handle.

Enumeration Type Documentation

◆ FileOpenFlags

enum FileOpenFlags

File open flags.

Enumerator
eFO_ReadOnly	Read only file.
eFO_WriteOnly	Write only file.
eFO_ReadWrite	Read and write file.
eFO_CreateIfNotExist	Create new file if file does not exist.
eFO_Append	Append to file.
eFO_Truncate	Truncate file.
eFO_CreateNewAlways	Create new file even if file exists.

◆ SeekOriginFlags

enum SeekOriginFlags

File seek flags.

Enumerator
eSO_FileStart	Start of file.
eSO_CurrentPos	Current position in file.
eSO_FileEnd	End of file.

Function Documentation

◆ fileClearLastError()

void fileClearLastError ( file_t fd )

Clear last file system error.

Parameters

fd Not used

Todo:: Why does fileClearLastError have unused fd parameter?

◆ fileClose()

void fileClose ( file_t file )

Clode file.

Parameters

file	ID of file to open

Note: File ID is returned from fileOpen function

◆ fileDelete() [1/2]

int fileDelete ( const String & name )

Delete file.

Parameters

name	Name of file to delete

Return values

int	error code, 0 on success

◆ fileDelete() [2/2]

int fileDelete ( file_t file )

Delete file.

Parameters

file	ID of file to delete

Return values

int	error code, 0 on success

◆ fileExist()

bool fileExist ( const String & name )

Check if a file exists on file system.

Parameters

name	Name of file to check for

Return values

bool	True if file exists

◆ fileFlush()

int fileFlush ( file_t file )

Flush pending writes.

Parameters

file File ID

Return values

int	Size of last file written or negative error number

◆ fileGetContent() [1/2]

String fileGetContent ( const String & fileName )

Read content of a file.

Parameters

fileName Name of file to read from

Return values

String String variable in to which to read the file content

Note: After calling this function the content of the file is placed in to a string. The result will be an invalid String (equates to false) if the file could not be read. If the file exists, but is empty, the result will be an empty string "".

◆ fileGetContent() [2/2]

size_t fileGetContent	(	const String &	fileName,
		char *	buffer,
		size_t	bufSize
	)

Read content of a file.

Parameters

fileName	Name of file to read from
buffer	Pointer to a character buffer in to which to read the file content
bufSize	Quantity of bytes to read from file

Return values

size_t Quantity of bytes read from file or zero on failure

Note: After calling this function the content of the file is placed in to a c-string Ensure there is sufficient space in the buffer for file content plus extra trailing null, i.e. at least bufSize + 1; Returns 0 if the file could not be read

◆ fileGetSize()

uint32_t fileGetSize ( const String & fileName )

Get size of file.

Parameters

fileName Name of file

Return values

uint32_t Size of file in bytes

Note: Returns 0 if error occurs

◆ fileIsEOF()

bool fileIsEOF ( file_t file )

Check if at end of file.

Parameters

file File ID

Return values

bool	True if at end of file

◆ fileLastError()

int fileLastError ( file_t fd )

Get last file system error code.

Parameters

fd Not used

Todo:: Why does fileLastError have unused fd parameter?

Return values

int	Error code of last file system operation

◆ fileList()

Vector<String> fileList ( )

Get list of files on file system.

Return values

Vector<String> Vector of strings. Each string element contains the name of a file on the file system

◆ fileOpen()

file_t fileOpen	(	const String &	name,
		FileOpenFlags	flags
	)

Open file.

Parameters

name	File name
flags	Mode to open file

Return values

file	File ID or negative error code

◆ fileRead()

int fileRead	(	file_t	file,
		void *	data,
		size_t	size
	)

Read from file.

Parameters

file	File ID
data	Pointer to data buffer in to which to read data
size	Quantity of data elements to read from file

Return values

int	Quantity of data elements actually read from file or negative error code

◆ fileRename()

int fileRename	(	const String &	oldName,
		const String &	newName
	)

Rename file.

Parameters

oldName	Original name of file to rename
newName	New name for file

Return values

int	error code

◆ fileSeek()

int fileSeek	(	file_t	file,
		int	offset,
		SeekOriginFlags	origin
	)

Position file cursor.

Parameters

file	File ID
offset	Quantity of bytes to move cursor
origin	Position from where to move cursor

Return values

Offset within file or negative error code

◆ fileSetContent() [1/2]

int fileSetContent	(	const String &	fileName,
		const char *	content,
		int	length = `-1`
	)

Create or replace file with defined content.

Parameters

fileName	Name of file to create or replace
content	Pointer to c-string containing content to populate file with
length	(optional) number of characters to write

Return values

int	Positive value (>= 0) represents the numbers of bytes written Negative value (< 0) indicates error

Note: This function creates a new file or replaces an existing file and populates the file with the content of a c-string buffer. If you do not specify length, remember to terminate your c-string buffer with a NUL ('\0').

◆ fileSetContent() [2/2]

int fileSetContent	(	const String &	fileName,
		const String &	content
	)

Create or replace file with defined content.

Parameters

fileName	Name of file to create or replace
content	String containing content to populate file with

Return values

int	Positive integer represents the numbers of bytes written, negative integer represents the error code of last file system operation.

Note: This function creates a new file or replaces an existing file and populates the file with the content of a string.

◆ fileStats() [1/2]

int fileStats	(	const String &	name,
		spiffs_stat *	stat
	)

brief Get file statistics

Parameters

name	File name
stat	Pointer to SPIFFS statistic structure to populate

Return values

int	-1 on error

Note: Pass a pointer to an instantiated fileStats structure

Todo:: Document the return value of fileStats

◆ fileStats() [2/2]

int fileStats	(	file_t	file,
		spiffs_stat *	stat
	)

brief Get file statistics

Parameters

file	File ID
stat	Pointer to SPIFFS statistic structure to populate

Return values

int	-1 on error

Note: Pass a pointer to an instantiated fileStats structure

Todo:: Document the return value of fileStats

◆ fileTell()

int32_t fileTell ( file_t file )

Get position in file.

Parameters

file File ID

Return values

int32_t Read / write cursor position

◆ fileTruncate() [1/3]

int fileTruncate	(	file_t	file,
		size_t	newSize
	)

Truncate (reduce) the size of an open file.

Parameters

file	Open file handle, must have Write access
newSize

Return values

int	error code

Note: In POSIX ftruncate() can also make the file bigger, however SPIFFS can only reduce the file size and will return an error if newSize > fileSize

◆ fileTruncate() [2/3]

int fileTruncate ( file_t file )

Truncate an open file at the current cursor position.

Parameters

file	Open file handle, must have Write access

Return values

int	error code

◆ fileTruncate() [3/3]

int fileTruncate	(	const String &	fileName,
		size_t	newSize
	)

Truncate (reduce) the size of a file.

Parameters

fileName
newSize

Return values

int	error code

Note: In POSIX truncate() can also make the file bigger, however SPIFFS can only reduce the file size and will return an error if newSize > fileSize

◆ fileWrite()

int fileWrite	(	file_t	file,
		const void *	data,
		size_t	size
	)

Write to file.

Parameters

file	File ID
data	Pointer to data to write to file
size	Quantity of data elements to write to file

Return values

int	Quantity of data elements actually written to file or negative error code

◆ operator|()

static FileOpenFlags operator\|	(	FileOpenFlags	lhs,
		FileOpenFlags	rhs
	)

inlinestatic

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ file_t

Enumeration Type Documentation

◆ FileOpenFlags

◆ SeekOriginFlags

Function Documentation

◆ fileClearLastError()

◆ fileClose()

◆ fileDelete() [1/2]

◆ fileDelete() [2/2]

◆ fileExist()

◆ fileFlush()

◆ fileGetContent() [1/2]

◆ fileGetContent() [2/2]

◆ fileGetSize()

◆ fileIsEOF()

◆ fileLastError()

◆ fileList()

◆ fileOpen()

◆ fileRead()

◆ fileRename()

◆ fileSeek()

◆ fileSetContent() [1/2]

◆ fileSetContent() [2/2]

◆ fileStats() [1/2]

◆ fileStats() [2/2]

◆ fileTell()

◆ fileTruncate() [1/3]

◆ fileTruncate() [2/3]

◆ fileTruncate() [3/3]

◆ fileWrite()

◆ operator|()