Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
landlock: Improve kernel-doc "Return:" section consistency
The canonical kernel-doc form is "Return:" (singular, without trailing
"s"). Normalize all existing "Returns:" occurrences across the Landlock
source tree to the canonical form.
Also fix capitalization for consistency. Balance descriptions to
describe all possible returned values.
Consolidate bullet-point return descriptions into inline text for
functions with simple two-value or three-value returns for consistency.
Cc: Günther Noack <gnoack@google.com>
Reviewed-by: Günther Noack <gnoack3000@gmail.com>
Link: https://lore.kernel.org/r/20260304193134.250495-3-mic@digikod.net
Signed-off-by: Mickaël Salaün <mic@digikod.net>
+25
-34
+1
-1
security/landlock/cred.h
+1
-1
security/landlock/cred.h
···
115
115
* @handle_layer: returned youngest layer handling a subset of @masks. Not set
116
116
* if the function returns NULL.
117
117
*
118
-
* Returns: landlock_cred(@cred) if any access rights specified in @masks is
118
+
* Return: landlock_cred(@cred) if any access rights specified in @masks is
119
119
* handled, or NULL otherwise.
120
120
*/
121
121
static inline const struct landlock_cred_security *
+2
-2
security/landlock/domain.c
+2
-2
security/landlock/domain.c
···
34
34
* @exe_size: Returned size of @exe_str (including the trailing null
35
35
* character), if any.
36
36
*
37
-
* Returns: A pointer to an allocated buffer where @exe_str point to, %NULL if
37
+
* Return: A pointer to an allocated buffer where @exe_str point to, %NULL if
38
38
* there is no executable path, or an error otherwise.
39
39
*/
40
40
static const void *get_current_exe(const char **const exe_str,
···
73
73
}
74
74
75
75
/*
76
-
* Returns: A newly allocated object describing a domain, or an error
76
+
* Return: A newly allocated object describing a domain, or an error
77
77
* otherwise.
78
78
*/
79
79
static struct landlock_details *get_current_details(void)
+11
-15
security/landlock/fs.c
+11
-15
security/landlock/fs.c
···
119
119
* Any new IOCTL commands that are implemented in fs/ioctl.c's do_vfs_ioctl()
120
120
* should be considered for inclusion here.
121
121
*
122
-
* Returns: true if the IOCTL @cmd can not be restricted with Landlock for
123
-
* device files.
122
+
* Return: True if the IOCTL @cmd can not be restricted with Landlock for
123
+
* device files, false otherwise.
124
124
*/
125
125
static __attribute_const__ bool is_masked_device_ioctl(const unsigned int cmd)
126
126
{
···
428
428
* Check that a destination file hierarchy has more restrictions than a source
429
429
* file hierarchy. This is only used for link and rename actions.
430
430
*
431
-
* Returns: true if child1 may be moved from parent1 to parent2 without
432
-
* increasing its access rights. If child2 is set, an additional condition is
431
+
* Return: True if child1 may be moved from parent1 to parent2 without
432
+
* increasing its access rights (if child2 is set, an additional condition is
433
433
* that child2 may be used from parent2 to parent1 without increasing its access
434
-
* rights.
434
+
* rights), false otherwise.
435
435
*/
436
436
static bool no_more_access(const struct layer_access_masks *const parent1,
437
437
const struct layer_access_masks *const child1,
···
734
734
* checks that the collected accesses and the remaining ones are enough to
735
735
* allow the request.
736
736
*
737
-
* Returns:
738
-
* - true if the access request is granted;
739
-
* - false otherwise.
737
+
* Return: True if the access request is granted, false otherwise.
740
738
*/
741
739
static bool
742
740
is_access_to_paths_allowed(const struct landlock_ruleset *const domain,
···
1020
1022
* only handles walking on the same mount point and only checks one set of
1021
1023
* accesses.
1022
1024
*
1023
-
* Returns:
1024
-
* - true if all the domain access rights are allowed for @dir;
1025
-
* - false if the walk reached @mnt_root.
1025
+
* Return: True if all the domain access rights are allowed for @dir, false if
1026
+
* the walk reached @mnt_root.
1026
1027
*/
1027
1028
static bool collect_domain_accesses(const struct landlock_ruleset *const domain,
1028
1029
const struct dentry *const mnt_root,
···
1117
1120
* ephemeral matrices take some space on the stack, which limits the number of
1118
1121
* layers to a deemed reasonable number: 16.
1119
1122
*
1120
-
* Returns:
1121
-
* - 0 if access is allowed;
1122
-
* - -EXDEV if @old_dentry would inherit new access rights from @new_dir;
1123
-
* - -EACCES if file removal or creation is denied.
1123
+
* Return: 0 if access is allowed, -EXDEV if @old_dentry would inherit new
1124
+
* access rights from @new_dir, or -EACCES if file removal or creation is
1125
+
* denied.
1124
1126
*/
1125
1127
static int current_check_refer_path(struct dentry *const old_dentry,
1126
1128
const struct path *const new_dir,
+1
-1
security/landlock/id.c
+1
-1
security/landlock/id.c
+1
-1
security/landlock/ruleset.c
+1
-1
security/landlock/ruleset.c
···
674
674
* @masks: Layer access masks to populate.
675
675
* @key_type: The key type to switch between access masks of different types.
676
676
*
677
-
* Returns: An access mask where each access right bit is set which is handled
677
+
* Return: An access mask where each access right bit is set which is handled
678
678
* in any of the active layers in @domain.
679
679
*/
680
680
access_mask_t
+1
-1
security/landlock/ruleset.h
+1
-1
security/landlock/ruleset.h
···
224
224
*
225
225
* @domain: Landlock ruleset (used as a domain)
226
226
*
227
-
* Returns: an access_masks result of the OR of all the domain's access masks.
227
+
* Return: An access_masks result of the OR of all the domain's access masks.
228
228
*/
229
229
static inline struct access_masks
230
230
landlock_union_access_masks(const struct landlock_ruleset *const domain)
+2
-2
security/landlock/task.c
+2
-2
security/landlock/task.c
···
174
174
* @server: IPC receiver domain.
175
175
* @scope: The scope restriction criteria.
176
176
*
177
-
* Returns: True if @server is in a different domain from @client, and @client
178
-
* is scoped to access @server (i.e. access should be denied).
177
+
* Return: True if @server is in a different domain from @client and @client
178
+
* is scoped to access @server (i.e. access should be denied), false otherwise.
179
179
*/
180
180
static bool domain_is_scoped(const struct landlock_ruleset *const client,
181
181
const struct landlock_ruleset *const server,
+6
-11
security/landlock/tsync.c
+6
-11
security/landlock/tsync.c
···
183
183
* capacity. This can legitimately happen if new threads get started after we
184
184
* grew the capacity.
185
185
*
186
-
* Returns:
187
-
* A pointer to the preallocated context struct, with task filled in.
188
-
*
189
-
* NULL, if we ran out of preallocated context structs.
186
+
* Return: A pointer to the preallocated context struct with task filled in, or
187
+
* NULL if preallocated context structs ran out.
190
188
*/
191
189
static struct tsync_work *tsync_works_provide(struct tsync_works *s,
192
190
struct task_struct *task)
···
241
243
* On a successful return, the subsequent n calls to tsync_works_provide() are
242
244
* guaranteed to succeed. (size + n <= capacity)
243
245
*
244
-
* Returns:
245
-
* -ENOMEM if the (re)allocation fails
246
-
247
-
* 0 if the allocation succeeds, partially succeeds, or no reallocation
248
-
* was needed
246
+
* Return: 0 if sufficient space for n more elements could be provided, -ENOMEM
247
+
* on allocation errors, -EOVERFLOW in case of integer overflow.
249
248
*/
250
249
static int tsync_works_grow_by(struct tsync_works *s, size_t n, gfp_t flags)
251
250
{
···
358
363
* For each added task_work, atomically increments shared_ctx->num_preparing and
359
364
* shared_ctx->num_unfinished.
360
365
*
361
-
* Returns:
362
-
* true, if at least one eligible sibling thread was found
366
+
* Return: True if at least one eligible sibling thread was found, false
367
+
* otherwise.
363
368
*/
364
369
static bool schedule_task_work(struct tsync_works *works,
365
370
struct tsync_shared_context *shared_ctx)