The glibc library limits the return code to 8 bits. We need to
stick to this limit when using sys.exit(error_count).

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc.py | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 7a1eaf986bcd..600bdfea6a96 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -176,7 +176,14 @@ class MsgFormatter(logging.Formatter):
         return logging.Formatter.format(self, record)
 
 def main():
-    """Main program"""
+    """
+    Main program
+    By default, the return value is zero on parsing errors or when the
+    Python version is not compatible with kernel-doc. The rationale is
+    to not break Linux compilation on such cases.
+    If -Werror is used, it will return the number of parse errors, up to
+    255 errors, as this is the maximum value allowed by glibc.
+    """
 
     parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
                                      description=DESC)
@@ -321,18 +328,23 @@ def main():
     if not error_count:
         sys.exit(0)
 
+    if args.verbose:
+        print("%s errors" % error_count)                # pylint: disable=C0209
+
+
     if args.werror:
         print("%s warnings as errors" % error_count)    # pylint: disable=C0209
+
+        #
+        # Return code is 8-bits, as seen at:
+        #   https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html
+        # Truncate to avoid overflow
+        #
+        if error_count > 255:
+            error_count = 255
+
         sys.exit(error_count)
-
-    if args.verbose:
-        print("%s errors" % error_count)                # pylint: disable=C0209
-
-    if args.none:
-        sys.exit(0)
-
-    sys.exit(error_count)
-
+    sys.exit(0)
 
 # Call main method
 if __name__ == "__main__":
-- 
2.52.0

On Mon, 12 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> The glibc library limits the return code to 8 bits. We need to
> stick to this limit when using sys.exit(error_count).
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  scripts/kernel-doc.py | 32 ++++++++++++++++++++++----------
>  1 file changed, 22 insertions(+), 10 deletions(-)
>
> diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
> index 7a1eaf986bcd..600bdfea6a96 100755
> --- a/scripts/kernel-doc.py
> +++ b/scripts/kernel-doc.py
> @@ -176,7 +176,14 @@ class MsgFormatter(logging.Formatter):
>          return logging.Formatter.format(self, record)
>  
>  def main():
> -    """Main program"""
> +    """
> +    Main program
> +    By default, the return value is zero on parsing errors or when the
> +    Python version is not compatible with kernel-doc. The rationale is
> +    to not break Linux compilation on such cases.
> +    If -Werror is used, it will return the number of parse errors, up to
> +    255 errors, as this is the maximum value allowed by glibc.
> +    """
>  
>      parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
>                                       description=DESC)
> @@ -321,18 +328,23 @@ def main():
>      if not error_count:
>          sys.exit(0)
>  
> +    if args.verbose:
> +        print("%s errors" % error_count)                # pylint: disable=C0209
> +
> +
>      if args.werror:
>          print("%s warnings as errors" % error_count)    # pylint: disable=C0209
> +
> +        #
> +        # Return code is 8-bits, as seen at:
> +        #   https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html
> +        # Truncate to avoid overflow
> +        #
> +        if error_count > 255:
> +            error_count = 255

What's the point in returning the error count anyway?

I'd rather see some error/warning classification in the exit code than a
count. Like, the argparser uses exit code 2 by default, so you can't
even trust the exit code to return the count anyway.

BR,
Jani.

> +
>          sys.exit(error_count)
> -
> -    if args.verbose:
> -        print("%s errors" % error_count)                # pylint: disable=C0209
> -
> -    if args.none:
> -        sys.exit(0)
> -
> -    sys.exit(error_count)
> -
> +    sys.exit(0)
>  
>  # Call main method
>  if __name__ == "__main__":

-- 
Jani Nikula, Intel

On Mon, Jan 12, 2026 at 02:02:10PM +0200, Jani Nikula wrote:
> On Mon, 12 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > The glibc library limits the return code to 8 bits. We need to
> > stick to this limit when using sys.exit(error_count).
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  scripts/kernel-doc.py | 32 ++++++++++++++++++++++----------
> >  1 file changed, 22 insertions(+), 10 deletions(-)
> >
> > diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
> > index 7a1eaf986bcd..600bdfea6a96 100755
> > --- a/scripts/kernel-doc.py
> > +++ b/scripts/kernel-doc.py
> > @@ -176,7 +176,14 @@ class MsgFormatter(logging.Formatter):
> >          return logging.Formatter.format(self, record)
> >  
> >  def main():
> > -    """Main program"""
> > +    """
> > +    Main program
> > +    By default, the return value is zero on parsing errors or when the
> > +    Python version is not compatible with kernel-doc. The rationale is
> > +    to not break Linux compilation on such cases.
> > +    If -Werror is used, it will return the number of parse errors, up to
> > +    255 errors, as this is the maximum value allowed by glibc.
> > +    """
> >  
> >      parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
> >                                       description=DESC)
> > @@ -321,18 +328,23 @@ def main():
> >      if not error_count:
> >          sys.exit(0)
> >  
> > +    if args.verbose:
> > +        print("%s errors" % error_count)                # pylint: disable=C0209
> > +
> > +
> >      if args.werror:
> >          print("%s warnings as errors" % error_count)    # pylint: disable=C0209
> > +
> > +        #
> > +        # Return code is 8-bits, as seen at:
> > +        #   https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html
> > +        # Truncate to avoid overflow
> > +        #
> > +        if error_count > 255:
> > +            error_count = 255
> 
> What's the point in returning the error count anyway?

Mostly historical reasons. I used the return value during the conversion
to help verifying if the Python version was doing the right thing.

> I'd rather see some error/warning classification in the exit code than a
> count. Like, the argparser uses exit code 2 by default, so you can't
> even trust the exit code to return the count anyway.

Right now, python can exit with:

1. argparse errors;

2. sys.exit() with messages like:
    sys.exit(f"Error running fc-list: {repr(exc)}")

3. eventually unhandled errors that would rise

4. sys.exit(0) if:
    - No warnings;
    - the -Werror is not used and warnings were issued;
    - Python version < 3.6 (we want kernel to keep building)

5. error count > 0

(2) and (3) returns 1; argparse returns 2.

So, maybe we can use sys.exit(3) for warnings.

-- 
Thanks,
Mauro