[PATCH] man: fix doc ip will exit with -1

[PATCH] man: fix doc ip will exit with -1

[Jiayun Chen]

The exit code of -1 (255) is not documented:

$ ip link set dev; echo $?
255

$ ip route help; echo $?
255

It appears that ip returns -1 on syntax error, e.g., invalid device, buffer
size. Here is a patch for documenting this behavior.

Signed-off-by: Jiayun Chen <chenjiayunju@gmail.com>
---
 man/man8/ip.8 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man/man8/ip.8 b/man/man8/ip.8
index fdae57c5..e7bd9eb4 100644
--- a/man/man8/ip.8
+++ b/man/man8/ip.8
@@ -405,8 +405,8 @@ If this value is 0-6 or 8, chose colors suitable for dark background:
 COLORFGBG=";0" ip -c a
 
 .SH EXIT STATUS
-Exit status is 0 if command was successful, and 1 if there is a syntax error.
-If an error was reported by the kernel exit status is 2.
+Exit status is 0 if command was successful, and -1 or 1 if there is a 
+syntax error. If an error was reported by the kernel exit status is 2.
 
 .SH "EXAMPLES"
 .PP
-- 
2.34.1

Re: [PATCH] man: fix doc ip will exit with -1

[Stephen Hemminger]

On Tue, 23 Apr 2024 15:03:46 +0800
Jiayun Chen <chenjiayunju@gmail.com> wrote:

> The exit code of -1 (255) is not documented:
> 
> $ ip link set dev; echo $?
> 255
> 
> $ ip route help; echo $?
> 255
> 
> It appears that ip returns -1 on syntax error, e.g., invalid device, buffer
> size. Here is a patch for documenting this behavior.
> 
> Signed-off-by: Jiayun Chen <chenjiayunju@gmail.com>
> ---
>  man/man8/ip.8 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

I wish Alexey had used the semi-standard exit codes from bash.
The convention is to use 2 for incorrect usage.
Probably too late to fix now?

Re: [PATCH] man: fix doc ip will exit with -1

[jiayun chen]

But a checker based on the manual doesn't know
what such an undefined value means and how to
handle it.

So I suggest fixing the manual only, not the code.


On Tue, Apr 23, 2024 at 11:35 PM Stephen Hemminger
<stephen@networkplumber.org> wrote:
>
> On Tue, 23 Apr 2024 15:03:46 +0800
> Jiayun Chen <chenjiayunju@gmail.com> wrote:
>
> > The exit code of -1 (255) is not documented:
> >
> > $ ip link set dev; echo $?
> > 255
> >
> > $ ip route help; echo $?
> > 255
> >
> > It appears that ip returns -1 on syntax error, e.g., invalid device, buffer
> > size. Here is a patch for documenting this behavior.
> >
> > Signed-off-by: Jiayun Chen <chenjiayunju@gmail.com>
> > ---
> >  man/man8/ip.8 | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
>
> I wish Alexey had used the semi-standard exit codes from bash.
> The convention is to use 2 for incorrect usage.
> Probably too late to fix now?

Re: [PATCH] man: fix doc ip will exit with -1

[Stephen Hemminger]

On Tue, 23 Apr 2024 15:03:46 +0800
Jiayun Chen <chenjiayunju@gmail.com> wrote:

> The exit code of -1 (255) is not documented:
> 
> $ ip link set dev; echo $?
> 255
> 
> $ ip route help; echo $?
> 255
> 
> It appears that ip returns -1 on syntax error, e.g., invalid device, buffer
> size. Here is a patch for documenting this behavior.
> 
> Signed-off-by: Jiayun Chen <chenjiayunju@gmail.com>
> ---

I would rather fix all of iproute2 commands (ip, bridge, tc, devlink, etc)
to follow the conventions used by other Linux utilities of return 2 for errors
in command line arguments. Doing that is unlikely to break any scripts because
a sane script will be checking for exit status of non-zero.