backtrace(3): Inconsistency and missing indentation

In the example section of the page the following snippet is given:

--8><--

        void
        myfunc3(void)
        {
            int j, nptrs;
        #define SIZE 100
            void *buffer[100];
            char **strings;

            nptrs = backtrace(buffer, SIZE);

--><8--

Problems:

1. "#define SIZE 100" is not indented correctly.
2. SIZE should also be used for the buffer array size.

Quoted 12 lines · Martin Gebert

In the example section of the page the following snippet is given:

--8><--

        void
        myfunc3(void)
        {
            int j, nptrs;
        #define SIZE 100
            void *buffer[100];
            char **strings;

            nptrs = backtrace(buffer, SIZE);

Quoted 6 lines

--><8--

Problems:

1. "#define SIZE 100" is not indented correctly.
2. SIZE should also be used for the buffer array size.

Thanks, Martin. Fixed as below.

Cheers,

Michael

man3/backtrace.3 +0 -0

index afca93d..064b970 100644

Quoted 31 lines · Michael Kerrisk (man-pages)

Quoted 12 lines · Martin Gebert

In the example section of the page the following snippet is given:

--8><--

        void
        myfunc3(void)
        {
            int j, nptrs;
        #define SIZE 100
            void *buffer[100];
            char **strings;

            nptrs = backtrace(buffer, SIZE);

Quoted 6 lines

--><8--

Problems:

1. "#define SIZE 100" is not indented correctly.
2. SIZE should also be used for the buffer array size.

Thanks, Martin. Fixed as below.

Cheers,

Michael

man3/backtrace.3 +0 -0

index afca93d..064b970 100644

man3/backtrace.3 void · line 222

Quoted 10 lines

man3/backtrace.3 +2 -2

@@ -215,8 +215,8 @@ void
 myfunc3(void)
 {
     int j, nptrs;
-#define SIZE 100
-    void *buffer[100];
+    const int SIZE = 100;
+    void *buffer[SIZE];
     char **strings;
 
     nptrs = backtrace(buffer, SIZE);

I suggest leaving it as it was, apart from using SIZE in the definition of buffer.

It's common for preprocessor directives to be left-justified rather than aligned with the surrounding code. (They mostly appear at file scope, so it's not usually an issue.) It's perfectly valid to indent the #define, but it's a bit misleading, since it implies that SIZE has a scope (it doesn't, it's visible to the end of the translation unit).

With the "const int" declaration, buffer becomes a VLA (variable length array). VLAs don't exist in C90, do exist in C99, and are optional in C11.

The code won't compile with "gcc -pedantic-errors".

Hi Keith,

Quoted 53 lines · Keith Thompson

Quoted 31 lines · Michael Kerrisk (man-pages)

Quoted 12 lines · Martin Gebert

In the example section of the page the following snippet is given:

--8><--

        void
        myfunc3(void)
        {
            int j, nptrs;
        #define SIZE 100
            void *buffer[100];
            char **strings;

            nptrs = backtrace(buffer, SIZE);

Quoted 6 lines

--><8--

Problems:

1. "#define SIZE 100" is not indented correctly.
2. SIZE should also be used for the buffer array size.

Thanks, Martin. Fixed as below.

Cheers,

Michael

man3/backtrace.3 +0 -0

index afca93d..064b970 100644

man3/backtrace.3 void · line 222

Quoted 10 lines

man3/backtrace.3 +2 -2

@@ -215,8 +215,8 @@ void
 myfunc3(void)
 {
     int j, nptrs;
-#define SIZE 100
-    void *buffer[100];
+    const int SIZE = 100;
+    void *buffer[SIZE];
     char **strings;
 
     nptrs = backtrace(buffer, SIZE);

I suggest leaving it as it was, apart from using SIZE in the definition of buffer.

It's common for preprocessor directives to be left-justified rather than aligned with the surrounding code. (They mostly appear at file scope, so it's not usually an issue.) It's perfectly valid to indent the #define, but it's a bit misleading, since it implies that SIZE has a scope (it doesn't, it's visible to the end of the translation unit).

Quoted 3 lines

With the "const int" declaration, buffer becomes a VLA (variable length array). VLAs don't exist in C90, do exist in C99, and are optional in C11.

Ahhh -- I was not aware of the C11 detail.

Quoted 1 line

The code won't compile with "gcc -pedantic-errors".

Which gcc versions do that? I do not see such an error from gcc 5.3.

Cheers,

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

I suggest leaving it as it was, apart from using SIZE in the definition > of buffer. > > It's common for preprocessor directives to be

Hi Keith!

Quoted 1 line

I suggest leaving it as it was, apart from using SIZE in the definition > of buffer. > > It's common for preprocessor directives to be

left-justified rather > than aligned with the surrounding code. (They mostly appear at file > scope, so it's not usually an issue.) It's perfectly valid to indent > the #define, but it's a bit misleading, since it implies that SIZE has > a scope (it doesn't, it's visible to the end of the translation unit).

While I agree with you concerning the scope, I would then expect the SIZE macro be placed between the includes and the function header, as everything that has not a block scope. It just seems misplaced in the middle of the function (more exactly between the variable definitions), but outdented.
More generally, if somebody wants to make clear that a macro has only meaning in the local block I would prefer to place it there, but indent it with the rest of the code. If it's supposed to be used file-wide I would expect it before the first function, but without indention. IMHO the given code snippet is a wild mix that caught my eye as being quite unpleasing and unintuitive. So I suggest doing it the one /or/ the other way; I would've preferred Michael's solution in the first place, but obviously that's not universal enough for a man page.
And as a disclaimer, that's my built-in, intuitive style guide speaking, as I'm by no means an authority of C code formatting.