File Access and Management. More...

Modules
	File Data
	File Data Structure Reference.

Functions list
fs_status_t	file_open (file_t file, fs_file_t fs_specific_file, const char __generic_ptr path, int flags)
	Open or Create a File. More...

fs_status_t	file_close (file_t *file)
	Close the Opened File. More...

fs_status_t	file_read (file_t file, void buffer, uint32_t bytes_to_read)
	Read Data from the File. More...

fs_status_t	file_write (file_t file, void buffer, uint32_t bytes_to_write)
	Write Data to a File. More...

fs_status_t	file_sync (file_t *file)
	Flush Cached Data of a File. More...

fs_status_t	file_seek (file_t *file, int32_t offset, logical_drive_type_t starting_position)
	Move Read/Write Pointer of the File. More...

uint32_t	file_tell (file_t *file)
	Get Current Read/Write Pointer of the File. More...

fs_status_t	file_rewind (file_t *file)
	Move Read/Write Pointer to the beginning of the File. More...

uint32_t	file_size (file_t *file)
	Get Size of the File. More...

fs_status_t	file_truncate (file_t *file, uint32_t truncated_size)
	Truncate File Size. More...

Detailed Description

Function Documentation

◆ file_open()

fs_status_t file_open	(	file_t *	file,
		fs_file_t	fs_specific_file,
		const char *__generic_ptr	path,
		int	flags
	)

This API function will open a file in a location specified by the parameter path, on the logical drive identified by the drive number found also in the path parameter. The file data structure specific to the particular file system implementation fs_specific_file, and file structure will be initialized too. Parameter flags will affect the circumstances of the file creation and/or modification, as well what operations can be performed later with it.

Parameters

[in,out]	file	A pointer to the file data structure, that acts as the file identifier. See file_t, structure for detailed explanation.
[in]	fs_specific_file	A pointer to the file data structure specific to the particular file system. See fs_file_t structure for detailed explanation.
[in]	path	A null terminated string, that specifies the absolute path to the file that needs to be opened. It should contain the the logical drive identifying drive number and semicolon at the beginning of the string, eg `"3:/"`. If it does not, the default logical drive, `0`:, will be assumed.
[in]	flags	Determins the type of access and open method for the file. It is specified by a combination of following flags. See File Flags, macros for detailed explanation.

Return values

FSS_OK	If file was opened successfully,
FSS_GENERAL_ERROR	If too many files were opened already, or if `flags` paramater does not allow creation of the new file but no `file` is found on the drive, etc.

Precondition: A logical drive must be mounted to the file system to the location specified by the path See file_system_mount function for detailed explanation.

Postcondition: Other file access APIs can now be called, using the file structure as identifier, allowing various operations with the opened file.

Note: Maximum 10 files and/or directories can be opened at one time. See FS_MAX_OBJECTS.

◆ file_close()

fs_status_t file_close ( file_t * file )

This API function will close an open file object. If the file has been changed, the cached information of the file will be written to the drive specified by the file structure.

Parameters

[in,out] file A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.

Return values

FSS_OK	If file was closed successfully,
FSS_GENERAL_ERROR	If the `file` was not opened, or if there was an error on the physical drive linked to the logical drive, etc.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

◆ file_read()

fs_status_t file_read	(	file_t *	file,
		void *	buffer,
		uint32_t	bytes_to_read
	)

This API function will read bytes_to_read number of bytes of data, from the opened file, starting from the offset pointed by the read/write pointer of the file object, and store it into the buffer.

Parameters

[in]	file	A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.
[in]	buffer	A pointer to the buffer address, where the read data will be stored.
[in]	bytes_to_read	Specifies number of bytes of data that needs to be read from the `file`.

Return values

FSS_OK	If all the data was read successfully.
FSS_END_OF_FILE	If the end of the file is reached before the `bytes_to_read` number of bytes is read from it.
FSS_GENERAL_ERROR	If the `file` was not opened, or if there was an error on the physical drive linked to the logical drive, etc.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

◆ file_write()

