* backtrace(3): Inconsistency and missing indentation
@ 2016-02-24 9:26 Martin Gebert
[not found] ` <56CD772C.8030606-Mmb7MZpHnFY@public.gmane.org>
0 siblings, 1 reply; 7+ messages in thread
From: Martin Gebert @ 2016-02-24 9:26 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: backtrace(3): Inconsistency and missing indentation
[not found] ` <56CD772C.8030606-Mmb7MZpHnFY@public.gmane.org>
@ 2016-02-26 15:46 ` Michael Kerrisk (man-pages)
[not found] ` <56D07349.10901-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
0 siblings, 1 reply; 7+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-02-26 15:46 UTC (permalink / raw)
To: Martin Gebert
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: backtrace(3): Inconsistency and missing indentation
[not found] ` <56D07349.10901-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
@ 2016-02-26 19:52 ` Keith Thompson
[not found] ` <CAAHpriNbkVCsH-mrVi97Y57ahw=6yO=kh+C7OuLzfQXrJiJO-Q-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
0 siblings, 1 reply; 7+ messages in thread
From: Keith Thompson @ 2016-02-26 19:52 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Martin Gebert, linux-man-u79uwXL29TY76Z2rM5mHXA, 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: backtrace(3): Inconsistency and missing indentation
[not found] ` <CAAHpriNbkVCsH-mrVi97Y57ahw=6yO=kh+C7OuLzfQXrJiJO-Q-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
@ 2016-02-26 20:35 ` Michael Kerrisk (man-pages)
[not found] ` <56D0B704.8050001-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
0 siblings, 1 reply; 7+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-02-26 20:35 UTC (permalink / raw)
To: Keith Thompson
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, Martin Gebert,
linux-man-u79uwXL29TY76Z2rM5mHXA, Keith Thompson
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: backtrace(3): Inconsistency and missing indentation
[not found] ` <56D0B704.8050001-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
@ 2016-02-26 20:41 ` Keith Thompson
2016-02-26 21:08 ` Martin Gebert
1 sibling, 0 replies; 7+ messages in thread
From: Keith Thompson @ 2016-02-26 20:41 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Martin Gebert, linux-man-u79uwXL29TY76Z2rM5mHXA, 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: backtrace(3): Inconsistency and missing indentation
[not found] ` <56D0B704.8050001-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2016-02-26 20:41 ` Keith Thompson
@ 2016-02-26 21:08 ` Martin Gebert
[not found] ` <56D0BEBD.50908-Mmb7MZpHnFY@public.gmane.org>
1 sibling, 1 reply; 7+ messages in thread
From: Martin Gebert @ 2016-02-26 21:08 UTC (permalink / raw)
To: Michael Kerrisk (man-pages), Keith Thompson
Cc: linux-man-u79uwXL29TY76Z2rM5mHXA, Keith Thompson
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: backtrace(3): Inconsistency and missing indentation
[not found] ` <56D0BEBD.50908-Mmb7MZpHnFY@public.gmane.org>
@ 2016-02-28 19:21 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 7+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-02-28 19:21 UTC (permalink / raw)
To: Martin Gebert; +Cc: Keith Thompson, linux-man, Keith Thompson
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
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2016-02-28 19:21 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-02-24 9:26 backtrace(3): Inconsistency and missing indentation Martin Gebert
[not found] ` <56CD772C.8030606-Mmb7MZpHnFY@public.gmane.org>
2016-02-26 15:46 ` Michael Kerrisk (man-pages)
[not found] ` <56D07349.10901-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2016-02-26 19:52 ` Keith Thompson
[not found] ` <CAAHpriNbkVCsH-mrVi97Y57ahw=6yO=kh+C7OuLzfQXrJiJO-Q-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2016-02-26 20:35 ` Michael Kerrisk (man-pages)
[not found] ` <56D0B704.8050001-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2016-02-26 20:41 ` Keith Thompson
2016-02-26 21:08 ` Martin Gebert
[not found] ` <56D0BEBD.50908-Mmb7MZpHnFY@public.gmane.org>
2016-02-28 19:21 ` Michael Kerrisk (man-pages)
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.