Commit 1dc8689e authored by Luis Chamberlain's avatar Luis Chamberlain
Browse files

proc_sysctl: enhance documentation 



Expand documentation to clarify:

  o that paths don't need to exist for the new API callers
  o clarify that we *require* callers to keep the memory of
    the table around during the lifetime of the sysctls
  o annotate routines we are trying to deprecate and later remove

Cc: stable@vger.kernel.org # v5.17
Cc: Christian Brauner <brauner@kernel.org>
Cc: Kefeng Wang <wangkefeng.wang@huawei.com>
Signed-off-by: default avatarLuis Chamberlain <mcgrof@kernel.org>
parent 9f17a75b

fs/proc/proc_sysctl.c

+20 −5
Original line number Diff line number Diff line
@@ -1316,7 +1316,10 @@ static struct ctl_dir *sysctl_mkdir_p(struct ctl_dir *dir, const char *path) 
 * __register_sysctl_table - register a leaf sysctl table

 * @set: Sysctl tree to register on

 * @path: The path to the directory the sysctl table is in.

 * @table: the top-level table structure without any child

 * @table: the top-level table structure without any child. This table

 * 	 should not be free'd after registration. So it should not be

 * 	 used on stack. It can either be a global or dynamically allocated

 * 	 by the caller and free'd later after sysctl unregistration.

 *

 * Register a sysctl table hierarchy. @table should be a filled in ctl_table

 * array. A completely 0 filled entry terminates the table.
@@ -1410,8 +1413,15 @@ struct ctl_table_header *__register_sysctl_table( 


/**

 * register_sysctl - register a sysctl table

 * @path: The path to the directory the sysctl table is in.

 * @table: the table structure

 * @path: The path to the directory the sysctl table is in. If the path

 * 	doesn't exist we will create it for you.

 * @table: the table structure. The calller must ensure the life of the @table

 * 	will be kept during the lifetime use of the syctl. It must not be freed

 * 	until unregister_sysctl_table() is called with the given returned table

 * 	with this registration. If your code is non modular then you don't need

 * 	to call unregister_sysctl_table() and can instead use something like

 * 	register_sysctl_init() which does not care for the result of the syctl

 * 	registration.

 *

 * Register a sysctl table. @table should be a filled in ctl_table

 * array. A completely 0 filled entry terminates the table.
@@ -1427,8 +1437,11 @@ EXPORT_SYMBOL(register_sysctl); 


/**

 * __register_sysctl_init() - register sysctl table to path

 * @path: path name for sysctl base

 * @table: This is the sysctl table that needs to be registered to the path

 * @path: path name for sysctl base. If that path doesn't exist we will create

 * 	it for you.

 * @table: This is the sysctl table that needs to be registered to the path.

 * 	The caller must ensure the life of the @table will be kept during the

 * 	lifetime use of the sysctl.

 * @table_name: The name of sysctl table, only used for log printing when

 *              registration fails

 *
@@ -1570,6 +1583,7 @@ static int register_leaf_sysctl_tables(const char *path, char *pos, 
 *

 * Register a sysctl table hierarchy. @table should be a filled in ctl_table

 * array. A completely 0 filled entry terminates the table.

 * We are slowly deprecating this call so avoid its use.

 *

 * See __register_sysctl_table for more details.

 */
@@ -1641,6 +1655,7 @@ struct ctl_table_header *__register_sysctl_paths( 
 *

 * Register a sysctl table hierarchy. @table should be a filled in ctl_table

 * array. A completely 0 filled entry terminates the table.

 * We are slowly deprecating this caller so avoid future uses of it.

 *

 * See __register_sysctl_paths for more details.

 */