From nobody Sun Feb 8 01:42:09 2026 Received: from mail-pj1-f53.google.com (mail-pj1-f53.google.com [209.85.216.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 499BA13D24D; Thu, 9 Jan 2025 03:28:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.53 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393299; cv=none; b=ZwjwAjb3XPWNix22k4DKyhiJjQDQJsGA1yBhYBUkgG0+ysYFIKRoSXRpAO/Xf9lKgEmi6CzXv5PsT0fgvrF6Zwe4BbuKXHCWUzXwASh0yC01hoPDbSAlf83nx+m1hhPMZAQiGLlf8RSXc4wG4u4FX+uLQbDxeXaUnKMalQBcbyg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393299; c=relaxed/simple; bh=ryDfTMcbW522a/WW7Y4bzB7bwiIx2ByuYW/fQLQaj1M=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kwscTjtETqJ8mMpNUIDCFvEtSuK6BIWx8FQiC7WyLkHHTsvZU1AgYMoKDwKJIHBEsnijbUWdjOBpCAtNVK2NANHrMRwOT5j2jtRQ5JPiByb5eacN+1Lkthulh0D10QR9MrLCupDNaDwJa0z4v3jjG6B3W55OPlSZPjoj5QXLKJc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=nEoF3E8C; arc=none smtp.client-ip=209.85.216.53 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="nEoF3E8C" Received: by mail-pj1-f53.google.com with SMTP id 98e67ed59e1d1-2ee74291415so646582a91.3; Wed, 08 Jan 2025 19:28:17 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1736393296; x=1736998096; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=Akx0QHC5lpOEidPKLbiXZnArP0eNdRdOGsJ9JWNfnX8=; b=nEoF3E8ChWq6TESpLtg9FkgP09vhUsvDJ2SR91078OeDtFlhjQkN73kWsXB8X+MvDh xjpWZB8lWu1srB2HLSfQXrKBREBrG7Dy5nGM6/pK/4ryQHYFFYiZYaH/9YBVc3Sp84Nt 7acjNJ4IjGBzQX683jWtDYAeKbFTeCP7UVvOz6UvnMbcrPkhcH1zutbgM7VY1VlYpnFA j48I0dnRiW1T17bg3MvPt9orb15FRv8pXMt8ew+tmBikXWr1hNZBwYiry4doWoQvh8Y0 r5L3WF8zgema3Zblg2LQ1nw7D3C/UZjtIeKU5rY72NLQV2iIMGMtnKA0iYIlH9uU/HLw 1coA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1736393296; x=1736998096; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Akx0QHC5lpOEidPKLbiXZnArP0eNdRdOGsJ9JWNfnX8=; b=JLwyIbP6KkaDY7bqNusuTOQCyKNFbdQxSCm+kBM1rctH7P9rt8+G6G/eeyhuKEizKP BTYcbyjiSnFVID6mrs9p0EsIiHV8XuIr/Vkw4ig6Nd6KHwFXJbOcOu6QCMamVpiVpvYq fq40maHu/Wks03FdMJdms6eJcpqYidHbatZTQGOjA8kRcbEH/i/IMZpwPoMm4up07jll uTFcGw1rnrIQXnAxo9aSC5AjnZGCvZCoqTrx5aMNC4HM/wr2yyfULJPrgp96cgGQMrUd W01Ubf1LhDidrhb0rwbVIntX7S17l47D9z9maF3v6/47OVjh5tp9nz+PbgSNPl4Fytgj GDpw== X-Forwarded-Encrypted: i=1; AJvYcCWqnTw1ahAdDaNSSFu+NEPErIul4wel593S0bEYBexzgKQawSmLUyjTOw/j0vn+aioD9nQVhrOInfgMSLM=@vger.kernel.org X-Gm-Message-State: AOJu0YxwMG5Z8Her9PaBGOC4Xs2LHHz+cuSMeBloyrZFqHCBkF+cBHAH Qp2njk7TGZreDgUIAv45ljggK9CFr/+rln/WmNp+/SKEM2MVq6NbV/iRRA== X-Gm-Gg: ASbGnctAJ6NahqjZ+OtcRbfu5dfvTYKFcLROkdJ5owrA+xJfUK+k4onUqv4QKVqf1E9 ogOkOMexQ26lN2GtsjyhIA+XqBGhKAstRPOtLNIr78Deo3ZEgckCS9AFYXMI4LYA6OTlmmYv4jC SQzkTb6SmFAJk90Lc9V5BJ5Us1lt2gxaMl9eQ0h3vJsNB+3KZtQlZDtqaDKQkwLROMGJOp6gMYy Qk7Lq9nMVlMMW4BcoRymiQwbDgWVT7wR7dXwLKylqMLYbiUaH4FLp1n/rFyOqr+iSXfcvvkMwq7 2VNhi9uLM206EVfPdQXymX8X7Y/H X-Google-Smtp-Source: AGHT+IECVmz7MNyKEPlVrkw4GzVJVhSsGQYRJYp9ro0iLFl4zVoTPROaBnirVW1SZHx7OOKUeS4W7Q== X-Received: by 2002:a17:90b:37ce:b0:2ee:dd9b:e3e8 with SMTP id 98e67ed59e1d1-2f548ea5390mr8429718a91.8.1736393296002; Wed, 08 Jan 2025 19:28:16 -0800 (PST) Received: from carrot.. (i114-186-237-30.s41.a014.ap.plala.or.jp. [114.186.237.30]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2f55942eed5sm194963a91.27.2025.01.08.19.28.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 08 Jan 2025 19:28:15 -0800 (PST) From: Ryusuke Konishi To: Andrew Morton Cc: linux-nilfs@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 1/6] nilfs2: correct return value kernel-doc descriptions for ioctl functions Date: Thu, 9 Jan 2025 12:23:20 +0900 Message-ID: <20250109032846.10147-2-konishi.ryusuke@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250109032846.10147-1-konishi.ryusuke@gmail.com> References: <20250109032846.10147-1-konishi.ryusuke@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. Signed-off-by: Ryusuke Konishi --- fs/nilfs2/ioctl.c | 220 ++++++++++++++++++---------------------------- 1 file changed, 84 insertions(+), 136 deletions(-) diff --git a/fs/nilfs2/ioctl.c b/fs/nilfs2/ioctl.c index fa77f78df681..f7bcc95847bb 100644 --- a/fs/nilfs2/ioctl.c +++ b/fs/nilfs2/ioctl.c @@ -33,17 +33,13 @@ * @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 successfu= l, + * 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 the following negative error code 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 +186,9 @@ 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 the following negative error code on failure. + * %-EFAULT - Failure during checkpoint mode changing. + * %-EPERM - Operation not permitted. */ static int nilfs_ioctl_change_cpmode(struct inode *inode, struct file *fil= p, unsigned int cmd, void __user *argp) @@ -244,13 +236,9 @@ static int nilfs_ioctl_change_cpmode(struct inode *ino= de, struct file *filp, * 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 the following negative error code 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 +284,7 @@ nilfs_ioctl_delete_checkpoint(struct inode *inode, stru= ct file *filp, * 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 +308,13 @@ nilfs_ioctl_do_get_cpinfo(struct the_nilfs *nilfs, __= u64 *posp, int flags, * * Description: nilfs_ioctl_get_cpstat() returns information about checkpo= ints. * The NILFS_IOCTL_GET_CPSTAT ioctl is used by lscp, rmcp utilities - * and by nilfs_cleanerd daemon. - * - * 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. + * and by nilfs_cleanerd daemon. The checkpoint statistics are copied to + * the userspace memory pointed to by @argp. * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-EFAULT - Failure during getting checkpoints statistics. + * Return: 0 on success, or the following negative error code 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 +347,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 +372,13 @@ 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. - * - * 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. + * and by nilfs_cleanerd daemon. The requested segment usage information = is + * copied to the userspace memory pointed to by @argp. * - * %-EFAULT - Failure during getting segment usage statistics. + * Return: 0 on success, or the following negative error code 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 +411,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 +439,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 ioc= tl * 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 succes, 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 +477,14 @@ 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 ioc= tl - * is used by nilfs_cleanerd daemon. - * - * 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. + * is used by nilfs_cleanerd daemon. If successful, disk block descriptors + * are copied to userspace pointer @argp. * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-EFAULT - Failure during getting disk block descriptors. + * Return: 0 on success, or the following negative error code on failure. + * * %-EFAULT - Failure during getting dick 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 +518,11 @@ 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 the following negative error code 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 +577,8 @@ static int nilfs_ioctl_move_inode_block(struct inode *i= node, * 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 +655,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 checkp= oints * 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 the + * following negative error code 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 +687,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 + * the following error code 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 +713,11 @@ static int nilfs_ioctl_free_vblocknrs(struct the_nilf= s *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 the follow= ing + * negative error code 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 +816,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 *fi= lp, unsigned int cmd, void __user *argp) @@ -976,20 +940,13 @@ static int nilfs_ioctl_clean_segments(struct inode *i= node, struct file *filp, * 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 the following negative error code 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 +980,7 @@ static int nilfs_ioctl_sync(struct inode *inode, struc= t 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 +1016,7 @@ static int nilfs_ioctl_resize(struct inode *inode, st= ruct file *filp, * checks the arguments from userspace and calls nilfs_sufile_trim_fs, whi= ch * performs the actual trim operation. * - * Return Value: On success, 0 is returned or negative error code, otherwi= se. + * 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 +1058,7 @@ static int nilfs_ioctl_trim_fs(struct inode *inode, v= oid __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 *a= rgp) { @@ -1152,17 +1109,14 @@ static int nilfs_ioctl_set_alloc_range(struct inode= *inode, void __user *argp) * @dofunc: concrete function of getting metadata info * * Description: nilfs_ioctl_get_info() gets metadata info by means of - * calling dofunc() function. - * - * 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. + * calling dofunc() function. The requested metadata information is copied + * to userspace memory @argp. * - * %-EINVAL - Invalid arguments from userspace. - * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-EFAULT - Failure during execution of requested operation. + * Return: 0 on success, or the following negative error code 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 +1156,12 @@ 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 the following negative error code 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. + * * %-EPERM - Not enough permissions. */ static int nilfs_ioctl_set_suinfo(struct inode *inode, struct file *filp, unsigned int cmd, void __user *argp) --=20 2.43.0 From nobody Sun Feb 8 01:42:09 2026 Received: from mail-pj1-f53.google.com (mail-pj1-f53.google.com [209.85.216.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 47AD51684AE; Thu, 9 Jan 2025 03:28:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.53 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393301; cv=none; b=msKTARsmKECNYYnu9ctydI07mpr2eHDl3nH7sTV42ChyambW2olextgPgmVqxxDw2wiP5QpXVFBJR9yYjxj9/G4o8Nkf2tDdwgAy1MNjaJGblJhGMhl2ty+qtjtqKVkXSHh+XKiXdpdczoxDFkoF+VCQpBF+d1MzYGLpnKd57Vs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393301; c=relaxed/simple; bh=umj6CQIVsXyZT+uwsppRIYh41lv+WfbNlsR7/+2LrM8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=vEa9jEeJ16hWC5HCUpk/TXIWUnhUWhHZ/tnufoEdQuIwjc1yyp3h5pqdu/Dr7O4ko9+ugRM5jg0QPMHTBcsqFumxWsQGZahwZZzE4zEqgW7X4581AVdbc5Px7l8llRfa9nomCWq9+JL4Lz+woUUHkIngrqPuUNVKXlg3U1m1Q5c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=c9NvGndb; arc=none smtp.client-ip=209.85.216.53 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="c9NvGndb" Received: by mail-pj1-f53.google.com with SMTP id 98e67ed59e1d1-2ee786b3277so623958a91.1; Wed, 08 Jan 2025 19:28:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1736393298; x=1736998098; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=Y7JxCEda9M0WZjHMO8mQopXCuOQme8n8+3GrvRENd5Q=; b=c9NvGndbQHJh/aOFLdfHQJWL3WiiFcLEPmr+FWA23qCFvjPLvKwqrECpZ0ZKswyVCz aZ5LwN+6TqhFMI3iG+b0Kja3Cmr8cl/5qphb5ElFLTEnM1Oyum2tp+3chmeKDezoaAx2 dWrW4urJb3ANZbAUsSnwjpZsW6eCNxcyVN0tYr4KbkLnCSWBUKDa5ulQ5Kz03s7+exju Pmx5WI8A7wFX1fq+0ZGNKossIzXvXsyEAspDMNvnobjLyGDpNWXF6T3kXjgUvZ8Yt365 SYq6soEWgDi33ZGW96QyCZNW+DTOmyoBBE0asPesB7HsgdYsWUCyQC5APU227Hqr8zyz jQLA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1736393298; x=1736998098; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Y7JxCEda9M0WZjHMO8mQopXCuOQme8n8+3GrvRENd5Q=; b=IB8IBFt483/PUZ2TzBvf9cESELtTvgBHxSwyOg/Bf89oeY+NOhnWzzQkpapnw8O8ZQ h16JASCheNvRkViacRyi0NkvhNBQDNx5Qo+CRGip4uVSoVXOtoqc4hyW7X1SPt5Q0RtW 70AvSZRFNc1mPmtyr0XR/+r7MWGZYZSXzzQTivl2gXj5Ls6Bk6ZrgmZTebUybcYyHrg4 I7cnAhImxyNAZ3K8Jc1IRZoJqLLt96Ev8scTpITyWURLqeyfHHjaNGbXQpH8RFQ9l+5t uXhLpXVr3QyipjFnRJYvU9X/3Km+iUi2KAdB9hLGFERVMFwd8pq5kGSMt98wwJCkxXyq NqlA== X-Forwarded-Encrypted: i=1; AJvYcCXvLYFuYNWgqjte2BtGsXanGJ9p414j7HICSlb7yjvaqsYUD69jiyHU1HqP0teyAQaFxc/l9L6Q7ekHEiU=@vger.kernel.org X-Gm-Message-State: AOJu0Yw5PZ7y82BpQIQPkfJuJNLeIGKWum3BpAXzzJp7POJhafHmhgdH 12Bq2UoyB2riak/JTgi/9KfAyP/fzMDXZfo04UzW4eo4LBndJrYfWJ+kbA== X-Gm-Gg: ASbGncugfUIbroG1WPNPcRH0E3HzuvNr/AARueVioQHiCgYiSSeXKURWiECZqfpR8k0 TYRO3bo30dR8UfrBUEWLCBSVXI+2Bhh6gZM/ORu9/dGDWi8s5VZNHz6sXcOEEIWxT0S4NsSUS/d JN5Tb+G3GzIBvVcLpp6ltgrmwtYHeCn/AxuUgW6auWiBbpW5/1PDIS83aXJoy1o6cztwLNHydMQ vQCNGJiTR4lK0rBLpG4t0IHz+XRB6Dt3i3H1Hj/nOpKNgA6KMX+3UxEpb6hAohqbiYV7CLiWpm7 GgzpBmKhzo+a0X6lghKMp5hX0NS6 X-Google-Smtp-Source: AGHT+IEiC67o7UiF+pQM3vda/jEfMXgoG2yq+aAY/sImLPzO09yPTnFHuaMi2gIC/gaSK/TjkI0OBQ== X-Received: by 2002:a17:90b:3a46:b0:2ee:af31:a7b3 with SMTP id 98e67ed59e1d1-2f548ea664fmr7937675a91.7.1736393298447; Wed, 08 Jan 2025 19:28:18 -0800 (PST) Received: from carrot.. (i114-186-237-30.s41.a014.ap.plala.or.jp. [114.186.237.30]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2f55942eed5sm194963a91.27.2025.01.08.19.28.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 08 Jan 2025 19:28:17 -0800 (PST) From: Ryusuke Konishi To: Andrew Morton Cc: linux-nilfs@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 2/6] nilfs2: correct return value kernel-doc descriptions for bmap functions Date: Thu, 9 Jan 2025 12:23:21 +0900 Message-ID: <20250109032846.10147-3-konishi.ryusuke@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250109032846.10147-1-konishi.ryusuke@gmail.com> References: <20250109032846.10147-1-konishi.ryusuke@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Similar to the previous patch to fix the ioctl return value descriptions, this fixes the format of the return value descriptions for bmap (and btree)-related functions, which was causing the kernel-doc script to emit a number of warnings. Signed-off-by: Ryusuke Konishi --- fs/nilfs2/bmap.c | 113 ++++++++++++++++++---------------------------- fs/nilfs2/btree.c | 7 ++- 2 files changed, 46 insertions(+), 74 deletions(-) diff --git a/fs/nilfs2/bmap.c b/fs/nilfs2/bmap.c index c9e8d9a7d820..63516dfac692 100644 --- a/fs/nilfs2/bmap.c +++ b/fs/nilfs2/bmap.c @@ -47,17 +47,13 @@ static int nilfs_bmap_convert_error(struct nilfs_bmap *= bmap, * @ptrp: place to store the value associated to @key * * Description: nilfs_bmap_lookup_at_level() finds a record whose key - * matches @key in the block at @level of the bmap. + * matches @key in the block at @level of the bmap. The record associated + * with @key is stored in the place pointed to by @ptrp. * - * Return Value: On success, 0 is returned and the record associated with = @key - * is stored in the place pointed by @ptrp. On error, one of the following - * negative error codes is returned. - * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-ENOENT - A record associated with @key does not exist. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - A record associated with @key does not exist. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_lookup_at_level(struct nilfs_bmap *bmap, __u64 key, int lev= el, __u64 *ptrp) @@ -138,14 +134,10 @@ static int nilfs_bmap_do_insert(struct nilfs_bmap *bm= ap, __u64 key, __u64 ptr) * Description: nilfs_bmap_insert() inserts the new key-record pair specif= ied * by @key and @rec into @bmap. * - * 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. - * - * %-EEXIST - A record associated with @key already exist. + * Return: 0 on success, or the following negative error code on failure. + * * %-EEXIST - A record associated with @key already exist. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_insert(struct nilfs_bmap *bmap, __u64 key, unsigned long re= c) { @@ -193,14 +185,10 @@ static int nilfs_bmap_do_delete(struct nilfs_bmap *bm= ap, __u64 key) * Description: nilfs_bmap_seek_key() seeks a valid key on @bmap * starting from @start, and stores it to @keyp if found. * - * 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 - No valid entry was found + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - No valid entry was found. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_seek_key(struct nilfs_bmap *bmap, __u64 start, __u64 *keyp) { @@ -236,14 +224,10 @@ int nilfs_bmap_last_key(struct nilfs_bmap *bmap, __u6= 4 *keyp) * Description: nilfs_bmap_delete() deletes the key-record pair specified = by * @key from @bmap. * - * 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 - A record associated with @key does not exist. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - A record associated with @key does not exist. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_delete(struct nilfs_bmap *bmap, __u64 key) { @@ -290,12 +274,9 @@ static int nilfs_bmap_do_truncate(struct nilfs_bmap *b= map, __u64 key) * Description: nilfs_bmap_truncate() removes key-record pairs whose keys = are * greater than or equal to @key from @bmap. * - * 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. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_truncate(struct nilfs_bmap *bmap, __u64 key) { @@ -330,12 +311,9 @@ void nilfs_bmap_clear(struct nilfs_bmap *bmap) * Description: nilfs_bmap_propagate() marks the buffers that directly or * indirectly refer to the block specified by @bh dirty. * - * 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. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_propagate(struct nilfs_bmap *bmap, struct buffer_head *bh) { @@ -362,22 +340,21 @@ void nilfs_bmap_lookup_dirty_buffers(struct nilfs_bma= p *bmap, =20 /** * nilfs_bmap_assign - assign a new block number to a block - * @bmap: bmap - * @bh: pointer to buffer head + * @bmap: bmap + * @bh: place to store a pointer to the buffer head to which a block + * address is assigned (in/out) * @blocknr: block number - * @binfo: block information + * @binfo: block information * * Description: nilfs_bmap_assign() assigns the block number @blocknr to t= he - * buffer specified by @bh. - * - * Return Value: On success, 0 is returned and the buffer head of a newly - * create buffer and the block information associated with the buffer are - * stored in the place pointed by @bh and @binfo, respectively. On error, = one - * of the following negative error codes is returned. - * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. + * buffer specified by @bh. The block information is stored in the memory + * pointed to by @binfo, and the buffer head may be replaced as a block + * address is assigned, in which case a pointer to the new buffer head is + * stored in the memory pointed to by @bh. + * + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_assign(struct nilfs_bmap *bmap, struct buffer_head **bh, @@ -402,12 +379,9 @@ int nilfs_bmap_assign(struct nilfs_bmap *bmap, * Description: nilfs_bmap_mark() marks the block specified by @key and @l= evel * as dirty. * - * 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. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_mark(struct nilfs_bmap *bmap, __u64 key, int level) { @@ -430,7 +404,7 @@ int nilfs_bmap_mark(struct nilfs_bmap *bmap, __u64 key,= int level) * Description: nilfs_test_and_clear() is the atomic operation to test and * clear the dirty state of @bmap. * - * Return Value: 1 is returned if @bmap is dirty, or 0 if clear. + * Return: 1 if @bmap is dirty, or 0 if clear. */ int nilfs_bmap_test_and_clear_dirty(struct nilfs_bmap *bmap) { @@ -490,10 +464,9 @@ static struct lock_class_key nilfs_bmap_mdt_lock_key; * * Description: nilfs_bmap_read() initializes the bmap @bmap. * - * Return Value: On success, 0 is returned. On error, the following negati= ve - * error code is returned. - * - * %-ENOMEM - Insufficient amount of memory available. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (corrupted bmap). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_bmap_read(struct nilfs_bmap *bmap, struct nilfs_inode *raw_inode) { diff --git a/fs/nilfs2/btree.c b/fs/nilfs2/btree.c index ef5061bb56da..9dd131cb2a1c 100644 --- a/fs/nilfs2/btree.c +++ b/fs/nilfs2/btree.c @@ -334,7 +334,7 @@ static int nilfs_btree_node_lookup(const struct nilfs_b= tree_node *node, * @inode: host inode of btree * @blocknr: block number * - * Return Value: If node is broken, 1 is returned. Otherwise, 0 is returne= d. + * Return: 0 if normal, 1 if the node is broken. */ static int nilfs_btree_node_broken(const struct nilfs_btree_node *node, size_t size, struct inode *inode, @@ -366,7 +366,7 @@ static int nilfs_btree_node_broken(const struct nilfs_b= tree_node *node, * @node: btree root node to be examined * @inode: host inode of btree * - * Return Value: If node is broken, 1 is returned. Otherwise, 0 is returne= d. + * Return: 0 if normal, 1 if the root node is broken. */ static int nilfs_btree_root_broken(const struct nilfs_btree_node *node, struct inode *inode) @@ -652,8 +652,7 @@ static int nilfs_btree_do_lookup_last(const struct nilf= s_bmap *btree, * @minlevel: start level * @nextkey: place to store the next valid key * - * Return Value: If a next key was found, 0 is returned. Otherwise, - * -ENOENT is returned. + * Return: 0 if next key found, %-ENOENT if not. */ static int nilfs_btree_get_next_key(const struct nilfs_bmap *btree, const struct nilfs_btree_path *path, --=20 2.43.0 From nobody Sun Feb 8 01:42:09 2026 Received: from mail-pj1-f50.google.com (mail-pj1-f50.google.com [209.85.216.50]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D285318132A; Thu, 9 Jan 2025 03:28:21 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.50 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393303; cv=none; b=YFk/XX6kilNxGWZrfZDdCjvvhFBCM8SehzZcxABrgLD8kg231g1eVdpWhnS6Oxo/OXroK9yf3Uavia74amJf/D0MdEYxCWioLSBTMkY4+qQ16mPfHkpt6GRwrmnfI0c0S71Xf42kGKL05gSa4/IL6swtfkCMGwUaiVEedCsiK+o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393303; c=relaxed/simple; bh=TE4BGf1b3nrjf92JVAMZXm76IUR/co+kngALIO2Vsx0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AGkW0V7eO1d1erxt6KRaHXp5Ba716rDsY3cdBzJrDYDvIYEoSD1pOIva7aT+CRhKR0ElMzlAlTvxcgfEiCiipgK6De0qK8rDo3I7N3Tcupij9EnXIzvsEJo6NgWfgGsI4Z/bLvovdqHhqz5HFWfksNIacl4+n0GzHPcq+JK3lYg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=DElWa6xs; arc=none smtp.client-ip=209.85.216.50 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="DElWa6xs" Received: by mail-pj1-f50.google.com with SMTP id 98e67ed59e1d1-2ee67e9287fso813365a91.0; Wed, 08 Jan 2025 19:28:21 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1736393301; x=1736998101; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=HGL7WGrqr6eMyNJ4UIgqhdrm86SmggbTmX9qpzq+ui0=; b=DElWa6xsEDMfjL2bTLLXZWmpzgSky6dYI5u+kvWOKqyTLSC259xNhAL1BRgYTYYHJJ wF8odarfUh2FXcOI/2UbrywBOiwbMaHiYl8t1Q/7SGNR06AuRlIYK9jv/0K56GC8+79l 5rIOnKlsd7MSFgHrH3uqFS9no36lbjkZ8TyWmFi2sBOuYKMODy6/PvDM4IQel62xIRtA oBZonJbTz49OKEqjaXDyl6tI2yQLK3mmp72fxHJDHc7Hs7nbCJSuwpeEyYUSa7raLWup Sp/FbtYpP/5EH2bbCW7yOBjrRy/nYV2MoxeTJ8wkrS/8h/WxWOxnCQPt03kNbl01Dx17 mmQg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1736393301; x=1736998101; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=HGL7WGrqr6eMyNJ4UIgqhdrm86SmggbTmX9qpzq+ui0=; b=KXDFGiHDFbyPyljolZphC7VQyNURoP9EeFYjhEeoiG3JF0CvQhWsydqNaBrcU3eTgK Ru3xgZZun8UUkFf4SuwXgrqBsFSO1ets18l6cONqKLAiBhyFn6l4r72/YY2b83FD7tnI jUxoziEaHJoIMFXTYTVDNUDTYwlRTCrHk82iHvAI8GipoELbVkajg4ESTfe9kw6Luahm U1qm2ik7vNu1oR37jayX47e708nlxzblyFFLZnscaYShg8hYm0WvPRdszTA1AhzRLheA py1C+h2tebtInwHEPsAhl1hUyAJvUUm7SOdzF9kPN5g9EbzObXoNAeASapJAXeINMdz/ EMXg== X-Forwarded-Encrypted: i=1; AJvYcCV6np+EAJE2S3LZ8QgdiFqFVIVH57xqdF74UbyilaZ4U0dxwbgFBVRAV85zba3oktEwFI1cPbQRkmtq8cE=@vger.kernel.org X-Gm-Message-State: AOJu0YwKoZzsJjEhJSt7mYni74XhmCSS9ZC9Z333F1PBtM3dGLr3c9q9 J24CGilYUB04pmYFWK0j/ym4BGXcz/mn4LCTWTrPM/X6iUUl35p3SnqBGg== X-Gm-Gg: ASbGncuNMrDseNPWtIVXZBOcH7ZAJBAqenv1y5ak29h4fKxnb/RQc2bjUpjVaqsOc8a F0a3AbLGs/ybhaZslpLFmdiKxtI2RoZuGP5ea5vR+v42R+BV488TA/Ja4oKMUiC3MjYQ+XnVU4t H68w5dAwV994nkEux7aqEvI2DK4NsuUK+nAeU/n2XqUiMVcceYwN46ytSybe4VA9Q0yr28ZyJyB wE7IX3kwiYsVlCFB53MmuPIAdd1phGzb77eY9RQNdw2XXK5b57trjQu/3beOoQ42kkQEnDIXRFe CkSH7XNyvptvLtddB6E5xwdjTp4C X-Google-Smtp-Source: AGHT+IGb7NDXfiepNwFcUlOgylATLw3pWG+t3coTuYSYQlijfodVK9bByLsALPLG0+jwBe1wmv7pDg== X-Received: by 2002:a17:90b:4ed0:b0:2ee:6736:8512 with SMTP id 98e67ed59e1d1-2f548eb3229mr9599157a91.12.1736393300866; Wed, 08 Jan 2025 19:28:20 -0800 (PST) Received: from carrot.. (i114-186-237-30.s41.a014.ap.plala.or.jp. [114.186.237.30]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2f55942eed5sm194963a91.27.2025.01.08.19.28.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 08 Jan 2025 19:28:20 -0800 (PST) From: Ryusuke Konishi To: Andrew Morton Cc: linux-nilfs@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 3/6] nilfs2: correct return value kernel-doc descriptions for sufile Date: Thu, 9 Jan 2025 12:23:22 +0900 Message-ID: <20250109032846.10147-4-konishi.ryusuke@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250109032846.10147-1-konishi.ryusuke@gmail.com> References: <20250109032846.10147-1-konishi.ryusuke@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Similar to the previous changes to fix return value descriptions, this fixes the format of the return value descriptions of functions for sufile-related functions, eliminating a dozen warnings emitted by the kernel-doc script. Signed-off-by: Ryusuke Konishi --- fs/nilfs2/sufile.c | 96 ++++++++++++++++------------------------------ fs/nilfs2/sufile.h | 15 +++----- 2 files changed, 38 insertions(+), 73 deletions(-) diff --git a/fs/nilfs2/sufile.c b/fs/nilfs2/sufile.c index d3ecc813d633..92a301487a93 100644 --- a/fs/nilfs2/sufile.c +++ b/fs/nilfs2/sufile.c @@ -155,17 +155,12 @@ unsigned long nilfs_sufile_get_ncleansegs(struct inod= e *sufile) * of successfully modified segments from the head is stored in the * place @ndone points to. * - * Return Value: On success, zero is returned. On error, one of the - * following negative error codes is returned. - * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-ENOENT - Given segment usage is in hole block (may be returned if - * @create is zero) - * - * %-EINVAL - Invalid segment usage number + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - Invalid segment usage number + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - Given segment usage is in hole block (may be returned if + * @create is zero) + * * %-ENOMEM - Insufficient memory available. */ int nilfs_sufile_updatev(struct inode *sufile, __u64 *segnumv, size_t nseg= s, int create, size_t *ndone, @@ -272,10 +267,7 @@ int nilfs_sufile_update(struct inode *sufile, __u64 se= gnum, int create, * @start: minimum segment number of allocatable region (inclusive) * @end: maximum segment number of allocatable region (inclusive) * - * Return Value: On success, 0 is returned. On error, one of the - * following negative error codes is returned. - * - * %-ERANGE - invalid segment region + * Return: 0 on success, or %-ERANGE if segment range is invalid. */ int nilfs_sufile_set_alloc_range(struct inode *sufile, __u64 start, __u64 = end) { @@ -300,17 +292,13 @@ int nilfs_sufile_set_alloc_range(struct inode *sufile= , __u64 start, __u64 end) * @sufile: inode of segment usage file * @segnump: pointer to segment number * - * Description: nilfs_sufile_alloc() allocates a clean segment. - * - * Return Value: On success, 0 is returned and the segment number of the - * allocated segment is stored in the place pointed by @segnump. On error,= one - * of the following negative error codes is returned. - * - * %-EIO - I/O error. + * Description: nilfs_sufile_alloc() allocates a clean segment, and stores + * its segment number in the place pointed to by @segnump. * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-ENOSPC - No clean segment left. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. + * * %-ENOSPC - No clean segment left. */ int nilfs_sufile_alloc(struct inode *sufile, __u64 *segnump) { @@ -610,16 +598,12 @@ int nilfs_sufile_set_segment_usage(struct inode *sufi= le, __u64 segnum, * @sufile: inode of segment usage file * @sustat: pointer to a structure of segment usage statistics * - * Description: nilfs_sufile_get_stat() returns information about segment - * usage. - * - * Return Value: On success, 0 is returned, and segment usage information = is - * stored in the place pointed by @sustat. On error, one of the following - * negative error codes is returned. + * Description: nilfs_sufile_get_stat() retrieves segment usage statistics + * and stores them in the location pointed to by @sustat. * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_sufile_get_stat(struct inode *sufile, struct nilfs_sustat *susta= t) { @@ -683,16 +667,11 @@ void nilfs_sufile_do_set_error(struct inode *sufile, = __u64 segnum, * @start: start segment number (inclusive) * @end: end segment number (inclusive) * - * 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. - * - * %-EINVAL - Invalid number of segments specified - * - * %-EBUSY - Dirty or active segments are present in the range + * Return: 0 on success, or the following negative error code on failure. + * * %-EBUSY - Dirty or active segments are present in the range. + * * %-EINVAL - Invalid number of segments specified. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ static int nilfs_sufile_truncate_range(struct inode *sufile, __u64 start, __u64 end) @@ -787,16 +766,11 @@ static int nilfs_sufile_truncate_range(struct inode *= sufile, * @sufile: inode of segment usage file * @newnsegs: new number of segments * - * 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. - * - * %-ENOSPC - Enough free space is not left for shrinking - * - * %-EBUSY - Dirty or active segments exist in the region to be truncated + * Return: 0 on success, or the following negative error code on failure. + * * %-EBUSY - Dirty or active segments exist in the region to be truncate= d. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. + * * %-ENOSPC - Enough free space is not left for shrinking. */ int nilfs_sufile_resize(struct inode *sufile, __u64 newnsegs) { @@ -939,14 +913,10 @@ ssize_t nilfs_sufile_get_suinfo(struct inode *sufile,= __u64 segnum, void *buf, * segment usage accordingly. Only the fields indicated by the sup_flags * are updated. * - * 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. - * - * %-EINVAL - Invalid values in input (segment number, flags or nblocks) + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - Invalid values in input (segment number, flags or nblocks). + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ ssize_t nilfs_sufile_set_suinfo(struct inode *sufile, void *buf, unsigned int supsz, size_t nsup) @@ -1073,7 +1043,7 @@ ssize_t nilfs_sufile_set_suinfo(struct inode *sufile,= void *buf, * and start+len is rounded down. For each clean segment blkdev_issue_disc= ard * function is invoked. * - * Return Value: On success, 0 is returned or negative error code, otherwi= se. + * Return: 0 on success, or a negative error code on failure. */ int nilfs_sufile_trim_fs(struct inode *sufile, struct fstrim_range *range) { diff --git a/fs/nilfs2/sufile.h b/fs/nilfs2/sufile.h index 8e8a1a5a0402..6b39e8d97ce9 100644 --- a/fs/nilfs2/sufile.h +++ b/fs/nilfs2/sufile.h @@ -95,8 +95,7 @@ static inline int nilfs_sufile_freev(struct inode *sufile= , __u64 *segnumv, * @nsegs: size of @segnumv array * @ndone: place to store the number of cancelled segments * - * Return Value: On success, 0 is returned. On error, a negative error cod= es - * is returned. + * Return: 0 on success, or a negative error code on failure. */ static inline int nilfs_sufile_cancel_freev(struct inode *sufile, __u64 *segnumv, size_t nsegs, @@ -114,14 +113,10 @@ static inline int nilfs_sufile_cancel_freev(struct in= ode *sufile, * Description: nilfs_sufile_set_error() marks the segment specified by * @segnum as erroneous. The error segment will never be used again. * - * 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. - * - * %-EINVAL - Invalid segment usage number. + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - Invalid segment usage number. + * * %-ENOMEM - Insufficient memory available. + * * %-EIO - I/O error (including metadata corruption). */ static inline int nilfs_sufile_set_error(struct inode *sufile, __u64 segnu= m) { --=20 2.43.0 From nobody Sun Feb 8 01:42:09 2026 Received: from mail-pj1-f42.google.com (mail-pj1-f42.google.com [209.85.216.42]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 41CF81898EA; Thu, 9 Jan 2025 03:28:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.42 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393306; cv=none; b=K3MyG13Q7Wvz0T8j7N4Y4kN96QGRPOAxUNwAZidLfrkO+S2Xj16Q0kKHavyf6ZcWsnhAVf6zMJQZfgW4SFWnAIxOintdOVx+ag7QdvncuXoQqR8ld2WW7c7CD84G62MAW6iQLpHKQMbujzJ33x4ty5+9x7dzKBgPmLo25bCcWhc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393306; c=relaxed/simple; bh=V2bDMpH577fvk1ErBDdIJWu6KPtaFnenyKBoXZpaUHA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=qa+nB3Vp1TGTX1l3/G8exdKy9xbBchWx76AvMZ24XBuNq6gLb+zKXBL9D6AL/7Pyuqa5iU9HJz+zYC7rRPKCNkslOvwwTUJeJyJyan51qH1eyYxYlCKFORoj8iog1WVST/EGJKu4sKbz7dQibWj3REgIKZgXBRS48kHD1TfUBGs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=KwdX3EUp; arc=none smtp.client-ip=209.85.216.42 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="KwdX3EUp" Received: by mail-pj1-f42.google.com with SMTP id 98e67ed59e1d1-2ee86a1a92dso672188a91.1; Wed, 08 Jan 2025 19:28:24 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1736393304; x=1736998104; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=3VDl1xVCrvkEU4rkIcrxCMpEj6sIDtXziLLH3X845Do=; b=KwdX3EUpBmkflJOiryP0wpLk09HO40uR4TofB8vi3dd7FagAZTbCKxzunhzoUIBeTo i71Wh0v6eov6MrndUKxTv2D5c34CJOwyK8wTUX5a1UKPoIs4oWThTk03irRColcxFsLb dA5RV4brjbxXnIvHvn385sjXQlEqjtanYmn1Qwvzk7nJfweSxZgOO82Lo1OjU3Ado70S OWJ/EoY2JL6quOn7Bg7pf4q6dHO2ww8Yh6XOaE6p6xjUuAVaEKE8Clgc9ROdZ8iK2HTE 9eKBSIGyY0P3M31LFBVIhHsqcdE3rOML8HEAfKhTP9OBqkMnwG/9S4hL0/zVmc0DVwZH 11HA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1736393304; x=1736998104; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=3VDl1xVCrvkEU4rkIcrxCMpEj6sIDtXziLLH3X845Do=; b=aesbdpyQzO80Kh34FcInGHyvs9KOY+5gTHMvoWMnsTHFYIRZZaBfT0Sq1j0bJe5ulP OjtAn2FSvLcOFPYcXCtzikd/LQ8y1jtES40kocVTzUbzk/tluhd1CcSgyegCcsBCA/kL 5FM275IoZjXlQyIe560psYhnIRzc9J5FCCup71F67hHXbd6q1EBXmvImdKAoW0ckFiBI ueZS/ta/hSs7CCYPjis8lYhZMpxmqIE3sBw/jwtx5D0j4IlVuvXRWrTm7I/dOReXxz7p Ljx+L/sBxY5KAfS2ETicptjemiJ+7xXMr4kT7j2TVE5+yKe41Arvq1uRg1qbJUbn78li ZCBw== X-Forwarded-Encrypted: i=1; AJvYcCVE6wY/8TpbZ8yFfKoF2YviEy5SuTYcTI5oojiBy11tgbN4wXIaS9uqS1pqjYwLMz3c0yAhjAHZGGl+/1Y=@vger.kernel.org X-Gm-Message-State: AOJu0YzuSpNGKALvbPieg71xRCu6FR7WkK+diJcIGebhoqsXrpBWf6P1 CJ0GvtOmGee5usfxB+WquuaP7nWDu8uNBGozo1W2x41V5PtFz3XxRcPHjA== X-Gm-Gg: ASbGncveyExEok0f51fhI1EGFYSFRNo47zfV4mUQjf+mkP36F2c8sV18+3isvMKbzDj F27HXYdf5s0JGLdQH2VJZBB24JlT2k0Ie6kW81dNkV6n0sx/tz6BTPjygQ/b7EaCCBj+MEBHENZ vi2AUedpiTBGv2lU7SW1/sCcjVGrQOiHs6jCM2vIT30BPtv6IKH6IMoj94v+iKNvPjQaBekeIRz 8TYYI0IyiE6qEWWBtoNH4FEzxZCeJa/CJBxQ6vtvqlKqr4WrG2AxoO9xAD4GPmqk3sAWXdcojFP VY+ouWR85YpCOg4ObhNO8AOGTEGL X-Google-Smtp-Source: AGHT+IE1W9vlv5cTDvfKfPE2MmjcO5HX4XHFpMNeB8GE2t8QIGrwsyKSkCgTWqqWj4E5HxK0kqnUxg== X-Received: by 2002:a17:90b:3a0e:b0:2ee:e113:815d with SMTP id 98e67ed59e1d1-2f548e98373mr8364022a91.8.1736393303390; Wed, 08 Jan 2025 19:28:23 -0800 (PST) Received: from carrot.. (i114-186-237-30.s41.a014.ap.plala.or.jp. [114.186.237.30]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2f55942eed5sm194963a91.27.2025.01.08.19.28.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 08 Jan 2025 19:28:22 -0800 (PST) From: Ryusuke Konishi To: Andrew Morton Cc: linux-nilfs@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 4/6] nilfs2: correct return value kernel-doc descriptions for metadata files Date: Thu, 9 Jan 2025 12:23:23 +0900 Message-ID: <20250109032846.10147-5-konishi.ryusuke@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250109032846.10147-1-konishi.ryusuke@gmail.com> References: <20250109032846.10147-1-konishi.ryusuke@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Similar to the previous changes to fix return value descriptions, this fixes the format of the return value descriptions for metadata file functions other than sufile. Signed-off-by: Ryusuke Konishi --- fs/nilfs2/cpfile.c | 47 ++++++++++++++------------------------- fs/nilfs2/dat.c | 37 +++++++++++-------------------- fs/nilfs2/ifile.c | 30 ++++++++++--------------- fs/nilfs2/mdt.c | 55 +++++++++++++++++++--------------------------- 4 files changed, 64 insertions(+), 105 deletions(-) diff --git a/fs/nilfs2/cpfile.c b/fs/nilfs2/cpfile.c index c20207d7a989..6fb9a8743fe2 100644 --- a/fs/nilfs2/cpfile.c +++ b/fs/nilfs2/cpfile.c @@ -191,14 +191,10 @@ static inline int nilfs_cpfile_get_checkpoint_block(s= truct inode *cpfile, * @cnop: place to store the next checkpoint number * @bhp: place to store a pointer to buffer_head struct * - * Return Value: On success, it returns 0. On error, the following negative - * error code is returned. - * - * %-ENOMEM - Insufficient memory available. - * - * %-EIO - I/O error - * - * %-ENOENT - no block exists in the range. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - no block exists in the range. + * * %-ENOMEM - Insufficient memory available. */ static int nilfs_cpfile_find_checkpoint_block(struct inode *cpfile, __u64 start_cno, __u64 end_cno, @@ -447,14 +443,10 @@ int nilfs_cpfile_finalize_checkpoint(struct inode *cp= file, __u64 cno, * the period from @start to @end, excluding @end itself. The checkpoints * which have been already deleted are ignored. * - * 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. - * - * %-EINVAL - invalid checkpoints. + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - Invalid checkpoints. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_cpfile_delete_checkpoints(struct inode *cpfile, __u64 start, @@ -1058,14 +1050,10 @@ int nilfs_cpfile_is_snapshot(struct inode *cpfile, = __u64 cno) * Description: nilfs_change_cpmode() changes the mode of the checkpoint * specified by @cno. The mode @mode is NILFS_CHECKPOINT or NILFS_SNAPSHOT. * - * 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 - No such checkpoint. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - No such checkpoint. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_cpfile_change_cpmode(struct inode *cpfile, __u64 cno, int mode) { @@ -1097,14 +1085,11 @@ int nilfs_cpfile_change_cpmode(struct inode *cpfile= , __u64 cno, int mode) * @cpstat: pointer to a structure of checkpoint statistics * * Description: nilfs_cpfile_get_stat() returns information about checkpoi= nts. + * The checkpoint statistics are stored in the location pointed to by @cps= tat. * - * Return Value: On success, 0 is returned, and checkpoints information is - * stored in the place pointed by @cpstat. On error, one of the following - * negative error codes is returned. - * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_cpfile_get_stat(struct inode *cpfile, struct nilfs_cpstat *cpsta= t) { diff --git a/fs/nilfs2/dat.c b/fs/nilfs2/dat.c index e220dcb08aa6..fc5dd28e7baa 100644 --- a/fs/nilfs2/dat.c +++ b/fs/nilfs2/dat.c @@ -302,14 +302,10 @@ int nilfs_dat_mark_dirty(struct inode *dat, __u64 vbl= ocknr) * Description: nilfs_dat_freev() frees the virtual block numbers specifie= d by * @vblocknrs and @nitems. * - * 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 - The virtual block number have not been allocated. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - The virtual block number have not been allocated. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_dat_freev(struct inode *dat, __u64 *vblocknrs, size_t nitems) { @@ -325,12 +321,9 @@ int nilfs_dat_freev(struct inode *dat, __u64 *vblocknr= s, size_t nitems) * Description: nilfs_dat_move() changes the block number associated with * @vblocknr to @blocknr. * - * 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. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. */ int nilfs_dat_move(struct inode *dat, __u64 vblocknr, sector_t blocknr) { @@ -390,17 +383,13 @@ int nilfs_dat_move(struct inode *dat, __u64 vblocknr,= sector_t blocknr) * @blocknrp: pointer to a block number * * Description: nilfs_dat_translate() maps the virtual block number @vbloc= knr - * to the corresponding block number. - * - * Return Value: On success, 0 is returned and the block number associated - * with @vblocknr is stored in the place pointed by @blocknrp. On error, o= ne - * of the following negative error codes is returned. - * - * %-EIO - I/O error. + * to the corresponding block number. The block number associated with + * @vblocknr is stored in the place pointed to by @blocknrp. * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-ENOENT - A block number associated with @vblocknr does not exist. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - A block number associated with @vblocknr does not exist. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_dat_translate(struct inode *dat, __u64 vblocknr, sector_t *block= nrp) { diff --git a/fs/nilfs2/ifile.c b/fs/nilfs2/ifile.c index e7339eb3c08a..cd38ba05a655 100644 --- a/fs/nilfs2/ifile.c +++ b/fs/nilfs2/ifile.c @@ -38,17 +38,15 @@ static inline struct nilfs_ifile_info *NILFS_IFILE_I(st= ruct inode *ifile) * @out_ino: pointer to a variable to store inode number * @out_bh: buffer_head contains newly allocated disk inode * - * Return Value: On success, 0 is returned and the newly allocated inode - * number is stored in the place pointed by @ino, and buffer_head pointer - * that contains newly allocated disk inode structure is stored in the - * place pointed by @out_bh - * On error, one of the following negative error codes is returned. + * nilfs_ifile_create_inode() allocates a new inode in the ifile metadata + * file and stores the inode number in the variable pointed to by @out_ino, + * as well as storing the ifile's buffer with the disk inode in the locati= on + * pointed to by @out_bh. * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-ENOSPC - No inode left. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. + * * %-ENOSPC - No inode left. */ int nilfs_ifile_create_inode(struct inode *ifile, ino_t *out_ino, struct buffer_head **out_bh) @@ -83,14 +81,10 @@ int nilfs_ifile_create_inode(struct inode *ifile, ino_t= *out_ino, * @ifile: ifile inode * @ino: inode number * - * 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 - The inode number @ino have not been allocated. + * Return: 0 on success, or the following negative error code on failure. + * * %-ENOMEM - Insufficient memory available. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - Inode number unallocated. */ int nilfs_ifile_delete_inode(struct inode *ifile, ino_t ino) { diff --git a/fs/nilfs2/mdt.c b/fs/nilfs2/mdt.c index 965b5ad1c0df..06bc534c7dbe 100644 --- a/fs/nilfs2/mdt.c +++ b/fs/nilfs2/mdt.c @@ -226,20 +226,20 @@ static int nilfs_mdt_read_block(struct inode *inode, = unsigned long block, * @out_bh: output of a pointer to the buffer_head * * nilfs_mdt_get_block() looks up the specified buffer and tries to create - * a new buffer if @create is not zero. On success, the returned buffer is - * assured to be either existing or formatted using a buffer lock on succe= ss. - * @out_bh is substituted only when zero is returned. + * a new buffer if @create is not zero. If (and only if) this function + * succeeds, it stores a pointer to the retrieved buffer head in the locat= ion + * pointed to by @out_bh. * - * Return Value: On success, it returns 0. On error, the following negative - * error code is returned. + * The retrieved buffer may be either an existing one or a newly allocated= one. + * For a newly created buffer, if the callback function argument @init_blo= ck + * is non-NULL, the callback will be called with the buffer locked to form= at + * the block. * - * %-ENOMEM - Insufficient memory available. - * - * %-EIO - I/O error - * - * %-ENOENT - the specified block does not exist (hole block) - * - * %-EROFS - Read only filesystem (for create mode) + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - The specified block does not exist (hole block). + * * %-ENOMEM - Insufficient memory available. + * * %-EROFS - Read only filesystem (for create mode). */ int nilfs_mdt_get_block(struct inode *inode, unsigned long blkoff, int cre= ate, void (*init_block)(struct inode *, @@ -275,14 +275,10 @@ int nilfs_mdt_get_block(struct inode *inode, unsigned= long blkoff, int create, * @out_bh, and block offset to @blkoff, respectively. @out_bh and * @blkoff are substituted only when zero is returned. * - * Return Value: On success, it returns 0. On error, the following negative - * error code is returned. - * - * %-ENOMEM - Insufficient memory available. - * - * %-EIO - I/O error - * - * %-ENOENT - no block was found in the range + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - No block was found in the range. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_mdt_find_block(struct inode *inode, unsigned long start, unsigned long end, unsigned long *blkoff, @@ -321,12 +317,10 @@ int nilfs_mdt_find_block(struct inode *inode, unsigne= d long start, * @inode: inode of the meta data file * @block: block offset * - * Return Value: On success, zero is returned. - * On error, one of the following negative error code is returned. - * - * %-ENOMEM - Insufficient memory available. - * - * %-EIO - I/O error + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - Non-existent block. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_mdt_delete_block(struct inode *inode, unsigned long block) { @@ -349,12 +343,9 @@ int nilfs_mdt_delete_block(struct inode *inode, unsign= ed long block) * nilfs_mdt_forget_block() clears a dirty flag of the specified buffer, a= nd * tries to release the page including the buffer from a page cache. * - * Return Value: On success, 0 is returned. On error, one of the following - * negative error code is returned. - * - * %-EBUSY - page has an active buffer. - * - * %-ENOENT - page cache has no page addressed by the offset. + * Return: 0 on success, or the following negative error code on failure. + * * %-EBUSY - Page has an active buffer. + * * %-ENOENT - Page cache has no page addressed by the offset. */ int nilfs_mdt_forget_block(struct inode *inode, unsigned long block) { --=20 2.43.0 From nobody Sun Feb 8 01:42:09 2026 Received: from mail-pj1-f45.google.com (mail-pj1-f45.google.com [209.85.216.45]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A949718C039; Thu, 9 Jan 2025 03:28:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.45 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393308; cv=none; b=Ex84AZmWc3wUySBvpu5geY9+JNM2j+KM8MNM8aJytkMYM2i0ObZENd9eNsr4teeaZK9QXEuc/oBfF5ns6gH634dJI0jH+XhoMWXL9C0uxMww14CQcH934S7/SZxFYLuNgFd3O8mHcrU0hnvpL2q2DZjibWTHLPlnh9d8hS4v+dE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393308; c=relaxed/simple; bh=6dQxUNzSuilcgy9/j+F5ThC+2Fq5KDS+c6hIWRvlcaU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=KJc45jxWHPuSsz1U0IybMwOFk8HGG+siTcAQ3pP7g68W/u78NDuqJILqT5K1C5zcZkvfF16p+a88qGK0z18CA6jvS/o4axAYsULx3Eji//9WQZR5TCJ2iTo/+nIntV9Khh3z0vX2n2RCPIC0/Ipcz8QUcYaVcEUd349rOkAOUUY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=VqAKP5zD; arc=none smtp.client-ip=209.85.216.45 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="VqAKP5zD" Received: by mail-pj1-f45.google.com with SMTP id 98e67ed59e1d1-2ee74291415so646687a91.3; Wed, 08 Jan 2025 19:28:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1736393306; x=1736998106; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=Xj+jkXlg8GgaeC3zx83MHGcdKZ6KPzSuLeeYhzZqUdg=; b=VqAKP5zDqWYsp1TfWH5UqRFZ7XXTQ8z/m2xAYk4Te8QK6cywS7QglMeO7uSIDt+sZw NZfSWDPyJlnG+8AXmlKBfraQcVfa+w0WfKiA7ORZhI52dOYLVcpA+ksgOSguws7bdet+ SZCz22+BydPqE36Pkvobon+sjPWqstwzwCwoUi2/XTsTeM0SiUrQjZ+R9BXR9f7k6NPh 1IqRgX26EPAk1rl78heN+MwU/mrqJUiH3A6VQ3ewc7+gjOGadf2PZK4X8dkO6NONIYup aK8hvH8ui5ItCF5KFqOL/q+YNuIO0r4L851/prT4B+vGp67HhveN0DwN/TyLNmVdTnQm Nskg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1736393306; x=1736998106; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Xj+jkXlg8GgaeC3zx83MHGcdKZ6KPzSuLeeYhzZqUdg=; b=biW0uW2pj6r3ZJDJwtNRow4cjNdhDNwpLB4d928YO9yygG9Sq2VW533L3PPk+D6ajq +xDnNCHS1HkINxE5h14gL6hJT/mNT/USgBWifV3He5ptB1GjT0tEHPgbtvkdgkVFFuj8 nSkLv0W1V0xUZP5Qm4Bw88uYxNkLGZDETIGTLcOkhniGiv5g9mFOlp+43hTaGme/G8Z7 wOXYQ8izaCdaDQBv7U2U8ADiK0JG+ufKix0rfmvwEhhgQqisa79OiWSs1h6RFQEyDFCM BUF1PxjZNyuVdRecCO+WMuuFmWqhG1mzsFSdwUuvuvOsZtGjv3BNi2iwB07Dir+oghRL NxlA== X-Forwarded-Encrypted: i=1; AJvYcCUSkZ8ZZXQNljUcmv4gZa6QO13qm0xwWFtltk750dk9agYO5LhAMLEG5REHApk9+tDFQHmcD+n/j15gR4A=@vger.kernel.org X-Gm-Message-State: AOJu0YxDgN/BGhD9wyYjqtO26jdnAyNoVU7PVgMMCkB21iaRXJNb0XKA fB+fVSKkJiJy8DPauK0znGxMAN8R4Bp6XornRW0kD5Nuv5nUNNTP7Hj/eQ== X-Gm-Gg: ASbGncuQAjv/E23fB9PWtSOyHag6kwzROSh1mU8UBgInGfi2Sy+CwgwOFHjRCSQumBh vU5+uERb04sPtW6ArnoCGfWVeoMWuAhMxHrjt0B/kcknlYf3sWnqUNJ422jlCNrB5q1DM8eicce L0aVjDCIWOZup1XeS+l4Www7oOIlPVK1OXFK7Q7EpSfcCq2oEJ+FP8YdR6uEuybPfDxvra0ai1L 4a7eIUGyPHBMU13cZES2sieXDDU/8gOGMa111MmHS40LN4xogzBcOhtSll2LP9g/m9qvi6dVXJ+ rROxLIJcc0F8Zs2zvbTg/3/N8N0G X-Google-Smtp-Source: AGHT+IHbtPG3Yv1BGo9jnmDccwoQ6AaXae4yK3VkCe6/BnNaTuPLhLCNm9RYv+hvZC5phKMz4UyAYw== X-Received: by 2002:a17:90a:c2c7:b0:2ee:ba84:5cac with SMTP id 98e67ed59e1d1-2f548ea5a01mr7956485a91.7.1736393305802; Wed, 08 Jan 2025 19:28:25 -0800 (PST) Received: from carrot.. (i114-186-237-30.s41.a014.ap.plala.or.jp. [114.186.237.30]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2f55942eed5sm194963a91.27.2025.01.08.19.28.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 08 Jan 2025 19:28:25 -0800 (PST) From: Ryusuke Konishi To: Andrew Morton Cc: linux-nilfs@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 5/6] nilfs2: correct return value kernel-doc descriptions for the rest Date: Thu, 9 Jan 2025 12:23:24 +0900 Message-ID: <20250109032846.10147-6-konishi.ryusuke@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250109032846.10147-1-konishi.ryusuke@gmail.com> References: <20250109032846.10147-1-konishi.ryusuke@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Similar to the previous changes to fix return value descriptions, this fixes the format of the return value descriptions of functions for the rest. Signed-off-by: Ryusuke Konishi --- fs/nilfs2/gcinode.c | 22 ++++++++------------- fs/nilfs2/inode.c | 12 +++--------- fs/nilfs2/recovery.c | 30 ++++++++++------------------- fs/nilfs2/segbuf.c | 12 ++---------- fs/nilfs2/segment.c | 45 +++++++++++++++---------------------------- fs/nilfs2/the_nilfs.c | 12 +++++------- 6 files changed, 43 insertions(+), 90 deletions(-) diff --git a/fs/nilfs2/gcinode.c b/fs/nilfs2/gcinode.c index 2dbb15767df1..639998099824 100644 --- a/fs/nilfs2/gcinode.c +++ b/fs/nilfs2/gcinode.c @@ -46,14 +46,10 @@ * specified by @pbn to the GC pagecache with the key @blkoff. * This function sets @vbn (@pbn if @vbn is zero) in b_blocknr of the buff= er. * - * Return Value: On success, 0 is returned. On Error, one of the following - * negative error code is returned. - * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. - * - * %-ENOENT - The block specified with @pbn does not exist. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - The block specified with @pbn does not exist. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_gccache_submit_read_data(struct inode *inode, sector_t blkoff, sector_t pbn, __u64 vbn, @@ -114,12 +110,10 @@ int nilfs_gccache_submit_read_data(struct inode *inod= e, sector_t blkoff, * specified by @vbn to the GC pagecache. @pbn can be supplied by the * caller to avoid translation of the disk block address. * - * Return Value: On success, 0 is returned. On Error, one of the following - * negative error code is returned. - * - * %-EIO - I/O error. - * - * %-ENOMEM - Insufficient amount of memory available. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - Invalid virtual block address. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_gccache_submit_read_node(struct inode *inode, sector_t pbn, __u64 vbn, struct buffer_head **out_bh) diff --git a/fs/nilfs2/inode.c b/fs/nilfs2/inode.c index 23f3a75edd50..228bfffa5d22 100644 --- a/fs/nilfs2/inode.c +++ b/fs/nilfs2/inode.c @@ -598,10 +598,7 @@ struct inode *nilfs_iget_for_gc(struct super_block *sb= , unsigned long ino, * or does nothing if the inode already has it. This function allocates * an additional inode to maintain page cache of B-tree nodes one-on-one. * - * Return Value: On success, 0 is returned. On errors, one of the following - * negative error code is returned. - * - * %-ENOMEM - Insufficient memory available. + * Return: 0 on success, or %-ENOMEM if memory is insufficient. */ int nilfs_attach_btree_node_cache(struct inode *inode) { @@ -660,11 +657,8 @@ void nilfs_detach_btree_node_cache(struct inode *inode) * in one inode and the one for b-tree node pages is set up in the * other inode, which is attached to the former inode. * - * Return Value: On success, a pointer to the inode for data pages is - * returned. On errors, one of the following negative error code is return= ed - * in a pointer type. - * - * %-ENOMEM - Insufficient memory available. + * Return: a pointer to the inode for data pages on success, or %-ENOMEM + * if memory is insufficient. */ struct inode *nilfs_iget_for_shadow(struct inode *inode) { diff --git a/fs/nilfs2/recovery.c b/fs/nilfs2/recovery.c index e43405bf521e..bb708e6eb42a 100644 --- a/fs/nilfs2/recovery.c +++ b/fs/nilfs2/recovery.c @@ -754,18 +754,12 @@ static void nilfs_abort_roll_forward(struct the_nilfs= *nilfs) * @sb: super block instance * @ri: pointer to a nilfs_recovery_info struct to store search results. * - * Return Value: On success, 0 is returned. On error, one of the following - * negative error code is returned. - * - * %-EINVAL - Inconsistent filesystem state. - * - * %-EIO - I/O error - * - * %-ENOSPC - No space left on device (only in a panic state). - * - * %-ERESTARTSYS - Interrupted. - * - * %-ENOMEM - Insufficient memory available. + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - Inconsistent filesystem state. + * * %-EIO - I/O error. + * * %-ENOMEM - Insufficient memory available. + * * %-ENOSPC - No space left on device (only in a panic state). + * * %-ERESTARTSYS - Interrupted. */ int nilfs_salvage_orphan_logs(struct the_nilfs *nilfs, struct super_block *sb, @@ -830,14 +824,10 @@ int nilfs_salvage_orphan_logs(struct the_nilfs *nilfs, * segment pointed by the superblock. It sets up struct the_nilfs through * this search. It fills nilfs_recovery_info (ri) required for recovery. * - * Return Value: On success, 0 is returned. On error, one of the following - * negative error code is returned. - * - * %-EINVAL - No valid segment found - * - * %-EIO - I/O error - * - * %-ENOMEM - Insufficient memory available. + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - No valid segment found. + * * %-EIO - I/O error. + * * %-ENOMEM - Insufficient memory available. */ int nilfs_search_super_root(struct the_nilfs *nilfs, struct nilfs_recovery_info *ri) diff --git a/fs/nilfs2/segbuf.c b/fs/nilfs2/segbuf.c index e08cab03366b..a8bdf3d318ea 100644 --- a/fs/nilfs2/segbuf.c +++ b/fs/nilfs2/segbuf.c @@ -406,12 +406,7 @@ static int nilfs_segbuf_submit_bh(struct nilfs_segment= _buffer *segbuf, * @segbuf: buffer storing a log to be written * @nilfs: nilfs object * - * Return Value: On Success, 0 is returned. On Error, one of the following - * negative error code is returned. - * - * %-EIO - I/O error - * - * %-ENOMEM - Insufficient memory available. + * Return: Always 0. */ static int nilfs_segbuf_write(struct nilfs_segment_buffer *segbuf, struct the_nilfs *nilfs) @@ -452,10 +447,7 @@ static int nilfs_segbuf_write(struct nilfs_segment_buf= fer *segbuf, * nilfs_segbuf_wait - wait for completion of requested BIOs * @segbuf: segment buffer * - * Return Value: On Success, 0 is returned. On Error, one of the following - * negative error code is returned. - * - * %-EIO - I/O error + * Return: 0 on success, or %-EIO if I/O error is detected. */ static int nilfs_segbuf_wait(struct nilfs_segment_buffer *segbuf) { diff --git a/fs/nilfs2/segment.c b/fs/nilfs2/segment.c index 58a598b548fa..0eef8d1d88e6 100644 --- a/fs/nilfs2/segment.c +++ b/fs/nilfs2/segment.c @@ -191,12 +191,9 @@ static int nilfs_prepare_segment_lock(struct super_blo= ck *sb, * When @vacancy_check flag is set, this function will check the amount of * free space, and will wait for the GC to reclaim disk space if low capac= ity. * - * Return Value: On success, 0 is returned. On error, one of the following - * negative error code is returned. - * - * %-ENOMEM - Insufficient memory available. - * - * %-ENOSPC - No space left on device + * Return: 0 on success, or the following negative error code on failure. + * * %-ENOMEM - Insufficient memory available. + * * %-ENOSPC - No space left on device (if checking free space). */ int nilfs_transaction_begin(struct super_block *sb, struct nilfs_transaction_info *ti, @@ -2314,18 +2311,12 @@ static void nilfs_segctor_wakeup(struct nilfs_sc_in= fo *sci, int err, bool force) * nilfs_construct_segment - construct a logical segment * @sb: super block * - * Return Value: On success, 0 is returned. 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. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. + * * %-ENOSPC - No space left on device (only in a panic state). + * * %-ERESTARTSYS - Interrupted. + * * %-EROFS - Read only filesystem. */ int nilfs_construct_segment(struct super_block *sb) { @@ -2349,18 +2340,12 @@ int nilfs_construct_segment(struct super_block *sb) * @start: start byte offset * @end: end byte offset (inclusive) * - * Return Value: On success, 0 is returned. 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. + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. + * * %-ENOSPC - No space left on device (only in a panic state). + * * %-ERESTARTSYS - Interrupted. + * * %-EROFS - Read only filesystem. */ int nilfs_construct_dsync_segment(struct super_block *sb, struct inode *in= ode, loff_t start, loff_t end) diff --git a/fs/nilfs2/the_nilfs.c b/fs/nilfs2/the_nilfs.c index ac03fd3c330c..1bcaf85506d3 100644 --- a/fs/nilfs2/the_nilfs.c +++ b/fs/nilfs2/the_nilfs.c @@ -49,8 +49,8 @@ void nilfs_set_last_segment(struct the_nilfs *nilfs, * alloc_nilfs - allocate a nilfs object * @sb: super block instance * - * Return Value: On success, pointer to the_nilfs is returned. - * On error, NULL is returned. + * Return: a pointer to the allocated nilfs object on success, or NULL on + * failure. */ struct the_nilfs *alloc_nilfs(struct super_block *sb) { @@ -200,8 +200,7 @@ static int nilfs_store_log_cursor(struct the_nilfs *nil= fs, * exponent information written in @sbp and stores it in @blocksize, * or aborts with an error message if it's too large. * - * Return Value: On success, 0 is returned. If the block size is too - * large, -EINVAL is returned. + * Return: 0 on success, or %-EINVAL if the block size is too large. */ static int nilfs_get_blocksize(struct super_block *sb, struct nilfs_super_block *sbp, int *blocksize) @@ -538,7 +537,7 @@ static int nilfs_valid_sb(struct nilfs_super_block *sbp) * area, or if the parameters themselves are not normal, it is * determined to be invalid. * - * Return Value: true if invalid, false if valid. + * Return: true if invalid, false if valid. */ static bool nilfs_sb2_bad_offset(struct nilfs_super_block *sbp, u64 offset) { @@ -684,8 +683,7 @@ static int nilfs_load_super_block(struct the_nilfs *nil= fs, * reading the super block, getting disk layout information, initializing * shared fields in the_nilfs). * - * Return Value: On success, 0 is returned. On error, a negative error - * code is returned. + * Return: 0 on success, or a negative error code on failure. */ int init_nilfs(struct the_nilfs *nilfs, struct super_block *sb) { --=20 2.43.0 From nobody Sun Feb 8 01:42:09 2026 Received: from mail-pj1-f50.google.com (mail-pj1-f50.google.com [209.85.216.50]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 40CD5192D66; Thu, 9 Jan 2025 03:28:30 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.50 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393312; cv=none; b=pcgD5tDFP/cjbbqq4uJnurnocKGCH2zQqknBiBF+AKk/kKF5ZILWocVWc2Cf7VaGNe4jqOUeEQ7YX6sV59mj8B+lLXFXjUUoDy3Tx3RF3DYcrGvPkK2U3ymYw3ueaC41rykXLRaPBQ9ECs/++rogX95Kx/tW1XMfDvXy3Baghh0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736393312; c=relaxed/simple; bh=Zu5IzYd+q5hJ+XCPB06Zk/taGjIZopTl5d20TVVOL80=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=m9bOOzqkdMkZL80YgoqebKtJe9Jouqd/Y2TImz1EuVJbNlTReYQiiX4ZDjmBof4TEoMYsFAlDAY1c8HUsj4BN89QHBJvXO1cDNLprPrA6vLs6odgKe3VHyVwr3WVRTx/Rx4o/rFq/4lvC9Z4qk+ZG/Bm5koOEMZ1aZWhPoXgFgo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=LBah55uG; arc=none smtp.client-ip=209.85.216.50 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="LBah55uG" Received: by mail-pj1-f50.google.com with SMTP id 98e67ed59e1d1-2f43da61ba9so611151a91.2; Wed, 08 Jan 2025 19:28:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1736393309; x=1736998109; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=l9Iw8PLZcaFAbjxT5K8tzy429MYmcNWW3sXymEMkZHI=; b=LBah55uGmh4LLvKMYHoFxN703SeyrsfbEtnCzgp9dRGVrZmZsV5FALGAe+Zn77S+UU u/Lv/TmG4oMEzg0tVsemsOjvr4+WYXnNdNE8iD1fYxfiZ5i9RSprlpE40dMVzxv+I4aE yw7dwYVj9YfT+/9d9Rt6e8pD0goitN298L3RV1PPkpKUqGkW/iQy5fKoWovLEO9z4NSj qKrRx0Q3grtSPgYV/nRg6Oxgq63U32akiF6jJ5mzyL8eJ3E02ob533EzzXW4y3e9y2gC LCnzSxwWUmFJgB8bCJ52jRmQaopdn+weEZEacFseAST2YwL3Tpb/2TeKWD5hlIVhTIq0 PgOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1736393309; x=1736998109; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=l9Iw8PLZcaFAbjxT5K8tzy429MYmcNWW3sXymEMkZHI=; b=ZJya2Hwr6mbRQcKXYaCvKdZ0z7H9zJU+Wo9ENDEWIZTHJ+E1coZL76cZeml4j/1385 z119nFO6ItVudMEYunDgmDFQTkMh3S0rUVugm1IThBSn7SKr89frc66etcgg/uCC/bOs s7s0FEVub5Uo6T490EfPWAe/fFwipNYjNhDgktWVZH1HVVjOeb02Tf6GBGr7FyKNOX3n M8cuF4y6pelbMIG98g177l/3DUdKw62vqN4i6AN1ZacPXimXF5MtjkQq76pM/lZY10C0 Ra1sZaNvaGAaRbZgi5JIOd0FeX6HOLD/KZ8nXzO9gdbDbPZAXB60CTrWRHNegZWpArwy TPFA== X-Forwarded-Encrypted: i=1; AJvYcCVlTNlVAwD7CG82iHYu+rGk+dCr7CZPKKSuNppyQTxSZX5Nf/bq0q4c6cY/Zd/aOx2S/y25fldLIhRF2AI=@vger.kernel.org X-Gm-Message-State: AOJu0YywosZx63YuK6dCORoFp16FaGX1MFyT7ArVDEnsPm4ZOVZ+GgPc 8dXO0HPhnQ7WHBTBlxcSjkoPMr7wMGk3U8izk+kqp9Z9nFacVgUzAdm+mA== X-Gm-Gg: ASbGncvnzqzaagBE785C0gxFp4KFQqQEskTBCU9Q6hT27nGWxaVRXz9WDdMc4srH+iN Y0XGvKkQP1l2pl/TuqkHH3Ss7VRg4Y1eOjsERhBDbLfMDMPCb055j9WeBxGke6e1myVDHKjj/Pt Vgrg0HZubYeVJvzLH1mvHiOv95hz5jf+YY6yo8/vpaeCV/Ez1kL/TVIv9mmRY8Q7QWu67vzYx/U azsxIeeIzVAMlKqX7XaBh4bO1zSwgLBhTYYkfGU7EXxcduGQ6T0dh6s2DnfDylOksp0H9WBihYk 0neOz+hMZdHhbVwZeHuB54uyqSXy X-Google-Smtp-Source: AGHT+IHVJTz3CXoPb0zMEEus6RGirStG5SxJ3qiLB2FKhGHr0YNe3T6JTycSze1sK7fjRXleQH7hLQ== X-Received: by 2002:a17:90b:2f0b:b0:2ee:ab29:1a65 with SMTP id 98e67ed59e1d1-2f548f103f4mr7385232a91.4.1736393308834; Wed, 08 Jan 2025 19:28:28 -0800 (PST) Received: from carrot.. (i114-186-237-30.s41.a014.ap.plala.or.jp. [114.186.237.30]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2f55942eed5sm194963a91.27.2025.01.08.19.28.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 08 Jan 2025 19:28:27 -0800 (PST) From: Ryusuke Konishi To: Andrew Morton Cc: linux-nilfs@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 6/6] nilfs2: add missing return value kernel-doc descriptions Date: Thu, 9 Jan 2025 12:23:25 +0900 Message-ID: <20250109032846.10147-7-konishi.ryusuke@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250109032846.10147-1-konishi.ryusuke@gmail.com> References: <20250109032846.10147-1-konishi.ryusuke@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" There are a number of kernel-doc comments for functions that are missing return values, which also causes a number of warnings when the kernel-doc script is run with the "-Wall" option. Fix this issue by adding proper return value descriptions, and improve code maintainability. Signed-off-by: Ryusuke Konishi --- fs/nilfs2/alloc.c | 64 +++++++++++++++++++++++++++++++++++++++++-- fs/nilfs2/alloc.h | 2 ++ fs/nilfs2/cpfile.c | 2 ++ fs/nilfs2/dat.c | 2 ++ fs/nilfs2/ifile.c | 2 ++ fs/nilfs2/inode.c | 4 +++ fs/nilfs2/mdt.c | 4 +++ fs/nilfs2/page.c | 8 +++--- fs/nilfs2/recovery.c | 27 ++++++++++++++++++ fs/nilfs2/segment.c | 8 ++++++ fs/nilfs2/sufile.c | 8 ++++++ fs/nilfs2/sufile.h | 6 ++++ fs/nilfs2/super.c | 10 ++++++- fs/nilfs2/the_nilfs.c | 13 +++++++++ 14 files changed, 153 insertions(+), 7 deletions(-) diff --git a/fs/nilfs2/alloc.c b/fs/nilfs2/alloc.c index ba3e1f591f36..b57fc1628711 100644 --- a/fs/nilfs2/alloc.c +++ b/fs/nilfs2/alloc.c @@ -21,6 +21,8 @@ * nilfs_palloc_groups_per_desc_block - get the number of groups that a gr= oup * descriptor block can maintain * @inode: inode of metadata file using this allocator + * + * Return: Number of groups that a group descriptor block can maintain. */ static inline unsigned long nilfs_palloc_groups_per_desc_block(const struct inode *inode) @@ -32,6 +34,8 @@ nilfs_palloc_groups_per_desc_block(const struct inode *in= ode) /** * nilfs_palloc_groups_count - get maximum number of groups * @inode: inode of metadata file using this allocator + * + * Return: Maximum number of groups. */ static inline unsigned long nilfs_palloc_groups_count(const struct inode *inode) @@ -43,6 +47,8 @@ nilfs_palloc_groups_count(const struct inode *inode) * nilfs_palloc_init_blockgroup - initialize private variables for allocat= or * @inode: inode of metadata file using this allocator * @entry_size: size of the persistent object + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_palloc_init_blockgroup(struct inode *inode, unsigned int entry_s= ize) { @@ -78,6 +84,9 @@ int nilfs_palloc_init_blockgroup(struct inode *inode, uns= igned int entry_size) * @inode: inode of metadata file using this allocator * @nr: serial number of the entry (e.g. inode number) * @offset: pointer to store offset number in the group + * + * Return: Number of the group that contains the entry with the index + * specified by @nr. */ static unsigned long nilfs_palloc_group(const struct inode *inode, __u64 n= r, unsigned long *offset) @@ -93,8 +102,8 @@ static unsigned long nilfs_palloc_group(const struct ino= de *inode, __u64 nr, * @inode: inode of metadata file using this allocator * @group: group number * - * nilfs_palloc_desc_blkoff() returns block offset of the descriptor - * block which contains a descriptor of the specified group. + * Return: Index number in the metadata file of the descriptor block of + * the group specified by @group. */ static unsigned long nilfs_palloc_desc_blkoff(const struct inode *inode, unsigned long group) @@ -111,6 +120,9 @@ nilfs_palloc_desc_blkoff(const struct inode *inode, uns= igned long group) * * nilfs_palloc_bitmap_blkoff() returns block offset of the bitmap * block used to allocate/deallocate entries in the specified group. + * + * Return: Index number in the metadata file of the bitmap block of + * the group specified by @group. */ static unsigned long nilfs_palloc_bitmap_blkoff(const struct inode *inode, unsigned long group) @@ -125,6 +137,8 @@ nilfs_palloc_bitmap_blkoff(const struct inode *inode, u= nsigned long group) * nilfs_palloc_group_desc_nfrees - get the number of free entries in a gr= oup * @desc: pointer to descriptor structure for the group * @lock: spin lock protecting @desc + * + * Return: Number of free entries written in the group descriptor @desc. */ static unsigned long nilfs_palloc_group_desc_nfrees(const struct nilfs_palloc_group_desc *desc, @@ -143,6 +157,9 @@ nilfs_palloc_group_desc_nfrees(const struct nilfs_pallo= c_group_desc *desc, * @desc: pointer to descriptor structure for the group * @lock: spin lock protecting @desc * @n: delta to be added + * + * Return: Number of free entries after adjusting the group descriptor + * @desc. */ static u32 nilfs_palloc_group_desc_add_entries(struct nilfs_palloc_group_desc *desc, @@ -161,6 +178,9 @@ nilfs_palloc_group_desc_add_entries(struct nilfs_palloc= _group_desc *desc, * nilfs_palloc_entry_blkoff - get block offset of an entry block * @inode: inode of metadata file using this allocator * @nr: serial number of the entry (e.g. inode number) + * + * Return: Index number in the metadata file of the block containing + * the entry specified by @nr. */ static unsigned long nilfs_palloc_entry_blkoff(const struct inode *inode, __u64 nr) @@ -238,6 +258,11 @@ static int nilfs_palloc_get_block(struct inode *inode,= unsigned long blkoff, * @blkoff: block offset * @prev: nilfs_bh_assoc struct of the last used buffer * @lock: spin lock protecting @prev + * + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOENT - Non-existent block. + * * %-ENOMEM - Insufficient memory available. */ static int nilfs_palloc_delete_block(struct inode *inode, unsigned long bl= koff, struct nilfs_bh_assoc *prev, @@ -258,6 +283,8 @@ static int nilfs_palloc_delete_block(struct inode *inod= e, unsigned long blkoff, * @group: group number * @create: create flag * @bhp: pointer to store the resultant buffer head + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_palloc_get_desc_block(struct inode *inode, unsigned long group, @@ -277,6 +304,8 @@ static int nilfs_palloc_get_desc_block(struct inode *in= ode, * @group: group number * @create: create flag * @bhp: pointer to store the resultant buffer head + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_palloc_get_bitmap_block(struct inode *inode, unsigned long group, @@ -294,6 +323,8 @@ static int nilfs_palloc_get_bitmap_block(struct inode *= inode, * nilfs_palloc_delete_bitmap_block - delete a bitmap block * @inode: inode of metadata file using this allocator * @group: group number + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_palloc_delete_bitmap_block(struct inode *inode, unsigned long group) @@ -312,6 +343,8 @@ static int nilfs_palloc_delete_bitmap_block(struct inod= e *inode, * @nr: serial number of the entry (e.g. inode number) * @create: create flag * @bhp: pointer to store the resultant buffer head + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_palloc_get_entry_block(struct inode *inode, __u64 nr, int create, struct buffer_head **bhp) @@ -328,6 +361,8 @@ int nilfs_palloc_get_entry_block(struct inode *inode, _= _u64 nr, * nilfs_palloc_delete_entry_block - delete an entry block * @inode: inode of metadata file using this allocator * @nr: serial number of the entry + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_palloc_delete_entry_block(struct inode *inode, __u64 nr) { @@ -397,6 +432,9 @@ size_t nilfs_palloc_entry_offset(const struct inode *in= ode, __u64 nr, * @bsize: size in bits * @lock: spin lock protecting @bitmap * @wrap: whether to wrap around + * + * Return: Offset number within the group of the found free entry, or + * %-ENOSPC if not found. */ static int nilfs_palloc_find_available_slot(unsigned char *bitmap, unsigned long target, @@ -438,6 +476,9 @@ static int nilfs_palloc_find_available_slot(unsigned ch= ar *bitmap, * @inode: inode of metadata file using this allocator * @curr: current group number * @max: maximum number of groups + * + * Return: Number of remaining descriptors (=3D groups) managed by the des= criptor + * block. */ static unsigned long nilfs_palloc_rest_groups_in_desc_block(const struct inode *inode, @@ -453,6 +494,8 @@ nilfs_palloc_rest_groups_in_desc_block(const struct ino= de *inode, * nilfs_palloc_count_desc_blocks - count descriptor blocks number * @inode: inode of metadata file using this allocator * @desc_blocks: descriptor blocks number [out] + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_palloc_count_desc_blocks(struct inode *inode, unsigned long *desc_blocks) @@ -473,6 +516,8 @@ static int nilfs_palloc_count_desc_blocks(struct inode = *inode, * MDT file growing * @inode: inode of metadata file using this allocator * @desc_blocks: known current descriptor blocks count + * + * Return: true if a group can be added in the metadata file, false if not. */ static inline bool nilfs_palloc_mdt_file_can_grow(struct inode *inode, unsigned long desc_blocks) @@ -487,6 +532,11 @@ static inline bool nilfs_palloc_mdt_file_can_grow(stru= ct inode *inode, * @inode: inode of metadata file using this allocator * @nused: current number of used entries * @nmaxp: max number of entries [out] + * + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. + * * %-ERANGE - Number of entries in use is out of range. */ int nilfs_palloc_count_max_entries(struct inode *inode, u64 nused, u64 *nm= axp) { @@ -518,6 +568,12 @@ int nilfs_palloc_count_max_entries(struct inode *inode= , u64 nused, u64 *nmaxp) * @inode: inode of metadata file using this allocator * @req: nilfs_palloc_req structure exchanged for the allocation * @wrap: whether to wrap around + * + * Return: 0 on success, or the following negative error code on failure. + * * %-EIO - I/O error (including metadata corruption). + * * %-ENOMEM - Insufficient memory available. + * * %-ENOSPC - Entries exhausted (No entries available for allocation). + * * %-EROFS - Read only filesystem */ int nilfs_palloc_prepare_alloc_entry(struct inode *inode, struct nilfs_palloc_req *req, bool wrap) @@ -710,6 +766,8 @@ void nilfs_palloc_abort_alloc_entry(struct inode *inode, * nilfs_palloc_prepare_free_entry - prepare to deallocate a persistent ob= ject * @inode: inode of metadata file using this allocator * @req: nilfs_palloc_req structure exchanged for the removal + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_palloc_prepare_free_entry(struct inode *inode, struct nilfs_palloc_req *req) @@ -754,6 +812,8 @@ void nilfs_palloc_abort_free_entry(struct inode *inode, * @inode: inode of metadata file using this allocator * @entry_nrs: array of entry numbers to be deallocated * @nitems: number of entries stored in @entry_nrs + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_palloc_freev(struct inode *inode, __u64 *entry_nrs, size_t nitem= s) { diff --git a/fs/nilfs2/alloc.h b/fs/nilfs2/alloc.h index 3f115ab7e9a7..046d876ea3e0 100644 --- a/fs/nilfs2/alloc.h +++ b/fs/nilfs2/alloc.h @@ -21,6 +21,8 @@ * * The number of entries per group is defined by the number of bits * that a bitmap block can maintain. + * + * Return: Number of entries per group. */ static inline unsigned long nilfs_palloc_entries_per_group(const struct inode *inode) diff --git a/fs/nilfs2/cpfile.c b/fs/nilfs2/cpfile.c index 6fb9a8743fe2..7cd755a9b7d3 100644 --- a/fs/nilfs2/cpfile.c +++ b/fs/nilfs2/cpfile.c @@ -1120,6 +1120,8 @@ int nilfs_cpfile_get_stat(struct inode *cpfile, struc= t nilfs_cpstat *cpstat) * @cpsize: size of a checkpoint entry * @raw_inode: on-disk cpfile inode * @inodep: buffer to store the inode + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_cpfile_read(struct super_block *sb, size_t cpsize, struct nilfs_inode *raw_inode, struct inode **inodep) diff --git a/fs/nilfs2/dat.c b/fs/nilfs2/dat.c index fc5dd28e7baa..4a8774f784c7 100644 --- a/fs/nilfs2/dat.c +++ b/fs/nilfs2/dat.c @@ -478,6 +478,8 @@ ssize_t nilfs_dat_get_vinfo(struct inode *dat, void *bu= f, unsigned int visz, * @entry_size: size of a dat entry * @raw_inode: on-disk dat inode * @inodep: buffer to store the inode + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_dat_read(struct super_block *sb, size_t entry_size, struct nilfs_inode *raw_inode, struct inode **inodep) diff --git a/fs/nilfs2/ifile.c b/fs/nilfs2/ifile.c index cd38ba05a655..69eca755a589 100644 --- a/fs/nilfs2/ifile.c +++ b/fs/nilfs2/ifile.c @@ -144,6 +144,8 @@ int nilfs_ifile_get_inode_block(struct inode *ifile, in= o_t ino, * @ifile: ifile inode * @nmaxinodes: current maximum of available inodes count [out] * @nfreeinodes: free inodes count [out] + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_ifile_count_free_inodes(struct inode *ifile, u64 *nmaxinodes, u64 *nfreeinodes) diff --git a/fs/nilfs2/inode.c b/fs/nilfs2/inode.c index 228bfffa5d22..e8015d24a82c 100644 --- a/fs/nilfs2/inode.c +++ b/fs/nilfs2/inode.c @@ -68,6 +68,8 @@ void nilfs_inode_sub_blocks(struct inode *inode, int n) * * This function does not issue actual read request of the specified data * block. It is done by VFS. + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_get_block(struct inode *inode, sector_t blkoff, struct buffer_head *bh_result, int create) @@ -141,6 +143,8 @@ int nilfs_get_block(struct inode *inode, sector_t blkof= f, * address_space_operations. * @file: file struct of the file to be read * @folio: the folio to be read + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_read_folio(struct file *file, struct folio *folio) { diff --git a/fs/nilfs2/mdt.c b/fs/nilfs2/mdt.c index 06bc534c7dbe..cedd1e5ece8e 100644 --- a/fs/nilfs2/mdt.c +++ b/fs/nilfs2/mdt.c @@ -515,6 +515,8 @@ void nilfs_mdt_set_entry_size(struct inode *inode, unsi= gned int entry_size, * nilfs_mdt_setup_shadow_map - setup shadow map and bind it to metadata f= ile * @inode: inode of the metadata file * @shadow: shadow mapping + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_mdt_setup_shadow_map(struct inode *inode, struct nilfs_shadow_map *shadow) @@ -536,6 +538,8 @@ int nilfs_mdt_setup_shadow_map(struct inode *inode, /** * nilfs_mdt_save_to_shadow_map - copy bmap and dirty pages to shadow map * @inode: inode of the metadata file + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_mdt_save_to_shadow_map(struct inode *inode) { diff --git a/fs/nilfs2/page.c b/fs/nilfs2/page.c index 899686d2e5f7..806b056d2260 100644 --- a/fs/nilfs2/page.c +++ b/fs/nilfs2/page.c @@ -135,8 +135,7 @@ void nilfs_copy_buffer(struct buffer_head *dbh, struct = buffer_head *sbh) * nilfs_folio_buffers_clean - Check if a folio has dirty buffers or not. * @folio: Folio to be checked. * - * nilfs_folio_buffers_clean() returns false if the folio has dirty buffer= s. - * Otherwise, it returns true. + * Return: false if the folio has dirty buffers, true otherwise. */ bool nilfs_folio_buffers_clean(struct folio *folio) { @@ -500,8 +499,9 @@ void __nilfs_clear_folio_dirty(struct folio *folio) * This function searches an extent of buffers marked "delayed" which * starts from a block offset equal to or larger than @start_blk. If * such an extent was found, this will store the start offset in - * @blkoff and return its length in blocks. Otherwise, zero is - * returned. + * @blkoff and return its length in blocks. + * + * Return: Length in blocks of found extent, 0 otherwise. */ unsigned long nilfs_find_uncommitted_extent(struct inode *inode, sector_t start_blk, diff --git a/fs/nilfs2/recovery.c b/fs/nilfs2/recovery.c index bb708e6eb42a..735a0407821b 100644 --- a/fs/nilfs2/recovery.c +++ b/fs/nilfs2/recovery.c @@ -88,6 +88,8 @@ static int nilfs_warn_segment_error(struct super_block *s= b, int err) * @check_bytes: number of bytes to be checked * @start: DBN of start block * @nblock: number of blocks to be checked + * + * Return: 0 on success, or %-EIO if an I/O error occurs. */ static int nilfs_compute_checksum(struct the_nilfs *nilfs, struct buffer_head *bhs, u32 *sum, @@ -126,6 +128,10 @@ static int nilfs_compute_checksum(struct the_nilfs *ni= lfs, * @sr_block: disk block number of the super root block * @pbh: address of a buffer_head pointer to return super root buffer * @check: CRC check flag + * + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - Super root block corrupted. + * * %-EIO - I/O error. */ int nilfs_read_super_root_block(struct the_nilfs *nilfs, sector_t sr_block, struct buffer_head **pbh, int check) @@ -176,6 +182,8 @@ int nilfs_read_super_root_block(struct the_nilfs *nilfs= , sector_t sr_block, * @nilfs: nilfs object * @start_blocknr: start block number of the log * @sum: pointer to return segment summary structure + * + * Return: Buffer head pointer, or NULL if an I/O error occurs. */ static struct buffer_head * nilfs_read_log_header(struct the_nilfs *nilfs, sector_t start_blocknr, @@ -195,6 +203,13 @@ nilfs_read_log_header(struct the_nilfs *nilfs, sector_= t start_blocknr, * @seg_seq: sequence number of segment * @bh_sum: buffer head of summary block * @sum: segment summary struct + * + * Return: 0 on success, or the following internal code on failure. + * * %NILFS_SEG_FAIL_MAGIC - Magic number mismatch. + * * %NILFS_SEG_FAIL_SEQ - Sequence number mismatch. + * * %NIFLS_SEG_FAIL_CONSISTENCY - Block count out of range. + * * %NILFS_SEG_FAIL_IO - I/O error. + * * %NILFS_SEG_FAIL_CHECKSUM_FULL - Full log checksum verification faile= d. */ static int nilfs_validate_log(struct the_nilfs *nilfs, u64 seg_seq, struct buffer_head *bh_sum, @@ -238,6 +253,9 @@ static int nilfs_validate_log(struct the_nilfs *nilfs, = u64 seg_seq, * @pbh: the current buffer head on summary blocks [in, out] * @offset: the current byte offset on summary blocks [in, out] * @bytes: byte size of the item to be read + * + * Return: Kernel space address of current segment summary entry, or + * NULL if an I/O error occurs. */ static void *nilfs_read_summary_info(struct the_nilfs *nilfs, struct buffer_head **pbh, @@ -300,6 +318,10 @@ static void nilfs_skip_summary_info(struct the_nilfs *= nilfs, * @start_blocknr: start block number of the log * @sum: log summary information * @head: list head to add nilfs_recovery_block struct + * + * Return: 0 on success, or the following negative error code on failure: + * * %-EIO - I/O error. + * * %-ENOMEM - Insufficient memory available. */ static int nilfs_scan_dsync_log(struct the_nilfs *nilfs, sector_t start_bl= ocknr, struct nilfs_segment_summary *sum, @@ -571,6 +593,11 @@ static int nilfs_recover_dsync_blocks(struct the_nilfs= *nilfs, * @sb: super block instance * @root: NILFS root instance * @ri: pointer to a nilfs_recovery_info + * + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - Log format error. + * * %-EIO - I/O error. + * * %-ENOMEM - Insufficient memory available. */ static int nilfs_do_roll_forward(struct the_nilfs *nilfs, struct super_block *sb, diff --git a/fs/nilfs2/segment.c b/fs/nilfs2/segment.c index 0eef8d1d88e6..cc2f2b3c0cce 100644 --- a/fs/nilfs2/segment.c +++ b/fs/nilfs2/segment.c @@ -249,6 +249,8 @@ int nilfs_transaction_begin(struct super_block *sb, * nilfs_transaction_commit() sets a timer to start the segment * constructor. If a sync flag is set, it starts construction * directly. + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_transaction_commit(struct super_block *sb) { @@ -404,6 +406,8 @@ static void *nilfs_segctor_map_segsum_entry(struct nilf= s_sc_info *sci, /** * nilfs_segctor_reset_segment_buffer - reset the current segment buffer * @sci: nilfs_sc_info + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_segctor_reset_segment_buffer(struct nilfs_sc_info *sci) { @@ -1314,6 +1318,8 @@ static int nilfs_segctor_collect_blocks(struct nilfs_= sc_info *sci, int mode) * nilfs_segctor_begin_construction - setup segment buffer to make a new l= og * @sci: nilfs_sc_info * @nilfs: nilfs object + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_segctor_begin_construction(struct nilfs_sc_info *sci, struct the_nilfs *nilfs) @@ -2451,6 +2457,8 @@ static void nilfs_segctor_notify(struct nilfs_sc_info= *sci, int mode, int err) * nilfs_segctor_construct - form logs and write them to disk * @sci: segment constructor object * @mode: mode of log forming + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_segctor_construct(struct nilfs_sc_info *sci, int mode) { diff --git a/fs/nilfs2/sufile.c b/fs/nilfs2/sufile.c index 92a301487a93..1f6cfa064b55 100644 --- a/fs/nilfs2/sufile.c +++ b/fs/nilfs2/sufile.c @@ -133,6 +133,8 @@ static void nilfs_sufile_mod_counter(struct buffer_head= *header_bh, /** * nilfs_sufile_get_ncleansegs - return the number of clean segments * @sufile: inode of segment usage file + * + * Return: Number of clean segments. */ unsigned long nilfs_sufile_get_ncleansegs(struct inode *sufile) { @@ -498,6 +500,8 @@ void nilfs_sufile_do_free(struct inode *sufile, __u64 s= egnum, * nilfs_sufile_mark_dirty - mark the buffer having a segment usage dirty * @sufile: inode of segment usage file * @segnum: segment number + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_sufile_mark_dirty(struct inode *sufile, __u64 segnum) { @@ -557,6 +561,8 @@ int nilfs_sufile_mark_dirty(struct inode *sufile, __u64= segnum) * @segnum: segment number * @nblocks: number of live blocks in the segment * @modtime: modification time (option) + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_sufile_set_segment_usage(struct inode *sufile, __u64 segnum, unsigned long nblocks, time64_t modtime) @@ -1189,6 +1195,8 @@ int nilfs_sufile_trim_fs(struct inode *sufile, struct= fstrim_range *range) * @susize: size of a segment usage entry * @raw_inode: on-disk sufile inode * @inodep: buffer to store the inode + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_sufile_read(struct super_block *sb, size_t susize, struct nilfs_inode *raw_inode, struct inode **inodep) diff --git a/fs/nilfs2/sufile.h b/fs/nilfs2/sufile.h index 6b39e8d97ce9..eb52d486aaa8 100644 --- a/fs/nilfs2/sufile.h +++ b/fs/nilfs2/sufile.h @@ -58,6 +58,8 @@ int nilfs_sufile_trim_fs(struct inode *sufile, struct fst= rim_range *range); * nilfs_sufile_scrap - make a segment garbage * @sufile: inode of segment usage file * @segnum: segment number to be freed + * + * Return: 0 on success, or a negative error code on failure. */ static inline int nilfs_sufile_scrap(struct inode *sufile, __u64 segnum) { @@ -68,6 +70,8 @@ static inline int nilfs_sufile_scrap(struct inode *sufile= , __u64 segnum) * nilfs_sufile_free - free segment * @sufile: inode of segment usage file * @segnum: segment number to be freed + * + * Return: 0 on success, or a negative error code on failure. */ static inline int nilfs_sufile_free(struct inode *sufile, __u64 segnum) { @@ -80,6 +84,8 @@ static inline int nilfs_sufile_free(struct inode *sufile,= __u64 segnum) * @segnumv: array of segment numbers * @nsegs: size of @segnumv array * @ndone: place to store the number of freed segments + * + * Return: 0 on success, or a negative error code on failure. */ static inline int nilfs_sufile_freev(struct inode *sufile, __u64 *segnumv, size_t nsegs, size_t *ndone) diff --git a/fs/nilfs2/super.c b/fs/nilfs2/super.c index eca79cca3803..badc2cbc895e 100644 --- a/fs/nilfs2/super.c +++ b/fs/nilfs2/super.c @@ -309,6 +309,8 @@ int nilfs_commit_super(struct super_block *sb, int flag) * This function restores state flags in the on-disk super block. * This will set "clean" flag (i.e. NILFS_VALID_FS) unless the * filesystem was not clean previously. + * + * Return: 0 on success, %-EIO if I/O error or superblock is corrupted. */ int nilfs_cleanup_super(struct super_block *sb) { @@ -339,6 +341,8 @@ int nilfs_cleanup_super(struct super_block *sb) * nilfs_move_2nd_super - relocate secondary super block * @sb: super block instance * @sb2off: new offset of the secondary super block (in bytes) + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_move_2nd_super(struct super_block *sb, loff_t sb2off) { @@ -420,6 +424,8 @@ static int nilfs_move_2nd_super(struct super_block *sb,= loff_t sb2off) * nilfs_resize_fs - resize the filesystem * @sb: super block instance * @newsize: new size of the filesystem (in bytes) + * + * Return: 0 on success, or a negative error code on failure. */ int nilfs_resize_fs(struct super_block *sb, __u64 newsize) { @@ -987,7 +993,7 @@ static int nilfs_attach_snapshot(struct super_block *s,= __u64 cno, * nilfs_tree_is_busy() - try to shrink dentries of a checkpoint * @root_dentry: root dentry of the tree to be shrunk * - * This function returns true if the tree was in-use. + * Return: true if the tree was in-use, false otherwise. */ static bool nilfs_tree_is_busy(struct dentry *root_dentry) { @@ -1033,6 +1039,8 @@ int nilfs_checkpoint_is_mounted(struct super_block *s= b, __u64 cno) * * This function is called exclusively by nilfs->ns_mount_mutex. * So, the recovery process is protected from other simultaneous mounts. + * + * Return: 0 on success, or a negative error code on failure. */ static int nilfs_fill_super(struct super_block *sb, struct fs_context *fc) diff --git a/fs/nilfs2/the_nilfs.c b/fs/nilfs2/the_nilfs.c index 1bcaf85506d3..97e53818a778 100644 --- a/fs/nilfs2/the_nilfs.c +++ b/fs/nilfs2/the_nilfs.c @@ -165,6 +165,9 @@ static void nilfs_clear_recovery_info(struct nilfs_reco= very_info *ri) * containing a super root from a given super block, and initializes * relevant information on the nilfs object preparatory for log * scanning and recovery. + * + * Return: 0 on success, or %-EINVAL if current segment number is out + * of range. */ static int nilfs_store_log_cursor(struct the_nilfs *nilfs, struct nilfs_super_block *sbp) @@ -225,6 +228,12 @@ static int nilfs_get_blocksize(struct super_block *sb, * load_nilfs() searches and load the latest super root, * attaches the last segment, and does recovery if needed. * The caller must call this exclusively for simultaneous mounts. + * + * Return: 0 on success, or the following negative error code on failure. + * * %-EINVAL - No valid segment found. + * * %-EIO - I/O error. + * * %-ENOMEM - Insufficient memory available. + * * %-EROFS - Read only device or RO compat mode (if recovery is required) */ int load_nilfs(struct the_nilfs *nilfs, struct super_block *sb) { @@ -394,6 +403,8 @@ static unsigned long long nilfs_max_size(unsigned int b= lkbits) * nilfs_nrsvsegs - calculate the number of reserved segments * @nilfs: nilfs object * @nsegs: total number of segments + * + * Return: Number of reserved segments. */ unsigned long nilfs_nrsvsegs(struct the_nilfs *nilfs, unsigned long nsegs) { @@ -405,6 +416,8 @@ unsigned long nilfs_nrsvsegs(struct the_nilfs *nilfs, u= nsigned long nsegs) /** * nilfs_max_segment_count - calculate the maximum number of segments * @nilfs: nilfs object + * + * Return: Maximum number of segments */ static u64 nilfs_max_segment_count(struct the_nilfs *nilfs) { --=20 2.43.0