file.h File Reference

Detailed Description

HAL file functions.

Author

zane

This file holds all of the file modifying functions supported by the HAL. In order for any of these to work the disk must be completely mounted and FatFS is in place.

Note most of these files work exactly like the C stdlib <stdio.h> versions!

Opening Files

Here's an example on how to open a file, do some operations on it, and properly close it.

#include "hal/shared.h" 
#include "hal/file.h"
_FILE file;
 
// Open a file with read, write, and create always
if(!ffopen("example.txt","rwx",&file))
{
    printf("Error opening file: %s\n", HAL_ERROR_to_str(file.errno));
} else {
    printf("Opened file!\n");
}
 
... // Do some other operations here, this could be writing, reading, etc.
 
// Now close the same file as before when we are done
if(!ffclose(&file))
{
    printf("Error closing file: %s\n", HAL_ERROR_to_str(file.errno));
} else {
    printf("Closed file!\n");
}   

Note once the file is open you can do any file operation on it!

Opening Directories

#include "hal/shared.h"
#include "hal/file.h"
_DIR dir;
 
// Open a directory assuming it's already created
if(!ffopendir(&dir, "home/"))
{
    printf("Error opening directory: %s\n", HAL_ERROR_to_str(dir.errno));
} else {
    printf("Opened directory!\n");
}
 
... // Only function you need ffopendir for is ffreaddir, so do something with that here
 
// Close the directory if we're not using it
if(!ffclosedir(&dir))
{
    printf("Error closing directory: %s\n", HAL_ERROR_to_str(dir.errno));
} else {
    printf("Closed directory!\n");
}

Note the directory does not need to opened with the function to create/access files inside of it. It just needs to be there either through ffmkdir() or through another method.

See also

shared.h

disk.h

#include "shared.h"

Go to the source code of this file.

Functions
HAL_ERROR	ff_err_to_hal (uint32_t ff_err)
	Converts an internal FatFS error to a HAL error. This is only used internally.
bool	ffopen (const char *filename, const char *mode, _FILE *fp)
	Opens a file at filename with certain access modifiers.
bool	ffclose (_FILE *fp)
	Closes a file.
uint32_t	ffread (_FILE *fp, void *buf, uint32_t buf_size)
	Reads data from the file at it's internal file position.
uint32_t	ffwrite (_FILE *fp, const void *buf, uint32_t buf_size)
	Writes data to the file at it's internal file position.
bool	ffseek (_FILE *fp, long offset)
	Sets the file position for the specified file.
bool	ffexpand (_FILE *fp, uint64_t size)
	Expands/Allocates a continous chunk of memory of n size.
uint32_t	fftell (_FILE *fp)
	Gets the current file position the file is at.
bool	ffstat (const char *path, _FILE *file_info)
	Checks whether the file exists and gets the information on the file.
bool	ffunlink (const char *path, _FILE *fp)
	Deletes file/directory at path.
bool	ffmkdir (const char *path, _DIR *dp)
	Creates a new directory.
bool	fdstat (const char *path, _DIR *dir_info)
	Check whether the directory exists and gets the information about the directory.
bool	ffopendir (_DIR *dp, const char *path)
	Opens the dir inside the _DIR object.
bool	ffclosedir (_DIR *dp)
	Closes the _DIR object.
bool	ffreaddir (_DIR *dp, _FILE *file_info)
	Reads a directory object (file).

Function Documentation

fdstat()

bool fdstat	(	const char *	path,
		_DIR *	dir_info )

Check whether the directory exists and gets the information about the directory.

Parameters

*path	Path to directory.
*dir_info	A _DIR pointer to store the resulting info. At this time only the directory attribute and the date/time of last modification are available.

Returns

True on success/False on failure and dp.errno is set.

ff_err_to_hal()

HAL_ERROR ff_err_to_hal

(

uint32_t

ff_err

)

Converts an internal FatFS error to a HAL error. This is only used internally.

Parameters

ff_err

Internal FatFS error.

Returns

A HAL_ERROR.

ffclose()

bool ffclose

(

_FILE *

fp

)

Closes a file.

Parameters

*fp	Pointer to the _FILE struct that contains the file.

Returns

True on success/False on failure and fp.errno is set.

ffclosedir()

bool ffclosedir

(

_DIR *

dp

)

Closes the _DIR object.

Parameters

*dp	_DIR pointer to be closed.

Returns

True on success/False on failure and dp.errno is set.

ffexpand()

bool ffexpand	(	_FILE *	fp,
		uint64_t	size )

Expands/Allocates a continous chunk of memory of n size.

Parameters

*fp	_FILE pointer to make modification to.
size	Size of expansion/allocation.

Returns

True on success/False on failure and fp.errno is set.

