4.2. fs
— Debug file system¶
The debug file system is not really a file system, but rather a file system like tree of commands, counters, parameters, and “real” file systems.
- A command is a file path mapped to a function callback. The callback
is invoked when its path is passed to the
fs_call()
function. Commands are registered into the debug file system by a call tofs_command_register()
. - A counter is a file path mapped to a 64 bit value. The value can be
incremented and read by the application. Counters are registered
into the debug file system by a call to
fs_counter_register()
. - A parameter is file path mapped to a value stored in ram that can be
easily read and modified by the user from a shell. Parameters are
registered into the debug file system by a call to
fs_parameter_register()
. - A “real” file system is a file path, or mount point, mapped to a
file system instance. The debug file system has a file access
interface. The purpose of this interface is to have a common file
access interface, independent of the underlying file systems
interface. File systems are registered into the debug file system by
a call to
fs_filesystem_register()
.
4.2.1. Debug file system commands¶
The debug file system module itself registers seven commands, all
located in the directory filesystems/fs/
.
Command | Description |
---|---|
filesystems/list |
Print a list of all registered file systems. |
list [<folder>] |
Print a list of all files and folders in given folder. |
read <file> |
Read from given file. |
write <file> <data> |
Create and write to a file. Overwrites existing files. |
append <file> <data> |
Append data to an existing file. |
counters/list |
Print a list of all registered counters. |
counters/reset |
Rest all counters to zero. |
parameters/list |
Print a list of all registered parameters. |
Example output from the shell:
$ filesystems/fs/filesystems/list
MOUNT-POINT MEDIUM TYPE AVAILABLE SIZE USAGE
/tmp ram fat16 54K 64K 14%
/home/erik sd fat16 1.9G 2G 5%
/etc flash spiffs 124K 128K 3%
$ filesystems/fs/write tmp/foo.txt "Hello "
$ filesystems/fs/append tmp/foo.txt world!
$ filesystems/fs/read tmp/foo.txt
Hello world!
$ filesystems/fs/list tmp
xxxx-xx-xx xx-xx 12 foo.txt
$ filesystems/fs/counters/list
NAME VALUE
/your/counter 0000000000000034
/my/counter 0000000000000002
$ filesystems/fs/counters/reset
$ filesystems/fs/counters/list
NAME VALUE
/your/counter 0000000000000000
/my/counter 0000000000000000
$ filesystems/fs/parameters/list
NAME VALUE
/foo/bar -2
Source code: src/filesystems/fs.h, src/filesystems/fs.c
Test code: tst/filesystems/fs/main.c
Test coverage: src/filesystems/fs.c
Defines
-
FS_SEEK_SET
¶ The offset is relative to the start of the file.
-
FS_SEEK_CUR
¶ The offset is relative to the current position indicator.
-
FS_SEEK_END
¶ The offset is relative to the end of the file.
-
FS_READ
¶ Open for reading.
-
FS_WRITE
¶ Open for write.
-
FS_RDWR
¶ Open for reading and writing.
-
FS_APPEND
¶ The file position indicator shall be set to the end of the file prior to each write.
-
FS_SYNC
¶ Synchronous writes.
-
FS_CREAT
¶ Create the file if non-existent.
-
FS_EXCL
¶ If FS_CREAT and FS_EXCL are set, file open shall fail if the file exists.
-
FS_TRUNC
¶ Truncate the file to zero length.
-
FS_TYPE_FILE
¶
-
FS_TYPE_DIR
¶
-
FS_TYPE_HARD_LINK
¶
-
FS_TYPE_SOFT_LINK
¶
Typedefs
-
typedef
int(* fs_callback_t)(int argc, const char *argv[], chan_t *out_p, chan_t *in_p, void *arg_p, void *call_arg_p)
Command callback prototype.
- Return
- zero(0) or negative error code.
- Parameters
argc
-Number of arguements in argv.
argv
-An array of agruments.
out_p
-Output channel.
in_p
-Input channel.
arg_p
-Argument passed to the init function of given command.
call_arg_p
-Argument passed to the
fs_call
function.
-
typedef
int(* fs_parameter_set_callback_t)(void *value_p, const char *src_p)
Parameter setter callback prototype.
- Return
- zero(0) or negative error code.
- Parameters
value_p
-Buffer the new value should be written to.
src_p
-Value to set as a string.
-
typedef
int(* fs_parameter_print_callback_t)(chan_t *chout_p, void *value_p)
Parameter printer callback prototype.
- Return
- zero(0) or negative error code.
- Parameters
chout_p
-Channel to write the formatted value to.
value_p
-Value to format and print to the output channel.
Functions
-
int
fs_module_init
(void)¶ Initialize the file system module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
fs_call
(char *command_p, chan_t *chin_p, chan_t *chout_p, void *arg_p)¶ Call given file system command with given input and output channels. Quote an argument if it contains spaces, otherwise it is parsed as multiple arguments. Any quotation mark in an argument string must be escaped with a backslash (
\
), otherwise it is interpreted as a string quotation mask.- Return
- zero(0) or negative error code.
- Parameters
command_p
-Command string to call. The command string will be modified by this function, so don’t use it after this function returns.
chin_p
-Input channel.
chout_p
-Output channel.
arg_p
-User argument passed to the command callback function as
call_arg_p
.
-
int
fs_open
(struct fs_file_t *self_p, const char *path_p, int flags)¶ Open a file by file path and mode flags. File operations are permitted after the file has been opened.
The path can be either absolute or relative. It’s an absolute path if it starts with a forward slash
/
, and relative otherwise. Relative paths are are relative to the current working directory, given by the thread environment variableCWD
.- Return
- zero(0) or negative error code.
- Parameters
self_p
-File object to be initialized.
path_p
-Path of the file to open. The path can be absolute or relative.
flags
-Mode of file open. A combination of
FS_READ
,FS_RDONLY
,FS_WRITE
,FS_WRONLY
,FS_RDWR
,FS_APPEND
,FS_SYNC
,FS_CREAT
,FS_EXCL
andFS_TRUNC
.
-
int
fs_close
(struct fs_file_t *self_p)¶ Close given file. No file operations are permitted on a closed file.
- Return
- zero(0) or negative error code.
- Parameters
self_p
-Initialized file object.
-
ssize_t
fs_read
(struct fs_file_t *self_p, void *dst_p, size_t size)¶ Read from given file into given buffer.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
-Initialized file object.
dst_p
-Buffer to read data into.
size
-Number of bytes to read.
-
ssize_t
fs_read_line
(struct fs_file_t *self_p, void *dst_p, size_t size)¶ Read one line from given file into given buffer. The function reads one character at a time from given file until the destination buffer is full, a newline
\n
is found or end of file is reached.- Return
- If a line was found the number of bytes read not including the null-termination is returned. If the destination buffer becomes full before a newline character, the destination buffer size is returned. Otherwise a negative error code is returned.
- Parameters
self_p
-Initialized file object.
dst_p
-Buffer to read data into. Should fit the whole line and null-termination.
size
-Size of the destination buffer.
-
ssize_t
fs_write
(struct fs_file_t *self_p, const void *src_p, size_t size)¶ Write from given buffer into given file.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
-Initialized file object.
dst_p
-Buffer to write.
size
-Number of bytes to write.
-
int
fs_seek
(struct fs_file_t *self_p, int offset, int whence)¶ Sets the file’s read/write position relative to whence.
- Return
- zero(0) or negative error code.
- Parameters
self_p
-Initialized file object.
offset
-New position in bytes from given whence.
whence
-Absolute (
FS_SEEK_SET
), relative (FS_SEEK_CUR
) or from end (FS_SEEK_END
).
-
ssize_t
fs_tell
(struct fs_file_t *self_p)¶ Return current position in the file.
- Return
- Current position or negative error code.
- Parameters
self_p
-Initialized file object.
-
int
fs_dir_open
(struct fs_dir_t *dir_p, const char *path_p, int oflag)¶ Open a directory by directory path and mode flags.
- Return
- zero(0) or negative error code.
- Parameters
dir_p
-Directory object to be initialized.
path_p
-A valid path name for a directory path.
oflag
-mode of the directory to open (create, read, etc).
-
int
fs_dir_close
(struct fs_dir_t *dir_p)¶ Close given directory.
- Return
- zero(0) or negative error code.
- Parameters
dir_p
-Directory object.
-
int
fs_dir_read
(struct fs_dir_t *dir_p, struct fs_dir_entry_t *entry_p)¶ Read the next file or directory within the opened directory.
- Return
- true(1) if an entry was read or false(0) if no entry could be read, otherwise negative error code.
- Parameters
dir_p
-Directory object.
entry_p
-Read entry.
-
int
fs_stat
(const char *path_p, struct fs_stat_t *stat_p)¶ Gets file status by path.
- Return
- zero(0) or negative error code.
- Parameters
path_p
-The path of the file to stat.
stat_p
-The stat struct to populate.
-
int
fs_mkdir
(const char *path_p)¶ Craete a directory with given path.
- Return
- zero(0) or negative error code.
- Parameters
path_p
-The path of the directoy to create.
-
int
fs_ls
(const char *path_p, const char *filter_p, chan_t *chout_p)¶ List files and folders in given path. Optionally with given filter. The list is written to the output channel.
- Return
- zero(0) or negative error code.
- Parameters
path_p
-Directory to list.
filter_p
-Filter out files and folders.
chout_p
-Output chan.
-
int
fs_list
(const char *path_p, const char *filter_p, chan_t *chout_p)¶ List files (callbacks) and directories in given path. Optionally with given filter. The list is written to the output channel.
- Return
- zero(0) or negative error code.
- Parameters
path_p
-Directory to list.
filter_p
-Filter out files and folders.
chout_p
-Output chan.
-
int
fs_auto_complete
(char *path_p)¶ Auto-complete given path.
- Return
- >=1 if completion happened. Number of autocompleted characters added to the path. 0 if no completion happend, or negative error code.
- Parameters
path_p
-Absolute or relative path to auto-complete.
-
void
fs_split
(char *buf_p, char **path_pp, char **cmd_pp)¶ Split buffer into path and command inplace.
- Return
- zero(0) or negative error code.
- Parameters
buf_p
-Buffer to split.
path_pp
-Path or NULL if no path was found.
cmd_pp
-Command or empty string.
-
void
fs_merge
(char *path_p, char *cmd_p)¶ Merge path and command previously split using
fs_split()
.- Return
- zero(0) or negative error code.
- Parameters
path_p
-Path from spilt.
cmd_p
-Command from split.
-
int fs_filesystem_init(struct fs_filesystem_t * self_p, const char * name_p, enum fs_type_t type, void * fs_p)
Initialize given file system.
- Return
- zero(0) or negative error code.
- Parameters
self_p
-File system to initialize.
name_p
-Path to register.
type
-File system type.
fs_p
-File system pointer.
-
int
fs_filesystem_register
(struct fs_filesystem_t *self_p)¶ Register given file system. Use the functions
fs_open()
,fs_read()
,fs_write()
,fs_close()
,fs_seek()
, fs_tell() andfs_read_line()
to access files in a registerd file system.- Return
- zero(0) or negative error code.
- Parameters
self_p
-File system to register.
-
int
fs_filesystem_deregister
(struct fs_filesystem_t *self_p)¶ Deregister given file system.
- Return
- zero(0) or negative error code.
- Parameters
self_p
-File system to deregister.
-
int fs_command_init(struct fs_command_t * self_p, const FAR char * path_p, fs_callback_t callback, void * arg_p)
Initialize given command.
- Return
- zero(0) or negative error code.
- Parameters
self_p
-Command to initialize.
path_p
-Path to register.
callback
-Command callback function.
arg_p
-Callback argument.
-
int
fs_command_register
(struct fs_command_t *command_p)¶ Register given command. Registered commands are called by the function
fs_call()
.- Return
- zero(0) or negative error code.
- Parameters
command_p
-Command to register.
-
int
fs_command_deregister
(struct fs_command_t *command_p)¶ Deregister given command.
- Return
- zero(0) or negative error code.
- Parameters
command_p
-Command to deregister.
-
int fs_counter_init(struct fs_counter_t * self_p, const FAR char * path_p, uint64_t value)
Initialize given counter.
- Return
- zero(0) or negative error code.
- Parameters
self_p
-Counter to initialize.
path_p
-Path to register.
value
-Initial value of the counter.
-
int
fs_counter_increment
(struct fs_counter_t *self_p, uint64_t value)¶ Increment given counter.
- Return
- zero(0) or negative error code.
- Parameters
self_p
-Command to initialize.
value
-Increment value.
-
int
fs_counter_register
(struct fs_counter_t *counter_p)¶ Register given counter.
- Return
- zero(0) or negative error code.
- Parameters
counter_p
-Counter to register.
-
int
fs_counter_deregister
(struct fs_counter_t *counter_p)¶ Deregister given counter.
- Return
- zero(0) or negative error code.
- Parameters
counter_p
-Counter to deregister.
-
int fs_parameter_init(struct fs_parameter_t * self_p, const FAR char * path_p, fs_parameter_set_callback_t set_cb, fs_parameter_print_callback_t print_cb, void * value_p)
Initialize given parameter.
- Return
- zero(0) or negative error code.
- Parameters
self_p
-Parameter to initialize.
path_p
-Path to register.
set_cb
-Callback function set set the parameter value.
print_cb
-Callback function set print the parameter value.
value_p
-Value storage area.
-
int
fs_parameter_register
(struct fs_parameter_t *parameter_p)¶ Register given parameter.
- Return
- zero(0) or negative error code.
- Parameters
parameter_p
-Parameter to register.
-
int
fs_parameter_deregister
(struct fs_parameter_t *parameter_p)¶ Deregister given parameter.
- Return
- zero(0) or negative error code.
- Parameters
parameter_p
-Parameter to deregister.
-
int
fs_parameter_int_set
(void *value_p, const char *src_p)¶ Integer parameter setter function callback
- Return
- zero(0) or negative error code.
- Parameters
value_p
-Buffer the new value should be written to.
src_p
-Value to set as a string.
-
struct
fs_filesystem_t
¶
-
struct
fs_file_t
¶ Public Members
-
struct fs_filesystem_t *
filesystem_p
¶
-
struct fat16_file_t
fat16
¶
-
spiffs_file_t
spiffs
¶
-
union fs_file_t::@26 fs_file_t::u
-
struct fs_filesystem_t *
-
struct
fs_stat_t
¶ - #include <fs.h>
Path stats.
-
struct
fs_command_t
¶ Public Members
-
const FAR char* fs_command_t::path_p
-
fs_callback_t
callback
¶
-
void *
arg_p
¶
-
struct fs_command_t *
next_p
¶
-
-
struct
fs_counter_t
¶ Public Members
-
struct fs_command_t
command
¶
-
long long unsigned int fs_counter_t::value
-
struct fs_counter_t *
next_p
¶
-
struct fs_command_t
-
struct
fs_parameter_t
¶ Public Members
-
struct fs_command_t
command
¶
-
fs_parameter_set_callback_t
set_cb
¶
-
fs_parameter_print_callback_t
print_cb
¶
-
void *
value_p
¶
-
struct fs_parameter_t *
next_p
¶
-
struct fs_command_t
-
struct
fs_dir_t
¶ Public Members
-
struct fs_filesystem_t *
filesystem_p
¶
-
struct fat16_dir_t
fat16
¶
-
struct spiffs_dir_t
spiffs
¶
-
union fs_dir_t::@27 fs_dir_t::u
-
struct fs_filesystem_t *
-
struct
fs_dir_entry_t
¶