From: Mickaël Salaün Date: Wed, 4 Mar 2026 19:31:25 +0000 (+0100) Subject: landlock: Add missing kernel-doc "Return:" sections X-Git-Tag: v7.1-rc1~234^2~15 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e89dea254dce44c629d98639c05fe5ca7add7241;p=thirdparty%2Fkernel%2Flinux.git landlock: Add missing kernel-doc "Return:" sections 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 --- diff --git a/security/landlock/domain.c b/security/landlock/domain.c index f0d83f43afa1d..7bf6296162b00 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 e764470f588c1..cfe69075bf4e6 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 73018dc8d6c7e..5abea30f1d958 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 a0bb664e0d315..5ebd606e84e69 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 833bc0cfe5c9b..bf7c3db7ce46e 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) {