File system

Access to files regardless of the file system format. More...

Modules
	File system backends
	Interface between the file system core and the file system formats.
	Pebble File System
	PFS, the wear-leveled file system on the external NOR flash.

Data Structures
struct	pbl_fs_dirent
	Directory entry, see pbl_fs_readdir() and pbl_fs_stat(). More...
struct	pbl_fs_statvfs
	Space of a file system, see pbl_fs_statvfs(). More...
struct	pbl_fs_file
	An open file, see pbl_fs_open(). More...
struct	pbl_fs_dir
	An open directory, see pbl_fs_opendir(). More...

Macros
#define	PBL_FS_NAME_MAX   255
	Maximum length of a file name, without the NUL terminator.
#define	PBL_FS_O_READ   PBL_BIT(0)
	Open for reading.
#define	PBL_FS_O_WRITE   PBL_BIT(1)
	Open for writing.
#define	PBL_FS_O_RDWR   (PBL_FS_O_READ | PBL_FS_O_WRITE)
	Open for reading and writing.
#define	PBL_FS_O_CREATE   PBL_BIT(2)
	Create the file, empty, if it does not exist.
#define	PBL_FS_O_REPLACE   PBL_BIT(3)
	Write a new, empty version of the file that replaces the current one on close.
#define	PBL_FS_O_FORMAT(n)   PBL_BIT(16 + (n))
	Format-specific open flag n, from 0 to 15.
#define	PBL_FS_SEEK_SET   0
	pbl_fs_seek() from the start of the file.
#define	PBL_FS_SEEK_CUR   1
	pbl_fs_seek() from the current position.
#define	PBL_FS_SEEK_END   2
	pbl_fs_seek() from the end of the file.
#define	PBL_FS_WATCH_CLOSED   PBL_BIT(0)
	pbl_fs_watch_add() event: a file opened for writing was closed.
#define	PBL_FS_WATCH_REMOVED   PBL_BIT(1)
	pbl_fs_watch_add() event: the file was removed.
#define	PBL_FS_WATCH_ALL   (PBL_FS_WATCH_CLOSED | PBL_FS_WATCH_REMOVED)
	pbl_fs_watch_add() events: all of them.

Typedefs
typedef void(*	pbl_fs_watch_cb_t) (void *user_data)
	Callback of pbl_fs_watch_add().

Enumerations
enum	pbl_fs_dir_entry_type { PBL_FS_DIR_ENTRY_FILE , PBL_FS_DIR_ENTRY_DIR }
	Type of a directory entry. More...

Functions
int	pbl_fs_mount (struct pbl_fs_mount *mp)
	Mount a file system.
int	pbl_fs_unmount (struct pbl_fs_mount *mp)
	Unmount a file system.
int	pbl_fs_format (const char *mnt_point)
	Erase every file of a mounted file system.
int	pbl_fs_open (struct pbl_fs_file *file, const char *path, uint32_t flags)
	Open a file.
ssize_t	pbl_fs_read (struct pbl_fs_file *file, void *buf, size_t len)
	Read from the current position, then advance it.
ssize_t	pbl_fs_write (struct pbl_fs_file *file, const void *buf, size_t len)
	Write at the current position, then advance it.
off_t	pbl_fs_seek (struct pbl_fs_file *file, off_t offset, int whence)
	Set the current position.
off_t	pbl_fs_tell (struct pbl_fs_file *file)
	Get the current position.
off_t	pbl_fs_size (struct pbl_fs_file *file)
	Get the size of an open file.
int	pbl_fs_truncate (struct pbl_fs_file *file, off_t length)
	Set the size of a file.
int	pbl_fs_sync (struct pbl_fs_file *file)
	Flush cached data of a file to the storage.
int	pbl_fs_close (struct pbl_fs_file *file)
	Close a file.
int	pbl_fs_unlink (const char *path)
	Remove a file.
int	pbl_fs_rename (const char *from, const char *to)
	Rename a file, replacing to if it exists.
int	pbl_fs_mkdir (const char *path)
	Create a directory.
int	pbl_fs_stat (const char *path, struct pbl_fs_dirent *entry)
	Get the type and size of a file or directory.
