[PATCH 1/1] landlock: Mention -1 return code on failure

[PATCH 1/1] landlock: Mention -1 return code on failure

[Petr Vorel]

Mention -1 return code on failure for landlock_add_rule(),
landlock_create_ruleset() and landlock_restrict_self().

Although it's a common rule to return -1 on error, it's better to be
explicit (as the other man pages are).

Fixes: a01d04a69 ("landlock_add_rule.2: Document new syscall")
Fixes: ca5163697 ("landlock_create_ruleset.2: Document new syscall")
Fixes: 3f7e4f808 ("landlock_restrict_self.2: Document new syscall")
Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
FYI we test return codes in LTP.

https://lore.kernel.org/ltp/20240711-landlock-v3-0-c7b0e9edf9b0@suse.com/
https://lore.kernel.org/ltp/20240711201306.98519-1-pvorel@suse.cz/

Kind regards,
Petr

 man/man2/landlock_add_rule.2       | 4 ++++
 man/man2/landlock_create_ruleset.2 | 4 ++++
 man/man2/landlock_restrict_self.2  | 4 ++++
 3 files changed, 12 insertions(+)

diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
index 4b95afb07..6fdc2f896 100644
--- a/man/man2/landlock_add_rule.2
+++ b/man/man2/landlock_add_rule.2
@@ -79,6 +79,10 @@ must be 0.
 On success,
 .BR landlock_add_rule ()
 returns 0.
+On error,
+\-1 is returned and
+.I errno
+is set to indicate the cause of the error.
 .SH ERRORS
 .BR landlock_add_rule ()
 can fail for the following reasons:
diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
index e62a3f9b9..4f638e85c 100644
--- a/man/man2/landlock_create_ruleset.2
+++ b/man/man2/landlock_create_ruleset.2
@@ -86,6 +86,10 @@ returns a new Landlock ruleset file descriptor,
 or a Landlock ABI version,
 according to
 .IR flags .
+On error,
+\-1 is returned and
+.I errno
+is set to indicate the cause of the error.
 .SH ERRORS
 .BR landlock_create_ruleset ()
 can fail for the following reasons:
diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
index 43f15c932..88850ddfb 100644
--- a/man/man2/landlock_restrict_self.2
+++ b/man/man2/landlock_restrict_self.2
@@ -72,6 +72,10 @@ must be 0.
 On success,
 .BR landlock_restrict_self ()
 returns 0.
+On error,
+\-1 is returned and
+.I errno
+is set to indicate the cause of the error.
 .SH ERRORS
 .BR landlock_restrict_self ()
 can fail for the following reasons:
-- 
2.45.2

Re: [PATCH 1/1] landlock: Mention -1 return code on failure

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2694 bytes --]

Hi Petr,

On Fri, Jul 12, 2024 at 03:09:04PM GMT, Petr Vorel wrote:
> Mention -1 return code on failure for landlock_add_rule(),
> landlock_create_ruleset() and landlock_restrict_self().
> 
> Although it's a common rule to return -1 on error, it's better to be
> explicit (as the other man pages are).
> 
> Fixes: a01d04a69 ("landlock_add_rule.2: Document new syscall")
> Fixes: ca5163697 ("landlock_create_ruleset.2: Document new syscall")
> Fixes: 3f7e4f808 ("landlock_restrict_self.2: Document new syscall")
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> FYI we test return codes in LTP.
> 
> https://lore.kernel.org/ltp/20240711-landlock-v3-0-c7b0e9edf9b0@suse.com/
> https://lore.kernel.org/ltp/20240711201306.98519-1-pvorel@suse.cz/
> 
> Kind regards,
> Petr

Thanks!  Please see a comment below.

> 
>  man/man2/landlock_add_rule.2       | 4 ++++
>  man/man2/landlock_create_ruleset.2 | 4 ++++
>  man/man2/landlock_restrict_self.2  | 4 ++++
>  3 files changed, 12 insertions(+)
> 
> diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
> index 4b95afb07..6fdc2f896 100644
> --- a/man/man2/landlock_add_rule.2
> +++ b/man/man2/landlock_add_rule.2
> @@ -79,6 +79,10 @@ must be 0.
>  On success,
>  .BR landlock_add_rule ()
>  returns 0.
> +On error,
> +\-1 is returned and
> +.I errno
> +is set to indicate the cause of the error.
>  .SH ERRORS
>  .BR landlock_add_rule ()
>  can fail for the following reasons:
> diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
> index e62a3f9b9..4f638e85c 100644
> --- a/man/man2/landlock_create_ruleset.2
> +++ b/man/man2/landlock_create_ruleset.2
> @@ -86,6 +86,10 @@ returns a new Landlock ruleset file descriptor,
>  or a Landlock ABI version,
>  according to
>  .IR flags .
> +On error,
> +\-1 is returned and
> +.I errno
> +is set to indicate the cause of the error.

I think the common wording is s/the cause of //

Michael unified these a few years ago.

Cheers,
Alex

>  .SH ERRORS
>  .BR landlock_create_ruleset ()
>  can fail for the following reasons:
> diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
> index 43f15c932..88850ddfb 100644
> --- a/man/man2/landlock_restrict_self.2
> +++ b/man/man2/landlock_restrict_self.2
> @@ -72,6 +72,10 @@ must be 0.
>  On success,
>  .BR landlock_restrict_self ()
>  returns 0.
> +On error,
> +\-1 is returned and
> +.I errno
> +is set to indicate the cause of the error.
>  .SH ERRORS
>  .BR landlock_restrict_self ()
>  can fail for the following reasons:
> -- 
> 2.45.2
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/1] landlock: Mention -1 return code on failure

