The Contiki file system interface
[Contiki system]

The Contiki file system interface (CFS) defines an abstract API for reading directories and for reading and writing files. More...

Files
file	cfs-coffee.h
	Header for the Coffee file system.
file	cfs.h
	CFS header file.
Defines
#define	CFS_COFFEE_IO_FLASH_AWARE 0x1
	Instruct Coffee that the access pattern to this file is adapted to flash I/O semantics by design, and Coffee should therefore not invoke its own micro logs when file modifications occur.
#define	CFS_COFFEE_IO_FIRM_SIZE 0x2
	Instruct Coffee not to attempt to extend the file when there is an attempt to write past the reserved file size.
#define	CFS_READ 1
	Specify that cfs_open() should open a file for reading.
#define	CFS_WRITE 2
	Specify that cfs_open() should open a file for writing.
#define	CFS_APPEND 4
	Specify that cfs_open() should append written data to the file rather than overwriting it.
#define	CFS_SEEK_SET 0
	Specify that cfs_seek() should compute the offset from the beginning of the file.
#define	CFS_SEEK_CUR 1
	Specify that cfs_seek() should compute the offset from the current position of the file pointer.
#define	CFS_SEEK_END 2
	Specify that cfs_seek() should compute the offset from the end of the file.
Functions
CCIF int	cfs_open (const char *name, int flags)
	Open a file.
CCIF void	cfs_close (int fd)
	Close an open file.
CCIF int	cfs_read (int fd, void *buf, unsigned int len)
	Read data from an open file.
CCIF int	cfs_write (int fd, const void *buf, unsigned int len)
	Write data to an open file.
CCIF cfs_offset_t	cfs_seek (int fd, cfs_offset_t offset, int whence)
	Seek to a specified position in an open file.
CCIF int	cfs_remove (const char *name)
	Remove a file.
CCIF int	cfs_opendir (struct cfs_dir dirp, const char name)
	Open a directory for reading directory entries.
CCIF int	cfs_readdir (struct cfs_dir dirp, struct cfs_dirent dirent)
	Read a directory entry.
CCIF void	cfs_closedir (struct cfs_dir *dirp)
	Close a directory opened with cfs_opendir().
Functions called from application programs

int	cfs_coffee_reserve (const char *name, cfs_offset_t size)
	Reserve space for a file.
int	cfs_coffee_configure_log (const char *file, unsigned log_size, unsigned log_entry_size)
	Configure the on-demand log file.
int	cfs_coffee_set_io_semantics (int fd, unsigned flags)
	Set the I/O semantics for accessing a file.
int	cfs_coffee_format (void)
	Format the storage area assigned to Coffee.
void *	cfs_coffee_get_protected_mem (unsigned *size)
	Points out a memory region that may not be altered during checkpointing operations that use the file system.

Detailed Description

The Contiki file system interface (CFS) defines an abstract API for reading directories and for reading and writing files.

The CFS API is intentionally simple. The CFS API is modeled after the POSIX file API, and slightly simplified.

Define Documentation

#define CFS_APPEND 4

Specify that cfs_open() should append written data to the file rather than overwriting it.

This constant indicates to cfs_open() that a file that should be opened for writing gets written data appended to the end of the file. The default behaviour (without CFS_APPEND) is that the file is overwritten with the new data.

See also:: cfs_open()

Examples:: example-rudolph0.c, example-rudolph1.c, and example-rudolph2.c.

Definition at line 118 of file cfs.h.

Referenced by cfs_open().

#define CFS_COFFEE_IO_FIRM_SIZE 0x2

Instruct Coffee not to attempt to extend the file when there is an attempt to write past the reserved file size.

A case when this is necessary is when the file has a firm size limit, and a safeguard is needed to protect against writes beyond this limit.

See also:: cfs_coffee_set_io_semantics()

Definition at line 64 of file cfs-coffee.h.

#define CFS_COFFEE_IO_FLASH_AWARE 0x1