int	pbl_fs_statvfs (const char *path, struct pbl_fs_statvfs *stat)
	Get the space of the file system holding a path.
int	pbl_fs_opendir (struct pbl_fs_dir *dir, const char *path)
	Open a directory.
int	pbl_fs_readdir (struct pbl_fs_dir *dir, struct pbl_fs_dirent *entry)
	Read the next entry of a directory.
int	pbl_fs_closedir (struct pbl_fs_dir *dir)
	Close a directory.
struct pbl_fs_watch *	pbl_fs_watch_add (const char *path, uint32_t events, pbl_fs_watch_cb_t cb, void *user_data)
	Watch a file for changes.
void	pbl_fs_watch_remove (struct pbl_fs_watch *watch)
	Stop watching a file.

Detailed Description

Access to files regardless of the file system format.

File systems are mounted at absolute paths, such as the root "/" or "/sdcard", and files are reached through paths below them, such as "/pindb". A path belongs to the mount with the longest matching mount point. The format behind a mount point is a backend (struct pbl_fs_ops); formats differ in what they support:

• Some formats have fixed-size files: a file then gets its size from pbl_fs_truncate() once, right after it is created, and reads and writes stay within it.
• Some formats have no directories, and their file names may contain '/'.

Every function returns 0 (or a count or offset) on success and a negative errno on failure, -ENOTSUP for what the format does not support. Files and directories are handles owned by the caller; a handle is used by one thread at a time.

struct pbl_fs_file f;
int ret = pbl_fs_open(&f, "/myfile", PBL_FS_O_RDWR | PBL_FS_O_CREATE);
if (ret == 0) {
  if (pbl_fs_size(&f) == 0) {
    ret = pbl_fs_truncate(&f, 128);
  }
  if (ret == 0) {
    ret = pbl_fs_write(&f, data, sizeof(data));
  }
  pbl_fs_close(&f);
}

---

Data Structure Documentation

pbl_fs_dirent

struct pbl_fs_dirent

Directory entry, see pbl_fs_readdir() and pbl_fs_stat().

Data Fields
char	name[PBL_FS_NAME_MAX+1]	NUL-terminated name, relative to the directory.
size_t	size	Size of a file in bytes.
enum pbl_fs_dir_entry_type	type	Type of the entry.

pbl_fs_statvfs

struct pbl_fs_statvfs

Space of a file system, see pbl_fs_statvfs().

Data Fields
unsigned long	f_bfree	Space available for new data in f_frsize units.
unsigned long	f_blocks	Size of the file system in f_frsize units.
unsigned long	f_bsize	Optimal transfer size in bytes.
unsigned long	f_frsize	Allocation unit in bytes.

pbl_fs_file

struct pbl_fs_file

An open file, see pbl_fs_open().

Data Fields
void *	filep	Private to the backend.
uint32_t	flags	Private to the core.
struct pbl_fs_mount *	mp	Private to the core.
const char *	name	Set by the backend on open: name relative to the mount point, valid until closed.

pbl_fs_dir

struct pbl_fs_dir

An open directory, see pbl_fs_opendir().

Data Fields
void *	dirp	Private to the backend.
struct pbl_fs_mount *	mp	Private to the core.

Macro Definition Documentation

PBL_FS_NAME_MAX

#define PBL_FS_NAME_MAX   255

Maximum length of a file name, without the NUL terminator.

PBL_FS_O_CREATE

#define PBL_FS_O_CREATE   PBL_BIT(2)

Create the file, empty, if it does not exist.

PBL_FS_O_FORMAT

#define PBL_FS_O_FORMAT

(

n

)

PBL_BIT(16 + (n))

Format-specific open flag n, from 0 to 15.

Hints that formats without the flag ignore. The formats define their own names for them.

PBL_FS_O_RDWR

#define PBL_FS_O_RDWR   (PBL_FS_O_READ | PBL_FS_O_WRITE)

Open for reading and writing.

PBL_FS_O_READ

#define PBL_FS_O_READ   PBL_BIT(0)

Open for reading.

PBL_FS_O_REPLACE

#define PBL_FS_O_REPLACE   PBL_BIT(3)

Write a new, empty version of the file that replaces the current one on close.

