X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=99e5248a89d0e6d69ef12d5fa2f6078353cf1eb9;hb=12453b93bd8de559235835300eac68118c4ade70;hp=dddc88b79e513c84574c9830c7d95d321a68b7a8;hpb=87f67dbac2c40477b490e0eb1c5fa6f275d60bba;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index dddc88b79e..99e5248a89 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 +@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 @c Free Software Foundation, Inc. @c @c %**start of header @@ -43,20 +43,10 @@ * Gdb: (gdb). The GNU debugger. @end direntry -@ifinfo -This file documents the @sc{gnu} debugger @value{GDBN}. - - -This is the @value{EDITION} Edition, of @cite{Debugging with -@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} -@ifset VERSION_PACKAGE -@value{VERSION_PACKAGE} -@end ifset -Version @value{GDBVN}. - -Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@* - 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@* - Free Software Foundation, Inc. +@copying +Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, +1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 +Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or @@ -68,7 +58,20 @@ and with the Back-Cover Texts as in (a) below. (a) The FSF's Back-Cover Text is: ``You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom.'' -@end ifinfo +@end copying + +@ifnottex +This file documents the @sc{gnu} debugger @value{GDBN}. + +This is the @value{EDITION} Edition, of @cite{Debugging with +@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} +@ifset VERSION_PACKAGE +@value{VERSION_PACKAGE} +@end ifset +Version @value{GDBVN}. + +@insertcopying +@end ifnottex @titlepage @title Debugging with @value{GDBN} @@ -90,25 +93,12 @@ developing GNU and promoting software freedom.'' @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, -1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006 -Free Software Foundation, Inc. -@sp 2 Published by the Free Software Foundation @* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA@* ISBN 1-882114-77-9 @* -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``Free Software'' and ``Free Software Needs -Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. - -(a) The FSF's Back-Cover Text is: ``You are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' +@insertcopying @page This edition of the GDB manual is dedicated to the memory of Fred Fish. Fred was a long-standing contributor to GDB and to Free @@ -129,7 +119,7 @@ This is the @value{EDITION} Edition, for @value{GDBN} @end ifset Version @value{GDBVN}. -Copyright (C) 1988-2006 Free Software Foundation, Inc. +Copyright (C) 1988-2009 Free Software Foundation, Inc. This edition of the GDB manual is dedicated to the memory of Fred Fish. Fred was a long-standing contributor to GDB and to Free @@ -143,6 +133,7 @@ software in general. We will miss him. * Commands:: @value{GDBN} commands * Running:: Running programs under @value{GDBN} * Stopping:: Stopping and continuing +* Reverse Execution:: Running programs backward * Stack:: Examining the stack * Source:: Examining source files * Data:: Examining data @@ -177,6 +168,8 @@ software in general. We will miss him. * Agent Expressions:: The GDB Agent Expression Mechanism * Target Descriptions:: How targets can describe themselves to @value{GDBN} +* Operating System Information:: Getting additional information from + the operating system * Copying:: GNU General Public License says how you can copy and share GDB * GNU Free Documentation License:: The license for this documentation @@ -1218,7 +1211,13 @@ Sets up the command interpreter as specified by the command line @item @cindex init file -Reads the @dfn{init file} (if any) in your home directory@footnote{On +Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was +used when building @value{GDBN}; @pxref{System-wide configuration, + ,System-wide configuration and settings}) and executes all the commands in +that file. + +@item +Reads the init file (if any) in your home directory@footnote{On DOS/Windows systems, the home directory is the one pointed to by the @code{HOME} environment variable.} and executes all the commands in that file. @@ -1251,6 +1250,9 @@ complaints}) that affect subsequent processing of command line options and operands. Init files are not executed if you use the @samp{-nx} option (@pxref{Mode Options, ,Choosing Modes}). +To display the list of init files loaded by gdb at startup, you +can use @kbd{gdb --help}. + @cindex init file name @cindex @file{.gdbinit} @cindex @file{gdb.ini} @@ -3642,16 +3644,6 @@ and @sc{gnu}/Linux. A call to @code{vfork}. This is currently only available for HP-UX and @sc{gnu}/Linux. -@item load -@itemx load @var{libname} -@cindex break on load/unload of shared library -The dynamic loading of any shared library, or the loading of the library -@var{libname}. This is currently only available for HP-UX. - -@item unload -@itemx unload @var{libname} -The unloading of any dynamically loaded shared library, or the unloading -of the library @var{libname}. This is currently only available for HP-UX. @end table @item tcatch @var{event} @@ -4042,40 +4034,9 @@ end @c @ifclear BARETARGET @node Error in Breakpoints @subsection ``Cannot insert breakpoints'' -@c -@c FIXME!! 14/6/95 Is there a real example of this? Let's use it. -@c -Under some operating systems, breakpoints cannot be used in a program if -any other process is running that program. In this situation, -attempting to run or continue a program with a breakpoint causes -@value{GDBN} to print an error message: - -@smallexample -Cannot insert breakpoints. -The same program may be running in another process. -@end smallexample -When this happens, you have three ways to proceed: - -@enumerate -@item -Remove or disable the breakpoints, then continue. - -@item -Suspend @value{GDBN}, and copy the file containing your program to a new -name. Resume @value{GDBN} and use the @code{exec-file} command to specify -that @value{GDBN} should run your program under that name. -Then start your program again. - -@item -Relink your program so that the text segment is nonsharable, using the -linker option @samp{-N}. The operating system limitation may not apply -to nonsharable executables. -@end enumerate -@c @end ifclear - -A similar message can be printed if you request too many active -hardware-assisted breakpoints and watchpoints: +If you request too many active hardware-assisted breakpoints and +watchpoints, you will see this error message: @c FIXME: the precise wording of this message may change; the relevant @c source change is not committed yet (Sep 3, 1999). @@ -4727,6 +4688,10 @@ are: @kindex next& @xref{Continuing and Stepping, next}. +@item nexti +@kindex nexti& +@xref{Continuing and Stepping, nexti}. + @item continue @kindex continue& @xref{Continuing and Stepping, continue}. @@ -4850,6 +4815,126 @@ When such an event happens, a system call in another thread may return prematurely, even though your program does not appear to stop. +@node Reverse Execution +@chapter Running programs backward +@cindex reverse execution +@cindex running programs backward + +When you are debugging a program, it is not unusual to realize that +you have gone too far, and some event of interest has already happened. +If the target environment supports it, @value{GDBN} can allow you to +``rewind'' the program by running it backward. + +A target environment that supports reverse execution should be able +to ``undo'' the changes in machine state that have taken place as the +program was executing normally. Variables, registers etc.@: should +revert to their previous values. Obviously this requires a great +deal of sophistication on the part of the target environment; not +all target environments can support reverse execution. + +When a program is executed in reverse, the instructions that +have most recently been executed are ``un-executed'', in reverse +order. The program counter runs backward, following the previous +thread of execution in reverse. As each instruction is ``un-executed'', +the values of memory and/or registers that were changed by that +instruction are reverted to their previous states. After executing +a piece of source code in reverse, all side effects of that code +should be ``undone'', and all variables should be returned to their +prior values@footnote{ +Note that some side effects are easier to undo than others. For instance, +memory and registers are relatively easy, but device I/O is hard. Some +targets may be able undo things like device I/O, and some may not. + +The contract between @value{GDBN} and the reverse executing target +requires only that the target do something reasonable when +@value{GDBN} tells it to execute backwards, and then report the +results back to @value{GDBN}. Whatever the target reports back to +@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN} +assumes that the memory and registers that the target reports are in a +consistant state, but @value{GDBN} accepts whatever it is given. +}. + +If you are debugging in a target environment that supports +reverse execution, @value{GDBN} provides the following commands. + +@table @code +@kindex reverse-continue +@kindex rc @r{(@code{reverse-continue})} +@item reverse-continue @r{[}@var{ignore-count}@r{]} +@itemx rc @r{[}@var{ignore-count}@r{]} +Beginning at the point where your program last stopped, start executing +in reverse. Reverse execution will stop for breakpoints and synchronous +exceptions (signals), just like normal execution. Behavior of +asynchronous signals depends on the target environment. + +@kindex reverse-step +@kindex rs @r{(@code{step})} +@item reverse-step @r{[}@var{count}@r{]} +Run the program backward until control reaches the start of a +different source line; then stop it, and return control to @value{GDBN}. + +Like the @code{step} command, @code{reverse-step} will only stop +at the beginning of a source line. It ``un-executes'' the previously +executed source line. If the previous source line included calls to +debuggable functions, @code{reverse-step} will step (backward) into +the called function, stopping at the beginning of the @emph{last} +statement in the called function (typically a return statement). + +Also, as with the @code{step} command, if non-debuggable functions are +called, @code{reverse-step} will run thru them backward without stopping. + +@kindex reverse-stepi +@kindex rsi @r{(@code{reverse-stepi})} +@item reverse-stepi @r{[}@var{count}@r{]} +Reverse-execute one machine instruction. Note that the instruction +to be reverse-executed is @emph{not} the one pointed to by the program +counter, but the instruction executed prior to that one. For instance, +if the last instruction was a jump, @code{reverse-stepi} will take you +back from the destination of the jump to the jump instruction itself. + +@kindex reverse-next +@kindex rn @r{(@code{reverse-next})} +@item reverse-next @r{[}@var{count}@r{]} +Run backward to the beginning of the previous line executed in +the current (innermost) stack frame. If the line contains function +calls, they will be ``un-executed'' without stopping. Starting from +the first line of a function, @code{reverse-next} will take you back +to the caller of that function, @emph{before} the function was called, +just as the normal @code{next} command would take you from the last +line of a function back to its return to its caller +@footnote{Unles the code is too heavily optimized.}. + +@kindex reverse-nexti +@kindex rni @r{(@code{reverse-nexti})} +@item reverse-nexti @r{[}@var{count}@r{]} +Like @code{nexti}, @code{reverse-nexti} executes a single instruction +in reverse, except that called functions are ``un-executed'' atomically. +That is, if the previously executed instruction was a return from +another instruction, @code{reverse-nexti} will continue to execute +in reverse until the call to that function (from the current stack +frame) is reached. + +@kindex reverse-finish +@item reverse-finish +Just as the @code{finish} command takes you to the point where the +current function returns, @code{reverse-finish} takes you to the point +where it was called. Instead of ending up at the end of the current +function invocation, you end up at the beginning. + +@kindex set exec-direction +@item set exec-direction +Set the direction of target execution. +@itemx set exec-direction reverse +@cindex execute forward or backward in time +@value{GDBN} will perform all execution commands in reverse, until the +exec-direction mode is changed to ``forward''. Affected commands include +@code{step, stepi, next, nexti, continue, and finish}. The @code{return} +command cannot be used in reverse mode. +@item set exec-direction forward +@value{GDBN} will perform all execution commands in the normal fashion. +This is the default. +@end table + @node Stack @chapter Examining the Stack @@ -7484,6 +7569,18 @@ most appropriate form for a recognized tag, and in hexadecimal for an unrecognized tag. @end table +On some targets, @value{GDBN} can access operating-system-specific information +and display it to user, without interpretation. For remote targets, +this functionality depends on the remote stub's support of the +@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}. + +@table @code +@kindex info os processes +@item info os processes +Display the list of processes on the target. For each process, +@value{GDBN} prints the process identifier, the name of the user, and +the command corresponding to the process. +@end table @node Memory Region Attributes @section Memory Region Attributes @@ -11023,9 +11120,9 @@ index bounds, and all built-in functions and procedures. @vindex colon-colon@r{, in Modula-2} @c Info cannot handle :: but TeX can. @end ifinfo -@iftex +@ifnotinfo @vindex ::@r{, in Modula-2} -@end iftex +@end ifnotinfo There are a few subtle differences between the Modula-2 scope operator (@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have @@ -11094,6 +11191,8 @@ to be difficult. * Omissions from Ada:: Restrictions on the Ada expression syntax. * Additions to Ada:: Extensions of the Ada expression syntax. * Stopping Before Main Program:: Debugging the program during elaboration. +* Ada Tasks:: Listing and setting breakpoints in tasks. +* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files * Ada Glitches:: Known peculiarities of Ada mode. @end menu @@ -11207,12 +11306,12 @@ There is limited support for array and record aggregates. They are permitted only on the right sides of assignments, as in these examples: @smallexample -set An_Array := (1, 2, 3, 4, 5, 6) -set An_Array := (1, others => 0) -set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) -set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) -set A_Record := (1, "Peter", True); -set A_Record := (Name => "Peter", Id => 1, Alive => True) +(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6) +(@value{GDBP}) set An_Array := (1, others => 0) +(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) +(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) +(@value{GDBP}) set A_Record := (1, "Peter", True); +(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True) @end smallexample Changing a @@ -11234,8 +11333,8 @@ you can assign a value with a different size of @code{Vals} with two assignments: @smallexample -set A_Rec.Len := 4 -set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) +(@value{GDBP}) set A_Rec.Len := 4 +(@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) @end smallexample As this example also illustrates, @value{GDBN} is very loose about the usual @@ -11321,8 +11420,8 @@ The assignment statement is allowed as an expression, returning its right-hand operand as its value. Thus, you may enter @smallexample -set x := y + 3 -print A(tmp := y + 1) +(@value{GDBP}) set x := y + 3 +(@value{GDBP}) print A(tmp := y + 1) @end smallexample @item @@ -11332,8 +11431,8 @@ This allows, for example, complex conditional breaks: @smallexample -break f -condition 1 (report(i); k += 1; A(k) > 100) +(@value{GDBP}) break f +(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100) @end smallexample @item @@ -11357,7 +11456,7 @@ The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and to write @smallexample -print 'max(x, y) +(@value{GDBP}) print 'max(x, y) @end smallexample @item @@ -11390,7 +11489,7 @@ For the rare occasions when you actually have to look at them, enclose them in angle brackets to avoid the lower-case mapping. For example, @smallexample -@value{GDBP} print [0] +(@value{GDBP}) print [0] @end smallexample @item @@ -11414,6 +11513,187 @@ Manual, the elaboration code is invoked from a procedure called elaboration, simply use the following two commands: @code{tbreak adainit} and @code{run}. +@node Ada Tasks +@subsubsection Extensions for Ada Tasks +@cindex Ada, tasking + +Support for Ada tasks is analogous to that for threads (@pxref{Threads}). +@value{GDBN} provides the following task-related commands: + +@table @code +@kindex info tasks +@item info tasks +This command shows a list of current Ada tasks, as in the following example: + + +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 8088000 0 15 Child Activation Wait main_task + 2 80a4000 1 15 Accept Statement b + 3 809a800 1 15 Child Activation Wait a +* 4 80ae800 3 15 Running c + +@end smallexample + +@noindent +In this listing, the asterisk before the last task indicates it to be the +task currently being inspected. + +@table @asis +@item ID +Represents @value{GDBN}'s internal task number. + +@item TID +The Ada task ID. + +@item P-ID +The parent's task ID (@value{GDBN}'s internal task number). + +@item Pri +The base priority of the task. + +@item State +Current state of the task. + +@table @code +@item Unactivated +The task has been created but has not been activated. It cannot be +executing. + +@item Running +The task currently running. + +@item Runnable +The task is not blocked for any reason known to Ada. (It may be waiting +for a mutex, though.) It is conceptually "executing" in normal mode. + +@item Terminated +The task is terminated, in the sense of ARM 9.3 (5). Any dependents +that were waiting on terminate alternatives have been awakened and have +terminated themselves. + +@item Child Activation Wait +The task is waiting for created tasks to complete activation. + +@item Accept Statement +The task is waiting on an accept or selective wait statement. + +@item Waiting on entry call +The task is waiting on an entry call. + +@item Async Select Wait +The task is waiting to start the abortable part of an asynchronous +select statement. + +@item Delay Sleep +The task is waiting on a select statement with only a delay +alternative open. + +@item Child Termination Wait +The task is sleeping having completed a master within itself, and is +waiting for the tasks dependent on that master to become terminated or +waiting on a terminate Phase. + +@item Wait Child in Term Alt +The task is sleeping waiting for tasks on terminate alternatives to +finish terminating. + +@item Accepting RV with @var{taskno} +The task is accepting a rendez-vous with the task @var{taskno}. +@end table + +@item Name +Name of the task in the program. + +@end table + +@kindex info task @var{taskno} +@item info task @var{taskno} +This command shows detailled informations on the specified task, as in +the following example: +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 8077880 0 15 Child Activation Wait main_task +* 2 807c468 1 15 Running task_1 +(@value{GDBP}) info task 2 +Ada Task: 0x807c468 +Name: task_1 +Thread: 0x807f378 +Parent: 1 (main_task) +Base Priority: 15 +State: Runnable +@end smallexample + +@item task +@kindex task@r{ (Ada)} +@cindex current Ada task ID +This command prints the ID of the current task. + +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task +* 2 807c458 1 15 Running t +(@value{GDBP}) task +[Current task is 2] +@end smallexample + +@item task @var{taskno} +@cindex Ada task switching +This command is like the @code{thread @var{threadno}} +command (@pxref{Threads}). It switches the context of debugging +from the current task to the given task. + +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task +* 2 807c458 1 15 Running t +(@value{GDBP}) task 1 +[Switching to task 1] +#0 0x8067726 in pthread_cond_wait () +(@value{GDBP}) bt +#0 0x8067726 in pthread_cond_wait () +#1 0x8056714 in system.os_interface.pthread_cond_wait () +#2 0x805cb63 in system.task_primitives.operations.sleep () +#3 0x806153e in system.tasking.stages.activate_tasks () +#4 0x804aacc in un () at un.adb:5 +@end smallexample + +@end table + +@node Ada Tasks and Core Files +@subsubsection Tasking Support when Debugging Core Files +@cindex Ada tasking and core file debugging + +When inspecting a core file, as opposed to debugging a live program, +tasking support may be limited or even unavailable, depending on +the platform being used. +For instance, on x86-linux, the list of tasks is available, but task +switching is not supported. On Tru64, however, task switching will work +as usual. + +On certain platforms, including Tru64, the debugger needs to perform some +memory writes in order to provide Ada tasking support. When inspecting +a core file, this means that the core file must be opened with read-write +privileges, using the command @samp{"set write on"} (@pxref{Patching}). +Under these circumstances, you should make a backup copy of the core +file before inspecting it with @value{GDBN}. + @node Ada Glitches @subsubsection Known Peculiarities of Ada Mode @cindex Ada, problems @@ -11448,9 +11728,6 @@ Fixed-point arithmetic, conversions, input, and output is carried out using floating-point arithmetic, and may give results that only approximate those on the host machine. -@item -The type of the @t{'Address} attribute may not be @code{System.Address}. - @item The GNAT compiler never generates the prefix @code{Standard} for any of the standard symbols defined by the Ada language. @value{GDBN} knows about @@ -11562,6 +11839,16 @@ _initialize_vx + 396 in section .text This is the opposite of the @code{info address} command. You can use it to find out the name of a variable or a function given its address. +For dynamically linked executables, the name of executable or shared +library containing the symbol is also printed: + +@smallexample +(@value{GDBP}) info symbol 0x400225 +_start + 5 in section .text of /tmp/a.out +(@value{GDBP}) info symbol 0x2aaaac2811cf +__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 +@end smallexample + @kindex whatis @item whatis [@var{arg}] Print the data type of @var{arg}, which can be either an expression or @@ -12218,7 +12505,7 @@ repairs. @item set write on @itemx set write off If you specify @samp{set write on}, @value{GDBN} opens executable and -core files for both reading and writing; if you specify @samp{set write +core files for both reading and writing; if you specify @kbd{set write off} (the default), @value{GDBN} opens them read-only. If you have already loaded a file, you must load it again (using the @@ -13707,10 +13994,11 @@ You can terminate it by using @code{monitor exit} @subsubsection Other Command-Line Arguments for @code{gdbserver} -You can include @option{--debug} on the @code{gdbserver} command line. -@code{gdbserver} will display extra status information about the debugging -process. This option is intended for @code{gdbserver} development and -for bug reports to the developers. +The @option{--debug} option tells @code{gdbserver} to display extra +status information about the debugging process. The +@option{--remote-debug} option tells @code{gdbserver} to display +remote protocol debug output. These options are intended for +@code{gdbserver} development and for bug reports to the developers. The @option{--wrapper} option specifies a wrapper to launch programs for debugging. The option should be followed by the name of the @@ -13891,6 +14179,36 @@ Select the file used for @code{run} with @code{target extended-remote}. This should be set to a filename valid on the target system. If it is not set, the target will use a default filename (e.g.@: the last program run). + +@kindex set tcp +@kindex show tcp +@item set tcp auto-retry on +@cindex auto-retry, for remote TCP target +Enable auto-retry for remote TCP connections. This is useful if the remote +debugging agent is launched in parallel with @value{GDBN}; there is a race +condition because the agent may not become ready to accept the connection +before @value{GDBN} attempts to connect. When auto-retry is +enabled, if the initial attempt to connect fails, @value{GDBN} reattempts +to establish the connection using the timeout specified by +@code{set tcp connect-timeout}. + +@item set tcp auto-retry off +Do not auto-retry failed TCP connections. + +@item show tcp auto-retry +Show the current auto-retry setting. + +@item set tcp connect-timeout @var{seconds} +@cindex connection timeout, for remote TCP target +@cindex timeout, for remote target connection +Set the timeout for establishing a TCP connection to the remote target to +@var{seconds}. The timeout affects both polling to retry failed connections +(enabled by @code{set tcp auto-retry on}) and waiting for connections +that are merely slow to complete, and represents an approximate cumulative +value. + +@item show tcp connect-timeout +Show the current connection timeout setting. @end table @cindex remote packets, enabling and disabling @@ -14028,6 +14346,10 @@ are: @item @code{noack-packet} @tab @code{QStartNoAckMode} @tab Packet acknowledgment + +@item @code{osdata} +@tab @code{qXfer:osdata:read} +@tab @code{info os} @end multitable @node Remote Stub @@ -14371,6 +14693,7 @@ configurations. * Cygwin Native:: Features specific to the Cygwin port * Hurd Native:: Features specific to @sc{gnu} Hurd * Neutrino:: Features specific to QNX Neutrino +* Darwin:: Features specific to Darwin @end menu @node HP-UX @@ -15152,6 +15475,48 @@ Neutrino support. Show the current state of QNX Neutrino messages. @end table +@node Darwin +@subsection Darwin +@cindex Darwin + +@value{GDBN} provides the following commands specific to the Darwin target: + +@table @code +@item set debug darwin @var{num} +@kindex set debug darwin +When set to a non zero value, enables debugging messages specific to +the Darwin support. Higher values produce more verbose output. + +@item show debug darwin +@kindex show debug darwin +Show the current state of Darwin messages. + +@item set debug mach-o @var{num} +@kindex set debug mach-o +When set to a non zero value, enables debugging messages while +@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the +file format used on Darwin for object and executable files.) Higher +values produce more verbose output. This is a command to diagnose +problems internal to @value{GDBN} and should not be needed in normal +usage. + +@item show debug mach-o +@kindex show debug mach-o +Show the current state of Mach-O file messages. + +@item set mach-exceptions on +@itemx set mach-exceptions off +@kindex set mach-exceptions +On Darwin, faults are first reported as a Mach exception and are then +mapped to a Posix signal. Use this command to turn on trapping of +Mach exceptions in the inferior. This might be sometimes useful to +better understand the cause of a fault. The default is off. + +@item show mach-exceptions +@kindex show mach-exceptions +Show the current state of exceptions trapping. +@end table + @node Embedded OS @section Embedded Operating Systems @@ -17019,6 +17384,13 @@ Display debugging messages about inner workings of the AIX thread module. @item show debug aix-thread Show the current state of AIX thread debugging info display. +@item set debug dwarf2-die +@cindex DWARF2 DIEs +Dump DWARF2 DIEs after they are read in. +The value is the number of nesting levels to print. +A value of zero turns off the display. +@item show debug dwarf2-die +Show the current state of DWARF2 DIE debugging. @item set debug displaced @cindex displaced stepping debugging info Turns on or off display of @value{GDBN} debugging info for the @@ -17215,6 +17587,10 @@ end @item define @var{commandname} Define a command named @var{commandname}. If there is already a command by that name, you are asked to confirm that you want to redefine it. +@var{commandname} may be a bare command name consisting of letters, +numbers, dashes, and underscores. It may also start with any predefined +prefix command. For example, @samp{define target my-target} creates +a user-defined @samp{target my-target} command. The definition of the command is made up of other @value{GDBN} command lines, which are given following the @code{define} command. The end of these @@ -17349,6 +17725,10 @@ not for command aliases; you should define a hook for the basic command name, e.g.@: @code{backtrace} rather than @code{bt}. @c FIXME! So how does Joe User discover whether a command is an alias @c or not? +You can hook a multi-word command by adding @code{hook-} or +@code{hookpost-} to the last word of the command, e.g.@: +@samp{define target hook-remote} to add a hook to @samp{target remote}. + If an error occurs during the execution of your hook, execution of @value{GDBN} commands stops and @value{GDBN} issues a prompt (before the command that you actually typed had a chance to run). @@ -17683,6 +18063,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. @menu * Basic Python:: Basic Python Functions. * Exception Handling:: +* Values From Inferior:: @end menu @node Basic Python @@ -17697,11 +18078,15 @@ methods and classes added by @value{GDBN} are placed in this module. use in all scripts evaluated by the @code{python} command. @findex gdb.execute -@defun execute command +@defun execute command [from_tty] Evaluate @var{command}, a string, as a @value{GDBN} CLI command. If a GDB exception happens while @var{command} runs, it is translated as described in @ref{Exception Handling,,Exception Handling}. If no exceptions occur, this function returns @code{None}. + +@var{from_tty} specifies whether @value{GDBN} ought to consider this +command as having originated from the user invoking it interactively. +It must be a boolean value. If omitted, it defaults to @code{False}. @end defun @findex gdb.get_parameter @@ -17716,6 +18101,21 @@ If the named parameter does not exist, this function throws a a Python value of the appropriate type, and returned. @end defun +@findex gdb.history +@defun history number +Return a value from @value{GDBN}'s value history (@pxref{Value +History}). @var{number} indicates which history element to return. +If @var{number} is negative, then @value{GDBN} will take its absolute value +and count backward from the last element (i.e., the most recent element) to +find the value to return. If @var{number} is zero, then @value{GDBN} will +return the most recent element. If the element specified by @value{number} +doesn't exist in the value history, a @code{RuntimeError} exception will be +raised. + +If no exception is raised, the return value is always an instance of +@code{gdb.Value} (@pxref{Values From Inferior}). +@end defun + @findex gdb.write @defun write string Print a string to @value{GDBN}'s paginated standard output stream. @@ -17761,6 +18161,64 @@ message as its value, and the Python call stack backtrace at the Python statement closest to where the @value{GDBN} error occured as the traceback. +@node Values From Inferior +@subsubsection Values From Inferior +@cindex values from inferior, with Python +@cindex python, working with values from inferior + +@cindex @code{gdb.Value} +@value{GDBN} provides values it obtains from the inferior program in +an object of type @code{gdb.Value}. @value{GDBN} uses this object +for its internal bookkeeping of the inferior's values, and for +fetching values when necessary. + +Inferior values that are simple scalars can be used directly in +Python expressions that are valid for the value's data type. Here's +an example for an integer or floating-point value @code{some_val}: + +@smallexample +bar = some_val + 2 +@end smallexample + +@noindent +As result of this, @code{bar} will also be a @code{gdb.Value} object +whose values are of the same type as those of @code{some_val}. + +Inferior values that are structures or instances of some class can +be accessed using the Python @dfn{dictionary syntax}. For example, if +@code{some_val} is a @code{gdb.Value} instance holding a structure, you +can access its @code{foo} element with: + +@smallexample +bar = some_val['foo'] +@end smallexample + +Again, @code{bar} will also be a @code{gdb.Value} object. + +For pointer data types, @code{gdb.Value} provides a method for +dereferencing the pointer to obtain the object it points to. + +@defmethod Value dereference +This method returns a new @code{gdb.Value} object whose contents is +the object pointed to by the pointer. For example, if @code{foo} is +a C pointer to an @code{int}, declared in your C program as + +@smallexample +int *foo; +@end smallexample + +@noindent +then you can use the corresponding @code{gdb.Value} to access what +@code{foo} points to like this: + +@smallexample +bar = foo.dereference () +@end smallexample + +The result @code{bar} will be a @code{gdb.Value} object holding the +value pointed to by @code{foo}. +@end defmethod + @node Interpreters @chapter Command Interpreters @cindex command interpreters @@ -18446,6 +18904,7 @@ may repeat one or more times. @end ignore @menu +* GDB/MI General Design:: * GDB/MI Command Syntax:: * GDB/MI Compatibility with CLI:: * GDB/MI Development and Front Ends:: @@ -18472,6 +18931,181 @@ may repeat one or more times. * GDB/MI Miscellaneous Commands:: @end menu +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI General Design +@section @sc{gdb/mi} General Design +@cindex GDB/MI General Design + +Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three +parts---commands sent to @value{GDBN}, responses to those commands +and notifications. Each command results in exactly one response, +indicating either successful completion of the command, or an error. +For the commands that do not resume the target, the response contains the +requested information. For the commands that resume the target, the +response only indicates whether the target was successfully resumed. +Notifications is the mechanism for reporting changes in the state of the +target, or in @value{GDBN} state, that cannot conveniently be associated with +a command and reported as part of that command response. + +The important examples of notifications are: +@itemize @bullet + +@item +Exec notifications. These are used to report changes in +target state---when a target is resumed, or stopped. It would not +be feasible to include this information in response of resuming +commands, because one resume commands can result in multiple events in +different threads. Also, quite some time may pass before any event +happens in the target, while a frontend needs to know whether the resuming +command itself was successfully executed. + +@item +Console output, and status notifications. Console output +notifications are used to report output of CLI commands, as well as +diagnostics for other commands. Status notifications are used to +report the progress of a long-running operation. Naturally, including +this information in command response would mean no output is produced +until the command is finished, which is undesirable. + +@item +General notifications. Commands may have various side effects on +the @value{GDBN} or target state beyond their official purpose. For example, +a command may change the selected thread. Although such changes can +be included in command response, using notification allows for more +orthogonal frontend design. + +@end itemize + +There's no guarantee that whenever an MI command reports an error, +@value{GDBN} or the target are in any specific state, and especially, +the state is not reverted to the state before the MI command was +processed. Therefore, whenever an MI command results in an error, +we recommend that the frontend refreshes all the information shown in +the user interface. + +@subsection Context management + +In most cases when @value{GDBN} accesses the target, this access is +done in context of a specific thread and frame (@pxref{Frames}). +Often, even when accessing global data, the target requires that a thread +be specified. The CLI interface maintains the selected thread and frame, +and supplies them to target on each command. This is convenient, +because a command line user would not want to specify that information +explicitly on each command, and because user interacts with +@value{GDBN} via a single terminal, so no confusion is possible as +to what thread and frame are the current ones. + +In the case of MI, the concept of selected thread and frame is less +useful. First, a frontend can easily remember this information +itself. Second, a graphical frontend can have more than one window, +each one used for debugging a different thread, and the frontend might +want to access additional threads for internal purposes. This +increases the risk that by relying on implicitly selected thread, the +frontend may be operating on a wrong one. Therefore, each MI command +should explicitly specify which thread and frame to operate on. To +make it possible, each MI command accepts the @samp{--thread} and +@samp{--frame} options, the value to each is @value{GDBN} identifier +for thread and frame to operate on. + +Usually, each top-level window in a frontend allows the user to select +a thread and a frame, and remembers the user selection for further +operations. However, in some cases @value{GDBN} may suggest that the +current thread be changed. For example, when stopping on a breakpoint +it is reasonable to switch to the thread where breakpoint is hit. For +another example, if the user issues the CLI @samp{thread} command via +the frontend, it is desirable to change the frontend's selected thread to the +one specified by user. @value{GDBN} communicates the suggestion to +change current thread using the @samp{=thread-selected} notification. +No such notification is available for the selected frame at the moment. + +Note that historically, MI shares the selected thread with CLI, so +frontends used the @code{-thread-select} to execute commands in the +right context. However, getting this to work right is cumbersome. The +simplest way is for frontend to emit @code{-thread-select} command +before every command. This doubles the number of commands that need +to be sent. The alternative approach is to suppress @code{-thread-select} +if the selected thread in @value{GDBN} is supposed to be identical to the +thread the frontend wants to operate on. However, getting this +optimization right can be tricky. In particular, if the frontend +sends several commands to @value{GDBN}, and one of the commands changes the +selected thread, then the behaviour of subsequent commands will +change. So, a frontend should either wait for response from such +problematic commands, or explicitly add @code{-thread-select} for +all subsequent commands. No frontend is known to do this exactly +right, so it is suggested to just always pass the @samp{--thread} and +@samp{--frame} options. + +@subsection Asynchronous command execution and non-stop mode + +On some targets, @value{GDBN} is capable of processing MI commands +even while the target is running. This is called @dfn{asynchronous +command execution} (@pxref{Background Execution}). The frontend may +specify a preferrence for asynchronous execution using the +@code{-gdb-set target-async 1} command, which should be emitted before +either running the executable or attaching to the target. After the +frontend has started the executable or attached to the target, it can +find if asynchronous execution is enabled using the +@code{-list-target-features} command. + +Even if @value{GDBN} can accept a command while target is running, +many commands that access the target do not work when the target is +running. Therefore, asynchronous command execution is most useful +when combined with non-stop mode (@pxref{Non-Stop Mode}). Then, +it is possible to examine the state of one thread, while other threads +are running. + +When a given thread is running, MI commands that try to access the +target in the context of that thread may not work, or may work only on +some targets. In particular, commands that try to operate on thread's +stack will not work, on any target. Commands that read memory, or +modify breakpoints, may work or not work, depending on the target. Note +that even commands that operate on global state, such as @code{print}, +@code{set}, and breakpoint commands, still access the target in the +context of a specific thread, so frontend should try to find a +stopped thread and perform the operation on that thread (using the +@samp{--thread} option). + +Which commands will work in the context of a running thread is +highly target dependent. However, the two commands +@code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, +to find the state of a thread, will always work. + +@subsection Thread groups +@value{GDBN} may be used to debug several processes at the same time. +On some platfroms, @value{GDBN} may support debugging of several +hardware systems, each one having several cores with several different +processes running on each core. This section describes the MI +mechanism to support such debugging scenarios. + +The key observation is that regardless of the structure of the +target, MI can have a global list of threads, because most commands that +accept the @samp{--thread} option do not need to know what process that +thread belongs to. Therefore, it is not necessary to introduce +neither additional @samp{--process} option, nor an notion of the +current process in the MI interface. The only strictly new feature +that is required is the ability to find how the threads are grouped +into processes. + +To allow the user to discover such grouping, and to support arbitrary +hierarchy of machines/cores/processes, MI introduces the concept of a +@dfn{thread group}. Thread group is a collection of threads and other +thread groups. A thread group always has a string identifier, a type, +and may have additional attributes specific to the type. A new +command, @code{-list-thread-groups}, returns the list of top-level +thread groups, which correspond to processes that @value{GDBN} is +debugging at the moment. By passing an identifier of a thread group +to the @code{-list-thread-groups} command, it is possible to obtain +the members of specific thread group. + +To allow the user to easily discover processes, and other objects, he +wishes to debug, a concept of @dfn{available thread group} is +introduced. Available thread group is an thread group that +@value{GDBN} is not debugging, but that can be attached to, using the +@code{-target-attach} command. The list of available top-level thread +groups can be obtained using @samp{-list-thread-groups --available}. +In general, the content of a thread group may be only retrieved only +after attaching to that thread group. + @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @node GDB/MI Command Syntax @section @sc{gdb/mi} Command Syntax @@ -18775,6 +19409,7 @@ follow development on @email{gdb@@sourceware.org} and * GDB/MI Result Records:: * GDB/MI Stream Records:: * GDB/MI Async Records:: +* GDB/MI Frame Information:: @end menu @node GDB/MI Result Records @@ -18867,7 +19502,7 @@ several times, either for different threads, because it cannot resume all threads together, or even for a single thread, if the thread must be stepped though some code before letting it run freely. -@item *stopped,reason="@var{reason}" +@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}" The target has stopped. The @var{reason} field can have one of the following values: @@ -18899,12 +19534,74 @@ The inferior exited normally. A signal was received by the inferior. @end table -@item =thread-created,id="@var{id}" -@itemx =thread-exited,id="@var{id}" +The @var{id} field identifies the thread that directly caused the stop +-- for example by hitting a breakpoint. Depending on whether all-stop +mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either +stop all threads, or only the thread that directly triggered the stop. +If all threads are stopped, the @var{stopped} field will have the +value of @code{"all"}. Otherwise, the value of the @var{stopped} +field will be a list of thread identifiers. Presently, this list will +always include a single thread, but frontend should be prepared to see +several threads in the list. + +@item =thread-group-created,id="@var{id}" +@itemx =thread-group-exited,id="@var{id}" +A thread thread group either was attached to, or has exited/detached +from. The @var{id} field contains the @value{GDBN} identifier of the +thread group. + +@item =thread-created,id="@var{id}",group-id="@var{gid}" +@itemx =thread-exited,id="@var{id}",group-id="@var{gid}" A thread either was created, or has exited. The @var{id} field -contains the @value{GDBN} identifier of the thread. +contains the @value{GDBN} identifier of the thread. The @var{gid} +field identifies the thread group this thread belongs to. + +@item =thread-selected,id="@var{id}" +Informs that the selected thread was changed as result of the last +command. This notification is not emitted as result of @code{-thread-select} +command but is emitted whenever an MI command that is not documented +to change the selected thread actually changes it. In particular, +invoking, directly or indirectly (via user-defined command), the CLI +@code{thread} command, will generate this notification. + +We suggest that in response to this notification, front ends +highlight the selected thread and cause subsequent commands to apply to +that thread. + @end table +@node GDB/MI Frame Information +@subsection @sc{gdb/mi} Frame Information + +Response from many MI commands includes an information about stack +frame. This information is a tuple that may have the following +fields: + +@table @code +@item level +The level of the stack frame. The innermost frame has the level of +zero. This field is always present. + +@item func +The name of the function corresponding to the frame. This field may +be absent if @value{GDBN} is unable to determine the function name. + +@item addr +The code address for the frame. This field is always present. + +@item file +The name of the source files that correspond to the frame's code +address. This field may be absent. + +@item line +The source line corresponding to the frames' code address. This field +may be absent. + +@item from +The name of the binary file (either executable or shared library) the +corresponds to the frame's code address. This field may be absent. + +@end table @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -19247,7 +19944,7 @@ N.A. @subsubheading Synopsis @smallexample - -break-insert [ -t ] [ -h ] [ -f ] + -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -c @var{condition} ] [ -i @var{ignore-count} ] [ -p @var{thread} ] [ @var{location} ] @end smallexample @@ -19282,6 +19979,8 @@ refers to unknown files or functions), create a pending breakpoint. Without this flag, @value{GDBN} will report an error, and won't create a breakpoint, if @var{location} cannot be parsed. +@item -d +Create a disabled breakpoint. @end table @subsubheading Result @@ -19791,14 +20490,27 @@ about all threads. -thread-info ^done,threads=[ @{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", - frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@}, + frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@}, @{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}], - file="/tmp/a.c",fullname="/tmp/a.c",line="158"@}@}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}], current-thread-id="1" (gdb) @end smallexample +The @samp{state} field may have the following values: + +@table @code +@item stopped +The thread is stopped. Frame information is available for stopped +threads. + +@item running +The thread is running. There's no frame information for running +threads. + +@end table + @subheading The @code{-thread-list-ids} Command @findex -thread-list-ids @@ -19811,29 +20523,20 @@ current-thread-id="1" Produces a list of the currently known @value{GDBN} thread ids. At the end of the list it also prints the total number of such threads. +This command is retained for historical reasons, the +@code{-thread-info} command should be used instead. + @subsubheading @value{GDBN} Command Part of @samp{info threads} supplies the same information. @subsubheading Example -No threads present, besides the main process: - -@smallexample -(gdb) --thread-list-ids -^done,thread-ids=@{@},number-of-threads="0" -(gdb) -@end smallexample - - -Several threads: - @smallexample (gdb) -thread-list-ids ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, -number-of-threads="3" +current-thread-id="1",number-of-threads="3" (gdb) @end smallexample @@ -19850,6 +20553,9 @@ number-of-threads="3" Make @var{threadnum} the current thread. It prints the number of the new current thread, and the topmost frame for that thread. +This command is deprecated in favor of explicitly using the +@samp{--thread} option to each command. + @subsubheading @value{GDBN} Command The corresponding @value{GDBN} command is @samp{thread}. @@ -19892,11 +20598,20 @@ other cases. @subsubheading Synopsis @smallexample - -exec-continue + -exec-continue [--all|--thread-group N] @end smallexample Resumes the execution of the inferior program until a breakpoint is -encountered, or until the inferior exits. +encountered, or until the inferior exits. In all-stop mode +(@pxref{All-Stop Mode}), may resume only one thread, or all threads, +depending on the value of the @samp{scheduler-locking} variable. In +non-stop mode (@pxref{Non-Stop Mode}), if the @samp{--all} is not +specified, only the thread specified with the @samp{--thread} option +(or current thread, if no @samp{--thread} is provided) is resumed. If +@samp{--all} is specified, all threads will be resumed. The +@samp{--all} option is ignored in all-stop mode. If the +@samp{--thread-group} options is specified, then all threads in that +thread group are resumed. @subsubheading @value{GDBN} Command @@ -19968,7 +20683,7 @@ gdb-result-var="$1",return-value="0" @subsubheading Synopsis @smallexample - -exec-interrupt + -exec-interrupt [--all|--thread-group N] @end smallexample Interrupts the background execution of the target. Note how the token @@ -19977,6 +20692,16 @@ that has been interrupted. The token for the interrupt itself only appears in the @samp{^done} output. If the user is trying to interrupt a non-running program, an error message will be printed. +Note that when asynchronous execution is enabled, this command is +asynchronous just like other execution commands. That is, first the +@samp{^done} response will be printed, and the target stop will be +reported after that using the @samp{*stopped} notification. + +In non-stop mode, only the context thread is interrupted by default. +All threads will be interrupted if the @samp{--all} option is +specified. If the @samp{--thread-group} option is specified, all +threads in that group will be interrupted. + @subsubheading @value{GDBN} Command The corresponding @value{GDBN} command is @samp{interrupt}. @@ -20614,6 +21339,9 @@ more detail. Change the selected frame. Select a different frame @var{framenum} on the stack. +This command in deprecated in favor of passing the @samp{--frame} +option to every command. + @subsubheading @value{GDBN} Command The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, @@ -20719,6 +21447,37 @@ visible on the screen, or ``closed''. This is possible using so called ``frozen variable objects''. Such variable objects are never implicitly updated. +Variable objects can be either @dfn{fixed} or @dfn{floating}. For the +fixed variable object, the expression is parsed when the variable +object is created, including associating identifiers to specific +variables. The meaning of expression never changes. For a floating +variable object the values of variables whose names appear in the +expressions are re-evaluated every time in the context of the current +frame. Consider this example: + +@smallexample +void do_work(...) +@{ + struct work_state state; + + if (...) + do_work(...); +@} +@end smallexample + +If a fixed variable object for the @code{state} variable is created in +this function, and we enter the recursive call, the the variable +object will report the value of @code{state} in the top-level +@code{do_work} invocation. On the other hand, a floating variable +object will report the value of @code{state} in the current frame. + +If an expression specified when creating a fixed variable object +refers to a local variable, the variable object becomes bound to the +thread and frame in which the variable object is created. When such +variable object is updated, @value{GDBN} makes sure that the +thread/frame combination the variable object is bound to still exists, +and re-evaluates the variable object in context of that thread/frame. + The following is the complete set of @sc{gdb/mi} operations defined to access this functionality: @@ -20768,7 +21527,7 @@ how it can be used. @smallexample -var-create @{@var{name} | "-"@} - @{@var{frame-addr} | "*"@} @var{expression} + @{@var{frame-addr} | "*" | "@@"@} @var{expression} @end smallexample This operation creates a variable object, which allows the monitoring of @@ -20778,12 +21537,13 @@ register. The @var{name} parameter is the string by which the object can be referenced. It must be unique. If @samp{-} is specified, the varobj system will generate a string ``varNNNNNN'' automatically. It will be -unique provided that one does not specify @var{name} on that format. +unique provided that one does not specify @var{name} of that format. The command fails if a duplicate name is found. The frame under which the expression should be evaluated can be specified by @var{frame-addr}. A @samp{*} indicates that the current -frame should be used. +frame should be used. A @samp{@@} indicates that a floating variable +object must be created. @var{expression} is any expression valid on the current language set (must not begin with a @samp{*}), or one of the following: @@ -20803,10 +21563,11 @@ begin with a @samp{*}), or one of the following: This operation returns the name, number of children and the type of the object created. Type is returned as a string as the ones generated by -the @value{GDBN} CLI: +the @value{GDBN} CLI. If a fixed variable object is bound to a +specific thread, the thread is is also printed: @smallexample - name="@var{name}",numchild="N",type="@var{type}" + name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}" @end smallexample @@ -21081,6 +21842,9 @@ as for @code{-var-list-children} (@pxref{-var-list-children}). It is recommended to use the @samp{--all-values} option, to reduce the number of MI commands needed on each program stop. +With the @samp{*} parameter, if a variable object is bound to a +currently running thread, it will not be updated, without any +diagnostic. @subsubheading Example @@ -22139,10 +22903,13 @@ Signal handling commands are not implemented. @subsubheading Synopsis @smallexample - -target-attach @var{pid} | @var{file} + -target-attach @var{pid} | @var{gid} | @var{file} @end smallexample -Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}. +Attach to a process @var{pid} or a file @var{file} outside of +@value{GDBN}, or a thread group @var{gid}. If attaching to a thread +group, the id previously returned by +@samp{-list-thread-groups --available} must be used. @subsubheading @value{GDBN} Command @@ -22184,11 +22951,12 @@ N.A. @subsubheading Synopsis @smallexample - -target-detach + -target-detach [ @var{pid} | @var{gid} ] @end smallexample Detach from the remote target which normally resumes its execution. -There's no output. +If either @var{pid} or @var{gid} is specified, detaches from either +the specified process, or specified thread group. There's no output. @subsubheading @value{GDBN} Command @@ -22736,6 +23504,40 @@ while the target is running. @end table +@subheading The @code{-list-thread-groups} Command +@findex -list-thread-groups + +@subheading Synopsis + +@smallexample +-list-thread-groups [ --available ] [ @var{group} ] +@end smallexample + +When used without the @var{group} parameter, lists top-level thread +groups that are being debugged. When used with the @var{group} +parameter, the children of the specified group are listed. The +children can be either threads, or other groups. At present, +@value{GDBN} will not report both threads and groups as children at +the same time, but it may change in future. + +With the @samp{--available} option, instead of reporting groups that +are been debugged, GDB will report all thread groups available on the +target. Using the @samp{--available} option together with @var{group} +is not allowed. + +@subheading Example + +@smallexample +@value{GDBP} +-list-thread-groups +^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}] +-list-thread-groups 17 +^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@}, +@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]] +@end smallexample @subheading The @code{-interpreter-exec} Command @findex -interpreter-exec @@ -23533,6 +24335,7 @@ Then give @file{gdb.dvi} to your @sc{dvi} printing program. * Separate Objdir:: Compiling @value{GDBN} in another directory * Config Names:: Specifying names for hosts and targets * Configure Options:: Summary of options for configure +* System-wide configuration:: Having a system-wide init file @end menu @node Requirements @@ -23875,6 +24678,42 @@ There is no convenient way to generate a list of all available hosts. There are many other options available as well, but they are generally needed for special purposes only. +@node System-wide configuration +@section System-wide configuration and settings +@cindex system-wide init file + +@value{GDBN} can be configured to have a system-wide init file; +this file will be read and executed at startup (@pxref{Startup, , What +@value{GDBN} does during startup}). + +Here is the corresponding configure option: + +@table @code +@item --with-system-gdbinit=@var{file} +Specify that the default location of the system-wide init file is +@var{file}. +@end table + +If @value{GDBN} has been configured with the option @option{--prefix=$prefix}, +it may be subject to relocation. Two possible cases: + +@itemize @bullet +@item +If the default location of this init file contains @file{$prefix}, +it will be subject to relocation. Suppose that the configure options +are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit}; +if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system +init file is looked for as @file{$install/etc/gdbinit} instead of +@file{$prefix/etc/gdbinit}. + +@item +By contrast, if the default location does not contain the prefix, +it will not be relocated. E.g.@: if @value{GDBN} has been configured with +@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit}, +then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit}, +wherever @value{GDBN} is installed. +@end itemize + @node Maintenance Commands @appendix Maintenance Commands @cindex maintenance commands @@ -23926,18 +24765,33 @@ Shared library events. @end table -@kindex maint set can-use-displaced-stepping -@kindex maint show can-use-displaced-stepping +@kindex set displaced-stepping +@kindex show displaced-stepping @cindex displaced stepping support @cindex out-of-line single-stepping -@item maint set can-use-displaced-stepping -@itemx maint show can-use-displaced-stepping +@item set displaced-stepping +@itemx show displaced-stepping Control whether or not @value{GDBN} will do @dfn{displaced stepping} -if the target supports it. The default is on. Displaced stepping is -a way to single-step over breakpoints without removing them from the -inferior, by executing an out-of-line copy of the instruction that was -originally at the breakpoint location. It is also known as -out-of-line single-stepping. +if the target supports it. Displaced stepping is a way to single-step +over breakpoints without removing them from the inferior, by executing +an out-of-line copy of the instruction that was originally at the +breakpoint location. It is also known as out-of-line single-stepping. + +@table @code +@item set displaced-stepping on +If the target architecture supports it, @value{GDBN} will use +displaced stepping to step over breakpoints. + +@item set displaced-stepping off +@value{GDBN} will not use displaced stepping to step over breakpoints, +even if such is supported by the target architecture. + +@cindex non-stop mode, and @samp{set displaced-stepping} +@item set displaced-stepping auto +This is the default mode. @value{GDBN} will use displaced stepping +only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target +architecture supports displaced stepping. +@end table @kindex maint check-symtabs @item maint check-symtabs @@ -23999,6 +24853,33 @@ Create a core file? (y or n) @kbd{n} (@value{GDBP}) @end smallexample +@cindex @value{GDBN} internal error +@cindex internal errors, control of @value{GDBN} behavior + +@kindex maint set internal-error +@kindex maint show internal-error +@kindex maint set internal-warning +@kindex maint show internal-warning +@item maint set internal-error @var{action} [ask|yes|no] +@itemx maint show internal-error @var{action} +@itemx maint set internal-warning @var{action} [ask|yes|no] +@itemx maint show internal-warning @var{action} +When @value{GDBN} reports an internal problem (error or warning) it +gives the user the opportunity to both quit @value{GDBN} and create a +core file of the current @value{GDBN} session. These commands let you +override the default behaviour for each particular @var{action}, +described in the table below. + +@table @samp +@item quit +You can specify that @value{GDBN} should always (yes) or never (no) +quit. The default is to ask the user what to do. + +@item corefile +You can specify that @value{GDBN} should always (yes) or never (no) +create a core file. The default is to ask the user what to do. +@end table + @kindex maint packet @item maint packet @var{text} If @value{GDBN} is talking to an inferior via the serial protocol, @@ -24223,6 +25104,10 @@ the symbol's location to the specified address. This is similar to the @code{info address} command (@pxref{Symbols}), except that this command also allows to find symbols in other sections. +If section was not specified, the section in which the symbol was found +is also printed. For dynamically linked executables, the name of +executable or shared library containing the symbol is printed as well. + @end table The following command is useful for non-interactive invocations of @@ -24253,6 +25138,8 @@ Show the current setting of the target wait timeout. * Tracepoint Packets:: * Host I/O Packets:: * Interrupts:: +* Notification Packets:: +* Remote Non-Stop:: * Packet Acknowledgment:: * Examples:: * File-I/O Remote Protocol Extension:: @@ -24274,8 +25161,9 @@ transmitted and received data, respectively. @cindex protocol, @value{GDBN} remote serial @cindex serial protocol, @value{GDBN} remote @cindex remote serial protocol -All @value{GDBN} commands and responses (other than acknowledgments) are -sent as a @var{packet}. A @var{packet} is introduced with the character +All @value{GDBN} commands and responses (other than acknowledgments +and notifications, see @ref{Notification Packets}) are sent as a +@var{packet}. A @var{packet} is introduced with the character @samp{$}, the actual @var{packet-data}, and the terminating character @samp{#} followed by a two-digit @var{checksum}: @@ -24321,7 +25209,10 @@ once a connection is established. The host (@value{GDBN}) sends @var{command}s, and the target (the debugging stub incorporated in your program) sends a @var{response}. In the case of step and continue @var{command}s, the response is only sent -when the operation has completed (the target has again stopped). +when the operation has completed, and the target has again stopped all +threads in all attached processes. This is the default all-stop mode +behavior, but the remote protocol also supports @value{GDBN}'s non-stop +execution mode; see @ref{Remote Non-Stop}, for details. @var{packet-data} consists of a sequence of characters with the exception of @samp{#} and @samp{$} (see @samp{X} packet for additional @@ -24457,7 +25348,8 @@ The remote target both supports and has enabled extended mode. @item ? @cindex @samp{?} packet Indicate the reason the target halted. The reply is the same as for -step and continue. +step and continue. This packet has a special interpretation when the +target is in non-stop mode; see @ref{Remote Non-Stop}. Reply: @xref{Stop Reply Packets}, for the reply specifications. @@ -24499,6 +25391,22 @@ breakpoint at @var{addr}. Don't use this packet. Use the @samp{Z} and @samp{z} packets instead (@pxref{insert breakpoint or watchpoint packet}). +@item bc +@cindex @samp{bc} packet +Backward continue. Execute the target system in reverse. No parameter. +@xref{Reverse Execution}, for more information. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item bs +@cindex @samp{bs} packet +Backward single step. Execute one instruction in reverse. No parameter. +@xref{Reverse Execution}, for more information. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + @item c @r{[}@var{addr}@r{]} @cindex @samp{c} packet Continue. @var{addr} is address to resume. If @var{addr} is omitted, @@ -24761,9 +25669,20 @@ up to the first @samp{;} or @samp{?} (or the end of the packet). @item vAttach;@var{pid} @cindex @samp{vAttach} packet -Attach to a new process with the specified process ID. @var{pid} is a -hexadecimal integer identifying the process. The attached process is -stopped. +Attach to a new process with the specified process ID @var{pid}. +The process ID is a +hexadecimal integer identifying the process. In all-stop mode, all +threads in the attached process are stopped; in non-stop mode, it may be +attached without being stopped if that is supported by the target. + +@c In non-stop mode, on a successful vAttach, the stub should set the +@c current thread to a thread of the newly-attached process. After +@c attaching, GDB queries for the attached process's thread ID with qC. +@c Also note that, from a user perspective, whether or not the +@c target is stopped on attach in non-stop mode depends on whether you +@c use the foreground or background version of the attach command, not +@c on what vAttach does; GDB does the right thing with respect to either +@c stopping or restarting threads. This packet is only available in extended mode (@pxref{extended mode}). @@ -24772,7 +25691,9 @@ Reply: @item E @var{nn} for an error @item @r{Any stop packet} -for success (@pxref{Stop Reply Packets}) +for success in all-stop mode (@pxref{Stop Reply Packets}) +@item OK +for success in non-stop mode (@pxref{Remote Non-Stop}) @end table @item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{} @@ -24780,7 +25701,9 @@ for success (@pxref{Stop Reply Packets}) Resume the inferior, specifying different actions for each thread. If an action is specified with no @var{thread-id}, then it is applied to any threads that don't have a specific action specified; if no default action is -specified then other threads should remain stopped. Specifying multiple +specified then other threads should remain stopped in all-stop mode and +in their current state in non-stop mode. +Specifying multiple default actions is an error; specifying no actions is also an error. Thread IDs are specified using the syntax described in @ref{thread-id syntax}. @@ -24790,16 +25713,29 @@ Currently supported actions are: @item c Continue. @item C @var{sig} -Continue with signal @var{sig}. @var{sig} should be two hex digits. +Continue with signal @var{sig}. The signal @var{sig} should be two hex digits. @item s Step. @item S @var{sig} -Step with signal @var{sig}. @var{sig} should be two hex digits. +Step with signal @var{sig}. The signal @var{sig} should be two hex digits. +@item t +Stop. +@item T @var{sig} +Stop with signal @var{sig}. The signal @var{sig} should be two hex digits. @end table -The optional @var{addr} argument normally associated with these packets is +The optional argument @var{addr} normally associated with the +@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is not supported in @samp{vCont}. +The @samp{t} and @samp{T} actions are only relevant in non-stop mode +(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise. +A stop reply should be generated for any affected thread not already stopped. +When a thread is stopped by means of a @samp{t} action, +the corresponding stop reply should indicate that the thread has stopped with +signal @samp{0}, regardless of whether the target uses some other signal +as an implementation detail. + Reply: @xref{Stop Reply Packets}, for the reply specifications. @@ -24902,6 +25838,8 @@ command line. The file and arguments are hex-encoded strings. If (e.g.@: the last program run). The program is created in the stopped state. +@c FIXME: What about non-stop mode? + This packet is only available in extended mode (@pxref{extended mode}). Reply: @@ -24912,6 +25850,21 @@ for an error for success (@pxref{Stop Reply Packets}) @end table +@item vStopped +@anchor{vStopped packet} +@cindex @samp{vStopped} packet + +In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop +reply and prompt for the stub to report another one. + +Reply: +@table @samp +@item @r{Any stop packet} +if there is another unreported stop event (@pxref{Stop Reply Packets}) +@item OK +if there are no unreported stop events +@end table + @item X @var{addr},@var{length}:@var{XX@dots{}} @anchor{X packet} @cindex @samp{X} packet @@ -25051,9 +26004,10 @@ for an error @section Stop Reply Packets @cindex stop reply packets -The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can -receive any of the below as a reply. In the case of the @samp{C}, -@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned +The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont}, +@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can +receive any of the below as a reply. Except for @samp{?} +and @samp{vStopped}, that reply is only returned when the target halts. In the below the exact meaning of @dfn{signal number} is defined by the header @file{include/gdb/signals.h} in the @value{GDBN} source code. @@ -25116,6 +26070,16 @@ hex. The packet indicates that the loaded libraries have changed. @value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new list of loaded libraries. @var{r} is ignored. + +@cindex replay log events, remote reply +@item replaylog +The packet indicates that the target cannot continue replaying +logged execution events, because it has reached the end (or the +beginning when executing backward) of the log. The value of @var{r} +will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, +for more information. + + @end table @item W @var{AA} @@ -25141,7 +26105,7 @@ extensions}. The @var{pid} is formatted as a big-endian hex string. @samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be written as the program's console output. This can happen at any time while the program is running and the debugger should continue to wait -for @samp{W}, @samp{T}, etc. +for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode. @item F @var{call-id},@var{parameter}@dots{} @var{call-id} is the identifier which says which host system call should @@ -25366,6 +26330,32 @@ Don't use this packet; use the @samp{qThreadExtraInfo} query instead Reply: see @code{remote.c:remote_unpack_thread_info_response()}. +@item QNonStop:1 +@item QNonStop:0 +@cindex non-stop mode, remote request +@cindex @samp{QNonStop} packet +@anchor{QNonStop} +Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode. +@xref{Remote Non-Stop}, for more information. + +Reply: +@table @samp +@item OK +The request succeeded. + +@item E @var{nn} +An error occurred. @var{nn} are hex digits. + +@item +An empty reply indicates that @samp{QNonStop} is not supported by +the stub. +@end table + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +Use of this packet is controlled by the @code{set non-stop} command; +@pxref{Non-Stop Mode}. + @item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} @cindex pass signals to inferior, remote request @cindex @samp{QPassSignals} packet @@ -25608,6 +26598,11 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab Yes +@item @samp{QNonStop} +@tab No +@tab @samp{-} +@tab Yes + @item @samp{QPassSignals} @tab No @tab @samp{-} @@ -25663,6 +26658,10 @@ The remote stub understands the @samp{qXfer:spu:read} packet The remote stub understands the @samp{qXfer:spu:write} packet (@pxref{qXfer spu write}). +@item QNonStop +The remote stub understands the @samp{QNonStop} packet +(@pxref{QNonStop}). + @item QPassSignals The remote stub understands the @samp{QPassSignals} packet (@pxref{QPassSignals}). @@ -25684,6 +26683,10 @@ debugging of more than one process at a time. The stub must not use multiprocess extensions in packet replies unless @value{GDBN} has also indicated it supports them in its @samp{qSupported} request. +@item qXfer:osdata:read +The remote stub understands the @samp{qXfer:osdata:read} packet +((@pxref{qXfer osdata read}). + @end table @item qSymbol:: @@ -25822,7 +26825,14 @@ in the target process, and @var{name} identifes the @code{spufs} file in that context to be accessed. This packet is not probed by default; the remote stub must request it, -by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). + +@item qXfer:osdata:read::@var{offset},@var{length} +@anchor{qXfer osdata read} +Access the target's @dfn{operating system information}. +@xref{Operating System Information}. + @end table Reply: @@ -25870,7 +26880,7 @@ Here are the specific requests of this form defined so far. All formats, listed below. @table @samp -@item qXfer:@var{spu}:write:@var{annex}:@var{offset}:@var{data}@dots{} +@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{} @anchor{qXfer spu write} Write @var{data} to an @code{spufs} file on the target system. The annex specifies which file to write; it must be of the form @@ -26224,11 +27234,148 @@ and does @emph{not} represent an interrupt. E.g., an @samp{X} packet Stubs are not required to recognize these interrupt mechanisms and the precise meaning associated with receipt of the interrupt is -implementation defined. If the stub is successful at interrupting the -running program, it is expected that it will send one of the Stop -Reply Packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result -of successfully stopping the program. Interrupts received while the -program is stopped will be discarded. +implementation defined. If the target supports debugging of multiple +threads and/or processes, it should attempt to interrupt all +currently-executing threads and processes. +If the stub is successful at interrupting the +running program, it should send one of the stop +reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result +of successfully stopping the program in all-stop mode, and a stop reply +for each stopped thread in non-stop mode. +Interrupts received while the +program is stopped are discarded. + +@node Notification Packets +@section Notification Packets +@cindex notification packets +@cindex packets, notification + +The @value{GDBN} remote serial protocol includes @dfn{notifications}, +packets that require no acknowledgment. Both the GDB and the stub +may send notifications (although the only notifications defined at +present are sent by the stub). Notifications carry information +without incurring the round-trip latency of an acknowledgment, and so +are useful for low-impact communications where occasional packet loss +is not a problem. + +A notification packet has the form @samp{% @var{data} # +@var{checksum}}, where @var{data} is the content of the notification, +and @var{checksum} is a checksum of @var{data}, computed and formatted +as for ordinary @value{GDBN} packets. A notification's @var{data} +never contains @samp{$}, @samp{%} or @samp{#} characters. Upon +receiving a notification, the recipient sends no @samp{+} or @samp{-} +to acknowledge the notification's receipt or to report its corruption. + +Every notification's @var{data} begins with a name, which contains no +colon characters, followed by a colon character. + +Recipients should silently ignore corrupted notifications and +notifications they do not understand. Recipients should restart +timeout periods on receipt of a well-formed notification, whether or +not they understand it. + +Senders should only send the notifications described here when this +protocol description specifies that they are permitted. In the +future, we may extend the protocol to permit existing notifications in +new contexts; this rule helps older senders avoid confusing newer +recipients. + +(Older versions of @value{GDBN} ignore bytes received until they see +the @samp{$} byte that begins an ordinary packet, so new stubs may +transmit notifications without fear of confusing older clients. There +are no notifications defined for @value{GDBN} to send at the moment, but we +assume that most older stubs would ignore them, as well.) + +The following notification packets from the stub to @value{GDBN} are +defined: + +@table @samp +@item Stop: @var{reply} +Report an asynchronous stop event in non-stop mode. +The @var{reply} has the form of a stop reply, as +described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop}, +for information on how these notifications are acknowledged by +@value{GDBN}. +@end table + +@node Remote Non-Stop +@section Remote Protocol Support for Non-Stop Mode + +@value{GDBN}'s remote protocol supports non-stop debugging of +multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub +supports non-stop mode, it should report that to @value{GDBN} by including +@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}). + +@value{GDBN} typically sends a @samp{QNonStop} packet only when +establishing a new connection with the stub. Entering non-stop mode +does not alter the state of any currently-running threads, but targets +must stop all threads in any already-attached processes when entering +all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to +probe the target state after a mode change. + +In non-stop mode, when an attached process encounters an event that +would otherwise be reported with a stop reply, it uses the +asynchronous notification mechanism (@pxref{Notification Packets}) to +inform @value{GDBN}. In contrast to all-stop mode, where all threads +in all processes are stopped when a stop reply is sent, in non-stop +mode only the thread reporting the stop event is stopped. That is, +when reporting a @samp{S} or @samp{T} response to indicate completion +of a step operation, hitting a breakpoint, or a fault, only the +affected thread is stopped; any other still-running threads continue +to run. When reporting a @samp{W} or @samp{X} response, all running +threads belonging to other attached processes continue to run. + +Only one stop reply notification at a time may be pending; if +additional stop events occur before @value{GDBN} has acknowledged the +previous notification, they must be queued by the stub for later +synchronous transmission in response to @samp{vStopped} packets from +@value{GDBN}. Because the notification mechanism is unreliable, +the stub is permitted to resend a stop reply notification +if it believes @value{GDBN} may not have received it. @value{GDBN} +ignores additional stop reply notifications received before it has +finished processing a previous notification and the stub has completed +sending any queued stop events. + +Otherwise, @value{GDBN} must be prepared to receive a stop reply +notification at any time. Specifically, they may appear when +@value{GDBN} is not otherwise reading input from the stub, or when +@value{GDBN} is expecting to read a normal synchronous response or a +@samp{+}/@samp{-} acknowledgment to a packet it has sent. +Notification packets are distinct from any other communication from +the stub so there is no ambiguity. + +After receiving a stop reply notification, @value{GDBN} shall +acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet}) +as a regular, synchronous request to the stub. Such acknowledgment +is not required to happen immediately, as @value{GDBN} is permitted to +send other, unrelated packets to the stub first, which the stub should +process normally. + +Upon receiving a @samp{vStopped} packet, if the stub has other queued +stop events to report to @value{GDBN}, it shall respond by sending a +normal stop reply response. @value{GDBN} shall then send another +@samp{vStopped} packet to solicit further responses; again, it is +permitted to send other, unrelated packets as well which the stub +should process normally. + +If the stub receives a @samp{vStopped} packet and there are no +additional stop events to report, the stub shall return an @samp{OK} +response. At this point, if further stop events occur, the stub shall +send a new stop reply notification, @value{GDBN} shall accept the +notification, and the process shall be repeated. + +In non-stop mode, the target shall respond to the @samp{?} packet as +follows. First, any incomplete stop reply notification/@samp{vStopped} +sequence in progress is abandoned. The target must begin a new +sequence reporting stop events for all stopped threads, whether or not +it has previously reported those events to @value{GDBN}. The first +stop reply is sent as a synchronous reply to the @samp{?} packet, and +subsequent stop replies are sent as responses to @samp{vStopped} packets +using the mechanism described above. The target must not send +asynchronous stop reply notifications until the sequence is complete. +If all threads are running when the target receives the @samp{?} packet, +or if the target is not attached to any process, it shall respond +@samp{OK}. @node Packet Acknowledgment @section Packet Acknowledgment @@ -26273,7 +27420,6 @@ new connection is established, there is also no protocol request to re-enable the acknowledgments for the current connection, once disabled. - @node Examples @section Examples @@ -26368,6 +27514,8 @@ the host file system. Character or block special devices, pipes, named pipes, sockets or any other communication method on the host system are not supported by this protocol. +File I/O is not supported in non-stop mode. + @node Protocol Basics @subsection Protocol Basics @cindex protocol basics, file-i/o @@ -28041,7 +29189,7 @@ Linux kernel to control restartable syscalls. @itemx @samp{org.gnu.gdb.coldfire.core} @itemx @samp{org.gnu.gdb.fido.core} One of those features must be always present. -The feature that is present determines which flavor of m86k is +The feature that is present determines which flavor of m68k is used. The feature that is present should contain registers @samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp}, @samp{sp}, @samp{ps} and @samp{pc}. @@ -28083,6 +29231,55 @@ contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and these to present registers @samp{ev0} through @samp{ev31} to the user. +@node Operating System Information +@appendix Operating System Information +@cindex operating system information + +@menu +* Process list:: +@end menu + +Users of @value{GDBN} often wish to obtain information about the state of +the operating system running on the target---for example the list of +processes, or the list of open files. This section describes the +mechanism that makes it possible. This mechanism is similar to the +target features mechanism (@pxref{Target Descriptions}), but focuses +on a different aspect of target. + +Operating system information is retrived from the target via the +remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata +read}). The object name in the request should be @samp{osdata}, and +the @var{annex} identifies the data to be fetched. + +@node Process list +@appendixsection Process list +@cindex operating system information, process list + +When requesting the process list, the @var{annex} field in the +@samp{qXfer} request should be @samp{processes}. The returned data is +an XML document. The formal syntax of this document is defined in +@file{gdb/features/osdata.dtd}. + +An example document is: + +@smallexample + + + + + 1 + root + /sbin/init + + +@end smallexample + +Each item should include a column whose name is @samp{pid}. The value +of that column should identify the process on the target. The +@samp{user} and @samp{command} columns are optional, and will be +displayed by @value{GDBN}. Target may provide additional columns, +which @value{GDBN} currently ignores. + @include gpl.texi @raisesections