File Interface

An API that enables integration of standard C library with an arbitrary file system. More...

Content
	Definitions

Data Structures
struct	rt_fs_time_t
	Time and Date Information. More...
struct	rt_fs_stat_t
	File Status Information. More...

Functions
int32_t	rt_fs_open (const char *path, int32_t mode)
	Open a file.
int32_t	rt_fs_close (int32_t fd)
	Close a file.
int32_t	rt_fs_write (int32_t fd, const void *buf, uint32_t cnt)
	Write to a file.
int32_t	rt_fs_read (int32_t fd, void *buf, uint32_t cnt)
	Read from a file.
int64_t	rt_fs_seek (int32_t fd, int64_t offset, int32_t whence)
	Move the file position pointer.
int64_t	rt_fs_size (int32_t fd)
	Get file size.
int32_t	rt_fs_stat (int32_t fd, rt_fs_stat_t *stat)
	Get file status information.
int32_t	rt_fs_remove (const char *path)
	Remove a file or directory.
int32_t	rt_fs_rename (const char *oldpath, const char *newpath)
	Rename or move a file or directory.

Description

An API that enables integration of standard C library with an arbitrary file system.

---

Data Structure Documentation

rt_fs_time_t

struct rt_fs_time_t

Time and Date Information.

This struct contains time and date information, including seconds, minutes, hours, day of the month, month of the year and year. Values outside of the specified range are treated as invalid. Reserved bits should be ignored.

Data Fields
uint16_t	year	Year.
uint8_t	mon	Month of year [0, 11].
uint8_t	day	Day of month [1, 31].
uint8_t	hour	Hours [0, 23].
uint8_t	min	Minutes [0, 59].
uint8_t	sec	Seconds [0, 60].
uint8_t	rsvd	Reserved.

rt_fs_stat_t

struct rt_fs_stat_t

File Status Information.

This struct contains various attributes and metadata about a file or directory in a filesystem, including its attribute bitmap, access time, modification time, change time and filesystem specific block size and block count allocated to store the file.

Data Fields
uint32_t	attr	File attribute bitmap.
rt_fs_time_t	access	Last file data access timestamp.
rt_fs_time_t	modify	Last file data modification timestamp.
rt_fs_time_t	change	Last file object change timestamp.
uint32_t	blksize	The size of filesystem block.
uint32_t	blkcount	Number of allocated filesystem blocks.

Function Documentation

rt_fs_open()

int32_t rt_fs_open	(	const char *	path,
		int32_t	mode
	)

Open a file.

Parameters

[in]	path	string specifying the pathname of the file to be opened
[in]	mode	integer bitmap specifying the file open mode

Returns

a non-negative integer representing the file descriptor on success, or error code on failure

This function opens a file specified by the pathname.

The mode parameter is a bitmap that specifies the file open mode. The following bits are exclusive:

• FS_OPEN_RDONLY: open file for reading only
• FS_OPEN_WRONLY: open file for writing only
• FS_OPEN_RDWR: open file for reading and writing

In addition, any combination of the values below can be set:

• FS_OPEN_APPEND: if set, the file offset is set to the end of file prior to each write
• FS_OPEN_CREATE: if set, the file is created if it does not exist
• FS_OPEN_TRUNCATE: if set, the size of an existing file opened for writing is truncated to zero

The file position offset shall be set to the beginning of the file unless append mode is specified.

rt_fs_close()

int32_t rt_fs_close

(

int32_t

fd

)

Close a file.

Parameters

[in]

fd

file descriptor of an opened file

Returns

zero if the file was successfully closed, or error code on failure

This function closes the file associated with the file descriptor fd.

rt_fs_write()

int32_t rt_fs_write	(	int32_t	fd,
		const void *	buf,
		uint32_t	cnt
	)

Write to a file.

Parameters

[in]	fd	file descriptor of an opened file
[in]	buf	pointer to the buffer containing data to write
[in]	cnt	number of bytes to write

Returns

number of bytes actually written, or error code on failure

This function shall write cnt bytes from the buffer pointed to by buf to the file associated with the open file descriptor, fd.

rt_fs_read()

int32_t rt_fs_read	(	int32_t	fd,
		void *	buf,
		uint32_t	cnt
	)

Read from a file.

Parameters

[in]	fd	file descriptor of an opened file
[out]	buf	pointer to the buffer to store read data
[in]	cnt	number of bytes to read

Returns

number of bytes actually read, 0 at the EOF, or error code on failure

This function reads cnt bytes from the file associated with the file descriptor fd, into the buffer pointed to by buf. The actual number of bytes read can be less than cnt.

rt_fs_seek()

int64_t rt_fs_seek	(	int32_t	fd,
		int64_t	offset,
		int32_t	whence
	)

Move the file position pointer.

Parameters

[in]	fd	file descriptor of an opened file
[in]	offset	the number of bytes to move
[in]	whence	file position location (RT_SEEK_SET, RT_SEEK_CUR, RT_SEEK_END)

Returns

current file position from the beginning of the file, or error code on failure

This functions moves the file position pointer as specified with parameters offset and whence. Parameter whence can have the following possible values:

• RT_SEEK_SET: set the file position pointer to offset bytes from the start of the file
• RT_SEEK_CUR: set the file position pointer to offset bytes from the current location
• RT_SEEK_END: set the file position pointer to offset bytes from the end of the file

rt_fs_size()

int64_t rt_fs_size

(

int32_t

fd

)

Get file size.

Parameters

[in]

fd

file descriptor of an opened file

Returns

file size in bytes, or error code on failure

This function retrieves the size of an opened file.

rt_fs_stat()

int32_t rt_fs_stat	(	int32_t	fd,
		rt_fs_stat_t *	stat
	)

Get file status information.

Parameters

[in]	fd	file descriptor of an opened file
[out]	stat	pointer to a rt_fs_stat_t object to store the status information in

Returns

zero if the file status was successfully retrieved, or error code on failure

This function retrieves status information about the file associated with the given file descriptor. The status information is stored in the rt_fs_stat_t struct pointed to by stat. The function shall return with error if fd is not a valid file descriptor or if parameter stat is NULL.

rt_fs_remove()

int32_t rt_fs_remove

(

const char *

path

)

Remove a file or directory.

Parameters

[in]

path

string specifying the pathname

Returns

zero if the file or directory was successfully removed, or error code on failure

If removing a directory, the directory must be empty.

rt_fs_rename()

int32_t rt_fs_rename	(	const char *	oldpath,
		const char *	newpath
	)

Rename or move a file or directory.

Parameters

[in]	oldpath	string specifying file or directory to be renamed
[in]	newpath	string specifying the new pathname

Returns

zero if the file or directory was successfully renamed or moved, or error code on failure

This function changes the name of a file or directory.

If the destination exists, it must match the source in type. If the destination is a directory, the directory must be empty.