From: Andrea Cervesato <andrea.cervesato@suse.com>
Add kernel-doc comments for filesystem query and file creation helpers
in include/tst_fs.h. Document new-API wrappers so they render properly
in the generated documentation.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
include/tst_fs.h | 186 +++++++++++++++++++++++++++++++++++++------------------
1 file changed, 127 insertions(+), 59 deletions(-)
diff --git a/include/tst_fs.h b/include/tst_fs.h
index c55f8a646..80eb1292e 100644
--- a/include/tst_fs.h
+++ b/include/tst_fs.h
@@ -67,32 +67,21 @@ int tst_fs_has_free_(void (*cleanup)(void), const char *path, uint64_t size,
unsigned int mult);
/*
- * Returns filesystem magick for a given path.
+ * Returns filesystem magic for a given path.
*
* The expected usage is:
*
- * if (tst_fs_type(cleanup, ".") == TST_NFS_MAGIC) {
- * tst_brkm(TCONF, cleanup,
- * "Test not supported on NFS filesystem");
- * }
- *
- * Or:
- *
- * long type;
- *
- * switch ((type = tst_fs_type(cleanup, "."))) {
- * case TST_NFS_MAGIC:
- * case TST_TMPFS_MAGIC:
- * case TST_RAMFS_MAGIC:
- * tst_brkm(TCONF, cleanup, "Test not supported on %s filesystem",
- * tst_fs_type_name(type));
- * break;
- * }
+ * if (tst_fs_type(".") == TST_NFS_MAGIC)
+ * tst_brk(TCONF, "Test not supported on NFS filesystem");
*/
long tst_fs_type_(void (*cleanup)(void), const char *path);
-/*
- * Returns filesystem name given magic.
+/**
+ * tst_fs_type_name() - Returns filesystem name given magic.
+ *
+ * @f_type: Filesystem magic number.
+ *
+ * Return: Name of the filesystem as a string.
*/
const char *tst_fs_type_name(long f_type);
@@ -139,10 +128,14 @@ int tst_fs_fill_subdirs_(void (*cleanup) (void), const char *dir);
*/
int tst_dir_is_empty_(void (*cleanup)(void), const char *name, int verbose);
-/*
- * Search $PATH for prog_name and fills buf with absolute path if found.
+/**
+ * tst_get_path() - Searches PATH for program and returns its absolute path.
+ *
+ * @prog_name: Name of executable to look up.
+ * @buf: Buffer to store the absolute path.
+ * @buf_len: Size of the buffer in bytes.
*
- * Returns -1 on failure, either command was not found or buffer was too small.
+ * Return: 0 on success, -1 on failure (command not found or buffer too small).
*/
int tst_get_path(const char *prog_name, char *buf, size_t buf_len);
@@ -156,38 +149,53 @@ int tst_get_path(const char *prog_name, char *buf, size_t buf_len);
int tst_path_exists(const char *fmt, ...)
__attribute__ ((format (printf, 1, 2)));
-/*
- * Fill a file with specified pattern
- * @fd: file descriptor
- * @pattern: pattern
- * @bs: block size
- * @bcount: blocks count
+/**
+ * tst_fill_fd() - Fills an open file descriptor with pattern.
+ *
+ * @fd: File descriptor to write to.
+ * @pattern: Byte pattern to fill with.
+ * @bs: Block size in bytes.
+ * @bcount: Number of blocks.
+ *
+ * Return: 0 on success, non-zero on error.
*/
int tst_fill_fd(int fd, char pattern, size_t bs, size_t bcount);
-/*
- * Preallocate space in open file. If fallocate() fails, falls back to
- * using tst_fill_fd().
- * @fd: file descriptor
- * @bs: block size
- * @bcount: blocks count
+/**
+ * tst_prealloc_size_fd() - Preallocates space in open file descriptor.
+ *
+ * @fd: File descriptor to preallocate space in.
+ * @bs: Block size in bytes.
+ * @bcount: Number of blocks.
+ *
+ * If fallocate() fails, falls back to using tst_fill_fd().
+ *
+ * Return: 0 on success, non-zero on failure.
*/
int tst_prealloc_size_fd(int fd, size_t bs, size_t bcount);
-/*
- * Creates/ovewrites a file with specified pattern
- * @path: path to file
- * @pattern: pattern
- * @bs: block size
- * @bcount: blocks amount
+/**
+ * tst_fill_file() - Creates or overwrites a file with pattern.
+ *
+ * @path: Path to the file.
+ * @pattern: Byte pattern to fill with.
+ * @bs: Block size in bytes.
+ * @bcount: Number of blocks.
+ *
+ * Return: 0 on success, non-zero on failure.
*/
int tst_fill_file(const char *path, char pattern, size_t bs, size_t bcount);
-/*
- * Creates file of specified size. Space will be only preallocated if possible.
- * @path: path to file
- * @bs: block size
- * @bcount: blocks amount
+/**
+ * tst_prealloc_file() - Creates file of specified size.
+ *
+ * @path: Path to the file.
+ * @bs: Block size in bytes.
+ * @bcount: Number of blocks.
+ *
+ * Space will be preallocated if supported, otherwise filled with zeroes.
+ *
+ * Return: 0 on success, non-zero on failure.
*/
int tst_prealloc_file(const char *path, size_t bs, size_t bcount);
@@ -197,56 +205,116 @@ enum tst_fs_impl {
TST_FS_FUSE = 2,
};
-/*
- * Returns if filesystem is supported and if driver is in kernel or FUSE.
+/**
+ * tst_fs_is_supported() - Checks if filesystem is supported.
*
- * @fs_type A filesystem name to check the support for.
+ * @fs_type: Filesystem name to check support for.
+ *
+ * Return: TST_FS_KERNEL if driver is in kernel, TST_FS_FUSE if driver is
+ * in FUSE, or TST_FS_UNSUPPORTED otherwise.
*/
enum tst_fs_impl tst_fs_is_supported(const char *fs_type);
-/*
- * Returns 1 if filesystem is in skiplist 0 otherwise.
+/**
+ * tst_fs_in_skiplist() - Checks if filesystem is in skiplist.
+ *
+ * @fs_type: Filesystem type to look up.
+ * @skiplist: NULL-terminated array of filesystems to skip.
*
- * @fs_type A filesystem type to lookup.
- * @skiplist A NULL terminated array of filesystems to skip.
+ * Return: 1 if filesystem is in skiplist, 0 otherwise.
*/
int tst_fs_in_skiplist(const char *fs_type, const char *const *skiplist);
-/*
- * Creates and writes to files on given path until write fails with ENOSPC
+/**
+ * tst_fill_fs() - Writes to files on given path until ENOSPC.
+ *
+ * @path: Path to directory on filesystem.
+ * @verbose: If non-zero, prints information messages.
+ * @pattern: Pattern access type (TST_FILL_BLOCKS or TST_FILL_RANDOM).
*/
void tst_fill_fs(const char *path, int verbose, enum tst_fill_access_pattern pattern);
-/*
- * Check if FIBMAP ioctl is supported.
- * Tests needs to set .needs_root = 1 in order to avoid EPERM.
+/**
+ * tst_fibmap() - Checks if FIBMAP ioctl is supported.
+ *
+ * @filename: Path to file to check.
*
- * @return 0: FIBMAP is supported, 1: FIBMAP is *not* supported.
+ * Tests need to set .needs_root = 1 in order to avoid EPERM.
+ *
+ * Return: 0 if FIBMAP is supported, 1 if FIBMAP is not supported.
*/
int tst_fibmap(const char *filename);
#ifdef TST_TEST_H__
+/**
+ * tst_fs_type() - Returns filesystem magic for a given path.
+ *
+ * @path: Path to inspect.
+ *
+ * Return: Filesystem magic number.
+ */
static inline long tst_fs_type(const char *path)
{
return tst_fs_type_(NULL, path);
}
+/**
+ * tst_fs_has_free() - Checks if filesystem has sufficient free space.
+ *
+ * @path: Pathname of any file within the mounted filesystem.
+ * @size: Space amount.
+ * @mult: Multiplier for size (TST_BYTES, TST_KB, TST_MB, or TST_GB).
+ *
+ * Return: 1 if required free space is available, 0 otherwise.
+ */
static inline int tst_fs_has_free(const char *path, uint64_t size,
unsigned int mult)
{
return tst_fs_has_free_(NULL, path, size, mult);
}
+/**
+ * tst_fs_fill_hardlinks() - Creates maximum number of hard links in directory.
+ *
+ * @dir: Directory path where hard links are created.
+ *
+ * Creates hard links to a single file inside dir until EMLINK or 65535 links
+ * is reached. If the limit is reached, created files are left in dir and the
+ * count is returned. If no limit is reached or link() fails with ENOSPC or
+ * EDQUOT, previously created files are removed and 0 is returned.
+ *
+ * Return: Number of hard links on success, 0 on failure or no limit.
+ */
static inline int tst_fs_fill_hardlinks(const char *dir)
{
return tst_fs_fill_hardlinks_(NULL, dir);
}
+/**
+ * tst_fs_fill_subdirs() - Creates maximum number of subdirectories in directory.
+ *
+ * @dir: Directory path where subdirectories are created.
+ *
+ * Creates subdirectories in dir until EMLINK or 65535 directories is reached.
+ * If the limit is reached, created directories are left in dir and the count
+ * is returned. If no limit is reached or mkdir() fails with ENOSPC or EDQUOT,
+ * previously created directories are removed and 0 is returned.
+ *
+ * Return: Number of subdirectories on success, 0 on failure or no limit.
+ */
static inline int tst_fs_fill_subdirs(const char *dir)
{
return tst_fs_fill_subdirs_(NULL, dir);
}
+/**
+ * tst_dir_is_empty() - Checks if directory contains any entries.
+ *
+ * @name: Path to the directory.
+ * @verbose: If non-zero, prints messages about directory contents.
+ *
+ * Return: 1 if directory is empty (only '.' and '..'), 0 otherwise.
+ */
static inline int tst_dir_is_empty(const char *name, int verbose)
{
return tst_dir_is_empty_(NULL, name, verbose);
--
2.51.0