Until pbl_fs_close(), opening the path returns the current version, and a reboot keeps it. Fails with -ENOENT if the file does not exist, unless PBL_FS_O_CREATE is set, which then creates it as usual. Implies PBL_FS_O_WRITE.

PBL_FS_O_WRITE

#define PBL_FS_O_WRITE   PBL_BIT(1)

Open for writing.

PBL_FS_SEEK_CUR

#define PBL_FS_SEEK_CUR   1

pbl_fs_seek() from the current position.

PBL_FS_SEEK_END

#define PBL_FS_SEEK_END   2

pbl_fs_seek() from the end of the file.

PBL_FS_SEEK_SET

#define PBL_FS_SEEK_SET   0

pbl_fs_seek() from the start of the file.

PBL_FS_WATCH_ALL

#define PBL_FS_WATCH_ALL   (PBL_FS_WATCH_CLOSED | PBL_FS_WATCH_REMOVED)

pbl_fs_watch_add() events: all of them.

PBL_FS_WATCH_CLOSED

#define PBL_FS_WATCH_CLOSED   PBL_BIT(0)

pbl_fs_watch_add() event: a file opened for writing was closed.

PBL_FS_WATCH_REMOVED

#define PBL_FS_WATCH_REMOVED   PBL_BIT(1)

pbl_fs_watch_add() event: the file was removed.

Typedef Documentation

pbl_fs_watch_cb_t

typedef void(* pbl_fs_watch_cb_t) (void *user_data)

Callback of pbl_fs_watch_add().

Runs on the thread that closed or removed the file. It must not add or remove watches.

Parameters

user_data

Data passed to pbl_fs_watch_add().

Enumeration Type Documentation

pbl_fs_dir_entry_type

enum pbl_fs_dir_entry_type

Type of a directory entry.

Enumerator
PBL_FS_DIR_ENTRY_FILE	Regular file.
PBL_FS_DIR_ENTRY_DIR	Directory.

Function Documentation

pbl_fs_close()

int pbl_fs_close

(

struct pbl_fs_file *

file

)

Close a file.

Commits a PBL_FS_O_REPLACE version and notifies watchers if the file was open for writing. The handle is invalid afterwards, even on failure.

Parameters

file	Open file.

pbl_fs_closedir()

int pbl_fs_closedir

(

struct pbl_fs_dir *

dir

)

Close a directory.

Parameters

dir	Open directory.

pbl_fs_format()

int pbl_fs_format

(

const char *

mnt_point

)

Erase every file of a mounted file system.

Files open on it become invalid; they still have to be closed.

Parameters

mnt_point

Mount point.

Return values

-ENOENT

Nothing is mounted at mnt_point.

pbl_fs_mkdir()

int pbl_fs_mkdir

(

const char *

path

)

Create a directory.

Parameters

path	Absolute path.

pbl_fs_mount()

int pbl_fs_mount

(

struct pbl_fs_mount *

mp

)

Mount a file system.

Parameters

mp	Mount, with its mount point and format set.

Return values

-EBUSY	The mount point is in use.
-EINVAL	Invalid mount point.

Returns

Other negative errno from the backend.

pbl_fs_open()

int pbl_fs_open	(	struct pbl_fs_file *	file,
		const char *	path,
		uint32_t	flags
	)

Open a file.

Parameters

file	Handle to initialize.
path	Absolute path.
flags	PBL_FS_O_* flags.

Return values

-ENOENT	The file does not exist and is not to be created, or nothing is mounted there.
-EBUSY	The file is already open, on formats that open a file only once.
-EMFILE	Too many open files.
-ENOSPC	Not enough space.

Returns

Other negative errno on failure.

pbl_fs_opendir()

int pbl_fs_opendir	(	struct pbl_fs_dir *	dir,
		const char *	path
	)

Open a directory.

Parameters

dir	Handle to initialize.
path	Absolute path, such as a mount point.

pbl_fs_read()

ssize_t pbl_fs_read	(	struct pbl_fs_file *	file,
		void *	buf,
		size_t	len
	)

Read from the current position, then advance it.

Parameters

file	Open file.
buf	Destination buffer.
len	Number of bytes to read.

Returns

Number of bytes read, less than len at the end of the file, or negative errno.

