zephyr/include/fs.h
David B. Kinder 621ac8f84b doc: add missing API content
Some API material (from doxygen comments) wasn't included in the
generated documentation because there was no doxygengroup Sphinx
directive to display them. This PR add content into appropriate places
in existing documentation (e.g., Bluetooth Cryptography APIs into the
Bluetooth API doc) and creates two new collections for Display and
Miscellaneous APIs.

Comments added to the .rst files to mention doxygengroups that are
intentionally excluded (because they're organizational groups containing
subgroups that are included).

Sorted the Bluetooth API list, mostly.

Fixed a couple doxygen group titles defined in the include files, and
added a few patterns to filter new "expected" errors from the document
generation process.

Legacy and deprecated APIs remain left out, as intended:

   http_legacy  (net/http_legacy.h)
   spi_interface_legacy  (spi_legacy.h)
   zoap  (net/zoap.h)

fixes: Issue #5051

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2017-12-01 08:58:56 -05:00

336 lines
8.1 KiB
C

/*
* 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_ */