FAT16 file functions
[FAT16 support]

---

Detailed Description

Functions for managing files.

Data Structures
struct	fat16_dir_entry_struct
	Describes a directory entry. More...
Defines
#define	FAT16_ATTRIB_READONLY
	The file is read-only.
#define	FAT16_ATTRIB_HIDDEN
	The file is hidden.
#define	FAT16_ATTRIB_SYSTEM
	The file is a system file.
#define	FAT16_ATTRIB_VOLUME
	The file is empty and has the volume label as its name.
#define	FAT16_ATTRIB_DIR
	The file is a directory.
#define	FAT16_ATTRIB_ARCHIVE
	The file has to be archived.
#define	FAT16_SEEK_SET
	The given offset is relative to the beginning of the file.
#define	FAT16_SEEK_CUR
	The given offset is relative to the current read/write position.
#define	FAT16_SEEK_END
	The given offset is relative to the end of the file.
Functions
uint8_t	fat16_get_dir_entry_of_path (struct fat16_fs_struct *fs, const char *path, struct fat16_dir_entry_struct *dir_entry)
	Retrieves the directory entry of a path.
struct fat16_file_struct *	fat16_open_file (struct fat16_fs_struct *fs, const struct fat16_dir_entry_struct *dir_entry)
	Opens a file on a FAT16 filesystem.
void	fat16_close_file (struct fat16_file_struct *fd)
	Closes a file.
int16_t	fat16_read_file (struct fat16_file_struct *fd, uint8_t *buffer, uint16_t buffer_len)
	Reads data from a file.
int16_t	fat16_write_file (struct fat16_file_struct *fd, const uint8_t *buffer, uint16_t buffer_len)
	Writes data to a file.
uint8_t	fat16_seek_file (struct fat16_file_struct *fd, int32_t *offset, uint8_t whence)
	Repositions the read/write file offset.
uint8_t	fat16_resize_file (struct fat16_file_struct *fd, uint32_t size)
	Resizes a file to have a specific size.
uint8_t	fat16_create_file (struct fat16_dir_struct *parent, const char *file, struct fat16_dir_entry_struct *dir_entry)
	Creates a file.
uint8_t	fat16_delete_file (struct fat16_fs_struct *fs, struct fat16_dir_entry_struct *dir_entry)
	Deletes a file or directory.
void	fat16_get_file_modification_date (const struct fat16_dir_entry_struct *dir_entry, uint16_t *year, uint8_t *month, uint8_t *day)
	Returns the modification date of a file.
void	fat16_get_file_modification_time (const struct fat16_dir_entry_struct *dir_entry, uint8_t *hour, uint8_t *min, uint8_t *sec)
	Returns the modification time of a file.

---

Define Documentation

#define FAT16_ATTRIB_READONLY

The file is read-only.

#define FAT16_ATTRIB_HIDDEN

The file is hidden.

#define FAT16_ATTRIB_SYSTEM

The file is a system file.

#define FAT16_ATTRIB_VOLUME

The file is empty and has the volume label as its name.

#define FAT16_ATTRIB_DIR

The file is a directory.

#define FAT16_ATTRIB_ARCHIVE

The file has to be archived.

#define FAT16_SEEK_SET

The given offset is relative to the beginning of the file.

#define FAT16_SEEK_CUR

The given offset is relative to the current read/write position.

#define FAT16_SEEK_END

The given offset is relative to the end of the file.

---

Function Documentation

uint8_t fat16_get_dir_entry_of_path	(	struct fat16_fs_struct *	fs,
		const char *	path,
		struct fat16_dir_entry_struct *	dir_entry
	)

Retrieves the directory entry of a path.

The given path may both describe a file or a directory.

Parameters:

[in]	fs	The FAT16 filesystem on which to search.
[in]	path	The path of which to read the directory entry.
[out]	dir_entry	The directory entry to fill.

Returns:

0 on failure, 1 on success.

See also:

fat16_read_dir

struct fat16_file_struct* fat16_open_file	(	struct fat16_fs_struct *	fs,
		const struct fat16_dir_entry_struct *	dir_entry
	)			[read]

Opens a file on a FAT16 filesystem.

Parameters:

[in]	fs	The filesystem on which the file to open lies.
[in]	dir_entry	The directory entry of the file to open.

Returns:

The file handle, or 0 on failure.

See also:

fat16_close_file

void fat16_close_file

(

struct fat16_file_struct *

fd

)

Closes a file.

Parameters:

[in]

fd

The file handle of the file to close.

See also:

fat16_open_file

int16_t fat16_read_file	(	struct fat16_file_struct *	fd,
		uint8_t *	buffer,
		uint16_t	buffer_len
	)

Reads data from a file.

