So that they may not regard their many labors as thankless, we
particularly thank those who shepherded @value{GDBN} through major
releases:
-Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
+Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
Jim Blandy (release 4.18);
Jason Molenda (release 4.17);
Stan Shebs (release 4.14);
Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
Zuhn have made contributions both large and small.
+Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
+Cygnus Solutions, implemented the original @sc{gdb/mi} interface.
+
Jim Blandy added support for preprocessor macros, while working for Red
Hat.
+Andrew Cagney designed @value{GDBN}'s architecture vector. Many
+people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
+Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei
+Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason
+Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
+with the migration of old architectures to this new framework.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
@menu
* File Options:: Choosing files
* Mode Options:: Choosing modes
+* Startup:: What @value{GDBN} does during startup
@end menu
@node File Options
Execute @value{GDBN} commands from file @var{file}. @xref{Command
Files,, Command files}.
+@item -eval-command @var{command}
+@itemx -ex @var{command}
+@cindex @code{--eval-command}
+@cindex @code{-ex}
+Execute a single @value{GDBN} command.
+
+This option may be used multiple times to call multiple commands. It may
+also be interleaved with @samp{-command} as required.
+
+@smallexample
+@value{GDBP} -ex 'target sim' -ex 'load' \
+ -x setbreakpoints -ex 'run' a.out
+@end smallexample
+
@item -directory @var{directory}
@itemx -d @var{directory}
@cindex @code{--directory}
@cindex @code{-d}
Add @var{directory} to the path to search for source files.
-@item -m
-@itemx -mapped
-@cindex @code{--mapped}
-@cindex @code{-m}
-@emph{Warning: this option depends on operating system facilities that are not
-supported on all systems.}@*
-If memory-mapped files are available on your system through the @code{mmap}
-system call, you can use this option
-to have @value{GDBN} write the symbols from your
-program into a reusable file in the current directory. If the program you are debugging is
-called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.
-Future @value{GDBN} debugging sessions notice the presence of this file,
-and can quickly map in symbol information from it, rather than reading
-the symbol table from the executable program.
-
-The @file{.syms} file is specific to the host machine where @value{GDBN}
-is run. It holds an exact image of the internal @value{GDBN} symbol
-table. It cannot be shared across multiple host platforms.
-
@item -r
@itemx -readnow
@cindex @code{--readnow}
@end table
-You typically combine the @code{-mapped} and @code{-readnow} options in
-order to build a @file{.syms} file that contains complete symbol
-information. (@xref{Files,,Commands to specify files}, for information
-on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing
-but build a @file{.syms} file for future use is:
-
-@smallexample
-gdb -batch -nx -mapped -readnow programname
-@end smallexample
-
@node Mode Options
@subsection Choosing modes
@value{GDBN} control terminates) is not issued when running in batch
mode.
+@item -batch-silent
+@cindex @code{--batch-silent}
+Run in batch mode exactly like @samp{-batch}, but totally silently. All
+@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
+unaffected). This is much quieter than @samp{-silent} and would be useless
+for an interactive session.
+
+This is particularly useful when using targets that give @samp{Loading section}
+messages, for example.
+
+Note that targets that give their output via @value{GDBN}, as opposed to
+writing directly to @code{stdout}, will also be made silent.
+
+@item -return-child-result
+@cindex @code{--return-child-result}
+The return code from @value{GDBN} will be the return code from the child
+process (the process being debugged), with the following exceptions:
+
+@itemize @bullet
+@item
+@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an
+internal error. In this case the exit code is the same as it would have been
+without @samp{-return-child-result}.
+@item
+The user quits with an explicit value. E.g., @samp{quit 1}.
+@item
+The child process never runs, or is not allowed to terminate, in which case
+the exit code will be -1.
+@end itemize
+
+This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
+when @value{GDBN} is being used as a remote program loader or simulator
+interface.
+
@item -nowindows
@itemx -nw
@cindex @code{--nowindows}
@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
that control @value{GDBN}, and level 2 has been deprecated.
-The annotation mechanism has largely been superseeded by @sc{gdb/mi}
+The annotation mechanism has largely been superseded by @sc{gdb/mi}
(@pxref{GDB/MI}).
@item --args
@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
-The @sc{gdb/mi} Interface}) included since @var{GDBN} version 6.0. The
+The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The
previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
selected with @samp{--interpreter=mi1}, is deprecated. Earlier
@sc{gdb/mi} interfaces are no longer supported.
@end table
+@node Startup
+@subsection What @value{GDBN} does during startup
+@cindex @value{GDBN} startup
+
+Here's the description of what @value{GDBN} does during session startup:
+
+@enumerate
+@item
+Sets up the command interpreter as specified by the command line
+(@pxref{Mode Options, interpreter}).
+
+@item
+@cindex init file
+Reads the @dfn{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.
+
+@item
+Processes command line options and operands.
+
+@item
+Reads and executes the commands from init file (if any) in the current
+working directory. This is only done if the current directory is
+different from your home directory. Thus, you can have more than one
+init file, one generic in your home directory, and another, specific
+to the program you are debugging, in the directory where you invoke
+@value{GDBN}.
+
+@item
+Reads command files specified by the @samp{-x} option. @xref{Command
+Files}, for more details about @value{GDBN} command files.
+
+@item
+Reads the command history recorded in the @dfn{history file}.
+@xref{Command History}, for more details about the command history and the
+files where @value{GDBN} records it.
+@end enumerate
+
+Init files use the same syntax as @dfn{command files} (@pxref{Command
+Files}) and are processed by @value{GDBN} in the same way. The init
+file in your home directory can set options (such as @samp{set
+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}).
+
+@cindex init file name
+@cindex @file{.gdbinit}
+The @value{GDBN} init files are normally called @file{.gdbinit}.
+On some configurations of @value{GDBN}, the init file is known by a
+different name (these are typically environments where a specialized
+form of @value{GDBN} may need to coexist with other forms, hence a
+different name for the specialized version's init file). These are the
+environments with special init file names:
+
+@itemize @bullet
+@cindex @file{gdb.ini}
+@item
+The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
+the limitations of file names imposed by DOS filesystems. The Windows
+ports of @value{GDBN} use the standard name, but if they find a
+@file{gdb.ini} file, they warn you about that and suggest to rename
+the file to the standard name.
+
+@cindex @file{.vxgdbinit}
+@item
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
+
+@cindex @file{.os68gdbinit}
+@item
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
+
+@cindex @file{.esgdbinit}
+@item
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
+
+@item
+CISCO 68k: @file{.cisco-gdbinit}
+@end itemize
+
+
@node Quitting GDB
@section Quitting @value{GDBN}
@cindex exiting @value{GDBN}
To request debugging information, specify the @samp{-g} option when you run
the compiler.
-Most compilers do not include information about preprocessor macros in
-the debugging information if you specify the @option{-g} flag alone,
-because this information is rather large. Version 3.1 of @value{NGCC},
-the @sc{gnu} C compiler, provides macro information if you specify the
-options @option{-gdwarf-2} and @option{-g3}; the former option requests
-debugging information in the Dwarf 2 format, and the latter requests
-``extra information''. In the future, we hope to find more compact ways
-to represent macro information, so that it can be included with
-@option{-g} alone.
-
-Many C compilers are unable to handle the @samp{-g} and @samp{-O}
-options together. Using those compilers, you cannot generate optimized
+Programs that are to be shipped to your customers are compiled with
+optimizations, using the @samp{-O} compiler option. However, many
+compilers are unable to handle the @samp{-g} and @samp{-O} options
+together. Using those compilers, you cannot generate optimized
executables containing debugging information.
-@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or
+@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
without @samp{-O}, making it possible to debug optimized code. We
recommend that you @emph{always} use @samp{-g} whenever you compile a
program. You may think your program is correct, but there is no sense
@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
format; if your @sc{gnu} C compiler has this option, do not use it.
+@value{GDBN} knows about preprocessor macros and can show you their
+expansion (@pxref{Macros}). Most compilers do not include information
+about preprocessor macros in the debugging information if you specify
+the @option{-g} flag alone, because this information is rather large.
+Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler,
+provides macro information if you specify the options
+@option{-gdwarf-2} and @option{-g3}; the former option requests
+debugging information in the Dwarf 2 format, and the latter requests
+``extra information''. In the future, we hope to find more compact
+ways to represent macro information, so that it can be included with
+@option{-g} alone.
+
@need 2000
@node Starting
@section Starting your program
When you use the @code{tty} command or redirect input in the @code{run}
command, only the input @emph{for your program} is affected. The input
-for @value{GDBN} still comes from your terminal.
+for @value{GDBN} still comes from your terminal. @code{tty} is an alias
+for @code{set inferior-tty}.
+
+@cindex inferior tty
+@cindex set inferior controlling terminal
+You can use the @code{show inferior-tty} command to tell @value{GDBN} to
+display the name of the terminal that will be used for future runs of your
+program.
+
+@table @code
+@item set inferior-tty /dev/ttyb
+@kindex set inferior-tty
+Set the tty for the program being debugged to /dev/ttyb.
+
+@item show inferior-tty
+@kindex show inferior-tty
+Show the current tty for the program being debugged.
+@end table
@node Attach
@section Debugging an already-running process
threads.
@kindex thread apply
+@cindex apply command to several threads
@item thread apply [@var{threadno}] [@var{all}] @var{args}
The @code{thread apply} command allows you to apply a command to one or
more threads. Specify the numbers of the threads that you want affected
executes more slowly and reports the change in value at the next
@emph{statement}, not the instruction, after the change occurs.
-@vindex can-use-hw-watchpoints
@cindex use only software watchpoints
You can force @value{GDBN} to use only software watchpoints with the
@kbd{set can-use-hw-watchpoints 0} command. With this variable set to
stack frame consists of many bytes, each of which has its own address; each
kind of computer has a convention for choosing one byte whose
address serves as the address of the frame. Usually this address is kept
-in a register called the @dfn{frame pointer register} while execution is
-going on in that frame.
+in a register called the @dfn{frame pointer register}
+(@pxref{Registers, $fp}) while execution is going on in that frame.
@cindex frame number
@value{GDBN} assigns numbers to all existing stack frames, starting with
@item backtrace -@var{n}
@itemx bt -@var{n}
Similar, but print only the outermost @var{n} frames.
+
+@item backtrace full
+Print the values of the local variables also.
+@itemx bt full
@end table
@kindex where
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
+@cindex value optimized out, in backtrace
+@cindex function call arguments, optimized out
+If your program was compiled with optimizations, some compilers will
+optimize away arguments passed to functions if those arguments are
+never used after the call. Such optimizations generate code that
+passes arguments through registers, but doesn't store those arguments
+in the stack frame. @value{GDBN} has no way of displaying such
+arguments in stack frames other than the innermost one. Here's what
+such a backtrace might look like:
+
+@smallexample
+@group
+#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
+ at builtin.c:993
+#1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242
+#2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08)
+ at macro.c:71
+(More stack frames follow...)
+@end group
+@end smallexample
+
+@noindent
+The values of arguments that were not saved in their stack frames are
+shown as @samp{<value optimized out>}.
+
+If you need to display the values of such optimized-out arguments,
+either deduce that from other variables whose values depend on the one
+you are interested in, or recompile without optimizations.
+
@cindex backtrace beyond @code{main} function
@cindex program entry point
@cindex startup code, and backtrace
Most programs have a standard user entry point---a place where system
libraries and startup code transition into user code. For C this is
-@code{main}. When @value{GDBN} finds the entry function in a backtrace
+@code{main}@footnote{
+Note that embedded programs (the so-called ``free-standing''
+environment) are not required to have a @code{main} function as the
+entry point. They could even have multiple entry points.}.
+When @value{GDBN} finds the entry function in a backtrace
it will terminate the backtrace, to avoid tracing into highly
system-specific (and generally uninteresting) code.
On the 29k architecture, it needs three addresses: a register stack
pointer, a program counter, and a memory stack pointer.
-@c note to future updaters: this is conditioned on a flag
-@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date
-@c as of 27 Jan 1994.
@kindex up
@item up @var{n}
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
+For programs that were dynamically linked and use shared libraries,
+instructions that call functions or branch to locations in the shared
+libraries might show a seemingly bogus location---it's actually a
+location of the relocation table. On some architectures, @value{GDBN}
+might be able to resolve these to actual function names.
+
@table @code
@kindex set disassembly-flavor
@cindex Intel disassembly flavor
@xref{C, , Debugging C++}, for more info about debug info formats
that are best suited to C@t{++} programs.
+If you ask to print an object whose contents are unknown to
+@value{GDBN}, e.g., because its data type is not completely specified
+by the debug information, @value{GDBN} will say @samp{<incomplete
+type>}. @xref{Symbols, incomplete type}, for more about this.
+
@node Arrays
@section Artificial arrays
@xref{Symbols, info symbol}.
@item c
-Regard as an integer and print it as a character constant.
+Regard as an integer and print it as a character constant. This
+prints both the numerical value and its character representation. The
+character representation is replaced with the octal escape @samp{\nnn}
+for characters outside the 7-bit @sc{ascii} range.
@item f
Regard the bits of the value as a floating point number and print
@c 4.1.2.
@item @var{f}, the display format
-The display format is one of the formats used by @code{print},
-@samp{s} (null-terminated string), or @samp{i} (machine instruction).
-The default is @samp{x} (hexadecimal) initially.
-The default changes each time you use either @code{x} or @code{print}.
+The display format is one of the formats used by @code{print}
+(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
+@samp{f}), and in addition @samp{s} (for null-terminated strings) and
+@samp{i} (for machine instructions). The default is @samp{x}
+(hexadecimal) initially. The default changes each time you use either
+@code{x} or @code{print}.
@item @var{u}, the unit size
The unit size is any of
Show whether compressed or pretty format is selected for displaying
arrays.
+@cindex print array indexes
+@item set print array-indexes
+@itemx set print array-indexes on
+Print the index of each element when displaying arrays. May be more
+convenient to locate a given element in the array or quickly find the
+index of a given element in that printed array. The default is off.
+
+@item set print array-indexes off
+Stop printing element indexes when displaying arrays.
+
+@item show print array-indexes
+Show whether the index of each element is printed when displaying
+arrays.
+
@item set print elements @var{number-of-elements}
@cindex number of array elements to print
@cindex limit on number of printed array elements
the machine you are using, with or without the initial @samp{$}.
@end table
+@cindex stack pointer register
+@cindex program counter register
+@cindex process status register
+@cindex frame pointer register
+@cindex standard registers
@value{GDBN} has four ``standard'' register names that are available (in
expressions) on most machines---whenever they do not conflict with an
architecture's canonical mnemonics for registers. The register names
@subsection Fortran
@cindex Fortran-specific support in @value{GDBN}
+@value{GDBN} can be used to debug programs written in Fortran, but it
+currently supports only the features of Fortran 77 language.
+
+@cindex trailing underscore, in Fortran symbols
+Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
+among them) append an underscore to the names of variables and
+functions. When you debug programs compiled by those compilers, you
+will need to refer to variables and functions with a trailing
+underscore.
+
+@menu
+* Fortran Operators:: Fortran operators and expressions
+* Fortran Defaults:: Default settings for Fortran
+* Special Fortran commands:: Special @value{GDBN} commands for Fortran
+@end menu
+
+@node Fortran Operators
+@subsubsection Fortran operators and expressions
+
+@cindex Fortran operators and expressions
+
+Operators must be defined on values of specific types. For instance,
+@code{+} is defined on numbers, but not on characters or other non-
+arithmetic types. Operators are often defined on groups of types.
+
+@table @code
+@item **
+The exponentiation operator. It raises the first operand to the power
+of the second one.
+
+@item :
+The range operator. Normally used in the form of array(low:high) to
+represent a section of array.
+@end table
+
+@node Fortran Defaults
+@subsubsection Fortran Defaults
+
+@cindex Fortran Defaults
+
+Fortran symbols are usually case-insensitive, so @value{GDBN} by
+default uses case-insensitive matches for Fortran symbols. You can
+change that with the @samp{set case-insensitive} command, see
+@ref{Symbols}, for the details.
+
+@node Special Fortran commands
+@subsubsection Special Fortran commands
+
+@cindex Special Fortran commands
+
+@value{GDBN} had some commands to support Fortran specific feature,
+such as common block displaying.
+
@table @code
@cindex @code{COMMON} blocks, Fortran
@kindex info common
printed.
@end table
-Fortran symbols are usually case-insensitive, so @value{GDBN} by
-default uses case-insensitive matches for Fortran symbols. You can
-change that with the @samp{set case-insensitive} command, see
-@ref{Symbols}, for the details.
-
@node Pascal
@subsection Pascal
As with @code{whatis}, using @code{ptype} without an argument refers to
the type of @code{$}, the last value in the value history.
+@cindex incomplete type
+Sometimes, programs use opaque data types or incomplete specifications
+of complex data structure. If the debug information included in the
+program does not allow @value{GDBN} to display a full declaration of
+the data type, it will say @samp{<incomplete type>}. For example,
+given these declarations:
+
+@smallexample
+ struct foo;
+ struct foo *fooptr;
+@end smallexample
+
+@noindent
+but no definition for @code{struct foo} itself, @value{GDBN} will say:
+
+@smallexample
+ (gdb) ptype foo
+ $1 = <incomplete type>
+@end smallexample
+
+@noindent
+``Incomplete type'' is C terminology for data types that are not
+completely specified.
+
@kindex info types
@item info types @var{regexp}
@itemx info types
Out of @value{GDBN}}).
Occasionally it is necessary to change to a different file during a
-@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
-a file you want to use. In these situations the @value{GDBN} commands
-to specify new files are useful.
+@value{GDBN} session. Or you may run @value{GDBN} and forget to
+specify a file you want to use. Or you are debugging a remote target
+via @code{gdbserver} (@pxref{Server, file}). In these situations the
+@value{GDBN} commands to specify new files are useful.
@table @code
@cindex executable file
to run. You can change the value of this variable, for both @value{GDBN}
and your program, using the @code{path} command.
-On systems with memory-mapped files, an auxiliary file named
-@file{@var{filename}.syms} may hold symbol table information for
-@var{filename}. If so, @value{GDBN} maps in the symbol table from
-@file{@var{filename}.syms}, starting up more quickly. See the
-descriptions of the file options @samp{-mapped} and @samp{-readnow}
-(available on the command line, see @ref{File Options, , -readnow},
-and with the commands @code{file}, @code{symbol-file}, or
-@code{add-symbol-file}, described below), for more information.
+@cindex unlinked object files
+@cindex patching object files
+You can load unlinked object @file{.o} files into @value{GDBN} using
+the @code{file} command. You will not be able to ``run'' an object
+file, but you can disassemble functions and inspect variables. Also,
+if the underlying BFD functionality supports it, you could use
+@kbd{gdb -write} to patch object files using this technique. Note
+that @value{GDBN} can neither interpret nor modify relocations in this
+case, so branches and some initialized variables will appear to go to
+the wrong place. But this feature is still handy from time to time.
@item file
@code{file} with no argument makes @value{GDBN} discard any information it
@kindex readnow
@cindex reading symbols immediately
@cindex symbols, reading immediately
-@kindex mapped
-@cindex memory-mapped symbol file
-@cindex saving symbol table
-@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
-@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@item symbol-file @var{filename} @r{[} -readnow @r{]}
+@itemx file @var{filename} @r{[} -readnow @r{]}
You can override the @value{GDBN} two-stage strategy for reading symbol
tables by using the @samp{-readnow} option with any of the commands that
load symbol table information, if you want to be sure @value{GDBN} has the
entire symbol table available.
-If memory-mapped files are available on your system through the
-@code{mmap} system call, you can use another option, @samp{-mapped}, to
-cause @value{GDBN} to write the symbols for your program into a reusable
-file. Future @value{GDBN} debugging sessions map in symbol information
-from this auxiliary symbol file (if the program has not changed), rather
-than spending time reading the symbol table from the executable
-program. Using the @samp{-mapped} option has the same effect as
-starting @value{GDBN} with the @samp{-mapped} command-line option.
-
-You can use both options together, to make sure the auxiliary symbol
-file has all the symbol information for your program.
-
-The auxiliary symbol file for a program called @var{myprog} is called
-@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
-than the corresponding executable), @value{GDBN} always attempts to use
-it when you debug @var{myprog}; no special options or commands are
-needed.
-
-The @file{.syms} file is specific to the host machine where you run
-@value{GDBN}. It holds an exact image of the internal @value{GDBN}
-symbol table. It cannot be shared across multiple host platforms.
-
@c FIXME: for now no mention of directories, since this seems to be in
@c flux. 13mar1992 status is that in theory GDB would look either in
@c current dir or in same dir as myprog; but issues like competing
@kindex add-symbol-file
@cindex dynamic linking
@item add-symbol-file @var{filename} @var{address}
-@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]}
@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
-You can use the @samp{-mapped} and @samp{-readnow} options just as with
-the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
-table information for @var{filename}.
-
@kindex add-symbol-file-from-memory
@cindex @code{syscall DSO}
@cindex load symbols from memory
discarded.
@end table
-On some systems, such as HP-UX systems, @value{GDBN} supports
-autoloading shared library symbols until a limiting threshold size is
-reached. This provides the benefit of allowing autoloading to remain on
-by default, but avoids autoloading excessively large shared libraries,
-up to a threshold that is initially set, but which you can modify if you
-wish.
-
-Beyond that threshold, symbols from shared libraries must be explicitly
-loaded. To load these symbols, use the command @code{sharedlibrary
-@var{filename}}. The base address of the shared library is determined
-automatically by @value{GDBN} and need not be specified.
-
-To display or set the threshold, use the commands:
-
-@table @code
-@kindex set auto-solib-limit
-@item set auto-solib-limit @var{threshold}
-Set the autoloading size threshold, in an integral number of megabytes.
-If @var{threshold} is nonzero and shared library autoloading is enabled,
-symbols from all shared object libraries will be loaded until the total
-size of the loaded shared library symbols exceeds this threshold.
-Otherwise, symbols must be loaded manually, using the
-@code{sharedlibrary} command. The default threshold is 100 (i.e.@: 100
-Mb).
-
-@kindex show auto-solib-limit
-@item show auto-solib-limit
-Display the current autoloading size threshold, in megabytes.
-@end table
-
Sometimes you may wish that @value{GDBN} stops and gives you control
when any of shared library events happen. Use the @code{set
stop-on-solib-events} command for this:
copies on the target can be stripped as long as the copies on the host are
not.
-You need to tell @value{GDBN} where the target libraries are, so that it can
-load the correct copies---otherwise, it may try to load the host's libraries.
-@value{GDBN} has two variables to specify the search directories for target
-libraries.
+@cindex where to look for shared libraries
+For remote debugging, you need to tell @value{GDBN} where the target
+libraries are, so that it can load the correct copies---otherwise, it
+may try to load the host's libraries. @value{GDBN} has two variables
+to specify the search directories for target libraries.
@table @code
+@cindex prefix for shared library file names
@kindex set solib-absolute-prefix
@item set solib-absolute-prefix @var{path}
If this variable is set, @var{path} will be used as a prefix for any
out in the same way that they are on the target, with e.g.@: a
@file{/usr/lib} hierarchy under @var{path}.
+@cindex default value of @samp{solib-absolute-prefix}
+@cindex @samp{--with-sysroot}
You can set the default value of @samp{solib-absolute-prefix} by using the
configure-time @samp{--with-sysroot} option.
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
@samp{Connection refused}. You don't need to use the @code{load}
-command in @value{GDBN} when using gdbserver, since the program is
-already on the target.
+command in @value{GDBN} when using @code{gdbserver}, since the program is
+already on the target. However, if you want to load the symbols (as
+you normally would), do that with the @code{file} command, and issue
+it @emph{before} connecting to the server; otherwise, you will get an
+error message saying @code{"Program is already running"}, since the
+program is considered running after the connection.
@end table
@cindex BREAK signal instead of Ctrl-C
If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
when you press the @key{Ctrl-C} key to interrupt the program running
-on the remote. If set to off, @value{GDBN} sends the @samp{Strl-C}
+on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C}
character instead. The default is off, since most remote systems
expect to see @samp{Ctrl-C} as the interrupt signal.
@itemx show remote access-watchpoint-packet
@itemx show remote Z-packet
Show the current setting of @samp{Z} packets usage.
+
+@item set remote get-thread-local-storage-address
+@kindex set remote get-thread-local-storage-address
+@cindex thread local storage of remote targets
+This command enables or disables the use of the @samp{qGetTLSAddr}
+(Get Thread Local Storage Address) request packet. The default
+depends on whether the remote stub supports this request.
+@xref{General Query Packets, qGetTLSAddr}, for more details about this
+packet.
+
+@item show remote get-thread-local-storage-address
+@kindex show remote get-thread-local-storage-address
+Show the current setting of @samp{qGetTLSAddr} packet usage.
@end table
@node remote stub
how many threads are there in the process; its virtual memory usage;
the signals that are pending, blocked, and ignored; its TTY; its
consumption of system and user time; its stack size; its @samp{nice}
-value; etc. For more information, see the @samp{proc(5)} man page
+value; etc. For more information, see the @samp{proc} man page
(type @kbd{man 5 proc} from your shell prompt).
@item info proc all
@cindex native @sc{djgpp} debugging
@cindex MS-DOS-specific commands
-@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and
+@cindex DPMI
+@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and
MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
top of real-mode DOS systems and their emulations.
@cindex physical address from linear address
@item info dos address-pte @var{addr}
This command displays the Page Table entry for a specified linear
-address. The argument linear address @var{addr} should already have the
-appropriate segment's base address added to it, because this command
-accepts addresses which may belong to @emph{any} segment. For
-example, here's how to display the Page Table entry for the page where
-the variable @code{i} is stored:
+address. The argument @var{addr} is a linear address which should
+already have the appropriate segment's base address added to it,
+because this command accepts addresses which may belong to @emph{any}
+segment. For example, here's how to display the Page Table entry for
+the page where a variable @code{i} is stored:
@smallexample
@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
@noindent
This says that @code{i} is stored at offset @code{0xd30} from the page
-whose physical base address is @code{0x02698000}, and prints all the
+whose physical base address is @code{0x02698000}, and shows all the
attributes of that page.
Note that you must cast the addresses of variables to a @code{char *},
@noindent
(The @code{+ 3} offset is because the transfer buffer's address is the
-3rd member of the @code{_go32_info_block} structure.) The output of
-this command clearly shows that addresses in conventional memory are
-mapped 1:1, i.e.@: the physical and linear addresses are identical.
+3rd member of the @code{_go32_info_block} structure.) The output
+clearly shows that this DPMI server maps the addresses in conventional
+memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and
+linear (@code{0x29110}) addresses are identical.
This command is supported only with some DPMI servers.
@end table
@table @code
@item set cris-version @var{ver}
@cindex CRIS version
-Set the current CRIS version to @var{ver}. The CRIS version affects
-register names and sizes. This command is useful in case
-autodetection of the CRIS version fails.
+Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}.
+The CRIS version affects register names and sizes. This command is useful in
+case autodetection of the CRIS version fails.
@item show cris-version
Show the current CRIS version.
@item set cris-dwarf2-cfi
@cindex DWARF-2 CFI and CRIS
-Set the usage of DWARF-2 CFI for CRIS debugging. The default is off
-if using @code{gcc-cris} whose version is below @code{R59}, otherwise
-on.
+Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}.
+Change to @samp{off} when using @code{gcc-cris} whose version is below
+@code{R59}.
@item show cris-dwarf2-cfi
Show the current state of using DWARF-2 CFI.
+
+@item set cris-mode @var{mode}
+@cindex CRIS mode
+Set the current CRIS mode to @var{mode}. It should only be changed when
+debugging in guru mode, in which case it should be set to
+@samp{guru} (the default is @samp{normal}).
+
+@item show cris-mode
+Show the current CRIS mode.
@end table
@node Super-H
@menu
* Prompt:: Prompt
* Editing:: Command editing
-* History:: Command history
+* Command History:: Command history
* Screen Size:: Screen size
* Numbers:: Numbers
* ABI:: Configuring the current ABI
interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
encouraged to read that chapter.
-@node History
+@node Command History
@section Command history
@cindex command history
package, to provide the history facility. @xref{Using History
Interactively}, for the detailed description of the History library.
+To issue a command to @value{GDBN} without affecting certain aspects of
+the state which is seen by users, prefix it with @samp{server }. This
+means that this command will not affect the command history, nor will it
+affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
+pressed on a line by itself.
+
+@cindex @code{server}, command prefix
+The server prefix does not affect the recording of values into the value
+history; to print a value without recording it into the value history,
+use the @code{output} command instead of the @code{print} command.
+
Here is the description of @value{GDBN} commands related to command
history.
@cindex history size
@kindex set history size
+@cindex @env{HISTSIZE}, environment variable
@item set history size @var{size}
Set the number of commands which @value{GDBN} keeps in its history list.
This defaults to the value of the environment variable
You can always enter numbers in octal, decimal, or hexadecimal in
@value{GDBN} by the usual conventions: octal numbers begin with
@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
-begin with @samp{0x}. Numbers that begin with none of these are, by
-default, entered in base 10; likewise, the default display for
-numbers---when no particular format is specified---is base 10. You can
-change the default base for both input and output with the @code{set
-radix} command.
+begin with @samp{0x}. Numbers that neither begin with @samp{0} or
+@samp{0x}, nor end with a @samp{.} are, by default, entered in base
+10; likewise, the default display for numbers---when no particular
+format is specified---is base 10. You can change the default base for
+both input and output with the commands described below.
@table @code
@kindex set input-radix
@item set input-radix @var{base}
Set the default base for numeric input. Supported choices
for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
-specified either unambiguously or using the current default radix; for
+specified either unambiguously or using the current input radix; for
example, any of
@smallexample
@noindent
sets the input base to decimal. On the other hand, @samp{set input-radix 10}
-leaves the input radix unchanged, no matter what it was.
+leaves the input radix unchanged, no matter what it was, since
+@samp{10}, being without any leading or trailing signs of its base, is
+interpreted in the current radix. Thus, if the current radix is 16,
+@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't
+change the radix.
@kindex set output-radix
@item set output-radix @var{base}
Set the default base for numeric display. Supported choices
for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
-specified either unambiguously or using the current default radix.
+specified either unambiguously or using the current input radix.
@kindex show input-radix
@item show input-radix
which you assign a new name as a command. This is done with the
@code{define} command. User commands may accept up to 10 arguments
separated by whitespace. Arguments are accessed within the user command
-via @var{$arg0@dots{}$arg9}. A trivial example:
+via @code{$arg0@dots{}$arg9}. A trivial example:
@smallexample
define adder
print $arg0 + $arg1 + $arg2
+end
@end smallexample
@noindent
reference variables, use complex expressions, or even perform inferior
functions calls.
+In addition, @code{$argc} may be used to find out how many arguments have
+been passed. This expands to a number in the range 0@dots{}10.
+
+@smallexample
+define adder
+ if $argc == 2
+ print $arg0 + $arg1
+ end
+ if $argc == 3
+ print $arg0 + $arg1 + $arg2
+ end
+end
+@end smallexample
+
@table @code
@kindex define
@section Command files
@cindex command files
-A command file for @value{GDBN} is a file of lines that are @value{GDBN}
-commands. Comments (lines starting with @kbd{#}) may also be included.
-An empty line in a command file does nothing; it does not mean to repeat
-the last command, as it would from the terminal.
-
-@cindex init file
-@cindex @file{.gdbinit}
-@cindex @file{gdb.ini}
-When you start @value{GDBN}, it automatically executes commands from its
-@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP
-port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the
-limitations of file names imposed by DOS filesystems.}.
-During startup, @value{GDBN} does the following:
-
-@enumerate
-@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.}.
-
-@item
-Processes command line options and operands.
-
-@item
-Reads the init file (if any) in the current working directory.
-
-@item
-Reads command files specified by the @samp{-x} option.
-@end enumerate
-
-The init file in your home directory can set options (such as @samp{set
-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}).
-
-@cindex init file name
-On some configurations of @value{GDBN}, the init file is known by a
-different name (these are typically environments where a specialized
-form of @value{GDBN} may need to coexist with other forms, hence a
-different name for the specialized version's init file). These are the
-environments with special init file names:
-
-@cindex @file{.vxgdbinit}
-@itemize @bullet
-@item
-VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-
-@cindex @file{.os68gdbinit}
-@item
-OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-
-@cindex @file{.esgdbinit}
-@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
-@end itemize
+A command file for @value{GDBN} is a text file made of lines that are
+@value{GDBN} commands. Comments (lines starting with @kbd{#}) may
+also be included. An empty line in a command file does nothing; it
+does not mean to repeat the last command, as it would from the
+terminal.
-You can also request the execution of a command file with the
-@code{source} command:
+You can request the execution of a command file with the @code{source}
+command:
@table @code
@kindex source
@value{GDBN} also accepts command input from standard input. In this
mode, normal output goes to standard output and error output goes to
standard error. Errors in a command file supplied on standard input do
-not terminate execution of the command file --- execution continues with
+not terminate execution of the command file---execution continues with
the next command.
@smallexample
@unnumberedsec Function and Purpose
@cindex @sc{gdb/mi}, its purpose
-@sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is
-specifically intended to support the development of systems which use
-the debugger as just one small component of a larger system.
+@sc{gdb/mi} is a line based machine oriented text interface to
+@value{GDBN} and is activated by specifying using the
+@option{--interpreter} command line option (@pxref{Mode Options}). It
+is specifically intended to support the development of systems which
+use the debugger as just one small component of a larger system.
This chapter is a specification of the @sc{gdb/mi} interface. It is written
in the form of a reference manual.
target activity (e.g., target stopped).
The following is a preliminary list of possible out-of-band records.
+In particular, the @var{exec-async-output} records.
+
+@table @code
+@item *stopped,reason="@var{reason}"
+@end table
+
+@var{reason} can be one of the following:
@table @code
-@item "*" "stop"
+@item breakpoint-hit
+A breakpoint was reached.
+@item watchpoint-trigger
+A watchpoint was triggered.
+@item read-watchpoint-trigger
+A read watchpoint was triggered.
+@item access-watchpoint-trigger
+An access watchpoint was triggered.
+@item function-finished
+An -exec-finish or similar CLI command was accomplished.
+@item location-reached
+An -exec-until or similar CLI command was accomplished.
+@item watchpoint-scope
+A watchpoint has gone out of scope.
+@item end-stepping-range
+An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or
+similar CLI command was accomplished.
+@item exited-signalled
+The inferior exited because of a signal.
+@item exited
+The inferior exited.
+@item exited-normally
+The inferior exited normally.
+@item signal-received
+A signal was received by the inferior.
@end table
-command @var{args}@dots{}
@end smallexample
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} CLI command.
-
@subsubheading Result
-@subsubheading Out-of-band
+@subsubheading @value{GDBN} Command
-@subsubheading Notes
+The corresponding @value{GDBN} CLI command(s), if any.
@subsubheading Example
-
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Breakpoint Table Commands
@section @sc{gdb/mi} Breakpoint table commands
^running
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
value=@{old="-268439212",new="55"@},
-frame=@{func="main",args=[],file="recursive2.c",line="5"@}
+frame=@{func="main",args=[],file="recursive2.c",
+fullname="/home/foo/bar/devo/myproject/recursive2.c",line="5"@}
(@value{GDBP})
@end smallexample
^done,reason="watchpoint-trigger",
wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
(@value{GDBP})
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="5",
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
(@value{GDBP})
@end smallexample
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
^done,reason="watchpoint-scope",wpnum="2",
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
(@value{GDBP})
*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
-args=[],file="try.c",line="5"@}
+args=[],file="try.c",fullname="/home/foo/bar/devo/myproject/try.c",line="5"@}
(@value{GDBP})
-data-list-changed-registers
^done,changed-registers=["0","1","2","4","5","6","7","8","9",
(@value{GDBP})
@@Hello world
*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
-file="hello.c",line="13"@}
+file="hello.c",fullname="/home/foo/bar/devo/myproject/hello.c",line="13"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
@@hello from foo
*stopped,reason="function-finished",frame=@{func="main",args=[],
-file="hello.c",line="7"@}
+file="hello.c",fullname="/home/foo/bar/devo/myproject/hello.c",line="7"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
args=[@{name="a",value="1"],@{name="b",value="9"@}@},
-file="recursive2.c",line="14"@},
+file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
gdb-result-var="$1",return-value="0"
(@value{GDBP})
@end smallexample
222^done
(@value{GDBP})
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
-frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
+frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/devo/myproject/try.c",line="13"@}
(@value{GDBP})
(@value{GDBP})
(@value{GDBP})
000*stopped,reason="breakpoint-hit",bkptno="1",
frame=@{func="callee4",args=[],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
(@value{GDBP})
205-break-delete
205^done
111^done,frame=@{level="0",func="callee3",
args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
(@value{GDBP})
@end smallexample
^running
(@value{GDBP})
*stopped,reason="breakpoint-hit",bkptno="1",
-frame=@{func="main",args=[],file="recursive2.c",line="4"@}
+frame=@{func="main",args=[],file="recursive2.c",
+fullname="/home/foo/bar/devo/myproject/recursive2.c",line="4"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
*stopped,reason="end-stepping-range",
frame=@{func="foo",args=[@{name="a",value="10"@},
-@{name="b",value="0"@}],file="recursive2.c",line="11"@}
+@{name="b",value="0"@}],file="recursive2.c",
+fullname="/home/foo/bar/devo/myproject/recursive2.c",line="11"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
*stopped,reason="end-stepping-range",
-frame=@{func="foo",args=[],file="try.c",line="10"@}
+frame=@{func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/devo/myproject/try.c",line="10"@}
(@value{GDBP})
-exec-step-instruction
^running
(@value{GDBP})
*stopped,reason="end-stepping-range",
-frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
+frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/devo/myproject/try.c",line="10"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
x = 55
*stopped,reason="location-reached",frame=@{func="main",args=[],
-file="recursive2.c",line="6"@}
+file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="6"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
@end smallexample
-@ignore
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Kod Commands
-@section @sc{gdb/mi} Kod Commands
-
-The Kod commands are not implemented.
-
-@c @subheading -kod-info
+@subheading The @code{-inferior-tty-set} Command
+@findex -inferior-tty-set
-@c @subheading -kod-list
+@subheading Synopsis
-@c @subheading -kod-list-object-types
+@smallexample
+-inferior-tty-set /dev/pts/1
+@end smallexample
-@c @subheading -kod-show
+Set terminal for future runs of the program being debugged.
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Memory Overlay Commands
-@section @sc{gdb/mi} Memory Overlay Commands
+@subheading @value{GDBN} Command
-The memory overlay commands are not implemented.
+The corresponding @value{GDBN} command is @samp{set inferior-tty /dev/pts/1}.
-@c @subheading -overlay-auto
+@subheading Example
+
+@smallexample
+(@value{GDBP})
+-inferior-tty-set /dev/pts/1
+^done
+(@value{GDBP})
+@end smallexample
+
+@subheading The @code{-inferior-tty-show} Command
+@findex -inferior-tty-show
+
+@subheading Synopsis
+
+@smallexample
+-inferior-tty-show
+@end smallexample
+
+Show terminal for future runs of program being debugged.
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{show inferior-tty}.
+
+@subheading Example
+
+@smallexample
+(@value{GDBP})
+-inferior-tty-set /dev/pts/1
+^done
+(@value{GDBP})
+-inferior-tty-show
+^done,inferior_tty_terminal="/dev/pts/1"
+(@value{GDBP})
+@end smallexample
+
+@ignore
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Kod Commands
+@section @sc{gdb/mi} Kod Commands
+
+The Kod commands are not implemented.
+
+@c @subheading -kod-info
+
+@c @subheading -kod-list
+
+@c @subheading -kod-list-object-types
+
+@c @subheading -kod-show
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Memory Overlay Commands
+@section @sc{gdb/mi} Memory Overlay Commands
+
+The memory overlay commands are not implemented.
+
+@c @subheading -overlay-auto
@c @subheading -overlay-list-mapping-state
-stack-info-frame
@end smallexample
-Get info on the current frame.
+Get info on the selected frame.
@subsubheading @value{GDBN} Command
(without arguments).
@subsubheading Example
-N.A.
+
+@smallexample
+(@value{GDBP})
+-stack-info-frame
+^done,frame=@{level="1",addr="0x0001076c",func="callee3",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
+(@value{GDBP})
+@end smallexample
@subheading The @code{-stack-info-depth} Command
@findex -stack-info-depth
^done,
stack=[
frame=@{level="0",addr="0x00010734",func="callee4",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
frame=@{level="1",addr="0x0001076c",func="callee3",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
frame=@{level="2",addr="0x0001078c",func="callee2",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
frame=@{level="3",addr="0x000107b4",func="callee1",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
frame=@{level="4",addr="0x000107e0",func="main",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
(@value{GDBP})
-stack-list-arguments 0
^done,
-stack-list-frames
^done,stack=
[frame=@{level="0",addr="0x0001076c",func="foo",
- file="recursive2.c",line="11"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="11"@},
frame=@{level="1",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="2",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="6",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="7",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="8",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="9",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="10",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="11",addr="0x00010738",func="main",
- file="recursive2.c",line="4"@}]
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="4"@}]
(@value{GDBP})
@end smallexample
-stack-list-frames 3 5
^done,stack=
[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@}]
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@}]
(@value{GDBP})
@end smallexample
-stack-list-frames 3 3
^done,stack=
[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@}]
+ file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@}]
(@value{GDBP})
@end smallexample
-stack-list-locals @var{print-values}
@end smallexample
-Display the local variable names for the current frame. With an
-argument of 0 or @code{--no-values}, prints only the names of the variables.
-With argument of 1 or @code{--all-values}, prints also their values. With
-argument of 2 or @code{--simple-values}, prints the name, type and value for
-simple data types and the name and type for arrays, structures and
-unions. In this last case, the idea is that the user can see the
-value of simple data types immediately and he can create variable
-objects for other data types if he wishes to explore their values in
+Display the local variable names for the selected frame. If
+@var{print-values} is 0 or @code{--no-values}, print only the names of
+the variables; if it is 1 or @code{--all-values}, print also their
+values; and if it is 2 or @code{--simple-values}, print the name,
+type and value for simple data types and the name and type for arrays,
+structures and unions. In this last case, a frontend can immediately
+display the value of simple data types and create variable objects for
+other data types when the the user wishes to explore their values in
more detail.
@subsubheading @value{GDBN} Command
-stack-select-frame @var{framenum}
@end smallexample
-Change the current frame. Select a different frame @var{framenum} on
+Change the selected frame. Select a different frame @var{framenum} on
the stack.
@subsubheading @value{GDBN} Command
@smallexample
-var-list-children [@var{print-values}] @var{name}
@end smallexample
+@anchor{-var-list-children}
-Returns a list of the children of the specified variable object. With
-just the variable object name as an argument or with an optional
-preceding argument of 0 or @code{--no-values}, prints only the names of the
-variables. With an optional preceding argument of 1 or @code{--all-values},
-also prints their values.
+Return a list of the children of the specified variable object and
+create variable objects for them, if they do not already exist. With
+a single argument or if @var{print-values} has a value for of 0 or
+@code{--no-values}, print only the names of the variables; if
+@var{print-values} is 1 or @code{--all-values}, also print their
+values; and if it is 2 or @code{--simple-values} print the name and
+value for simple data types and just the name for arrays, structures
+and unions.
@subsubheading Example
@smallexample
(@value{GDBP})
-var-list-children n
- numchild=@var{n},children=[@{name=@var{name},
+ ^done,numchild=@var{n},children=[@{name=@var{name},
numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
(@value{GDBP})
-var-list-children --all-values n
- numchild=@var{n},children=[@{name=@var{name},
+ ^done,numchild=@var{n},children=[@{name=@var{name},
numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
@end smallexample
@subsubheading Synopsis
@smallexample
- -var-update @{@var{name} | "*"@}
+ -var-update [@var{print-values}] @{@var{name} | "*"@}
@end smallexample
Update the value of the variable object @var{name} by evaluating its
expression after fetching all the new values from memory or registers.
-A @samp{*} causes all existing variable objects to be updated.
+A @samp{*} causes all existing variable objects to be updated. The
+option @var{print-values} determines whether names both and values, or
+just names are printed in the manner described for
+@code{-var-list-children} (@pxref{-var-list-children}).
+@subsubheading Example
+
+@smallexample
+(@value{GDBP})
+-var-assign var1 3
+^done,value="3"
+(@value{GDBP})
+-var-update --all-values var1
+^done,changelist=[@{name="var1",value="3",in_scope="true",
+type_changed="false"@}]
+(@value{GDBP})
+@end smallexample
@node Annotations
@chapter @value{GDBN} Annotations
@menu
* Annotations Overview:: What annotations are; the general syntax.
-* Server Prefix:: Issuing a command without affecting user state.
* Prompting:: Annotations marking @value{GDBN}'s need for input.
* Errors:: Annotations for error messages.
* Invalidation:: Some annotations describe things now invalid.
@table @code
@kindex set annotate
@item set annotate @var{level}
-The @value{GDB} command @code{set annotate} sets the level of
+The @value{GDBN} command @code{set annotate} sets the level of
annotations to the specified @var{level}.
@item show annotate
denotes a @samp{control-z} character) are annotations; the rest is
output from @value{GDBN}.
-@node Server Prefix
-@section The Server Prefix
-@cindex server prefix for annotations
-
-To issue a command to @value{GDBN} without affecting certain aspects of
-the state which is seen by users, prefix it with @samp{server }. This
-means that this command will not affect the command history, nor will it
-affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
-pressed on a line by itself.
-
-The server prefix does not affect the recording of values into the value
-history; to print a value without recording it into the value history,
-use the @code{output} command instead of the @code{print} command.
-
@node Prompting
@section Annotation for @value{GDBN} Input
@xref{File-I/O remote protocol extension}, for details about the File
I/O extension of the remote protocol.
-@table @r
+Each packet's description has a template showing the packet's overall
+syntax, followed by an explanation of the packet's meaning. We
+include spaces in some of the templates for clarity; these are not
+part of the packet's syntax. No @value{GDBN} packet uses spaces to
+separate its components. For example, a template like @samp{foo
+@var{bar} @var{baz}} describes a packet beginning with the three ASCII
+bytes @samp{foo}, followed by a @var{bar}, followed directly by a
+@var{baz}. GDB does not transmit a space character between the
+@samp{foo} and the @var{bar}, or between the @var{bar} and the
+@var{baz}.
+
+Note that all packet forms beginning with an upper- or lower-case
+letter, other than those described here, are reserved for future use.
-@item @code{!} --- extended mode
-@cindex @code{!} packet
+Here are the packet descriptions.
+@table @samp
+
+@item !
+@cindex @samp{!} packet
Enable extended mode. In extended mode, the remote server is made
persistent. The @samp{R} packet is used to restart the program being
debugged.
The remote target both supports and has enabled extended mode.
@end table
-@item @code{?} --- last signal
-@cindex @code{?} packet
-
+@item ?
+@cindex @samp{?} packet
Indicate the reason the target halted. The reply is the same as for
step and continue.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{a} --- reserved
-
-Reserved for future use.
-
-@item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)}
-@cindex @code{A} packet
-
-Initialized @samp{argv[]} array passed into program. @var{arglen}
-specifies the number of bytes in the hex encoded byte stream @var{arg}.
-See @code{gdbserver} for more details.
+@item A @var{arglen},@var{argnum},@var{arg},@dots{}
+@cindex @samp{A} packet
+Initialized @code{argv[]} array passed into program. @var{arglen}
+specifies the number of bytes in the hex encoded byte stream
+@var{arg}. See @code{gdbserver} for more details.
Reply:
@table @samp
@item OK
-@item E@var{NN}
+The arguments were set.
+@item E @var{NN}
+An error occurred.
@end table
-@item @code{b}@var{baud} --- set baud @strong{(deprecated)}
-@cindex @code{b} packet
-
+@item b @var{baud}
+@cindex @samp{b} packet
+(Don't use this packet; its behavior is not well-defined.)
Change the serial line speed to @var{baud}.
JTC: @emph{When does the transport layer state change? When it's
switch happen "in between" packets, so that from remote protocol's point
of view, nothing actually happened.}
-@item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)}
-@cindex @code{B} packet
-
+@item B @var{addr},@var{mode}
+@cindex @samp{B} packet
Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
breakpoint at @var{addr}.
-This packet has been replaced by the @samp{Z} and @samp{z} packets
+Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
(@pxref{insert breakpoint or watchpoint packet}).
-@item @code{c}@var{addr} --- continue
-@cindex @code{c} packet
-
-@var{addr} is address to resume. If @var{addr} is omitted, resume at
-current address.
+@item c @var{addr}
+@cindex @samp{c} packet
+Continue. @var{addr} is address to resume. If @var{addr} is omitted,
+resume at current address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{C}@var{sig}@code{;}@var{addr} --- continue with signal
-@cindex @code{C} packet
-
+@item C @var{sig};@var{addr}
+@cindex @samp{C} packet
Continue with signal @var{sig} (hex signal number). If
-@code{;}@var{addr} is omitted, resume at same address.
+@samp{;@var{addr}} is omitted, resume at same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{d} --- toggle debug @strong{(deprecated)}
-@cindex @code{d} packet
-
+@item d
+@cindex @samp{d} packet
Toggle debug flag.
-@item @code{D} --- detach
-@cindex @code{D} packet
+Don't use this packet; instead, define a general set packet
+(@pxref{General Query Packets}).
+@item D
+@cindex @samp{D} packet
Detach @value{GDBN} from the remote system. Sent to the remote target
before @value{GDBN} disconnects via the @code{detach} command.
Reply:
@table @samp
-@item @emph{no response}
-@value{GDBN} does not check for any response after sending this packet.
+@item OK
+for success
+@item E @var{NN}
+for an error
@end table
-@item @code{e} --- reserved
-
-Reserved for future use.
-
-@item @code{E} --- reserved
-
-Reserved for future use.
-
-@item @code{f} --- reserved
+@item F @var{RC},@var{EE},@var{CF};@var{XX}
+@cindex @samp{F} packet
+A reply from @value{GDBN} to an @samp{F} packet sent by the target.
+This is part of the File-I/O protocol extension. @xref{File-I/O
+remote protocol extension}, for the specification.
-Reserved for future use.
-
-@item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet.
-@cindex @code{F} packet
-
-This packet is send by @value{GDBN} as reply to a @code{F} request packet
-sent by the target. This is part of the File-I/O protocol extension.
-@xref{File-I/O remote protocol extension}, for the specification.
-
-@item @code{g} --- read registers
+@item g
@anchor{read registers packet}
-@cindex @code{g} packet
-
+@cindex @samp{g} packet
Read general registers.
Reply:
@item @var{XX@dots{}}
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
-each register and their position within the @samp{g} @var{packet} are
+each register and their position within the @samp{g} packet are
determined by the @value{GDBN} internal macros
-@var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The
-specification of several standard @code{g} packets is specified below.
-@item E@var{NN}
+@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{REGISTER_NAME} macros. The
+specification of several standard @samp{g} packets is specified below.
+@item E @var{NN}
for an error.
@end table
-@item @code{G}@var{XX@dots{}} --- write regs
-@cindex @code{G} packet
-
-@xref{read registers packet}, for a description of the @var{XX@dots{}}
-data.
+@item G @var{XX@dots{}}
+@cindex @samp{G} packet
+Write general registers. @xref{read registers packet}, for a
+description of the @var{XX@dots{}} data.
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{h} --- reserved
-
-Reserved for future use.
-
-@item @code{H}@var{c}@var{t@dots{}} --- set thread
-@cindex @code{H} packet
-
+@item H @var{c} @var{t}
+@cindex @samp{H} packet
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
@samp{G}, et.al.). @var{c} depends on the operation to be performed: it
should be @samp{c} for step and continue operations, @samp{g} for other
-operations. The thread designator @var{t@dots{}} may be -1, meaning all
-the threads, a thread number, or zero which means pick any thread.
+operations. The thread designator @var{t} may be @samp{-1}, meaning all
+the threads, a thread number, or @samp{0} which means pick any thread.
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
@c selected, sets the registers of the register block of
@c that thread; otherwise sets current registers.
-@item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)}
+@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]}
@anchor{cycle step packet}
-@cindex @code{i} packet
-
-Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
+@cindex @samp{i} packet
+Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is
present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
step starting at that address.
-@item @code{I} --- signal then cycle step @strong{(reserved)}
-@cindex @code{I} packet
+@item I
+@cindex @samp{I} packet
+Signal, then cycle step. @xref{step with signal packet}. @xref{cycle
+step packet}.
-@xref{step with signal packet}. @xref{cycle step packet}.
-
-@item @code{j} --- reserved
-
-Reserved for future use.
-
-@item @code{J} --- reserved
-
-Reserved for future use.
-
-@item @code{k} --- kill request
-@cindex @code{k} packet
+@item k
+@cindex @samp{k} packet
+Kill request.
FIXME: @emph{There is no description of how to operate when a specific
thread context has been selected (i.e.@: does 'k' kill only that
thread?)}.
-@item @code{K} --- reserved
-
-Reserved for future use.
-
-@item @code{l} --- reserved
-
-Reserved for future use.
-
-@item @code{L} --- reserved
-
-Reserved for future use.
-
-@item @code{m}@var{addr}@code{,}@var{length} --- read memory
-@cindex @code{m} packet
-
+@item m @var{addr},@var{length}
+@cindex @samp{m} packet
Read @var{length} bytes of memory starting at address @var{addr}.
-Neither @value{GDBN} nor the stub assume that sized memory transfers are
-assumed using word aligned accesses. FIXME: @emph{A word aligned memory
-transfer mechanism is needed.}
+Note that @var{addr} may not be aligned to any particular boundary.
+
+The stub need not use any particular size or alignment when gathering
+data from memory for the response; even if @var{addr} is word-aligned
+and @var{length} is a multiple of the word size, the stub is free to
+use byte accesses, or not. For this reason, this packet may not be
+suitable for accessing memory-mapped I/O devices.
+@cindex alignment of remote memory accesses
+@cindex size of remote memory accesses
+@cindex memory, alignment and size of remote accesses
Reply:
@table @samp
@item @var{XX@dots{}}
-@var{XX@dots{}} is mem contents. Can be fewer bytes than requested if able
-to read only part of the data. Neither @value{GDBN} nor the stub assume
-that sized memory transfers are assumed using word aligned
-accesses. FIXME: @emph{A word aligned memory transfer mechanism is
-needed.}
-@item E@var{NN}
+Memory contents; each byte is transmitted as a two-digit hexidecimal
+number. The reply may contain fewer bytes than requested if the
+server was able to read only part of the region of memory.
+@item E @var{NN}
@var{NN} is errno
@end table
-@item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem
-@cindex @code{M} packet
-
+@item M @var{addr},@var{length}:@var{XX@dots{}}
+@cindex @samp{M} packet
Write @var{length} bytes of memory starting at address @var{addr}.
-@var{XX@dots{}} is the data.
+@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
+hexidecimal number.
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error (this includes the case where only part of the data was
written).
@end table
-@item @code{n} --- reserved
-
-Reserved for future use.
-
-@item @code{N} --- reserved
-
-Reserved for future use.
-
-@item @code{o} --- reserved
-
-Reserved for future use.
-
-@item @code{O} --- reserved
-
-@item @code{p}@var{hex number of register} --- read register packet
-@cindex @code{p} packet
-
+@item p @var{n}
+@cindex @samp{p} packet
+Read the value of register @var{n}; @var{n} is in hex.
@xref{read registers packet}, for a description of how the returned
register value is encoded.
@table @samp
@item @var{XX@dots{}}
the register's value
-@item E@var{NN}
+@item E @var{NN}
for an error
@item
Indicating an unrecognized @var{query}.
@end table
-@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register
+@item P @var{n@dots{}}=@var{r@dots{}}
@anchor{write register packet}
-@cindex @code{P} packet
-
-Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex
+@cindex @samp{P} packet
+Write register @var{n@dots{}} with value @var{r@dots{}}. The register
+number @var{n} is in hexidecimal, and @var{r@dots{}} contains two hex
digits for each byte in the register (target byte order).
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{q}@var{query} --- general query
+@item q @var{query}
@anchor{general query packet}
-@cindex @code{q} packet
-
-Request info about @var{query}. In general @value{GDBN} queries have a
-leading upper case letter. Custom vendor queries should use a company
-prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may optionally
-be followed by a @samp{,} or @samp{;} separated list. Stubs must ensure
-that they match the full @var{query} name.
+@cindex @samp{q} packet
+General query. Request info about @var{query}. In general
+@value{GDBN} queries have a leading upper case letter. Custom vendor
+queries should use a company prefix (in lower case) ex:
+@samp{qfsf.var}. @var{query} may optionally be followed by a @samp{,}
+or @samp{;} separated list. Stubs must ensure that they match the
+full @var{query} name.
Reply:
@table @samp
@item @var{XX@dots{}}
-Hex encoded data from query. The reply can not be empty.
-@item E@var{NN}
+Hex encoded data from query. The reply must not be empty.
+@item E @var{NN}
error reply
@item
Indicating an unrecognized @var{query}.
@end table
-@item @code{Q}@var{var}@code{=}@var{val} --- general set
-@cindex @code{Q} packet
-
-Set value of @var{var} to @var{val}.
-
+@item Q @var{var}=@var{val}
+@cindex @samp{Q} packet
+General set. Set value of @var{var} to @var{val}.
@xref{general query packet}, for a discussion of naming conventions.
-@item @code{r} --- reset @strong{(deprecated)}
-@cindex @code{r} packet
-
+@item r
+@cindex @samp{r} packet
Reset the entire system.
-@item @code{R}@var{XX} --- remote restart
-@cindex @code{R} packet
+Don't use this packet; use the @samp{R} packet instead.
+@item R @var{XX}
+@cindex @samp{R} packet
Restart the program being debugged. @var{XX}, while needed, is ignored.
This packet is only available in extended mode.
-Reply:
-@table @samp
-@item @emph{no reply}
The @samp{R} packet has no reply.
-@end table
-
-@item @code{s}@var{addr} --- step
-@cindex @code{s} packet
-@var{addr} is address to resume. If @var{addr} is omitted, resume at
-same address.
+@item s @var{addr}
+@cindex @samp{s} packet
+Single step. @var{addr} is the address at which to resume. If
+@var{addr} is omitted, resume at same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{S}@var{sig}@code{;}@var{addr} --- step with signal
+@item S @var{sig};@var{addr}
@anchor{step with signal packet}
-@cindex @code{S} packet
-
-Like @samp{C} but step not continue.
+@cindex @samp{S} packet
+Step with signal. This is analogous to the @samp{C} packet, but
+requests a single-step, rather than a normal resumption of execution.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search
-@cindex @code{t} packet
-
+@item t @var{addr}:@var{PP},@var{MM}
+@cindex @samp{t} packet
Search backwards starting at address @var{addr} for a match with pattern
@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
@var{addr} must be at least 3 digits.
-@item @code{T}@var{XX} --- thread alive
-@cindex @code{T} packet
-
+@item T @var{XX}
+@cindex @samp{T} packet
Find out if the thread XX is alive.
Reply:
@table @samp
@item OK
thread is still alive
-@item E@var{NN}
+@item E @var{NN}
thread is dead
@end table
-@item @code{u} --- reserved
-
-Reserved for future use.
-
-@item @code{U} --- reserved
-
-Reserved for future use.
-
-@item @code{v} --- verbose packet prefix
-
-Packets starting with @code{v} are identified by a multi-letter name,
-up to the first @code{;} or @code{?} (or the end of the packet).
-
-@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume
-@cindex @code{vCont} packet
+@item v
+Packets starting with @samp{v} are identified by a multi-letter name,
+up to the first @samp{;} or @samp{?} (or the end of the packet).
-Resume the inferior. Different actions may be specified for each thread.
+@item vCont@r{[};@var{action}@r{[}:@var{tid}@r{]]}@dots{}
+@cindex @samp{vCont} packet
+Resume the inferior, specifying different actions for each thread.
If an action is specified with no @var{tid}, 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
default actions is an error; specifying no actions is also an error.
Thread IDs are specified in hexadecimal. Currently supported actions are:
-@table @code
+@table @samp
@item c
Continue.
-@item C@var{sig}
+@item C @var{sig}
Continue with signal @var{sig}. @var{sig} should be two hex digits.
@item s
Step.
-@item S@var{sig}
+@item S @var{sig}
Step with signal @var{sig}. @var{sig} should be two hex digits.
@end table
The optional @var{addr} argument normally associated with these packets is
-not supported in @code{vCont}.
+not supported in @samp{vCont}.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{vCont?} --- extended resume query
-@cindex @code{vCont?} packet
-
-Query support for the @code{vCont} packet.
+@item vCont?
+@cindex @samp{vCont?} packet
+Request a list of actions supporetd by the @samp{vCont} packet.
Reply:
@table @samp
-@item @code{vCont}[;@var{action}]...
-The @code{vCont} packet is supported. Each @var{action} is a supported
-command in the @code{vCont} packet.
+@item vCont@r{[};@var{action}@dots{}@r{]}
+The @samp{vCont} packet is supported. Each @var{action} is a supported
+command in the @samp{vCont} packet.
@item
-The @code{vCont} packet is not supported.
+The @samp{vCont} packet is not supported.
@end table
-@item @code{V} --- reserved
-
-Reserved for future use.
-
-@item @code{w} --- reserved
-
-Reserved for future use.
-
-@item @code{W} --- reserved
-
-Reserved for future use.
-
-@item @code{x} --- reserved
-
-Reserved for future use.
-
-@item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary)
-@cindex @code{X} packet
-
-@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}}
-is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
-escaped using @code{0x7d}, and then XORed with @code{0x20}.
-For example, @code{0x7d} would be transmitted as @code{0x7d 0x5d}.
+@item X @var{addr},@var{length}:@var{XX@dots{}}
+@cindex @samp{X} packet
+Write data to memory, where the data is transmitted in binary.
+@var{addr} is address, @var{length} is number of bytes,
+@samp{@var{XX}@dots{}} is binary data. The bytes @code{0x23}
+(@sc{ascii} @samp{#}), @code{0x24} (@sc{ascii} @samp{$}), and
+@code{0x7d} (@sc{ascii} @samp{@}}) are escaped using @code{0x7d}
+(@sc{ascii} @samp{@}}), and then XORed with @code{0x20}. For example,
+the byte @code{0x7d} would be transmitted as the two bytes @code{0x7d
+0x5d}.
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{y} --- reserved
-
-Reserved for future use.
-
-@item @code{Y} reserved
-
-Reserved for future use.
-
-@item @code{z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- remove breakpoint or watchpoint @strong{(draft)}
-@itemx @code{Z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- insert breakpoint or watchpoint @strong{(draft)}
+@item z @var{type},@var{addr},@var{length}
+@itemx Z @var{type},@var{addr},@var{length}
@anchor{insert breakpoint or watchpoint packet}
-@cindex @code{z} packet
-@cindex @code{Z} packets
-
-Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or
+@cindex @samp{z} packet
+@cindex @samp{Z} packets
+Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or
watchpoint starting at address @var{address} and covering the next
@var{length} bytes.
@emph{Implementation notes: A remote target shall return an empty string
for an unrecognized breakpoint or watchpoint packet @var{type}. A
remote target shall support either both or neither of a given
-@code{Z}@var{type}@dots{} and @code{z}@var{type}@dots{} packet pair. To
+@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To
avoid potential problems with duplicate packets, the operations should
be implemented in an idempotent way.}
-@item @code{z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- remove memory breakpoint @strong{(draft)}
-@item @code{Z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- insert memory breakpoint @strong{(draft)}
-@cindex @code{z0} packet
-@cindex @code{Z0} packet
-
-Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address
-@code{addr} of size @code{length}.
+@item z0,@var{addr},@var{length}
+@itemx Z0,@var{addr},@var{length}
+@cindex @samp{z0} packet
+@cindex @samp{Z0} packet
+Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
+@var{addr} of size @var{length}.
A memory breakpoint is implemented by replacing the instruction at
@var{addr} with a software breakpoint or trap instruction. The
-@code{length} is used by targets that indicates the size of the
+@var{length} is used by targets that indicates the size of the
breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and
@sc{mips} can insert either a 2 or 4 byte breakpoint).
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- remove hardware breakpoint @strong{(draft)}
-@item @code{Z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- insert hardware breakpoint @strong{(draft)}
-@cindex @code{z1} packet
-@cindex @code{Z1} packet
-
-Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at
-address @code{addr} of size @code{length}.
+@item z1,@var{addr},@var{length}
+@itemx Z1,@var{addr},@var{length}
+@cindex @samp{z1} packet
+@cindex @samp{Z1} packet
+Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
+address @var{addr} of size @var{length}.
A hardware breakpoint is implemented using a mechanism that is not
dependant on being able to modify the target's memory.
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- remove write watchpoint @strong{(draft)}
-@item @code{Z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- insert write watchpoint @strong{(draft)}
-@cindex @code{z2} packet
-@cindex @code{Z2} packet
-
-Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint.
+@item z2,@var{addr},@var{length}
+@itemx Z2,@var{addr},@var{length}
+@cindex @samp{z2} packet
+@cindex @samp{Z2} packet
+Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint.
Reply:
@table @samp
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- remove read watchpoint @strong{(draft)}
-@item @code{Z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- insert read watchpoint @strong{(draft)}
-@cindex @code{z3} packet
-@cindex @code{Z3} packet
-
-Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint.
+@item z3,@var{addr},@var{length}
+@itemx Z3,@var{addr},@var{length}
+@cindex @samp{z3} packet
+@cindex @samp{Z3} packet
+Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint.
Reply:
@table @samp
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- remove access watchpoint @strong{(draft)}
-@item @code{Z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- insert access watchpoint @strong{(draft)}
-@cindex @code{z4} packet
-@cindex @code{Z4} packet
-
-Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint.
+@item z4,@var{addr},@var{length}
+@itemx Z4,@var{addr},@var{length}
+@cindex @samp{z4} packet
+@cindex @samp{Z4} packet
+Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint.
Reply:
@table @samp
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
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
-when the target halts. In the below the exact meaning of @samp{signal
-number} is poorly defined. In general one of the UNIX signal numbering
-conventions is used.
-
-@table @samp
+when the target halts. In the below the exact meaning of @dfn{signal
+number} is poorly defined. In general one of the UNIX signal
+numbering conventions is used.
-@item S@var{AA}
-@var{AA} is the signal number
+As in the description of request packets, we include spaces in the
+reply templates for clarity; these are not part of the reply packet's
+syntax. No @value{GDBN} stop reply packet uses spaces to separate its
+components.
-@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
-@cindex @code{T} packet reply
+@table @samp
-@var{AA} = two hex digit signal number; @var{n...} = register number
-(hex), @var{r...} = target byte ordered register contents, size defined
-by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread},
-@var{r...} = thread process ID, this is a hex integer; @var{n...} =
-(@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data
-address, this is a hex integer; @var{n...} = other string not starting
-with valid hex digit. @value{GDBN} should ignore this @var{n...},
-@var{r...} pair and go on to the next. This way we can extend the
-protocol.
+@item S @var{AA}
+The program received signal number @var{AA} (a two-digit hexidecimal
+number).
-@item W@var{AA}
+@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
+@cindex @samp{T} packet reply
+The program received signal number @var{AA} (a two-digit hexidecimal
+number). Single-step and breakpoint traps are reported this way. The
+@samp{@var{n}:@var{r}} pairs give the values of important registers or
+other information:
+@enumerate
+@item
+If @var{n} is a hexidecimal number, it is a register number, and the
+corresponding @var{r} gives that register's value. @var{r} is a
+series of bytes in target byte order, with each byte given by a
+two-digit hex number.
+@item
+If @var{n} is @samp{thread}, then @var{r} is the thread process ID, in
+hex.
+@item
+If @var{n} is @samp{watch}, @samp{rwatch}, or @samp{awatch}, then the
+packet indicates a watchpoint hit, and @var{r} is the data address, in
+hex.
+@item
+Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair
+and go on to the next; this allows us to extend the protocol in the
+future.
+@end enumerate
+@item W @var{AA}
The process exited, and @var{AA} is the exit status. This is only
applicable to certain targets.
-@item X@var{AA}
-
+@item X @var{AA}
The process terminated with signal @var{AA}.
-@item O@var{XX@dots{}}
-
-@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at
-any time while the program is running and the debugger should continue
-to wait for @samp{W}, @samp{T}, etc.
-
-@item F@var{call-id}@code{,}@var{parameter@dots{}}
+@item O @var{XX}@dots{}
+@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.
+@item F @var{call-id},@var{parameter}@dots{}
@var{call-id} is the identifier which says which host system call should
be called. This is just the name of the function. Translation into the
correct system call is only applicable as it's defined in @value{GDBN}.
@xref{File-I/O remote protocol extension}, for a list of implemented
system calls.
-@var{parameter@dots{}} is a list of parameters as defined for this very
-system call.
+@samp{@var{parameter}@dots{}} is a list of parameters as defined for
+this very system call.
-The target replies with this packet when it expects @value{GDBN} to call
-a host system call on behalf of the target. @value{GDBN} replies with
-an appropriate @code{F} packet and keeps up waiting for the next reply
-packet from the target. The latest @samp{C}, @samp{c}, @samp{S} or
-@samp{s} action is expected to be continued.
-@xref{File-I/O remote protocol extension}, for more details.
+The target replies with this packet when it expects @value{GDBN} to
+call a host system call on behalf of the target. @value{GDBN} replies
+with an appropriate @samp{F} packet and keeps up waiting for the next
+reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S}
+or @samp{s} action is expected to be continued. @xref{File-I/O remote
+protocol extension}, for more details.
@end table
The following set and query packets have already been defined.
-@table @r
+Like the descriptions of the other packets, each description here
+has a template showing the packet's overall syntax, followed by an
+explanation of the packet's meaning. We include spaces in some of the
+templates for clarity; these are not part of the packet's syntax. No
+@value{GDBN} packet uses spaces to separate its components.
+
+@table @samp
-@item @code{q}@code{C} --- current thread
+@item qC
@cindex current thread, remote request
-@cindex @code{qC} packet
+@cindex @samp{qC} packet
Return the current thread id.
Reply:
@table @samp
-@item @code{QC}@var{pid}
+@item QC @var{pid}
Where @var{pid} is an unsigned hexidecimal process id.
-@item *
+@item @r{(anything else)}
Any other reply implies the old pid.
@end table
-@item @code{q}@code{fThreadInfo} -- all thread ids
-@cindex list active threads, remote request
-@cindex @code{qfThreadInfo} packet
-@code{q}@code{sThreadInfo}
+@item qCRC:@var{addr},@var{length}
+@cindex CRC of memory block, remote request
+@cindex @samp{qCRC} packet
+Compute the CRC checksum of a block of memory.
+Reply:
+@table @samp
+@item E @var{NN}
+An error (such as memory fault)
+@item C @var{crc32}
+The specified memory region's checksum is @var{crc32}.
+@end table
-Obtain a list of active thread ids from the target (OS). Since there
+@item qfThreadInfo
+@itemx qsThreadInfo
+@cindex list active threads, remote request
+@cindex @samp{qfThreadInfo} packet
+@cindex @samp{qsThreadInfo} packet
+Obtain a list of all active thread ids from the target (OS). Since there
may be too many active threads to fit into one reply packet, this query
works iteratively: it may require more than one query/reply sequence to
obtain the entire list of threads. The first query of the sequence will
-be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
-sequence will be the @code{qs}@code{ThreadInfo} query.
+be the @samp{qfThreadInfo} query; subsequent queries in the
+sequence will be the @samp{qsThreadInfo} query.
-NOTE: replaces the @code{qL} query (see below).
+NOTE: This packet replaces the @samp{qL} query (see below).
Reply:
@table @samp
-@item @code{m}@var{id}
+@item m @var{id}
A single thread id
-@item @code{m}@var{id},@var{id}@dots{}
+@item m @var{id},@var{id}@dots{}
a comma-separated list of thread ids
-@item @code{l}
-(lower case 'el') denotes end of list.
+@item l
+(lower case letter @samp{L}) denotes end of list.
@end table
In response to each query, the target will reply with a list of one or
more thread ids, in big-endian unsigned hex, separated by commas.
@value{GDBN} will respond to each reply with a request for more thread
-ids (using the @code{qs} form of the query), until the target responds
-with @code{l} (lower-case el, for @code{'last'}).
+ids (using the @samp{qs} form of the query), until the target responds
+with @samp{l} (lower-case el, for @dfn{last}).
-@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
-@cindex thread attributes info, remote request
-@cindex @code{qThreadExtraInfo} packet
-Where @var{id} is a thread-id in big-endian hex. Obtain a printable
-string description of a thread's attributes from the target OS. This
-string may contain anything that the target OS thinks is interesting for
-@value{GDBN} to tell the user about the thread. The string is displayed
-in @value{GDBN}'s @samp{info threads} display. Some examples of
-possible thread extra info strings are ``Runnable'', or ``Blocked on
-Mutex''.
+@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
+@cindex get thread-local storage address, remote request
+@cindex @samp{qGetTLSAddr} packet
+Fetch the address associated with thread local storage specified
+by @var{thread-id}, @var{offset}, and @var{lm}.
+
+@var{thread-id} is the (big endian, hex encoded) thread id associated with the
+thread for which to fetch the TLS address.
+
+@var{offset} is the (big endian, hex encoded) offset associated with the
+thread local variable. (This offset is obtained from the debug
+information associated with the variable.)
+
+@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
+the load module associated with the thread local storage. For example,
+a @sc{gnu}/Linux system will pass the link map address of the shared
+object associated with the thread local storage under consideration.
+Other operating environments may choose to represent the load module
+differently, so the precise meaning of this parameter will vary.
Reply:
@table @samp
-@item @var{XX@dots{}}
-Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising
-the printable string containing the extra information about the thread's
-attributes.
+@item @var{XX}@dots{}
+Hex encoded (big endian) bytes representing the address of the thread
+local storage requested.
+
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+
+@item
+An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
@end table
-@item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
+Use of this request packet is controlled by the @code{set remote
+get-thread-local-storage-address} command (@pxref{Remote
+configuration, set remote get-thread-local-storage-address}).
+@item qL @var{startflag} @var{threadcount} @var{nextthread}
Obtain thread information from RTOS. Where: @var{startflag} (one hex
digit) is one to indicate the first query and zero to indicate a
subsequent query; @var{threadcount} (two hex digits) is the maximum
(eight hex digits), for subsequent queries (@var{startflag} is zero), is
returned in the response as @var{argthread}.
-NOTE: this query is replaced by the @code{q}@code{fThreadInfo} query
-(see above).
+Don't use this packet; use the @samp{qfThreadInfo} query instead (see above).
Reply:
@table @samp
-@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}}
+@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{}
Where: @var{count} (two hex digits) is the number of threads being
returned; @var{done} (one hex digit) is zero to indicate more threads
and one indicates no further threads; @var{argthreadid} (eight hex
-digits) is @var{nextthread} from the request packet; @var{thread@dots{}}
+digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
is a sequence of thread IDs from the target. @var{threadid} (eight hex
digits). See @code{remote.c:parse_threadlist_response()}.
@end table
-@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block
-@cindex CRC of memory block, remote request
-@cindex @code{qCRC} packet
-Reply:
-@table @samp
-@item @code{E}@var{NN}
-An error (such as memory fault)
-@item @code{C}@var{CRC32}
-A 32 bit cyclic redundancy check of the specified memory region.
-@end table
-
-@item @code{q}@code{Offsets} --- query sect offs
+@item qOffsets
@cindex section offsets, remote request
-@cindex @code{qOffsets} packet
+@cindex @samp{qOffsets} packet
Get section offsets that the target used when re-locating the downloaded
image. @emph{Note: while a @code{Bss} offset is included in the
response, @value{GDBN} ignores this and instead applies the @code{Data}
Reply:
@table @samp
-@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
+@item Text=@var{xxx};Data=@var{yyy};Bss=@var{zzz}
@end table
-@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request
+@item qP @var{mode} @var{threadid}
@cindex thread information, remote request
-@cindex @code{qP} packet
+@cindex @samp{qP} packet
Returns information on @var{threadid}. Where: @var{mode} is a hex
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
-Reply:
-@table @samp
-@item *
-@end table
-
-See @code{remote.c:remote_unpack_thread_info_response()}.
-
-@item @code{q}@code{Rcmd,}@var{command} --- remote command
-@cindex execute remote command, remote request
-@cindex @code{qRcmd} packet
-@var{command} (hex encoded) is passed to the local interpreter for
-execution. Invalid commands should be reported using the output string.
-Before the final result packet, the target may also respond with a
-number of intermediate @code{O}@var{output} console output packets.
-@emph{Implementors should note that providing access to a stubs's
-interpreter may have security implications}.
-
-Reply:
-@table @samp
-@item OK
-A command response with no output.
-@item @var{OUTPUT}
-A command response with the hex encoded output string @var{OUTPUT}.
-@item @code{E}@var{NN}
-Indicate a badly formed request.
-@item @samp{}
-When @samp{q}@samp{Rcmd} is not recognized.
-@end table
-z
-@item @code{qSymbol::} --- symbol lookup
-@cindex symbol lookup, remote request
-@cindex @code{qSymbol} packet
-Notify the target that @value{GDBN} is prepared to serve symbol lookup
-requests. Accept requests from the target for the values of symbols.
-
-Reply:
-@table @samp
-@item @code{OK}
-The target does not need to look up any (more) symbols.
-@item @code{qSymbol:}@var{sym_name}
-The target requests the value of symbol @var{sym_name} (hex encoded).
-@value{GDBN} may provide the value by using the
-@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below.
-@end table
-
-@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value
-
-Set the value of @var{sym_name} to @var{sym_value}.
-
-@var{sym_name} (hex encoded) is the name of a symbol whose value the
-target has previously requested.
-
-@var{sym_value} (hex) is the value for symbol @var{sym_name}. If
-@value{GDBN} cannot supply a value for @var{sym_name}, then this field
-will be empty.
-
-Reply:
-@table @samp
-@item @code{OK}
-The target does not need to look up any (more) symbols.
-@item @code{qSymbol:}@var{sym_name}
-The target requests the value of a new symbol @var{sym_name} (hex
-encoded). @value{GDBN} will continue to supply the values of symbols
-(if available), until the target ceases to request them.
-@end table
+Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
-@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data
+@item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length}
@cindex read special object, remote request
-@cindex @code{qPart} packet
+@cindex @samp{qPart} packet
Read uninterpreted bytes from the target's special data area
-identified by the keyword @code{object}.
-Request @var{length} bytes starting at @var{offset} bytes into the data.
-The content and encoding of @var{annex} is specific to the object;
-it can supply additional details about what data to access.
+identified by the keyword @var{object}. Request @var{length} bytes
+starting at @var{offset} bytes into the data. The content and
+encoding of @var{annex} is specific to the object; it can supply
+additional details about what data to access.
-Here are the specific requests of this form defined so far.
-All @samp{@code{qPart}:@var{object}:@code{read}:@dots{}}
-requests use the same reply formats, listed below.
+Here are the specific requests of this form defined so far. All
+@samp{qPart:@var{object}:read:@dots{}} requests use the same reply
+formats, listed below.
-@table @asis
-@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length}
+@table @samp
+@item qPart:auxv:read::@var{offset},@var{length}
Access the target's @dfn{auxiliary vector}. @xref{OS Information,
auxiliary vector}, and see @ref{Remote configuration,
read-aux-vector-packet}. Note @var{annex} must be empty.
@end table
Reply:
-@table @asis
-@item @code{OK}
+@table @samp
+@item OK
The @var{offset} in the request is at the end of the data.
There is no more data to be read.
-@item @var{XX@dots{}}
+@item @var{XX}@dots{}
Hex encoded data bytes read.
This may be fewer bytes than the @var{length} in the request.
-@item @code{E00}
+@item E00
The request was malformed, or @var{annex} was invalid.
-@item @code{E}@var{nn}
+@item E @var{nn}
The offset was invalid, or there was an error encountered reading the data.
@var{nn} is a hex-encoded @code{errno} value.
-@item @code{""} (empty)
+@item
An empty reply indicates the @var{object} or @var{annex} string was not
recognized by the stub.
@end table
-@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}}
+@item qPart:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
@cindex write data into object, remote request
Write uninterpreted bytes into the target's special data area
-identified by the keyword @code{object},
-starting at @var{offset} bytes into the data.
-@var{data@dots{}} is the hex-encoded data to be written.
-The content and encoding of @var{annex} is specific to the object;
-it can supply additional details about what data to access.
+identified by the keyword @var{object}, starting at @var{offset} bytes
+into the data. @samp{@var{data}@dots{}} is the hex-encoded data to be
+written. The content and encoding of @var{annex} is specific to the
+object; it can supply additional details about what data to access.
No requests of this form are presently in use. This specification
serves as a placeholder to document the common format that new
specific request specifications ought to use.
Reply:
-@table @asis
+@table @samp
@item @var{nn}
@var{nn} (hex encoded) is the number of bytes written.
This may be fewer bytes than supplied in the request.
-@item @code{E00}
+@item E00
The request was malformed, or @var{annex} was invalid.
-@item @code{E}@var{nn}
+@item E @var{nn}
The offset was invalid, or there was an error encountered writing the data.
@var{nn} is a hex-encoded @code{errno} value.
-@item @code{""} (empty)
+@item
An empty reply indicates the @var{object} or @var{annex} string was not
recognized by the stub, or that the object does not support writing.
@end table
-@item @code{qPart}:@var{object}:@var{operation}:@dots{}
+@item qPart:@var{object}:@var{operation}:@dots{}
Requests of this form may be added in the future. When a stub does
not recognize the @var{object} keyword, or its support for
-@var{object} does not recognize the @var{operation} keyword,
-the stub must respond with an empty packet.
+@var{object} does not recognize the @var{operation} keyword, the stub
+must respond with an empty packet.
-@item @code{qGetTLSAddr}:@var{thread-id},@var{offset},@var{lm} --- get thread local storage address
-@cindex get thread-local storage address, remote request
-@cindex @code{qGetTLSAddr} packet
-Fetch the address associated with thread local storage specified
-by @var{thread-id}, @var{offset}, and @var{lm}.
+@item qRcmd,@var{command}
+@cindex execute remote command, remote request
+@cindex @samp{qRcmd} packet
+@var{command} (hex encoded) is passed to the local interpreter for
+execution. Invalid commands should be reported using the output
+string. Before the final result packet, the target may also respond
+with a number of intermediate @samp{O@var{output}} console output
+packets. @emph{Implementors should note that providing access to a
+stubs's interpreter may have security implications}.
-@var{thread-id} is the (big endian, hex encoded) thread id associated with the
-thread for which to fetch the TLS address.
+Reply:
+@table @samp
+@item OK
+A command response with no output.
+@item @var{OUTPUT}
+A command response with the hex encoded output string @var{OUTPUT}.
+@item E @var{NN}
+Indicate a badly formed request.
+@item
+An empty reply indicates that @samp{qRcmd} is not recognized.
+@end table
-@var{offset} is the (big endian, hex encoded) offset associated with the
-thread local variable. (This offset is obtained from the debug
-information associated with the variable.)
+@item qSymbol::
+@cindex symbol lookup, remote request
+@cindex @samp{qSymbol} packet
+Notify the target that @value{GDBN} is prepared to serve symbol lookup
+requests. Accept requests from the target for the values of symbols.
-@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
-the load module associated with the thread local storage. For example,
-a @sc{gnu}/Linux system will pass the link map address of the shared
-object associated with the thread local storage under consideration.
-Other operating environments may choose to represent the load module
-differently, so the precise meaning of this parameter will vary.
+Reply:
+@table @samp
+@item OK
+The target does not need to look up any (more) symbols.
+@item qSymbol:@var{sym_name}
+The target requests the value of symbol @var{sym_name} (hex encoded).
+@value{GDBN} may provide the value by using the
+@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described
+below.
+@end table
+
+@item qSymbol:@var{sym_value}:@var{sym_name}
+Set the value of @var{sym_name} to @var{sym_value}.
+
+@var{sym_name} (hex encoded) is the name of a symbol whose value the
+target has previously requested.
+
+@var{sym_value} (hex) is the value for symbol @var{sym_name}. If
+@value{GDBN} cannot supply a value for @var{sym_name}, then this field
+will be empty.
Reply:
-@table @asis
-@item @var{XX@dots{}}
-Hex encoded (big endian) bytes representing the address of the thread
-local storage requested.
+@table @samp
+@item OK
+The target does not need to look up any (more) symbols.
+@item qSymbol:@var{sym_name}
+The target requests the value of a new symbol @var{sym_name} (hex
+encoded). @value{GDBN} will continue to supply the values of symbols
+(if available), until the target ceases to request them.
+@end table
-@item @code{E}@var{nn} (where @var{nn} are hex digits)
-An error occurred.
+@item qThreadExtraInfo,@var{id}
+@cindex thread attributes info, remote request
+@cindex @samp{qThreadExtraInfo} packet
+Obtain a printable string description of a thread's attributes from
+the target OS. @var{id} is a thread-id in big-endian hex. This
+string may contain anything that the target OS thinks is interesting
+for @value{GDBN} to tell the user about the thread. The string is
+displayed in @value{GDBN}'s @code{info threads} display. Some
+examples of possible thread extra info strings are @samp{Runnable}, or
+@samp{Blocked on Mutex}.
-@item @code{""} (empty)
-An empty reply indicates that @code{qGetTLSAddr} is not supported by the stub.
+Reply:
+@table @samp
+@item @var{XX}@dots{}
+Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data,
+comprising the printable string containing the extra information about
+the thread's attributes.
@end table
@end table
@node Register Packet Format
@section Register Packet Format
-The following @samp{g}/@samp{G} packets have previously been defined.
+The following @code{g}/@code{G} packets have previously been defined.
In the below, some thirty-two bit registers are transferred as
sixty-four bits. Those registers should be zero/sign extended (which?)
to fill the space allocated. Register bytes are transfered in target
is stopped on users request.
@node The isatty call
-@subsection The isatty(3) call
+@subsection The @samp{isatty} function call
@cindex isatty call, file-i/o protocol
A special case in this protocol is the library call @code{isatty} which
needed.
@node The system call
-@subsection The system(3) call
+@subsection The @samp{system} function call
@cindex system call, file-i/o protocol
The other special case in this protocol is the @code{system} call which
projects / deliverable / binutils-gdb.git / blobdiff