mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2026-01-11 17:10:13 +00:00
nilfs2: correct return value kernel-doc descriptions for ioctl functions
Patch series "nilfs2: fix kernel-doc comments for function return values", v2. This series fixes the inadequacies in the return value descriptions in nilfs2's kernel-doc comments (mainly incorrect formatting), as well as the lack of return value descriptions themselves, and fixes most of the remaining warnings that are output when the kernel-doc script is run with the "-Wall" option. This patch (of 7): In the kernel-doc comments for functions, there are many cases where the format of the return value description is inaccurate, such as "Return Value: ...", which causes many warnings to be output when the kernel-doc script is executed with the "-Wall" option. This fixes such incorrectly formatted return value descriptions for ioctl functions. Link: https://lkml.kernel.org/r/20250110010530.21872-1-konishi.ryusuke@gmail.com Link: https://lkml.kernel.org/r/20250110010530.21872-2-konishi.ryusuke@gmail.com Signed-off-by: Ryusuke Konishi <konishi.ryusuke@gmail.com> Cc: "Brian G ." <gissf1@gmail.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
This commit is contained in:
Ryusuke Konishi
Andrew Morton
parent
d22feb5b64
commit
17c46a45cd
@ -33,17 +33,14 @@
|
||||
* @dofunc: concrete function of get/set metadata info
|
||||
*
|
||||
* Description: nilfs_ioctl_wrap_copy() gets/sets metadata info by means of
|
||||
* calling dofunc() function on the basis of @argv argument.
|
||||
* calling dofunc() function on the basis of @argv argument. If successful,
|
||||
* the requested metadata information is copied to userspace memory.
|
||||
*
|
||||
* Return Value: On success, 0 is returned and requested metadata info
|
||||
* is copied into userspace. On error, one of the following
|
||||
* negative error codes is returned.
|
||||
*
|
||||
* %-EINVAL - Invalid arguments from userspace.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-EFAULT - Failure during execution of requested operation.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* * %-EFAULT - Failure during execution of requested operation.
|
||||
* * %-EINVAL - Invalid arguments from userspace.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_wrap_copy(struct the_nilfs *nilfs,
|
||||
struct nilfs_argv *argv, int dir,
|
||||
@ -190,13 +187,10 @@ static int nilfs_ioctl_getversion(struct inode *inode, void __user *argp)
|
||||
* given checkpoint between checkpoint and snapshot state. This ioctl
|
||||
* is used in chcp and mkcp utilities.
|
||||
*
|
||||
* Return Value: On success, 0 is returned and mode of a checkpoint is
|
||||
* changed. On error, one of the following negative error codes
|
||||
* is returned.
|
||||
*
|
||||
* %-EPERM - Operation not permitted.
|
||||
*
|
||||
* %-EFAULT - Failure during checkpoint mode changing.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* %-EFAULT - Failure during checkpoint mode changing.
|
||||
* %-EPERM - Operation not permitted.
|
||||
*/
|
||||
static int nilfs_ioctl_change_cpmode(struct inode *inode, struct file *filp,
|
||||
unsigned int cmd, void __user *argp)
|
||||
@ -244,13 +238,10 @@ out:
|
||||
* checkpoint from NILFS2 file system. This ioctl is used in rmcp
|
||||
* utility.
|
||||
*
|
||||
* Return Value: On success, 0 is returned and a checkpoint is
|
||||
* removed. On error, one of the following negative error codes
|
||||
* is returned.
|
||||
*
|
||||
* %-EPERM - Operation not permitted.
|
||||
*
|
||||
* %-EFAULT - Failure during checkpoint removing.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* %-EFAULT - Failure during checkpoint removing.
|
||||
* %-EPERM - Operation not permitted.
|
||||
*/
|
||||
static int
|
||||
nilfs_ioctl_delete_checkpoint(struct inode *inode, struct file *filp,
|
||||
@ -296,7 +287,7 @@ out:
|
||||
* requested checkpoints. The NILFS_IOCTL_GET_CPINFO ioctl is used in
|
||||
* lscp utility and by nilfs_cleanerd daemon.
|
||||
*
|
||||
* Return value: count of nilfs_cpinfo structures in output buffer.
|
||||
* Return: Count of nilfs_cpinfo structures in output buffer.
|
||||
*/
|
||||
static ssize_t
|
||||
nilfs_ioctl_do_get_cpinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
|
||||
@ -320,17 +311,14 @@ nilfs_ioctl_do_get_cpinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
|
||||
*
|
||||
* Description: nilfs_ioctl_get_cpstat() returns information about checkpoints.
|
||||
* The NILFS_IOCTL_GET_CPSTAT ioctl is used by lscp, rmcp utilities
|
||||
* and by nilfs_cleanerd daemon.
|
||||
* and by nilfs_cleanerd daemon. The checkpoint statistics are copied to
|
||||
* the userspace memory pointed to by @argp.
|
||||
*
|
||||
* Return Value: On success, 0 is returned, and checkpoints information is
|
||||
* copied into userspace pointer @argp. On error, one of the following
|
||||
* negative error codes is returned.
|
||||
*
|
||||
* %-EIO - I/O error.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-EFAULT - Failure during getting checkpoints statistics.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* * %-EFAULT - Failure during getting checkpoints statistics.
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_get_cpstat(struct inode *inode, struct file *filp,
|
||||
unsigned int cmd, void __user *argp)
|
||||
@ -363,7 +351,8 @@ static int nilfs_ioctl_get_cpstat(struct inode *inode, struct file *filp,
|
||||
* info about requested segments. The NILFS_IOCTL_GET_SUINFO ioctl is used
|
||||
* in lssu, nilfs_resize utilities and by nilfs_cleanerd daemon.
|
||||
*
|
||||
* Return value: count of nilfs_suinfo structures in output buffer.
|
||||
* Return: Count of nilfs_suinfo structures in output buffer on success,
|
||||
* or a negative error code on failure.
|
||||
*/
|
||||
static ssize_t
|
||||
nilfs_ioctl_do_get_suinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
|
||||
@ -387,17 +376,14 @@ nilfs_ioctl_do_get_suinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
|
||||
*
|
||||
* Description: nilfs_ioctl_get_sustat() returns segment usage statistics.
|
||||
* The NILFS_IOCTL_GET_SUSTAT ioctl is used in lssu, nilfs_resize utilities
|
||||
* and by nilfs_cleanerd daemon.
|
||||
* and by nilfs_cleanerd daemon. The requested segment usage information is
|
||||
* copied to the userspace memory pointed to by @argp.
|
||||
*
|
||||
* Return Value: On success, 0 is returned, and segment usage information is
|
||||
* copied into userspace pointer @argp. On error, one of the following
|
||||
* negative error codes is returned.
|
||||
*
|
||||
* %-EIO - I/O error.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-EFAULT - Failure during getting segment usage statistics.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* * %-EFAULT - Failure during getting segment usage statistics.
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_get_sustat(struct inode *inode, struct file *filp,
|
||||
unsigned int cmd, void __user *argp)
|
||||
@ -430,7 +416,8 @@ static int nilfs_ioctl_get_sustat(struct inode *inode, struct file *filp,
|
||||
* on virtual block addresses. The NILFS_IOCTL_GET_VINFO ioctl is used
|
||||
* by nilfs_cleanerd daemon.
|
||||
*
|
||||
* Return value: count of nilfs_vinfo structures in output buffer.
|
||||
* Return: Count of nilfs_vinfo structures in output buffer on success, or
|
||||
* a negative error code on failure.
|
||||
*/
|
||||
static ssize_t
|
||||
nilfs_ioctl_do_get_vinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
|
||||
@ -457,7 +444,8 @@ nilfs_ioctl_do_get_vinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
|
||||
* about descriptors of disk block numbers. The NILFS_IOCTL_GET_BDESCS ioctl
|
||||
* is used by nilfs_cleanerd daemon.
|
||||
*
|
||||
* Return value: count of nilfs_bdescs structures in output buffer.
|
||||
* Return: Count of nilfs_bdescs structures in output buffer on success, or
|
||||
* a negative error code on failure.
|
||||
*/
|
||||
static ssize_t
|
||||
nilfs_ioctl_do_get_bdescs(struct the_nilfs *nilfs, __u64 *posp, int flags,
|
||||
@ -494,19 +482,15 @@ nilfs_ioctl_do_get_bdescs(struct the_nilfs *nilfs, __u64 *posp, int flags,
|
||||
*
|
||||
* Description: nilfs_ioctl_do_get_bdescs() function returns information
|
||||
* about descriptors of disk block numbers. The NILFS_IOCTL_GET_BDESCS ioctl
|
||||
* is used by nilfs_cleanerd daemon.
|
||||
* is used by nilfs_cleanerd daemon. If successful, disk block descriptors
|
||||
* are copied to userspace pointer @argp.
|
||||
*
|
||||
* Return Value: On success, 0 is returned, and disk block descriptors are
|
||||
* copied into userspace pointer @argp. On error, one of the following
|
||||
* negative error codes is returned.
|
||||
*
|
||||
* %-EINVAL - Invalid arguments from userspace.
|
||||
*
|
||||
* %-EIO - I/O error.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-EFAULT - Failure during getting disk block descriptors.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* * %-EFAULT - Failure during getting disk block descriptors.
|
||||
* * %-EINVAL - Invalid arguments from userspace.
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_get_bdescs(struct inode *inode, struct file *filp,
|
||||
unsigned int cmd, void __user *argp)
|
||||
@ -540,16 +524,12 @@ static int nilfs_ioctl_get_bdescs(struct inode *inode, struct file *filp,
|
||||
* Description: nilfs_ioctl_move_inode_block() function registers data/node
|
||||
* buffer in the GC pagecache and submit read request.
|
||||
*
|
||||
* Return Value: On success, 0 is returned. On error, one of the following
|
||||
* negative error codes is returned.
|
||||
*
|
||||
* %-EIO - I/O error.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-ENOENT - Requested block doesn't exist.
|
||||
*
|
||||
* %-EEXIST - Blocks conflict is detected.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* * %-EEXIST - Block conflict detected.
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOENT - Requested block doesn't exist.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_move_inode_block(struct inode *inode,
|
||||
struct nilfs_vdesc *vdesc,
|
||||
@ -604,8 +584,8 @@ static int nilfs_ioctl_move_inode_block(struct inode *inode,
|
||||
* blocks that garbage collector specified with the array of nilfs_vdesc
|
||||
* structures and stores them into page caches of GC inodes.
|
||||
*
|
||||
* Return Value: Number of processed nilfs_vdesc structures or
|
||||
* error code, otherwise.
|
||||
* Return: Number of processed nilfs_vdesc structures on success, or
|
||||
* a negative error code on failure.
|
||||
*/
|
||||
static int nilfs_ioctl_move_blocks(struct super_block *sb,
|
||||
struct nilfs_argv *argv, void *buf)
|
||||
@ -682,14 +662,11 @@ static int nilfs_ioctl_move_blocks(struct super_block *sb,
|
||||
* in the period from p_start to p_end, excluding p_end itself. The checkpoints
|
||||
* which have been already deleted are ignored.
|
||||
*
|
||||
* Return Value: Number of processed nilfs_period structures or
|
||||
* error code, otherwise.
|
||||
*
|
||||
* %-EIO - I/O error.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-EINVAL - invalid checkpoints.
|
||||
* Return: Number of processed nilfs_period structures on success, or one of
|
||||
* the following negative error codes on failure:
|
||||
* * %-EINVAL - invalid checkpoints.
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_delete_checkpoints(struct the_nilfs *nilfs,
|
||||
struct nilfs_argv *argv, void *buf)
|
||||
@ -717,14 +694,11 @@ static int nilfs_ioctl_delete_checkpoints(struct the_nilfs *nilfs,
|
||||
* Description: nilfs_ioctl_free_vblocknrs() function frees
|
||||
* the virtual block numbers specified by @buf and @argv->v_nmembs.
|
||||
*
|
||||
* Return Value: Number of processed virtual block numbers or
|
||||
* error code, otherwise.
|
||||
*
|
||||
* %-EIO - I/O error.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-ENOENT - The virtual block number have not been allocated.
|
||||
* Return: Number of processed virtual block numbers on success, or one of the
|
||||
* following negative error codes on failure:
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOENT - Unallocated virtual block number.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_free_vblocknrs(struct the_nilfs *nilfs,
|
||||
struct nilfs_argv *argv, void *buf)
|
||||
@ -746,14 +720,11 @@ static int nilfs_ioctl_free_vblocknrs(struct the_nilfs *nilfs,
|
||||
* Description: nilfs_ioctl_mark_blocks_dirty() function marks
|
||||
* metadata file or data blocks as dirty.
|
||||
*
|
||||
* Return Value: Number of processed block descriptors or
|
||||
* error code, otherwise.
|
||||
*
|
||||
* %-ENOMEM - Insufficient memory available.
|
||||
*
|
||||
* %-EIO - I/O error
|
||||
*
|
||||
* %-ENOENT - the specified block does not exist (hole block)
|
||||
* Return: Number of processed block descriptors on success, or one of the
|
||||
* following negative error codes on failure:
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOENT - Non-existent block (hole block).
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_mark_blocks_dirty(struct the_nilfs *nilfs,
|
||||
struct nilfs_argv *argv, void *buf)
|
||||
@ -852,7 +823,7 @@ int nilfs_ioctl_prepare_clean_segments(struct the_nilfs *nilfs,
|
||||
* from userspace. The NILFS_IOCTL_CLEAN_SEGMENTS ioctl is used by
|
||||
* nilfs_cleanerd daemon.
|
||||
*
|
||||
* Return Value: On success, 0 is returned or error code, otherwise.
|
||||
* Return: 0 on success, or a negative error code on failure.
|
||||
*/
|
||||
static int nilfs_ioctl_clean_segments(struct inode *inode, struct file *filp,
|
||||
unsigned int cmd, void __user *argp)
|
||||
@ -976,20 +947,14 @@ out:
|
||||
* and metadata are written out to the device when it successfully
|
||||
* returned.
|
||||
*
|
||||
* Return Value: On success, 0 is retured. On errors, one of the following
|
||||
* negative error code is returned.
|
||||
*
|
||||
* %-EROFS - Read only filesystem.
|
||||
*
|
||||
* %-EIO - I/O error
|
||||
*
|
||||
* %-ENOSPC - No space left on device (only in a panic state).
|
||||
*
|
||||
* %-ERESTARTSYS - Interrupted.
|
||||
*
|
||||
* %-ENOMEM - Insufficient memory available.
|
||||
*
|
||||
* %-EFAULT - Failure during execution of requested operation.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* * %-EFAULT - Failure during execution of requested operation.
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
* * %-ENOSPC - No space left on device (only in a panic state).
|
||||
* * %-ERESTARTSYS - Interrupted.
|
||||
* * %-EROFS - Read only filesystem.
|
||||
*/
|
||||
static int nilfs_ioctl_sync(struct inode *inode, struct file *filp,
|
||||
unsigned int cmd, void __user *argp)
|
||||
@ -1023,7 +988,7 @@ static int nilfs_ioctl_sync(struct inode *inode, struct file *filp,
|
||||
* @filp: file object
|
||||
* @argp: pointer on argument from userspace
|
||||
*
|
||||
* Return Value: On success, 0 is returned or error code, otherwise.
|
||||
* Return: 0 on success, or a negative error code on failure.
|
||||
*/
|
||||
static int nilfs_ioctl_resize(struct inode *inode, struct file *filp,
|
||||
void __user *argp)
|
||||
@ -1059,7 +1024,7 @@ out:
|
||||
* checks the arguments from userspace and calls nilfs_sufile_trim_fs, which
|
||||
* performs the actual trim operation.
|
||||
*
|
||||
* Return Value: On success, 0 is returned or negative error code, otherwise.
|
||||
* Return: 0 on success, or a negative error code on failure.
|
||||
*/
|
||||
static int nilfs_ioctl_trim_fs(struct inode *inode, void __user *argp)
|
||||
{
|
||||
@ -1101,7 +1066,7 @@ static int nilfs_ioctl_trim_fs(struct inode *inode, void __user *argp)
|
||||
* of segments in bytes and upper limit of segments in bytes.
|
||||
* The NILFS_IOCTL_SET_ALLOC_RANGE is used by nilfs_resize utility.
|
||||
*
|
||||
* Return Value: On success, 0 is returned or error code, otherwise.
|
||||
* Return: 0 on success, or a negative error code on failure.
|
||||
*/
|
||||
static int nilfs_ioctl_set_alloc_range(struct inode *inode, void __user *argp)
|
||||
{
|
||||
@ -1152,17 +1117,15 @@ out:
|
||||
* @dofunc: concrete function of getting metadata info
|
||||
*
|
||||
* Description: nilfs_ioctl_get_info() gets metadata info by means of
|
||||
* calling dofunc() function.
|
||||
* calling dofunc() function. The requested metadata information is copied
|
||||
* to userspace memory @argp.
|
||||
*
|
||||
* Return Value: On success, 0 is returned and requested metadata info
|
||||
* is copied into userspace. On error, one of the following
|
||||
* negative error codes is returned.
|
||||
*
|
||||
* %-EINVAL - Invalid arguments from userspace.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-EFAULT - Failure during execution of requested operation.
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* * %-EFAULT - Failure during execution of requested operation.
|
||||
* * %-EINVAL - Invalid arguments from userspace.
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
*/
|
||||
static int nilfs_ioctl_get_info(struct inode *inode, struct file *filp,
|
||||
unsigned int cmd, void __user *argp,
|
||||
@ -1202,18 +1165,14 @@ static int nilfs_ioctl_get_info(struct inode *inode, struct file *filp,
|
||||
* encapsulated in nilfs_argv and updates the segment usage info
|
||||
* according to the flags in nilfs_suinfo_update.
|
||||
*
|
||||
* Return Value: On success, 0 is returned. On error, one of the
|
||||
* following negative error codes is returned.
|
||||
*
|
||||
* %-EPERM - Not enough permissions
|
||||
*
|
||||
* %-EFAULT - Error copying input data
|
||||
*
|
||||
* %-EIO - I/O error.
|
||||
*
|
||||
* %-ENOMEM - Insufficient amount of memory available.
|
||||
*
|
||||
* %-EINVAL - Invalid values in input (segment number, flags or nblocks)
|
||||
* Return: 0 on success, or one of the following negative error codes on
|
||||
* failure:
|
||||
* * %-EEXIST - Block conflict detected.
|
||||
* * %-EFAULT - Error copying input data.
|
||||
* * %-EINVAL - Invalid values in input (segment number, flags or nblocks).
|
||||
* * %-EIO - I/O error.
|
||||
* * %-ENOMEM - Insufficient memory available.
|
||||
* * %-EPERM - Not enough permissions.
|
||||
*/
|
||||
static int nilfs_ioctl_set_suinfo(struct inode *inode, struct file *filp,
|
||||
unsigned int cmd, void __user *argp)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user