File System APIs¶
File System Functions¶
-
int
fs_open
(fs_file_t *zfp, const char *file_name)¶ File open.
Opens an existing file or create a new one and associates a stream with it.
- Parameters
zfp
: Pointer to file objectfile_name
: The name of file to open
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_close
(fs_file_t *zfp)¶ File close.
Flushes the associated stream and closes the file.
- Parameters
zfp
: Pointer to the file object
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_unlink
(const char *path)¶ File unlink.
Deletes the specified file or directory
- Parameters
path
: Path to the file or directory to delete
- Return Value
0
: Success-ERRNO
: errno code if error
-
ssize_t
fs_read
(fs_file_t *zfp, void *ptr, size_t size)¶ File read.
Reads items of data of size bytes long.
- Return
- Number of bytes read. On success, it will be equal to number of items requested to be read. Returns less than number of bytes requested if there are not enough bytes available in file. Will return -ERRNO code on error.
- Parameters
zfp
: Pointer to the file objectptr
: Pointer to the data buffersize
: Number of bytes to be read
-
ssize_t
fs_write
(fs_file_t *zfp, const void *ptr, size_t size)¶ File write.
Writes items of data of size bytes long.
- Return
- Number of bytes written. On success, it will be equal to the number of bytes requested to be written. Any other value, indicates an error. Will return -ERRNO code on error. In the case where -ERRNO is returned, the file pointer will not be advanced because it couldn’t start the operation. In the case where it is able to write, but is not able to complete writing all of the requested number of bytes, then it is because the disk got full. In that case, it returns less number of bytes written than requested, but not a negative -ERRNO value as in regular error case.
- Parameters
zfp
: Pointer to the file objectptr
: Pointer to the data buffersize
: Number of bytes to be write
-
int
fs_seek
(fs_file_t *zfp, off_t offset, int whence)¶ File seek.
Moves the file position to a new location in the file. The offset is added to file position based on the ‘whence’ parameter.
- Parameters
zfp
: Pointer to the file objectoffset
: Relative location to move the file pointer towhence
: Relative location from where offset is to be calculated.- FS_SEEK_SET = from beginning of file
- FS_SEEK_CUR = from current position,
- FS_SEEK_END = from end of file.
- Return Value
0
: Success-ERRNO
: errno code if error.
-
off_t
fs_tell
(fs_file_t *zfp)¶ Get current file position.
Retrieves the current position in the file.
- Parameters
zfp
: Pointer to the file object
- Return Value
position
: Current position in file Current revision does not validate the file object.
-
int
fs_truncate
(fs_file_t *zfp, off_t length)¶ Change the size of an open file.
Truncates the file to the new length if it is shorter than the current size of the file. Expands the file if the new length is greater than the current size of the file. The expanded region would be filled with zeroes.
- Note
- In the case of expansion, if the volume got full during the expansion process, the function will expand to the maximum possible length and returns success. Caller should check if the expanded size matches the requested length.
- Parameters
zfp
: Pointer to the file objectlength
: New size of the file in bytes
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_sync
(fs_file_t *zfp)¶ Flushes any cached write of an open file.
This function can be used to flush the cache of an open file. This can be called to ensure data gets written to the storage media immediately. This may be done to avoid data loss if power is removed unexpectedly. Note that closing a file will cause caches to be flushed correctly so it need not be called if the file is being closed.
- Parameters
zfp
: Pointer to the file object
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_mkdir
(const char *path)¶ Directory create.
Creates a new directory using specified path.
- Parameters
path
: Path to the directory to create
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_opendir
(fs_dir_t *zdp, const char *path)¶ Directory open.
Opens an existing directory specified by the path.
- Parameters
zdp
: Pointer to the directory objectpath
: Path to the directory to open
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_readdir
(fs_dir_t *zdp, struct fs_dirent *entry)¶ Directory read entry.
Reads directory entries of a open directory
- Return
- In end-of-dir condition, this will return 0 and set entry->name[0] = 0
- Parameters
zdp
: Pointer to the directory objectentry
: Pointer to zfs_dirent structure to read the entry into
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_closedir
(fs_dir_t *zdp)¶ Directory close.
Closes an open directory.
- Parameters
zdp
: Pointer to the directory object
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_stat
(const char *path, struct fs_dirent *entry)¶ File or directory status.
Checks the status of a file or directory specified by the path
- Parameters
path
: Path to the file or directoryentry
: Pointer to zfs_dirent structure to fill if file or directory exists.
- Return Value
0
: Success-ERRNO
: errno code if error
-
int
fs_statvfs
(struct fs_statvfs *stat)¶ Retrieves statistics of the file system volume.
Returns the total and available space in the file system volume.
- Parameters
stat
: Pointer to zfs_statvfs structure to receive the fs statistics
- Return Value
0
: Success-ERRNO
: errno code if error
File System Data Structures¶
-
typedef
fs_file_t
¶ File object representing an open file.
-
typedef
fs_dir_t
¶ Directory object representing an open directory.
-
struct
fs_dirent
¶ - #include <fs.h>
Structure to receive file or directory information.
Used in functions that reads the directory entries to get file or directory information.
- Parameters
dir_entry_type
: Whether file or directory- FS_DIR_ENTRY_FILE
- FS_DIR_ENTRY_DIR
name
: Name of directory or filesize
: Size of file. 0 if directory
-
struct
fs_statvfs
¶ - #include <fs.h>
Structure to receive volume statistics.
Used to retrieve information about total and available space in the volume.
- Parameters
f_bsize
: Optimal transfer block sizef_frsize
: Allocation unit sizef_blocks
: Size of FS in f_frsize unitsf_bfree
: Number of free blocks