Loading...
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 | /*
* Copyright (c) 2016 Intel Corporation.
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef _FS_H_
#define _FS_H_
#include <sys/types.h>
#include <fs/fs_interface.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Create a fs_file_t type similar to FILE for familiarity */
typedef struct _fs_file_object fs_file_t;
/* Create a fs_dir_t type similar to DIR for familiarity */
typedef struct _fs_dir_object fs_dir_t;
enum fs_dir_entry_type {
FS_DIR_ENTRY_FILE,
FS_DIR_ENTRY_DIR
};
/**
* @brief File System
* @defgroup file_system File System
* @{
* @}
*/
/**
* @brief File System Data Structures
* @defgroup data_structures File System Data Structures
* @ingroup file_system
* @{
*/
/** @var fs_file_t
* @brief File object representing an open file
*/
/** @var fs_dir_t
* @brief Directory object representing an open directory
*/
/**
* @brief Structure to receive file or directory information
*
* Used in functions that reads the directory entries to get
* file or directory information.
*
* @param dir_entry_type Whether file or directory
* - FS_DIR_ENTRY_FILE
* - FS_DIR_ENTRY_DIR
* @param name Name of directory or file
* @param size Size of file. 0 if directory
*/
struct fs_dirent {
enum fs_dir_entry_type type;
char name[MAX_FILE_NAME + 1];
size_t size;
};
/**
* @brief Structure to receive volume statistics
*
* Used to retrieve information about total and available space
* in the volume.
*
* @param f_bsize Optimal transfer block size
* @param f_frsize Allocation unit size
* @param f_blocks Size of FS in f_frsize units
* @param f_bfree Number of free blocks
*/
struct fs_statvfs {
unsigned long f_bsize;
unsigned long f_frsize;
unsigned long f_blocks;
unsigned long f_bfree;
};
/**
* @}
*/
#ifndef FS_SEEK_SET
#define FS_SEEK_SET 0 /* Seek from beginning of file. */
#endif
#ifndef FS_SEEK_CUR
#define FS_SEEK_CUR 1 /* Seek from current position. */
#endif
#ifndef FS_SEEK_END
#define FS_SEEK_END 2 /* Seek from end of file. */
#endif
/**
* @brief File System APIs
* @defgroup file_system_api File System APIs
* @ingroup file_system
* @{
*/
/**
* @brief File open
*
* Opens an existing file or create a new one and associates
* a stream with it.
*
* @param zfp Pointer to file object
* @param file_name The name of file to open
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_open(fs_file_t *zfp, const char *file_name);
/**
* @brief File close
*
* Flushes the associated stream and closes
* the file.
*
* @param zfp Pointer to the file object
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_close(fs_file_t *zfp);
/**
* @brief File unlink
*
* Deletes the specified file or directory
*
* @param path Path to the file or directory to delete
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_unlink(const char *path);
/**
* @brief File read
*
* Reads items of data of size bytes long.
*
* @param zfp Pointer to the file object
* @param ptr Pointer to the data buffer
* @param size Number of bytes to be read
*
* @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.
*/
ssize_t fs_read(fs_file_t *zfp, void *ptr, size_t size);
/**
* @brief File write
*
* Writes items of data of size bytes long.
*
* @param zfp Pointer to the file object
* @param ptr Pointer to the data buffer
* @param size Number of bytes to be write
*
* @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.
*/
ssize_t fs_write(fs_file_t *zfp, const void *ptr, size_t size);
/**
* @brief 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.
*
* @param zfp Pointer to the file object
* @param offset Relative location to move the file pointer to
* @param whence 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.
*
* @retval 0 Success
* @retval -ERRNO errno code if error.
*/
int fs_seek(fs_file_t *zfp, off_t offset, int whence);
/**
* @brief Get current file position.
*
* Retrieves the current position in the file.
*
* @param zfp Pointer to the file object
*
* @retval position Current position in file
* Current revision does not validate the file object.
*/
off_t fs_tell(fs_file_t *zfp);
/**
* @brief 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.
*
* @param zfp Pointer to the file object
* @param length New size of the file in bytes
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_truncate(fs_file_t *zfp, off_t length);
/**
* @brief 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.
*
* @param zfp Pointer to the file object
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_sync(fs_file_t *zfp);
/**
* @brief Directory create
*
* Creates a new directory using specified path.
*
* @param path Path to the directory to create
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_mkdir(const char *path);
/**
* @brief Directory open
*
* Opens an existing directory specified by the path.
*
* @param zdp Pointer to the directory object
* @param path Path to the directory to open
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_opendir(fs_dir_t *zdp, const char *path);
/**
* @brief Directory read entry
*
* Reads directory entries of a open directory
*
* @param zdp Pointer to the directory object
* @param entry Pointer to zfs_dirent structure to read the entry into
*
* @retval 0 Success
* @retval -ERRNO errno code if error
* @return In end-of-dir condition, this will return 0 and set
* entry->name[0] = 0
*/
int fs_readdir(fs_dir_t *zdp, struct fs_dirent *entry);
/**
* @brief Directory close
*
* Closes an open directory.
*
* @param zdp Pointer to the directory object
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_closedir(fs_dir_t *zdp);
/**
* @brief File or directory status
*
* Checks the status of a file or directory specified by the path
*
* @param path Path to the file or directory
* @param entry Pointer to zfs_dirent structure to fill if file or directory
* exists.
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_stat(const char *path, struct fs_dirent *entry);
/**
* @brief Retrieves statistics of the file system volume
*
* Returns the total and available space in the file system volume.
*
* @param stat Pointer to zfs_statvfs structure to receive the fs statistics
*
* @retval 0 Success
* @retval -ERRNO errno code if error
*/
int fs_statvfs(struct fs_statvfs *stat);
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif /* _FS_H_ */
|