fs_status_t file_write	(	file_t *	file,
		void *	buffer,
		uint32_t	bytes_to_write
	)

This API function will write bytes_to_write number of bytes of data, from the the buffer to the opened file, starting from the offset pointed by the read/write pointer of the file object, and store it into the buffer.

Parameters

[in]	file	A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.
[in]	buffer	A pointer to the buffer address, where data needs to be written is stored.
[in]	bytes_to_write	Specifies number of bytes of data that needs to be written to the `file`.

Return values

FSS_OK	If all the data was read successfully.
FSS_DRIVE_FULL	If during the writing to the opened `file`, memory of the logical drive identified by the `file` structure, is filled before `bytes_to_write` number of bytes could be written.
FSS_GENERAL_ERROR	If the `file` was not opened, or if there was an error on the physical drive linked to the logical drive, etc.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

◆ file_sync()

fs_status_t file_sync ( file_t * file )

This API function will flush the cached data of a file to the logical drive identified by the file structure. It performs the same process as, file_close API, but the file will remain open for further read/write/seek operations on it. Performing a sync operation can minimize the risk of data loss due to a loss of power, or media removal.

Parameters

[in] file A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.

Return values

FSS_OK	If cached data was flushed successfully,
FSS_GENERAL_ERROR	If the `file` was not opened, or if there was an error on the physical drive linked to the logical drive, etc.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

◆ file_seek()

fs_status_t file_seek	(	file_t *	file,
		int32_t	offset,
		logical_drive_type_t	starting_position
	)

This API function will move read/write pointer of the opened file, by offset from the position indicated by the starting_position parameter.

Parameters

[in]	file	A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.
[in]	offset	Byte offset from `starting_position` to move read/write pointer of the opened `file`. Negative values will move it toward the beginning, while positive values will move it towards the end of the file.
[in]	starting_position	Position in the `file`, from where read/write pointer of the `file` will be moved from.

Return values

FSS_OK	If read/write pointer of the `file` was moved to the desired offset successfully.
FSS_DRIVE_FULL	If positive offset was used, and if the `file` needed to be expanded but the was not more free space on the logical drive identified by the `file` structure.
FSS_GENERAL_ERROR	If the `file` was not opened, or if there was an error on the physical drive linked to the logical drive, etc.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

Note: Negative value offset can move the read/write pointer only up to the beginning of the file.; Positive value offset may expand the file size.

◆ file_tell()

uint32_t file_tell ( file_t * file )

This API function will return current read/write pointer of the opened file structure.

Parameters

[in] file A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.

Returns: read/write pointer of the file.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

◆ file_rewind()

fs_status_t file_rewind ( file_t * file )

This API function will will move read/write pointer of the opened file, to the beginning of the opened file.

Parameters

[in] file A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.

Return values

FSS_OK	If read/write pointer of the `file` was moved to the desired offset successfully.
FSS_GENERAL_ERROR	If the `file` was not opened, or if there was an error on the physical drive linked to the logical drive, etc.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

◆ file_size()

uint32_t file_size ( file_t * file )

This API function will return size of the opened file.

Parameters

[in] file A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.

Returns: Size of the file in uint of bytes.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

◆ file_truncate()

fs_status_t file_truncate	(	file_t *	file,
		uint32_t	truncated_size
	)

This API function will truncate the opened file to the size indicated by the parameter truncated_size.

Parameters

[in] file A pointer to the file data structure, that acts as the opened file identifier. See file_t, structure for detailed explanation.

Return values

FSS_OK	If the `file` was truncated successfully.
FSS_GENERAL_ERROR	If the `file` was not opened, or if there was an error on the physical drive linked to the logical drive, etc.

Precondition: The file must be opened first, before calling this function. See file_open, function for detailed explanation.

Modules

Functions list

Detailed Description

Function Documentation

◆ file_open()

◆ file_close()

◆ file_read()

◆ file_write()

◆ file_sync()

◆ file_seek()

◆ file_tell()

◆ file_rewind()

◆ file_size()

◆ file_truncate()