[Petr Vorel]

> Hi Petr,

> On Fri, Jul 12, 2024 at 03:09:04PM GMT, Petr Vorel wrote:
> > Mention -1 return code on failure for landlock_add_rule(),
> > landlock_create_ruleset() and landlock_restrict_self().

> > Although it's a common rule to return -1 on error, it's better to be
> > explicit (as the other man pages are).

> > Fixes: a01d04a69 ("landlock_add_rule.2: Document new syscall")
> > Fixes: ca5163697 ("landlock_create_ruleset.2: Document new syscall")
> > Fixes: 3f7e4f808 ("landlock_restrict_self.2: Document new syscall")
> > Signed-off-by: Petr Vorel <pvorel@suse.cz>
> > ---
> > FYI we test return codes in LTP.

> > https://lore.kernel.org/ltp/20240711-landlock-v3-0-c7b0e9edf9b0@suse.com/
> > https://lore.kernel.org/ltp/20240711201306.98519-1-pvorel@suse.cz/

> > Kind regards,
> > Petr

> Thanks!  Please see a comment below.


> >  man/man2/landlock_add_rule.2       | 4 ++++
> >  man/man2/landlock_create_ruleset.2 | 4 ++++
> >  man/man2/landlock_restrict_self.2  | 4 ++++
> >  3 files changed, 12 insertions(+)

> > diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
> > index 4b95afb07..6fdc2f896 100644
> > --- a/man/man2/landlock_add_rule.2
> > +++ b/man/man2/landlock_add_rule.2
> > @@ -79,6 +79,10 @@ must be 0.
> >  On success,
> >  .BR landlock_add_rule ()
> >  returns 0.
> > +On error,
> > +\-1 is returned and
> > +.I errno
> > +is set to indicate the cause of the error.
> >  .SH ERRORS
> >  .BR landlock_add_rule ()
> >  can fail for the following reasons:
> > diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
> > index e62a3f9b9..4f638e85c 100644
> > --- a/man/man2/landlock_create_ruleset.2
> > +++ b/man/man2/landlock_create_ruleset.2
> > @@ -86,6 +86,10 @@ returns a new Landlock ruleset file descriptor,
> >  or a Landlock ABI version,
> >  according to
> >  .IR flags .
> > +On error,
> > +\-1 is returned and
> > +.I errno
> > +is set to indicate the cause of the error.

> I think the common wording is s/the cause of //

> Michael unified these a few years ago.

Yes, you're right, it's mentioned in Changes.old.
But I copied that from man/man2/mount_setattr.2 and it's on several places:

$ git grep "the cause of the error" man/ | wc -l
12

I'll send v2 later today or on Monday.

Kind regards,
Petr

> Cheers,
> Alex

> >  .SH ERRORS
> >  .BR landlock_create_ruleset ()
> >  can fail for the following reasons:
> > diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
> > index 43f15c932..88850ddfb 100644
> > --- a/man/man2/landlock_restrict_self.2
> > +++ b/man/man2/landlock_restrict_self.2
> > @@ -72,6 +72,10 @@ must be 0.
> >  On success,
> >  .BR landlock_restrict_self ()
> >  returns 0.
> > +On error,
> > +\-1 is returned and
> > +.I errno
> > +is set to indicate the cause of the error.
> >  .SH ERRORS
> >  .BR landlock_restrict_self ()
> >  can fail for the following reasons:
> > -- 
> > 2.45.2

Re: [PATCH 1/1] landlock: Mention -1 return code on failure

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 722 bytes --]

Hi Petr,

On Fri, Jul 12, 2024 at 03:25:22PM GMT, Petr Vorel wrote:
> > Hi Petr,
> > > +On error,
> > > +\-1 is returned and
> > > +.I errno
> > > +is set to indicate the cause of the error.
> 
> > I think the common wording is s/the cause of //
> 
> > Michael unified these a few years ago.
> 
> Yes, you're right, it's mentioned in Changes.old.
> But I copied that from man/man2/mount_setattr.2 and it's on several places:
> 
> $ git grep "the cause of the error" man/ | wc -l
> 12
> 
> I'll send v2 later today or on Monday.

Hmmm, thanks for investigating.  Would you mind also sending a patch for
fixing those 12 cases?

Have a lovely day!
Alex


-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/1] landlock: Mention -1 return code on failure

[Günther Noack]

On Fri, Jul 12, 2024 at 03:09:04PM +0200, Petr Vorel wrote:
> Mention -1 return code on failure for landlock_add_rule(),
> landlock_create_ruleset() and landlock_restrict_self().
> 
> Although it's a common rule to return -1 on error, it's better to be
> explicit (as the other man pages are).
> 
> Fixes: a01d04a69 ("landlock_add_rule.2: Document new syscall")
> Fixes: ca5163697 ("landlock_create_ruleset.2: Document new syscall")
> Fixes: 3f7e4f808 ("landlock_restrict_self.2: Document new syscall")
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> FYI we test return codes in LTP.
> 
> https://lore.kernel.org/ltp/20240711-landlock-v3-0-c7b0e9edf9b0@suse.com/
> https://lore.kernel.org/ltp/20240711201306.98519-1-pvorel@suse.cz/

Thank you, Petr!  This looks good.
(Please apply Alejandro's rewording suggestion as well.)

Reviewed-by: Günther Noack <gnoack@google.com>

—Günther