fm_io_t Struct Reference

The card: every function set, each answering FM_OK or the reason it failed. ctx is passed to each of them. More...

#include <fm_io.h>

Data Fields
bool(*)	mounted (void *ctx)
	Whether a volume is mounted now.
unsigned(*)	mounts (void *ctx)
	The mount number: another one after a card is put in.
bool(*)	hold (void *ctx, unsigned mount)
	Keep the volume of mount mount for the calls that follow, until release().
void(*)	release (void *ctx)
	The end of a hold() that answered true.
fm_err_t(*)	walk (void *ctx, const char *dir, fm_visit_fn visit, void *vctx, unsigned *unlisted)
	Hand every entry of folder dir to visit, in the order the volume holds them.
fm_err_t(*)	stat (void *ctx, const char *path, fm_stat_t *out)
	The size and kind of one name.
fm_err_t(*)	mkdir (void *ctx, const char *path)
	Make folder path, whose parent is there.
fm_err_t(*)	unlink (void *ctx, const char *path)
	Delete file path.
fm_err_t(*)	rmdir (void *ctx, const char *path)
	Delete the empty folder path.
fm_err_t(*)	rename (void *ctx, const char *from, const char *to)
	Give from the path to, on the one volume: no data moves.
fm_err_t(*)	open (void *ctx, const char *path, fm_mode_t mode, void **file)
	Open file path.
fm_err_t(*)	read (void *ctx, void *file, uint8_t *buf, size_t cap, size_t *got)
	Read up to cap bytes from the file's position on.
fm_err_t(*)	write (void *ctx, void *file, const uint8_t *buf, size_t len)
	Write len bytes at the file's end, all of them or fail.
fm_err_t(*)	sync (void *ctx, void *file)
	Put what was written on the card: fflush() and fsync().
fm_err_t(*)	close (void *ctx, void *file)
	Close an open() handle.
void *	ctx

Detailed Description

The card: every function set, each answering FM_OK or the reason it failed. ctx is passed to each of them.

A call that finds the card gone answers FM_ERR_CARD_GONE; one with nothing mounted FM_ERR_NO_CARD. A file handle from open() is closed by close(), also after a failure; close() of a card gone frees the handle.

Field Documentation

close

fm_err_t(*) fm_io_t::close(void *ctx, void *file)

Close an open() handle.

Parameters

ctx	the card's context
file	the handle; invalid afterwards whatever the answer

Returns

FM_OK, or why the last bytes did not reach the card

ctx

void* fm_io_t::ctx

passed to every function

hold

bool(*) fm_io_t::hold(void *ctx, unsigned mount)

Keep the volume of mount mount for the calls that follow, until release().

Parameters

ctx	the card's context
mount	the mount number the caller read its names from

Returns

false when that volume is no longer mounted; then nothing is held and release() is not called

mkdir

fm_err_t(*) fm_io_t::mkdir(void *ctx, const char *path)

Make folder path, whose parent is there.

Parameters

ctx	the card's context
path	the new folder's path

Returns

FM_OK, or FM_ERR_EXISTS for a taken name

mounted

bool(*) fm_io_t::mounted(void *ctx)

Whether a volume is mounted now.

Parameters

ctx	the card's context

Returns

true while a volume is mounted

mounts

unsigned(*) fm_io_t::mounts(void *ctx)

The mount number: another one after a card is put in.

Parameters

ctx	the card's context

Returns

the number of the volume mounted now

open

fm_err_t(*) fm_io_t::open(void *ctx, const char *path, fm_mode_t mode, void **file)

Open file path.

Parameters

ctx	the card's context
path	the file's path
mode	read an existing file, or make a new one
file	takes the handle on FM_OK

Returns

FM_OK, or why not

read

fm_err_t(*) fm_io_t::read(void *ctx, void *file, uint8_t *buf, size_t cap, size_t *got)

Read up to cap bytes from the file's position on.

Parameters

ctx	the card's context
file	an open() handle
buf	takes the bytes
cap	room in buf
got	takes the count read, 0 at the file's end

Returns

FM_OK, or why not

release

void(*) fm_io_t::release(void *ctx)

The end of a hold() that answered true.

Parameters

ctx	the card's context

rename

fm_err_t(*) fm_io_t::rename(void *ctx, const char *from, const char *to)

Give from the path to, on the one volume: no data moves.

FAT renames over no existing name: a taken to is FM_ERR_EXISTS, except the same entry with its case changed.

Parameters

ctx	the card's context
from	the entry's path now
to	its new path

Returns

FM_OK, or why not

rmdir

fm_err_t(*) fm_io_t::rmdir(void *ctx, const char *path)

Delete the empty folder path.

Parameters

ctx	the card's context
path	the folder's path

Returns

FM_OK; FM_ERR_NOT_EMPTY or FM_ERR_DENIED for a folder that holds entries

stat

fm_err_t(*) fm_io_t::stat(void *ctx, const char *path, fm_stat_t *out)

The size and kind of one name.

Parameters

ctx	the card's context
path	the name's path from the root
out	takes the answer

Returns

FM_OK, or FM_ERR_NOT_FOUND for no such name

sync

fm_err_t(*) fm_io_t::sync(void *ctx, void *file)

Put what was written on the card: fflush() and fsync().

Parameters

ctx	the card's context
file	an FM_OPEN_NEW handle

Returns

FM_OK, or why not

unlink

fm_err_t(*) fm_io_t::unlink(void *ctx, const char *path)

Delete file path.

Parameters

ctx	the card's context
path	the file's path

Returns

FM_OK, or FM_ERR_NOT_FOUND

walk

fm_err_t(*) fm_io_t::walk(void *ctx, const char *dir, fm_visit_fn visit, void *vctx, unsigned *unlisted)

Hand every entry of folder dir to visit, in the order the volume holds them.

Every entry is either handed to visit or counted in unlisted, with no third way: an implementation that leaves an entry out (a name over FM_LIST_NAME_MAX bytes, which it cannot hand over whole; a name starting with ".", the files a Mac writes) counts it. The panel's walk is storage_walk_counted() with no suffix filter, its left_out the count. A folder whose walk visits nothing and counts nothing is empty, and only such a folder is moved or deleted (fm_ops.h).

Parameters

ctx	the card's context
dir	the folder, a path from the root
visit	called per entry
vctx	passed to visit
unlisted	takes the count of entries not handed over; may be NULL

Returns

FM_OK at the folder's end; FM_ERR_NOT_FOUND for no such folder; FM_ERR_CARD_GONE when the card was found gone part way, and what was visited is the old card's

write

fm_err_t(*) fm_io_t::write(void *ctx, void *file, const uint8_t *buf, size_t len)

Write len bytes at the file's end, all of them or fail.

Parameters

ctx	the card's context
file	an FM_OPEN_NEW handle
buf	the bytes
len	how many

Returns

FM_OK; FM_ERR_FULL for a full card

---

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

• shared/files/include/fm_io.h