tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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>

authored by

Ryusuke Konishi and committed by
Andrew Morton 17c46a45 d22feb5b

+95 -136
+95 -136
fs/nilfs2/ioctl.c
··· 33 33 * @dofunc: concrete function of get/set metadata info 34 34 * 35 35 * Description: nilfs_ioctl_wrap_copy() gets/sets metadata info by means of 36 - * calling dofunc() function on the basis of @argv argument. 36 + * calling dofunc() function on the basis of @argv argument. If successful, 37 + * the requested metadata information is copied to userspace memory. 37 38 * 38 - * Return Value: On success, 0 is returned and requested metadata info 39 - * is copied into userspace. On error, one of the following 40 - * negative error codes is returned. 41 - * 42 - * %-EINVAL - Invalid arguments from userspace. 43 - * 44 - * %-ENOMEM - Insufficient amount of memory available. 45 - * 46 - * %-EFAULT - Failure during execution of requested operation. 39 + * Return: 0 on success, or one of the following negative error codes on 40 + * failure: 41 + * * %-EFAULT - Failure during execution of requested operation. 42 + * * %-EINVAL - Invalid arguments from userspace. 43 + * * %-ENOMEM - Insufficient memory available. 47 44 */ 48 45 static int nilfs_ioctl_wrap_copy(struct the_nilfs *nilfs, 49 46 struct nilfs_argv *argv, int dir, ··· 187 190 * given checkpoint between checkpoint and snapshot state. This ioctl 188 191 * is used in chcp and mkcp utilities. 189 192 * 190 - * Return Value: On success, 0 is returned and mode of a checkpoint is 191 - * changed. On error, one of the following negative error codes 192 - * is returned. 193 - * 194 - * %-EPERM - Operation not permitted. 195 - * 196 - * %-EFAULT - Failure during checkpoint mode changing. 193 + * Return: 0 on success, or one of the following negative error codes on 194 + * failure: 195 + * %-EFAULT - Failure during checkpoint mode changing. 196 + * %-EPERM - Operation not permitted. 197 197 */ 198 198 static int nilfs_ioctl_change_cpmode(struct inode *inode, struct file *filp, 199 199 unsigned int cmd, void __user *argp) ··· 238 244 * checkpoint from NILFS2 file system. This ioctl is used in rmcp 239 245 * utility. 240 246 * 241 - * Return Value: On success, 0 is returned and a checkpoint is 242 - * removed. On error, one of the following negative error codes 243 - * is returned. 244 - * 245 - * %-EPERM - Operation not permitted. 246 - * 247 - * %-EFAULT - Failure during checkpoint removing. 247 + * Return: 0 on success, or one of the following negative error codes on 248 + * failure: 249 + * %-EFAULT - Failure during checkpoint removing. 250 + * %-EPERM - Operation not permitted. 248 251 */ 249 252 static int 250 253 nilfs_ioctl_delete_checkpoint(struct inode *inode, struct file *filp, ··· 287 296 * requested checkpoints. The NILFS_IOCTL_GET_CPINFO ioctl is used in 288 297 * lscp utility and by nilfs_cleanerd daemon. 289 298 * 290 - * Return value: count of nilfs_cpinfo structures in output buffer. 299 + * Return: Count of nilfs_cpinfo structures in output buffer. 291 300 */ 292 301 static ssize_t 293 302 nilfs_ioctl_do_get_cpinfo(struct the_nilfs *nilfs, __u64 *posp, int flags, ··· 311 320 * 312 321 * Description: nilfs_ioctl_get_cpstat() returns information about checkpoints. 313 322 * The NILFS_IOCTL_GET_CPSTAT ioctl is used by lscp, rmcp utilities 314 - * and by nilfs_cleanerd daemon. 323 + * and by nilfs_cleanerd daemon. The checkpoint statistics are copied to 324 + * the userspace memory pointed to by @argp. 315 325 * 316 - * Return Value: On success, 0 is returned, and checkpoints information is 317 - * copied into userspace pointer @argp. On error, one of the following 318 - * negative error codes is returned. 319 - * 320 - * %-EIO - I/O error. 321 - * 322 - * %-ENOMEM - Insufficient amount of memory available. 323 - * 324 - * %-EFAULT - Failure during getting checkpoints statistics. 326 + * Return: 0 on success, or one of the following negative error codes on 327 + * failure: 328 + * * %-EFAULT - Failure during getting checkpoints statistics. 329 + * * %-EIO - I/O error. 330 + * * %-ENOMEM - Insufficient memory available. 325 331 */ 326 332 static int nilfs_ioctl_get_cpstat(struct inode *inode, struct file *filp, 327 333 unsigned int cmd, void __user *argp) ··· 351 363 * info about requested segments. The NILFS_IOCTL_GET_SUINFO ioctl is used 352 364 * in lssu, nilfs_resize utilities and by nilfs_cleanerd daemon. 353 365 * 354 - * Return value: count of nilfs_suinfo structures in output buffer. 366 + * Return: Count of nilfs_suinfo structures in output buffer on success, 367 + * or a negative error code on failure. 355 368 */ 356 369 static ssize_t 357 370 nilfs_ioctl_do_get_suinfo(struct the_nilfs *nilfs, __u64 *posp, int flags, ··· 376 387 * 377 388 * Description: nilfs_ioctl_get_sustat() returns segment usage statistics. 378 389 * The NILFS_IOCTL_GET_SUSTAT ioctl is used in lssu, nilfs_resize utilities 379 - * and by nilfs_cleanerd daemon. 390 + * and by nilfs_cleanerd daemon. The requested segment usage information is 391 + * copied to the userspace memory pointed to by @argp. 380 392 * 381 - * Return Value: On success, 0 is returned, and segment usage information is 382 - * copied into userspace pointer @argp. On error, one of the following 383 - * negative error codes is returned. 384 - * 385 - * %-EIO - I/O error. 386 - * 387 - * %-ENOMEM - Insufficient amount of memory available. 388 - * 389 - * %-EFAULT - Failure during getting segment usage statistics. 393 + * Return: 0 on success, or one of the following negative error codes on 394 + * failure: 395 + * * %-EFAULT - Failure during getting segment usage statistics. 396 + * * %-EIO - I/O error. 397 + * * %-ENOMEM - Insufficient memory available. 390 398 */ 391 399 static int nilfs_ioctl_get_sustat(struct inode *inode, struct file *filp, 392 400 unsigned int cmd, void __user *argp) ··· 416 430 * on virtual block addresses. The NILFS_IOCTL_GET_VINFO ioctl is used 417 431 * by nilfs_cleanerd daemon. 418 432 * 419 - * Return value: count of nilfs_vinfo structures in output buffer. 433 + * Return: Count of nilfs_vinfo structures in output buffer on success, or 434 + * a negative error code on failure. 420 435 */ 421 436 static ssize_t 422 437 nilfs_ioctl_do_get_vinfo(struct the_nilfs *nilfs, __u64 *posp, int flags, ··· 444 457 * about descriptors of disk block numbers. The NILFS_IOCTL_GET_BDESCS ioctl 445 458 * is used by nilfs_cleanerd daemon. 446 459 * 447 - * Return value: count of nilfs_bdescs structures in output buffer. 460 + * Return: Count of nilfs_bdescs structures in output buffer on success, or 461 + * a negative error code on failure. 448 462 */ 449 463 static ssize_t 450 464 nilfs_ioctl_do_get_bdescs(struct the_nilfs *nilfs, __u64 *posp, int flags, ··· 482 494 * 483 495 * Description: nilfs_ioctl_do_get_bdescs() function returns information 484 496 * about descriptors of disk block numbers. The NILFS_IOCTL_GET_BDESCS ioctl 485 - * is used by nilfs_cleanerd daemon. 497 + * is used by nilfs_cleanerd daemon. If successful, disk block descriptors 498 + * are copied to userspace pointer @argp. 486 499 * 487 - * Return Value: On success, 0 is returned, and disk block descriptors are 488 - * copied into userspace pointer @argp. On error, one of the following 489 - * negative error codes is returned. 490 - * 491 - * %-EINVAL - Invalid arguments from userspace. 492 - * 493 - * %-EIO - I/O error. 494 - * 495 - * %-ENOMEM - Insufficient amount of memory available. 496 - * 497 - * %-EFAULT - Failure during getting disk block descriptors. 500 + * Return: 0 on success, or one of the following negative error codes on 501 + * failure: 502 + * * %-EFAULT - Failure during getting disk block descriptors. 503 + * * %-EINVAL - Invalid arguments from userspace. 504 + * * %-EIO - I/O error. 505 + * * %-ENOMEM - Insufficient memory available. 498 506 */ 499 507 static int nilfs_ioctl_get_bdescs(struct inode *inode, struct file *filp, 500 508 unsigned int cmd, void __user *argp) ··· 524 540 * Description: nilfs_ioctl_move_inode_block() function registers data/node 525 541 * buffer in the GC pagecache and submit read request. 526 542 * 527 - * Return Value: On success, 0 is returned. On error, one of the following 528 - * negative error codes is returned. 529 - * 530 - * %-EIO - I/O error. 531 - * 532 - * %-ENOMEM - Insufficient amount of memory available. 533 - * 534 - * %-ENOENT - Requested block doesn't exist. 535 - * 536 - * %-EEXIST - Blocks conflict is detected. 543 + * Return: 0 on success, or one of the following negative error codes on 544 + * failure: 545 + * * %-EEXIST - Block conflict detected. 546 + * * %-EIO - I/O error. 547 + * * %-ENOENT - Requested block doesn't exist. 548 + * * %-ENOMEM - Insufficient memory available. 537 549 */ 538 550 static int nilfs_ioctl_move_inode_block(struct inode *inode, 539 551 struct nilfs_vdesc *vdesc, ··· 584 604 * blocks that garbage collector specified with the array of nilfs_vdesc 585 605 * structures and stores them into page caches of GC inodes. 586 606 * 587 - * Return Value: Number of processed nilfs_vdesc structures or 588 - * error code, otherwise. 607 + * Return: Number of processed nilfs_vdesc structures on success, or 608 + * a negative error code on failure. 589 609 */ 590 610 static int nilfs_ioctl_move_blocks(struct super_block *sb, 591 611 struct nilfs_argv *argv, void *buf) ··· 662 682 * in the period from p_start to p_end, excluding p_end itself. The checkpoints 663 683 * which have been already deleted are ignored. 664 684 * 665 - * Return Value: Number of processed nilfs_period structures or 666 - * error code, otherwise. 667 - * 668 - * %-EIO - I/O error. 669 - * 670 - * %-ENOMEM - Insufficient amount of memory available. 671 - * 672 - * %-EINVAL - invalid checkpoints. 685 + * Return: Number of processed nilfs_period structures on success, or one of 686 + * the following negative error codes on failure: 687 + * * %-EINVAL - invalid checkpoints. 688 + * * %-EIO - I/O error. 689 + * * %-ENOMEM - Insufficient memory available. 673 690 */ 674 691 static int nilfs_ioctl_delete_checkpoints(struct the_nilfs *nilfs, 675 692 struct nilfs_argv *argv, void *buf) ··· 694 717 * Description: nilfs_ioctl_free_vblocknrs() function frees 695 718 * the virtual block numbers specified by @buf and @argv->v_nmembs. 696 719 * 697 - * Return Value: Number of processed virtual block numbers or 698 - * error code, otherwise. 699 - * 700 - * %-EIO - I/O error. 701 - * 702 - * %-ENOMEM - Insufficient amount of memory available. 703 - * 704 - * %-ENOENT - The virtual block number have not been allocated. 720 + * Return: Number of processed virtual block numbers on success, or one of the 721 + * following negative error codes on failure: 722 + * * %-EIO - I/O error. 723 + * * %-ENOENT - Unallocated virtual block number. 724 + * * %-ENOMEM - Insufficient memory available. 705 725 */ 706 726 static int nilfs_ioctl_free_vblocknrs(struct the_nilfs *nilfs, 707 727 struct nilfs_argv *argv, void *buf) ··· 720 746 * Description: nilfs_ioctl_mark_blocks_dirty() function marks 721 747 * metadata file or data blocks as dirty. 722 748 * 723 - * Return Value: Number of processed block descriptors or 724 - * error code, otherwise. 725 - * 726 - * %-ENOMEM - Insufficient memory available. 727 - * 728 - * %-EIO - I/O error 729 - * 730 - * %-ENOENT - the specified block does not exist (hole block) 749 + * Return: Number of processed block descriptors on success, or one of the 750 + * following negative error codes on failure: 751 + * * %-EIO - I/O error. 752 + * * %-ENOENT - Non-existent block (hole block). 753 + * * %-ENOMEM - Insufficient memory available. 731 754 */ 732 755 static int nilfs_ioctl_mark_blocks_dirty(struct the_nilfs *nilfs, 733 756 struct nilfs_argv *argv, void *buf) ··· 823 852 * from userspace. The NILFS_IOCTL_CLEAN_SEGMENTS ioctl is used by 824 853 * nilfs_cleanerd daemon. 825 854 * 826 - * Return Value: On success, 0 is returned or error code, otherwise. 855 + * Return: 0 on success, or a negative error code on failure. 827 856 */ 828 857 static int nilfs_ioctl_clean_segments(struct inode *inode, struct file *filp, 829 858 unsigned int cmd, void __user *argp) ··· 947 976 * and metadata are written out to the device when it successfully 948 977 * returned. 949 978 * 950 - * Return Value: On success, 0 is retured. On errors, one of the following 951 - * negative error code is returned. 952 - * 953 - * %-EROFS - Read only filesystem. 954 - * 955 - * %-EIO - I/O error 956 - * 957 - * %-ENOSPC - No space left on device (only in a panic state). 958 - * 959 - * %-ERESTARTSYS - Interrupted. 960 - * 961 - * %-ENOMEM - Insufficient memory available. 962 - * 963 - * %-EFAULT - Failure during execution of requested operation. 979 + * Return: 0 on success, or one of the following negative error codes on 980 + * failure: 981 + * * %-EFAULT - Failure during execution of requested operation. 982 + * * %-EIO - I/O error. 983 + * * %-ENOMEM - Insufficient memory available. 984 + * * %-ENOSPC - No space left on device (only in a panic state). 985 + * * %-ERESTARTSYS - Interrupted. 986 + * * %-EROFS - Read only filesystem. 964 987 */ 965 988 static int nilfs_ioctl_sync(struct inode *inode, struct file *filp, 966 989 unsigned int cmd, void __user *argp) ··· 988 1023 * @filp: file object 989 1024 * @argp: pointer on argument from userspace 990 1025 * 991 - * Return Value: On success, 0 is returned or error code, otherwise. 1026 + * Return: 0 on success, or a negative error code on failure. 992 1027 */ 993 1028 static int nilfs_ioctl_resize(struct inode *inode, struct file *filp, 994 1029 void __user *argp) ··· 1024 1059 * checks the arguments from userspace and calls nilfs_sufile_trim_fs, which 1025 1060 * performs the actual trim operation. 1026 1061 * 1027 - * Return Value: On success, 0 is returned or negative error code, otherwise. 1062 + * Return: 0 on success, or a negative error code on failure. 1028 1063 */ 1029 1064 static int nilfs_ioctl_trim_fs(struct inode *inode, void __user *argp) 1030 1065 { ··· 1066 1101 * of segments in bytes and upper limit of segments in bytes. 1067 1102 * The NILFS_IOCTL_SET_ALLOC_RANGE is used by nilfs_resize utility. 1068 1103 * 1069 - * Return Value: On success, 0 is returned or error code, otherwise. 1104 + * Return: 0 on success, or a negative error code on failure. 1070 1105 */ 1071 1106 static int nilfs_ioctl_set_alloc_range(struct inode *inode, void __user *argp) 1072 1107 { ··· 1117 1152 * @dofunc: concrete function of getting metadata info 1118 1153 * 1119 1154 * Description: nilfs_ioctl_get_info() gets metadata info by means of 1120 - * calling dofunc() function. 1155 + * calling dofunc() function. The requested metadata information is copied 1156 + * to userspace memory @argp. 1121 1157 * 1122 - * Return Value: On success, 0 is returned and requested metadata info 1123 - * is copied into userspace. On error, one of the following 1124 - * negative error codes is returned. 1125 - * 1126 - * %-EINVAL - Invalid arguments from userspace. 1127 - * 1128 - * %-ENOMEM - Insufficient amount of memory available. 1129 - * 1130 - * %-EFAULT - Failure during execution of requested operation. 1158 + * Return: 0 on success, or one of the following negative error codes on 1159 + * failure: 1160 + * * %-EFAULT - Failure during execution of requested operation. 1161 + * * %-EINVAL - Invalid arguments from userspace. 1162 + * * %-EIO - I/O error. 1163 + * * %-ENOMEM - Insufficient memory available. 1131 1164 */ 1132 1165 static int nilfs_ioctl_get_info(struct inode *inode, struct file *filp, 1133 1166 unsigned int cmd, void __user *argp, ··· 1165 1202 * encapsulated in nilfs_argv and updates the segment usage info 1166 1203 * according to the flags in nilfs_suinfo_update. 1167 1204 * 1168 - * Return Value: On success, 0 is returned. On error, one of the 1169 - * following negative error codes is returned. 1170 - * 1171 - * %-EPERM - Not enough permissions 1172 - * 1173 - * %-EFAULT - Error copying input data 1174 - * 1175 - * %-EIO - I/O error. 1176 - * 1177 - * %-ENOMEM - Insufficient amount of memory available. 1178 - * 1179 - * %-EINVAL - Invalid values in input (segment number, flags or nblocks) 1205 + * Return: 0 on success, or one of the following negative error codes on 1206 + * failure: 1207 + * * %-EEXIST - Block conflict detected. 1208 + * * %-EFAULT - Error copying input data. 1209 + * * %-EINVAL - Invalid values in input (segment number, flags or nblocks). 1210 + * * %-EIO - I/O error. 1211 + * * %-ENOMEM - Insufficient memory available. 1212 + * * %-EPERM - Not enough permissions. 1180 1213 */ 1181 1214 static int nilfs_ioctl_set_suinfo(struct inode *inode, struct file *filp, 1182 1215 unsigned int cmd, void __user *argp)