backtrace(3): Inconsistency and missing indentation

backtrace(3): Inconsistency and missing indentation

[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);
--><8--

Problems:

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

Thank you.

Martin

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: backtrace(3): Inconsistency and missing indentation

[Michael Kerrisk (man-pages)]

On 02/24/2016 10:26 AM, Martin Gebert wrote:
> 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.

Thanks, Martin. Fixed as below.

Cheers,

Michael

diff --git a/man3/backtrace.3 b/man3/backtrace.3
index afca93d..064b970 100644
--- a/man3/backtrace.3
+++ b/man3/backtrace.3
@@ -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);



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: backtrace(3): Inconsistency and missing indentation

[Keith Thompson]

On Fri, Feb 26, 2016 at 7:46 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On 02/24/2016 10:26 AM, Martin Gebert wrote:
>> 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.
>
> Thanks, Martin. Fixed as below.
>
> Cheers,
>
> Michael
>
> diff --git a/man3/backtrace.3 b/man3/backtrace.3
> index afca93d..064b970 100644
> --- a/man3/backtrace.3
> +++ b/man3/backtrace.3
> @@ -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".

Given the need to support C90, I suggest that the #define is still
the best way to define the constant.  You could use an enum hack:

    enum { size = 100 };
    void *buffer[size];

but that's a little obscure, and introduces an issue that's not
relevant to the backtrace() function.

-- 
Keith Thompson <Keith.S.Thompson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: backtrace(3): Inconsistency and missing indentation

[Michael Kerrisk (man-pages)]

Hi Keith,

On 02/26/2016 08:52 PM, Keith Thompson wrote:
> On Fri, Feb 26, 2016 at 7:46 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> On 02/24/2016 10:26 AM, Martin Gebert wrote:
>>> 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.
>>
>> Thanks, Martin. Fixed as below.
>>
>> Cheers,
>>
>> Michael
>>
>> diff --git a/man3/backtrace.3 b/man3/backtrace.3
>> index afca93d..064b970 100644
>> --- a/man3/backtrace.3
>> +++ b/man3/backtrace.3
>> @@ -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.  

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

> 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/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: backtrace(3): Inconsistency and missing indentation

[Keith Thompson]

Sorry, I meant "gcc -ansi -pedantic".

On Fri, Feb 26, 2016 at 12:35 PM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hi Keith,
>
> On 02/26/2016 08:52 PM, Keith Thompson wrote:
>> On Fri, Feb 26, 2016 at 7:46 AM, Michael Kerrisk (man-pages)
>> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>> On 02/24/2016 10:26 AM, Martin Gebert wrote:
>>>> 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.
>>>
>>> Thanks, Martin. Fixed as below.
>>>
>>> Cheers,
>>>
>>> Michael
>>>
>>> diff --git a/man3/backtrace.3 b/man3/backtrace.3
>>> index afca93d..064b970 100644
>>> --- a/man3/backtrace.3
>>> +++ b/man3/backtrace.3
>>> @@ -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.
>
> Ahhh -- I was not aware of the C11 detail.
>
>> 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/



-- 
Keith Thompson <Keith.S.Thompson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: backtrace(3): Inconsistency and missing indentation

[Martin Gebert]

Hi Keith!

> 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.

Cheers,

Martin
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: backtrace(3): Inconsistency and missing indentation

[Michael Kerrisk (man-pages)]

On 26 February 2016 at 22:08, Martin Gebert <Murphy.Gebert-Mmb7MZpHnFY@public.gmane.org> wrote:
> Hi Keith!
>
>> 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.

Okay, I made it

   Program source

       #include <execinfo.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       #define BT_BUF_SIZE 100

       void
       myfunc3(void)
       {
           int j, nptrs;
           void *buffer[BT_BUF_SIZE];
           char **strings;

           nptrs = backtrace(buffer, BT_BUF_SIZE);
       [...]

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html