Instruct Coffee that the access pattern to this file is adapted to flash I/O semantics by design, and Coffee should therefore not invoke its own micro logs when file modifications occur.

This semantical I/O setting is useful when implementing flash storage algorithms on top of Coffee.

See also:: cfs_coffee_set_io_semantics()

Definition at line 53 of file cfs-coffee.h.

#define CFS_READ 1

Specify that cfs_open() should open a file for reading.

This constant indicates to cfs_open() that a file should be opened for reading. CFS_WRITE should be used if the file is opened for writing, and CFS_READ + CFS_WRITE indicates that the file is opened for both reading and writing.

See also:: cfs_open()

Examples:: example-rudolph0.c, example-rudolph1.c, and example-rudolph2.c.

Definition at line 90 of file cfs.h.

Referenced by cfs_open(), and cfs_read().

#define CFS_SEEK_CUR 1

Specify that cfs_seek() should compute the offset from the current position of the file pointer.

See also:: cfs_seek()

Definition at line 136 of file cfs.h.

Referenced by cfs_seek(), and elfloader_arch_relocate().

#define CFS_SEEK_END 2

Specify that cfs_seek() should compute the offset from the end of the file.

See also:: cfs_seek()

Definition at line 145 of file cfs.h.

Referenced by cfs_seek().

#define CFS_SEEK_SET 0

Specify that cfs_seek() should compute the offset from the beginning of the file.

See also:: cfs_seek()

Examples:: example-rudolph0.c, example-rudolph1.c, and example-rudolph2.c.

Definition at line 127 of file cfs.h.

Referenced by cfs_seek(), elfloader_arch_relocate(), and elfloader_arch_write_rom().

#define CFS_WRITE 2

Specify that cfs_open() should open a file for writing.

This constant indicates to cfs_open() that a file should be opened for writing. CFS_READ should be used if the file is opened for reading, and CFS_READ + CFS_WRITE indicates that the file is opened for both reading and writing.

See also:: cfs_open()

Examples:: example-rudolph0.c, example-rudolph1.c, and example-rudolph2.c.

Definition at line 104 of file cfs.h.

Referenced by cfs_open(), and cfs_write().

Function Documentation

CCIF void cfs_close ( int fd )

Close an open file.

Parameters:

fd

The file descriptor of the open file.

This function closes a file that has previously been opened with cfs_open().

Definition at line 1034 of file cfs-coffee.c.

CCIF void cfs_closedir ( struct cfs_dir * dirp )

Close a directory opened with cfs_opendir().

Parameters:

dirp

A pointer to a struct cfs_dir that has been opened with cfs_opendir().

See also:: cfs_opendir(); cfs_readdir()

Definition at line 1284 of file cfs-coffee.c.

int cfs_coffee_configure_log	(	const char *	file,
		unsigned	log_size,
		unsigned	log_entry_size
	)

Configure the on-demand log file.

Parameters:

	file	The filename.
	log_size	The total log size.
	log_entry_size	The log entry size.

Returns:: 0 on success, -1 on failure.

When file data is first modified, Coffee creates a micro log for the file. The micro log stores a table of modifications whose parameters--the log size and the log entry size--can be modified through the cfs_coffee_configure_log function.

Definition at line 1296 of file cfs-coffee.c.

int cfs_coffee_format ( void )

Format the storage area assigned to Coffee.

Returns:: 0 on success, -1 on failure.

Coffee formats the underlying storage by setting all bits to zero. Formatting must be done before using Coffee for the first time in a mote.

Definition at line 1340 of file cfs-coffee.c.

void* cfs_coffee_get_protected_mem ( unsigned * size )

Points out a memory region that may not be altered during checkpointing operations that use the file system.

Parameters:

size

Returns:: A pointer to the protected memory.

This function returns the protected memory pointer and writes its size to the given parameter. Mainly used by sensornet checkpointing to protect the coffee state during CFS-based checkpointing operations.

