From e89dea254dce44c629d98639c05fe5ca7add7241 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= Date: Wed, 4 Mar 2026 20:31:25 +0100 Subject: [PATCH] landlock: Add missing kernel-doc "Return:" sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The kernel-doc -Wreturn check warns about functions with documentation comments that lack a "Return:" section. Add "Return:" documentation to all functions missing it so that kernel-doc -Wreturn passes cleanly. Convert existing function descriptions into a formal "Return:" section. Also fix the inaccurate return documentation for landlock_merge_ruleset() which claimed to return @parent directly, and document the previously missing ERR_PTR() error return path. Document the ABI version and errata return paths for landlock_create_ruleset() which were previously only implied by the prose. Cc: Günther Noack Reviewed-by: Günther Noack Link: https://lore.kernel.org/r/20260304193134.250495-2-mic@digikod.net Signed-off-by: Mickaël Salaün --- security/landlock/domain.c | 2 ++ security/landlock/fs.c | 2 +- security/landlock/ruleset.c | 8 +++++--- security/landlock/syscalls.c | 17 +++++++++++------ security/landlock/task.c | 9 +++++---- 5 files changed, 24 insertions(+), 14 deletions(-) diff --git a/security/landlock/domain.c b/security/landlock/domain.c index f0d83f43afa1..7bf6296162b0 100644 --- a/security/landlock/domain.c +++ b/security/landlock/domain.c @@ -114,6 +114,8 @@ static struct landlock_details *get_current_details(void) * restriction. The subjective credentials must not be in an overridden state. * * @hierarchy->parent and @hierarchy->usage should already be set. + * + * Return: 0 on success, -errno on failure. */ int landlock_init_hierarchy_log(struct landlock_hierarchy *const hierarchy) { diff --git a/security/landlock/fs.c b/security/landlock/fs.c index e764470f588c..cfe69075bf4e 100644 --- a/security/landlock/fs.c +++ b/security/landlock/fs.c @@ -1568,7 +1568,7 @@ static int hook_path_truncate(const struct path *const path) * * @file: File being opened. * - * Returns the access rights that are required for opening the given file, + * Return: The access rights that are required for opening the given file, * depending on the file type and open mode. */ static access_mask_t diff --git a/security/landlock/ruleset.c b/security/landlock/ruleset.c index 73018dc8d6c7..5abea30f1d95 100644 --- a/security/landlock/ruleset.c +++ b/security/landlock/ruleset.c @@ -201,6 +201,8 @@ static void build_check_ruleset(void) * When merging a ruleset in a domain, or copying a domain, @layers will be * added to @ruleset as new constraints, similarly to a boolean AND between * access rights. + * + * Return: 0 on success, -errno on failure. */ static int insert_rule(struct landlock_ruleset *const ruleset, const struct landlock_id id, @@ -530,8 +532,8 @@ void landlock_put_ruleset_deferred(struct landlock_ruleset *const ruleset) * The current task is requesting to be restricted. The subjective credentials * must not be in an overridden state. cf. landlock_init_hierarchy_log(). * - * Returns the intersection of @parent and @ruleset, or returns @parent if - * @ruleset is empty, or returns a duplicate of @ruleset if @parent is empty. + * Return: A new domain merging @parent and @ruleset on success, or ERR_PTR() + * on failure. If @parent is NULL, the new domain duplicates @ruleset. */ struct landlock_ruleset * landlock_merge_ruleset(struct landlock_ruleset *const parent, @@ -622,7 +624,7 @@ landlock_find_rule(const struct landlock_ruleset *const ruleset, * @rule: A rule that grants a set of access rights for each layer * @masks: A matrix of unfulfilled access rights for each layer * - * Returns true if the request is allowed (i.e. the access rights granted all + * Return: True if the request is allowed (i.e. the access rights granted all * remaining unfulfilled access rights and masks has no leftover set bits). */ bool landlock_unmask_layers(const struct landlock_rule *const rule, diff --git a/security/landlock/syscalls.c b/security/landlock/syscalls.c index a0bb664e0d31..5ebd606e84e6 100644 --- a/security/landlock/syscalls.c +++ b/security/landlock/syscalls.c @@ -60,6 +60,8 @@ static bool is_initialized(void) * @ksize_min: Minimal required size to be copied. * @src: User space pointer or NULL. * @usize: (Alleged) size of the data pointed to by @src. + * + * Return: 0 on success, -errno on failure. */ static __always_inline int copy_min_struct_from_user(void *const dst, const size_t ksize, @@ -178,16 +180,19 @@ const int landlock_abi_version = 8; * - %LANDLOCK_CREATE_RULESET_VERSION * - %LANDLOCK_CREATE_RULESET_ERRATA * - * This system call enables to create a new Landlock ruleset, and returns the - * related file descriptor on success. + * This system call enables to create a new Landlock ruleset. * * If %LANDLOCK_CREATE_RULESET_VERSION or %LANDLOCK_CREATE_RULESET_ERRATA is * set, then @attr must be NULL and @size must be 0. * - * Possible returned errors are: + * Return: The ruleset file descriptor on success, the Landlock ABI version if + * %LANDLOCK_CREATE_RULESET_VERSION is set, the errata value if + * %LANDLOCK_CREATE_RULESET_ERRATA is set, or -errno on failure. Possible + * returned errors are: * * - %EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time; - * - %EINVAL: unknown @flags, or unknown access, or unknown scope, or too small @size; + * - %EINVAL: unknown @flags, or unknown access, or unknown scope, or too small + * @size; * - %E2BIG: @attr or @size inconsistencies; * - %EFAULT: @attr or @size inconsistencies; * - %ENOMSG: empty &landlock_ruleset_attr.handled_access_fs. @@ -398,7 +403,7 @@ static int add_rule_net_port(struct landlock_ruleset *ruleset, * This system call enables to define a new rule and add it to an existing * ruleset. * - * Possible returned errors are: + * Return: 0 on success, or -errno on failure. Possible returned errors are: * * - %EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time; * - %EAFNOSUPPORT: @rule_type is %LANDLOCK_RULE_NET_PORT but TCP/IP is not @@ -464,7 +469,7 @@ SYSCALL_DEFINE4(landlock_add_rule, const int, ruleset_fd, * namespace or is running with no_new_privs. This avoids scenarios where * unprivileged tasks can affect the behavior of privileged children. * - * Possible returned errors are: + * Return: 0 on success, or -errno on failure. Possible returned errors are: * * - %EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time; * - %EINVAL: @flags contains an unknown bit. diff --git a/security/landlock/task.c b/security/landlock/task.c index 833bc0cfe5c9..bf7c3db7ce46 100644 --- a/security/landlock/task.c +++ b/security/landlock/task.c @@ -37,6 +37,9 @@ * * Checks if the @parent domain is less or equal to (i.e. an ancestor, which * means a subset of) the @child domain. + * + * Return: True if @parent is an ancestor of or equal to @child, false + * otherwise. */ static bool domain_scope_le(const struct landlock_ruleset *const parent, const struct landlock_ruleset *const child) @@ -79,8 +82,7 @@ static int domain_ptrace(const struct landlock_ruleset *const parent, * If the current task has Landlock rules, then the child must have at least * the same rules. Else denied. * - * Determines whether a process may access another, returning 0 if permission - * granted, -errno if denied. + * Return: 0 if permission is granted, -errno if denied. */ static int hook_ptrace_access_check(struct task_struct *const child, const unsigned int mode) @@ -129,8 +131,7 @@ static int hook_ptrace_access_check(struct task_struct *const child, * If the parent has Landlock rules, then the current task must have the same * or more rules. Else denied. * - * Determines whether the nominated task is permitted to trace the current - * process, returning 0 if permission is granted, -errno if denied. + * Return: 0 if permission is granted, -errno if denied. */ static int hook_ptrace_traceme(struct task_struct *const parent) {