device_io_t Struct Reference

This struct defines the interface with the user-provided device. More...

#include <device_io.h>

Data Fields
int(*	close )(int fd)
	It closes the provided file descriptor.
int(*	closedir )(DIR *dirp)
	Closes a directory.
int(*	get_attr )(const char *file)
	Gets the FAT attributes of the specified file.
bool(*	get_short_name_for )(const char *file, char *buf)
	Returns the short name of the specified file.
bool(*	isdrive )(const char *name)
	Receives a drive name and returns if it's a valid name for the device.
int(*	open )(const char *path, int flags, mode_t mode)
	Opens the file at the given path and returns a file descriptor.
void *(*	opendir )(const char *name, DIR *dirp)
	Opens a directory.
int(*	set_attr )(const char *file, uint8_t attr)
	Sets the FAT attributes of the specified file.

Detailed Description

This struct defines the interface with the user-provided device.

It's possible to leave some pointers as NULL, they will simply make the syscall to fail and set errno to ENODEV. The only mandatory callback is isdrive(), all other callbacks are optional. However, you will need at least open(), read() and close() to define an interface that can do anything useful.

All callbacks in this struct use 26 bit file descriptors. The top 4 bits are reserved because they identify the filesystem type, and the bottom 2 bits are reserved for future use. open() may only use bits 27:2 (inclusive) to define file descriptors.

Field Documentation

close

int(* device_io_t::close) (int fd)

It closes the provided file descriptor.

It must free any memory allocated by open().

Parameters

fd	File descriptor to be closed.

Returns

On success it returns 0. On failure it returns -1 and sets errno.

closedir

int(* device_io_t::closedir) (DIR *dirp)

Closes a directory.

This function must call free(dirp->dp) if opendir() has allocated it.

Parameters

dirp	DIR structure associated to the opened directory.

Returns

On success it returns 0. On failure it sets errno and returns -1.

get_attr

int(* device_io_t::get_attr) (const char *file)

Gets the FAT attributes of the specified file.

Parameters

file	File to get the attributes of.

Returns

Attributes of the file. In FAT filesystems this is a mask of ATTR_ARCHIVE, ATTR_DIRECTORY, ATTR_VOLUME, ATTR_SYSTEM, ATTR_HIDDEN and ATTR_READONLY. On error it returns -1 and sets errno.

get_short_name_for

bool(* device_io_t::get_short_name_for) (const char *file, char *buf)

Returns the short name of the specified file.

Parameters

file	File to get the short name of.
buf	Buffer to store the short file name. This buffer should be at least FAT_SHORT_FILE_NAME_MAX+1 bytes in size.

Returns

On success it returns true, on error it returns false and sets errno.

isdrive

bool(* device_io_t::isdrive) (const char *name)

Receives a drive name and returns if it's a valid name for the device.

A device can have multiple names. For example, you could support all names that start with "test" so that "test0", "test1" up to "test9" are valid names for this device.

Parameters

name	Drive name without colon or slash. For example, "fat" or "nitro", but not "fat:/" or "nitro:".

Returns

If it's a valid name for this device, true. If not, false.

open

int(* device_io_t::open) (const char *path, int flags, mode_t mode)

Opens the file at the given path and returns a file descriptor.

The callback is responsible for generating a unique file descriptor for that device. For example, it's possible to allocate a struct in main RAM with malloc(), cast it to an int, and use that as file descriptor.

Warning

Bits 31:28 and 1:0 of the descriptor are reserved and must be zero.

Returns

The file descriptor. On return, it returns -1 and sets errno.

opendir

void *(* device_io_t::opendir) (const char *name, DIR *dirp)

Opens a directory.

This function is free to allocate with malloc() its own custom struct with directory information. The pointer needs to be the value returned by this function. The other directory functions will be able to access this data by using dirp->dp.

Parameters

name	Path to the directory to be opened.
dirp	Pre-allocated DIR struct.

Returns

It returns a pointer to a user-defined struct that will be saved to dirp->dp. On error, it returns NULL and sets errno.

set_attr

int(* device_io_t::set_attr) (const char *file, uint8_t attr)

Sets the FAT attributes of the specified file.

Parameters

file	File to set the attributes of.
attr	Attributes to set. In FAT filesystems this is a mask of ATTR_ARCHIVE, ATTR_DIRECTORY, ATTR_VOLUME, ATTR_SYSTEM, ATTR_HIDDEN and ATTR_READONLY.

Returns

On success it returns 0, on error it returns -1 and sets errno.

---

The documentation for this struct was generated from the following file:

• device_io.h