From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25739 invoked by alias); 19 Jan 2008 13:47:45 -0000 Received: (qmail 25725 invoked by uid 22791); 19 Jan 2008 13:47:42 -0000 X-Spam-Check-By: sourceware.org Received: from nitzan.inter.net.il (HELO nitzan.inter.net.il) (213.8.233.22) by sourceware.org (qpsmtpd/0.31) with ESMTP; Sat, 19 Jan 2008 13:47:15 +0000 Received: from HOME-C4E4A596F7 (IGLD-84-229-117-69.inter.net.il [84.229.117.69]) by nitzan.inter.net.il (MOS 3.7.3a-GA) with ESMTP id IXJ00173 (AUTH halo1); Sat, 19 Jan 2008 15:44:38 +0200 (IST) Date: Sat, 19 Jan 2008 13:47:00 -0000 Message-Id: From: Eli Zaretskii To: Jim Blandy CC: mark.kettenis@xs4all.nl, uweigand@de.ibm.com, brobecker@adacore.com, msnyder@specifix.com, gdb-patches@sourceware.org In-reply-to: (message from Jim Blandy on Thu, 17 Jan 2008 10:37:57 -0800) Subject: Re: [RFC/RFA?] Should break FILE:LINENO skip prologue? Reply-to: Eli Zaretskii References: <200801152140.m0FLeMha003566@d12av02.megacenter.de.ibm.com> <200801161034.m0GAYfpk000326@brahms.sibelius.xs4all.nl> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2008-01/txt/msg00490.txt.bz2 > Cc: mark.kettenis@xs4all.nl, uweigand@de.ibm.com, brobecker@adacore.com, > msnyder@specifix.com, gdb-patches@sourceware.org > From: Jim Blandy > Date: Thu, 17 Jan 2008 10:37:57 -0800 > > > Eli Zaretskii writes: > >> Cc: Mark Kettenis , uweigand@de.ibm.com, > >> brobecker@adacore.com, msnyder@specifix.com, > >> gdb-patches@sourceware.org > >> From: Jim Blandy > >> Date: Wed, 16 Jan 2008 13:36:11 -0800 > >> > >> GDB allows 'FILENAME'::FUNCTION in C expressions: > > > > Thanks. > > > > But if "break *'FILENAME'::FUNCTION" works, why is it wrong to expect > > that "break *FILENAME:FUNCTION" should also work. None of them is a > > valid C expression, it's just something GDB does to help the user, > > right? > > Our goal here is for GDB to provide memorable, predictable, terse ways > for people to describe locations for breakpoints, listings, and so on. > There should be terse, memorable ways to specify every form one needs > in daily use. The '*EXPRESSION' form is an escape hatch for those > cases that fall outside daily use. > > Setting breakpoints in functions before stack frame and argument setup > instructions is an obscure corner case that only people writing or > generating assembly code (say, compiler authors) or people working on > GDB need. The '*EXPRESSION' escape hatch syntax is adequate for such > users. > > To make 'break *FILENAME:FUNCTION' work, there are two approaches: > > - We could extend GDB's C grammar to treat 'FILENAME:FUNCTION' as a > valid expression. However, if not quoted, many FILENAMES would be > ambiguous with other C expressions --- for example, is foo.c a > filename, or a reference to the member 'c' of a structure or union > 'foo'? If that problem could be resolved, the use of ':' would > still be ambiguous with the ?: operator. > > - We could extend the linespec syntax to recognize > '*FILENAME:FUNCTION' specially, and not try to parse > 'FILENAME:FUNCTION' as an expression. > > But who does this serve? The people setting breakpoints at function > entry points won't find this helpful, as it just introduces > ambiguities and special cases into a grammar that already does the job > for them. And other users don't want to set breakpoints there. Okay, I'm obviously in disagreement here with several other maintainers, and I'm tired of arguing about this. So I went out and documented the current behavior with the patch below. Comments are welcome. Committed. 2008-01-19 Eli Zaretskii * gdb.texinfo (Specify Location): New section. (Delete Breaks, Edit, Set Breaks): Remove description of locations. Instead, add a reference to "Specify Location". (Machine Code, Jumping, Thread Stops, Continuing and Stepping) (Symbols): Refer to "Specify Location" for the valid forms of linespecs and locations. Index: gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.457 diff -u -r1.457 gdb.texinfo --- gdb.texinfo 12 Jan 2008 08:36:09 -0000 1.457 +++ gdb.texinfo 19 Jan 2008 13:35:53 -0000 @@ -2836,41 +2836,18 @@ Vars,, Convenience Variables}, for a discussion of what you can do with convenience variables. -You have several ways to say where the breakpoint should go. - @table @code -@item break @var{function} -Set a breakpoint at entry to function @var{function}. +@item break @var{location} +Set a breakpoint at the given @var{location}, which can specify a +function name, a line number, or an address of an instruction. +(@xref{Specify Location}, for a list of all the possible ways to +specify a @var{location}.) The breakpoint will stop your program just +before it executes any of the code in the specified @var{location}. + When using source languages that permit overloading of symbols, such as -C@t{++}, @var{function} may refer to more than one possible place to break. +C@t{++}, a function name may refer to more than one possible place to break. @xref{Breakpoint Menus,,Breakpoint Menus}, for a discussion of that situation. -@item break +@var{offset} -@itemx break -@var{offset} -Set a breakpoint some number of lines forward or back from the position -at which execution stopped in the currently selected @dfn{stack frame}. -(@xref{Frames, ,Frames}, for a description of stack frames.) - -@item break @var{linenum} -Set a breakpoint at line @var{linenum} in the current source file. -The current source file is the last file whose source text was printed. -The breakpoint will stop your program just before it executes any of the -code on that line. - -@item break @var{filename}:@var{linenum} -Set a breakpoint at line @var{linenum} in source file @var{filename}. - -@item break @var{filename}:@var{function} -Set a breakpoint at entry to function @var{function} found in file -@var{filename}. Specifying a file name as well as a function name is -superfluous except when multiple files contain similarly named -functions. - -@item break *@var{address} -Set a breakpoint at address @var{address}. You can use this to set -breakpoints in parts of your program which do not have debugging -information or source files. - @item break When called without any arguments, @code{break} sets a breakpoint at the next instruction to be executed in the selected stack frame @@ -2926,7 +2903,6 @@ breakpoints @value{GDBN} will use, see @ref{set remote hardware-breakpoint-limit}. - @kindex thbreak @item thbreak @var{args} Set a hardware-assisted breakpoint enabled only for one stop. @var{args} @@ -3520,6 +3496,12 @@ the innermost frame is selected, this is a good way to delete a breakpoint where your program just stopped. +@item clear @var{location} +Delete any breakpoints set at the specified @var{location}. +@xref{Specify Location}, for the various forms of @var{location}; the +most useful ones are listed below: + +@table @code @item clear @var{function} @itemx clear @var{filename}:@var{function} Delete any breakpoints set at entry to the named @var{function}. @@ -3528,6 +3510,7 @@ @itemx clear @var{filename}:@var{linenum} Delete any breakpoints set at or within the code of the specified @var{linenum} of the specified @var{filename}. +@end table @cindex delete breakpoints @kindex delete @@ -4158,8 +4141,8 @@ @itemx u @var{location} Continue running your program until either the specified location is reached, or the current stack frame returns. @var{location} is any of -the forms of argument acceptable to @code{break} (@pxref{Set Breaks, -,Setting Breakpoints}). This form of the command uses breakpoints, and +the forms described in @ref{Specify Location}. +This form of the command uses temporary breakpoints, and hence is quicker than @code{until} without an argument. The specified location is actually reached only if it is in the current frame. This implies that @code{until} can be used to skip over recursive function @@ -4182,8 +4165,9 @@ @kindex advance @var{location} @itemx advance @var{location} Continue running the program up to the given @var{location}. An argument is -required, which should be of the same form as arguments for the @code{break} -command. Execution will also stop upon exit from the current stack +required, which should be of one of the forms described in +@ref{Specify Location}. +Execution will also stop upon exit from the current stack frame. This command is similar to @code{until}, but @code{advance} will not skip over recursive function calls, and the target location doesn't have to be in the same frame as the current one. @@ -4341,7 +4325,8 @@ @item break @var{linespec} thread @var{threadno} @itemx break @var{linespec} thread @var{threadno} if @dots{} @var{linespec} specifies source lines; there are several ways of -writing them, but the effect is always to specify some source line. +writing them (@pxref{Specify Location}), but the effect is always to +specify some source line. Use the qualifier @samp{thread @var{threadno}} with a breakpoint command to specify that you only want @value{GDBN} to stop the program when a @@ -4904,6 +4889,7 @@ @menu * List:: Printing source lines +* Specify Location:: How to specify code locations * Edit:: Editing source files * Search:: Searching source files * Source Path:: Specifying source directories @@ -4917,7 +4903,8 @@ @kindex l @r{(@code{list})} To print lines from a source file, use the @code{list} command (abbreviated @code{l}). By default, ten lines are printed. -There are several ways to specify what part of the file you want to print. +There are several ways to specify what part of the file you want to +print; see @ref{Specify Location}, for the full list. Here are the forms of the @code{list} command most commonly used: @@ -4962,10 +4949,11 @@ argument of @samp{-}; that argument is preserved in repetition so that each repetition moves up in the source file. -@cindex linespec In general, the @code{list} command expects you to supply zero, one or two @dfn{linespecs}. Linespecs specify source lines; there are several ways -of writing them, but the effect is always to specify some source line. +of writing them (@pxref{Specify Location}), but the effect is always +to specify some source line. + Here is a complete description of the possible arguments for @code{list}: @table @code @@ -4974,7 +4962,9 @@ @item list @var{first},@var{last} Print lines from @var{first} to @var{last}. Both arguments are -linespecs. +linespecs. When a @code{list} command has two linespecs, and the +source file of the second linespec is omitted, this refers to +the same source file as the first linespec. @item list ,@var{last} Print lines ending with @var{last}. @@ -4992,42 +4982,86 @@ As described in the preceding table. @end table -Here are the ways of specifying a single source line---all the -kinds of linespec. +@node Specify Location +@section Specifying a Location +@cindex specifying location +@cindex linespec -@table @code -@item @var{number} -Specifies line @var{number} of the current source file. -When a @code{list} command has two linespecs, this refers to -the same source file as the first linespec. +Several @value{GDBN} commands accept arguments that specify a location +of your program's code. Since @value{GDBN} is a source-level +debugger, a location usually specifies some line in the source code; +for that reason, locations are also known as @dfn{linespecs}. + +Here are all the different ways of specifying a code location that +@value{GDBN} understands: -@item +@var{offset} -Specifies the line @var{offset} lines after the last line printed. -When used as the second linespec in a @code{list} command that has -two, this specifies the line @var{offset} lines down from the -first linespec. +@table @code +@item @var{linenum} +Specifies the line number @var{linenum} of the current source file. @item -@var{offset} -Specifies the line @var{offset} lines before the last line printed. +@itemx +@var{offset} +Specifies the line @var{offset} lines before or after the @dfn{current +line}. For the @code{list} command, the current line is the last one +printed; for the breakpoint commands, this is the line at which +execution stopped in the currently selected @dfn{stack frame} +(@pxref{Frames, ,Frames}, for a description of stack frames.) When +used as the second of the two linespecs in a @code{list} command, +this specifies the line @var{offset} lines up or down from the first +linespec. -@item @var{filename}:@var{number} -Specifies line @var{number} in the source file @var{filename}. +@item @var{filename}:@var{linenum} +Specifies the line @var{linenum} in the source file @var{filename}. @item @var{function} Specifies the line that begins the body of the function @var{function}. -For example: in C, this is the line with the open brace. +For example, in C, this is the line with the open brace. @item @var{filename}:@var{function} -Specifies the line of the open-brace that begins the body of the -function @var{function} in the file @var{filename}. You only need the -file name with a function name to avoid ambiguity when there are -identically named functions in different source files. +Specifies the line that begins the body of the function @var{function} +in the file @var{filename}. You only need the file name with a +function name to avoid ambiguity when there are identically named +functions in different source files. @item *@var{address} -Specifies the line containing the program address @var{address}. -@var{address} may be any expression. +Specifies the program address @var{address}. For line-oriented +commands, such as @code{list} and @code{edit}, this specifies a source +line that contains @var{address}. For @code{break} and other +breakpoint oriented commands, this can be used to set breakpoints in +parts of your program which do not have debugging information or +source files. + +Here @var{address} may be any expression valid in the current working +language (@pxref{Languages, working language}) that specifies a code +address. As a convenience, @value{GDBN} extends the semantics of +expressions used in locations to cover the situations that frequently +happen during debugging. Here are the various forms of @var{address}: + +@table @code +@item @var{expression} +Any expression valid in the current working language. + +@item @var{funcaddr} +An address of a function or procedure derived from its name. In C, +C@t{++}, Java, Objective-C, Fortran, minimal, and assembly, this is +simply the function's name @var{function} (and actually a special case +of a valid expression). In Pascal and Modula-2, this is +@code{&@var{function}}. In Ada, this is @code{@var{function}'Address} +(although the Pascal form also works). + +This form specifies the address of the function's first instruction, +before the stack frame and arguments have been set up. + +@item '@var{filename}'::@var{funcaddr} +Like @var{funcaddr} above, but also specifies the name of the source +file explicitly. This is useful if the name of the function does not +specify the function unambiguously, e.g., if there are several +functions with identical names in different source files. +@end table + @end table + @node Edit @section Editing Source Files @cindex editing source files @@ -5039,32 +5073,24 @@ is invoked with the current line set to the active line in the program. Alternatively, there are several ways to specify what part of the file you -want to print if you want to see other parts of the program. - -Here are the forms of the @code{edit} command most commonly used: +want to print if you want to see other parts of the program: @table @code -@item edit -Edit the current source file at the active line number in the program. +@item edit @var{location} +Edit the source file specified by @code{location}. Editing starts at +that @var{location}, e.g., at the specified source line of the +specified file. @xref{Specify Location}, for all the possible forms +of the @var{location} argument; here are the forms of the @code{edit} +command most commonly used: +@table @code @item edit @var{number} Edit the current source file with @var{number} as the active line number. @item edit @var{function} Edit the file containing @var{function} at the beginning of its definition. +@end table -@item edit @var{filename}:@var{number} -Specifies line @var{number} in the source file @var{filename}. - -@item edit @var{filename}:@var{function} -Specifies the line that begins the body of the -function @var{function} in the file @var{filename}. You only need the -file name with a function name to avoid ambiguity when there are -identically named functions in different source files. - -@item edit *@var{address} -Specifies the line containing the program address @var{address}. -@var{address} may be any expression. @end table @subsection Choosing your Editor @@ -5335,8 +5361,7 @@ @item info line @var{linespec} Print the starting and ending addresses of the compiled code for source line @var{linespec}. You can specify source lines in any of -the ways understood by the @code{list} command (@pxref{List, ,Printing -Source Lines}). +the ways documented in @ref{Specify Location}. @end table For example, we can use @code{info line} to discover the location of @@ -10988,7 +11013,8 @@ List all the variables local to a particular scope. This command accepts a @var{location} argument---a function name, a source line, or an address preceded by a @samp{*}, and prints all the variables local -to the scope defined by that location. For example: +to the scope defined by that location. (@xref{Specify Location}, for +details about supported forms of @var{location}.) For example: @smallexample (@value{GDBP}) @b{info scope command_line_handler} @@ -11358,12 +11384,13 @@ @table @code @kindex jump @item jump @var{linespec} -Resume execution at line @var{linespec}. Execution stops again -immediately if there is a breakpoint there. @xref{List, ,Printing -Source Lines}, for a description of the different forms of -@var{linespec}. It is common practice to use the @code{tbreak} command -in conjunction with @code{jump}. @xref{Set Breaks, ,Setting -Breakpoints}. +@itemx jump @var{location} +Resume execution at line @var{linespec} or at address given by +@var{location}. Execution stops again immediately if there is a +breakpoint there. @xref{Specify Location}, for a description of the +different forms of @var{linespec} and @var{location}. It is common +practice to use the @code{tbreak} command in conjunction with +@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}. The @code{jump} command does not change the current stack frame, or the stack pointer, or the contents of any memory location or any @@ -11374,9 +11401,6 @@ confirmation if the specified line is not in the function currently executing. However, even bizarre results are predictable if you are well acquainted with the machine-language code of your program. - -@item jump *@var{address} -Resume execution at the instruction at address @var{address}. @end table @c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.