pbl_fs_readdir()

int pbl_fs_readdir	(	struct pbl_fs_dir *	dir,
		struct pbl_fs_dirent *	entry
	)

Read the next entry of a directory.

Entries may come in any order. Removing a file while reading does not change the entries still to come.

Parameters

	dir	Open directory.
[out]	entry	Next entry, with an empty name once there are no more.

pbl_fs_rename()

int pbl_fs_rename	(	const char *	from,
		const char *	to
	)

Rename a file, replacing to if it exists.

Parameters

from	Absolute path of the file.
to	New absolute path, on the same file system.

Return values

-EXDEV

The paths are on different file systems.

pbl_fs_seek()

off_t pbl_fs_seek	(	struct pbl_fs_file *	file,
		off_t	offset,
		int	whence
	)

Set the current position.

Parameters

file	Open file.
offset	Offset from whence.
whence	PBL_FS_SEEK_SET, PBL_FS_SEEK_CUR or PBL_FS_SEEK_END.

Returns

New position, or negative errno.

Return values

-EINVAL

The position is outside the file, on formats with fixed-size files.

pbl_fs_size()

off_t pbl_fs_size

(

struct pbl_fs_file *

file

)

Get the size of an open file.

Parameters

file	Open file.

Returns

Size in bytes, or negative errno.

pbl_fs_stat()

int pbl_fs_stat	(	const char *	path,
		struct pbl_fs_dirent *	entry
	)

Get the type and size of a file or directory.

Parameters

	path	Absolute path.
[out]	entry	Type, size and name (the last component of path).

Return values

-ENOENT

It does not exist.

pbl_fs_statvfs()

int pbl_fs_statvfs	(	const char *	path,
		struct pbl_fs_statvfs *	stat
	)

Get the space of the file system holding a path.

Parameters

	path	Absolute path.
[out]	stat	Space.

pbl_fs_sync()

int pbl_fs_sync

(

struct pbl_fs_file *

file

)

Flush cached data of a file to the storage.

Parameters

file	Open file.

pbl_fs_tell()

off_t pbl_fs_tell

(

struct pbl_fs_file *

file

)

Get the current position.

Parameters

file	Open file.

Returns

Current position, or negative errno.

pbl_fs_truncate()

int pbl_fs_truncate	(	struct pbl_fs_file *	file,
		off_t	length
	)

Set the size of a file.

On formats with fixed-size files, sets the size of a file that is still empty, after PBL_FS_O_CREATE or PBL_FS_O_REPLACE; other sizes fail with -ENOTSUP. The new space reads as erased flash there (0xff), and as zeros on other formats.

Parameters

file	File opened for writing.
length	New size in bytes.

Return values

-ENOSPC

Not enough space.

pbl_fs_unlink()

int pbl_fs_unlink

(

const char *

path

)

Remove a file.

Parameters

path	Absolute path.

Return values

-ENOENT

The file does not exist.

pbl_fs_unmount()

int pbl_fs_unmount

(

struct pbl_fs_mount *

mp

)

Unmount a file system.

Parameters

mp	Mount passed to pbl_fs_mount().

pbl_fs_watch_add()

struct pbl_fs_watch * pbl_fs_watch_add	(	const char *	path,
		uint32_t	events,
		pbl_fs_watch_cb_t	cb,
		void *	user_data
	)

Watch a file for changes.

Parameters

path	Absolute path of the file, which need not exist.
events	PBL_FS_WATCH_* events that run cb.
cb	Callback.
user_data	Data passed to cb.

Returns

Watch, for pbl_fs_watch_remove(). Never NULL.

pbl_fs_watch_remove()

void pbl_fs_watch_remove

(

struct pbl_fs_watch *

watch

)

Stop watching a file.

Parameters

watch

Watch returned by pbl_fs_watch_add().

pbl_fs_write()

ssize_t pbl_fs_write	(	struct pbl_fs_file *	file,
		const void *	buf,
		size_t	len
	)

Write at the current position, then advance it.

Parameters

file	File opened for writing.
buf	Data to write.
len	Number of bytes to write.

Returns

Number of bytes written, or negative errno.

Return values

-EFBIG

The write goes past the end of a fixed-size file.