Message-Id: <20251219-jag-dovec_consolidate-v1-9-1413b92c6040@kernel.org>
Date: Fri, 19 Dec 2025 13:16:00 +0100
From: Joel Granados <joel.granados@...nel.org>
To: Kees Cook <kees@...nel.org>, Alexander Viro <viro@...iv.linux.org.uk>, 
 Christian Brauner <brauner@...nel.org>, Jan Kara <jack@...e.cz>
Cc: linux-kernel@...r.kernel.org, linux-fsdevel@...r.kernel.org, 
 Joel Granados <joel.granados@...nel.org>
Subject: [PATCH 9/9] sysctl: Update API function documentation

Add colon ":" after argument name where it is missing
Add doc for proc_int_conv and proc_dointvec_conv

Signed-off-by: Joel Granados <joel.granados@...nel.org>
---
 kernel/sysctl.c | 60 +++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 46 insertions(+), 14 deletions(-)

diff --git a/kernel/sysctl.c b/kernel/sysctl.c
index 3fa59ef77f931c2753584ed03006f3ff9f5a1d0e..0965ea1212b4097fb21158b08007cf550815a19f 100644
--- a/kernel/sysctl.c
+++ b/kernel/sysctl.c
@@ -365,7 +365,7 @@ static void proc_put_char(void **buf, size_t *size, char c)
  * not NULL. Check that the values are less than UINT_MAX to avoid
  * having to support wrap around from userspace.
  *
- * returns 0 on success.
+ * Returns: 0 on success.
  */
 int proc_uint_u2k_conv_uop(const ulong *u_ptr, uint *k_ptr,
 			   ulong (*u_ptr_op)(const ulong))
@@ -386,7 +386,7 @@ int proc_uint_u2k_conv_uop(const ulong *u_ptr, uint *k_ptr,
  *
  * Uses READ_ONCE to assign value to u_ptr.
  *
- * returns 0 on success.
+ * Returns: 0 on success.
  */
 int proc_uint_k2u_conv(ulong *u_ptr, const uint *k_ptr)
 {
@@ -460,16 +460,16 @@ static int do_proc_uint_conv_minmax(bool *negp, ulong *u_ptr, uint *k_ptr,
 
 /**
  * proc_int_k2u_conv_kop - Assign kernel value to a user space pointer
- * @u_ptr - pointer to user space variable
- * @k_ptr - pointer to kernel variable
- * @negp - assigned %TRUE if the converted kernel value is negative;
+ * @u_ptr: pointer to user space variable
+ * @k_ptr: pointer to kernel variable
+ * @negp: assigned %TRUE if the converted kernel value is negative;
  *         %FALSE otherweise
- * @k_ptr_op - execute this function before assigning to u_ptr
+ * @k_ptr_op: execute this function before assigning to u_ptr
  *
  * Uses READ_ONCE to get value from k_ptr. Executes k_ptr_op before assigning
  * to u_ptr if not NULL. Does **not** check for overflow.
  *
- * returns 0 on success.
+ * Returns: 0 on success.
  */
 int proc_int_k2u_conv_kop(ulong *u_ptr, const int *k_ptr, bool *negp,
 			  ulong (*k_ptr_op)(const ulong))
@@ -488,15 +488,15 @@ int proc_int_k2u_conv_kop(ulong *u_ptr, const int *k_ptr, bool *negp,
 
 /**
  * proc_int_u2k_conv_uop - Assign user value to a kernel pointer
- * @u_ptr - pointer to user space variable
- * @k_ptr - pointer to kernel variable
- * @negp - If %TRUE, the converted user value is made negative.
- * @u_ptr_op - execute this function before assigning to k_ptr
+ * @u_ptr: pointer to user space variable
+ * @k_ptr: pointer to kernel variable
+ * @negp: If %TRUE, the converted user value is made negative.
+ * @u_ptr_op: execute this function before assigning to k_ptr
  *
  * Uses WRITE_ONCE to assign value to k_ptr. Executes u_ptr_op if
  * not NULL. Check for overflow with UINT_MAX.
  *
- * returns 0 on success.
+ * Returns: 0 on success.
  */
 int proc_int_u2k_conv_uop(const ulong *u_ptr, int *k_ptr, const bool *negp,
 			  ulong (*u_ptr_op)(const ulong))
@@ -515,6 +515,23 @@ int proc_int_u2k_conv_uop(const ulong *u_ptr, int *k_ptr, const bool *negp,
 	return 0;
 }
 
+/**
+ * proc_int_conv - Change user or kernel pointer based on direction
+ *
+ * @negp: will be passed to uni-directional converters
+ * @u_ptr: pointer to user variable
+ * @k_ptr: pointer to kernel variable
+ * @dir: %TRUE if this is a write to the sysctl file
+ * @tbl: the sysctl table
+ * @k_ptr_range_check: Check range for k_ptr when %TRUE
+ * @user_to_kern: Callback used to assign value from user to kernel var
+ * @kern_to_user: Callback used to assign value from kernel to user var
+ *
+ * When direction is kernel to user, then the u_ptr is modified.
+ * When direction is user to kernel, then the k_ptr is modified.
+ *
+ * Returns: 0 on success
+ */
 int proc_int_conv(bool *negp, ulong *u_ptr, int *k_ptr, int dir,
 		  const struct ctl_table *tbl, bool k_ptr_range_check,
 		  int (*user_to_kern)(const bool *negp, const ulong *u_ptr, int *k_ptr),
@@ -910,7 +927,7 @@ int proc_ulong_conv(ulong *u_ptr, ulong *k_ptr, int dir,
  * Uses WRITE_ONCE to assign value to k_ptr. Executes u_ptr_op if
  * not NULL.
  *
- * returns: 0 on success.
+ * Returns: 0 on success.
  */
 int proc_ulong_u2k_conv_uop(const ulong *u_ptr, ulong *k_ptr,
 			    ulong (*u_ptr_op)(const ulong))
@@ -936,7 +953,7 @@ static int proc_ulong_u2k_conv(const ulong *u_ptr, ulong *k_ptr)
  * Uses READ_ONCE to assign value to u_ptr. Executes k_ptr_op if
  * not NULL.
  *
- * returns: 0 on success.
+ * Returns: 0 on success.
  */
 int proc_ulong_k2u_conv_kop(ulong *u_ptr, const ulong *k_ptr,
 			    ulong (*k_ptr_op)(const ulong))
@@ -1005,6 +1022,21 @@ int proc_doulongvec_minmax(const struct ctl_table *table, int dir,
 				do_proc_ulong_conv);
 }
 
+/**
+ * proc_dointvec_conv - read a vector of ints with a custom converter
+ *
+ * @table: the sysctl table
+ * @dir: %TRUE if this is a write to the sysctl file
+ * @buffer: the user buffer
+ * @lenp: the size of the user buffer
+ * @ppos: file position
+ * @conv: Custom converter call back. Defaults to do_proc_int_conv
+ *
+ * Reads/writes up to table->maxlen/sizeof(int) integer values from/to the
+ * user buffer, treated as an ASCII string.
+ *
+ * Returns: 0 on success
+ */
 int proc_dointvec_conv(const struct ctl_table *table, int dir, void *buffer,
 		       size_t *lenp, loff_t *ppos,
 		       int (*conv)(bool *negp, unsigned long *u_ptr, int *k_ptr,

-- 
2.50.1

Powered by blists - more mailing lists