* [Patch] Clarify addr2line output in the manual
@ 2014-05-28 7:54 Tristan Gingold
2014-06-09 10:18 ` Ping: " Tristan Gingold
2014-06-09 16:45 ` Nicholas Clifton
0 siblings, 2 replies; 4+ messages in thread
From: Tristan Gingold @ 2014-05-28 7:54 UTC (permalink / raw)
To: binutils@sourceware.org Development
Hi,
I think the current description of addr2line in the manual is a little bit confusing.
But as I am not a native English speaker, please proof read my changes.
The sentence
The file name and line number for each input address is printed on separate lines.
is ambiguous, so I reformulate it.
The description for -i ("then the `{FUNCTIONNAME} FILENAME:LINENO' information for the inlining function will be displayed afterwards. This continues recursively until there is no more inlining to report.") is
not clear.
The combination of -a and -f (or -a and -i) is not clear.
The description of -p ("If the -p option is used then the output for each input address is displayed on one, possibly quite long, line.") isn't correct in presence of -i.
I hope my changes clarify the above points, feel free to comment.
Checked by make info in binutils/
Tristan.
binutils/
2014-05-28 Tristan Gingold <gingold@adacore.com>
* doc/binutils.texi: Clarify addr2line output.
diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi
index 3375d36..c22526d 100644
--- a/binutils/doc/binutils.texi
+++ b/binutils/doc/binutils.texi
@@ -3206,26 +3206,33 @@ standard input, and prints the file name and line number for each
address on standard output. In this mode, @command{addr2line} may be used
in a pipe to convert dynamically chosen addresses.
-The format of the output is @samp{FILENAME:LINENO}. The file name and
-line number for each input address is printed on separate lines.
+The format of the output is @samp{FILENAME:LINENO}. By default,
+each input address generates one line.
-If the @option{-f} option is used, then each @samp{FILENAME:LINENO}
-line is preceded by @samp{FUNCTIONNAME} which is the name of the
-function containing the address.
+Two options can generate additional lines before each
+@samp{FILENAME:LINENO} line (in that order).
+
+If the @option{-a} option is used then a line with the input address
+is displayed.
+
+If the @option{-f} option is used, then a line with the
+@samp{FUNCTIONNAME} is displayed. This is the name of the function
+containing the address.
+
+One option can generate additional lines after the
+@samp{FILENAME:LINENO} line.
If the @option{-i} option is used and the code at the given address is
-present there because of inlining by the compiler then the
-@samp{@{FUNCTIONNAME@} FILENAME:LINENO} information for the inlining
-function will be displayed afterwards. This continues recursively
-until there is no more inlining to report.
-
-If the @option{-a} option is used then the output is prefixed by the
-input address.
-
-If the @option{-p} option is used then the output for each input
-address is displayed on one, possibly quite long, line. If
-@option{-p} is not used then the output is broken up into multiple
-lines, based on the paragraphs above.
+present there because of inlining by the compiler then additional
+lines are displayed afterwards. One or two (if the @option{-f} option
+is used) are displayed for each inlined function.
+
+Finally, if the @option{-p} option is used then the input address, the
+function name, the filename and the line number are displayed on
+one, possibly quite long, line. If the @option{-i} is also used,
+an inlined function generate one additional line, prefixed with
+@samp{(inlined by)}. If @option{-p} is not used then the
+output is broken up into multiple lines, based on the paragraphs above.
If the file name or function name can not be determined,
@command{addr2line} will print two question marks in their place. If the
^ permalink raw reply [flat|nested] 4+ messages in thread
* Ping: [Patch] Clarify addr2line output in the manual
2014-05-28 7:54 [Patch] Clarify addr2line output in the manual Tristan Gingold
@ 2014-06-09 10:18 ` Tristan Gingold
2014-06-09 16:45 ` Nicholas Clifton
1 sibling, 0 replies; 4+ messages in thread
From: Tristan Gingold @ 2014-06-09 10:18 UTC (permalink / raw)
To: binutils@sourceware.org Development
Hi,
any review for a doco patch ?
Thanks,
Tristan.
On 28 May 2014, at 09:54, Tristan Gingold <gingold@adacore.com> wrote:
> Hi,
>
> I think the current description of addr2line in the manual is a little bit confusing.
> But as I am not a native English speaker, please proof read my changes.
>
> The sentence
> The file name and line number for each input address is printed on separate lines.
> is ambiguous, so I reformulate it.
>
> The description for -i ("then the `{FUNCTIONNAME} FILENAME:LINENO' information for the inlining function will be displayed afterwards. This continues recursively until there is no more inlining to report.") is
> not clear.
>
> The combination of -a and -f (or -a and -i) is not clear.
>
> The description of -p ("If the -p option is used then the output for each input address is displayed on one, possibly quite long, line.") isn't correct in presence of -i.
>
> I hope my changes clarify the above points, feel free to comment.
>
> Checked by make info in binutils/
>
> Tristan.
>
> binutils/
> 2014-05-28 Tristan Gingold <gingold@adacore.com>
>
> * doc/binutils.texi: Clarify addr2line output.
>
> diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi
> index 3375d36..c22526d 100644
> --- a/binutils/doc/binutils.texi
> +++ b/binutils/doc/binutils.texi
> @@ -3206,26 +3206,33 @@ standard input, and prints the file name and line number for each
> address on standard output. In this mode, @command{addr2line} may be used
> in a pipe to convert dynamically chosen addresses.
>
> -The format of the output is @samp{FILENAME:LINENO}. The file name and
> -line number for each input address is printed on separate lines.
> +The format of the output is @samp{FILENAME:LINENO}. By default,
> +each input address generates one line.
>
> -If the @option{-f} option is used, then each @samp{FILENAME:LINENO}
> -line is preceded by @samp{FUNCTIONNAME} which is the name of the
> -function containing the address.
> +Two options can generate additional lines before each
> +@samp{FILENAME:LINENO} line (in that order).
> +
> +If the @option{-a} option is used then a line with the input address
> +is displayed.
> +
> +If the @option{-f} option is used, then a line with the
> +@samp{FUNCTIONNAME} is displayed. This is the name of the function
> +containing the address.
> +
> +One option can generate additional lines after the
> +@samp{FILENAME:LINENO} line.
>
> If the @option{-i} option is used and the code at the given address is
> -present there because of inlining by the compiler then the
> -@samp{@{FUNCTIONNAME@} FILENAME:LINENO} information for the inlining
> -function will be displayed afterwards. This continues recursively
> -until there is no more inlining to report.
> -
> -If the @option{-a} option is used then the output is prefixed by the
> -input address.
> -
> -If the @option{-p} option is used then the output for each input
> -address is displayed on one, possibly quite long, line. If
> -@option{-p} is not used then the output is broken up into multiple
> -lines, based on the paragraphs above.
> +present there because of inlining by the compiler then additional
> +lines are displayed afterwards. One or two (if the @option{-f} option
> +is used) are displayed for each inlined function.
> +
> +Finally, if the @option{-p} option is used then the input address, the
> +function name, the filename and the line number are displayed on
> +one, possibly quite long, line. If the @option{-i} is also used,
> +an inlined function generate one additional line, prefixed with
> +@samp{(inlined by)}. If @option{-p} is not used then the
> +output is broken up into multiple lines, based on the paragraphs above.
>
> If the file name or function name can not be determined,
> @command{addr2line} will print two question marks in their place. If the
>
>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [Patch] Clarify addr2line output in the manual
2014-05-28 7:54 [Patch] Clarify addr2line output in the manual Tristan Gingold
2014-06-09 10:18 ` Ping: " Tristan Gingold
@ 2014-06-09 16:45 ` Nicholas Clifton
2014-07-03 15:33 ` Tristan Gingold
1 sibling, 1 reply; 4+ messages in thread
From: Nicholas Clifton @ 2014-06-09 16:45 UTC (permalink / raw)
To: Tristan Gingold, binutils@sourceware.org Development
Hi Tristan,
> I think the current description of addr2line in the manual is a little bit confusing.
> But as I am not a native English speaker, please proof read my changes.
OK - I have a couple of minor suggestions for improvements:
> +The format of the output is @samp{FILENAME:LINENO}. By default,
> +each input address generates one line.
I think that this would be clearer as:
The format of the output is @samp{FILENAME:LINENO}. By default
each input address generates one line of output.
> +One or two (if the @option{-f} option
> +is used) are displayed for each inlined function.
Would be clearer (imho) as:
One or two extra lines (if the @option{-f} option is used) are
displayed for each inlined function.
> +Finally, if the @option{-p} option is used then the input address, the
> +function name, the filename and the line number are displayed on
> +one, possibly quite long, line. If the @option{-i} is also used,
> +an inlined function generate one additional line, prefixed with
> +@samp{(inlined by)}. If @option{-p} is not used then the
> +output is broken up into multiple lines, based on the paragraphs above.
I find this paragraph to be a little bit complicated. How about this
instead:
Alternatively if the @option{-p} option is used then each input
address generates a single, long, output line containing the address,
the function name, the file name and the line number. If the
@option{-i} option has also been used then any inlined functions will
be displayed in the same manner, but on separate lines, and prefixed
by the text @samp{(inlined by)}.
Approved with these changes. If you want to make some other changes or
disagree with my suggestions then please repost with your version and I
will review again.
Cheers
Nick
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [Patch] Clarify addr2line output in the manual
2014-06-09 16:45 ` Nicholas Clifton
@ 2014-07-03 15:33 ` Tristan Gingold
0 siblings, 0 replies; 4+ messages in thread
From: Tristan Gingold @ 2014-07-03 15:33 UTC (permalink / raw)
To: Nicholas Clifton; +Cc: binutils@sourceware.org Development
On 09 Jun 2014, at 18:45, Nicholas Clifton <nickc@redhat.com> wrote:
> Hi Tristan,
>
>> I think the current description of addr2line in the manual is a little bit confusing.
>> But as I am not a native English speaker, please proof read my changes.
>
> OK - I have a couple of minor suggestions for improvements:
I'm late, but I have just committed using your wordings.
Thank you for the review.
Tristan.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2014-07-03 15:33 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-05-28 7:54 [Patch] Clarify addr2line output in the manual Tristan Gingold
2014-06-09 10:18 ` Ping: " Tristan Gingold
2014-06-09 16:45 ` Nicholas Clifton
2014-07-03 15:33 ` Tristan Gingold
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).