diff --git a/include/fs/fs.h b/include/fs/fs.h index 0ed06922a1b..6a24739d659 100644 --- a/include/fs/fs.h +++ b/include/fs/fs.h @@ -253,11 +253,13 @@ static inline void fs_dir_t_init(struct fs_dir_t *zdp) * @param flags The mode flags * * @retval 0 on success; + * @retval -EBUSY when zfp is already used; * @retval -EINVAL when a bad file name is given; * @retval -EROFS when opening read-only file for write, or attempting to * create a file on a system that has been mounted with the * FS_MOUNT_FLAG_READ_ONLY flag; * @retval -ENOENT when the file path is not possible (bad mount point); + * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 an other negative errno code, depending on a file system back-end. */ int fs_open(struct fs_file_t *zfp, const char *file_name, fs_mode_t flags); @@ -270,6 +272,7 @@ int fs_open(struct fs_file_t *zfp, const char *file_name, fs_mode_t flags); * @param zfp Pointer to the file object * * @retval 0 on success; + * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 a negative errno code on error. */ int fs_close(struct fs_file_t *zfp); @@ -282,6 +285,7 @@ int fs_close(struct fs_file_t *zfp); * @param path Path to the file or directory to delete * * @retval 0 on success; + * @retval -EINVAL when a bad file name is given; * @retval -EROFS if file is read-only, or when file system has been mounted * with the FS_MOUNT_FLAG_READ_ONLY flag; * @retval -ENOTSUP when not implemented by underlying file system driver; @@ -307,6 +311,10 @@ int fs_unlink(const char *path); * @param to The destination path * * @retval 0 on success; + * @retval -EINVAL when a bad file name is given, or when rename would cause move + * between mount points; + * @retval -EROFS if file is read-only, or when file system has been mounted + * with the FS_MOUNT_FLAG_READ_ONLY flag; * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 an other negative errno code on error. */ @@ -324,6 +332,8 @@ int fs_rename(const char *from, const char *to); * @param size Number of bytes to be read * * @retval >=0 a number of bytes read, on success; + * @retval -EBADF when invoked on zfp that represents unopened/closed file; + * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 a negative errno code on error. */ ssize_t fs_read(struct fs_file_t *zfp, void *ptr, size_t size); @@ -343,6 +353,7 @@ ssize_t fs_read(struct fs_file_t *zfp, void *ptr, size_t size); * @param size Number of bytes to be written * * @retval >=0 a number of bytes written, on success; + * @retval -EBADF when invoked on zfp that represents unopened/closed file; * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 an other negative errno code on error. */ @@ -362,6 +373,7 @@ ssize_t fs_write(struct fs_file_t *zfp, const void *ptr, size_t size); * - @c FS_SEEK_END for the end of the file. * * @retval 0 on success; + * @retval -EBADF when invoked on zfp that represents unopened/closed file; * @retval -ENOTSUP if not supported by underlying file system driver; * @retval <0 an other negative errno code on error. */ @@ -375,6 +387,7 @@ int fs_seek(struct fs_file_t *zfp, off_t offset, int whence); * @param zfp Pointer to the file object * * @retval >= 0 a current position in file; + * @retval -EBADF when invoked on zfp that represents unopened/closed file; * @retval -ENOTSUP if not supported by underlying file system driver; * @retval <0 an other negative errno code on error. * @@ -398,6 +411,7 @@ off_t fs_tell(struct fs_file_t *zfp); * @param length New size of the file in bytes * * @retval 0 on success; + * @retval -EBADF when invoked on zfp that represents unopened/closed file; * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 an other negative errno code on error. */ @@ -415,6 +429,8 @@ int fs_truncate(struct fs_file_t *zfp, off_t length); * @param zfp Pointer to the file object * * @retval 0 on success; + * @retval -EBADF when invoked on zfp that represents unopened/closed file; + * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 a negative errno code on error. */ int fs_sync(struct fs_file_t *zfp); @@ -427,6 +443,8 @@ int fs_sync(struct fs_file_t *zfp); * @param path Path to the directory to create * * @retval 0 on success; + * @retval -EROFS if file is read-only, or when file system has been mounted + * with the FS_MOUNT_FLAG_READ_ONLY flag; * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 an other negative errno code on error */ @@ -441,6 +459,9 @@ int fs_mkdir(const char *path); * @param path Path to the directory to open * * @retval 0 on success; + * @retval -EINVAL when a bad directory path is given; + * @retval -EBUSY when zdp is already used; + * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 a negative errno code on error. */ int fs_opendir(struct fs_dir_t *zdp, const char *path); @@ -459,7 +480,9 @@ int fs_opendir(struct fs_dir_t *zdp, const char *path); * @param zdp Pointer to the directory object * @param entry Pointer to zfs_dirent structure to read the entry into * - * @retval 0 on success or end-of-dir;; + * @retval 0 on success or end-of-dir; + * @retval -ENOENT when no such directory found; + * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 a negative errno code on error. */ int fs_readdir(struct fs_dir_t *zdp, struct fs_dirent *entry); @@ -472,6 +495,7 @@ int fs_readdir(struct fs_dir_t *zdp, struct fs_dirent *entry); * @param zdp Pointer to the directory object * * @retval 0 on success; + * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 a negative errno code on error. */ int fs_closedir(struct fs_dir_t *zdp); @@ -547,6 +571,9 @@ int fs_readmount(int *index, const char **name); * directory exists. * * @retval 0 on success; + * @retval -EINVAL when a bad directory or file name is given; + * @retval -ENOENT when no such directory or file is found; + * @retval -ENOTSUP when not supported by underlying file system driver; * @retval <0 negative errno code on error. */ int fs_stat(const char *path, struct fs_dirent *entry); @@ -558,9 +585,10 @@ int fs_stat(const char *path, struct fs_dirent *entry); * * @param path Path to the mounted directory * @param stat Pointer to the zfs_statvfs structure to receive the fs - * statistics + * statistics. * * @retval 0 on success; + * @retval -EINVAL when a bad path to a directory, or a file, is given; * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 an other negative errno code on error. */ @@ -570,12 +598,16 @@ int fs_statvfs(const char *path, struct fs_statvfs *stat); * @brief Register a file system * * Register file system with virtual file system. + * Number of allowed file system types to be registered is controlled with the + * CONFIG_FILE_SYSTEM_MAX_TYPES Kconfig option. * * @param type Type of file system (ex: @c FS_FATFS) * @param fs Pointer to File system * * @retval 0 on success; - * @retval <0 negative errno code on error. + * @retval -EALREADY when a file system of a given type has already been registered; + * @retval -ENOSCP when there is no space left, in file system registry, to add + * this file system type. */ int fs_register(int type, const struct fs_file_system_t *fs); @@ -588,7 +620,7 @@ int fs_register(int type, const struct fs_file_system_t *fs); * @param fs Pointer to File system * * @retval 0 on success; - * @retval <0 negative errno code on error. + * @retval -EINVAL when file system of a given type has not been registered. */ int fs_unregister(int type, const struct fs_file_system_t *fs);