The data requested is read from the current file location.

Parameters:

[in]	fd	The file handle of the file from which to read.
[out]	buffer	The buffer into which to write.
[in]	buffer_len	The amount of data to read.

Returns:

The number of bytes read, 0 on end of file, or -1 on failure.

See also:

fat16_write_file

int16_t fat16_write_file	(	struct fat16_file_struct *	fd,
		const uint8_t *	buffer,
		uint16_t	buffer_len
	)

Writes data to a file.

The data is written to the current file location.

Parameters:

[in]	fd	The file handle of the file to which to write.
[in]	buffer	The buffer from which to read the data to be written.
[in]	buffer_len	The amount of data to write.

Returns:

The number of bytes written, 0 on disk full, or -1 on failure.

See also:

fat16_read_file

uint8_t fat16_seek_file	(	struct fat16_file_struct *	fd,
		int32_t *	offset,
		uint8_t	whence
	)

Repositions the read/write file offset.

Changes the file offset where the next call to fat16_read_file() or fat16_write_file() starts reading/writing.

If the new offset is beyond the end of the file, fat16_resize_file() is implicitly called, i.e. the file is expanded.

The new offset can be given in different ways determined by the whence parameter:

• FAT16_SEEK_SET: *offset is relative to the beginning of the file.
• FAT16_SEEK_CUR: *offset is relative to the current file position.
• FAT16_SEEK_END: *offset is relative to the end of the file.

The resulting absolute offset is written to the location the offset parameter points to.

Parameters:

[in]	fd	The file decriptor of the file on which to seek.
[in,out]	offset	A pointer to the new offset, as affected by the whence parameter. The function writes the new absolute offset to this location before it returns.
[in]	whence	Affects the way offset is interpreted, see above.

Returns:

0 on failure, 1 on success.

uint8_t fat16_resize_file	(	struct fat16_file_struct *	fd,
		uint32_t	size
	)

Resizes a file to have a specific size.

Enlarges or shrinks the file pointed to by the file descriptor to have exactly the specified size.

If the file is truncated, all bytes having an equal or larger offset than the given size are lost. If the file is expanded, the additional bytes are allocated.

Note:

Please be aware that this function just allocates or deallocates disk space, it does not explicitely clear it. To avoid data leakage, this must be done manually.

Parameters:

[in]	fd	The file decriptor of the file which to resize.
[in]	size	The new size of the file.

Returns:

0 on failure, 1 on success.

uint8_t fat16_create_file	(	struct fat16_dir_struct *	parent,
		const char *	file,
		struct fat16_dir_entry_struct *	dir_entry
	)

Creates a file.

Creates a file and obtains the directory entry of the new file. If the file to create already exists, the directory entry of the existing file will be returned within the dir_entry parameter.

Note:

The file name is not checked for invalid characters.

The generation of the short 8.3 file name is quite simple. The first eight characters are used for the filename. The extension, if any, is made up of the first three characters following the last dot within the long filename. If the filename (without the extension) is longer than eight characters, the lower byte of the cluster number replaces the last two characters to avoid name clashes. In any other case, it is your responsibility to avoid name clashes.

Parameters:

[in]	parent	The handle of the directory in which to create the file.
[in]	file	The name of the file to create.
[out]	dir_entry	The directory entry to fill for the new file.

Returns:

0 on failure, 1 on success.

See also:

fat16_delete_file

uint8_t fat16_delete_file	(	struct fat16_fs_struct *	fs,
		struct fat16_dir_entry_struct *	dir_entry
	)

Deletes a file or directory.

If a directory is deleted without first deleting its subdirectories and files, disk space occupied by these files will get wasted as there is no chance to release it and mark it as free.

Parameters:

[in]	fs	The filesystem on which to operate.
[in]	dir_entry	The directory entry of the file to delete.

Returns:

0 on failure, 1 on success.

See also:

fat16_create_file

void fat16_get_file_modification_date	(	const struct fat16_dir_entry_struct *	dir_entry,
		uint16_t *	year,
		uint8_t *	month,
		uint8_t *	day
	)

Returns the modification date of a file.

Parameters:

[in]	dir_entry	The directory entry of which to return the modification date.
[out]	year	The year the file was last modified.
[out]	month	The month the file was last modified.
[out]	day	The day the file was last modified.

void fat16_get_file_modification_time	(	const struct fat16_dir_entry_struct *	dir_entry,
		uint8_t *	hour,
		uint8_t *	min,
		uint8_t *	sec
	)

Returns the modification time of a file.

Parameters:

[in]	dir_entry	The directory entry of which to return the modification time.
[out]	hour	The hour the file was last modified.
[out]	min	The min the file was last modified.
[out]	sec	The sec the file was last modified.