Note that expansion occurs from end of file. If creating a new file size will be the new size (since the original size is zero). If a continous allocation cannot be made this function will return false.

ffmkdir()

bool ffmkdir	(	const char *	path,
		_DIR *	dp )

Creates a new directory.

Parameters

*path	The new name/path to directory.
*dp	_DIR pointer to store an errno if something bad occurs.

Returns

True on success/False on failure and dp.errno is set.

ffopen()

bool ffopen	(	const char *	filename,
		const char *	mode,
		_FILE *	fp )

Opens a file at filename with certain access modifiers.

Parameters

filename	Filename for file to be opened/created.
*mode	This is the POSIX-styled mode string similar to the C stdlib fopen.
*fp	_FILE pointer to hold errno and internal file information.

This function can return two unique error codes besides the standard ones. These are:

HAL_FS_TOO_MANY_OPN if you're trying to open more than HAL_FS_MAX_OPEN_FILES.

HAL_FS_DOUBLE_OPEN if you're trying to open a file on an already opened _FILE pointer.

Both of these errors are resolved with ffclose() in some fashion.

Mode Strings

• 'r' = Read.
• 'w' = Write.
• '+' = Read & Write.
• 'a' = Append.
• 'x' = Create new file if not already open.

These can be combined in several ways, ie. "r+x", "+x", "ax", etc.

Note write & append cannot be used at the same time!

See also

ffclose()

Returns

True on success/False on failure and fp.errno is set.

ffopendir()

bool ffopendir	(	_DIR *	dp,
		const char *	path )

Opens the dir inside the _DIR object.

Parameters

*dp	_DIR pointer to be opened.
*path	Path to directory.

This function can return the same unique errors as ffopen(). Please see that for more info on those two unique errors.

See also

ffopen()

Note for ffreaddir(), this function must be called because this function internally opens the directory for that action. While creating new files and writing/reading them does not explicitly require you to open the directory with ffopendir in order to access them at that directory path, you should still be mindful to open it if you need the aformentioned functions.

Returns

True on success/False on failure and dp.errno is set.

ffread()

uint32_t ffread	(	_FILE *	fp,
		void *	buf,
		uint32_t	buf_size )

Reads data from the file at it's internal file position.

Parameters

*fp	Pointer to the _FILE object.
*buf	Output buffer to store the read information.
buf_size	Amount of data to read.

Typically this reads at whatever internal position the file pointer is at. This can be viewed with fftell(). This can be set with ffseek().

See also

fftell()

ffseek()

Returns

Amount of bytes read.

ffreaddir()

bool ffreaddir	(	_DIR *	dp,
		_FILE *	file_info )

Reads a directory object (file).

Parameters

*dp	_DIR pointer with opened directory.
*file_info	Resulting file information output.

This function requires a properly opened directory with ffopendir(). This function will read a file and then internally sets the current object to the next in line file in the directory. This functions similarly to the ls command on linux where it lists a file and then goes to the next and lists a file. This function also sets the filename in the passed in _FILE pointer.

See also

ffopendir()

Returns

True on success/False on failure and dp.errno is set.

ffseek()

bool ffseek	(	_FILE *	fp,
		long	offset )

Sets the file position for the specified file.

Parameters

*fp	_FILE pointer to make modification to.
offset	The new position to go to. If the offset is negative it goes backwards from the current position to zero. If offset is above the file length then it goes to end of file.

Returns

True on success/False on failure and fp.errno is set.

ffstat()

bool ffstat	(	const char *	path,
		_FILE *	file_info )

Checks whether the file exists and gets the information on the file.

Parameters

*path	File path to check.
*file_info	A _FILE struct to store the resulting information from.

If the file exists then it's information is set inside the *file_info _FILE struct. This is typically just the date and time of creation, file attributes, and size.

Returns

True on success/False on failure and fp.errno is set.

fftell()

uint32_t fftell

(

_FILE *

fp

)

Gets the current file position the file is at.

Parameters

*fp	_FILE pointer to get position from.

Returns

The current position.

ffunlink()

bool ffunlink	(	const char *	path,
		_FILE *	fp )

Deletes file/directory at path.

Parameters

*path	Path of file/directory to delete.
*fp	Just here to store the resultant errno if the function fails.

Returns

True on success/False on failure and fp.errno is set.

ffwrite()

uint32_t ffwrite	(	_FILE *	fp,
		const void *	buf,
		uint32_t	buf_size )

Writes data to the file at it's internal file position.

Parameters

*fp	Pointer to the _FILE object.
*buf	Input buffer for data to write.
buf_size	Amount of data to write.

Typically this writes at whatever internal position the file pointer is at. This can be viewed with fftell(). This can be set with ffseek().

See also

fftell()

ffseek()

Returns

Amount of bytes written.