Definition at line 1362 of file cfs-coffee.c.

int cfs_coffee_reserve	(	const char *	name,
		cfs_offset_t	size
	)

Reserve space for a file.

Parameters:

	name	The filename.
	size	The size of the file.

Returns:: 0 on success, -1 on failure.

Coffee uses sequential page structures for files. The sequential structure can be reserved with a certain size. If a file has not been reserved when it is opened for the first time, it will be allocated with a default size.

Definition at line 1290 of file cfs-coffee.c.

int cfs_coffee_set_io_semantics	(	int	fd,
		unsigned	flags
	)

Set the I/O semantics for accessing a file.

Parameters:

	fd	The file descriptor through which the file is accessed.
	flags	A bit vector of flags.

Coffee is used on a wide range of storage types, and the default I/O file semantics may not be optimal for the access pattern of a certain file. Hence, this functions allows programmers to switch the /O semantics on a file that is accessed through a particular file descriptor.

CCIF int cfs_open	(	const char *	name,
		int	flags
	)

Open a file.

Parameters:

	name	The name of the file.
	flags	CFS_READ, or CFS_WRITE/CFS_APPEND, or both.

Returns:: A file descriptor, if the file could be opened, or -1 if the file could not be opened.

This function opens a file and returns a file descriptor for the opened file. If the file could not be opened, the function returns -1. The function can open a file for reading or writing, or both.

An opened file must be closed with cfs_close().

See also:: CFS_READ; CFS_WRITE; cfs_close()

Definition at line 998 of file cfs-coffee.c.

References CFS_APPEND, CFS_READ, and CFS_WRITE.

CCIF int cfs_opendir	(	struct cfs_dir *	dirp,
		const char *	name
	)

Open a directory for reading directory entries.

Parameters:

	dirp	A pointer to a struct cfs_dir that is filled in by the function.
	name	The name of the directory.

Returns:: 0 or -1 if the directory could not be opened.

See also:: cfs_readdir(); cfs_closedir()

Definition at line 1247 of file cfs-coffee.c.

CCIF int cfs_read	(	int	fd,
		void *	buf,
		unsigned int	len
	)

Read data from an open file.

Parameters:

	fd	The file descriptor of the open file.
	buf	The buffer in which data should be read from the file.
	len	The number of bytes that should be read.

Returns:: The number of bytes that was actually read from the file.

This function reads data from an open file into a buffer. The file must have first been opened with cfs_open() and the CFS_READ flag.

Definition at line 85 of file cfs-eeprom.c.

References CFS_READ, and eeprom_read().

CCIF int cfs_readdir	(	struct cfs_dir *	dirp,
		struct cfs_dirent *	dirent
	)

Read a directory entry.

Parameters:

	dirp	A pointer to a struct cfs_dir that has been opened with cfs_opendir().
	dirent	A pointer to a struct cfs_dirent that is filled in by cfs_readdir()

Return values:

	0	If a directory entry was read.
	-1	If no more directory entries can be read.

See also:: cfs_opendir(); cfs_closedir()

Definition at line 1258 of file cfs-coffee.c.

CCIF int cfs_remove ( const char * name )

Remove a file.

Parameters:

name

The name of the file.

Return values:

0

If the file was removed.

Returns:: -1 If the file could not be removed or if it doesn't exist.

Definition at line 1076 of file cfs-coffee.c.

CCIF cfs_offset_t cfs_seek	(	int	fd,
		cfs_offset_t	offset,
		int	whence
	)

Seek to a specified position in an open file.

Parameters:

	fd	The file descriptor of the open file.
	offset	A position, either relative or absolute, in the file.
	whence	Determines how to interpret the offset parameter.

Returns:: The new position in the file, or (cfs_offset_t)-1 if the seek failed.

This function moves the file position to the specified position in the file. The next byte that is read from or written to the file will be at the position given determined by the combination of the offset parameter and the whence parameter.