-symbol-list-lines doco update

-symbol-list-lines doco update

[Bob Rossi]

This documents several of the special case's that -symbol-list-lines
outputs.


2004-02-17  Bob Rossi  <bob@brasko.net>

    * gdb.texinfo (-symbol-list-lines): Add info about the special
        case's that this command outputs.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.195
diff -w -u -r1.195 gdb.texinfo
--- gdb.texinfo	17 Feb 2004 14:54:32 -0000	1.195
+++ gdb.texinfo	17 Feb 2004 15:35:21 -0000
@@ -17463,6 +17465,17 @@
 addresses for the given source filename.  The entries are sorted in
 ascending PC order.
 
+There are two interesting points to be mentioned here.
+
+- The line number can be returned as "0". The line number "0" means
+end-of-sequence. For example, PCs greater than 0x8048406 that
+don't have a new starting line do not belong to this line number table.
+
+- Also, entries can be duplicated when returned. This means the front end
+must be capable of receiving several PC/line entries with the same value.
+Duplicated line numbers are emitted by the compiler to mark, mostly,
+the ends of prologues.  Sometimes the prologue is zero-sized.
+
 @subsubheading @value{GDBN} Command
 
 There is no corresponding @value{GDBN} command.
@@ -17471,7 +17484,21 @@
 @smallexample
 (@value{GDBP})
 -symbol-list-lines basics.c
-^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
+^done,lines=[
+@{pc="0x080483e0",line="7"@},@{pc="0x080483e6",line="8"@},
+@{pc="0x080483ed",line="9"@},@{pc="0x080483f4",line="12"@},
+@{pc="0x08048400",line="13"@},@{pc="0x08048404",line="14"@},
+@{pc="0x08048404",line="14"@},@{pc="0x08048406",line="0"@},
+@{pc="0x08048408",line="16"@},@{pc="0x0804840e",line="17"@},
+@{pc="0x08048413",line="18"@},@{pc="0x08048415",line="0"@},
+@{pc="0x08048418",line="21"@},@{pc="0x0804841e",line="22"@},
+@{pc="0x0804842d",line="23"@},@{pc="0x0804842f",line="0"@},
+@{pc="0x08048430",line="26"@},@{pc="0x08048436",line="27"@},
+@{pc="0x08048449",line="28"@},@{pc="0x0804844b",line="0"@},
+@{pc="0x0804844c",line="31"@},@{pc="0x08048452",line="32"@},
+@{pc="0x0804846d",line="33"@},@{pc="0x08048488",line="35"@},
+@{pc="0x08048498",line="37"@},@{pc="0x0804849c",line="38"@},
+@{pc="0x0804849c",line="38"@},@{pc="0x080484a2",line="0"@}]
 (@value{GDBP})
 @end smallexample

Re: -symbol-list-lines doco update

[Eli Zaretskii]

> Date: Tue, 17 Feb 2004 10:43:39 -0500
> From: Bob Rossi <bob@brasko.net>
> 
> This documents several of the special case's that -symbol-list-lines
> outputs.

Thanks.  I have several comments about your Texinfo usage.

> +There are two interesting points to be mentioned here.
> +
> +- The line number can be returned as "0". The line number "0" means

Please use "@itemize @minus"  and "@item" here, like this:

  There are two interesting points to be mentioned here.

  @itemize @minus
  @item
  The line number can be returned as ``0''.  The line number ``0'' means

etc., I hope you get the point.  The Texinfo translators, like
makeinfo and TeX, will then take care of producing the "-" before
every @item, and will also indent the list so it looks pretty.

Note two other changes I made in the original text: "0" should be
``0'', and there should be 2 blanks after each period that ends a
sentence.  These are basic rules of Texinfo and should be observed
throughout.

> +For example, PCs greater than 0x8048406 that
> +don't have a new starting line do not belong to this line number table.

This sentence is confusing, I think: if I were a programmer of a front
end, I'd have hard time understanding what it means.  What ``line
number table'' are we talking about, and what does it mean that a PC
value ``does not belong'' to it?  Also, ``don't have a new starting
line'' is unclear, at least to me.

> +Duplicated line numbers are emitted by the compiler to mark, mostly,
> +the ends of prologues.

I think there's another noteworthy case where this happens: when
optimizations cause the code produced for some line be scattered
among the PC values.

Thanks again for taking time to write this up.

Re: -symbol-list-lines doco update

[Andrew Cagney]

> 
> Please use "@itemize @minus"  and "@item" here, like this:
> 
>   There are two interesting points to be mentioned here.
> 
>   @itemize @minus
>   @item

Eli, fyi, appears to 100% consistently use "@itemize @bullet". 
Shouldn't that be used here?

Andrew

Re: -symbol-list-lines doco update

[Bob Rossi]

> Please use "@itemize @minus"  and "@item" here, like this:
> 
>   There are two interesting points to be mentioned here.
> 
>   @itemize @minus
>   @item
>   The line number can be returned as ``0''.  The line number ``0'' means
> 
> etc., I hope you get the point.  The Texinfo translators, like
> makeinfo and TeX, will then take care of producing the "-" before
> every @item, and will also indent the list so it looks pretty.

Understood, thanks. Andrew, I will use @bullet.

> > +For example, PCs greater than 0x8048406 that
> > +don't have a new starting line do not belong to this line number table.

I don't even know what this means. That's why it's confusing. Maybe
Daniel can give us a better description, otherwise, I'll just put

The line number can be returned as ''0''.

I will resubmit this patch soon, if Daniel doesn't have a better
description.

Thanks,
Bob Rossi

Re: -symbol-list-lines doco update

[Daniel Jacobowitz]

On Tue, Feb 17, 2004 at 03:09:11PM -0500, Bob Rossi wrote:
> > Please use "@itemize @minus"  and "@item" here, like this:
> > 
> >   There are two interesting points to be mentioned here.
> > 
> >   @itemize @minus
> >   @item
> >   The line number can be returned as ``0''.  The line number ``0'' means
> > 
> > etc., I hope you get the point.  The Texinfo translators, like
> > makeinfo and TeX, will then take care of producing the "-" before
> > every @item, and will also indent the list so it looks pretty.
> 
> Understood, thanks. Andrew, I will use @bullet.
> 
> > > +For example, PCs greater than 0x8048406 that
> > > +don't have a new starting line do not belong to this line number table.
> 
> I don't even know what this means. That's why it's confusing. Maybe
> Daniel can give us a better description, otherwise, I'll just put
> 
> The line number can be returned as ''0''.
> 
> I will resubmit this patch soon, if Daniel doesn't have a better
> description.

I'm not especially good with documentation.  Let me see if I can
explain the comment, and then maybe you can think of a better way to
say it...

An entry in the line table is "starting PC" and "line".  But a line is
not a starting PC, it's a range of PC values from start to end.  The
end is taken from the next line entry in the table.  The line table:

	0x0	1
	0x4	2
	0x8	4
	0xc	0

means:
	line 1 from 0x0 to 0x3
	line 2 from 0x4 to 0x7
	line 4 from 0x8 to 0xb
	no line number information at 0xc

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

Re: -symbol-list-lines doco update

[Eli Zaretskii]

> Date: Tue, 17 Feb 2004 14:50:43 -0500
> From: Andrew Cagney <cagney@gnu.org>
> 
> Eli, fyi, appears to 100% consistently use "@itemize @bullet". 
> Shouldn't that be used here?

Consistency is a Good Thing, I agree.