#include "spiffs_config.h"
Go to the source code of this file.
Classes | |
struct | spiffs_config |
struct | spiffs_t |
struct | spiffs_stat |
struct | spiffs_dirent |
struct | spiffs_DIR |
Typedefs | |
typedef s16_t | spiffs_file |
typedef u16_t | spiffs_flags |
typedef u16_t | spiffs_mode |
typedef u8_t | spiffs_obj_type |
typedef s32_t(* | spiffs_read) (u32_t addr, u32_t size, u8_t *dst) |
typedef s32_t(* | spiffs_write) (u32_t addr, u32_t size, u8_t *src) |
typedef s32_t(* | spiffs_erase) (u32_t addr, u32_t size) |
typedef void(* | spiffs_check_callback) (spiffs_check_type type, spiffs_check_report report, u32_t arg1, u32_t arg2) |
typedef void(* | spiffs_file_callback) (struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix) |
typedef struct spiffs_t | spiffs |
Enumerations | |
enum | spiffs_check_type { SPIFFS_CHECK_LOOKUP = 0 , SPIFFS_CHECK_INDEX , SPIFFS_CHECK_PAGE } |
enum | spiffs_check_report { SPIFFS_CHECK_PROGRESS = 0 , SPIFFS_CHECK_ERROR , SPIFFS_CHECK_FIX_INDEX , SPIFFS_CHECK_FIX_LOOKUP , SPIFFS_CHECK_DELETE_ORPHANED_INDEX , SPIFFS_CHECK_DELETE_PAGE , SPIFFS_CHECK_DELETE_BAD_FILE } |
enum | spiffs_fileop_type { SPIFFS_CB_CREATED = 0 , SPIFFS_CB_UPDATED , SPIFFS_CB_DELETED } |
Macro Definition Documentation
◆ SPIFFS_APPEND
#define SPIFFS_APPEND (1<<0) |
◆ SPIFFS_CACHE_DBG
#define SPIFFS_CACHE_DBG | ( | ... | ) | printf(__VA_ARGS__) |
◆ SPIFFS_CHECK_DBG
#define SPIFFS_CHECK_DBG | ( | ... | ) | printf(__VA_ARGS__) |
◆ SPIFFS_CREAT
#define SPIFFS_CREAT (1<<2) |
◆ SPIFFS_DBG
#define SPIFFS_DBG | ( | ... | ) | printf(__VA_ARGS__) |
◆ SPIFFS_DIRECT
#define SPIFFS_DIRECT (1<<5) |
◆ SPIFFS_ERR_BAD_DESCRIPTOR
#define SPIFFS_ERR_BAD_DESCRIPTOR -10010 |
◆ SPIFFS_ERR_CONFLICTING_NAME
#define SPIFFS_ERR_CONFLICTING_NAME -10023 |
◆ SPIFFS_ERR_DATA_SPAN_MISMATCH
#define SPIFFS_ERR_DATA_SPAN_MISMATCH -10014 |
◆ SPIFFS_ERR_DELETED
#define SPIFFS_ERR_DELETED -10004 |
◆ SPIFFS_ERR_END_OF_OBJECT
#define SPIFFS_ERR_END_OF_OBJECT -10003 |
◆ SPIFFS_ERR_ERASE_FAIL
#define SPIFFS_ERR_ERASE_FAIL -10027 |
◆ SPIFFS_ERR_FILE_CLOSED
#define SPIFFS_ERR_FILE_CLOSED -10008 |
◆ SPIFFS_ERR_FILE_DELETED
#define SPIFFS_ERR_FILE_DELETED -10009 |
◆ SPIFFS_ERR_FILE_EXISTS
#define SPIFFS_ERR_FILE_EXISTS -10030 |
◆ SPIFFS_ERR_FULL
#define SPIFFS_ERR_FULL -10001 |
◆ SPIFFS_ERR_INDEX_FREE
#define SPIFFS_ERR_INDEX_FREE -10018 |
◆ SPIFFS_ERR_INDEX_INVALID
#define SPIFFS_ERR_INDEX_INVALID -10020 |
◆ SPIFFS_ERR_INDEX_LU
#define SPIFFS_ERR_INDEX_LU -10019 |
◆ SPIFFS_ERR_INDEX_REF_FREE
#define SPIFFS_ERR_INDEX_REF_FREE -10015 |
◆ SPIFFS_ERR_INDEX_REF_INVALID
#define SPIFFS_ERR_INDEX_REF_INVALID -10017 |
◆ SPIFFS_ERR_INDEX_REF_LU
#define SPIFFS_ERR_INDEX_REF_LU -10016 |
◆ SPIFFS_ERR_INDEX_SPAN_MISMATCH
#define SPIFFS_ERR_INDEX_SPAN_MISMATCH -10013 |
◆ SPIFFS_ERR_INTERNAL
#define SPIFFS_ERR_INTERNAL -10050 |
◆ SPIFFS_ERR_IS_FREE
#define SPIFFS_ERR_IS_FREE -10012 |
◆ SPIFFS_ERR_IS_INDEX
#define SPIFFS_ERR_IS_INDEX -10011 |
◆ SPIFFS_ERR_IX_MAP_BAD_RANGE
#define SPIFFS_ERR_IX_MAP_BAD_RANGE -10039 |
◆ SPIFFS_ERR_IX_MAP_MAPPED
#define SPIFFS_ERR_IX_MAP_MAPPED -10038 |
◆ SPIFFS_ERR_IX_MAP_UNMAPPED
#define SPIFFS_ERR_IX_MAP_UNMAPPED -10037 |
◆ SPIFFS_ERR_MAGIC_NOT_POSSIBLE
#define SPIFFS_ERR_MAGIC_NOT_POSSIBLE -10028 |
◆ SPIFFS_ERR_MOUNTED
#define SPIFFS_ERR_MOUNTED -10026 |
◆ SPIFFS_ERR_NAME_TOO_LONG
#define SPIFFS_ERR_NAME_TOO_LONG -10036 |
◆ SPIFFS_ERR_NO_DELETED_BLOCKS
#define SPIFFS_ERR_NO_DELETED_BLOCKS -10029 |
◆ SPIFFS_ERR_NOT_A_FILE
#define SPIFFS_ERR_NOT_A_FILE -10031 |
◆ SPIFFS_ERR_NOT_A_FS
#define SPIFFS_ERR_NOT_A_FS -10025 |
◆ SPIFFS_ERR_NOT_CONFIGURED
#define SPIFFS_ERR_NOT_CONFIGURED -10024 |
◆ SPIFFS_ERR_NOT_FINALIZED
#define SPIFFS_ERR_NOT_FINALIZED -10005 |
◆ SPIFFS_ERR_NOT_FOUND
#define SPIFFS_ERR_NOT_FOUND -10002 |
◆ SPIFFS_ERR_NOT_INDEX
#define SPIFFS_ERR_NOT_INDEX -10006 |
◆ SPIFFS_ERR_NOT_MOUNTED
#define SPIFFS_ERR_NOT_MOUNTED -10000 |
◆ SPIFFS_ERR_NOT_READABLE
#define SPIFFS_ERR_NOT_READABLE -10022 |
◆ SPIFFS_ERR_NOT_WRITABLE
#define SPIFFS_ERR_NOT_WRITABLE -10021 |
◆ SPIFFS_ERR_OUT_OF_FILE_DESCS
#define SPIFFS_ERR_OUT_OF_FILE_DESCS -10007 |
◆ SPIFFS_ERR_PROBE_NOT_A_FS
#define SPIFFS_ERR_PROBE_NOT_A_FS -10035 |
◆ SPIFFS_ERR_PROBE_TOO_FEW_BLOCKS
#define SPIFFS_ERR_PROBE_TOO_FEW_BLOCKS -10034 |
◆ SPIFFS_ERR_RO_ABORTED_OPERATION
#define SPIFFS_ERR_RO_ABORTED_OPERATION -10033 |
◆ SPIFFS_ERR_RO_NOT_IMPL
#define SPIFFS_ERR_RO_NOT_IMPL -10032 |
◆ SPIFFS_ERR_SEEK_BOUNDS
#define SPIFFS_ERR_SEEK_BOUNDS -10040 |
◆ SPIFFS_ERR_TEST
#define SPIFFS_ERR_TEST -10100 |
◆ SPIFFS_EXCL
#define SPIFFS_EXCL (1<<6) |
◆ SPIFFS_GC_DBG
#define SPIFFS_GC_DBG | ( | ... | ) | printf(__VA_ARGS__) |
◆ SPIFFS_LOCK
#define SPIFFS_LOCK | ( | fs | ) |
◆ SPIFFS_O_APPEND
#define SPIFFS_O_APPEND SPIFFS_APPEND |
◆ SPIFFS_O_CREAT
#define SPIFFS_O_CREAT SPIFFS_CREAT |
◆ SPIFFS_O_DIRECT
#define SPIFFS_O_DIRECT SPIFFS_DIRECT |
◆ SPIFFS_O_EXCL
#define SPIFFS_O_EXCL SPIFFS_EXCL |
◆ SPIFFS_O_RDONLY
#define SPIFFS_O_RDONLY SPIFFS_RDONLY |
◆ SPIFFS_O_RDWR
#define SPIFFS_O_RDWR SPIFFS_RDWR |
◆ SPIFFS_O_TRUNC
#define SPIFFS_O_TRUNC SPIFFS_TRUNC |
◆ SPIFFS_O_WRONLY
#define SPIFFS_O_WRONLY SPIFFS_WRONLY |
◆ SPIFFS_OK
#define SPIFFS_OK 0 |
◆ SPIFFS_RDONLY
#define SPIFFS_RDONLY (1<<3) |
◆ SPIFFS_RDWR
#define SPIFFS_RDWR (SPIFFS_RDONLY | SPIFFS_WRONLY) |
◆ SPIFFS_SEEK_CUR
#define SPIFFS_SEEK_CUR (1) |
◆ SPIFFS_SEEK_END
#define SPIFFS_SEEK_END (2) |
◆ SPIFFS_SEEK_SET
#define SPIFFS_SEEK_SET (0) |
◆ SPIFFS_TRUNC
#define SPIFFS_TRUNC (1<<1) |
◆ SPIFFS_TYPE_DIR
#define SPIFFS_TYPE_DIR (2) |
◆ SPIFFS_TYPE_FILE
#define SPIFFS_TYPE_FILE (1) |
◆ SPIFFS_TYPE_HARD_LINK
#define SPIFFS_TYPE_HARD_LINK (3) |
◆ SPIFFS_TYPE_SOFT_LINK
#define SPIFFS_TYPE_SOFT_LINK (4) |
◆ SPIFFS_UNLOCK
#define SPIFFS_UNLOCK | ( | fs | ) |
◆ SPIFFS_WRONLY
#define SPIFFS_WRONLY (1<<4) |
Typedef Documentation
◆ spiffs
◆ spiffs_check_callback
typedef void(* spiffs_check_callback) (spiffs_check_type type, spiffs_check_report report, u32_t arg1, u32_t arg2) |
◆ spiffs_erase
◆ spiffs_file
typedef s16_t spiffs_file |
◆ spiffs_file_callback
typedef void(* spiffs_file_callback) (struct spiffs_t *fs, spiffs_fileop_type op, spiffs_obj_id obj_id, spiffs_page_ix pix) |
◆ spiffs_flags
typedef u16_t spiffs_flags |
◆ spiffs_mode
typedef u16_t spiffs_mode |
◆ spiffs_obj_type
typedef u8_t spiffs_obj_type |
◆ spiffs_read
◆ spiffs_write
Enumeration Type Documentation
◆ spiffs_check_report
enum spiffs_check_report |
◆ spiffs_check_type
enum spiffs_check_type |
◆ spiffs_fileop_type
enum spiffs_fileop_type |
Function Documentation
◆ SPIFFS_check()
Runs a consistency check on given filesystem.
- Parameters
-
fs the file system struct
◆ SPIFFS_clearerr()
void SPIFFS_clearerr | ( | spiffs * | fs | ) |
Clears last error.
- Parameters
-
fs the file system struct
◆ SPIFFS_close()
s32_t SPIFFS_close | ( | spiffs * | fs, |
spiffs_file | fh | ||
) |
Closes a filehandle. If there are pending write operations, these are finalized before closing.
- Parameters
-
fs the file system struct fh the filehandle of the file to close
◆ SPIFFS_closedir()
s32_t SPIFFS_closedir | ( | spiffs_DIR * | d | ) |
Closes a directory stream
- Parameters
-
d the directory stream to close
◆ SPIFFS_creat()
s32_t SPIFFS_creat | ( | spiffs * | fs, |
const char * | path, | ||
spiffs_mode | mode | ||
) |
Creates a new file.
- Parameters
-
fs the file system struct path the path of the new file mode ignored, for posix compliance
◆ SPIFFS_eof()
s32_t SPIFFS_eof | ( | spiffs * | fs, |
spiffs_file | fh | ||
) |
Check if EOF reached.
- Parameters
-
fs the file system struct fh the filehandle of the file to check
◆ SPIFFS_errno()
Returns last error of last file operation.
- Parameters
-
fs the file system struct
◆ SPIFFS_fflush()
s32_t SPIFFS_fflush | ( | spiffs * | fs, |
spiffs_file | fh | ||
) |
Flushes all pending write operations from cache for given file
- Parameters
-
fs the file system struct fh the filehandle of the file to flush
◆ SPIFFS_format()
Formats the entire file system. All data will be lost. The filesystem must not be mounted when calling this.
NB: formatting is awkward. Due to backwards compatibility, SPIFFS_mount MUST be called prior to formatting in order to configure the filesystem. If SPIFFS_mount succeeds, SPIFFS_unmount must be called before calling SPIFFS_format. If SPIFFS_mount fails, SPIFFS_format can be called directly without calling SPIFFS_unmount first.
- Parameters
-
fs the file system struct
◆ SPIFFS_fremove()
s32_t SPIFFS_fremove | ( | spiffs * | fs, |
spiffs_file | fh | ||
) |
Removes a file by filehandle
- Parameters
-
fs the file system struct fh the filehandle of the file to remove
◆ SPIFFS_fstat()
s32_t SPIFFS_fstat | ( | spiffs * | fs, |
spiffs_file | fh, | ||
spiffs_stat * | s | ||
) |
Gets file status by filehandle
- Parameters
-
fs the file system struct fh the filehandle of the file to stat s the stat struct to populate
◆ SPIFFS_ftruncate()
s32_t SPIFFS_ftruncate | ( | spiffs * | fs, |
spiffs_file | fh, | ||
u32_t | new_size | ||
) |
Truncates a file at given size
- Parameters
-
fs the file system struct fh the filehandle of the file to truncate new_size the new size, must be less than existing file size
- Returns
- 0 on success, error code otherwise
◆ SPIFFS_gc()
Will try to make room for given amount of bytes in the filesystem by moving pages and erasing blocks. If it is physically impossible, err_no will be set to SPIFFS_ERR_FULL. If there already is this amount (or more) of free space, SPIFFS_gc will silently return. It is recommended to call SPIFFS_info before invoking this method in order to determine what amount of bytes to give.
NB: the garbage collector is automatically called when spiffs needs free pages. The reason for this function is to give possibility to do background tidying when user knows the system is idle.
Use with care.
- Parameters
-
fs the file system struct size amount of bytes that should be freed
◆ SPIFFS_gc_quick()
Tries to find a block where most or all pages are deleted, and erase that block if found. Does not care for wear levelling. Will not move pages around. If parameter max_free_pages are set to 0, only blocks with only deleted pages will be selected.
NB: the garbage collector is automatically called when spiffs needs free pages. The reason for this function is to give possibility to do background tidying when user knows the system is idle.
Use with care.
Setting max_free_pages to anything larger than zero will eventually wear flash more as a block containing free pages can be erased.
Will set err_no to SPIFFS_OK if a block was found and erased, SPIFFS_ERR_NO_DELETED_BLOCK if no matching block was found, or other error.
- Parameters
-
fs the file system struct max_free_pages maximum number allowed free pages in block
◆ SPIFFS_info()
Returns number of total bytes available and number of used bytes. This is an estimation, and depends on if there a many files with little data or few files with much data. NB: If used number of bytes exceeds total bytes, a SPIFFS_check should run. This indicates a power loss in midst of things. In worst case (repeated powerlosses in mending or gc) you might have to delete some files.
- Parameters
-
fs the file system struct total total number of bytes in filesystem used used number of bytes in filesystem
◆ SPIFFS_lseek()
s32_t SPIFFS_lseek | ( | spiffs * | fs, |
spiffs_file | fh, | ||
s32_t | offs, | ||
int | whence | ||
) |
Moves the read/write file offset. Resulting offset is returned or negative if error. lseek(fs, fd, 0, SPIFFS_SEEK_CUR) will thus return current offset.
- Parameters
-
fs the file system struct fh the filehandle offs how much/where to move the offset whence if SPIFFS_SEEK_SET, the file offset shall be set to offset bytes if SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset if SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offse, which should be negative
◆ SPIFFS_mount()
s32_t SPIFFS_mount | ( | spiffs * | fs, |
spiffs_config * | config, | ||
u8_t * | work, | ||
u8_t * | fd_space, | ||
u32_t | fd_space_size, | ||
void * | cache, | ||
u32_t | cache_size, | ||
spiffs_check_callback | check_cb_f | ||
) |
Initializes the file system dynamic parameters and mounts the filesystem. If SPIFFS_USE_MAGIC is enabled the mounting may fail with SPIFFS_ERR_NOT_A_FS if the flash does not contain a recognizable file system. In this case, SPIFFS_format must be called prior to remounting.
- Parameters
-
fs the file system struct config the physical and logical configuration of the file system work a memory work buffer comprising 2*config->log_page_size bytes used throughout all file system operations fd_space memory for file descriptors fd_space_size memory size of file descriptors cache memory for cache, may be null cache_size memory size of cache check_cb_f callback function for reporting during consistency checks
◆ SPIFFS_mounted()
Returns nonzero if spiffs is mounted, or zero if unmounted.
- Parameters
-
fs the file system struct
◆ SPIFFS_open()
spiffs_file SPIFFS_open | ( | spiffs * | fs, |
const char * | path, | ||
spiffs_flags | flags, | ||
spiffs_mode | mode | ||
) |
Opens/creates a file.
- Parameters
-
fs the file system struct path the path of the new file flags the flags for the open command, can be combinations of SPIFFS_O_APPEND, SPIFFS_O_TRUNC, SPIFFS_O_CREAT, SPIFFS_O_RDONLY, SPIFFS_O_WRONLY, SPIFFS_O_RDWR, SPIFFS_O_DIRECT, SPIFFS_O_EXCL mode ignored, for posix compliance
◆ SPIFFS_open_by_dirent()
spiffs_file SPIFFS_open_by_dirent | ( | spiffs * | fs, |
struct spiffs_dirent * | e, | ||
spiffs_flags | flags, | ||
spiffs_mode | mode | ||
) |
Opens a file by given dir entry. Optimization purposes, when traversing a file system with SPIFFS_readdir a normal SPIFFS_open would need to traverse the filesystem again to find the file, whilst SPIFFS_open_by_dirent already knows where the file resides.
- Parameters
-
fs the file system struct e the dir entry to the file flags the flags for the open command, can be combinations of SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY, SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT. SPIFFS_CREAT will have no effect in this case. mode ignored, for posix compliance
◆ SPIFFS_open_by_page()
spiffs_file SPIFFS_open_by_page | ( | spiffs * | fs, |
spiffs_page_ix | page_ix, | ||
spiffs_flags | flags, | ||
spiffs_mode | mode | ||
) |
Opens a file by given page index. Optimization purposes, opens a file by directly pointing to the page index in the spi flash. If the page index does not point to a file header SPIFFS_ERR_NOT_A_FILE is returned.
- Parameters
-
fs the file system struct page_ix the page index flags the flags for the open command, can be combinations of SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY, SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT. SPIFFS_CREAT will have no effect in this case. mode ignored, for posix compliance
◆ SPIFFS_opendir()
spiffs_DIR* SPIFFS_opendir | ( | spiffs * | fs, |
const char * | name, | ||
spiffs_DIR * | d | ||
) |
Opens a directory stream corresponding to the given name. The stream is positioned at the first entry in the directory. On hydrogen builds the name argument is ignored as hydrogen builds always correspond to a flat file structure - no directories.
- Parameters
-
fs the file system struct name the name of the directory d pointer the directory stream to be populated
◆ SPIFFS_read()
s32_t SPIFFS_read | ( | spiffs * | fs, |
spiffs_file | fh, | ||
void * | buf, | ||
s32_t | len | ||
) |
Reads from given filehandle.
- Parameters
-
fs the file system struct fh the filehandle buf where to put read data len how much to read
- Returns
- number of bytes read, or -1 if error
◆ SPIFFS_readdir()
struct spiffs_dirent* SPIFFS_readdir | ( | spiffs_DIR * | d, |
struct spiffs_dirent * | e | ||
) |
Reads a directory into given spifs_dirent struct.
- Parameters
-
d pointer to the directory stream e the dirent struct to be populated
- Returns
- null if error or end of stream, else given dirent is returned
◆ SPIFFS_remove()
Removes a file by path
- Parameters
-
fs the file system struct path the path of the file to remove
◆ SPIFFS_rename()
Renames a file
- Parameters
-
fs the file system struct old path of file to rename newPath new path of file
◆ SPIFFS_set_file_callback_func()
s32_t SPIFFS_set_file_callback_func | ( | spiffs * | fs, |
spiffs_file_callback | cb_func | ||
) |
Registers a callback function that keeps track on operations on file headers. Do note, that this callback is called from within internal spiffs mechanisms. Any operations on the actual file system being callbacked from in this callback will mess things up for sure - do not do this. This can be used to track where files are and move around during garbage collection, which in turn can be used to build location tables in ram. Used in conjuction with SPIFFS_open_by_page this may improve performance when opening a lot of files. Must be invoked after mount.
- Parameters
-
fs the file system struct cb_func the callback on file operations
◆ SPIFFS_stat()
s32_t SPIFFS_stat | ( | spiffs * | fs, |
const char * | path, | ||
spiffs_stat * | s | ||
) |
Gets file status by path
- Parameters
-
fs the file system struct path the path of the file to stat s the stat struct to populate
◆ SPIFFS_tell()
s32_t SPIFFS_tell | ( | spiffs * | fs, |
spiffs_file | fh | ||
) |
Get position in file.
- Parameters
-
fs the file system struct fh the filehandle of the file to check
◆ SPIFFS_unmount()
void SPIFFS_unmount | ( | spiffs * | fs | ) |
Unmounts the file system. All file handles will be flushed of any cached writes and closed.
- Parameters
-
fs the file system struct
◆ SPIFFS_write()
s32_t SPIFFS_write | ( | spiffs * | fs, |
spiffs_file | fh, | ||
void * | buf, | ||
s32_t | len | ||
) |
Writes to given filehandle.
- Parameters
-
fs the file system struct fh the filehandle buf the data to write len how much to write
- Returns
- number of bytes written, or -1 if error