diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/Makefile.in | 66 | ||||
| -rw-r--r-- | gdb/doc/agentexpr.texi | 2 | ||||
| -rw-r--r-- | gdb/doc/all-cfg.texi | 10 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 1409 | ||||
| -rw-r--r-- | gdb/doc/guile.texi | 27 | ||||
| -rw-r--r-- | gdb/doc/python.texi | 628 | ||||
| -rw-r--r-- | gdb/doc/stabs.texinfo | 4130 |
7 files changed, 1601 insertions, 4671 deletions
diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index b9c79b9..c22865a 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -82,7 +82,7 @@ PACKAGE = @PACKAGE@ PKGVERSION = @PKGVERSION@ BUGURL_TEXI = @REPORT_BUGS_TEXI@ -# Where is the source dir for the READLINE library doc? +# Where is the source dir for the READLINE library doc? # Traditionally readline is in .. or . READLINE_DIR = ${gdbdir}/../readline/readline/doc READLINE_TEXI_INCFLAG = @READLINE_TEXI_INCFLAG@ @@ -94,15 +94,15 @@ SET_TEXINPUTS = \ TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$(GDBMI_DIR):$$TEXINPUTS # Files which should be generated via 'info' and installed by 'install-info' -INFO_DEPS = gdb.info stabs.info annotate.info +INFO_DEPS = gdb.info annotate.info # Files which should be generated via 'dvi' and installed by 'install-dvi' -DVIFILES = gdb.dvi stabs.dvi refcard.dvi annotate.dvi +DVIFILES = gdb.dvi refcard.dvi annotate.dvi # Files which should be generated via 'pdf' and installed by 'install-pdf' -PDFFILES = gdb.pdf stabs.pdf refcard.pdf annotate.pdf +PDFFILES = gdb.pdf refcard.pdf annotate.pdf # Files which should be generated via 'html' and installed by 'install-html' -HTMLFILES = gdb/index.html stabs/index.html annotate/index.html -HTMLFILES_INSTALL = gdb stabs annotate +HTMLFILES = gdb/index.html annotate/index.html +HTMLFILES_INSTALL = gdb annotate # There may be alternate predefined collections of switches to configure # the GDB manual. Normally this is not done in synch with the software @@ -156,17 +156,6 @@ GDB_DOC_FILES = \ $(GDB_DOC_SOURCE_INCLUDES) \ $(GDB_DOC_BUILD_INCLUDES) -# Stabs manual: All files -STABS_DOC_SOURCE_INCLUDES = \ - $(srcdir)/fdl.texi -STABS_DOC_BUILD_INCLUDES = \ - gdb-cfg.texi \ - GDBvn.texi -STABS_DOC_FILES = \ - $(srcdir)/stabs.texinfo \ - $(STABS_DOC_SOURCE_INCLUDES) \ - $(STABS_DOC_BUILD_INCLUDES) - # Annotate migration document ANNOTATE_DOC_SOURCE_INCLUDES = \ $(srcdir)/fdl.texi @@ -207,7 +196,7 @@ all: info info: $(INFO_DEPS) dvi: $(DVIFILES) -ps: gdb.ps stabs.ps refcard.ps annotate.ps +ps: gdb.ps refcard.ps annotate.ps html: $(HTMLFILES) pdf: $(PDFFILES) man: $(MANS) @@ -236,10 +225,10 @@ doxy/gdbserver/index.html: Doxyfile-gdbserver Doxyfile-base -mkdir -p doxy $(DOXYGEN) Doxyfile-gdbserver -Doxyfile-base: $(srcdir)/Doxyfile-base.in +Doxyfile-base: $(srcdir)/Doxyfile-base.in $(doxyedit) $(srcdir)/Doxyfile-base.in >Doxyfile-base -Doxyfile-gdb-api: $(srcdir)/Doxyfile-gdb-api.in +Doxyfile-gdb-api: $(srcdir)/Doxyfile-gdb-api.in $(doxyedit) $(srcdir)/Doxyfile-gdb-api.in >Doxyfile-gdb-api Doxyfile-gdb-xref: $(srcdir)/Doxyfile-gdb-xref.in @@ -517,7 +506,7 @@ gdb.info: ${GDB_DOC_FILES} # GDB MANUAL: roff translations # Try to use a recent texi2roff. v2 was put on prep in jan91. -# If you want an index, see texi2roff doc for postprocessing +# If you want an index, see texi2roff doc for postprocessing # and add -i to texi2roff invocations below. # Workarounds for texi2roff-2 (probably fixed in later texi2roff's, delete # corresponding -e lines when later texi2roff's are current) @@ -526,7 +515,7 @@ gdb.info: ${GDB_DOC_FILES} # + @ (that's at-BLANK) not recognized by texi2roff, turned into blank # + @alphaenumerate is ridiculously new, turned into @enumerate -# texi2roff doesn't have a notion of include dirs, so we have to fake +# texi2roff doesn't have a notion of include dirs, so we have to fake # it out for gdb manual's include files---but only if not configured # in main sourcedir. links2roff: $(GDB_DOC_SOURCE_INCLUDES) @@ -550,7 +539,7 @@ gdb.me: $(GDB_DOC_FILES) links2roff $(srcdir)/gdb.texinfo | \ $(TEXI2ROFF) -me | \ sed -e 's/---/\\(em/g' \ - >gdb.me + >gdb.me # gdb manual suitable for [gtn]roff -ms gdb.ms: $(GDB_DOC_FILES) links2roff @@ -565,10 +554,10 @@ gdb.ms: $(GDB_DOC_FILES) links2roff $(srcdir)/gdb.texinfo | \ $(TEXI2ROFF) -ms | \ sed -e 's/---/\\(em/g' \ - >gdb.ms + >gdb.ms # gdb manual suitable for [tn]roff -mm -# '@noindent's removed due to texi2roff-2 mm bug; if yours is newer, +# '@noindent's removed due to texi2roff-2 mm bug; if yours is newer, # try leaving them in gdb.mm: $(GDB_DOC_FILES) links2roff $(ECHO_GEN) sed -e '/\\input texinfo/d' \ @@ -583,7 +572,7 @@ gdb.mm: $(GDB_DOC_FILES) links2roff $(srcdir)/gdb.texinfo | \ $(TEXI2ROFF) -mm | \ sed -e 's/---/\\(em/g' \ - >gdb.mm + >gdb.mm # GDB MANUAL: HTML file @@ -593,29 +582,6 @@ gdb/index.html: ${GDB_DOC_FILES} $(READLINE_TEXI_INCFLAG) -I ${GDBMI_DIR} -I $(srcdir) \ $(srcdir)/gdb.texinfo -stabs.info: $(STABS_DOC_FILES) - $(ECHO_MAKEINFO) $(MAKEINFO_CMD) -I $(srcdir) -o stabs.info $(srcdir)/stabs.texinfo - -# STABS DOCUMENTATION: HTML file - -stabs/index.html: $(STABS_DOC_FILES) - $(ECHO_GEN) $(MAKEHTML) $(MAKEHTMLFLAGS) \ - -o stabs \ - -I $(srcdir) \ - $(srcdir)/stabs.texinfo - -# STABS DOCUMENTATION: TeX dvi file -stabs.dvi : $(STABS_DOC_FILES) - $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) -I $(srcdir) \ - $(srcdir)/stabs.texinfo - -stabs.ps: stabs.dvi - $(ECHO_DVIPS) $(DVIPS) $(SILENT_Q_FLAG) -o $@ $? - -stabs.pdf: $(STABS_DOC_FILES) - $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) --pdf -I $(srcdir) \ - $(srcdir)/stabs.texinfo - # ANNOTATE DOCUMENTATION: TeX dvi file annotate.dvi : $(ANNOTATE_DOC_FILES) $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) -I $(srcdir) \ @@ -685,7 +651,7 @@ clean: mostlyclean distclean: clean rm -f Makefile -# GDBvn.texi, the dvi files, the info files, and the postscript files, +# GDBvn.texi, the dvi files, the info files, and the postscript files, # are all part of the distribution, so it should not be removed by # "clean" or "distclean". Use maintainer-clean to remove them. diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi index 970f930..d83435a 100644 --- a/gdb/doc/agentexpr.texi +++ b/gdb/doc/agentexpr.texi @@ -118,7 +118,7 @@ operations. There are no instructions to perform side effects on the running program, or call the program's functions; we assume that these expressions are only used for unobtrusive debugging, not for patching -the running code. +the running code. Most bytecode instructions do not distinguish between the various sizes of values, and operate on full-width values; the upper bits of the diff --git a/gdb/doc/all-cfg.texi b/gdb/doc/all-cfg.texi index 5d2af66..c44cabc 100644 --- a/gdb/doc/all-cfg.texi +++ b/gdb/doc/all-cfg.texi @@ -1,4 +1,4 @@ -@c GDB MANUAL configuration file. +@c GDB MANUAL configuration file. @c @c Copyright (C) 1993--2025 Free Software Foundation, Inc. @c @@ -10,8 +10,8 @@ @c @c The only automatically-varying variable is the GDB version number, @c which the Makefile rewrites based on the VERSION variable from -@c `../Makefile.in'. -@c +@c `../Makefile.in'. +@c @c GDB version number is recorded in the variable GDBVN @include GDBvn.texi @c @@ -30,7 +30,7 @@ @c @c Name of GDB program. Used also for (gdb) prompt string. @set GDBP gdb -@c +@c @c Name of GDB product. Used in running text. @set GDBN @sc{gdb} @c @@ -40,6 +40,6 @@ @c @c Name of GCC product @set NGCC @sc{gcc} -@c +@c @c Name of GCC program @set GCC gcc diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 362e6e7..bd5d025 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -898,14 +898,17 @@ debugger attached to a bare board, there may not be any notion of ``process'', and there is often no way to get a core dump. @value{GDBN} will warn you if it is unable to attach or to read core dumps. -You can optionally have @code{@value{GDBP}} pass any arguments after the -executable file to the inferior using @code{--args}. This option stops -option processing. +You can optionally have @code{@value{GDBP}} pass any arguments after +the executable file to the inferior using @code{--args} or +@code{--no-escape-args}. These options stop option processing. @smallexample @value{GDBP} --args gcc -O2 -c foo.c @end smallexample This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set -@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. +@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 +-c foo.c}. For the differences between @code{--args} and +@code{--no-escape-args}, see @ref{--args and --no-escape-args options, +,@code{--args} and @code{--no-escape-args}}. You can run @code{@value{GDBP}} without printing the front material, which describes @value{GDBN}'s non-warranty, by specifying @code{--silent} @@ -1212,6 +1215,17 @@ Run @value{GDBN} using @var{directory} as its data directory. The data directory is where @value{GDBN} searches for its auxiliary files. @xref{Data Files}. +@item -binary-output +@cindex @code{--binary-output} + +Instructs @value{GDBN} to set the translation mode of its +@code{stdout}/@code{stderr} to binary. MS-Windows only. Useful for +running the @value{GDBN} testsuite. By default, @value{GDBN} opens +@code{stdout}/@code{stderr} in text mode, and translates @samp{\n} +(LF, a single Line Feed) into @samp{\r\n} (CR-LF, a Carriage +Return-Line Feed combination). If this option is set, no translation +is done. + @item -fullname @itemx -f @cindex @code{--fullname} @@ -1240,12 +1254,67 @@ that control @value{GDBN}, and level 2 has been deprecated. The annotation mechanism has largely been superseded by @sc{gdb/mi} (@pxref{GDB/MI}). +@anchor{--args and --no-escape-args options} @item --args @cindex @code{--args} Change interpretation of command line so that arguments following the executable file are passed as command line arguments to the inferior. This option stops option processing. +Arguments supplied using @code{--args} will have backslashes applied +to escape any special shell characters. This ensures that when the +inferior starts it is passed arguments exactly as @value{GDBN} +receives them. + +For example, consider the following command run under a shell: + +@smallexample +$ @value{GDBP} --args ls *.c +@end smallexample + +@noindent +In this case the shell will expand @kbd{*.c} at the time @value{GDBN} +is invoked, not at the time that the inferior is invoked. As a +result, if an additional @kbd{.c} file is created after @value{GDBN} +is started, but before the inferior is started, then the inferior will +not show the file in its output; the list of matching files was +resolved at the time @value{GDBN} was started. + +If you quote the @kbd{*} character used on the @value{GDBN} command +line argument then this will prevent the shell that starts +@value{GDBN} from expanding the @kbd{*.c} pattern, however, this +quoting will also be passed to the shell that @value{GDBN} invokes in +order to start the inferior (@pxref{set startup-with-shell}), and this +will prevent the @kbd{*.c} pattern being expanded at this point either: + +@smallexample +$ @value{GDBP} --args ls '*.c' +(@value{GDBP}) show args +Argument list to give program being debugged when it is started is "\*.log". +@end smallexample + +@noindent +If this quoting behaviour does not meet your needs, then you could use +@code{--no-escape-args} instead, which is described below. + +@item --no-escape-args +@cindex @code{--no-escape-args} +Change interpretation of command line so that arguments following the +executable file are passed as command line arguments to the inferior. +This option stops option processing. + +Unlike @code{--args}, arguments after the executable name will not +have any escaping applied to them. As a result, any special shell +characters that are not expanded by the shell that invokes +@value{GDBN} will be expanded by the shell that @value{GDBN} uses to +start the inferior. + +@smallexample +$ @value{GDBP} --no-escape-args ls '*.c' +(@value{GDBP}) show args +Argument list to give program being debugged when it is started is "*.log". +@end smallexample + @item -baud @var{bps} @itemx -b @var{bps} @cindex @code{--baud} @@ -3298,6 +3367,7 @@ elements, even duplicates or overlapping ranges are valid. E.g.@: To find out what inferiors exist at any moment, use @w{@code{info inferiors}}: +@anchor{info inferiors command} @table @code @kindex info inferiors [ @var{id}@dots{} ] @item info inferiors @@ -3321,10 +3391,14 @@ the connection. @item the name of the executable the inferior is running. - @end enumerate @noindent +If an inferior is currently debugging a core file, then an additional +line will be printed after the line describing the inferior, this +additional line gives the file name of the core file being debugged. + +@noindent An asterisk @samp{*} preceding the @value{GDBN} inferior number indicates the current inferior. @@ -3336,7 +3410,19 @@ For example, (@value{GDBP}) info inferiors Num Description Connection Executable * 1 process 3401 1 (native) goodbye + 2 process 2307 2 (extended0remote host:10000) hello +@end smallexample + +Adding an additional inferior that is debugging a core file causes the +additional core file line to be displayed, for example@: + +@smallexample +(@value{GDBP}) info inferiors + Num Description Connection Executable +* 1 process 3401 1 (native) goodbye 2 process 2307 2 (extended-remote host:10000) hello + 3 process 1578 3 (core) broken + core file core.1578 @end smallexample To get information about the current inferior, use @code{inferior}: @@ -3439,8 +3525,40 @@ with no connection yet. You can then for example use the @code{target remote} command to connect to some other @code{gdbserver} instance, use @code{run} to spawn a local program, etc. +Not all connections can be shared between inferiors. For example, the +@code{target core} target is unique for each inferior. That is, +multiple inferiors can use @code{target core} at the same time, but +each @code{target core} is different. If you try to +@code{add-inferior}, and the current inferior is @code{target core}, +then @value{GDBN} will give a warning and create the new inferior +without a connection, like this@: + +@smallexample +(@value{GDBP}) file test1 +Reading symbols from test1... +(@value{GDBP}) target core core.test1.433190 +[New LWP 433190] +Core was generated by `./test1'. +Program terminated with signal SIGSEGV, Segmentation fault. +#0 0x0000000000401111 in foo () at test1.c:6 +6 return *global_ptr; +(@value{GDBP}) add-inferior +[New inferior 2] +warning: can't share connection 1 (core) between inferiors +Added inferior 2 +@end smallexample + +Another target that cannot be shared is @code{target remote} +(@pxref{Connecting,,Types of Remote Connections}). A remote target +doesn't allow new inferiors to be started, as such creating a new, +non-running, inferior that shares a remote connection doesn't make +sense. As with the core target above, if you try to +@code{add-inferior}, and the current inferior is @code{target remote}, +then @value{GDBN} will give a warning and create the new inferior +without a connection. + @kindex clone-inferior -@item clone-inferior [ -copies @var{n} ] [ @var{infno} ] +@item clone-inferior [ -copies @var{n} ] [ -no-connection ] [ @var{infno} ] Adds @var{n} inferiors ready to execute the same program as inferior @var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the number of the current inferior. This command copies the values of the @@ -3465,6 +3583,13 @@ Added inferior 2. You can now simply switch focus to inferior 2 and run it. +Like @code{add-inferior}, @code{clone-inferior} shares the connection +with the inferior @var{infno}. If the @var{-no-connection} option is +given, then the new inferior will be created without a connection. If +the connection of inferior @var{infno} can't be shared, then +@value{GDBN} will give a warning, and the new inferior will be created +without a connection. + @anchor{remove_inferiors_cli} @kindex remove-inferiors @item remove-inferiors @var{infno}@dots{} @@ -3547,10 +3672,6 @@ the program space number assigned by @value{GDBN} the name of the executable loaded into the program space, with e.g., the @code{file} command. -@item -the name of the core file loaded into the program space, with e.g., -the @code{core-file} command. - @end enumerate @noindent @@ -3563,7 +3684,7 @@ example, the list of inferiors bound to the program space. @smallexample (@value{GDBP}) maint info program-spaces - Id Executable Core File + Id Executable * 1 hello 2 goodbye Bound inferiors: ID 1 (process 21561) @@ -3577,7 +3698,7 @@ the parent and child processes of a @code{vfork} call. For example, @smallexample (@value{GDBP}) maint info program-spaces - Id Executable Core File + Id Executable * 1 vfork-test Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) @end smallexample @@ -3661,7 +3782,7 @@ programs: @item @samp{thread apply [@var{thread-id-list} | all] @var{args}}, a command to apply a command to a list of threads @item thread-specific breakpoints -@item @samp{set print thread-events}, which controls printing of +@item @samp{set print thread-events}, which controls printing of messages on thread start and exit. @item @samp{set libthread-db-search-path @var{path}}, which lets the user specify which @code{libthread_db} to use if the default choice @@ -3807,7 +3928,7 @@ Thread 1 "main" received signal SIGINT, Interrupt. @table @code @anchor{info_threads} @kindex info threads -@item info threads @r{[}-gid@r{]} @r{[}@var{thread-id-list}@r{]} +@item info threads @r{[}-gid@r{]} @r{[}-stopped@r{]} @r{[}-running@r{]} @r{[}@var{thread-id-list}@r{]} Display information about one or more threads. With no arguments displays information about all threads. You can specify the list of @@ -3857,6 +3978,14 @@ If you're debugging multiple inferiors, @value{GDBN} displays thread IDs using the qualified @var{inferior-num}.@var{thread-num} format. Otherwise, only @var{thread-num} is shown. +If you specify the @samp{-stopped} option, @value{GDBN} filters the +output of the command to print the stopped threads only. Similarly, +if you specify the @samp{-running} option, @value{GDBN} filters the +output to print the running threads only. These options can be +helpful to reduce the output list if there is a large number of +threads. If you specify both options, @value{GDBN} prints both +stopped and running threads. + If you specify the @samp{-gid} option, @value{GDBN} displays a column indicating each thread's global thread ID: @@ -3992,8 +4121,8 @@ system-give name, and removing the user-specified name will cause Search for and display thread ids whose name or @var{systag} matches the supplied regular expression. -As well as being the complement to the @samp{thread name} command, -this command also allows you to identify a thread by its target +As well as being the complement to the @samp{thread name} command, +this command also allows you to identify a thread by its target @var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag} is the LWP id. @@ -4001,7 +4130,7 @@ is the LWP id. (@value{GDBP}) thread find 26688 Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' (@value{GDBP}) info thread 4 - Id Target Id Frame + Id Target Id Frame 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () @end smallexample @@ -4069,8 +4198,8 @@ If none of @code{libthread_db} libraries initialize successfully, Setting @code{libthread-db-search-path} is currently implemented only on some platforms. -@kindex show libthread-db-search-path -@item show libthread-db-search-path +@kindex show libthread-db-search-path +@item show libthread-db-search-path Display current libthread_db search path. @kindex set debug libthread-db @@ -4216,14 +4345,14 @@ retain debugger control over them both. @table @code @item on The child process (or parent process, depending on the value of -@code{follow-fork-mode}) will be detached and allowed to run +@code{follow-fork-mode}) will be detached and allowed to run independently. This is the default. @item off Both processes will be held under the control of @value{GDBN}. -One process (child or parent, depending on the value of +One process (child or parent, depending on the value of @code{follow-fork-mode}) is debugged as usual, while the other -is held suspended. +is held suspended. @end table @@ -4352,8 +4481,8 @@ the critical statement, instead of having to restart your program from the beginning, you can just go back to the checkpoint and start again from there. -This can be especially useful if it takes a lot of time or -steps to reach the point where you think the bug occurs. +This can be especially useful if it takes a lot of time or +steps to reach the point where you think the bug occurs. To use the @code{checkpoint}/@code{restart} method of debugging: @@ -4437,7 +4566,7 @@ different execution path this time. @cindex checkpoints and process id Finally, there is one bit of internal program state that will be different when you return to a checkpoint --- the program's process -id. Each checkpoint will have a unique process id (or @var{pid}), +id. Each checkpoint will have a unique process id (or @var{pid}), and each will be different from the program's original @var{pid}. If your program has saved a local copy of its process id, this could potentially pose a problem. @@ -4445,15 +4574,15 @@ potentially pose a problem. @subsection A Non-obvious Benefit of Using Checkpoints On some systems such as @sc{gnu}/Linux, address space randomization -is performed on new processes for security reasons. This makes it +is performed on new processes for security reasons. This makes it difficult or impossible to set a breakpoint, or watchpoint, on an -absolute address if you have to restart the program, since the +absolute address if you have to restart the program, since the absolute location of a symbol will change from one execution to the next. -A checkpoint, however, is an @emph{identical} copy of a process. -Therefore if you create a checkpoint at (eg.@:) the start of main, -and simply return to that checkpoint instead of restarting the +A checkpoint, however, is an @emph{identical} copy of a process. +Therefore if you create a checkpoint at (eg.@:) the start of main, +and simply return to that checkpoint instead of restarting the process, you can avoid the effects of address randomization and your symbols will all stay in the same place. @@ -6278,7 +6407,7 @@ for more information on how to add @code{SystemTap} @acronym{SDT} probes in your applications.}. @code{SystemTap} probes are usable from assembly, C and C@t{++} languages@footnote{See @uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation} -for a good reference on how the @acronym{SDT} probes are implemented.}. +for a good reference on how the @acronym{SDT} probes are implemented.}. @item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace}) @acronym{USDT} probes. @code{DTrace} probes are usable from C and @@ -7194,9 +7323,9 @@ Depending on target support, @code{$_siginfo} may also be writable. (@pxref{Threads,, Debugging Programs with Multiple Threads}). There are two modes of controlling execution of your program within the debugger. In the default mode, referred to as @dfn{all-stop mode}, -when any thread in your program stops (for example, at a breakpoint -or while being stepped), all other threads in the program are also stopped by -@value{GDBN}. On some targets, @value{GDBN} also supports +when any thread in your program stops (for example, at a breakpoint +or while being stepped), all other threads in the program are also stopped by +@value{GDBN}. On some targets, @value{GDBN} also supports @dfn{non-stop mode}, in which other threads can continue to run freely while you examine the stopped thread in the debugger. @@ -7244,7 +7373,7 @@ Whenever @value{GDBN} stops your program, due to a breakpoint or a signal, it automatically selects the thread where that breakpoint or signal happened. @value{GDBN} alerts you to the context switch with a message such as @samp{[Switching to Thread @var{n}]} to identify the -thread. +thread. @anchor{set scheduler-locking} @@ -7549,7 +7678,7 @@ Tasks}); using more than one of the @code{thread}, @code{inferior}, or @code{task} keywords when creating a breakpoint will give an error. @node Interrupted System Calls -@subsection Interrupted System Calls +@subsection Interrupted System Calls @cindex thread breakpoints and system calls @cindex system calls and thread breakpoints @@ -7723,7 +7852,7 @@ targets may be able undo things like device I/O, and some may not. The contract between @value{GDBN} and the reverse executing target requires only that the target do something reasonable when -@value{GDBN} tells it to execute backwards, and then report the +@value{GDBN} tells it to execute backwards, and then report the results back to @value{GDBN}. Whatever the target reports back to @value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN} assumes that the memory and registers that the target reports are in a @@ -7782,7 +7911,7 @@ the current (innermost) stack frame. If the line contains function calls, they will be ``un-executed'' without stopping. Starting from the first line of a function, @code{reverse-next} will take you back to the caller of that function, @emph{before} the function was called, -just as the normal @code{next} command would take you from the last +just as the normal @code{next} command would take you from the last line of a function back to its return to its caller @footnote{Unless the code is too heavily optimized.}. @@ -10787,7 +10916,7 @@ Enter the index of the element you want to explore in `cs.arr': 5 (cs.arr)[5] = 4 -Press enter to return to parent value: +Press enter to return to parent value: @end smallexample In general, at any stage of exploration, you can go deeper towards the @@ -12638,7 +12767,7 @@ with the corresponding objfile (e.g., shared library). @xref{Objfiles In Python}, for more details on objfiles in Python. @end itemize -@xref{Selecting Pretty-Printers}, for further information on how +@xref{Selecting Pretty-Printers}, for further information on how pretty-printers are selected, @xref{Writing a Pretty-Printer}, for implementing pretty printers @@ -12652,7 +12781,7 @@ Here is how a C@t{++} @code{std::string} looks without a pretty-printer: @smallexample (@value{GDBP}) print s $1 = @{ - static npos = 4294967295, + static npos = 4294967295, _M_dataplus = @{ <std::allocator<char>> = @{ <__gnu_cxx::new_allocator<char>> = @{ @@ -13096,17 +13225,17 @@ variable which may be @samp{truecolor} or @samp{24bit}. Other color spaces are determined by the "Co" termcap which in turn depends on the @env{TERM} environment variable. -@vindex $_active_linker_namespaces@r{, convenience variable} -@item $_active_linker_namespaces -Number of active linkage namespaces in the inferior. In systems with no -support for linkage namespaces, this variable will always be set to @samp{1}. +@vindex $_linker_namespace_count@r{, convenience variable} +@item $_linker_namespace_count +Number of active linker namespaces in the inferior (@pxref{Files}). In systems +with no support for linker namespaces or if the inferior hasn't started, this +variable will always be set to @samp{0}. -@vindex $_current_linker_namespace@r{, convenience variable} -@item $_current_linker_namespace -The namespace which contains the current location in the inferior. This -returns GDB's internal identifier for namespaces, which is @samp{[[@var{n}]]} -where @var{n} is a zero-based namespace number. In systems with no support -for linkage namespaces, this variable will always be set to @samp{[[0]]}. +@vindex $_linker_namespace@r{, convenience variable} +@item $_linker_namespace +The namespace which contains the current location in the inferior. This returns +@value{GDBN}'s internal numbering for the namespace. In systems with no support +for linker namespaces, this variable will always be set to @samp{0}. @end table @@ -15721,7 +15850,7 @@ Num Type Disp Enb Address What end collect globfoo2 end - pass count 1200 + pass count 1200 2 tracepoint keep y <MULTIPLE> collect $eip 2.1 y 0x0804859c in func4 at change-loc.h:35 @@ -18731,7 +18860,7 @@ type = POINTER TO ARRAY [-2..2] OF foo = RECORD f1 : CARDINAL; f2 : CHAR; f3 : ARRAY [-2..2] OF CARDINAL; -END +END @end smallexample @node M2 Defaults @@ -18880,8 +19009,8 @@ to be difficult. @cindex expressions in Ada @menu -* Ada Mode Intro:: General remarks on the Ada syntax - and semantics supported by Ada mode +* Ada Mode Intro:: General remarks on the Ada syntax + and semantics supported by Ada mode in @value{GDBN}. * Omissions from Ada:: Restrictions on the Ada expression syntax. * Additions to Ada:: Extensions of the Ada expression syntax. @@ -18901,22 +19030,22 @@ to be difficult. @subsubsection Introduction @cindex Ada mode, general -The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression +The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression syntax, with some extensions. -The philosophy behind the design of this subset is +The philosophy behind the design of this subset is @itemize @bullet @item -That @value{GDBN} should provide basic literals and access to operations for -arithmetic, dereferencing, field selection, indexing, and subprogram calls, +That @value{GDBN} should provide basic literals and access to operations for +arithmetic, dereferencing, field selection, indexing, and subprogram calls, leaving more sophisticated computations to subprograms written into the program (which therefore may be called from @value{GDBN}). -@item +@item That type safety and strict adherence to Ada language restrictions are not particularly important to the @value{GDBN} user. -@item +@item That brevity is important to the @value{GDBN} user. @end itemize @@ -18926,13 +19055,13 @@ according to Ada rules, thus making it unnecessary to fully qualify most names with their packages, regardless of context. Where this causes ambiguity, @value{GDBN} asks the user's intent. -The debugger will start in Ada mode if it detects an Ada main program. +The debugger will start in Ada mode if it detects an Ada main program. As for other languages, it will enter Ada mode when stopped in a program that was translated from an Ada source file. -While in Ada mode, you may use `@t{--}' for comments. This is useful -mostly for documenting command files. The standard @value{GDBN} comment -(@samp{#}) still works at the beginning of a line in Ada mode, but not in the +While in Ada mode, you may use `@t{--}' for comments. This is useful +mostly for documenting command files. The standard @value{GDBN} comment +(@samp{#}) still works at the beginning of a line in Ada mode, but not in the middle (to allow based literals). @node Omissions from Ada @@ -18951,10 +19080,10 @@ Only a subset of the attributes are supported: on array objects (not on types and subtypes). @item -@t{'Min} and @t{'Max}. +@t{'Min} and @t{'Max}. -@item -@t{'Pos} and @t{'Val}. +@item +@t{'Pos} and @t{'Val}. @item @t{'Tag}. @@ -18963,8 +19092,8 @@ Only a subset of the attributes are supported: @t{'Range} on array objects (not subtypes), but only as the right operand of the membership (@code{in}) operator. -@item -@t{'Access}, @t{'Unchecked_Access}, and +@item +@t{'Access}, @t{'Unchecked_Access}, and @t{'Unrestricted_Access} (a GNAT extension). @item @@ -18985,20 +19114,20 @@ Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise equality of representations. They will generally work correctly for strings and arrays whose elements have integer or enumeration types. They may not work correctly for arrays whose element -types have user-defined equality, for arrays of real values +types have user-defined equality, for arrays of real values (in particular, IEEE-conformant floating point, because of negative zeroes and NaNs), and for arrays whose elements contain unused bits with -indeterminate values. +indeterminate values. @item -The other component-by-component array operations (@code{and}, @code{or}, +The other component-by-component array operations (@code{and}, @code{or}, @code{xor}, @code{not}, and relational tests other than equality) -are not implemented. +are not implemented. -@item +@item @cindex array aggregates (Ada) @cindex record aggregates (Ada) -@cindex aggregates (Ada) +@cindex aggregates (Ada) There is limited support for array and record aggregates. They are permitted only on the right sides of assignments, as in these examples: @@ -19016,7 +19145,7 @@ discriminant's value by assigning an aggregate has an undefined effect if that discriminant is used within the record. However, you can first modify discriminants by directly assigning to them (which normally would not be allowed in Ada), and then performing an -aggregate assignment. For example, given a variable @code{A_Rec} +aggregate assignment. For example, given a variable @code{A_Rec} declared to have a type such as: @smallexample @@ -19036,7 +19165,7 @@ assignments: As this example also illustrates, @value{GDBN} is very loose about the usual rules concerning aggregates. You may leave out some of the -components of an array or record aggregate (such as the @code{Len} +components of an array or record aggregate (such as the @code{Len} component in the assignment to @code{A_Rec} above); they will retain their original values upon assignment. You may freely use dynamic values as indices in component associations. You may even use overlapping or @@ -19060,16 +19189,16 @@ The @code{new} operator is not implemented. @item Entry calls are not implemented. -@item -Aside from printing, arithmetic operations on the native VAX floating-point +@item +Aside from printing, arithmetic operations on the native VAX floating-point formats are not supported. @item It is not possible to slice a packed array. @item -The names @code{True} and @code{False}, when not part of a qualified name, -are interpreted as if implicitly prefixed by @code{Standard}, regardless of +The names @code{True} and @code{False}, when not part of a qualified name, +are interpreted as if implicitly prefixed by @code{Standard}, regardless of context. Should your program redefine these names in a package or procedure (at best a dubious practice), @@ -19081,7 +19210,7 @@ Based real literals are not implemented. @node Additions to Ada @subsubsection Additions to Ada -@cindex Ada, deviations from +@cindex Ada, deviations from As it does for other languages, @value{GDBN} makes certain generic extensions to Ada (@pxref{Expressions}): @@ -19102,12 +19231,12 @@ which certain debugging information has been optimized away. appears in function or file @var{B}.'' When @var{B} is a file name, you must typically surround it in single quotes. -@item +@item The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type @var{type} that appears at address @var{addr}.'' @item -A name starting with @samp{$} is a convenience variable +A name starting with @samp{$} is a convenience variable (@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). @end itemize @@ -19115,7 +19244,7 @@ In addition, @value{GDBN} provides a few other shortcuts and outright additions specific to Ada: @itemize @bullet -@item +@item The assignment statement is allowed as an expression, returning its right-hand operand as its value. Thus, you may enter @@ -19124,8 +19253,8 @@ its right-hand operand as its value. Thus, you may enter (@value{GDBP}) print A(tmp := y + 1) @end smallexample -@item -The semicolon is allowed as an ``operator,'' returning as its value +@item +The semicolon is allowed as an ``operator,'' returning as its value the value of its right-hand operand. This allows, for example, complex conditional breaks: @@ -19148,13 +19277,13 @@ constant: zero means @code{Float} is used, one means $1 = 23.0 @end smallexample -@item -Rather than use catenation and symbolic character names to introduce special -characters into strings, one may instead use a special bracket notation, -which is also used to print strings. A sequence of characters of the form -@samp{["@var{XX}"]} within a string or character literal denotes the +@item +Rather than use catenation and symbolic character names to introduce special +characters into strings, one may instead use a special bracket notation, +which is also used to print strings. A sequence of characters of the form +@samp{["@var{XX}"]} within a string or character literal denotes the (single) character whose numeric encoding is @var{XX} in hexadecimal. The -sequence of characters @samp{["""]} also denotes a single quotation mark +sequence of characters @samp{["""]} also denotes a single quotation mark in strings. For example, @smallexample "One line.["0a"]Next line.["0a"]" @@ -19173,7 +19302,7 @@ to write @end smallexample @item -When printing arrays, @value{GDBN} uses positional notation when the +When printing arrays, @value{GDBN} uses positional notation when the array has a lower bound of 1, and uses a modified named notation otherwise. For example, a one-dimensional array of three integers with a lower bound of 3 might print as @@ -19183,30 +19312,30 @@ of 3 might print as @end smallexample @noindent -That is, in contrast to valid Ada, only the first component has a @code{=>} +That is, in contrast to valid Ada, only the first component has a @code{=>} clause. @item You may abbreviate attributes in expressions with any unique, -multi-character subsequence of +multi-character subsequence of their names (an exact match gets preference). For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} in place of @t{a'length}. @item @cindex quoting Ada internal identifiers -Since Ada is case-insensitive, the debugger normally maps identifiers you type -to lower case. The GNAT compiler uses upper-case characters for +Since Ada is case-insensitive, the debugger normally maps identifiers you type +to lower case. The GNAT compiler uses upper-case characters for some of its internal identifiers, which are normally of no interest to users. For the rare occasions when you actually have to look at them, -enclose them in angle brackets to avoid the lower-case mapping. +enclose them in angle brackets to avoid the lower-case mapping. For example, @smallexample (@value{GDBP}) print <JMPBUF_SAVE>[0] @end smallexample @item -Printing an object of class-wide type or dereferencing an +Printing an object of class-wide type or dereferencing an access-to-class-wide value will display all the components of the object's specific type (as indicated by its run-time tag). Likewise, component selection on such a value will operate on the specific type of the @@ -19235,7 +19364,7 @@ Multiple matches for f [0] cancel [1] foo.f (integer) return boolean at foo.adb:23 [2] foo.f (foo.new_integer) return boolean at foo.adb:28 -> +> @end smallexample In this case, just select one menu entry either to cancel expression evaluation @@ -19404,6 +19533,10 @@ The task has been created and is being made runnable. @item Selective Wait The task is waiting in a selective wait statement. +@item Suspension object sleep +The task is waiting in a call to @code{Suspend_Until_True} on a suspension +object. + @item Accepting RV with @var{taskno} The task is accepting a rendez-vous with the task @var{taskno}. @@ -19672,12 +19805,12 @@ Show the current source character set for Ada. Besides the omissions listed previously (@pxref{Omissions from Ada}), we know of several problems with and limitations of Ada mode in @value{GDBN}, -some of which will be fixed with planned future releases of the debugger +some of which will be fixed with planned future releases of the debugger and the GNU Ada compiler. @itemize @bullet -@item -Static constants that the compiler chooses not to materialize as objects in +@item +Static constants that the compiler chooses not to materialize as objects in storage are invisible to the debugger. @item @@ -19688,22 +19821,22 @@ argument lists are treated as positional). Many useful library packages are currently invisible to the debugger. @item -Fixed-point arithmetic, conversions, input, and output is carried out using -floating-point arithmetic, and may give results that only approximate those on +Fixed-point arithmetic, conversions, input, and output is carried out using +floating-point arithmetic, and may give results that only approximate those on the host machine. @item -The GNAT compiler never generates the prefix @code{Standard} for any of -the standard symbols defined by the Ada language. @value{GDBN} knows about +The GNAT compiler never generates the prefix @code{Standard} for any of +the standard symbols defined by the Ada language. @value{GDBN} knows about this: it will strip the prefix from names when you use it, and will never look for a name you have so qualified among local symbols, nor match against -symbols in other packages or subprograms. If you have -defined entities anywhere in your program other than parameters and -local variables whose simple names match names in @code{Standard}, +symbols in other packages or subprograms. If you have +defined entities anywhere in your program other than parameters and +local variables whose simple names match names in @code{Standard}, GNAT's lack of qualification here can cause confusion. When this happens, -you can usually resolve the confusion +you can usually resolve the confusion by qualifying the problematic names with package -@code{Standard} explicitly. +@code{Standard} explicitly. @end itemize Older versions of the compiler sometimes generate erroneous debugging @@ -20324,7 +20457,7 @@ if the debug information provides it, the program that compiled the file (which may include, e.g., the compiler version and command line arguments), @item whether the executable includes debugging information for that file, and -if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and +if so, what format the information is in (e.g., Dwarf 2), and @item whether the debugging information includes information about preprocessor macros. @@ -21909,9 +22042,7 @@ Warnings and Messages}.) We have not implemented the two-stage strategy for COFF yet. When the symbol table is stored in COFF format, @code{symbol-file} reads the -symbol table data in full right away. Note that ``stabs-in-COFF'' -still does the two-stage strategy, since the debug info is actually -in stabs format. +symbol table data in full right away. @kindex readnow @cindex reading symbols immediately @@ -21958,6 +22089,9 @@ wish to debug a core file instead, you must kill the subprocess in which the program is running. To do this, use the @code{kill} command (@pxref{Kill Process, ,Killing the Child Process}). +To see which core files are loaded into which inferiors, use the +@kbd{info inferiors} command (@pxref{info inferiors command}). + @kindex add-symbol-file @cindex dynamic linking @item add-symbol-file @var{filename} @r{[} -readnow @r{|} -readnever @r{]} @r{[} -o @var{offset} @r{]} @r{[} @var{textaddress} @r{]} @r{[} -s @var{section} @var{address} @dots{} @r{]} @@ -22234,11 +22368,18 @@ be determined then the address range for the @code{.text} section from the library will be listed. If the @code{.text} section cannot be found then no addresses will be listed. -On systems that support linkage namespaces, the output includes an +On systems that support linker namespaces, the output includes an additional column @code{NS} if the inferior has more than one active -namespace when the command is used. This column the linkage namespace +namespace when the command is used. This column the linker namespace that the shared library was loaded into. +@cindex linker namespaces +@dfn{Linker namespaces} are a feature of some standard libraries, that allow +shared objects to be loaded in isolated environment, eliminating the +possibility that those objects may cross-talk. Each set of isolated +shared objects is said to belong to a ``namespace'', and linker related +actions such as relocations do not cross namespace boundaries. + @kindex info dll @item info dll @var{regex} This is an alias of @code{info sharedlibrary}. @@ -23009,7 +23150,7 @@ Instead you must do, for example, $ gdb -iex "set use-deprecated-index-sections on" <program> @end smallexample -Indices only work when using DWARF debugging information, not stabs. +Indices only work when using DWARF debugging information. @subsection Automatic symbol index cache @@ -23692,7 +23833,7 @@ current exec-file loaded by @value{GDBN} (@pxref{set exec-file-mismatch}). @cindex symbol files, remote debugging @value{GDBN}, running on the host, needs access to symbol and debugging -information for your program running on the target. This requires +information for your program running on the target. This requires access to an unstripped copy of your program, and possibly any associated symbol files. Note that this section applies equally to both @code{target remote} mode and @code{target extended-remote} mode. @@ -24529,7 +24670,15 @@ a remote hardware watchpoint. Select the file used for @code{run} with @code{target extended-remote}. This should be set to a filename valid on the target system. If it is not set, the target will use a default -filename (e.g.@: the last program run). +filename (e.g.@: the last program run, or a filename derived from the +current executable if @value{GDBN} and the remote can see the same +file system). + +When connecting to a remote system, with @kbd{target extended-remote} +or @kbd{target remote}, if the remote server supports the +@code{qExecAndArgs} packet (@pxref{qExecAndArgs}), then the +@kbd{remote exec-file} will be updated to reflect the executable +currently running on the remote system. @item set remote interrupt-sequence @cindex interrupt remote programs @@ -24568,7 +24717,7 @@ debugging agent is launched in parallel with @value{GDBN}; there is a race condition because the agent may not become ready to accept the connection before @value{GDBN} attempts to connect. When auto-retry is enabled, if the initial attempt to connect fails, @value{GDBN} reattempts -to establish the connection using the timeout specified by +to establish the connection using the timeout specified by @code{set tcp connect-timeout}. @item set tcp auto-retry off @@ -24582,7 +24731,7 @@ Show the current auto-retry setting. @cindex connection timeout, for remote TCP target @cindex timeout, for remote target connection Set the timeout for establishing a TCP connection to the remote target to -@var{seconds}. The timeout affects both polling to retry failed connections +@var{seconds}. The timeout affects both polling to retry failed connections (enabled by @code{set tcp auto-retry on}) and waiting for connections that are merely slow to complete, and represents an approximate cumulative value. If @var{seconds} is @code{unlimited}, there is no timeout and @@ -24767,6 +24916,10 @@ future connections is shown. The available settings are: @tab @code{vFile:stat} @tab Host I/O +@item @code{hostio-lstat-packet} +@tab @code{vFile:lstat} +@tab Host I/O + @item @code{hostio-setfs-packet} @tab @code{vFile:setfs} @tab Host I/O @@ -24863,6 +25016,10 @@ future connections is shown. The available settings are: @tab @code{no resumed thread left stop reply} @tab Tracking thread lifetime. +@item @code{multiple-watchpoint-addresses} +@tab @code{multiple watchpoint stop reasons} +@tab Allow multiple, ambiguous, watchpoint addresses in @samp{T} stop reply. + @end multitable @cindex packet size, remote, configuring @@ -26285,7 +26442,7 @@ Show whether ARM-specific debugging messages are enabled. @end table @table @code -@item target sim @r{[}@var{simargs}@r{]} @dots{} +@item target sim @r{[}@var{simargs}@r{]} @dots{} The @value{GDBN} ARM simulator accepts the following optional arguments. @table @code @@ -26338,8 +26495,8 @@ This host system is used to download the configuration bitstream to the target FPGA. The Xilinx Microprocessor Debugger (XMD) program communicates with the target board using the JTAG interface and presents a @code{gdbserver} interface to the board. By default -@code{xmd} uses port @code{1234}. (While it is possible to change -this default port, it requires the use of undocumented @code{xmd} +@code{xmd} uses port @code{1234}. (While it is possible to change +this default port, it requires the use of undocumented @code{xmd} commands. Contact Xilinx support if you need to do this.) Use these GDB commands to connect to the MicroBlaze target processor. @@ -26549,7 +26706,7 @@ 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 @samp{on}. -Change to @samp{off} when using @code{gcc-cris} whose version is below +Change to @samp{off} when using @code{gcc-cris} whose version is below @code{R59}. @item show cris-dwarf2-cfi @@ -26558,7 +26715,7 @@ 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 +debugging in guru mode, in which case it should be set to @samp{guru} (the default is @samp{normal}). @item show cris-mode @@ -26630,8 +26787,9 @@ Show whether AArch64 debugging messages are displayed. @end table -@subsubsection AArch64 SVE. -@cindex AArch64 SVE. +@subsubsection AArch64 Scalable Vector Extension +@cindex Scalable Vector Extension, AArch64 +@cindex SVE, AArch64 When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Vector Extension (SVE) is present, then @value{GDBN} will provide the vector registers @@ -26670,11 +26828,10 @@ internally by @value{GDBN} and the Linux Kernel. @end itemize -@subsubsection AArch64 SME. +@subsubsection AArch64 Scalable Matrix Extension @anchor{AArch64 SME} -@cindex SME -@cindex AArch64 SME -@cindex Scalable Matrix Extension +@cindex Scalable Matrix Extension, AArch64 +@cindex SME, AArch64 The Scalable Matrix Extension (@url{https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/scalable-matrix-extension-armv9-a-architecture, @acronym{SME}}) is an AArch64 architecture extension that expands on the concept of the @@ -26866,11 +27023,10 @@ incorrect values for SVE registers (when in streaming mode). This is the same limitation we have for the @acronym{SVE} registers, and there are plans to address this limitation going forward. -@subsubsection AArch64 SME2. +@subsubsection AArch64 Scalable Matrix Extension 2 @anchor{AArch64 SME2} -@cindex SME2 -@cindex AArch64 SME2 -@cindex Scalable Matrix Extension 2 +@cindex Scalable Matrix Extension 2, AArch64 +@cindex SME2, AArch64 The Scalable Matrix Extension 2 is an AArch64 architecture extension that further expands the @acronym{SME} extension with the following: @@ -26910,8 +27066,9 @@ For more information about @acronym{SME2}, please refer to the official @url{https://developer.arm.com/documentation/ddi0487/latest, architecture documentation}. -@subsubsection AArch64 Pointer Authentication. -@cindex AArch64 Pointer Authentication. +@subsubsection AArch64 Pointer Authentication +@cindex Pointer Authentication, AArch64 +@cindex PAC, AArch64 @anchor{AArch64 PAC} When @value{GDBN} is debugging the AArch64 architecture, and the program is @@ -26921,8 +27078,9 @@ When GDB prints a backtrace, any addresses that required unmasking will be postfixed with the marker [PAC]. When using the MI, this is printed as part of the @code{addr_flags} field. -@subsubsection AArch64 Memory Tagging Extension. -@cindex AArch64 Memory Tagging Extension. +@subsubsection AArch64 Memory Tagging Extension +@cindex Memory Tagging Extension, AArch64 +@cindex MTE, AArch64 When @value{GDBN} is debugging the AArch64 architecture, the program is using the v8.5-A feature Memory Tagging Extension (MTE) and there is support @@ -26976,6 +27134,53 @@ information automatically from the core file, and will show one of the above messages depending on whether the synchronous or asynchronous mode is selected. @xref{Memory Tagging}. @xref{Memory}. +@subsubsection AArch64 Guarded Control Stack +@cindex Guarded Control Stack, AArch64 +@cindex GCS, AArch64 + +When @value{GDBN} is debugging the AArch64 architecture, the program is +using the feature Guarded Control Stack (GCS), the operating system kernel +is Linux and it supports GCS, @value{GDBN} will make a couple of special +registers --- @code{gcs_features_enabled} and @code{gcs_features_locked} +--- available through the @code{org.gnu.gdb.aarch64.gcs.linux} feature. +These registers expose some options that can be controlled at runtime and +emulate the @code{prctl} option @code{PR_SET_SHADOW_STACK_STATUS}. For +further information, see the +@uref{https://www.kernel.org/doc/html/latest/arch/arm64/gcs.html,ignored, +documentation} in the Linux kernel. + +Naturally the Guarded Control Stack pointer at @code{EL0} is also +available, as the @code{gcspr} register. + +To aid debugging, @value{GDBN} will note when SIGSEGV signals are generated +as a result of a Guarded Control Stack error: + +@smallexample +Program received signal SIGSEGV, Segmentation fault +Guarded Control Stack error. +@end smallexample + +@subsubsection AArch64 Floating Point Mode Register +@cindex floating point mode register, AArch64 +@cindex FPMR, AArch64 + +When @value{GDBN} is debugging the AArch64 architecture and the Floating Point +Mode Register (@acronym{FPMR}) is available, then @value{GDBN} will make the +@code{fpmr} available. This register determines the behavior of @code{FP8} +instructions. + +To aid debugging, @value{GDBN} interprets the mode or value of each field in +@code{fpmr}. + +@smallexample +p $fpmr +$1 = [ F8S1=E5M2 F8S2=E5M2 F8D=E5M2 OSM=Inf OSC=Inf/NaN LSCALE=0 NSCALE=0 LSCALE2=0 ] +@end smallexample + +For more information about @acronym{FPMR}, please refer to the official +@uref{https://developer.arm.com/documentation/ddi0601/latest,ignored, +architecture registers documentation}. + @node x86 @subsection x86 @@ -27017,6 +27222,46 @@ registers @end itemize +@subsubsection Intel Control-Flow Enforcement Technology. +@cindex Intel Control-Flow Enforcement Technology. + +The @dfn{Intel Control-Flow Enforcement Technology} (@acronym{Intel CET}) +provides two capabilities to defend against ``Return-oriented Programming'' +and ``call/jmp-oriented programming'' style control-flow attacks: + +@itemize @bullet +@item Shadow Stack: +A shadow stack is a second stack for a program. It holds the return +addresses pushed by the call instruction. The @code{RET} instruction pops the +return addresses from both call and shadow stack. If the return addresses from +the two stacks do not match, the processor signals a control protection +exception. +@item Indirect Branch Tracking (IBT): +When IBT is enabled, the CPU implements a state machine that tracks +indirect @code{JMP} and @code{CALL} instructions. The state machine can +be either IDLE or WAIT_FOR_ENDBRANCH. When a @code{JMP} or @code{CALL} is +executed the state machine chages to the WAIT_FOR_ENDBRANCH state. In +WAIT_FOR_ENDBRANCH state the next instruction in the program stream +must be an @code{ENDBR} instruction, otherwise the processor signals a +control protection exception. After executing a @code{ENDBR} instruction +the state machine returns to the IDLE state. +@end itemize + +Impact on @value{GDBN} commands: +@itemize @bullet +@item Call/Print: +Inferior calls in @value{GDBN} reset the current PC to the beginning of the +function that is called. No call instruction is executed, but the @code{RET} +instruction actually is. To avoid a control protection exception due to the +missing return address on the shadow stack, @value{GDBN} pushes the new return +address to the shadow stack and updates the shadow stack pointer. +@item Step: +With displaced stepping, @value{GDBN} may run an out of line copy of a call +instruction. In this case, the wrong return address is pushed to the shadow +stack. @value{GDBN} corrects this value to avoid a control protection +exception. For more details on displaced stepping, see @ref{displaced-stepping}. +@end itemize + @node Alpha @subsection Alpha @@ -27182,7 +27427,7 @@ given @var{address}. @subsection PowerPC @cindex PowerPC architecture -When @value{GDBN} is debugging the PowerPC architecture, it provides a set of +When @value{GDBN} is debugging the PowerPC architecture, it provides a set of pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point numbers stored in the floating point registers. These values must be stored in two consecutive registers, always starting at an even register like @@ -27201,38 +27446,38 @@ wide Extended Floating Point Registers (@samp{f32} through @samp{f63}). @cindex Application Data Integrity @subsubsection ADI Support -The M7 processor supports an Application Data Integrity (ADI) feature that -detects invalid data accesses. When software allocates memory and enables -ADI on the allocated memory, it chooses a 4-bit version number, sets the -version in the upper 4 bits of the 64-bit pointer to that data, and stores -the 4-bit version in every cacheline of that data. Hardware saves the latter -in spare bits in the cache and memory hierarchy. On each load and store, -the processor compares the upper 4 VA (virtual address) bits to the -cacheline's version. If there is a mismatch, the processor generates a -version mismatch trap which can be either precise or disrupting. The trap -is an error condition which the kernel delivers to the process as a SIGSEGV +The M7 processor supports an Application Data Integrity (ADI) feature that +detects invalid data accesses. When software allocates memory and enables +ADI on the allocated memory, it chooses a 4-bit version number, sets the +version in the upper 4 bits of the 64-bit pointer to that data, and stores +the 4-bit version in every cacheline of that data. Hardware saves the latter +in spare bits in the cache and memory hierarchy. On each load and store, +the processor compares the upper 4 VA (virtual address) bits to the +cacheline's version. If there is a mismatch, the processor generates a +version mismatch trap which can be either precise or disrupting. The trap +is an error condition which the kernel delivers to the process as a SIGSEGV signal. Note that only 64-bit applications can use ADI and need to be built with ADI-enabled. -Values of the ADI version tags, which are in granularity of a -cacheline (64 bytes), can be viewed or modified. +Values of the ADI version tags, which are in granularity of a +cacheline (64 bytes), can be viewed or modified. @table @code @kindex adi examine @item adi (examine | x) [ / @var{n} ] @var{addr} -The @code{adi examine} command displays the value of one ADI version tag per -cacheline. +The @code{adi examine} command displays the value of one ADI version tag per +cacheline. -@var{n} is a decimal integer specifying the number in bytes; the default -is 1. It specifies how much ADI version information, at the ratio of 1:ADI -block size, to display. +@var{n} is a decimal integer specifying the number in bytes; the default +is 1. It specifies how much ADI version information, at the ratio of 1:ADI +block size, to display. -@var{addr} is the address in user address space where you want @value{GDBN} -to begin displaying the ADI version tags. +@var{addr} is the address in user address space where you want @value{GDBN} +to begin displaying the ADI version tags. Below is an example of displaying ADI versions of variable "shmaddr". @@ -27244,19 +27489,19 @@ Below is an example of displaying ADI versions of variable "shmaddr". @kindex adi assign @item adi (assign | a) [ / @var{n} ] @var{addr} = @var{tag} -The @code{adi assign} command is used to assign new ADI version tag -to an address. +The @code{adi assign} command is used to assign new ADI version tag +to an address. -@var{n} is a decimal integer specifying the number in bytes; -the default is 1. It specifies how much ADI version information, at the -ratio of 1:ADI block size, to modify. +@var{n} is a decimal integer specifying the number in bytes; +the default is 1. It specifies how much ADI version information, at the +ratio of 1:ADI block size, to modify. -@var{addr} is the address in user address space where you want @value{GDBN} -to begin modifying the ADI version tags. +@var{addr} is the address in user address space where you want @value{GDBN} +to begin modifying the ADI version tags. @var{tag} is the new ADI version tag. -For example, do the following to modify then verify ADI versions of +For example, do the following to modify then verify ADI versions of variable "shmaddr": @smallexample @@ -27639,6 +27884,16 @@ or a prompt that does not. @item set prompt @var{newprompt} Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. +For example, this will set a blue-colored ``(gdb)'' prompt: + +@smallexample +set prompt \001\033[0;34m\002(gdb)\001\033[0m\002 +@end smallexample + +It uses @samp{\001} and @samp{\002} to begin and end a sequence of +non-printing characters, to make sure they're not counted in the string +length. + @kindex show prompt @item show prompt Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} @@ -27974,6 +28229,19 @@ value, then @value{GDBN} will change this to @samp{off} at startup. @item show style enabled Show the current state of styling. +@item set style emoji @samp{auto|on|off} +Enable or disable the use of emoji. On most hosts, the default is +@samp{auto}, meaning that emoji will only be used if the host +character set is @samp{UTF-8}; however, on Windows the default is +@samp{off} when using the console. Note that disabling styling as a +whole will also prevent emoji display. + +Currently, emoji are printed whenever @value{GDBN} reports an error or +a warning. + +@item show style emoji +Show the current state of emoji output. + @item set style sources @samp{on|off} Enable or disable source code styling. This affects whether source code, such as the output of the @code{list} command, is styled. The @@ -27990,6 +28258,18 @@ then it will be used. @item show style sources Show the current state of source code styling. +@anchor{warning-prefix} +@item set style warning-prefix +@itemx show style warning-prefix +@itemx set style error-prefix +@itemx show style error-prefix + +These commands control the prefix that is printed before warnings and +errors, respectively. This functionality is intended for use with +emoji display, and so the prefixes are only displayed if emoji styling +is enabled. The defaults are the warning sign emoji for warnings, and +and the cross mark emoji for errors. + @item set style tui-current-position @samp{on|off} Enable or disable styling of the source and assembly code highlighted by the TUI's current position indicator. The default is @samp{off}. @@ -29035,7 +29315,7 @@ Show the current state of @sc{gnu}/Hurd debugging messages. @item set debug infrun @cindex inferior debugging info Turns on or off display of @value{GDBN} debugging info for running the inferior. -The default is off. @file{infrun.c} contains GDB's runtime state machine used +The default is off. @file{infrun.c} contains GDB's runtime state machine used for implementing operations such as single-stepping the inferior. @item show debug infrun Displays the current state of @value{GDBN} inferior debugging. @@ -29305,6 +29585,32 @@ Continuing. Suppressing CLI notifications may be useful in scripts to obtain a reduced output from a list of commands. + +@kindex show local-environment +@item show local-environment @r{[}@var{varname}@r{]} +Print the value of the local environment variable @var{varname}. If +you do not supply @var{varname}, print the names and values of all +local environment variables. A local environment variable is used +when @value{GDBN} executes a local command, such as by the +@code{shell} command. + +@kindex set local-environment +@anchor{set local-environment} +@item set local-environment @var{varname} @r{[}=@var{value}@r{]} +Set environment variable @var{varname} to @var{value}. The value +changes for @value{GDBN} itself. The @var{value} may be any string; +the values of environment variables are just strings, and any +interpretation is supplied by your program itself. The @var{value} +parameter is optional; if it is eliminated, the variable is set to a +null value. + +@kindex unset local-environment +@anchor{unset local-environment} +@item unset local-environment @var{varname} +Remove variable @var{varname} from the local environment. This is +different from @samp{set local-environment @var{varname} =}; +@code{unset local-environment} removes the variable from the +environment, rather than assigning it an empty value. @end table @kindex show suppress-cli-notifications @@ -31292,138 +31598,13 @@ appropriate @code{set style} commands. @xref{Output Styling}. @cindex Emacs @cindex @sc{gnu} Emacs -A special interface allows you to use @sc{gnu} Emacs to view (and -edit) the source files for the program you are debugging with -@value{GDBN}. - -To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the -executable file you want to debug as an argument. This command starts -@value{GDBN} as a subprocess of Emacs, with input and output through a newly -created Emacs buffer. -@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) - -Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two -things: - -@itemize @bullet -@item -All ``terminal'' input and output goes through an Emacs buffer, called -the GUD buffer. - -This applies both to @value{GDBN} commands and their output, and to the input -and output done by the program you are debugging. - -This is useful because it means that you can copy the text of previous -commands and input them again; you can even use parts of the output -in this way. - -All the facilities of Emacs' Shell mode are available for interacting -with your program. In particular, you can send signals the usual -way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a -stop. - -@item -@value{GDBN} displays source code through Emacs. - -Each time @value{GDBN} displays a stack frame, Emacs automatically finds the -source file for that frame and puts an arrow (@samp{=>}) at the -left margin of the current line. Emacs uses a separate buffer for -source display, and splits the screen to show both your @value{GDBN} session -and the source. - -Explicit @value{GDBN} @code{list} or search commands still produce output as -usual, but you probably have no reason to use them from Emacs. -@end itemize - -We call this @dfn{text command mode}. Emacs 22.1, and later, also uses -a graphical mode, enabled by default, which provides further buffers -that can control the execution and describe the state of your program. -@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}. - -If you specify an absolute file name when prompted for the @kbd{M-x -gdb} argument, then Emacs sets your current working directory to where -your program resides. If you only specify the file name, then Emacs -sets your current working directory to the directory associated -with the previous buffer. In this case, @value{GDBN} may find your -program by searching your environment's @env{PATH} variable, but on -some operating systems it might not find the source. So, although the -@value{GDBN} input and output session proceeds normally, the auxiliary -buffer does not display the current source and line of execution. - -The initial working directory of @value{GDBN} is printed on the top -line of the GUD buffer and this serves as a default for the commands -that specify files for @value{GDBN} to operate on. @xref{Files, -,Commands to Specify Files}. - -By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you -need to call @value{GDBN} by a different name (for example, if you -keep several configurations around, with different names) you can -customize the Emacs variable @code{gud-gdb-command-name} to run the -one you want. - -In the GUD buffer, you can use these special Emacs commands in -addition to the standard Shell mode commands: - -@table @kbd -@item C-h m -Describe the features of Emacs' GUD Mode. - -@item C-c C-s -Execute to another source line, like the @value{GDBN} @code{step} command; also -update the display window to show the current file and location. - -@item C-c C-n -Execute to next source line in this function, skipping all function -calls, like the @value{GDBN} @code{next} command. Then update the display window -to show the current file and location. - -@item C-c C-i -Execute one instruction, like the @value{GDBN} @code{stepi} command; update -display window accordingly. - -@item C-c C-f -Execute until exit from the selected stack frame, like the @value{GDBN} -@code{finish} command. - -@item C-c C-r -Continue execution of your program, like the @value{GDBN} @code{continue} -command. -@item C-c < -Go up the number of frames indicated by the numeric argument -(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), -like the @value{GDBN} @code{up} command. +In @sc{gnu} Emacs there is a special interface to @value{GDBN}, which +facilitates viewing the source code for the program you are debugging. +There is also an IDE-like interface to GDB, with specialized buffers for +breakpoints, stack frames and other aspects of the debugger state. -@item C-c > -Go down the number of frames indicated by the numeric argument, like the -@value{GDBN} @code{down} command. -@end table - -In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break}) -tells @value{GDBN} to set a breakpoint on the source line point is on. - -In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a -separate frame which shows a backtrace when the GUD buffer is current. -Move point to any frame in the stack and type @key{RET} to make it -become the current frame and display the associated source in the -source buffer. Alternatively, click @kbd{Mouse-2} to make the -selected frame become the current one. In graphical mode, the -speedbar displays watch expressions. - -If you accidentally delete the source-display buffer, an easy way to get -it back is to type the command @code{f} in the @value{GDBN} buffer, to -request a frame display; when you run under Emacs, this recreates -the source buffer if necessary to show you the context of the current -frame. - -The source files displayed in Emacs are in ordinary Emacs buffers -which are visiting the source files in the usual way. You can edit -the files with these buffers if you wish; but keep in mind that @value{GDBN} -communicates with Emacs in terms of line numbers. If you add or -delete lines from the text, the line numbers that @value{GDBN} knows cease -to correspond properly with the code. - -A more detailed description of Emacs' interaction with @value{GDBN} is +A detailed description of Emacs' interaction with @value{GDBN} is given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}). @@ -31444,7 +31625,7 @@ in the form of a reference manual. Note that @sc{gdb/mi} is still under construction, so some of the features described below are incomplete and subject to change -(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). +(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). @unnumberedsec Notation and Terminology @@ -31530,7 +31711,7 @@ a command and reported as part of that command response. The important examples of notifications are: @itemize @bullet -@item +@item Exec notifications. These are used to report changes in target state---when a target is resumed, or stopped. It would not be feasible to include this information in response of resuming @@ -31539,7 +31720,7 @@ different threads. Also, quite some time may pass before any event happens in the target, while a frontend needs to know whether the resuming command itself was successfully executed. -@item +@item Console output, and status notifications. Console output notifications are used to report output of CLI commands, as well as diagnostics for other commands. Status notifications are used to @@ -31559,8 +31740,8 @@ orthogonal frontend design. There's no guarantee that whenever an MI command reports an error, @value{GDBN} or the target are in any specific state, and especially, the state is not reverted to the state before the MI command was -processed. Therefore, whenever an MI command results in an error, -we recommend that the frontend refreshes all the information shown in +processed. Therefore, whenever an MI command results in an error, +we recommend that the frontend refreshes all the information shown in the user interface. @@ -31582,7 +31763,7 @@ be specified. The CLI interface maintains the selected thread and frame, and supplies them to target on each command. This is convenient, because a command line user would not want to specify that information explicitly on each command, and because user interacts with -@value{GDBN} via a single terminal, so no confusion is possible as +@value{GDBN} via a single terminal, so no confusion is possible as to what thread and frame are the current ones. In the case of MI, the concept of selected thread and frame is less @@ -31608,7 +31789,7 @@ frontend's selection to the one specified by user. @value{GDBN} communicates the suggestion to change current thread and frame using the @samp{=thread-selected} notification. -Note that historically, MI shares the selected thread with CLI, so +Note that historically, MI shares the selected thread with CLI, so frontends used the @code{-thread-select} to execute commands in the right context. However, getting this to work right is cumbersome. The simplest way is for frontend to emit @code{-thread-select} command @@ -31637,7 +31818,7 @@ For instance: @smallexample -data-evaluate-expression --language c "sizeof (void*)" ^done,value="4" -(gdb) +(gdb) @end smallexample The valid language names are the same names accepted by the @@ -31718,8 +31899,8 @@ hardware systems, each one having several cores with several different processes running on each core. This section describes the MI mechanism to support such debugging scenarios. -The key observation is that regardless of the structure of the -target, MI can have a global list of threads, because most commands that +The key observation is that regardless of the structure of the +target, MI can have a global list of threads, because most commands that accept the @samp{--thread} option do not need to know what process that thread belongs to. Therefore, it is not necessary to introduce neither additional @samp{--process} option, nor an notion of the @@ -32260,7 +32441,7 @@ A breakpoint was reached. A watchpoint was triggered. @item read-watchpoint-trigger A read watchpoint was triggered. -@item access-watchpoint-trigger +@item access-watchpoint-trigger An access watchpoint was triggered. @item function-finished An -exec-finish or similar CLI command was accomplished. @@ -32269,15 +32450,15 @@ 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 +An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or similar CLI command was accomplished. -@item exited-signalled +@item exited-signalled The inferior exited because of a signal. -@item exited +@item exited The inferior exited. -@item exited-normally +@item exited-normally The inferior exited normally. -@item signal-received +@item signal-received A signal was received by the inferior. @item solib-event The inferior has stopped due to a library being loaded or unloaded. @@ -32442,6 +32623,9 @@ method in use supports multiple recording formats, @var{format} will be present and contain the currently used format. @xref{Process Record and Replay}, for existing method and format values. +If recording was stopped for the btrace method, threads move to the +end of their execution history. + @item =cmd-param-changed,param=@var{param},value=@var{value} Reports that a parameter of the command @code{set @var{param}} is changed to @var{value}. In the multi-word @code{set} command, @@ -34350,8 +34534,8 @@ other cases. @end smallexample Resumes the execution of the inferior program, which will continue -to execute until it reaches a debugger stop event. If the -@samp{--reverse} option is specified, execution resumes in reverse until +to execute until it reaches a debugger stop event. If the +@samp{--reverse} option is specified, execution resumes in reverse until it reaches a stop event. Stop events may include @itemize @bullet @item @@ -35346,10 +35530,10 @@ object, or to change display format. Variable objects have hierarchical tree structure. Any variable object that corresponds to a composite type, such as structure in C, has a number of child variable objects, for example corresponding to each -element of a structure. A child variable object can itself have -children, recursively. Recursion ends when we reach +element of a structure. A child variable object can itself have +children, recursively. Recursion ends when we reach leaf variable objects, which always have built-in types. Child variable -objects are created only by explicit request, so if a frontend +objects are created only by explicit request, so if a frontend is not interested in the children of a particular variable object, no child will be created. @@ -35358,7 +35542,7 @@ string, or set the value from a string. String value can be also obtained for a non-leaf variable object, but it's generally a string that only indicates the type of the object, and does not list its contents. Assignment to a non-leaf variable object is not allowed. - + A frontend does not need to read the values of all variable objects each time the program stops. Instead, MI provides an update command that lists all variable objects whose values has changed since the last update @@ -35375,7 +35559,7 @@ relatively slow for embedded targets, so a frontend might want to disable automatic update for the variables that are either not visible on the screen, or ``closed''. This is possible using so called ``frozen variable objects''. Such variable objects are never -implicitly updated. +implicitly updated. Variable objects can be either @dfn{fixed} or @dfn{floating}. For the fixed variable object, the expression is parsed when the variable @@ -35616,8 +35800,8 @@ but with padding zeroes to the left of the value. For example, a 32-bit hexadecimal value of 0x1234 would be represented as 0x00001234 in the zero-hexadecimal format. -For a variable with children, the format is set only on the -variable itself, and the children are not affected. +For a variable with children, the format is set only on the +variable itself, and the children are not affected. @findex -var-show-format @subheading The @code{-var-show-format} Command @@ -35833,7 +36017,7 @@ Returns an expression that can be evaluated in the current context and will yield the same value that a variable object has. Compare this with the @code{-var-info-expression} command, which result can be used only for UI presentation. Typical use of -the @code{-var-info-path-expression} command is creating a +the @code{-var-info-path-expression} command is creating a watchpoint from a variable object. This command is currently not valid for children of a dynamic varobj, @@ -35878,10 +36062,10 @@ where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. Evaluates the expression that is represented by the specified variable object and returns its value as a string. The format of the string -can be specified with the @samp{-f} option. The possible values of -this option are the same as for @code{-var-set-format} +can be specified with the @samp{-f} option. The possible values of +this option are the same as for @code{-var-set-format} (@pxref{-var-set-format}). If the @samp{-f} option is not specified, -the current display format will be used. The current display format +the current display format will be used. The current display format can be changed using the @code{-var-set-format} command. @smallexample @@ -36058,12 +36242,12 @@ type_changed="false"@}] Set the frozenness flag on the variable object @var{name}. The @var{flag} parameter should be either @samp{1} to make the variable frozen or @samp{0} to make it unfrozen. If a variable object is -frozen, then neither itself, nor any of its children, are -implicitly updated by @code{-var-update} of +frozen, then neither itself, nor any of its children, are +implicitly updated by @code{-var-update} of a parent variable or by @code{-var-update *}. Only @code{-var-update} of the variable itself will update its value and values of its children. After a variable object is unfrozen, it is -implicitly updated by all subsequent @code{-var-update} operations. +implicitly updated by all subsequent @code{-var-update} operations. Unfreezing a variable does not update it, only subsequent @code{-var-update} does. @@ -38397,7 +38581,7 @@ Signal handling commands are not implemented. Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}, or a thread group @var{gid}. If attaching to a thread -group, the id previously returned by +group, the id previously returned by @samp{-list-thread-groups --available} must be used. @subsubheading @value{GDBN} Command @@ -38950,7 +39134,7 @@ Example output: @smallexample (gdb) -list-features -^done,result=["feature1","feature2"] +^done,features=["feature1","feature2"] @end smallexample The current list of features is: @@ -39005,7 +39189,7 @@ to an array, structure, or union. @subheading The @code{-list-target-features} Command Returns a list of particular features that are supported by the -target. Those features affect the permitted MI commands, but +target. Those features affect the permitted MI commands, but unlike the features reported by the @code{-list-features} command, the features depend on which target GDB is using at the moment. Whenever a target can change, due to commands such as @code{-target-select}, @@ -39015,7 +39199,7 @@ Example output: @smallexample (gdb) -list-target-features -^done,result=["async"] +^done,features=["async"] @end smallexample The current list of features is: @@ -39393,6 +39577,11 @@ with no connection yet. You can then for example use the @code{gdbserver} instance, use @code{-exec-run} to spawn a local program, etc. +If the connection of the current inferior cannot be shared, e.g.@: the +@code{-target-select core} target cannot be shared between inferiors, +then @value{GDBN} will give a warning and create the new inferior +without a connection. + The command response always has a field, @var{inferior}, whose value is the identifier of the thread group corresponding to the new inferior. @@ -39464,7 +39653,7 @@ The corresponding @value{GDBN} command is @samp{remove-inferiors} @smallexample -interpreter-exec @var{interpreter} @var{command} @end smallexample -@anchor{-interpreter-exec} +@anchor{-interpreter-exec} Execute the specified @var{command} in the given @var{interpreter}. @@ -40091,7 +40280,7 @@ normal exception and not normally be logged. This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation interface. A JIT compiler is a program or library that generates native executable code at runtime and executes it, usually in order to achieve good -performance while maintaining platform independence. +performance while maintaining platform independence. Programs that use JIT compilation are normally difficult to debug because portions of their code are generated at runtime, instead of being loaded from @@ -41347,6 +41536,14 @@ Configure @value{GDBN} for cross-debugging programs running on the specified list of targets. The special value @samp{all} configures @value{GDBN} for debugging programs running on any target it supports. +@item --enable-binary-file-formats=@r{[}@var{format}@r{]}@dots{} +@itemx --enable-binary-file-formats=all +Configure @value{GDBN} to support certain binary file formats. If a +format is the main (or only) file format for a given target, the +configure script may add support to it anyway, and warn the user. +If not given, all file formats that @value{GDBN} supports are compiled +in. + @item --with-gdb-datadir=@var{path} Set the @value{GDBN}-specific data directory. @value{GDBN} will look here for certain supporting files or scripts. This defaults to the @@ -41434,7 +41631,7 @@ libpython is present and found at configure time.) Python makes @value{GDBN} scripting much more powerful than the restricted CLI scripting language. If your host does not have Python installed, you can find it on @url{http://www.python.org/download/}. The oldest version -of Python supported by GDB is 3.0.1. The optional argument @var{python} +of Python supported by GDB is 3.4. The optional argument @var{python} is used to find the Python headers and libraries. It can be either the name of a Python executable, or the name of the directory in which Python is installed. @@ -41523,7 +41720,7 @@ If @value{GDBN} has been configured with the option @option{--prefix=$prefix}, they may be subject to relocation. Two possible cases: @itemize @bullet -@item +@item If the default location of this init file/directory contains @file{$prefix}, it will be subject to relocation. Suppose that the configure options are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit}; @@ -41632,6 +41829,13 @@ into remote agent bytecodes and display them as a disassembled list. This command is useful for debugging the agent version of dynamic printf (@pxref{Dynamic Printf}). +@kindex maint canonicalize +@item maint canonicalize @var{name} +Print the canonical form of @var{name}, a C@t{++} name. Because a +C@t{++} name may have multiple possible spellings, @value{GDBN} +computes a canonical form of a name for internal use. For example, +@code{short int} and @code{short} are two ways to name the same type. + @kindex maint info breakpoints @anchor{maint info breakpoints} @item maint info breakpoints @@ -41785,6 +41989,7 @@ GLOBAL Disassembler_2 (Matches current architecture) @cindex out-of-line single-stepping @item set displaced-stepping @itemx show displaced-stepping +@anchor{displaced-stepping} Control whether or not @value{GDBN} will do @dfn{displaced stepping} if the target supports it. Displaced stepping is a way to single-step over breakpoints without removing them from the inferior, by executing @@ -42329,14 +42534,13 @@ and the full path if known. This command prints, for each object file in the program, various data about that object file followed by the byte cache (@dfn{bcache}) statistics for the object file. The objfile data includes the number -of minimal, partial, full, and stabs symbols, the number of types -defined by the objfile, the number of as yet unexpanded psym tables, -the number of line tables and string tables, and the amount of memory -used by the various tables. The bcache statistics include the counts, -sizes, and counts of duplicates of all and unique objects, max, -average, and median entry size, total memory used and its overhead and -savings, and various measures of the hash table size and chain -lengths. +of minimal, partial, and full, the number of types defined by the +objfile, the number of as yet unexpanded psym tables, the number of +line tables and string tables, and the amount of memory used by the +various tables. The bcache statistics include the counts, sizes, and +counts of duplicates of all and unique objects, max, average, and +median entry size, total memory used and its overhead and savings, +and various measures of the hash table size and chain lengths. @kindex maint print target-stack @cindex target stack description @@ -42761,6 +42965,26 @@ These are representative commands for each @var{kind} of setting type @value{GDBN} supports. They are used by the testsuite for exercising the settings infrastructure. +@kindex maint test-remote-args +@item maint test-remote-args @var{args} +For targets that don't support passing inferior arguments as a single +string (@pxref{single-inf-arg}), @value{GDBN} will attempt to split +the inferior arguments before passing them to the remote target, and +the remote target might choose to join the inferior arguments upon +receipt. Historically gdbserver did join inferior arguments, but now +it will request inferior arguments be passed as a single string if +@value{GDBN} supports this feature. + +This maintenance command splits @var{args} as @value{GDBN} would +normally split such an argument string before passing the arguments to +a remote target, the split arguments are then printed. + +The split arguments are then joined together as gdbserver would join +them, and the result is printed. + +This command is intended to help diagnose issues passing inferior +arguments to remote targets. + @kindex maint set backtrace-on-fatal-signal @kindex maint show backtrace-on-fatal-signal @item maint set backtrace-on-fatal-signal [on|off] @@ -42828,6 +43052,7 @@ reports and error and the command is aborted. @item show watchdog Show the current setting of the target wait timeout. + @end table @node Remote Protocol @@ -42921,7 +43146,7 @@ debugging stub incorporated in your program) sends a @var{response}. In the case of step and continue @var{command}s, the response is only sent when the operation has completed, and the target has again stopped all threads in all attached processes. This is the default all-stop mode -behavior, but the remote protocol also supports @value{GDBN}'s non-stop +behavior, but the remote protocol also supports @value{GDBN}'s non-stop execution mode; see @ref{Remote Non-Stop}, for details. @var{packet-data} consists of a sequence of characters with the @@ -43057,7 +43282,7 @@ bytes @samp{foo}, followed by a @var{bar}, followed directly by a @var{baz}. @cindex @var{thread-id}, in remote protocol -@anchor{thread-id syntax} +@anchor{thread-id syntax} Several packets and replies include a @var{thread-id} field to identify a thread. Normally these are positive numbers with a target-specific interpretation, formatted as big-endian hex strings. A @var{thread-id} @@ -43199,7 +43424,7 @@ Don't use this packet; instead, define a general set packet @item D @itemx D;@var{pid} @cindex @samp{D} packet -The first form of the packet is used to detach @value{GDBN} from the +The first form of the packet is used to detach @value{GDBN} from the remote system. It is sent to the remote target before @value{GDBN} disconnects via the @code{detach} command. @@ -43480,10 +43705,10 @@ attached without being stopped if that is supported by the target. @c In non-stop mode, on a successful vAttach, the stub should set the @c current thread to a thread of the newly-attached process. After @c attaching, GDB queries for the attached process's thread ID with qC. -@c Also note that, from a user perspective, whether or not the -@c target is stopped on attach in non-stop mode depends on whether you -@c use the foreground or background version of the attach command, not -@c on what vAttach does; GDB does the right thing with respect to either +@c Also note that, from a user perspective, whether or not the +@c target is stopped on attach in non-stop mode depends on whether you +@c use the foreground or background version of the attach command, not +@c on what vAttach does; GDB does the right thing with respect to either @c stopping or restarting threads. This packet is only available in extended mode (@pxref{extended mode}). @@ -43542,7 +43767,7 @@ in a degenerate way as a single instruction step operation.) @end table -The optional argument @var{addr} normally associated with the +The optional argument @var{addr} normally associated with the @samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is not supported in @samp{vCont}. @@ -43684,6 +43909,12 @@ command line. The file and arguments are hex-encoded strings. If (e.g.@: the last program run). The program is created in the stopped state. +If @value{GDBN} sent the @samp{single-inf-arg} feature in the +@samp{qSupported} packet (@pxref{single-inf-arg}), and the stub replied +with @samp{single-inf-arg+}, then there will only be a single +@var{argument} string, which includes all inferior arguments, +separated with whitespace. + @c FIXME: What about non-stop mode? This packet is only available in extended mode (@pxref{extended mode}). @@ -43955,8 +44186,24 @@ The currently defined stop reasons are: @item watch @itemx rwatch @itemx awatch -The packet indicates a watchpoint hit, and @var{r} is the data address, in -hex. +The packet indicates a watchpoint hit, and @var{r} is the data +address, in hex. + +Some targets, for example AArch64, are unable to accurately report the +address which triggered a watchpoint trap. As a consequence, multiple +watched addresses could explain a single watchpoint trap. + +If @value{GDBN} sent the @samp{multi-wp-addr} feature flag in its +@samp{qSupported} packet (@pxref{multi-wp-addr feature}), then +multiple instances of these stop reasons can appear in a single +@samp{T} stop reply packet. @value{GDBN} will select between the +multiple reported watchpoint addresses when displaying the stop to the +user. + +If the @samp{multi-wp-addr} was not sent by @value{GDBN}, then +@value{GDBN} only expects one watchpoint related stop address in a +single @samp{T} packet. The server must select the most likely +watchpoint address. @item syscall_entry @itemx syscall_return @@ -43971,10 +44218,10 @@ list of loaded libraries. The @var{r} part is ignored. @cindex replay log events, remote reply @item replaylog -The packet indicates that the target cannot continue replaying +The packet indicates that the target cannot continue replaying logged execution events, because it has reached the end (or the beginning when executing backward) of the log. The value of @var{r} -will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, +will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, for more information. @item swbreak @@ -44226,7 +44473,7 @@ Return the current thread ID. Reply: @table @samp @item QC @var{thread-id} -Where @var{thread-id} is a thread ID as documented in +Where @var{thread-id} is a thread ID as documented in @ref{thread-id syntax}. @item @r{(anything else)} Any other reply implies the old thread ID. @@ -44480,7 +44727,7 @@ information associated with the variable.) @var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of 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. +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. @@ -44651,7 +44898,7 @@ kept at fixed offsets relative to the last relocated segment. @cindex thread information, remote request @cindex @samp{qP} packet Returns information on @var{thread-id}. Where: @var{mode} is a hex -encoded 32 bit mode; @var{thread-id} is a thread ID +encoded 32 bit mode; @var{thread-id} is a thread ID (@pxref{thread-id syntax}). Don't use this packet; use the @samp{qThreadExtraInfo} query instead @@ -44675,7 +44922,7 @@ The request succeeded. This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). -Use of this packet is controlled by the @code{set non-stop} command; +Use of this packet is controlled by the @code{set non-stop} command; @pxref{Non-Stop Mode}. @item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{} @@ -44718,7 +44965,7 @@ by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). @cindex pass signals to inferior, remote request @cindex @samp{QPassSignals} packet @anchor{QPassSignals} -Each listed @var{signal} should be passed directly to the inferior process. +Each listed @var{signal} should be passed directly to the inferior process. Signals are numbered identically to continue packets and stop replies (@pxref{Stop Reply Packets}). Each @var{signal} list item should be strictly greater than the previous item. These signals do not need to stop @@ -44925,7 +45172,8 @@ packets.) @anchor{qSearch memory} Search @var{length} bytes at @var{address} for @var{search-pattern}. Both @var{address} and @var{length} are encoded in hex; -@var{search-pattern} is a sequence of bytes, also hex encoded. +@var{search-pattern} is a sequence of binary-encoded bytes +(@pxref{Binary Data}). Reply: @table @samp @@ -45006,11 +45254,11 @@ state, even if the stub had previously been communicating with a different version of @value{GDBN}. The following values of @var{gdbfeature} (for the packet sent by @value{GDBN}) -are defined: +are defined: @table @samp @item multiprocess -This feature indicates whether @value{GDBN} supports multiprocess +This feature indicates whether @value{GDBN} supports multiprocess extensions to the remote protocol. @value{GDBN} does not use such extensions unless the stub also reports that it supports them by including @samp{multiprocess+} in its @samp{qSupported} reply. @@ -45067,6 +45315,24 @@ didn't support @samp{E.@var{errtext}}, and older versions of New packets should be written to support @samp{E.@var{errtext}} regardless of this feature being true or not. + +@anchor{single-inf-arg} +@item single-inf-arg +This feature indicates that @value{GDBN} would like to send the +inferior arguments as a single string within the @samp{vRun} packet. +@value{GDBN} will not send the arguments as a single string unless the +stub also reports that it supports this behaviour by including +@samp{single-inf-arg+} in its @samp{qSupported} reply. + +@anchor{multi-wp-addr feature} +@item multi-wp-addr +This features indicates that @value{GDBN} supports receiving multiple +watchpoint addresses in the @samp{T} stop reply packet (@pxref{Stop +Reply Packets}). + +Use of this feature is controlled by the @code{set remote +multiple-watchpoint-addresses-packet} command (@pxref{Remote +Configuration, set remote multiple-watchpoint-addresses-packet}). @end table Stubs should ignore any unknown values for @@ -45370,6 +45636,16 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab No +@item @samp{single-inf-arg} +@tab No +@tab @samp{-} +@tab No + +@item @samp{multi-wp-addr} +@tab No +@tab @samp{+} +@tab No + @end multitable These are the currently defined stub features, in more detail: @@ -45619,6 +45895,20 @@ if it sent the @samp{error-message} feature. @item binary-upload The remote stub supports the @samp{x} packet (@pxref{x packet}). + +@item single-inf-arg +The remote stub would like to receive the inferior arguments as a +single string within the @samp{vRun} packet. The stub should only +send this feature if @value{GDBN} sent @samp{single-inf-arg+} in the +@samp{qSupported} packet. + +@item multi-wp-addr +The remote stub supports sending multiple watchpoint addresses within +@samp{T} stop reply packet. Stubs that don't support this feature +don't need to tell @value{GDBN}. Not supporting this feature just +means sending back one watchpoint address instead of multiple, and +@value{GDBN} has always supported receiving a single watchpoint +address. @end table @item qSymbol:: @@ -45702,13 +45992,13 @@ packets.) @itemx QTSave @itemx qTsP @itemx qTsV -@itemx QTStart -@itemx QTStop +@itemx QTStart +@itemx QTStop @itemx QTEnable @itemx QTDisable -@itemx QTinit -@itemx QTro -@itemx qTStatus +@itemx QTinit +@itemx QTro +@itemx qTStatus @itemx qTV @itemx qTfSTM @itemx qTsSTM @@ -45836,7 +46126,7 @@ stub indicated it supports the augmented form of this packet by supplying an appropriate @samp{qSupported} response (@pxref{qXfer read}, @ref{qSupported}). -This packet is optional for better performance on SVR4 targets. +This packet is optional for better performance on SVR4 targets. @value{GDBN} uses memory read packets to read the SVR4 library list otherwise. This packet is not probed by default; the remote stub must request it, @@ -46007,6 +46297,45 @@ The remote server attached to an existing process. The remote server created a new process. @end table +@cindex query executable, remote request +@cindex query program arguments, remote request +@cindex @samp{qExecAndArgs} packet +@item qExecAndArgs +@anchor{qExecAndArgs} +Return the program filename and arguments string with which the remote +server was started, if the remote server was started with such things. +If the remote server was started without the filename of a program to +execute, or without any arguments, then the reply indicates this. + +Reply: +@table @samp +@item U +The program filename and arguments are unset. If @value{GDBN} wants +to start a new inferior, for example with @samp{vRun}, then it will +need to provide the filename of a program to use. + +@item S;@var{prog};@var{args}; +@itemx S;;@var{args}; +The program filename provided to the remote server when it started was +@var{prog}, which is a hex encoded string. The complete argument +string passed to the inferior when it started as @var{args}, this is +also a hex encoded string. + +If no arguments were passed when the inferior started then @var{args} +be an empty string. + +It is valid for @var{prog} to be the empty string, this indicates that +the server has no program set, @value{GDBN} will need to supply a +program name in order to start a new inferior. It is valid to reply +with an empty @var{prog} and non-empty @var{args}, @value{GDBN} will +set the inferior arguments, but the user will need to supply a remote +exec-file before an inferior can be started. + +The argument string @var{args} is passed directly to @value{GDBN} as +if to the @kbd{set args} command. And escaping required should be +present in @var{args}, no changes are made by @value{GDBN}. +@end table + @item Qbtrace:bts Enable branch tracing for the current thread using Branch Trace Store. @@ -46804,12 +47133,28 @@ If an error occurs the return value is -1. The format of the returned binary attachment is as described in @ref{struct stat}. @item vFile:stat: @var{filename} -Get information about the file @var{filename} on the target. -On success the information is returned as a binary attachment -and the return value is the size of this attachment in bytes. -If an error occurs the return value is -1. The format of the +Get information about the file @var{filename} on the target as if from +a @samp{stat} call. On success the information is returned as a binary +attachment and the return value is the size of this attachment in +bytes. If an error occurs the return value is -1. The format of the returned binary attachment is as described in @ref{struct stat}. +If @var{filename} is a symbolic link, then the information returned is +about the file the link refers to, this is inline with the @samp{stat} +library call. + +@item vFile:lstat: @var{filename} +Get information about the file @var{filename} on the target as if from +an @samp{lstat} call. On success the information is returned as a +binary attachment and the return value is the size of this attachment +in bytes. If an error occurs the return value is -1. The format of +the returned binary attachment is as described in @ref{struct stat}. + +This packet is identical to @samp{vFile:stat}, except if +@var{filename} is a symbolic link, then this packet returns +information about the link itself, not the file that the link refers +to, this is inline with the @samp{lstat} library call. + @item vFile:unlink: @var{filename} Delete the file at @var{filename} on the target. Return 0, or -1 if an error occurs. The @var{filename} is a string. @@ -46879,7 +47224,7 @@ packet}) with the usual packet framing instead of the single byte Stubs are not required to recognize these interrupt mechanisms and the precise meaning associated with receipt of the interrupt is implementation defined. If the target supports debugging of multiple -threads and/or processes, it should attempt to interrupt all +threads and/or processes, it should attempt to interrupt all currently-executing threads and processes. If the stub is successful at interrupting the running program, it should send one of the stop @@ -47011,7 +47356,7 @@ The following notifications are defined: @tab vStopped @tab @var{reply}. The @var{reply} has the form of a stop reply, as described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop}, -for information on how these notifications are acknowledged by +for information on how these notifications are acknowledged by @value{GDBN}. @tab Report an asynchronous stop event in non-stop mode. @@ -47045,7 +47390,7 @@ to run. When reporting a @samp{W} or @samp{X} response, all running threads belonging to other attached processes continue to run. In non-stop mode, the target shall respond to the @samp{?} packet as -follows. First, any incomplete stop reply notification/@samp{vStopped} +follows. First, any incomplete stop reply notification/@samp{vStopped} sequence in progress is abandoned. The target must begin a new sequence reporting stop events for all stopped threads, whether or not it has previously reported those events to @value{GDBN}. The first @@ -47180,12 +47525,12 @@ It uses its own internal representation of datatypes and values. Both translating the system-dependent value representations into the internal protocol representations when data is transmitted. -The communication is synchronous. A system call is possible only when -@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} +The communication is synchronous. A system call is possible only when +@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} or @samp{s} packets. While @value{GDBN} handles the request for a system call, the target is stopped to allow deterministic access to the target's memory. Therefore File-I/O is not interruptible by target signals. On -the other hand, it is possible to interrupt File-I/O by a user interrupt +the other hand, it is possible to interrupt File-I/O by a user interrupt (@samp{Ctrl-C}) within @value{GDBN}. The target's request to perform a host system call does not finish @@ -47203,7 +47548,7 @@ request from @value{GDBN} is required. <- target hits breakpoint and sends a Txx packet @end smallexample -The protocol only supports I/O on the console and to regular files on +The protocol only supports I/O on the console and to regular files on the host file system. Character or block special devices, pipes, named pipes, sockets or any other communication method on the host system are not supported by this protocol. @@ -47216,7 +47561,7 @@ File I/O is not supported in non-stop mode. The File-I/O protocol uses the @code{F} packet as the request as well as reply packet. Since a File-I/O system call can only occur when -@value{GDBN} is waiting for a response from the continuing or stepping target, +@value{GDBN} is waiting for a response from the continuing or stepping target, the File-I/O request is a reply that @value{GDBN} has to expect as a result of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. This @code{F} packet contains all information needed to allow @value{GDBN} @@ -47238,7 +47583,7 @@ At this point, @value{GDBN} has to perform the following actions. @itemize @bullet @item -If the parameters include pointer values to data needed as input to a +If the parameters include pointer values to data needed as input to a system call, @value{GDBN} requests this data from the target with a standard @code{m} packet request. This additional communication has to be expected by the target implementation and is handled as any other @code{m} @@ -47294,11 +47639,11 @@ The @code{F} request packet has the following format: @var{call-id} is the identifier to indicate the host system call to be called. This is just the name of the function. -@var{parameter@dots{}} are the parameters to the system call. +@var{parameter@dots{}} are the parameters to the system call. Parameters are hexadecimal integer values, either the actual values in case of scalar datatypes, pointers to target buffer space in case of compound datatypes and unspecified memory areas, or pointer/length pairs in case -of string parameters. These are appended to the @var{call-id} as a +of string parameters. These are appended to the @var{call-id} as a comma-delimited list. All values are transmitted in ASCII string representation, pointer/length pairs separated by a slash. @@ -47966,10 +48311,10 @@ The call was interrupted by the user. @end table -@value{GDBN} takes over the full task of calling the necessary host calls -to perform the @code{system} call. The return value of @code{system} on +@value{GDBN} takes over the full task of calling the necessary host calls +to perform the @code{system} call. The return value of @code{system} on the host is simplified before it's returned -to the target. Any termination signal information from the child process +to the target. Any termination signal information from the child process is discarded, and the return value consists entirely of the exit status of the called command. @@ -48005,9 +48350,9 @@ protocol. @unnumberedsubsubsec Integral Datatypes @cindex integral datatypes, in file-i/o protocol -The integral datatypes used in the system calls are @code{int}, +The integral datatypes used in the system calls are @code{int}, @code{unsigned int}, @code{long}, @code{unsigned long}, -@code{mode_t}, and @code{time_t}. +@code{mode_t}, and @code{time_t}. @code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are implemented as 32 bit values in this protocol. @@ -48051,10 +48396,10 @@ at address 0x123456 is transmitted as @cindex memory transfer, in file-i/o protocol Structured data which is transferred using a memory read or write (for -example, a @code{struct stat}) is expected to be in a protocol-specific format +example, a @code{struct stat}) is expected to be in a protocol-specific format with all scalar multibyte datatypes being big endian. Translation to -this representation needs to be done both by the target before the @code{F} -packet is sent, and by @value{GDBN} before +this representation needs to be done both by the target before the @code{F} +packet is sent, and by @value{GDBN} before it transfers memory to the target. Transferred pointers to structured data should point to the already-coerced data at any time. @@ -48063,7 +48408,7 @@ data should point to the already-coerced data at any time. @unnumberedsubsubsec struct stat @cindex struct stat, in file-i/o protocol -The buffer of type @code{struct stat} used by the target and @value{GDBN} +The buffer of type @code{struct stat} used by the target and @value{GDBN} is defined as follows: @smallexample @@ -48204,6 +48549,7 @@ All values are given in decimal representation. EPERM 1 ENOENT 2 EINTR 4 + EIO 5 EBADF 9 EACCES 13 EFAULT 14 @@ -48219,6 +48565,7 @@ All values are given in decimal representation. ENOSPC 28 ESPIPE 29 EROFS 30 + ENOSYS 88 ENAMETOOLONG 91 EUNKNOWN 9999 @end smallexample @@ -49277,6 +49624,7 @@ registers using the capitalization used in the description. @menu * AArch64 Features:: +* Alpha Features:: * ARC Features:: * ARM Features:: * i386 Features:: @@ -49540,8 +49888,8 @@ it should contain registers @code{ZA}, @code{SVG} and @code{SVCR}. @itemize @minus @item -@code{ZA} is a register represented by a vector of @var{svl}x@var{svl} -bytes. @xref{svl}. +@code{ZA} is a register represented by a 2-dimensional array of bytes, with each +dimension having size @var{svl}. @xref{svl}. @item @code{SVG} is a 64-bit register containing the value of @var{svg}. @xref{svg}. @@ -49583,6 +49931,155 @@ of bytes. Extra registers are allowed in this feature, but they will not affect @value{GDBN}. +@subsubsection AArch64 GCS registers feature + +The @samp{org.gnu.gdb.aarch64.gcs} feature is optional. If present, it +means the target supports Guarded Control Stacks and must contain the +following register: + +@itemize @minus + +@item +@code{gcspr}, which points to the thread's Guarded Control Stack. It is 64 +bits in size and has a type of @samp{data_ptr}. + +@end itemize + +The @samp{org.gnu.gdb.aarch64.gcs.linux} feature is optional. If present, +then the @samp{org.gnu.gdb.aarch64.gcs} feature must also be present. The +@samp{org.gnu.gdb.aarch64.gcs.linux} feature represents facilities provided +by the Linux kernel for GCS support and should contain the following: + +@itemize @minus + +@item +@code{gcs_features_enabled} shows the features currently enabled via the +prctl or ptrace system calls. It is represented as if it were a 64-bit +register with a custom flags type. + +@item +@code{gcs_features_locked} shows the features currently locked via the +prctl or ptrace system calls. It is represented as if it were a 64-bit +register with a custom flags type. + +@end itemize + +The custom flags type allows @value{GDBN} to print a human-friendly +representation of the contents of @code{gcs_features_enabled} and +@code{gcs_features_locked} and should contain: + +@itemize @minus + +@item +@code{PR_SHADOW_STACK_ENABLE} + +@item +@code{PR_SHADOW_STACK_WRITE} + +@item +@code{PR_SHADOW_STACK_PUSH} + +@end itemize + +For further information, see the +@uref{https://www.kernel.org/doc/html/latest/arch/arm64/gcs.html,ignored, +documentation} in the Linux kernel. + +Extra registers are allowed in these features, but they will not affect +@value{GDBN}. + +@subsubsection AArch64 FPMR feature + +The @samp{org.gnu.gdb.aarch64.fpmr} optional feature was introduced so +@value{GDBN} could detect support for the Floating Point Mode Register +extension. If present, this feature must have the following register: + +@itemize @minus +@item +@samp{fpmr}, the floating point mode register. It is represented as +if it were a 64-bit register with a custom flags type. +@end itemize + +The custom flags type allows @value{GDBN} to print a human-friendly +representation of the contents of @code{fpmr} should contain: + +@itemize @minus + +@item +@code{F8S1}, which is either @code{E5M2} or @code{E4M3} + +@item +@code{F8S2}, which is either @code{E5M2} or @code{E4M3} + +@item +@code{F8D}, which is either @code{E5M2} or @code{E4M3} + +@item +@code{OSM}, which is either @code{Inf} or @code{MaxNormal} + +@item +@code{OSC}, which is either @code{Inf/NaN} or @code{MaxNormal} + +@item +@code{LSCALE}, which is a 7-bit unsigned value + +@item +@code{NSCALE}, which is actually an 8-bit signed value but represented as an +8-bit unsigned value + +@item +@code{LSCALE2}, which is a 6-bit unsigned value + +@end itemize + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +For more information about @acronym{FPMR}, please refer to the official +@uref{https://developer.arm.com/documentation/ddi0601/latest,ignored, +architecture registers documentation}. + +@node Alpha Features +@subsection Alpha Features +@cindex target descriptions, Alpha Features + +The @samp{org.gnu.gdb.alpha.core} feature is required for Alpha targets. It +must contain the following 64-bit registers; note that @value{GDBN} uses the +software names for Alpha registers: + +@itemize @minus +@item +@samp{v0}: function return value +@item +@samp{t0} through @samp{t12}: temporary registers +@item +@samp{s0} through @samp{s5}: saved registers +@item +@samp{fp}: frame pointer +@item +@samp{a0} through @samp{a5}: argument registers +@item +@samp{ra}: return address +@item +@samp{at}: assembler temporary register +@item +@samp{gp}: global pointer +@item +@samp{sp}: stack pointer +@item +@samp{zero}: always zero +@item +@samp{f0} through @samp{f30}: floating-point registers +@item +@samp{fpcr}: floating-point control register +@item +@samp{pc}: program counter +@item +@samp{}: an anonymous register for historical purpose +@item +@samp{unique}: PALcode memory slot +@end itemize + @node ARC Features @subsection ARC Features @cindex target descriptions, ARC Features @@ -49932,9 +50429,9 @@ targets. It should describe the following registers: @item @samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es}, @samp{fs}, @samp{gs} -@item +@item @samp{st0} through @samp{st7} -@item +@item @samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff}, @samp{foseg}, @samp{fooff} and @samp{fop} @end itemize @@ -49949,7 +50446,7 @@ describe registers: @samp{xmm0} through @samp{xmm7} for i386 @item @samp{xmm0} through @samp{xmm15} for amd64 -@item +@item @samp{mxcsr} @end itemize @@ -49964,8 +50461,15 @@ describe the upper 128 bits of @sc{ymm} registers: @samp{ymm0h} through @samp{ymm15h} for amd64 @end itemize -The @samp{org.gnu.gdb.i386.linux} feature is optional. It should -describe a single register, @samp{orig_eax}. +The @samp{org.gnu.gdb.i386.linux} feature is optional. If the feature +is present, then it should describe the 32 bit register, @samp{orig_eax}. + +Additionally, the @samp{org.gnu.gdb.i386.linux} feature can optionally +contain three 128 bit registers called @samp{i386_tls_gdt_0}, +@samp{i386_tls_gdt_1}, and @samp{i386_tls_gdt_2}. Each of these +registers contains one 16 byte @samp{struct user_desc} (see @kbd{man +2 get_thread_area}) object which describes one of the three TLS +related GDT entries. The @samp{org.gnu.gdb.i386.segments} feature is optional. It should describe two system registers: @samp{fs_base} and @samp{gs_base}. @@ -50016,6 +50520,12 @@ The @samp{org.gnu.gdb.i386.pkeys} feature is optional. It should describe a single register, @samp{pkru}. It is a 32-bit register valid for i386 and amd64. +The @samp{org.gnu.gdb.i386.pl3_ssp} feature is optional. It should +describe the user mode register @samp{pl3_ssp} which has 64 bits on +amd64, 32 bits on amd64 with 32-bit pointer size (X32) and 32 bits on i386. +Following the restriction of the Linux kernel, only @value{GDBN} for amd64 +targets makes use of this feature for now. + @node LoongArch Features @subsection LoongArch Features @cindex target descriptions, LoongArch Features @@ -50077,7 +50587,7 @@ Linux kernel to control restartable syscalls. @item @samp{org.gnu.gdb.m68k.core} @itemx @samp{org.gnu.gdb.coldfire.core} @itemx @samp{org.gnu.gdb.fido.core} -One of those features must be always present. +One of those features must be always present. The feature that is present determines which flavor of m68k is used. The feature that is present should contain registers @samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp}, @@ -50381,7 +50891,7 @@ contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}. Users of @value{GDBN} often wish to obtain information about the state of the operating system running on the target---for example the list of processes, or the list of open files. This section describes the -mechanism that makes it possible. This mechanism is similar to the +mechanism that makes it possible. This mechanism is similar to the target features mechanism (@pxref{Target Descriptions}), but focuses on a different aspect of target. @@ -50535,17 +51045,13 @@ unless otherwise noted: @enumerate @item -The version number, currently 9. Versions 1, 2 and 3 are obsolete. -Version 4 uses a different hashing function from versions 5 and 6. -Version 6 includes symbols for inlined functions, whereas versions 4 -and 5 do not. Version 7 adds attributes to the CU indices in the -symbol table. Version 8 specifies that symbols from DWARF type units +The version number, currently 9. Versions 1 through 6 are obsolete. +Version 7 adds attributes to the CU indices in the symbol table. +Version 8 specifies that symbols from DWARF type units (@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the compilation unit (@samp{DW_TAG_comp_unit}) using the type. Version 9 adds the name and the language of the main function to the index. -@value{GDBN} will only read version 4, 5, or 6 indices -by specifying @code{set use-deprecated-index-sections on}. GDB has a workaround for potentially broken version 7 indices so it is currently not flagged as deprecated. @@ -50564,7 +51070,8 @@ The offset, from the start of the file, of the address area. The offset, from the start of the file, of the symbol table. @item -The offset, from the start of the file, of the shortcut table. +The offset, from the start of the file, of the shortcut table. This +field was introduced with index version 9. @item The offset, from the start of the file, of the constant pool. @@ -50657,6 +51164,8 @@ in the constant pool. This value must be ignored if the value for the language of main is zero. @end table +This data structure was introduced in index version 9. + @item The constant pool. This is simply a bunch of bytes. It is organized so that alignment is correct: CU vectors are stored first, followed by @@ -51089,9 +51598,10 @@ Note that targets that give their output via @value{GDBN}, as opposed to writing directly to @code{stdout}, will also be made silent. @item --args @var{prog} [@var{arglist}] -Change interpretation of command line so that arguments following this -option are passed as arguments to the inferior. As an example, take -the following command: +@itemx --no-escape-args @var{prog} [@var{arglist}] +Change interpretation of command line so that arguments following +either of these options are passed as arguments to the inferior. As +an example, take the following command: @smallexample gdb ./a.out -q @@ -51106,7 +51616,44 @@ gdb --args ./a.out -q @end smallexample @noindent -starts @value{GDBN} with the introductory message, and passes the option to the inferior. +starts @value{GDBN} with the introductory message, and passes the +option @code{-q} to the inferior. + +The difference between @option{--args} and @option{--no-escape-args} +is whether @value{GDBN} applies escapes to the arguments it sees: + +@smallexample +gdb --args ./a.out *.c +@end smallexample + +@noindent +in this case the @code{*.c} is expanded by the shell that invokes +@value{GDBN}, the list of matching files will be fixed in the inferior +argument list. If instead this is used: + +@smallexample +gdb --args ./a.out '*.c' +@end smallexample + +@noindent +then the shell that invokes @value{GDBN} will not expand @code{*.c}, +instead @value{GDBN} will escape the @code{*} character, so when a.out +is invoked it will be passed a literal @code{*.c}. If instead this is +used: + +@smallexample +gdb --no-escape-args ./a.out '*.c' +@end smallexample + +@noindent +now @value{GDBN} will not escape the @code{*} character. When the +inferior is invoked the @code{*.c} will be expanded, and the inferior +will be passed the list of files as present at the time the inferior +is invoked. + +This change of behaviour can be important if the list of matching +files could change between the time that @value{GDBN} is started, and +the time the inferior is started. @item --pid=@var{pid} Attach @value{GDBN} to an already running program, with the PID @var{pid}. @@ -51448,6 +51995,18 @@ additional connections are possible. However, if you start @code{gdbserver} with the @option{--once} option, it will stop listening for any further connection attempts after connecting to the first @value{GDBN} session. +@item --no-escape-args +By default, inferior arguments passed on the @command{gdbserver} +command line will have any special shell characters escaped by +@command{gdbserver}. This ensures that when @command{gdbserver} +invokes the inferior, the arguments passed to the inferior are +identical to the arguments passed to @command{gdbserver}. + +To disable this escaping, use @option{--no-escape-args}. With this +option special shell characters will not be escaped. When +@command{gdbserver} starts a new shell in order to invoke the +inferior, this new shell will expand any special shell characters. + @c --disable-packet is not documented for users. @c --disable-randomization and --no-disable-randomization are superseded by @@ -51510,6 +52069,12 @@ composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the process ID of the running program being analyzed by @command{gcore}. If not specified, @var{prefix} defaults to @var{core}. +@item -g @var{gdb} +Use @var{gdb} as the executable binary to invoke @value{GDBN} for +running the gcore command. This argument is optional, and defaults to +invoking the @value{GDBN} binary that is installed alongside +@command{gcore}. + @item -d @var{directory} Use @var{directory} as the data directory when invoking @value{GDBN} for running the gcore command. This argument is optional. diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index c6808ef..83ea3e0 100644 --- a/gdb/doc/guile.texi +++ b/gdb/doc/guile.texi @@ -5,7 +5,7 @@ @c Invariant Sections being ``Free Software'' and ``Free Software Needs @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' @c and with the Back-Cover Texts as in (a) below. -@c +@c @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify @c this GNU Manual. Buying copies from GNU Press supports the FSF in @c developing GNU and promoting software freedom.'' @@ -38,7 +38,7 @@ Guile support in @value{GDBN} follows the Python support in @value{GDBN} reasonably closely, so concepts there should carry over. However, some things are done differently where it makes sense. -@value{GDBN} requires Guile version 3.0, 2.2, or 2.0. +@value{GDBN} requires Guile version 3.0, 2.2. @cindex guile scripts directory Guile scripts used by @value{GDBN} should be installed in @@ -1772,6 +1772,16 @@ invoking it interactively. If this function throws an exception, it is turned into a @value{GDBN} @code{error} call. Otherwise, the return value is ignored. +For non-prefix commands, @var{invoke} is required. For prefix +commands @var{invoke} is optional. Only prefix commands that need to +handle unknown sub-commands should supply @var{invoke}. + +For prefix commands that don't supply @var{invoke}, if the prefix +command is used without a sub-command name then @value{GDBN} will +display the help text for every sub-command, unless the prefix command +is a @kbd{show} sub-command, in which case @value{GDBN} will list the +values of all sub-commands. + The argument @var{command-class} is one of the @samp{COMMAND_} constants defined below. This argument tells @value{GDBN} how to categorize the new command in the help system. The default is @code{COMMAND_NONE}. @@ -1826,7 +1836,7 @@ $1 = ("1" "2 \"3" "4 \"5" "6 '7") @deffn {Scheme Procedure} throw-user-error message . args Throw a @code{gdb:user-error} exception. -The argument @var{message} is the error message as a format string, like the +The argument @var{message} is the error message as a format string, like the @var{fmt} argument to the @code{format} Scheme function. @xref{Formatted Output,,, guile, GNU Guile Reference Manual}. The argument @var{args} is a list of the optional arguments of @var{message}. @@ -2098,8 +2108,10 @@ is the @code{<gdb:parameter>} object representing the parameter, and This function must return a string, and will be displayed to the user. @value{GDBN} will add a trailing newline. -The argument @var{doc} is the help text for the new parameter. -If there is no documentation string, a default value is used. +The argument @var{doc} is the help text for the new parameter. If +there is no documentation string, a default value is used. If the +documentation string is empty, then @value{GDBN} will print just the +@var{set-doc} and @var{show-doc} strings (see below). The argument @var{set-doc} is the help text for this parameter's @code{set} command. @@ -2425,7 +2437,7 @@ The previous frame's analyzer returns an invalid result. This frame is the outermost. @item FRAME_UNWIND_UNAVAILABLE -Cannot unwind further, because that would require knowing the +Cannot unwind further, because that would require knowing the values of registers or memory that have not been collected. @item FRAME_UNWIND_INNER_ID @@ -3899,6 +3911,9 @@ Return string to change terminal's color to this. If @var{is_foreground} is @code{#t}, then the returned sequence will change foreground color. Otherwise, the returned sequence will change background color. + +If styling is currently disabled (@pxref{Output Styling,,@kbd{set style +enabled}}), then this procedure will return an empty string. @end deffn When color is initialized, its color space must be specified. The diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index afbd62f..13ffde2 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -5,7 +5,7 @@ @c Invariant Sections being ``Free Software'' and ``Free Software Needs @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' @c and with the Back-Cover Texts as in (a) below. -@c +@c @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify @c this GNU Manual. Buying copies from GNU Press supports the FSF in @c developing GNU and promoting software freedom.'' @@ -76,7 +76,7 @@ If given an argument, the @code{python} command will evaluate the argument as a Python command. For example: @smallexample -(@value{GDBP}) python print 23 +(@value{GDBP}) python print(23) 23 @end smallexample @@ -88,7 +88,7 @@ containing @code{end}. For example: @smallexample (@value{GDBP}) python ->print 23 +>print(23) >end 23 @end smallexample @@ -226,6 +226,7 @@ optional arguments while skipping others. Example: using Python. * Lazy Strings In Python:: Python representation of lazy strings. * Colors In Python:: Python representation of colors. +* Styles In Python:: Python representation of styles. * Architectures In Python:: Python representation of architectures. * Registers In Python:: Python representation of registers. * Connections In Python:: Python representation of connections. @@ -233,6 +234,7 @@ optional arguments while skipping others. Example: * Disassembly In Python:: Instruction Disassembly In Python * Missing Debug Info In Python:: Handle missing debug info from Python. * Missing Objfiles In Python:: Handle objfiles from Python. +* Core Files In Python:: Python representation of core files. @end menu @node Basic Python @@ -451,7 +453,7 @@ will be @code{None} and 0 respectively. This is identical to historical compatibility. @end defun -@defun gdb.write (string @r{[}, stream@r{]}) +@defun gdb.write (string @r{[}, stream@r{]} @r{[}, style@r{]}) Print a string to @value{GDBN}'s paginated output stream. The optional @var{stream} determines the stream to print to. The default stream is @value{GDBN}'s standard output stream. Possible stream @@ -474,18 +476,25 @@ values are: @value{GDBN}'s log stream (@pxref{Logging Output}). @end table +The @var{style} should be a @code{gdb.Style} object (@pxref{Styles In +Python}), or @code{None} (the default). If @var{style} is @code{None} +then the current style for @var{stream} will be applied to @var{text}. +If @var{style} is a @code{gdb.Style} object, then this style is +applied to @var{text}, after which the default output style is +restored. + Writing to @code{sys.stdout} or @code{sys.stderr} will automatically call this function and will automatically direct the output to the relevant stream. @end defun -@defun gdb.flush (@r{[}, stream@r{]}) +@defun gdb.flush (@r{[}stream@r{]}) Flush the buffer of a @value{GDBN} paginated stream so that the contents are displayed immediately. @value{GDBN} will flush the contents of a stream automatically when it encounters a newline in the buffer. The optional @var{stream} determines the stream to flush. The default stream is @value{GDBN}'s standard output stream. Possible -stream values are: +stream values are: @table @code @findex STDOUT @@ -509,6 +518,17 @@ Flushing @code{sys.stdout} or @code{sys.stderr} will automatically call this function for the relevant stream. @end defun +@defun gdb.warning (text) +Print a warning message to @value{GDBN}'s standard output stream. The +warning message is the warning prefix (@pxref{warning-prefix}), the +string @w{@samp{warning: }}, and then @var{text}, which must be a +non-empty string. + +Due to the warning prefix, @var{text} should not begin with a capital +letter (except for proper nouns), and @var{text} should end with a +period. +@end defun + @defun gdb.target_charset () Return the name of the current target character set (@pxref{Character Sets}). This differs from @code{gdb.parameter('target-charset')} in @@ -557,7 +577,7 @@ If @var{prompt_hook} is callable, @value{GDBN} will call the method assigned to this operation before a prompt is displayed by @value{GDBN}. -The parameter @code{current_prompt} contains the current @value{GDBN} +The parameter @code{current_prompt} contains the current @value{GDBN} prompt. This method must return a Python string, or @code{None}. If a string is returned, the @value{GDBN} prompt will be set to that string. If @code{None} is returned, @value{GDBN} will continue to use @@ -736,7 +756,7 @@ depends on @code{set python print-stack} (@pxref{Python Commands}). Example: @smallexample -(@value{GDBP}) python print foo +(@value{GDBP}) python print(foo) Traceback (most recent call last): File "<string>", line 1, in <module> NameError: name 'foo' is not defined @@ -899,7 +919,26 @@ this attribute holds @code{None}. @cindex optimized out value in Python @defvar Value.is_optimized_out This read-only boolean attribute is true if the compiler optimized out -this value, thus it is not available for fetching from the inferior. +this value, or any part of this value, and thus it is not available +for fetching from the inferior. +@end defvar + +@cindex unavailable values in Python +@defvar Value.is_unavailable +This read-only boolean attribute is true if this value, or any part of +this value, is not available to @value{GDBN}. Where an optimized out +value has been removed from the program by the compiler, an +unavailable value does exist in the program, but @value{GDBN} is +unable to fetch it. + +Some reasons why this might occur include, but are not limited to: a +core file format that @value{GDBN} doesn't fully understand; during +live debugging if the debug API has no mechanism to access the +required state, e.g.@: the kernel gives an error when trying to read a +particular register set; or reading a value from @value{GDBN}'s +history, when only a partial value was stored, e.g.@: due to the +@kbd{max-value-size} setting (@pxref{set +max-value-size,,max-value-size}). @end defvar @defvar Value.type @@ -925,17 +964,17 @@ it will just return the static type of the value as in @kbd{ptype foo} @defvar Value.is_lazy The value of this read-only boolean attribute is @code{True} if this -@code{gdb.Value} has not yet been fetched from the inferior. -@value{GDBN} does not fetch values until necessary, for efficiency. +@code{gdb.Value} has not yet been fetched from the inferior. +@value{GDBN} does not fetch values until necessary, for efficiency. For example: @smallexample myval = gdb.parse_and_eval ('somevar') @end smallexample -The value of @code{somevar} is not fetched at this time. It will be +The value of @code{somevar} is not fetched at this time. It will be fetched when the value is needed, or when the @code{fetch_lazy} -method is invoked. +method is invoked. @end defvar @defvar Value.bytes @@ -1313,7 +1352,7 @@ and encoded until a null of appropriate width is found. @end defun @defun Value.fetch_lazy () -If the @code{gdb.Value} object is currently a lazy value +If the @code{gdb.Value} object is currently a lazy value (@code{gdb.Value.is_lazy} is @code{True}), then the value is fetched from the inferior. Any errors that occur in the process will produce a Python exception. @@ -1906,7 +1945,7 @@ settings. During a @code{print} or other operation, the values will reflect any flags that are temporarily in effect. @smallexample -(gdb) python print (gdb.print_options ()['max_elements']) +(gdb) python print(gdb.print_options ()['max_elements']) 200 @end smallexample @end defun @@ -3357,27 +3396,27 @@ defined as follows: class MyClass_geta(gdb.xmethod.XMethod): def __init__(self): gdb.xmethod.XMethod.__init__(self, 'geta') - + def get_worker(self, method_name): if method_name == 'geta': return MyClassWorker_geta() - - + + class MyClass_sum(gdb.xmethod.XMethod): def __init__(self): gdb.xmethod.XMethod.__init__(self, 'sum') - + def get_worker(self, method_name): if method_name == 'operator+': return MyClassWorker_plus() - - + + class MyClassMatcher(gdb.xmethod.XMethodMatcher): def __init__(self): gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher') # List of methods 'managed' by this matcher self.methods = [MyClass_geta(), MyClass_sum()] - + def match(self, class_type, method_name): if class_type.tag != 'MyClass': return None @@ -3387,7 +3426,7 @@ class MyClassMatcher(gdb.xmethod.XMethodMatcher): worker = method.get_worker(method_name) if worker: workers.append(worker) - + return workers @end smallexample @@ -3415,18 +3454,18 @@ class MyClassWorker_geta(gdb.xmethod.XMethodWorker): def get_result_type(self, obj): return gdb.lookup_type('int') - + def __call__(self, obj): return obj['a_'] - - + + class MyClassWorker_plus(gdb.xmethod.XMethodWorker): def get_arg_types(self): return gdb.lookup_type('MyClass') def get_result_type(self, obj): return gdb.lookup_type('int') - + def __call__(self, obj, other): return obj['a_'] + other['a_'] @end smallexample @@ -3469,12 +3508,12 @@ class MyTemplate public: MyTemplate () : dsize_(10), data_ (new T [10]) @{ @} ~MyTemplate () @{ delete [] data_; @} - + int footprint (void) @{ return sizeof (T) * dsize_ + sizeof (MyTemplate<T>); @} - + private: int dsize_; T *data_; @@ -3500,12 +3539,12 @@ class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker): return (self.class_type.sizeof + obj['dsize_'] * self.class_type.template_argument(0).sizeof) - - + + class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher): def __init__(self): gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher') - + def match(self, class_type, method_name): if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>', class_type.tag) and @@ -3596,6 +3635,15 @@ necessary quoting for the shell; when a sequence is assigned, the quoting is applied by @value{GDBN}. @end defvar +@defvar Inferior.corefile +If a core file has been loaded into this inferior (@pxref{core-file +command}), then this contains a @code{gdb.Corefile} object that +represents the loaded core file (@pxref{Core Files In Python}). + +If no core file has been loaded into this inferior, then this +attribute contains @code{None}. +@end defvar + A @code{gdb.Inferior} object has the following methods: @defun Inferior.is_valid () @@ -3797,7 +3845,7 @@ Emits @code{events.ExitedEvent}, which indicates that the inferior has exited. @code{events.ExitedEvent} has two attributes: @defvar ExitedEvent.exit_code -An integer representing the exit code, if available, which the inferior +An integer representing the exit code, if available, which the inferior has returned. (The exit code could be unavailable if, for example, @value{GDBN} detaches from the inferior.) If the exit code is unavailable, the attribute does not exist. @@ -3852,7 +3900,7 @@ Also emits @code{gdb.BreakpointEvent}, which extends been hit, and has the following attributes: @defvar BreakpointEvent.breakpoints -A sequence containing references to all the breakpoints (type +A sequence containing references to all the breakpoints (type @code{gdb.Breakpoint}) that were hit. @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object. @end defvar @@ -4525,6 +4573,7 @@ You can implement new @value{GDBN} CLI commands in Python. A CLI command is implemented using an instance of the @code{gdb.Command} class, most commonly using a subclass. +@anchor{Command.__init__} @defun Command.__init__ (name, command_class @r{[}, completer_class @r{[}, prefix@r{]]}) The object initializer for @code{Command} registers the new command with @value{GDBN}. This initializer is normally invoked from the @@ -4558,6 +4607,7 @@ documentation string is provided, the default value @samp{This command is not documented.} is used. @end defun +@anchor{Command.dont_repeat} @cindex don't repeat Python command @defun Command.dont_repeat () By default, a @value{GDBN} command is repeated when the user enters a @@ -4568,6 +4618,7 @@ exception). This is similar to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}. @end defun +@anchor{Command.invoke} @defun Command.invoke (argument, from_tty) This method is called by @value{GDBN} when this command is invoked. @@ -4581,6 +4632,17 @@ that the command came from elsewhere. If this method throws an exception, it is turned into a @value{GDBN} @code{error} call. Otherwise, the return value is ignored. +For non-prefix commands (@pxref{Command.__init__}), the @code{invoke} +method is required. For prefix commands the @code{invoke} method is +optional. Only prefix commands that need to handle unknown +sub-commands should implement the @code{invoke} method. + +For prefix commands that don't implement @code{invoke}, if the prefix +command is used without a sub-command name then @value{GDBN} will +display the help text for every sub-command, unless the prefix command +is a @kbd{show} sub-command, in which case @value{GDBN} will list the +values of all sub-commands. + @findex gdb.string_to_argv To break @var{argument} up into an argv-like string use @code{gdb.string_to_argv}. This function behaves identically to @@ -4590,7 +4652,7 @@ Arguments are separated by spaces and may be quoted. Example: @smallexample -print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") +print(gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")) ['1', '2 "3', '4 "5', "6 '7"] @end smallexample @@ -5079,7 +5141,9 @@ string from the parameter's class, if there is one. If there is no documentation string, a default value is used. The documentation string is included in the output of the parameters @code{help set} and @code{help show} commands, and should be written taking this into -account. +account. If the documentation string for the parameter's class is the +empty string then @value{GDBN} will only use @code{Parameter.set_doc} +or @code{Parameter.show_doc} (see below) in the @kbd{help} output. @end defun @defvar Parameter.set_doc @@ -5258,6 +5322,211 @@ constants provided when the parameter is created. The value is @code{gdb.Color} instance. @end table +When creating multiple new parameters using @code{gdb.Parameter}, it +is often desirable to create a prefix command that can be used to +group related parameters together, for example, if you wished to add +the parameters @kbd{plugin-name feature-1} and @kbd{plugin-name +feature-2}, then the @kbd{plugin-name} would need to be a prefix +command (@pxref{CLI Commands In Python}). + +@anchor{gdb.ParameterPrefix} +However, when creating parameters, you will almost always need to +create two prefix commands, one as a @kbd{set} sub-command, and one as +a @kbd{show} sub-command. @value{GDBN} provides the +@code{gdb.ParameterPrefix} helper class to make creation of these two +prefixes easier. + +@defun ParameterPrefix.__init__ (name, command_class, doc = @code{None}) +The object initializer for @code{ParameterPrefix} registers two new +@code{gdb.Command} prefixes, one as a @kbd{set} sub-command, and the +other as a @kbd{show} sub-command. + +@var{name}, a string, is the name of the new prefix, without either +@kbd{set} or @kbd{show}, similar to the @var{name} passed to +@code{gdb.Parameter} (@pxref{Parameters In Python}). For example, to +create the prefixes @kbd{set plugin-name} and @kbd{show plugin-name}, +you would pass the string @kbd{plugin-name}. + +@var{command_class} should be one of the @samp{COMMAND_} constants +(@pxref{CLI Commands In Python}). This argument tells @value{GDBN} how to +categorize the new parameter prefixes in the help system. + +There are a number of ways in which the help text for the two new +prefix commands can be provided. If the @var{doc} parameter is not +@code{None}, then this will be used as the documentation string for +both prefix commands. + +If @var{doc} is @code{None}, but @code{gdb.ParameterPrefix} has been +sub-classed, then the prefix command documentation will be taken from +sub-classes documentation string (i.e., the @code{__doc__} attribute). + +If @var{doc} is @code{None}, and there is no @code{__doc__} string, +then the default value @samp{This command is not documented.} is used. + +When writing the help text, keep in mind that the same text is used +for both the @kbd{set} and @kbd{show} prefix commands. +@end defun + +@defun ParameterPrefix.invoke_set (argument, from_tty) +If a sub-class defines this method, then @value{GDBN} will call this +when the prefix command is used with an unknown sub-command. The +@var{argument} and @var{from_tty} parameters are the same as for +@code{gdb.Command.invoke} (@pxref{Command.invoke}). + +If this method throws an exception, it is turned into a @value{GDBN} +@code{error} call. Otherwise, the return value is ignored. + +It is not required that a @code{ParameterPrefix} sub-class override +this method. Usually, a parameter prefix only exists as a means to +group related parameters together. @value{GDBN} handles this use case +automatically with no need to implement @code{invoke_set}. +@end defun + +@defun ParameterPrefix.invoke_show (argument, from_tty) +This is like the @code{invoke_set} method, but for the @kbd{show} +prefix command. As with @code{invoke_set}, implementation of this +method is optional, and usually not required. +@end defun + +@cindex don't repeat Python command +@defun ParameterPrefix.dont_repeat () +Like @code{Command.dont_repeat} (@pxref{Command.dont_repeat}), this +can be called from @code{ParameterPrefix.invoke_set} or +@code{ParameterPrefix.invoke_show} to prevent the prefix commands from +being repeated. +@end defun + +Here is a small example that uses @code{gdb.ParameterPrefix} along +with @code{gdb.Parameter} to create two new parameters +@kbd{plugin-name feature-1} and @kbd{plugin-name feature-2}. As +neither @code{invoke_set} or @code{invoke_show} is needed, this +example does not sub-class @code{gdb.ParameterPrefix}: + +@smallexample +class ExampleParam(gdb.Parameter): + def __init__ (self, name): + super ().__init__ (name, gdb.COMMAND_DATA, gdb.PARAM_BOOLEAN) + self.value = True + +gdb.ParameterPrefix("plugin-name", gdb.COMMAND_NONE, + """An example parameter prefix. + + This groups together some parameters.""") +ExampleParam("plugin-name feature-1") +ExampleParam("plugin-name feature-2") +@end smallexample + +@anchor{Creating Style Parameters} +The helper class @code{gdb.StyleParameterSet} exists to make it easier +to create new styles. @value{GDBN} places style settings under +@samp{show style @dots{}} and @samp{set style @dots{}}, an example of a style +is @samp{filename}. Each style is really a prefix command (@pxref{CLI +Commands In Python}), with sub-commands @samp{foreground}, +@samp{background}, and optionally, @samp{intensity}. + +It is simple enough to create a new style using two @code{gdb.Command} +objects for the prefix commands (one for @samp{set}, and one for +@samp{show}), and three @code{gdb.Parameter} objects, one each for the +@samp{foreground}, @samp{background}, and @samp{intensity}. You would +also want to take care to craft the help text so that the new style +behaves the same as the existing styles. + +Or, you can use the @code{gdb.StyleParameterSet} class, which takes +care of all this, as the following example shows: + +@smallexample +@group +(@value{GDBP}) python s = gdb.StyleParameterSet("my-style") +(@value{GDBP}) show style my-style +style my-style background: The "my-style" style background color is: none +style my-style foreground: The "my-style" style foreground color is: none +style my-style intensity: The "my-style" style display intensity is: normal +(@value{GDBP}) +@end group +@end smallexample + +You might also want to group a number of styles within a new prefix, +similar to how @value{GDBN} groups disassembler related styles within +the @samp{style disassembler} prefix. This can be done using +@code{gdb.ParameterPrefix} (@pxref{gdb.ParameterPrefix}), as in this +example: + +@smallexample +@group +(@value{GDBP}) python gdb.ParameterPrefix("style group", gdb.COMMAND_NONE) +(@value{GDBP}) python s_a = gdb.StyleParameterSet("group aa") +(@value{GDBP}) python s_b = gdb.StyleParameterSet("group bb") +(@value{GDBP}) show style group +style group aa background: The "group aa" style background color is: none +style group aa foreground: The "group aa" style foreground color is: none +style group aa intensity: The "group aa" style display intensity is: normal +style group bb background: The "group bb" style background color is: none +style group bb foreground: The "group bb" style foreground color is: none +style group bb intensity: The "group bb" style display intensity is: normal +(@value{GDBP}) +@end group +@end smallexample + +The @code{gdb.StyleParameterSet} class has the following methods and +attributes: + +@defun StyleParameterSet.__init__(name, @w{add_intensity=@code{True}}, @w{doc=@code{None}}) +Create a new style group based on @var{name}, which is a string. For +example if @var{name} is @samp{my-style}, then @value{GDBN} will +create the prefix commands @samp{set style my-style} and @samp{show +style my-style}. Within these prefix commands will be +@samp{foreground}, @samp{background}, and @samp{intensity} parameters +with the appropriate types. + +It is also possible for @var{name} to consist of multiple words, so +long as each prefix command (except the last one) already exists. For +example, it is valid to use a @var{name} value of @samp{disassembler +my-style}, as the @samp{disassembler} prefix command already exists. +@value{GDBN} would then create @samp{set style disassembler my-style} +and @samp{show style disassembler my-style}, and within the +@samp{my-style} prefixes will be the @samp{foreground}, +@samp{background}, and @samp{intensity} parameters with the +appropriate types. + +Every style requires a @samp{foreground} and @samp{background}, but +not every style needs an @samp{intensity}. If @var{add_intensity} is +@code{True} (the default), then the @samp{intensity} parameter will be +created. If @var{add_intensity} is @code{False}, then the +@samp{intensity} parameter will not be created. + +If the @samp{intensity} parameter is not created, then the +@code{gdb.Style} (@pxref{Styles In Python}) created from this +@code{gdb.StyleParameterSet} will have @code{gdb.INTENSITY_NORMAL}. + +The @var{doc} should be a string which will be used as the help text +for the @var{name} prefix command. This text is used as the +@code{Command.__doc__} value for the @code{gdb.Command} object that is +the prefix command object (@pxref{CLI Commands In Python}). If +@var{doc} is @code{None} (the default) then a basic default help text +is used. +@end defun + +@defun StyleParameterSet.apply(string) +Equivalent to @code{StyleParameterSet.style.apply(string)}. Returns a +copy of @var{string} with escape sequences added to the start and end. +The escape sequence at the start applies this style, and the escape +sequence at the end restores the terminal default. + +If styling is disabled (i.e.@: @samp{set style enabled off}), then no +escape sequences are added and this method returns a copy of +@var{string}. +@end defun + +@defvar StyleParameterSet.style +This read/write attribute holds a @code{gdb.Style} object +(@pxref{Styles In Python}), that is a named style associated with this +style parameter group. +@end defvar + +@defvar StyleParameterSet.value +This is an alias for @code{StyleParameterSet.style}, see above. +@end defvar + @node Functions In Python @subsubsection Writing new convenience functions @@ -5712,7 +5981,7 @@ Two @code{gdb.Frame} objects can be compared for equality with the @code{==} operator, like: @smallexample -(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame () +(@value{GDBP}) python print(gdb.newest_frame() == gdb.selected_frame ()) True @end smallexample @@ -5808,7 +6077,7 @@ compatibility. This frame is the outermost. @item gdb.FRAME_UNWIND_UNAVAILABLE -Cannot unwind further, because that would require knowing the +Cannot unwind further, because that would require knowing the values of registers or memory that have not been collected. @item gdb.FRAME_UNWIND_INNER_ID @@ -6149,12 +6418,14 @@ up such variables, iterate over the variables of the function's There can be multiple global symbols with static linkage with the same name. This function will only return the first matching symbol that -it finds. Which symbol is found depends on where @value{GDBN} is +it finds. Which symbol is found depends on where the program is currently stopped, as @value{GDBN} will first search for matching -symbols in the current object file, and then search all other object -files. If the application is not yet running then @value{GDBN} will -search all object files in the order they appear in the debug -information. +symbols in the current compilation unit. If it finds no match, or if +there is no current compilation unit (perhaps because the program is +not running), then @code{gdb.lookup_static_symbol} will return an +unspecified matching symbol. To safely handle the case of multiple +static symbols with the same name, an application can use +@code{gdb.lookup_static_symbols}. @end defun @defun gdb.lookup_static_symbols (name @r{[}, domain@r{]}) @@ -6944,22 +7215,22 @@ is not writable. A finish breakpoint is a temporary breakpoint set at the return address of a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint} -extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled -and deleted when the execution will run out of the breakpoint scope (i.e.@: +extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled +and deleted when the execution will run out of the breakpoint scope (i.e.@: @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered). -Finish breakpoints are thread specific and must be create with the right -thread selected. - +Finish breakpoints are thread specific and must be create with the right +thread selected. + @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]}) Create a finish breakpoint at the return address of the @code{gdb.Frame} object @var{frame}. If @var{frame} is not provided, this defaults to the newest frame. The optional @var{internal} argument allows the breakpoint to -become invisible to the user. @xref{Breakpoints In Python}, for further +become invisible to the user. @xref{Breakpoints In Python}, for further details about this argument. @end defun @defun FinishBreakpoint.out_of_scope (self) -In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} +In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} @code{return} command, @dots{}), a function may not properly terminate, and thus never hit the finish breakpoint. When @value{GDBN} notices such a situation, the @code{out_of_scope} callback will be triggered. @@ -6972,17 +7243,17 @@ class MyFinishBreakpoint (gdb.FinishBreakpoint) def stop (self): print ("normal finish") return True - + def out_of_scope (): print ("abnormal finish") -@end smallexample +@end smallexample @end defun @defvar FinishBreakpoint.return_value -When @value{GDBN} is stopped at a finish breakpoint and the frame +When @value{GDBN} is stopped at a finish breakpoint and the frame used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this attribute will contain a @code{gdb.Value} object corresponding to the return -value of the function. The value will be @code{None} if the function return +value of the function. The value will be @code{None} if the function return type is @code{void} or if the return value was not computable. This attribute is not writable. @end defvar @@ -7101,6 +7372,9 @@ Returns string to change terminal's color to this. If @var{is_foreground} is @code{True}, then the returned sequence will change foreground color. Otherwise, the returned sequence will change background color. + +If styling is currently disabled (@pxref{Output Styling,,@kbd{set style +enabled}}), then this method will return an empty string. @end defun When color is initialized, its color space must be specified. The @@ -7139,6 +7413,146 @@ Direct 24-bit RGB colors. It is not possible to sub-class the @code{Color} class. +@node Styles In Python +@subsubsection Python representation of styles + +@cindex styles in python +@tindex gdb.Style + +A style object contains the foreground and background colors +(@pxref{Colors In Python}), along with an intensity, and can be used +to apply this styling to output produced from Python. + +@value{GDBN} has many styles builtin (@pxref{Output Styling}), and +style objects can be created that apply these builtin styles to Python +output. It is also possible to create new styles which can be used to +style Python output (@pxref{Creating Style Parameters}). + +The style class is called @code{gdb.Style}, and has the following +methods and attributes: + +@defun Style.__init__ (style_name) +Create a @code{gdb.Style} that represents a builtin named style. The +@var{style_name} must be a non-empty string that names a style that +exists as a setting in @value{GDBN} within @samp{set style @dots{}}. For +example, the string @samp{"filename"} can be used to create a +@code{gdb.Style} object representing the @samp{set style filename} +style. + +If @var{style_name} names an unknown style then a @code{RuntimeError} +exception is raised. +@end defun + +@defun Style.__init__ (foreground=@code{None}, background=@code{None}, intensity=gdb.INTENSITY_NORMAL) +Create a custom @code{gdb.Style}, manually specifying the three +individual components. All of the arguments are optional. By +default, if no arguments are given, then the default style will be +created, this will produce output with the default terminal foreground +and background colors, along with the normal level of intensity +(i.e.@: neither bold, nor dim). + +The @var{foreground} and @var{background} arguments should either be +@code{None}, in which case the terminal default colors are used, or a +@code{gdb.Color} object (@pxref{Colors In Python}). Any other object +type will result in a @code{TypeError} exception being raised. + +The @var{intensity} argument should be one of the intensity constants +defined below (@pxref{Style Intensities}). Passing a none integer +value results in a @code{TypeError} exception, and passing an invalid +constant results in a @code{ValueError} exception. +@end defun + +@defun Style.escape_sequence () +If styling is enabled (@pxref{Output Styling}, then this method +returns the string which is the terminal escape sequence necessary to +apply this @code{gdb.Style}. + +If styling is disabled then this method returns the empty string. + +If this is a named style, which for some reason can no longer be read, +then a @code{RuntimeError} exception is raised. +@end defun + +@defun Style.apply (string) +This method returns @var{string}, which must be a @code{str} object, +with an escape sequence at both the start, and at the end. The escape +sequence at the start applies this style, while the escape sequence at +the end applies the terminal's default style. + +The effect of this is that, printing the result of this method, will +print @var{string} with this style applied. Future output will be +printed with the terminal's default style. + +If styling is currently disabled (@pxref{Output Styling}), then +@code{Style.apply} just returns a copy of @var{string} with no escape +sequences added. + +If this is a named style, which for some reason can no longer be read, +then a @code{RuntimeError} exception is raised. +@end defun + +@defvar Style.foreground +This read/write attribute contains the @code{gdb.Color} object +representing this style's foreground color. Writing to this attribute +updates the style's foreground color. + +If the @code{gdb.Style} object was created using a named style (i.e.@: +using the single argument @var{style_name} @code{__init__} method), +then the underlying setting will be updated. + +For unnamed styles, only the @code{gdb.Style} object will change. +@end defvar + +@defvar Style.background +This read/write attribute contains the @code{gdb.Color} object +representing this style's background color. Writing to this attribute +updates the style's background color. + +If the @code{gdb.Style} object was created using a named style (i.e.@: +using the single argument @var{style_name} @code{__init__} method), +then the underlying setting will be updated. + +For unnamed styles, only the @code{gdb.Style} object will change. +@end defvar + +@defvar Style.intensity +This read/write attribute contains the intensity for this style, and +will be one of the constants defined below (@pxref{Style +Intensities}). Writing to this attribute updates the style's +intensity. + +It is also possible to write @code{None} to this attribute, this is +equivalent of writing @code{gdb.INTENSITY_NORMAL}. This attribute +will never read as @code{None}. + +If the @code{gdb.Style} object was created using a named style (i.e.@: +using the single argument @var{style_name} @code{__init__} method), +then the underlying setting will be updated. + +For unnamed styles, only the @code{gdb.Style} object will change. +@end defvar + +@anchor{Style Intensities} +The following constants are defined to represent the different style +intensities: + +@table @code +@findex INTENSITY_NORMAL +@findex gdb.INTENSITY_NORMAL +@item gdb.INTENSITY_NORMAL +This is the terminal's default intensity. + +@findex INTENSITY_BOLD +@findex gdb.INTENSITY_BOLD +@item gdb.INTENSITY_BOLD +This is for bold text. + +@findex INTENSITY_DIM +@findex gdb.INTENSITY_DIM +@item gdb.INTENSITY_DIM +This is for dim text. +@end table + @node Architectures In Python @subsubsection Python representation of architectures @cindex Python architectures @@ -8482,6 +8896,106 @@ handlers, all of the matching handlers are enabled. The @code{enabled} field of each matching handler is set to @code{True}. @end table +@node Core Files In Python +@subsubsection Core Files In Python +@cindex python, core files + +When a core file is loaded into an inferior (@pxref{Inferiors In +Python}) for examination (@pxref{core-file command}), information +about the core file is contained in a @code{gdb.Corefile} object. + +The @code{gdb.Corefile} for an inferior can be accessed using the +@code{Inferior.corefile} attribute. This will be @code{None} if +no core file is loaded. + +A @code{gdb.Corefile} object has the following attributes: + +@defvar Corefile.filename +This read only attribute contains a non-empty string, the file name of +the core file. Attempting to access this attribute on an invalid +@code{gdb.Corefile} object will raise a @code{RuntimeError} exception. +@end defvar + +A @code{gdb.Corefile} object has the following methods: + +@defun Corefile.is_valid () +Returns @code{True} if the @code{gdb.Corefile} object is valid, +@code{False} if not. A @code{gdb.Corefile} object will become invalid +when the core file is unloaded from the inferior using the +@kbd{core-file} command (@pxref{core-file command}), or if the +inferior in which the core file is loaded is deleted. All other +@code{gdb.Corefile} methods and attributes will throw an exception if +it is invalid at the time the method is called, or the attribute +accessed. +@end defun + +@defun Corefile.mapped_files () +Return a list of @code{gdb.CorefileMappedFile} (see below) objects +representing files that were mapped into the process when the core +file was created. This information is read from the @samp{NT_FILE} +core file note on Linux. Not every target supports accessing this +information, for targets without support, an empty list will be +returned. +@end defun + +One may add arbitrary attributes to @code{gdb.Corefile} objects in the +usual Python way. This is useful if, for example, one needs to do +some extra record keeping associated with the corefile. +@xref{choosing attribute names}, for guidance on selecting a suitable +name for new attributes. + +The @code{Corefile.mapped_files ()} method returns a list of +@code{gdb.CorefileMappedFile} objects. Each of these objects +represents a file that was fully, or partially, mapped into the +processes address space when the core file was created. + +A @code{gdb.CorefileMappedFile} object has the following attributes: + +@defvar CorefileMappedFile.filename +This read only attribute contains a non-empty string, the file name of +the mapped file. +@end defvar + +@defvar CorefileMappedFile.build_id +This read only attribute contains a non-empty string or @code{None}. +This is the build-id of the mapped file extracted from the core file, +or @code{None} if there was no build-id, or @value{GDBN} was unable to +extract the build-id. +@end defvar + +@defvar CorefileMappedFile.is_main_executable +This read only attribute is @code{True} if @value{GDBN} believes this +mapping represents the main executable for which this core file was +created. This will be @code{False} for all other mappings. +@end defvar + +@defvar CorefileMappedFile.regions +This read only attribute contains a list of +@code{gdb.CorefileMappedFileRegion} objects. Each of these objects +describes a region of the file that was mapped into the process when +the core file was created, further details are given below. +@end defvar + +The @code{gdb.CorefileMappedFileRegion} object describes which part of +a file that was mapped into a process when the core file was created. + +A @code{gdb.CorefileMappedFile} object has the following attributes: + +@defvar CorefileMappedFileRegion.start +This read only attribute contains the start address of this mapping +within the inferior. +@end defvar + +@defvar CorefileMappedFileRegion.end +This read only attribute contains end address of this mapping within +the inferior. +@end defvar + +@defvar CorefileMappedFileRegion.file_offset +This read only attribute contains the offset within the mapped file +for this mapping. +@end defvar + @node Python Auto-loading @subsection Python Auto-loading @cindex Python auto-loading @@ -8617,7 +9131,7 @@ Then in gdb: (gdb) start (gdb) python import gdb.types (gdb) python foo_ref = gdb.parse_and_eval("foo_ref") -(gdb) python print gdb.types.get_basic_type(foo_ref.type) +(gdb) python print(gdb.types.get_basic_type(foo_ref.type)) int @end smallexample @@ -8650,9 +9164,9 @@ Then in @value{GDBN}: @smallexample (@value{GDBP}) python import gdb.types (@value{GDBP}) python struct_a = gdb.lookup_type("struct A") -(@value{GDBP}) python print struct_a.keys () +(@value{GDBP}) python print(struct_a.keys ()) @{['a', '']@} -(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)] +(@value{GDBP}) python print([k for k,v in gdb.types.deep_items(struct_a)]) @{['a', 'b0', 'b1']@} @end smallexample diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo deleted file mode 100644 index eac342a..0000000 --- a/gdb/doc/stabs.texinfo +++ /dev/null @@ -1,4130 +0,0 @@ -\input texinfo -@setfilename stabs.info -@setchapternewpage odd -@settitle STABS - -@c man begin INCLUDE -@include gdb-cfg.texi -@c man end - -@c @finalout - -@c This is a dir.info fragment to support semi-automated addition of -@c manuals to an info tree. -@dircategory Software development -@direntry -* Stabs: (stabs). The "stabs" debugging information format. -@end direntry - -@copying -Copyright @copyright{} 1992--2025 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, -and David MacKenzie. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end copying - -@ifnottex -This document describes the stabs debugging symbol tables. - -@insertcopying -@end ifnottex - -@titlepage -@title The ``stabs'' debug format -@author Julia Menapace, Jim Kingdon, David MacKenzie -@author Cygnus Support -@page -@tex -\def\$#1${{#1}} % Kludge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision$} % For use in headers, footers too -{\parskip=0pt -\hfill Cygnus Support\par -\hfill \manvers\par -\hfill \TeX{}info \texinfoversion\par -} -@end tex - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@node Top -@top The "stabs" representation of debugging information - -This document describes the stabs debugging format. - -@menu -* Overview:: Overview of stabs -* Program Structure:: Encoding of the structure of the program -* Constants:: Constants -* Variables:: -* Types:: Type definitions -* Macro define and undefine:: Representation of #define and #undef -* Symbol Tables:: Symbol information in symbol tables -* Cplusplus:: Stabs specific to C++ -* Stab Types:: Symbol types in a.out files -* Symbol Descriptors:: Table of symbol descriptors -* Type Descriptors:: Table of type descriptors -* Expanded Reference:: Reference information by stab type -* Questions:: Questions and anomalies -* Stab Sections:: In some object file formats, stabs are - in sections. -* GNU Free Documentation License:: The license for this documentation -* Symbol Types Index:: Index of symbolic stab symbol type names. -@end menu -@end ifnottex - -@contents - -@node Overview -@chapter Overview of Stabs - -@dfn{Stabs} refers to a format for information that describes a program -to a debugger. This format was apparently invented by -Peter Kessler at -the University of California at Berkeley, for the @code{pdx} Pascal -debugger; the format has spread widely since then. - -This document is one of the few published sources of documentation on -stabs. It is believed to be comprehensive for stabs used by C. The -lists of symbol descriptors (@pxref{Symbol Descriptors}) and type -descriptors (@pxref{Type Descriptors}) are believed to be completely -comprehensive. Stabs for COBOL-specific features and for variant -records (used by Pascal and Modula-2) are poorly documented here. - -@c FIXME: Need to document all OS9000 stuff in GDB; see all references -@c to os9k_stabs in stabsread.c. - -Other sources of information on stabs are @cite{Dbx and Dbxtool -Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files -Reference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in -the a.out section, page 2-31. This document is believed to incorporate -the information from those two sources except where it explicitly directs -you to them for more information. - -@menu -* Flow:: Overview of debugging information flow -* Stabs Format:: Overview of stab format -* String Field:: The string field -* C Example:: A simple example in C source -* Assembly Code:: The simple example at the assembly level -@end menu - -@node Flow -@section Overview of Debugging Information Flow - -The GNU C compiler compiles C source in a @file{.c} file into assembly -language in a @file{.s} file, which the assembler translates into -a @file{.o} file, which the linker combines with other @file{.o} files and -libraries to produce an executable file. - -With the @samp{-g} option, GCC puts in the @file{.s} file additional -debugging information, which is slightly transformed by the assembler -and linker, and carried through into the final executable. This -debugging information describes features of the source file like line -numbers, the types and scopes of variables, and function names, -parameters, and scopes. - -For some object file formats, the debugging information is encapsulated -in assembler directives known collectively as @dfn{stab} (symbol table) -directives, which are interspersed with the generated code. Stabs are -the native format for debugging information in the a.out and XCOFF -object file formats. The GNU tools can also emit stabs in the COFF and -ECOFF object file formats. - -The assembler adds the information from stabs to the symbol information -it places by default in the symbol table and the string table of the -@file{.o} file it is building. The linker consolidates the @file{.o} -files into one executable file, with one symbol table and one string -table. Debuggers use the symbol and string tables in the executable as -a source of debugging information about the program. - -@node Stabs Format -@section Overview of Stab Format - -There are three overall formats for stab assembler directives, -differentiated by the first word of the stab. The name of the directive -describes which combination of four possible data fields follows. It is -either @code{.stabs} (string), @code{.stabn} (number), or @code{.stabd} -(dot). IBM's XCOFF assembler uses @code{.stabx} (and some other -directives such as @code{.file} and @code{.bi}) instead of -@code{.stabs}, @code{.stabn} or @code{.stabd}. - -The overall format of each class of stab is: - -@example -.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value} -.stabn @var{type},@var{other},@var{desc},@var{value} -.stabd @var{type},@var{other},@var{desc} -.stabx "@var{string}",@var{value},@var{type},@var{sdb-type} -@end example - -@c what is the correct term for "current file location"? My AIX -@c assembler manual calls it "the value of the current location counter". -For @code{.stabn} and @code{.stabd}, there is no @var{string} (the -@code{n_strx} field is zero; see @ref{Symbol Tables}). For -@code{.stabd}, the @var{value} field is implicit and has the value of -the current file location. For @code{.stabx}, the @var{sdb-type} field -is unused for stabs and can always be set to zero. The @var{other} -field is almost always unused and can be set to zero. - -The number in the @var{type} field gives some basic information about -which type of stab this is (or whether it @emph{is} a stab, as opposed -to an ordinary symbol). Each valid type number defines a different stab -type; further, the stab type defines the exact interpretation of, and -possible values for, any remaining @var{string}, @var{desc}, or -@var{value} fields present in the stab. @xref{Stab Types}, for a list -in numeric order of the valid @var{type} field values for stab directives. - -@node String Field -@section The String Field - -For most stabs the string field holds the meat of the -debugging information. The flexible nature of this field -is what makes stabs extensible. For some stab types the string field -contains only a name. For other stab types the contents can be a great -deal more complex. - -The overall format of the string field for most stab types is: - -@example -"@var{name}:@var{symbol-descriptor} @var{type-information}" -@end example - -@var{name} is the name of the symbol represented by the stab; it can -contain a pair of colons (@pxref{Nested Symbols}). @var{name} can be -omitted, which means the stab represents an unnamed object. For -example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does -not give the type a name. Omitting the @var{name} field is supported by -AIX dbx and GDB after about version 4.8, but not other debuggers. GCC -sometimes uses a single space as the name instead of omitting the name -altogether; apparently that is supported by most debuggers. - -The @var{symbol-descriptor} following the @samp{:} is an alphabetic -character that tells more specifically what kind of symbol the stab -represents. If the @var{symbol-descriptor} is omitted, but type -information follows, then the stab represents a local variable. For a -list of symbol descriptors, see @ref{Symbol Descriptors}. The @samp{c} -symbol descriptor is an exception in that it is not followed by type -information. @xref{Constants}. - -@var{type-information} is either a @var{type-number}, or -@samp{@var{type-number}=}. A @var{type-number} alone is a type -reference, referring directly to a type that has already been defined. - -The @samp{@var{type-number}=} form is a type definition, where the -number represents a new type which is about to be defined. The type -definition may refer to other types by number, and those type numbers -may be followed by @samp{=} and nested definitions. Also, the Lucid -compiler will repeat @samp{@var{type-number}=} more than once if it -wants to define several type numbers at once. - -In a type definition, if the character that follows the equals sign is -non-numeric then it is a @var{type-descriptor}, and tells what kind of -type is about to be defined. Any other values following the -@var{type-descriptor} vary, depending on the @var{type-descriptor}. -@xref{Type Descriptors}, for a list of @var{type-descriptor} values. If -a number follows the @samp{=} then the number is a @var{type-reference}. -For a full description of types, @ref{Types}. - -A @var{type-number} is often a single number. The GNU and Sun tools -additionally permit a @var{type-number} to be a pair -(@var{file-number},@var{filetype-number}) (the parentheses appear in the -string, and serve to distinguish the two cases). The @var{file-number} -is 0 for the base source file, 1 for the first included file, 2 for the -next, and so on. The @var{filetype-number} is a number starting with -1 which is incremented for each new type defined in the file. -(Separating the file number and the type number permits the -@code{N_BINCL} optimization to succeed more often; see @ref{Include -Files}). - -There is an AIX extension for type attributes. Following the @samp{=} -are any number of type attributes. Each one starts with @samp{@@} and -ends with @samp{;}. Debuggers, including AIX's dbx and GDB 4.10, skip -any type attributes they do not recognize. GDB 4.9 and other versions -of dbx may not do this. Because of a conflict with C@t{++} -(@pxref{Cplusplus}), new attributes should not be defined which begin -with a digit, @samp{(}, or @samp{-}; GDB may be unable to distinguish -those from the C@t{++} type descriptor @samp{@@}. The attributes are: - -@table @code -@item a@var{boundary} -@var{boundary} is an integer specifying the alignment. I assume it -applies to all variables of this type. - -@item p@var{integer} -Pointer class (for checking). Not sure what this means, or how -@var{integer} is interpreted. - -@item P -Indicate this is a packed type, meaning that structure fields or array -elements are placed more closely in memory, to save memory at the -expense of speed. - -@item s@var{size} -Size in bits of a variable of this type. This is fully supported by GDB -4.11 and later. - -@item S -Indicate that this type is a string instead of an array of characters, -or a bitstring instead of a set. It doesn't change the layout of the -data being represented, but does enable the debugger to know which type -it is. - -@item V -Indicate that this type is a vector instead of an array. The only -major difference between vectors and arrays is that vectors are -passed by value instead of by reference (vector coprocessor extension). - -@end table - -All of this can make the string field quite long. All versions of GDB, -and some versions of dbx, can handle arbitrarily long strings. But many -versions of dbx (or assemblers or linkers, I'm not sure which) -cretinously limit the strings to about 80 characters, so compilers which -must work with such systems need to split the @code{.stabs} directive -into several @code{.stabs} directives. Each stab duplicates every field -except the string field. The string field of every stab except the last -is marked as continued with a backslash at the end (in the assembly code -this may be written as a double backslash, depending on the assembler). -Removing the backslashes and concatenating the string fields of each -stab produces the original, long string. Just to be incompatible (or so -they don't have to worry about what the assembler does with -backslashes), AIX can use @samp{?} instead of backslash. - -@node C Example -@section A Simple Example in C Source - -To get the flavor of how stabs describe source information for a C -program, let's look at the simple program: - -@example -main() -@{ - printf("Hello world"); -@} -@end example - -When compiled with @samp{-g}, the program above yields the following -@file{.s} file. Line numbers have been added to make it easier to refer -to parts of the @file{.s} file in the description of the stabs that -follows. - -@node Assembly Code -@section The Simple Example at the Assembly Level - -This simple ``hello world'' example demonstrates several of the stab -types used to describe C language source files. - -@example -1 gcc2_compiled.: -2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 -3 .stabs "hello.c",100,0,0,Ltext0 -4 .text -5 Ltext0: -6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 -7 .stabs "char:t2=r2;0;127;",128,0,0,0 -8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 -9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 -10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 -11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 -12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 -13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 -14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 -15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 -16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 -17 .stabs "float:t12=r1;4;0;",128,0,0,0 -18 .stabs "double:t13=r1;8;0;",128,0,0,0 -19 .stabs "long double:t14=r1;8;0;",128,0,0,0 -20 .stabs "void:t15=15",128,0,0,0 -21 .align 4 -22 LC0: -23 .ascii "Hello, world!\12\0" -24 .align 4 -25 .global _main -26 .proc 1 -27 _main: -28 .stabn 68,0,4,LM1 -29 LM1: -30 !#PROLOGUE# 0 -31 save %sp,-136,%sp -32 !#PROLOGUE# 1 -33 call ___main,0 -34 nop -35 .stabn 68,0,5,LM2 -36 LM2: -37 LBB2: -38 sethi %hi(LC0),%o1 -39 or %o1,%lo(LC0),%o0 -40 call _printf,0 -41 nop -42 .stabn 68,0,6,LM3 -43 LM3: -44 LBE2: -45 .stabn 68,0,6,LM4 -46 LM4: -47 L1: -48 ret -49 restore -50 .stabs "main:F1",36,0,0,_main -51 .stabn 192,0,0,LBB2 -52 .stabn 224,0,0,LBE2 -@end example - -@node Program Structure -@chapter Encoding the Structure of the Program - -The elements of the program structure that stabs encode include the name -of the main function, the names of the source and include files, the -line numbers, procedure names and types, and the beginnings and ends of -blocks of code. - -@menu -* Main Program:: Indicate what the main program is -* Source Files:: The path and name of the source file -* Include Files:: Names of include files -* Line Numbers:: -* Procedures:: -* Nested Procedures:: -* Block Structure:: -* Alternate Entry Points:: Entering procedures except at the beginning. -@end menu - -@node Main Program -@section Main Program - -@findex N_MAIN -Most languages allow the main program to have any name. The -@code{N_MAIN} stab type tells the debugger the name that is used in this -program. Only the string field is significant; it is the name of -a function which is the main program. Most C compilers do not use this -stab (they expect the debugger to assume that the name is @code{main}), -but some C compilers emit an @code{N_MAIN} stab for the @code{main} -function. I'm not sure how XCOFF handles this. - -@node Source Files -@section Paths and Names of the Source Files - -@findex N_SO -Before any other stabs occur, there must be a stab specifying the source -file. This information is contained in a symbol of stab type -@code{N_SO}; the string field contains the name of the file. The -value of the symbol is the start address of the portion of the -text section corresponding to that file. - -Some compilers use the desc field to indicate the language of the -source file. Sun's compilers started this usage, and the first -constants are derived from their documentation. Languages added -by gcc/gdb start at 0x32 to avoid conflict with languages Sun may -add in the future. A desc field with a value 0 indicates that no -language has been specified via this mechanism. - -@table @asis -@item @code{N_SO_AS} (0x1) -Assembly language -@item @code{N_SO_C} (0x2) -K&R traditional C -@item @code{N_SO_ANSI_C} (0x3) -ANSI C -@item @code{N_SO_CC} (0x4) -C++ -@item @code{N_SO_FORTRAN} (0x5) -Fortran -@item @code{N_SO_PASCAL} (0x6) -Pascal -@item @code{N_SO_FORTRAN90} (0x7) -Fortran90 -@item @code{N_SO_OBJC} (0x32) -Objective-C -@item @code{N_SO_OBJCPLUS} (0x33) -Objective-C++ -@end table - -Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also -include the directory in which the source was compiled, in a second -@code{N_SO} symbol preceding the one containing the file name. This -symbol can be distinguished by the fact that it ends in a slash. Code -from the @code{cfront} C@t{++} compiler can have additional @code{N_SO} symbols for -nonexistent source files after the @code{N_SO} for the real source file; -these are believed to contain no useful information. - -For example: - -@example -.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # @r{100 is N_SO} -.stabs "hello.c",100,0,0,Ltext0 - .text -Ltext0: -@end example - -@findex C_FILE -Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler -directive which assembles to a @code{C_FILE} symbol; explaining this in -detail is outside the scope of this document. - -@c FIXME: Exactly when should the empty N_SO be used? Why? -If it is useful to indicate the end of a source file, this is done with -an @code{N_SO} symbol with an empty string for the name. The value is -the address of the end of the text section for the file. For some -systems, there is no indication of the end of a source file, and you -just need to figure it ended when you see an @code{N_SO} for a different -source file, or a symbol ending in @code{.o} (which at least some -linkers insert to mark the start of a new @code{.o} file). - -@node Include Files -@section Names of Include Files - -There are several schemes for dealing with include files: the -traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the -XCOFF @code{C_BINCL} approach (which despite the similar name has little in -common with @code{N_BINCL}). - -@findex N_SOL -An @code{N_SOL} symbol specifies which include file subsequent symbols -refer to. The string field is the name of the file and the value is the -text address corresponding to the end of the previous include file and -the start of this one. To specify the main source file again, use an -@code{N_SOL} symbol with the name of the main source file. - -@findex N_BINCL -@findex N_EINCL -@findex N_EXCL -The @code{N_BINCL} approach works as follows. An @code{N_BINCL} symbol -specifies the start of an include file. In an object file, only the -string is significant; the linker puts data into some of the other -fields. The end of the include file is marked by an @code{N_EINCL} -symbol (which has no string field). In an object file, there is no -significant data in the @code{N_EINCL} symbol. @code{N_BINCL} and -@code{N_EINCL} can be nested. - -If the linker detects that two source files have identical stabs between -an @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case -for a header file), then it only puts out the stabs once. Each -additional occurrence is replaced by an @code{N_EXCL} symbol. I believe -the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only -ones which supports this feature. - -A linker which supports this feature will set the value of a -@code{N_BINCL} symbol to the total of all the characters in the stabs -strings included in the header file, omitting any file numbers. The -value of an @code{N_EXCL} symbol is the same as the value of the -@code{N_BINCL} symbol it replaces. This information can be used to -match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same -filename. The @code{N_EINCL} value, and the values of the other and -description fields for all three, appear to always be zero. - -@findex C_BINCL -@findex C_EINCL -For the start of an include file in XCOFF, use the @file{.bi} assembler -directive, which generates a @code{C_BINCL} symbol. A @file{.ei} -directive, which generates a @code{C_EINCL} symbol, denotes the end of -the include file. Both directives are followed by the name of the -source file in quotes, which becomes the string for the symbol. -The value of each symbol, produced automatically by the assembler -and linker, is the offset into the executable of the beginning -(inclusive, as you'd expect) or end (inclusive, as you would not expect) -of the portion of the COFF line table that corresponds to this include -file. @code{C_BINCL} and @code{C_EINCL} do not nest. - -@node Line Numbers -@section Line Numbers - -@findex N_SLINE -An @code{N_SLINE} symbol represents the start of a source line. The -desc field contains the line number and the value contains the code -address for the start of that source line. On most machines the address -is absolute; for stabs in sections (@pxref{Stab Sections}), it is -relative to the function in which the @code{N_SLINE} symbol occurs. - -@findex N_DSLINE -@findex N_BSLINE -GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line -numbers in the data or bss segments, respectively. They are identical -to @code{N_SLINE} but are relocated differently by the linker. They -were intended to be used to describe the source location of a variable -declaration, but I believe that GCC2 actually puts the line number in -the desc field of the stab for the variable itself. GDB has been -ignoring these symbols (unless they contain a string field) since -at least GDB 3.5. - -For single source lines that generate discontiguous code, such as flow -of control statements, there may be more than one line number entry for -the same source line. In this case there is a line number entry at the -start of each code range, each with the same line number. - -XCOFF does not use stabs for line numbers. Instead, it uses COFF line -numbers (which are outside the scope of this document). Standard COFF -line numbers cannot deal with include files, but in XCOFF this is fixed -with the @code{C_BINCL} method of marking include files (@pxref{Include -Files}). - -@node Procedures -@section Procedures - -@findex N_FUN, for functions -@findex N_FNAME -@findex N_STSYM, for functions (Sun acc) -@findex N_GSYM, for functions (Sun acc) -All of the following stabs normally use the @code{N_FUN} symbol type. -However, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and -@code{N_STSYM}, which means that the value of the stab for the function -is useless and the debugger must get the address of the function from -the non-stab symbols instead. On systems where non-stab symbols have -leading underscores, the stabs will lack underscores and the debugger -needs to know about the leading underscore to match up the stab and the -non-stab symbol. BSD Fortran is said to use @code{N_FNAME} with the -same restriction; the value of the symbol is not useful (I'm not sure it -really does use this, because GDB doesn't handle this and no one has -complained). - -@findex C_FUN -A function is represented by an @samp{F} symbol descriptor for a global -(extern) function, and @samp{f} for a static (local) function. For -a.out, the value of the symbol is the address of the start of the -function; it is already relocated. For stabs in ELF, the SunPRO -compiler version 2.0.1 and GCC put out an address which gets relocated -by the linker. In a future release SunPRO is planning to put out zero, -in which case the address can be found from the ELF (non-stab) symbol. -Because looking things up in the ELF symbols would probably be slow, I'm -not sure how to find which symbol of that name is the right one, and -this doesn't provide any way to deal with nested functions, it would -probably be better to make the value of the stab an address relative to -the start of the file, or just absolute. See @ref{ELF Linker -Relocation} for more information on linker relocation of stabs in ELF -files. For XCOFF, the stab uses the @code{C_FUN} storage class and the -value of the stab is meaningless; the address of the function can be -found from the csect symbol (XTY_LD/XMC_PR). - -The type information of the stab represents the return type of the -function; thus @samp{foo:f5} means that foo is a function returning type -5. There is no need to try to get the line number of the start of the -function from the stab for the function; it is in the next -@code{N_SLINE} symbol. - -@c FIXME: verify whether the "I suspect" below is true or not. -Some compilers (such as Sun's Solaris compiler) support an extension for -specifying the types of the arguments. I suspect this extension is not -used for old (non-prototyped) function definitions in C. If the -extension is in use, the type information of the stab for the function -is followed by type information for each argument, with each argument -preceded by @samp{;}. An argument type of 0 means that additional -arguments are being passed, whose types and number may vary (@samp{...} -in ANSI C). GDB has tolerated this extension (parsed the syntax, if not -necessarily used the information) since at least version 4.8; I don't -know whether all versions of dbx tolerate it. The argument types given -here are not redundant with the symbols for the formal parameters -(@pxref{Parameters}); they are the types of the arguments as they are -passed, before any conversions might take place. For example, if a C -function which is declared without a prototype takes a @code{float} -argument, the value is passed as a @code{double} but then converted to a -@code{float}. Debuggers need to use the types given in the arguments -when printing values, but when calling the function they need to use the -types given in the symbol defining the function. - -If the return type and types of arguments of a function which is defined -in another source file are specified (i.e., a function prototype in ANSI -C), traditionally compilers emit no stab; the only way for the debugger -to find the information is if the source file where the function is -defined was also compiled with debugging symbols. As an extension the -Solaris compiler uses symbol descriptor @samp{P} followed by the return -type of the function, followed by the arguments, each preceded by -@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}. -This use of symbol descriptor @samp{P} can be distinguished from its use -for register parameters (@pxref{Register Parameters}) by the fact that it has -symbol type @code{N_FUN}. - -The AIX documentation also defines symbol descriptor @samp{J} as an -internal function. I assume this means a function nested within another -function. It also says symbol descriptor @samp{m} is a module in -Modula-2 or extended Pascal. - -Procedures (functions which do not return values) are represented as -functions returning the @code{void} type in C. I don't see why this couldn't -be used for all languages (inventing a @code{void} type for this purpose if -necessary), but the AIX documentation defines @samp{I}, @samp{P}, and -@samp{Q} for internal, global, and static procedures, respectively. -These symbol descriptors are unusual in that they are not followed by -type information. - -The following example shows a stab for a function @code{main} which -returns type number @code{1}. The @code{_main} specified for the value -is a reference to an assembler label which is used to fill in the start -address of the function. - -@example -.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} -@end example - -The stab representing a procedure is located immediately following the -code of the procedure. This stab is in turn directly followed by a -group of other stabs describing elements of the procedure. These other -stabs describe the procedure's parameters, its block local variables, and -its block structure. - -If functions can appear in different sections, then the debugger may not -be able to find the end of a function. Recent versions of GCC will mark -the end of a function with an @code{N_FUN} symbol with an empty string -for the name. The value is the address of the end of the current -function. Without such a symbol, there is no indication of the address -of the end of a function, and you must assume that it ended at the -starting address of the next function or at the end of the text section -for the program. - -@node Nested Procedures -@section Nested Procedures - -For any of the symbol descriptors representing procedures, after the -symbol descriptor and the type information is optionally a scope -specifier. This consists of a comma, the name of the procedure, another -comma, and the name of the enclosing procedure. The first name is local -to the scope specified, and seems to be redundant with the name of the -symbol (before the @samp{:}). This feature is used by GCC, and -presumably Pascal, Modula-2, etc., compilers, for nested functions. - -If procedures are nested more than one level deep, only the immediately -containing scope is specified. For example, this code: - -@example -int -foo (int x) -@{ - int bar (int y) - @{ - int baz (int z) - @{ - return x + y + z; - @} - return baz (x + 2 * y); - @} - return x + bar (3 * x); -@} -@end example - -@noindent -produces the stabs: - -@example -.stabs "baz:f1,baz,bar",36,0,0,_baz.15 # @r{36 is N_FUN} -.stabs "bar:f1,bar,foo",36,0,0,_bar.12 -.stabs "foo:F1",36,0,0,_foo -@end example - -@node Block Structure -@section Block Structure - -@findex N_LBRAC -@findex N_RBRAC -@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of -@c function relative (as documented below). But GDB has never been able -@c to deal with that (it had wanted them to be relative to the file, but -@c I just fixed that (between GDB 4.12 and 4.13)), so it is function -@c relative just like ELF and SOM and the below documentation. -The program's block structure is represented by the @code{N_LBRAC} (left -brace) and the @code{N_RBRAC} (right brace) stab types. The variables -defined inside a block precede the @code{N_LBRAC} symbol for most -compilers, including GCC. Other compilers, such as the Convex, Acorn -RISC machine, and Sun @code{acc} compilers, put the variables after the -@code{N_LBRAC} symbol. The values of the @code{N_LBRAC} and -@code{N_RBRAC} symbols are the start and end addresses of the code of -the block, respectively. For most machines, they are relative to the -starting address of this source file. For the Gould NP1, they are -absolute. For stabs in sections (@pxref{Stab Sections}), they are -relative to the function in which they occur. - -The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block -scope of a procedure are located after the @code{N_FUN} stab that -represents the procedure itself. - -Sun documents the desc field of @code{N_LBRAC} and -@code{N_RBRAC} symbols as containing the nesting level of the block. -However, dbx seems to not care, and GCC always sets desc to -zero. - -@findex .bb -@findex .be -@findex C_BLOCK -For XCOFF, block scope is indicated with @code{C_BLOCK} symbols. If the -name of the symbol is @samp{.bb}, then it is the beginning of the block; -if the name of the symbol is @samp{.be}; it is the end of the block. - -@node Alternate Entry Points -@section Alternate Entry Points - -@findex N_ENTRY -@findex C_ENTRY -Some languages, like Fortran, have the ability to enter procedures at -some place other than the beginning. One can declare an alternate entry -point. The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN -compiler doesn't use it. According to AIX documentation, only the name -of a @code{C_ENTRY} stab is significant; the address of the alternate -entry point comes from the corresponding external symbol. A previous -revision of this document said that the value of an @code{N_ENTRY} stab -was the address of the alternate entry point, but I don't know the -source for that information. - -@node Constants -@chapter Constants - -The @samp{c} symbol descriptor indicates that this stab represents a -constant. This symbol descriptor is an exception to the general rule -that symbol descriptors are followed by type information. Instead, it -is followed by @samp{=} and one of the following: - -@table @code -@item b @var{value} -Boolean constant. @var{value} is a numeric value; I assume it is 0 for -false or 1 for true. - -@item c @var{value} -Character constant. @var{value} is the numeric value of the constant. - -@item e @var{type-information} , @var{value} -Constant whose value can be represented as integral. -@var{type-information} is the type of the constant, as it would appear -after a symbol descriptor (@pxref{String Field}). @var{value} is the -numeric value of the constant. GDB 4.9 does not actually get the right -value if @var{value} does not fit in a host @code{int}, but it does not -do anything violent, and future debuggers could be extended to accept -integers of any size (whether unsigned or not). This constant type is -usually documented as being only for enumeration constants, but GDB has -never imposed that restriction; I don't know about other debuggers. - -@item i @var{value} -Integer constant. @var{value} is the numeric value. The type is some -sort of generic integer type (for GDB, a host @code{int}); to specify -the type explicitly, use @samp{e} instead. - -@item r @var{value} -Real constant. @var{value} is the real value, which can be @samp{INF} -(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet -NaN (not-a-number), or @samp{SNAN} for a signalling NaN. If it is a -normal number the format is that accepted by the C library function -@code{atof}. - -@item s @var{string} -String constant. @var{string} is a string enclosed in either @samp{'} -(in which case @samp{'} characters within the string are represented as -@samp{\'} or @samp{"} (in which case @samp{"} characters within the -string are represented as @samp{\"}). - -@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern} -Set constant. @var{type-information} is the type of the constant, as it -would appear after a symbol descriptor (@pxref{String Field}). -@var{elements} is the number of elements in the set (does this means -how many bits of @var{pattern} are actually used, which would be -redundant with the type, or perhaps the number of bits set in -@var{pattern}? I don't get it), @var{bits} is the number of bits in the -constant (meaning it specifies the length of @var{pattern}, I think), -and @var{pattern} is a hexadecimal representation of the set. AIX -documentation refers to a limit of 32 bytes, but I see no reason why -this limit should exist. This form could probably be used for arbitrary -constants, not just sets; the only catch is that @var{pattern} should be -understood to be target, not host, byte order and format. -@end table - -The boolean, character, string, and set constants are not supported by -GDB 4.9, but it ignores them. GDB 4.8 and earlier gave an error -message and refused to read symbols from the file containing the -constants. - -The above information is followed by @samp{;}. - -@node Variables -@chapter Variables - -Different types of stabs describe the various ways that variables can be -allocated: on the stack, globally, in registers, in common blocks, -statically, or as arguments to a function. - -@menu -* Stack Variables:: Variables allocated on the stack. -* Global Variables:: Variables used by more than one source file. -* Register Variables:: Variables in registers. -* Common Blocks:: Variables statically allocated together. -* Statics:: Variables local to one source file. -* Based Variables:: Fortran pointer based variables. -* Parameters:: Variables for arguments to functions. -@end menu - -@node Stack Variables -@section Automatic Variables Allocated on the Stack - -If a variable's scope is local to a function and its lifetime is only as -long as that function executes (C calls such variables -@dfn{automatic}), it can be allocated in a register (@pxref{Register -Variables}) or on the stack. - -@findex N_LSYM, for stack variables -@findex C_LSYM -Each variable allocated on the stack has a stab with the symbol -descriptor omitted. Since type information should begin with a digit, -@samp{-}, or @samp{(}, only those characters precluded from being used -for symbol descriptors. However, the Acorn RISC machine (ARM) is said -to get this wrong: it puts out a mere type definition here, without the -preceding @samp{@var{type-number}=}. This is a bad idea; there is no -guarantee that type descriptors are distinct from symbol descriptors. -Stabs for stack variables use the @code{N_LSYM} stab type, or -@code{C_LSYM} for XCOFF. - -The value of the stab is the offset of the variable within the -local variables. On most machines this is an offset from the frame -pointer and is negative. The location of the stab specifies which block -it is defined in; see @ref{Block Structure}. - -For example, the following C code: - -@example -int -main () -@{ - int x; -@} -@end example - -produces the following stabs: - -@example -.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} -.stabs "x:1",128,0,0,-12 # @r{128 is N_LSYM} -.stabn 192,0,0,LBB2 # @r{192 is N_LBRAC} -.stabn 224,0,0,LBE2 # @r{224 is N_RBRAC} -@end example - -See @ref{Procedures} for more information on the @code{N_FUN} stab, and -@ref{Block Structure} for more information on the @code{N_LBRAC} and -@code{N_RBRAC} stabs. - -@node Global Variables -@section Global Variables - -@findex N_GSYM -@findex C_GSYM -@c FIXME: verify for sure that it really is C_GSYM on XCOFF -A variable whose scope is not specific to just one source file is -represented by the @samp{G} symbol descriptor. These stabs use the -@code{N_GSYM} stab type (C_GSYM for XCOFF). The type information for -the stab (@pxref{String Field}) gives the type of the variable. - -For example, the following source code: - -@example -char g_foo = 'c'; -@end example - -@noindent -yields the following assembly code: - -@example -.stabs "g_foo:G2",32,0,0,0 # @r{32 is N_GSYM} - .global _g_foo - .data -_g_foo: - .byte 99 -@end example - -The address of the variable represented by the @code{N_GSYM} is not -contained in the @code{N_GSYM} stab. The debugger gets this information -from the external symbol for the global variable. In the example above, -the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to -produce an external symbol. - -Some compilers, like GCC, output @code{N_GSYM} stabs only once, where -the variable is defined. Other compilers, like SunOS4 /bin/cc, output a -@code{N_GSYM} stab for each compilation unit which references the -variable. - -@node Register Variables -@section Register Variables - -@findex N_RSYM -@findex C_RSYM -@c According to an old version of this manual, AIX uses C_RPSYM instead -@c of C_RSYM. I am skeptical; this should be verified. -Register variables have their own stab type, @code{N_RSYM} -(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}. -The stab's value is the number of the register where the variable data -will be stored. -@c .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc) - -AIX defines a separate symbol descriptor @samp{d} for floating point -registers. This seems unnecessary; why not just just give floating -point registers different register numbers? I have not verified whether -the compiler actually uses @samp{d}. - -If the register is explicitly allocated to a global variable, but not -initialized, as in: - -@example -register int g_bar asm ("%g5"); -@end example - -@noindent -then the stab may be emitted at the end of the object file, with -the other bss symbols. - -@node Common Blocks -@section Common Blocks - -A common block is a statically allocated section of memory which can be -referred to by several source files. It may contain several variables. -I believe Fortran is the only language with this feature. - -@findex N_BCOMM -@findex N_ECOMM -@findex C_BCOMM -@findex C_ECOMM -A @code{N_BCOMM} stab begins a common block and an @code{N_ECOMM} stab -ends it. The only field that is significant in these two stabs is the -string, which names a normal (non-debugging) symbol that gives the -address of the common block. According to IBM documentation, only the -@code{N_BCOMM} has the name of the common block (even though their -compiler actually puts it both places). - -@findex N_ECOML -@findex C_ECOML -The stabs for the members of the common block are between the -@code{N_BCOMM} and the @code{N_ECOMM}; the value of each stab is the -offset within the common block of that variable. IBM uses the -@code{C_ECOML} stab type, and there is a corresponding @code{N_ECOML} -stab type, but Sun's Fortran compiler uses @code{N_GSYM} instead. The -variables within a common block use the @samp{V} symbol descriptor (I -believe this is true of all Fortran variables). Other stabs (at least -type declarations using @code{C_DECL}) can also be between the -@code{N_BCOMM} and the @code{N_ECOMM}. - -@node Statics -@section Static Variables - -Initialized static variables are represented by the @samp{S} and -@samp{V} symbol descriptors. @samp{S} means file scope static, and -@samp{V} means procedure scope static. One exception: in XCOFF, IBM's -xlc compiler always uses @samp{V}, and whether it is file scope or not -is distinguished by whether the stab is located within a function. - -@c This is probably not worth mentioning; it is only true on the sparc -@c for `double' variables which although declared const are actually in -@c the data segment (the text segment can't guarantee 8 byte alignment). -@c (although GCC -@c 2.4.5 has a bug in that it uses @code{N_FUN}, so neither dbx nor GDB can -@c find the variables) -@findex N_STSYM -@findex N_LCSYM -@findex N_FUN, for variables -@findex N_ROSYM -In a.out files, @code{N_STSYM} means the data section, @code{N_FUN} -means the text section, and @code{N_LCSYM} means the bss section. For -those systems with a read-only data section separate from the text -section (Solaris), @code{N_ROSYM} means the read-only data section. - -For example, the source lines: - -@example -static const int var_const = 5; -static int var_init = 2; -static int var_noinit; -@end example - -@noindent -yield the following stabs: - -@example -.stabs "var_const:S1",36,0,0,_var_const # @r{36 is N_FUN} -@dots{} -.stabs "var_init:S1",38,0,0,_var_init # @r{38 is N_STSYM} -@dots{} -.stabs "var_noinit:S1",40,0,0,_var_noinit # @r{40 is N_LCSYM} -@end example - -@findex C_STSYM -@findex C_BSTAT -@findex C_ESTAT -In XCOFF files, the stab type need not indicate the section; -@code{C_STSYM} can be used for all statics. Also, each static variable -is enclosed in a static block. A @code{C_BSTAT} (emitted with a -@samp{.bs} assembler directive) symbol begins the static block; its -value is the symbol number of the csect symbol whose value is the -address of the static block, its section is the section of the variables -in that static block, and its name is @samp{.bs}. A @code{C_ESTAT} -(emitted with a @samp{.es} assembler directive) symbol ends the static -block; its name is @samp{.es} and its value and section are ignored. - -In ECOFF files, the storage class is used to specify the section, so the -stab type need not indicate the section. - -In ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor -@samp{S} means that the address is absolute (the linker relocates it) -and symbol descriptor @samp{V} means that the address is relative to the -start of the relevant section for that compilation unit. SunPRO has -plans to have the linker stop relocating stabs; I suspect that their the -debugger gets the address from the corresponding ELF (not stab) symbol. -I'm not sure how to find which symbol of that name is the right one. -The clean way to do all this would be to have the value of a symbol -descriptor @samp{S} symbol be an offset relative to the start of the -file, just like everything else, but that introduces obvious -compatibility problems. For more information on linker stab relocation, -@xref{ELF Linker Relocation}. - -@node Based Variables -@section Fortran Based Variables - -Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature -which allows allocating arrays with @code{malloc}, but which avoids -blurring the line between arrays and pointers the way that C does. In -stabs such a variable uses the @samp{b} symbol descriptor. - -For example, the Fortran declarations - -@example -real foo, foo10(10), foo10_5(10,5) -pointer (foop, foo) -pointer (foo10p, foo10) -pointer (foo105p, foo10_5) -@end example - -produce the stabs - -@example -foo:b6 -foo10:bar3;1;10;6 -foo10_5:bar3;1;5;ar3;1;10;6 -@end example - -In this example, @code{real} is type 6 and type 3 is an integral type -which is the type of the subscripts of the array (probably -@code{integer}). - -The @samp{b} symbol descriptor is like @samp{V} in that it denotes a -statically allocated symbol whose scope is local to a function; see -@xref{Statics}. The value of the symbol, instead of being the address -of the variable itself, is the address of a pointer to that variable. -So in the above example, the value of the @code{foo} stab is the address -of a pointer to a real, the value of the @code{foo10} stab is the -address of a pointer to a 10-element array of reals, and the value of -the @code{foo10_5} stab is the address of a pointer to a 5-element array -of 10-element arrays of reals. - -@node Parameters -@section Parameters - -Formal parameters to a function are represented by a stab (or sometimes -two; see below) for each parameter. The stabs are in the order in which -the debugger should print the parameters (i.e., the order in which the -parameters are declared in the source file). The exact form of the stab -depends on how the parameter is being passed. - -@findex N_PSYM -@findex C_PSYM -Parameters passed on the stack use the symbol descriptor @samp{p} and -the @code{N_PSYM} symbol type (or @code{C_PSYM} for XCOFF). The value -of the symbol is an offset used to locate the parameter on the stack; -its exact meaning is machine-dependent, but on most machines it is an -offset from the frame pointer. - -As a simple example, the code: - -@example -main (argc, argv) - int argc; - char **argv; -@end example - -produces the stabs: - -@example -.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} -.stabs "argc:p1",160,0,0,68 # @r{160 is N_PSYM} -.stabs "argv:p20=*21=*2",160,0,0,72 -@end example - -The type definition of @code{argv} is interesting because it contains -several type definitions. Type 21 is pointer to type 2 (char) and -@code{argv} (type 20) is pointer to type 21. - -@c FIXME: figure out what these mean and describe them coherently. -The following symbol descriptors are also said to go with @code{N_PSYM}. -The value of the symbol is said to be an offset from the argument -pointer (I'm not sure whether this is true or not). - -@example -pP (<<??>>) -pF Fortran function parameter -X (function result variable) -@end example - -@menu -* Register Parameters:: -* Local Variable Parameters:: -* Reference Parameters:: -* Conformant Arrays:: -@end menu - -@node Register Parameters -@subsection Passing Parameters in Registers - -If the parameter is passed in a register, then traditionally there are -two symbols for each argument: - -@example -.stabs "arg:p1" . . . ; N_PSYM -.stabs "arg:r1" . . . ; N_RSYM -@end example - -Debuggers use the second one to find the value, and the first one to -know that it is an argument. - -@findex C_RPSYM -@findex N_RSYM, for parameters -Because that approach is kind of ugly, some compilers use symbol -descriptor @samp{P} or @samp{R} to indicate an argument which is in a -register. Symbol type @code{C_RPSYM} is used in XCOFF and @code{N_RSYM} -is used otherwise. The symbol's value is the register number. @samp{P} -and @samp{R} mean the same thing; the difference is that @samp{P} is a -GNU invention and @samp{R} is an IBM (XCOFF) invention. As of version -4.9, GDB should handle either one. - -There is at least one case where GCC uses a @samp{p} and @samp{r} pair -rather than @samp{P}; this is where the argument is passed in the -argument list and then loaded into a register. - -According to the AIX documentation, symbol descriptor @samp{D} is for a -parameter passed in a floating point register. This seems -unnecessary---why not just use @samp{R} with a register number which -indicates that it's a floating point register? I haven't verified -whether the system actually does what the documentation indicates. - -@c FIXME: On the hppa this is for any type > 8 bytes, I think, and not -@c for small structures (investigate). -On the sparc and hppa, for a @samp{P} symbol whose type is a structure -or union, the register contains the address of the structure. On the -sparc, this is also true of a @samp{p} and @samp{r} pair (using Sun -@code{cc}) or a @samp{p} symbol. However, if a (small) structure is -really in a register, @samp{r} is used. And, to top it all off, on the -hppa it might be a structure which was passed on the stack and loaded -into a register and for which there is a @samp{p} and @samp{r} pair! I -believe that symbol descriptor @samp{i} is supposed to deal with this -case (it is said to mean "value parameter by reference, indirect -access"; I don't know the source for this information), but I don't know -details or what compilers or debuggers use it, if any (not GDB or GCC). -It is not clear to me whether this case needs to be dealt with -differently than parameters passed by reference (@pxref{Reference Parameters}). - -@node Local Variable Parameters -@subsection Storing Parameters as Local Variables - -There is a case similar to an argument in a register, which is an -argument that is actually stored as a local variable. Sometimes this -happens when the argument was passed in a register and then the compiler -stores it as a local variable. If possible, the compiler should claim -that it's in a register, but this isn't always done. - -If a parameter is passed as one type and converted to a smaller type by -the prologue (for example, the parameter is declared as a @code{float}, -but the calling conventions specify that it is passed as a -@code{double}), then GCC2 (sometimes) uses a pair of symbols. The first -symbol uses symbol descriptor @samp{p} and the type which is passed. -The second symbol has the type and location which the parameter actually -has after the prologue. For example, suppose the following C code -appears with no prototypes involved: - -@example -void -subr (f) - float f; -@{ -@end example - -if @code{f} is passed as a double at stack offset 8, and the prologue -converts it to a float in register number 0, then the stabs look like: - -@example -.stabs "f:p13",160,0,3,8 # @r{160 is @code{N_PSYM}, here 13 is @code{double}} -.stabs "f:r12",64,0,3,0 # @r{64 is @code{N_RSYM}, here 12 is @code{float}} -@end example - -In both stabs 3 is the line number where @code{f} is declared -(@pxref{Line Numbers}). - -@findex N_LSYM, for parameter -GCC, at least on the 960, has another solution to the same problem. It -uses a single @samp{p} symbol descriptor for an argument which is stored -as a local variable but uses @code{N_LSYM} instead of @code{N_PSYM}. In -this case, the value of the symbol is an offset relative to the local -variables for that function, not relative to the arguments; on some -machines those are the same thing, but not on all. - -@c This is mostly just background info; the part that logically belongs -@c here is the last sentence. -On the VAX or on other machines in which the calling convention includes -the number of words of arguments actually passed, the debugger (GDB at -least) uses the parameter symbols to keep track of whether it needs to -print nameless arguments in addition to the formal parameters which it -has printed because each one has a stab. For example, in - -@example -extern int fprintf (FILE *stream, char *format, @dots{}); -@dots{} -fprintf (stdout, "%d\n", x); -@end example - -there are stabs for @code{stream} and @code{format}. On most machines, -the debugger can only print those two arguments (because it has no way -of knowing that additional arguments were passed), but on the VAX or -other machines with a calling convention which indicates the number of -words of arguments, the debugger can print all three arguments. To do -so, the parameter symbol (symbol descriptor @samp{p}) (not necessarily -@samp{r} or symbol descriptor omitted symbols) needs to contain the -actual type as passed (for example, @code{double} not @code{float} if it -is passed as a double and converted to a float). - -@node Reference Parameters -@subsection Passing Parameters by Reference - -If the parameter is passed by reference (e.g., Pascal @code{VAR} -parameters), then the symbol descriptor is @samp{v} if it is in the -argument list, or @samp{a} if it in a register. Other than the fact -that these contain the address of the parameter rather than the -parameter itself, they are identical to @samp{p} and @samp{R}, -respectively. I believe @samp{a} is an AIX invention; @samp{v} is -supported by all stabs-using systems as far as I know. - -@node Conformant Arrays -@subsection Passing Conformant Array Parameters - -@c Is this paragraph correct? It is based on piecing together patchy -@c information and some guesswork -Conformant arrays are a feature of Modula-2, and perhaps other -languages, in which the size of an array parameter is not known to the -called function until run-time. Such parameters have two stabs: a -@samp{x} for the array itself, and a @samp{C}, which represents the size -of the array. The value of the @samp{x} stab is the offset in the -argument list where the address of the array is stored (it this right? -it is a guess); the value of the @samp{C} stab is the offset in the -argument list where the size of the array (in elements? in bytes?) is -stored. - -@node Types -@chapter Defining Types - -The examples so far have described types as references to previously -defined types, or defined in terms of subranges of or pointers to -previously defined types. This chapter describes the other type -descriptors that may follow the @samp{=} in a type definition. - -@menu -* Builtin Types:: Integers, floating point, void, etc. -* Miscellaneous Types:: Pointers, sets, files, etc. -* Cross-References:: Referring to a type not yet defined. -* Subranges:: A type with a specific range. -* Arrays:: An aggregate type of same-typed elements. -* Strings:: Like an array but also has a length. -* Enumerations:: Like an integer but the values have names. -* Structures:: An aggregate type of different-typed elements. -* Typedefs:: Giving a type a name. -* Unions:: Different types sharing storage. -* Function Types:: -@end menu - -@node Builtin Types -@section Builtin Types - -Certain types are built in (@code{int}, @code{short}, @code{void}, -@code{float}, etc.); the debugger recognizes these types and knows how -to handle them. Thus, don't be surprised if some of the following ways -of specifying builtin types do not specify everything that a debugger -would need to know about the type---in some cases they merely specify -enough information to distinguish the type from other types. - -The traditional way to define builtin types is convoluted, so new ways -have been invented to describe them. Sun's @code{acc} uses special -builtin type descriptors (@samp{b} and @samp{R}), and IBM uses negative -type numbers. GDB accepts all three ways, as of version 4.8; dbx just -accepts the traditional builtin types and perhaps one of the other two -formats. The following sections describe each of these formats. - -@menu -* Traditional Builtin Types:: Put on your seat belts and prepare for kludgery -* Builtin Type Descriptors:: Builtin types with special type descriptors -* Negative Type Numbers:: Builtin types using negative type numbers -@end menu - -@node Traditional Builtin Types -@subsection Traditional Builtin Types - -This is the traditional, convoluted method for defining builtin types. -There are several classes of such type definitions: integer, floating -point, and @code{void}. - -@menu -* Traditional Integer Types:: -* Traditional Other Types:: -@end menu - -@node Traditional Integer Types -@subsubsection Traditional Integer Types - -Often types are defined as subranges of themselves. If the bounding values -fit within an @code{int}, then they are given normally. For example: - -@example -.stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # @r{128 is N_LSYM} -.stabs "char:t2=r2;0;127;",128,0,0,0 -@end example - -Builtin types can also be described as subranges of @code{int}: - -@example -.stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 -@end example - -If the lower bound of a subrange is 0 and the upper bound is -1, -the type is an unsigned integral type whose bounds are too -big to describe in an @code{int}. Traditionally this is only used for -@code{unsigned int} and @code{unsigned long}: - -@example -.stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 -@end example - -For larger types, GCC 2.4.5 puts out bounds in octal, with one or more -leading zeroes. In this case a negative bound consists of a number -which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in -the number (except the sign bit), and a positive bound is one which is a -1 bit for each bit in the number (except possibly the sign bit). All -known versions of dbx and GDB version 4 accept this (at least in the -sense of not refusing to process the file), but GDB 3.5 refuses to read -the whole file containing such symbols. So GCC 2.3.3 did not output the -proper size for these types. As an example of octal bounds, the string -fields of the stabs for 64 bit integer types look like: - -@c .stabs directives, etc., omitted to make it fit on the page. -@example -long int:t3=r1;001000000000000000000000;000777777777777777777777; -long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; -@end example - -If the lower bound of a subrange is 0 and the upper bound is negative, -the type is an unsigned integral type whose size in bytes is the -absolute value of the upper bound. I believe this is a Convex -convention for @code{unsigned long long}. - -If the lower bound of a subrange is negative and the upper bound is 0, -the type is a signed integral type whose size in bytes is -the absolute value of the lower bound. I believe this is a Convex -convention for @code{long long}. To distinguish this from a legitimate -subrange, the type should be a subrange of itself. I'm not sure whether -this is the case for Convex. - -@node Traditional Other Types -@subsubsection Traditional Other Types - -If the upper bound of a subrange is 0 and the lower bound is positive, -the type is a floating point type, and the lower bound of the subrange -indicates the number of bytes in the type: - -@example -.stabs "float:t12=r1;4;0;",128,0,0,0 -.stabs "double:t13=r1;8;0;",128,0,0,0 -@end example - -However, GCC writes @code{long double} the same way it writes -@code{double}, so there is no way to distinguish. - -@example -.stabs "long double:t14=r1;8;0;",128,0,0,0 -@end example - -Complex types are defined the same way as floating-point types; there is -no way to distinguish a single-precision complex from a double-precision -floating-point type. - -The C @code{void} type is defined as itself: - -@example -.stabs "void:t15=15",128,0,0,0 -@end example - -I'm not sure how a boolean type is represented. - -@node Builtin Type Descriptors -@subsection Defining Builtin Types Using Builtin Type Descriptors - -This is the method used by Sun's @code{acc} for defining builtin types. -These are the type descriptors to define builtin types: - -@table @code -@c FIXME: clean up description of width and offset, once we figure out -@c what they mean -@item b @var{signed} @var{char-flag} @var{width} ; @var{offset} ; @var{nbits} ; -Define an integral type. @var{signed} is @samp{u} for unsigned or -@samp{s} for signed. @var{char-flag} is @samp{c} which indicates this -is a character type, or is omitted. I assume this is to distinguish an -integral type from a character type of the same size, for example it -might make sense to set it for the C type @code{wchar_t} so the debugger -can print such variables differently (Solaris does not do this). Sun -sets it on the C types @code{signed char} and @code{unsigned char} which -arguably is wrong. @var{width} and @var{offset} appear to be for small -objects stored in larger ones, for example a @code{short} in an -@code{int} register. @var{width} is normally the number of bytes in the -type. @var{offset} seems to always be zero. @var{nbits} is the number -of bits in the type. - -Note that type descriptor @samp{b} used for builtin types conflicts with -its use for Pascal space types (@pxref{Miscellaneous Types}); they can -be distinguished because the character following the type descriptor -will be a digit, @samp{(}, or @samp{-} for a Pascal space type, or -@samp{u} or @samp{s} for a builtin type. - -@item w -Documented by AIX to define a wide character type, but their compiler -actually uses negative type numbers (@pxref{Negative Type Numbers}). - -@item R @var{fp-type} ; @var{bytes} ; -Define a floating point type. @var{fp-type} has one of the following values: - -@table @code -@item 1 (NF_SINGLE) -IEEE 32-bit (single precision) floating point format. - -@item 2 (NF_DOUBLE) -IEEE 64-bit (double precision) floating point format. - -@item 3 (NF_COMPLEX) -@item 4 (NF_COMPLEX16) -@item 5 (NF_COMPLEX32) -@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying -@c to put that here got an overfull hbox. -These are for complex numbers. A comment in the GDB source describes -them as Fortran @code{complex}, @code{double complex}, and -@code{complex*16}, respectively, but what does that mean? (i.e., Single -precision? Double precision?). - -@item 6 (NF_LDOUBLE) -Long double. This should probably only be used for Sun format -@code{long double}, and new codes should be used for other floating -point formats (@code{NF_DOUBLE} can be used if a @code{long double} is -really just an IEEE double, of course). -@end table - -@var{bytes} is the number of bytes occupied by the type. This allows a -debugger to perform some operations with the type even if it doesn't -understand @var{fp-type}. - -@item g @var{type-information} ; @var{nbits} -Documented by AIX to define a floating type, but their compiler actually -uses negative type numbers (@pxref{Negative Type Numbers}). - -@item c @var{type-information} ; @var{nbits} -Documented by AIX to define a complex type, but their compiler actually -uses negative type numbers (@pxref{Negative Type Numbers}). -@end table - -The C @code{void} type is defined as a signed integral type 0 bits long: -@example -.stabs "void:t19=bs0;0;0",128,0,0,0 -@end example -The Solaris compiler seems to omit the trailing semicolon in this case. -Getting sloppy in this way is not a swift move because if a type is -embedded in a more complex expression it is necessary to be able to tell -where it ends. - -I'm not sure how a boolean type is represented. - -@node Negative Type Numbers -@subsection Negative Type Numbers - -This is the method used in XCOFF for defining builtin types. -Since the debugger knows about the builtin types anyway, the idea of -negative type numbers is simply to give a special type number which -indicates the builtin type. There is no stab defining these types. - -There are several subtle issues with negative type numbers. - -One is the size of the type. A builtin type (for example the C types -@code{int} or @code{long}) might have different sizes depending on -compiler options, the target architecture, the ABI, etc. This issue -doesn't come up for IBM tools since (so far) they just target the -RS/6000; the sizes indicated below for each size are what the IBM -RS/6000 tools use. To deal with differing sizes, either define separate -negative type numbers for each size (which works but requires changing -the debugger, and, unless you get both AIX dbx and GDB to accept the -change, introduces an incompatibility), or use a type attribute -(@pxref{String Field}) to define a new type with the appropriate size -(which merely requires a debugger which understands type attributes, -like AIX dbx or GDB). For example, - -@example -.stabs "boolean:t10=@@s8;-16",128,0,0,0 -@end example - -defines an 8-bit boolean type, and - -@example -.stabs "boolean:t10=@@s64;-16",128,0,0,0 -@end example - -defines a 64-bit boolean type. - -A similar issue is the format of the type. This comes up most often for -floating-point types, which could have various formats (particularly -extended doubles, which vary quite a bit even among IEEE systems). -Again, it is best to define a new negative type number for each -different format; changing the format based on the target system has -various problems. One such problem is that the Alpha has both VAX and -IEEE floating types. One can easily imagine one library using the VAX -types and another library in the same executable using the IEEE types. -Another example is that the interpretation of whether a boolean is true -or false can be based on the least significant bit, most significant -bit, whether it is zero, etc., and different compilers (or different -options to the same compiler) might provide different kinds of boolean. - -The last major issue is the names of the types. The name of a given -type depends @emph{only} on the negative type number given; these do not -vary depending on the language, the target system, or anything else. -One can always define separate type numbers---in the following list you -will see for example separate @code{int} and @code{integer*4} types -which are identical except for the name. But compatibility can be -maintained by not inventing new negative type numbers and instead just -defining a new type with a new name. For example: - -@example -.stabs "CARDINAL:t10=-8",128,0,0,0 -@end example - -Here is the list of negative type numbers. The phrase @dfn{integral -type} is used to mean twos-complement (I strongly suspect that all -machines which use stabs use twos-complement; most machines use -twos-complement these days). - -@table @code -@item -1 -@code{int}, 32 bit signed integral type. - -@item -2 -@code{char}, 8 bit type holding a character. Both GDB and dbx on AIX -treat this as signed. GCC uses this type whether @code{char} is signed -or not, which seems like a bad idea. The AIX compiler (@code{xlc}) seems to -avoid this type; it uses -5 instead for @code{char}. - -@item -3 -@code{short}, 16 bit signed integral type. - -@item -4 -@code{long}, 32 bit signed integral type. - -@item -5 -@code{unsigned char}, 8 bit unsigned integral type. - -@item -6 -@code{signed char}, 8 bit signed integral type. - -@item -7 -@code{unsigned short}, 16 bit unsigned integral type. - -@item -8 -@code{unsigned int}, 32 bit unsigned integral type. - -@item -9 -@code{unsigned}, 32 bit unsigned integral type. - -@item -10 -@code{unsigned long}, 32 bit unsigned integral type. - -@item -11 -@code{void}, type indicating the lack of a value. - -@item -12 -@code{float}, IEEE single precision. - -@item -13 -@code{double}, IEEE double precision. - -@item -14 -@code{long double}, IEEE double precision. The compiler claims the size -will increase in a future release, and for binary compatibility you have -to avoid using @code{long double}. I hope when they increase it they -use a new negative type number. - -@item -15 -@code{integer}. 32 bit signed integral type. - -@item -16 -@code{boolean}. 32 bit type. GDB and GCC assume that zero is false, -one is true, and other values have unspecified meaning. I hope this -agrees with how the IBM tools use the type. - -@item -17 -@code{short real}. IEEE single precision. - -@item -18 -@code{real}. IEEE double precision. - -@item -19 -@code{stringptr}. @xref{Strings}. - -@item -20 -@code{character}, 8 bit unsigned character type. - -@item -21 -@code{logical*1}, 8 bit type. This Fortran type has a split -personality in that it is used for boolean variables, but can also be -used for unsigned integers. 0 is false, 1 is true, and other values are -non-boolean. - -@item -22 -@code{logical*2}, 16 bit type. This Fortran type has a split -personality in that it is used for boolean variables, but can also be -used for unsigned integers. 0 is false, 1 is true, and other values are -non-boolean. - -@item -23 -@code{logical*4}, 32 bit type. This Fortran type has a split -personality in that it is used for boolean variables, but can also be -used for unsigned integers. 0 is false, 1 is true, and other values are -non-boolean. - -@item -24 -@code{logical}, 32 bit type. This Fortran type has a split -personality in that it is used for boolean variables, but can also be -used for unsigned integers. 0 is false, 1 is true, and other values are -non-boolean. - -@item -25 -@code{complex}. A complex type consisting of two IEEE single-precision -floating point values. - -@item -26 -@code{complex}. A complex type consisting of two IEEE double-precision -floating point values. - -@item -27 -@code{integer*1}, 8 bit signed integral type. - -@item -28 -@code{integer*2}, 16 bit signed integral type. - -@item -29 -@code{integer*4}, 32 bit signed integral type. - -@item -30 -@code{wchar}. Wide character, 16 bits wide, unsigned (what format? -Unicode?). - -@item -31 -@code{long long}, 64 bit signed integral type. - -@item -32 -@code{unsigned long long}, 64 bit unsigned integral type. - -@item -33 -@code{logical*8}, 64 bit unsigned integral type. - -@item -34 -@code{integer*8}, 64 bit signed integral type. -@end table - -@node Miscellaneous Types -@section Miscellaneous Types - -@table @code -@item b @var{type-information} ; @var{bytes} -Pascal space type. This is documented by IBM; what does it mean? - -This use of the @samp{b} type descriptor can be distinguished -from its use for builtin integral types (@pxref{Builtin Type -Descriptors}) because the character following the type descriptor is -always a digit, @samp{(}, or @samp{-}. - -@item B @var{type-information} -A volatile-qualified version of @var{type-information}. This is -a Sun extension. References and stores to a variable with a -volatile-qualified type must not be optimized or cached; they -must occur as the user specifies them. - -@item d @var{type-information} -File of type @var{type-information}. As far as I know this is only used -by Pascal. - -@item k @var{type-information} -A const-qualified version of @var{type-information}. This is a Sun -extension. A variable with a const-qualified type cannot be modified. - -@item M @var{type-information} ; @var{length} -Multiple instance type. The type seems to composed of @var{length} -repetitions of @var{type-information}, for example @code{character*3} is -represented by @samp{M-2;3}, where @samp{-2} is a reference to a -character type (@pxref{Negative Type Numbers}). I'm not sure how this -differs from an array. This appears to be a Fortran feature. -@var{length} is a bound, like those in range types; see @ref{Subranges}. - -@item S @var{type-information} -Pascal set type. @var{type-information} must be a small type such as an -enumeration or a subrange, and the type is a bitmask whose length is -specified by the number of elements in @var{type-information}. - -In CHILL, if it is a bitstring instead of a set, also use the @samp{S} -type attribute (@pxref{String Field}). - -@item * @var{type-information} -Pointer to @var{type-information}. -@end table - -@node Cross-References -@section Cross-References to Other Types - -A type can be used before it is defined; one common way to deal with -that situation is just to use a type reference to a type which has not -yet been defined. - -Another way is with the @samp{x} type descriptor, which is followed by -@samp{s} for a structure tag, @samp{u} for a union tag, or @samp{e} for -a enumerator tag, followed by the name of the tag, followed by @samp{:}. -If the name contains @samp{::} between a @samp{<} and @samp{>} pair (for -C@t{++} templates), such a @samp{::} does not end the name---only a single -@samp{:} ends the name; see @ref{Nested Symbols}. - -For example, the following C declarations: - -@example -struct foo; -struct foo *bar; -@end example - -@noindent -produce: - -@example -.stabs "bar:G16=*17=xsfoo:",32,0,0,0 -@end example - -Not all debuggers support the @samp{x} type descriptor, so on some -machines GCC does not use it. I believe that for the above example it -would just emit a reference to type 17 and never define it, but I -haven't verified that. - -Modula-2 imported types, at least on AIX, use the @samp{i} type -descriptor, which is followed by the name of the module from which the -type is imported, followed by @samp{:}, followed by the name of the -type. There is then optionally a comma followed by type information for -the type. This differs from merely naming the type (@pxref{Typedefs}) in -that it identifies the module; I don't understand whether the name of -the type given here is always just the same as the name we are giving -it, or whether this type descriptor is used with a nameless stab -(@pxref{String Field}), or what. The symbol ends with @samp{;}. - -@node Subranges -@section Subrange Types - -The @samp{r} type descriptor defines a type as a subrange of another -type. It is followed by type information for the type of which it is a -subrange, a semicolon, an integral lower bound, a semicolon, an -integral upper bound, and a semicolon. The AIX documentation does not -specify the trailing semicolon, in an effort to specify array indexes -more cleanly, but a subrange which is not an array index has always -included a trailing semicolon (@pxref{Arrays}). - -Instead of an integer, either bound can be one of the following: - -@table @code -@item A @var{offset} -The bound is passed by reference on the stack at offset @var{offset} -from the argument list. @xref{Parameters}, for more information on such -offsets. - -@item T @var{offset} -The bound is passed by value on the stack at offset @var{offset} from -the argument list. - -@item a @var{register-number} -The bound is passed by reference in register number -@var{register-number}. - -@item t @var{register-number} -The bound is passed by value in register number @var{register-number}. - -@item J -There is no bound. -@end table - -Subranges are also used for builtin types; see @ref{Traditional Builtin Types}. - -@node Arrays -@section Array Types - -Arrays use the @samp{a} type descriptor. Following the type descriptor -is the type of the index and the type of the array elements. If the -index type is a range type, it ends in a semicolon; otherwise -(for example, if it is a type reference), there does not -appear to be any way to tell where the types are separated. In an -effort to clean up this mess, IBM documents the two types as being -separated by a semicolon, and a range type as not ending in a semicolon -(but this is not right for range types which are not array indexes, -@pxref{Subranges}). I think probably the best solution is to specify -that a semicolon ends a range type, and that the index type and element -type of an array are separated by a semicolon, but that if the index -type is a range type, the extra semicolon can be omitted. GDB (at least -through version 4.9) doesn't support any kind of index type other than a -range anyway; I'm not sure about dbx. - -It is well established, and widely used, that the type of the index, -unlike most types found in the stabs, is merely a type definition, not -type information (@pxref{String Field}) (that is, it need not start with -@samp{@var{type-number}=} if it is defining a new type). According to a -comment in GDB, this is also true of the type of the array elements; it -gives @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two -dimensional array. According to AIX documentation, the element type -must be type information. GDB accepts either. - -The type of the index is often a range type, expressed as the type -descriptor @samp{r} and some parameters. It defines the size of the -array. In the example below, the range @samp{r1;0;2;} defines an index -type which is a subrange of type 1 (integer), with a lower bound of 0 -and an upper bound of 2. This defines the valid range of subscripts of -a three-element C array. - -For example, the definition: - -@example -char char_vec[3] = @{'a','b','c'@}; -@end example - -@noindent -produces the output: - -@example -.stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 - .global _char_vec - .align 4 -_char_vec: - .byte 97 - .byte 98 - .byte 99 -@end example - -If an array is @dfn{packed}, the elements are spaced more -closely than normal, saving memory at the expense of speed. For -example, an array of 3-byte objects might, if unpacked, have each -element aligned on a 4-byte boundary, but if packed, have no padding. -One way to specify that something is packed is with type attributes -(@pxref{String Field}). In the case of arrays, another is to use the -@samp{P} type descriptor instead of @samp{a}. Other than specifying a -packed array, @samp{P} is identical to @samp{a}. - -@c FIXME-what is it? A pointer? -An open array is represented by the @samp{A} type descriptor followed by -type information specifying the type of the array elements. - -@c FIXME: what is the format of this type? A pointer to a vector of pointers? -An N-dimensional dynamic array is represented by - -@example -D @var{dimensions} ; @var{type-information} -@end example - -@c Does dimensions really have this meaning? The AIX documentation -@c doesn't say. -@var{dimensions} is the number of dimensions; @var{type-information} -specifies the type of the array elements. - -@c FIXME: what is the format of this type? A pointer to some offsets in -@c another array? -A subarray of an N-dimensional array is represented by - -@example -E @var{dimensions} ; @var{type-information} -@end example - -@c Does dimensions really have this meaning? The AIX documentation -@c doesn't say. -@var{dimensions} is the number of dimensions; @var{type-information} -specifies the type of the array elements. - -@node Strings -@section Strings - -Some languages, like C or the original Pascal, do not have string types, -they just have related things like arrays of characters. But most -Pascals and various other languages have string types, which are -indicated as follows: - -@table @code -@item n @var{type-information} ; @var{bytes} -@var{bytes} is the maximum length. I'm not sure what -@var{type-information} is; I suspect that it means that this is a string -of @var{type-information} (thus allowing a string of integers, a string -of wide characters, etc., as well as a string of characters). Not sure -what the format of this type is. This is an AIX feature. - -@item z @var{type-information} ; @var{bytes} -Just like @samp{n} except that this is a gstring, not an ordinary -string. I don't know the difference. - -@item N -Pascal Stringptr. What is this? This is an AIX feature. -@end table - -Languages, such as CHILL which have a string type which is basically -just an array of characters use the @samp{S} type attribute -(@pxref{String Field}). - -@node Enumerations -@section Enumerations - -Enumerations are defined with the @samp{e} type descriptor. - -@c FIXME: Where does this information properly go? Perhaps it is -@c redundant with something we already explain. -The source line below declares an enumeration type at file scope. -The type definition is located after the @code{N_RBRAC} that marks the end of -the previous procedure's block scope, and before the @code{N_FUN} that marks -the beginning of the next procedure's block scope. Therefore it does not -describe a block local symbol, but a file local one. - -The source line: - -@example -enum e_places @{first,second=3,last@}; -@end example - -@noindent -generates the following stab: - -@example -.stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 -@end example - -The symbol descriptor (@samp{T}) says that the stab describes a -structure, enumeration, or union tag. The type descriptor @samp{e}, -following the @samp{22=} of the type definition narrows it down to an -enumeration type. Following the @samp{e} is a list of the elements of -the enumeration. The format is @samp{@var{name}:@var{value},}. The -list of elements ends with @samp{;}. The fact that @var{value} is -specified as an integer can cause problems if the value is large. GCC -2.5.2 tries to output it in octal in that case with a leading zero, -which is probably a good thing, although GDB 4.11 supports octal only in -cases where decimal is perfectly good. Negative decimal values are -supported by both GDB and dbx. - -There is no standard way to specify the size of an enumeration type; it -is determined by the architecture (normally all enumerations types are -32 bits). Type attributes can be used to specify an enumeration type of -another size for debuggers which support them; see @ref{String Field}. - -Enumeration types are unusual in that they define symbols for the -enumeration values (@code{first}, @code{second}, and @code{third} in the -above example), and even though these symbols are visible in the file as -a whole (rather than being in a more local namespace like structure -member names), they are defined in the type definition for the -enumeration type rather than each having their own symbol. In order to -be fast, GDB will only get symbols from such types (in its initial scan -of the stabs) if the type is the first thing defined after a @samp{T} or -@samp{t} symbol descriptor (the above example fulfills this -requirement). If the type does not have a name, the compiler should -emit it in a nameless stab (@pxref{String Field}); GCC does this. - -@node Structures -@section Structures - -The encoding of structures in stabs can be shown with an example. - -The following source code declares a structure tag and defines an -instance of the structure in global scope. Then a @code{typedef} equates the -structure tag with a new type. Separate stabs are generated for the -structure tag, the structure @code{typedef}, and the structure instance. The -stabs for the tag and the @code{typedef} are emitted when the definitions are -encountered. Since the structure elements are not initialized, the -stab and code for the structure variable itself is located at the end -of the program in the bss section. - -@example -struct s_tag @{ - int s_int; - float s_float; - char s_char_vec[8]; - struct s_tag* s_next; -@} g_an_s; - -typedef struct s_tag s_typedef; -@end example - -The structure tag has an @code{N_LSYM} stab type because, like the -enumeration, the symbol has file scope. Like the enumeration, the -symbol descriptor is @samp{T}, for enumeration, structure, or tag type. -The type descriptor @samp{s} following the @samp{16=} of the type -definition narrows the symbol type to structure. - -Following the @samp{s} type descriptor is the number of bytes the -structure occupies, followed by a description of each structure element. -The structure element descriptions are of the form -@samp{@var{name}:@var{type}, @var{bit offset from the start of the -struct}, @var{number of bits in the element}}. - -@c FIXME: phony line break. Can probably be fixed by using an example -@c with fewer fields. -@example -# @r{128 is N_LSYM} -.stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; - s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 -@end example - -In this example, the first two structure elements are previously defined -types. For these, the type following the @samp{@var{name}:} part of the -element description is a simple type reference. The other two structure -elements are new types. In this case there is a type definition -embedded after the @samp{@var{name}:}. The type definition for the -array element looks just like a type definition for a stand-alone array. -The @code{s_next} field is a pointer to the same kind of structure that -the field is an element of. So the definition of structure type 16 -contains a type definition for an element which is a pointer to type 16. - -If a field is a static member (this is a C@t{++} feature in which a single -variable appears to be a field of every structure of a given type) it -still starts out with the field name, a colon, and the type, but then -instead of a comma, bit position, comma, and bit size, there is a colon -followed by the name of the variable which each such field refers to. - -If the structure has methods (a C@t{++} feature), they follow the non-method -fields; see @ref{Cplusplus}. - -@node Typedefs -@section Giving a Type a Name - -@findex N_LSYM, for types -@findex C_DECL, for types -To give a type a name, use the @samp{t} symbol descriptor. The type -is specified by the type information (@pxref{String Field}) for the stab. -For example, - -@example -.stabs "s_typedef:t16",128,0,0,0 # @r{128 is N_LSYM} -@end example - -specifies that @code{s_typedef} refers to type number 16. Such stabs -have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF). (The Sun -documentation mentions using @code{N_GSYM} in some cases). - -If you are specifying the tag name for a structure, union, or -enumeration, use the @samp{T} symbol descriptor instead. I believe C is -the only language with this feature. - -If the type is an opaque type (I believe this is a Modula-2 feature), -AIX provides a type descriptor to specify it. The type descriptor is -@samp{o} and is followed by a name. I don't know what the name -means---is it always the same as the name of the type, or is this type -descriptor used with a nameless stab (@pxref{String Field})? There -optionally follows a comma followed by type information which defines -the type of this type. If omitted, a semicolon is used in place of the -comma and the type information, and the type is much like a generic -pointer type---it has a known size but little else about it is -specified. - -@node Unions -@section Unions - -@example -union u_tag @{ - int u_int; - float u_float; - char* u_char; -@} an_u; -@end example - -This code generates a stab for a union tag and a stab for a union -variable. Both use the @code{N_LSYM} stab type. If a union variable is -scoped locally to the procedure in which it is defined, its stab is -located immediately preceding the @code{N_LBRAC} for the procedure's block -start. - -The stab for the union tag, however, is located preceding the code for -the procedure in which it is defined. The stab type is @code{N_LSYM}. This -would seem to imply that the union type is file scope, like the struct -type @code{s_tag}. This is not true. The contents and position of the stab -for @code{u_type} do not convey any information about its procedure local -scope. - -@c FIXME: phony line break. Can probably be fixed by using an example -@c with fewer fields. -@smallexample -# @r{128 is N_LSYM} -.stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", - 128,0,0,0 -@end smallexample - -The symbol descriptor @samp{T}, following the @samp{name:} means that -the stab describes an enumeration, structure, or union tag. The type -descriptor @samp{u}, following the @samp{23=} of the type definition, -narrows it down to a union type definition. Following the @samp{u} is -the number of bytes in the union. After that is a list of union element -descriptions. Their format is @samp{@var{name}:@var{type}, @var{bit -offset into the union}, @var{number of bytes for the element};}. - -The stab for the union variable is: - -@example -.stabs "an_u:23",128,0,0,-20 # @r{128 is N_LSYM} -@end example - -@samp{-20} specifies where the variable is stored (@pxref{Stack -Variables}). - -@node Function Types -@section Function Types - -Various types can be defined for function variables. These types are -not used in defining functions (@pxref{Procedures}); they are used for -things like pointers to functions. - -The simple, traditional, type is type descriptor @samp{f} is followed by -type information for the return type of the function, followed by a -semicolon. - -This does not deal with functions for which the number and types of the -parameters are part of the type, as in Modula-2 or ANSI C. AIX provides -extensions to specify these, using the @samp{f}, @samp{F}, @samp{p}, and -@samp{R} type descriptors. - -First comes the type descriptor. If it is @samp{f} or @samp{F}, this -type involves a function rather than a procedure, and the type -information for the return type of the function follows, followed by a -comma. Then comes the number of parameters to the function and a -semicolon. Then, for each parameter, there is the name of the parameter -followed by a colon (this is only present for type descriptors @samp{R} -and @samp{F} which represent Pascal function or procedure parameters), -type information for the parameter, a comma, 0 if passed by reference or -1 if passed by value, and a semicolon. The type definition ends with a -semicolon. - -For example, this variable definition: - -@example -int (*g_pf)(); -@end example - -@noindent -generates the following code: - -@example -.stabs "g_pf:G24=*25=f1",32,0,0,0 - .common _g_pf,4,"bss" -@end example - -The variable defines a new type, 24, which is a pointer to another new -type, 25, which is a function returning @code{int}. - -@node Macro define and undefine -@chapter Representation of #define and #undef - -This section describes the stabs support for macro define and undefine -information, supported on some systems. (e.g., with @option{-g3} -@option{-gstabs} when using GCC). - -A @code{#define @var{macro-name} @var{macro-body}} is represented with -an @code{N_MAC_DEFINE} stab with a string field of -@code{@var{macro-name} @var{macro-body}}. -@findex N_MAC_DEFINE - -An @code{#undef @var{macro-name}} is represented with an -@code{N_MAC_UNDEF} stabs with a string field of simply -@code{@var{macro-name}}. -@findex N_MAC_UNDEF - -For both @code{N_MAC_DEFINE} and @code{N_MAC_UNDEF}, the desc field is -the line number within the file where the corresponding @code{#define} -or @code{#undef} occurred. - -For example, the following C code: - -@example - #define NONE 42 - #define TWO(a, b) (a + (a) + 2 * b) - #define ONE(c) (c + 19) - - main(int argc, char *argv[]) - @{ - func(NONE, TWO(10, 11)); - func(NONE, ONE(23)); - - #undef ONE - #define ONE(c) (c + 23) - - func(NONE, ONE(-23)); - - return (0); - @} - - int global; - - func(int arg1, int arg2) - @{ - global = arg1 + arg2; - @} -@end example - -@noindent -produces the following stabs (as well as many others): - -@example - .stabs "NONE 42",54,0,1,0 - .stabs "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0 - .stabs "ONE(c) (c + 19)",54,0,3,0 - .stabs "ONE",58,0,10,0 - .stabs "ONE(c) (c + 23)",54,0,11,0 -@end example - -@noindent -NOTE: In the above example, @code{54} is @code{N_MAC_DEFINE} and -@code{58} is @code{N_MAC_UNDEF}. - -@node Symbol Tables -@chapter Symbol Information in Symbol Tables - -This chapter describes the format of symbol table entries -and how stab assembler directives map to them. It also describes the -transformations that the assembler and linker make on data from stabs. - -@menu -* Symbol Table Format:: -* Transformations On Symbol Tables:: -@end menu - -@node Symbol Table Format -@section Symbol Table Format - -Each time the assembler encounters a stab directive, it puts -each field of the stab into a corresponding field in a symbol table -entry of its output file. If the stab contains a string field, the -symbol table entry for that stab points to a string table entry -containing the string data from the stab. Assembler labels become -relocatable addresses. Symbol table entries in a.out have the format: - -@c FIXME: should refer to external, not internal. -@example -struct internal_nlist @{ - unsigned long n_strx; /* index into string table of name */ - unsigned char n_type; /* type of symbol */ - unsigned char n_other; /* misc info (usually empty) */ - unsigned short n_desc; /* description field */ - bfd_vma n_value; /* value of symbol */ -@}; -@end example - -If the stab has a string, the @code{n_strx} field holds the offset in -bytes of the string within the string table. The string is terminated -by a NUL character. If the stab lacks a string (for example, it was -produced by a @code{.stabn} or @code{.stabd} directive), the -@code{n_strx} field is zero. - -Symbol table entries with @code{n_type} field values greater than 0x1f -originated as stabs generated by the compiler (with one random -exception). The other entries were placed in the symbol table of the -executable by the assembler or the linker. - -@node Transformations On Symbol Tables -@section Transformations on Symbol Tables - -The linker concatenates object files and does fixups of externally -defined symbols. - -You can see the transformations made on stab data by the assembler and -linker by examining the symbol table after each pass of the build. To -do this, use @samp{nm -ap}, which dumps the symbol table, including -debugging information, unsorted. For stab entries the columns are: -@var{value}, @var{other}, @var{desc}, @var{type}, @var{string}. For -assembler and linker symbols, the columns are: @var{value}, @var{type}, -@var{string}. - -The low 5 bits of the stab type tell the linker how to relocate the -value of the stab. Thus for stab types like @code{N_RSYM} and -@code{N_LSYM}, where the value is an offset or a register number, the -low 5 bits are @code{N_ABS}, which tells the linker not to relocate the -value. - -Where the value of a stab contains an assembly language label, -it is transformed by each build step. The assembler turns it into a -relocatable address and the linker turns it into an absolute address. - -@menu -* Transformations On Static Variables:: -* Transformations On Global Variables:: -* Stab Section Transformations:: For some object file formats, - things are a bit different. -@end menu - -@node Transformations On Static Variables -@subsection Transformations on Static Variables - -This source line defines a static variable at file scope: - -@example -static int s_g_repeat -@end example - -@noindent -The following stab describes the symbol: - -@example -.stabs "s_g_repeat:S1",38,0,0,_s_g_repeat -@end example - -@noindent -The assembler transforms the stab into this symbol table entry in the -@file{.o} file. The location is expressed as a data segment offset. - -@example -00000084 - 00 0000 STSYM s_g_repeat:S1 -@end example - -@noindent -In the symbol table entry from the executable, the linker has made the -relocatable address absolute. - -@example -0000e00c - 00 0000 STSYM s_g_repeat:S1 -@end example - -@node Transformations On Global Variables -@subsection Transformations on Global Variables - -Stabs for global variables do not contain location information. In -this case, the debugger finds location information in the assembler or -linker symbol table entry describing the variable. The source line: - -@example -char g_foo = 'c'; -@end example - -@noindent -generates the stab: - -@example -.stabs "g_foo:G2",32,0,0,0 -@end example - -The variable is represented by two symbol table entries in the object -file (see below). The first one originated as a stab. The second one -is an external symbol. The upper case @samp{D} signifies that the -@code{n_type} field of the symbol table contains 7, @code{N_DATA} with -local linkage. The stab's value is zero since the value is not used for -@code{N_GSYM} stabs. The value of the linker symbol is the relocatable -address corresponding to the variable. - -@example -00000000 - 00 0000 GSYM g_foo:G2 -00000080 D _g_foo -@end example - -@noindent -These entries as transformed by the linker. The linker symbol table -entry now holds an absolute address: - -@example -00000000 - 00 0000 GSYM g_foo:G2 -@dots{} -0000e008 D _g_foo -@end example - -@node Stab Section Transformations -@subsection Transformations of Stabs in separate sections - -For object file formats using stabs in separate sections (@pxref{Stab -Sections}), use @code{objdump --stabs} instead of @code{nm} to show the -stabs in an object or executable file. @code{objdump} is a GNU utility; -Sun does not provide any equivalent. - -The following example is for a stab whose value is an address is -relative to the compilation unit (@pxref{ELF Linker Relocation}). For -example, if the source line - -@example -static int ld = 5; -@end example - -appears within a function, then the assembly language output from the -compiler contains: - -@example -.Ddata.data: -@dots{} - .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # @r{0x26 is N_STSYM} -@dots{} -.L18: - .align 4 - .word 0x5 -@end example - -Because the value is formed by subtracting one symbol from another, the -value is absolute, not relocatable, and so the object file contains - -@example -Symnum n_type n_othr n_desc n_value n_strx String -31 STSYM 0 4 00000004 680 ld:V(0,3) -@end example - -without any relocations, and the executable file also contains - -@example -Symnum n_type n_othr n_desc n_value n_strx String -31 STSYM 0 4 00000004 680 ld:V(0,3) -@end example - -@node Cplusplus -@chapter GNU C@t{++} Stabs - -@menu -* Class Names:: C++ class names are both tags and typedefs. -* Nested Symbols:: C++ symbol names can be within other types. -* Basic Cplusplus Types:: -* Simple Classes:: -* Class Instance:: -* Methods:: Method definition -* Method Type Descriptor:: The @samp{#} type descriptor -* Member Type Descriptor:: The @samp{@@} type descriptor -* Protections:: -* Method Modifiers:: -* Virtual Methods:: -* Inheritance:: -* Virtual Base Classes:: -* Static Members:: -@end menu - -@node Class Names -@section C@t{++} Class Names - -In C@t{++}, a class name which is declared with @code{class}, @code{struct}, -or @code{union}, is not only a tag, as in C, but also a type name. Thus -there should be stabs with both @samp{t} and @samp{T} symbol descriptors -(@pxref{Typedefs}). - -To save space, there is a special abbreviation for this case. If the -@samp{T} symbol descriptor is followed by @samp{t}, then the stab -defines both a type name and a tag. - -For example, the C@t{++} code - -@example -struct foo @{int x;@}; -@end example - -can be represented as either - -@example -.stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # @r{128 is N_LSYM} -.stabs "foo:t19",128,0,0,0 -@end example - -or - -@example -.stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 -@end example - -@node Nested Symbols -@section Defining a Symbol Within Another Type - -In C@t{++}, a symbol (such as a type name) can be defined within another type. -@c FIXME: Needs example. - -In stabs, this is sometimes represented by making the name of a symbol -which contains @samp{::}. Such a pair of colons does not end the name -of the symbol, the way a single colon would (@pxref{String Field}). I'm -not sure how consistently used or well thought out this mechanism is. -So that a pair of colons in this position always has this meaning, -@samp{:} cannot be used as a symbol descriptor. - -For example, if the string for a stab is @samp{foo::bar::baz:t5=*6}, -then @code{foo::bar::baz} is the name of the symbol, @samp{t} is the -symbol descriptor, and @samp{5=*6} is the type information. - -@node Basic Cplusplus Types -@section Basic Types For C@t{++} - -<< the examples that follow are based on a01.C >> - - -C@t{++} adds two more builtin types to the set defined for C. These are -the unknown type and the vtable record type. The unknown type, type -16, is defined in terms of itself like the void type. - -The vtable record type, type 17, is defined as a structure type and -then as a structure tag. The structure has four fields: delta, index, -pfn, and delta2. pfn is the function pointer. - -<< In boilerplate $vtbl_ptr_type, what are the fields delta, -index, and delta2 used for? >> - -This basic type is present in all C@t{++} programs even if there are no -virtual methods defined. - -@display -.stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) - elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); - elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); - elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), - bit_offset(32),field_bits(32); - elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" - N_LSYM, NIL, NIL -@end display - -@smallexample -.stabs "$vtbl_ptr_type:t17=s8 - delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" - ,128,0,0,0 -@end smallexample - -@display -.stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL -@end display - -@example -.stabs "$vtbl_ptr_type:T17",128,0,0,0 -@end example - -@node Simple Classes -@section Simple Class Definition - -The stabs describing C@t{++} language features are an extension of the -stabs describing C. Stabs representing C@t{++} class types elaborate -extensively on the stab format used to describe structure types in C. -Stabs representing class type variables look just like stabs -representing C language variables. - -Consider the following very simple class definition. - -@example -class baseA @{ -public: - int Adat; - int Ameth(int in, char other); -@}; -@end example - -The class @code{baseA} is represented by two stabs. The first stab describes -the class as a structure type. The second stab describes a structure -tag of the class type. Both stabs are of stab type @code{N_LSYM}. Since the -stab is not located between an @code{N_FUN} and an @code{N_LBRAC} stab this indicates -that the class is defined at file scope. If it were, then the @code{N_LSYM} -would signify a local variable. - -A stab describing a C@t{++} class type is similar in format to a stab -describing a C struct, with each class member shown as a field in the -structure. The part of the struct format describing fields is -expanded to include extra information relevant to C@t{++} class members. -In addition, if the class has multiple base classes or virtual -functions the struct format outside of the field parts is also -augmented. - -In this simple example the field part of the C@t{++} class stab -representing member data looks just like the field part of a C struct -stab. The section on protections describes how its format is -sometimes extended for member data. - -The field part of a C@t{++} class stab representing a member function -differs substantially from the field part of a C struct stab. It -still begins with @samp{name:} but then goes on to define a new type number -for the member function, describe its return type, its argument types, -its protection level, any qualifiers applied to the method definition, -and whether the method is virtual or not. If the method is virtual -then the method description goes on to give the vtable index of the -method, and the type number of the first base class defining the -method. - -When the field name is a method name it is followed by two colons rather -than one. This is followed by a new type definition for the method. -This is a number followed by an equal sign and the type of the method. -Normally this will be a type declared using the @samp{#} type -descriptor; see @ref{Method Type Descriptor}; static member functions -are declared using the @samp{f} type descriptor instead; see -@ref{Function Types}. - -The format of an overloaded operator method name differs from that of -other methods. It is @samp{op$::@var{operator-name}.} where -@var{operator-name} is the operator name such as @samp{+} or @samp{+=}. -The name ends with a period, and any characters except the period can -occur in the @var{operator-name} string. - -The next part of the method description represents the arguments to the -method, preceded by a colon and ending with a semi-colon. The types of -the arguments are expressed in the same way argument types are expressed -in C@t{++} name mangling. In this example an @code{int} and a @code{char} -map to @samp{ic}. - -This is followed by a number, a letter, and an asterisk or period, -followed by another semicolon. The number indicates the protections -that apply to the member function. Here the 2 means public. The -letter encodes any qualifier applied to the method definition. In -this case, @samp{A} means that it is a normal function definition. The dot -shows that the method is not virtual. The sections that follow -elaborate further on these fields and describe the additional -information present for virtual methods. - - -@display -.stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) - field_name(Adat):type(int),bit_offset(0),field_bits(32); - - method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); - :arg_types(int char); - protection(public)qualifier(normal)virtual(no);;" - N_LSYM,NIL,NIL,NIL -@end display - -@smallexample -.stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 - -.stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL - -.stabs "baseA:T20",128,0,0,0 -@end smallexample - -@node Class Instance -@section Class Instance - -As shown above, describing even a simple C@t{++} class definition is -accomplished by massively extending the stab format used in C to -describe structure types. However, once the class is defined, C stabs -with no modifications can be used to describe class instances. The -following source: - -@example -main () @{ - baseA AbaseA; -@} -@end example - -@noindent -yields the following stab describing the class instance. It looks no -different from a standard C stab describing a local variable. - -@display -.stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset -@end display - -@example -.stabs "AbaseA:20",128,0,0,-20 -@end example - -@node Methods -@section Method Definition - -The class definition shown above declares Ameth. The C@t{++} source below -defines Ameth: - -@example -int -baseA::Ameth(int in, char other) -@{ - return in; -@}; -@end example - - -This method definition yields three stabs following the code of the -method. One stab describes the method itself and following two describe -its parameters. Although there is only one formal argument all methods -have an implicit argument which is the @code{this} pointer. The @code{this} -pointer is a pointer to the object on which the method was called. Note -that the method name is mangled to encode the class name and argument -types. Name mangling is described in the @sc{arm} (@cite{The Annotated -C++ Reference Manual}, by Ellis and Stroustrup, @sc{isbn} -0-201-51459-1); @file{gpcompare.texi} in Cygnus GCC distributions -describes the differences between GNU mangling and @sc{arm} -mangling. -@c FIXME: Use @xref, especially if this is generally installed in the -@c info tree. -@c FIXME: This information should be in a net release, either of GCC or -@c GDB. But gpcompare.texi doesn't seem to be in the FSF GCC. - -@example -.stabs "name:symbol_descriptor(global function)return_type(int)", - N_FUN, NIL, NIL, code_addr_of_method_start - -.stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic -@end example - -Here is the stab for the @code{this} pointer implicit argument. The -name of the @code{this} pointer is always @code{this}. Type 19, the -@code{this} pointer is defined as a pointer to type 20, @code{baseA}, -but a stab defining @code{baseA} has not yet been emitted. Since the -compiler knows it will be emitted shortly, here it just outputs a cross -reference to the undefined symbol, by prefixing the symbol name with -@samp{xs}. - -@example -.stabs "name:sym_desc(register param)type_def(19)= - type_desc(ptr to)type_ref(baseA)= - type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number - -.stabs "this:P19=*20=xsbaseA:",64,0,0,8 -@end example - -The stab for the explicit integer argument looks just like a parameter -to a C function. The last field of the stab is the offset from the -argument pointer, which in most systems is the same as the frame -pointer. - -@example -.stabs "name:sym_desc(value parameter)type_ref(int)", - N_PSYM,NIL,NIL,offset_from_arg_ptr - -.stabs "in:p1",160,0,0,72 -@end example - -<< The examples that follow are based on A1.C >> - -@node Method Type Descriptor -@section The @samp{#} Type Descriptor - -This is used to describe a class method. This is a function which takes -an extra argument as its first argument, for the @code{this} pointer. - -If the @samp{#} is immediately followed by another @samp{#}, the second -one will be followed by the return type and a semicolon. The class and -argument types are not specified, and must be determined by demangling -the name of the method if it is available. - -Otherwise, the single @samp{#} is followed by the class type, a comma, -the return type, a comma, and zero or more parameter types separated by -commas. The list of arguments is terminated by a semicolon. In the -debugging output generated by gcc, a final argument type of @code{void} -indicates a method which does not take a variable number of arguments. -If the final argument type of @code{void} does not appear, the method -was declared with an ellipsis. - -Note that although such a type will normally be used to describe fields -in structures, unions, or classes, for at least some versions of the -compiler it can also be used in other contexts. - -@node Member Type Descriptor -@section The @samp{@@} Type Descriptor - -The @samp{@@} type descriptor is used for a -pointer-to-non-static-member-data type. It is followed -by type information for the class (or union), a comma, and type -information for the member data. - -The following C@t{++} source: - -@smallexample -typedef int A::*int_in_a; -@end smallexample - -generates the following stab: - -@smallexample -.stabs "int_in_a:t20=21=@@19,1",128,0,0,0 -@end smallexample - -Note that there is a conflict between this and type attributes -(@pxref{String Field}); both use type descriptor @samp{@@}. -Fortunately, the @samp{@@} type descriptor used in this C@t{++} sense always -will be followed by a digit, @samp{(}, or @samp{-}, and type attributes -never start with those things. - -@node Protections -@section Protections - -In the simple class definition shown above all member data and -functions were publicly accessible. The example that follows -contrasts public, protected and privately accessible fields and shows -how these protections are encoded in C@t{++} stabs. - -If the character following the @samp{@var{field-name}:} part of the -string is @samp{/}, then the next character is the visibility. @samp{0} -means private, @samp{1} means protected, and @samp{2} means public. -Debuggers should ignore visibility characters they do not recognize, and -assume a reasonable default (such as public) (GDB 4.11 does not, but -this should be fixed in the next GDB release). If no visibility is -specified the field is public. The visibility @samp{9} means that the -field has been optimized out and is public (there is no way to specify -an optimized out field with a private or protected visibility). -Visibility @samp{9} is not supported by GDB 4.11; this should be fixed -in the next GDB release. - -The following C@t{++} source: - -@example -class vis @{ -private: - int priv; -protected: - char prot; -public: - float pub; -@}; -@end example - -@noindent -generates the following stab: - -@example -# @r{128 is N_LSYM} -.stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 -@end example - -@samp{vis:T19=s12} indicates that type number 19 is a 12 byte structure -named @code{vis} The @code{priv} field has public visibility -(@samp{/0}), type int (@samp{1}), and offset and size @samp{,0,32;}. -The @code{prot} field has protected visibility (@samp{/1}), type char -(@samp{2}) and offset and size @samp{,32,8;}. The @code{pub} field has -type float (@samp{12}), and offset and size @samp{,64,32;}. - -Protections for member functions are signified by one digit embedded in -the field part of the stab describing the method. The digit is 0 if -private, 1 if protected and 2 if public. Consider the C@t{++} class -definition below: - -@example -class all_methods @{ -private: - int priv_meth(int in)@{return in;@}; -protected: - char protMeth(char in)@{return in;@}; -public: - float pubMeth(float in)@{return in;@}; -@}; -@end example - -It generates the following stab. The digit in question is to the left -of an @samp{A} in each case. Notice also that in this case two symbol -descriptors apply to the class name struct tag and struct type. - -@display -.stabs "class_name:sym_desc(struct tag&type)type_def(21)= - sym_desc(struct)struct_bytes(1) - meth_name::type_def(22)=sym_desc(method)returning(int); - :args(int);protection(private)modifier(normal)virtual(no); - meth_name::type_def(23)=sym_desc(method)returning(char); - :args(char);protection(protected)modifier(normal)virtual(no); - meth_name::type_def(24)=sym_desc(method)returning(float); - :args(float);protection(public)modifier(normal)virtual(no);;", - N_LSYM,NIL,NIL,NIL -@end display - -@smallexample -.stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.; - pubMeth::24=##12;:f;2A.;;",128,0,0,0 -@end smallexample - -@node Method Modifiers -@section Method Modifiers (@code{const}, @code{volatile}, @code{const volatile}) - -<< based on a6.C >> - -In the class example described above all the methods have the normal -modifier. This method modifier information is located just after the -protection information for the method. This field has four possible -character values. Normal methods use @samp{A}, const methods use -@samp{B}, volatile methods use @samp{C}, and const volatile methods use -@samp{D}. Consider the class definition below: - -@example -class A @{ -public: - int ConstMeth (int arg) const @{ return arg; @}; - char VolatileMeth (char arg) volatile @{ return arg; @}; - float ConstVolMeth (float arg) const volatile @{return arg; @}; -@}; -@end example - -This class is described by the following stab: - -@display -.stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1) - meth_name(ConstMeth)::type_def(21)sym_desc(method) - returning(int);:arg(int);protection(public)modifier(const)virtual(no); - meth_name(VolatileMeth)::type_def(22)=sym_desc(method) - returning(char);:arg(char);protection(public)modifier(volatile)virt(no) - meth_name(ConstVolMeth)::type_def(23)=sym_desc(method) - returning(float);:arg(float);protection(public)modifier(const volatile) - virtual(no);;", @dots{} -@end display - -@example -.stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.; - ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 -@end example - -@node Virtual Methods -@section Virtual Methods - -<< The following examples are based on a4.C >> - -The presence of virtual methods in a class definition adds additional -data to the class description. The extra data is appended to the -description of the virtual method and to the end of the class -description. Consider the class definition below: - -@example -class A @{ -public: - int Adat; - virtual int A_virt (int arg) @{ return arg; @}; -@}; -@end example - -This results in the stab below describing class A. It defines a new -type (20) which is an 8 byte structure. The first field of the class -struct is @samp{Adat}, an integer, starting at structure offset 0 and -occupying 32 bits. - -The second field in the class struct is not explicitly defined by the -C@t{++} class definition but is implied by the fact that the class -contains a virtual method. This field is the vtable pointer. The -name of the vtable pointer field starts with @samp{$vf} and continues with a -type reference to the class it is part of. In this example the type -reference for class A is 20 so the name of its vtable pointer field is -@samp{$vf20}, followed by the usual colon. - -Next there is a type definition for the vtable pointer type (21). -This is in turn defined as a pointer to another new type (22). - -Type 22 is the vtable itself, which is defined as an array, indexed by -a range of integers between 0 and 1, and whose elements are of type -17. Type 17 was the vtable record type defined by the boilerplate C@t{++} -type definitions, as shown earlier. - -The bit offset of the vtable pointer field is 32. The number of bits -in the field are not specified when the field is a vtable pointer. - -Next is the method definition for the virtual member function @code{A_virt}. -Its description starts out using the same format as the non-virtual -member functions described above, except instead of a dot after the -@samp{A} there is an asterisk, indicating that the function is virtual. -Since is is virtual some addition information is appended to the end -of the method description. - -The first number represents the vtable index of the method. This is a -32 bit unsigned number with the high bit set, followed by a -semi-colon. - -The second number is a type reference to the first base class in the -inheritance hierarchy defining the virtual member function. In this -case the class stab describes a base class so the virtual function is -not overriding any other definition of the method. Therefore the -reference is to the type number of the class that the stab is -describing (20). - -This is followed by three semi-colons. One marks the end of the -current sub-section, one marks the end of the method field, and the -third marks the end of the struct definition. - -For classes containing virtual functions the very last section of the -string part of the stab holds a type reference to the first base -class. This is preceded by @samp{~%} and followed by a final semi-colon. - -@display -.stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8) - field_name(Adat):type_ref(int),bit_offset(0),field_bits(32); - field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)= - sym_desc(array)index_type_ref(range of int from 0 to 1); - elem_type_ref(vtbl elem type), - bit_offset(32); - meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int); - :arg_type(int),protection(public)normal(yes)virtual(yes) - vtable_index(1);class_first_defining(A);;;~%first_base(A);", - N_LSYM,NIL,NIL,NIL -@end display - -@c FIXME: bogus line break. -@example -.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; - A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 -@end example - -@node Inheritance -@section Inheritance - -Stabs describing C@t{++} derived classes include additional sections that -describe the inheritance hierarchy of the class. A derived class stab -also encodes the number of base classes. For each base class it tells -if the base class is virtual or not, and if the inheritance is private -or public. It also gives the offset into the object of the portion of -the object corresponding to each base class. - -This additional information is embedded in the class stab following the -number of bytes in the struct. First the number of base classes -appears bracketed by an exclamation point and a comma. - -Then for each base type there repeats a series: a virtual character, a -visibility character, a number, a comma, another number, and a -semi-colon. - -The virtual character is @samp{1} if the base class is virtual and -@samp{0} if not. The visibility character is @samp{2} if the derivation -is public, @samp{1} if it is protected, and @samp{0} if it is private. -Debuggers should ignore virtual or visibility characters they do not -recognize, and assume a reasonable default (such as public and -non-virtual) (GDB 4.11 does not, but this should be fixed in the next -GDB release). - -The number following the virtual and visibility characters is the offset -from the start of the object to the part of the object pertaining to the -base class. - -After the comma, the second number is a type_descriptor for the base -type. Finally a semi-colon ends the series, which repeats for each -base class. - -The source below defines three base classes @code{A}, @code{B}, and -@code{C} and the derived class @code{D}. - - -@example -class A @{ -public: - int Adat; - virtual int A_virt (int arg) @{ return arg; @}; -@}; - -class B @{ -public: - int B_dat; - virtual int B_virt (int arg) @{return arg; @}; -@}; - -class C @{ -public: - int Cdat; - virtual int C_virt (int arg) @{return arg; @}; -@}; - -class D : A, virtual B, public C @{ -public: - int Ddat; - virtual int A_virt (int arg ) @{ return arg+1; @}; - virtual int B_virt (int arg) @{ return arg+2; @}; - virtual int C_virt (int arg) @{ return arg+3; @}; - virtual int D_virt (int arg) @{ return arg; @}; -@}; -@end example - -Class stabs similar to the ones described earlier are generated for -each base class. - -@c FIXME!!! the linebreaks in the following example probably make the -@c examples literally unusable, but I don't know any other way to get -@c them on the page. -@c One solution would be to put some of the type definitions into -@c separate stabs, even if that's not exactly what the compiler actually -@c emits. -@smallexample -.stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; - A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 - -.stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1; - :i;2A*-2147483647;25;;;~%25;",128,0,0,0 - -.stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1; - :i;2A*-2147483647;28;;;~%28;",128,0,0,0 -@end smallexample - -In the stab describing derived class @code{D} below, the information about -the derivation of this class is encoded as follows. - -@display -.stabs "derived_class_name:symbol_descriptors(struct tag&type)= - type_descriptor(struct)struct_bytes(32)!num_bases(3), - base_virtual(no)inheritance_public(no)base_offset(0), - base_class_type_ref(A); - base_virtual(yes)inheritance_public(no)base_offset(NIL), - base_class_type_ref(B); - base_virtual(no)inheritance_public(yes)base_offset(64), - base_class_type_ref(C); @dots{} -@end display - -@c FIXME! fake linebreaks. -@smallexample -.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat: - 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt: - :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647; - 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 -@end smallexample - -@node Virtual Base Classes -@section Virtual Base Classes - -A derived class object consists of a concatenation in memory of the data -areas defined by each base class, starting with the leftmost and ending -with the rightmost in the list of base classes. The exception to this -rule is for virtual inheritance. In the example above, class @code{D} -inherits virtually from base class @code{B}. This means that an -instance of a @code{D} object will not contain its own @code{B} part but -merely a pointer to a @code{B} part, known as a virtual base pointer. - -In a derived class stab, the base offset part of the derivation -information, described above, shows how the base class parts are -ordered. The base offset for a virtual base class is always given as 0. -Notice that the base offset for @code{B} is given as 0 even though -@code{B} is not the first base class. The first base class @code{A} -starts at offset 0. - -The field information part of the stab for class @code{D} describes the field -which is the pointer to the virtual base class @code{B}. The vbase pointer -name is @samp{$vb} followed by a type reference to the virtual base class. -Since the type id for @code{B} in this example is 25, the vbase pointer name -is @samp{$vb25}. - -@c FIXME!! fake linebreaks below -@smallexample -.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1, - 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i; - 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt: - :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 -@end smallexample - -Following the name and a semicolon is a type reference describing the -type of the virtual base class pointer, in this case 24. Type 24 was -defined earlier as the type of the @code{B} class @code{this} pointer. The -@code{this} pointer for a class is a pointer to the class type. - -@example -.stabs "this:P24=*25=xsB:",64,0,0,8 -@end example - -Finally the field offset part of the vbase pointer field description -shows that the vbase pointer is the first field in the @code{D} object, -before any data fields defined by the class. The layout of a @code{D} -class object is a follows, @code{Adat} at 0, the vtable pointer for -@code{A} at 32, @code{Cdat} at 64, the vtable pointer for C at 96, the -virtual base pointer for @code{B} at 128, and @code{Ddat} at 160. - - -@node Static Members -@section Static Members - -The data area for a class is a concatenation of the space used by the -data members of the class. If the class has virtual methods, a vtable -pointer follows the class data. The field offset part of each field -description in the class stab shows this ordering. - -<< How is this reflected in stabs? See Cygnus bug #677 for some info. >> - -@node Stab Types -@appendix Table of Stab Types - -The following are all the possible values for the stab type field, for -a.out files, in numeric order. This does not apply to XCOFF, but -it does apply to stabs in sections (@pxref{Stab Sections}). Stabs in -ECOFF use these values but add 0x8f300 to distinguish them from non-stab -symbols. - -The symbolic names are defined in the file @file{include/aout/stabs.def}. - -@menu -* Non-Stab Symbol Types:: Types from 0 to 0x1f -* Stab Symbol Types:: Types from 0x20 to 0xff -@end menu - -@node Non-Stab Symbol Types -@appendixsec Non-Stab Symbol Types - -The following types are used by the linker and assembler, not by stab -directives. Since this document does not attempt to describe aspects of -object file format other than the debugging format, no details are -given. - -@c Try to get most of these to fit on a single line. -@iftex -@tableindent=1.5in -@end iftex - -@table @code -@item 0x0 N_UNDF -Undefined symbol - -@item 0x2 N_ABS -File scope absolute symbol - -@item 0x3 N_ABS | N_EXT -External absolute symbol - -@item 0x4 N_TEXT -File scope text symbol - -@item 0x5 N_TEXT | N_EXT -External text symbol - -@item 0x6 N_DATA -File scope data symbol - -@item 0x7 N_DATA | N_EXT -External data symbol - -@item 0x8 N_BSS -File scope BSS symbol - -@item 0x9 N_BSS | N_EXT -External BSS symbol - -@item 0x0c N_FN_SEQ -Same as @code{N_FN}, for Sequent compilers - -@item 0x0a N_INDR -Symbol is indirected to another symbol - -@item 0x12 N_COMM -Common---visible after shared library dynamic link - -@item 0x14 N_SETA -@itemx 0x15 N_SETA | N_EXT -Absolute set element - -@item 0x16 N_SETT -@itemx 0x17 N_SETT | N_EXT -Text segment set element - -@item 0x18 N_SETD -@itemx 0x19 N_SETD | N_EXT -Data segment set element - -@item 0x1a N_SETB -@itemx 0x1b N_SETB | N_EXT -BSS segment set element - -@item 0x1c N_SETV -@itemx 0x1d N_SETV | N_EXT -Pointer to set vector - -@item 0x1e N_WARNING -Print a warning message during linking - -@item 0x1f N_FN -File name of a @file{.o} file -@end table - -@node Stab Symbol Types -@appendixsec Stab Symbol Types - -The following symbol types indicate that this is a stab. This is the -full list of stab numbers, including stab types that are used in -languages other than C. - -@table @code -@item 0x20 N_GSYM -Global symbol; see @ref{Global Variables}. - -@item 0x22 N_FNAME -Function name (for BSD Fortran); see @ref{Procedures}. - -@item 0x24 N_FUN -Function name (@pxref{Procedures}) or text segment variable -(@pxref{Statics}). - -@item 0x26 N_STSYM -Data segment file-scope variable; see @ref{Statics}. - -@item 0x28 N_LCSYM -BSS segment file-scope variable; see @ref{Statics}. - -@item 0x2a N_MAIN -Name of main routine; see @ref{Main Program}. - -@item 0x2c N_ROSYM -Variable in @code{.rodata} section; see @ref{Statics}. - -@item 0x30 N_PC -Global symbol (for Pascal); see @ref{N_PC}. - -@item 0x32 N_NSYMS -Number of symbols (according to Ultrix V4.0); see @ref{N_NSYMS}. - -@item 0x34 N_NOMAP -No DST map; see @ref{N_NOMAP}. - -@item 0x36 N_MAC_DEFINE -Name and body of a @code{#define}d macro; see @ref{Macro define and undefine}. - -@c FIXME: describe this solaris feature in the body of the text (see -@c comments in include/aout/stab.def). -@item 0x38 N_OBJ -Object file (Solaris2). - -@item 0x3a N_MAC_UNDEF -Name of an @code{#undef}ed macro; see @ref{Macro define and undefine}. - -@c See include/aout/stab.def for (a little) more info. -@item 0x3c N_OPT -Debugger options (Solaris2). - -@item 0x40 N_RSYM -Register variable; see @ref{Register Variables}. - -@item 0x42 N_M2C -Modula-2 compilation unit; see @ref{N_M2C}. - -@item 0x44 N_SLINE -Line number in text segment; see @ref{Line Numbers}. - -@item 0x46 N_DSLINE -Line number in data segment; see @ref{Line Numbers}. - -@item 0x48 N_BSLINE -Line number in bss segment; see @ref{Line Numbers}. - -@item 0x48 N_BROWS -Sun source code browser, path to @file{.cb} file; see @ref{N_BROWS}. - -@item 0x4a N_DEFD -GNU Modula2 definition module dependency; see @ref{N_DEFD}. - -@item 0x4c N_FLINE -Function start/body/end line numbers (Solaris2). - -@item 0x50 N_EHDECL -GNU C@t{++} exception variable; see @ref{N_EHDECL}. - -@item 0x50 N_MOD2 -Modula2 info "for imc" (according to Ultrix V4.0); see @ref{N_MOD2}. - -@item 0x54 N_CATCH -GNU C@t{++} @code{catch} clause; see @ref{N_CATCH}. - -@item 0x60 N_SSYM -Structure of union element; see @ref{N_SSYM}. - -@item 0x62 N_ENDM -Last stab for module (Solaris2). - -@item 0x64 N_SO -Path and name of source file; see @ref{Source Files}. - -@item 0x80 N_LSYM -Stack variable (@pxref{Stack Variables}) or type (@pxref{Typedefs}). - -@item 0x82 N_BINCL -Beginning of an include file (Sun only); see @ref{Include Files}. - -@item 0x84 N_SOL -Name of include file; see @ref{Include Files}. - -@item 0xa0 N_PSYM -Parameter variable; see @ref{Parameters}. - -@item 0xa2 N_EINCL -End of an include file; see @ref{Include Files}. - -@item 0xa4 N_ENTRY -Alternate entry point; see @ref{Alternate Entry Points}. - -@item 0xc0 N_LBRAC -Beginning of a lexical block; see @ref{Block Structure}. - -@item 0xc2 N_EXCL -Place holder for a deleted include file; see @ref{Include Files}. - -@item 0xc4 N_SCOPE -Modula2 scope information (Sun linker); see @ref{N_SCOPE}. - -@item 0xe0 N_RBRAC -End of a lexical block; see @ref{Block Structure}. - -@item 0xe2 N_BCOMM -Begin named common block; see @ref{Common Blocks}. - -@item 0xe4 N_ECOMM -End named common block; see @ref{Common Blocks}. - -@item 0xe8 N_ECOML -Member of a common block; see @ref{Common Blocks}. - -@c FIXME: How does this really work? Move it to main body of document. -@item 0xea N_WITH -Pascal @code{with} statement: type,,0,0,offset (Solaris2). - -@item 0xf0 N_NBTEXT -Gould non-base registers; see @ref{Gould}. - -@item 0xf2 N_NBDATA -Gould non-base registers; see @ref{Gould}. - -@item 0xf4 N_NBBSS -Gould non-base registers; see @ref{Gould}. - -@item 0xf6 N_NBSTS -Gould non-base registers; see @ref{Gould}. - -@item 0xf8 N_NBLCS -Gould non-base registers; see @ref{Gould}. -@end table - -@c Restore the default table indent -@iftex -@tableindent=.8in -@end iftex - -@node Symbol Descriptors -@appendix Table of Symbol Descriptors - -The symbol descriptor is the character which follows the colon in many -stabs, and which tells what kind of stab it is. @xref{String Field}, -for more information about their use. - -@c Please keep this alphabetical -@table @code -@c In TeX, this looks great, digit is in italics. But makeinfo insists -@c on putting it in `', not realizing that @var should override @code. -@c I don't know of any way to make makeinfo do the right thing. Seems -@c like a makeinfo bug to me. -@item @var{digit} -@itemx ( -@itemx - -Variable on the stack; see @ref{Stack Variables}. - -@item : -C@t{++} nested symbol; see @xref{Nested Symbols}. - -@item a -Parameter passed by reference in register; see @ref{Reference Parameters}. - -@item b -Based variable; see @ref{Based Variables}. - -@item c -Constant; see @ref{Constants}. - -@item C -Conformant array bound (Pascal, maybe other languages); @ref{Conformant -Arrays}. Name of a caught exception (GNU C@t{++}). These can be -distinguished because the latter uses @code{N_CATCH} and the former uses -another symbol type. - -@item d -Floating point register variable; see @ref{Register Variables}. - -@item D -Parameter in floating point register; see @ref{Register Parameters}. - -@item f -File scope function; see @ref{Procedures}. - -@item F -Global function; see @ref{Procedures}. - -@item G -Global variable; see @ref{Global Variables}. - -@item i -@xref{Register Parameters}. - -@item I -Internal (nested) procedure; see @ref{Nested Procedures}. - -@item J -Internal (nested) function; see @ref{Nested Procedures}. - -@item L -Label name (documented by AIX, no further information known). - -@item m -Module; see @ref{Procedures}. - -@item p -Argument list parameter; see @ref{Parameters}. - -@item pP -@xref{Parameters}. - -@item pF -Fortran Function parameter; see @ref{Parameters}. - -@item P -Unfortunately, three separate meanings have been independently invented -for this symbol descriptor. At least the GNU and Sun uses can be -distinguished by the symbol type. Global Procedure (AIX) (symbol type -used unknown); see @ref{Procedures}. Register parameter (GNU) (symbol -type @code{N_PSYM}); see @ref{Parameters}. Prototype of function -referenced by this file (Sun @code{acc}) (symbol type @code{N_FUN}). - -@item Q -Static Procedure; see @ref{Procedures}. - -@item R -Register parameter; see @ref{Register Parameters}. - -@item r -Register variable; see @ref{Register Variables}. - -@item S -File scope variable; see @ref{Statics}. - -@item s -Local variable (OS9000). - -@item t -Type name; see @ref{Typedefs}. - -@item T -Enumeration, structure, or union tag; see @ref{Typedefs}. - -@item v -Parameter passed by reference; see @ref{Reference Parameters}. - -@item V -Procedure scope static variable; see @ref{Statics}. - -@item x -Conformant array; see @ref{Conformant Arrays}. - -@item X -Function return variable; see @ref{Parameters}. -@end table - -@node Type Descriptors -@appendix Table of Type Descriptors - -The type descriptor is the character which follows the type number and -an equals sign. It specifies what kind of type is being defined. -@xref{String Field}, for more information about their use. - -@table @code -@item @var{digit} -@itemx ( -Type reference; see @ref{String Field}. - -@item - -Reference to builtin type; see @ref{Negative Type Numbers}. - -@item # -Method (C@t{++}); see @ref{Method Type Descriptor}. - -@item * -Pointer; see @ref{Miscellaneous Types}. - -@item & -Reference (C@t{++}). - -@item @@ -Type Attributes (AIX); see @ref{String Field}. Member (class and variable) -type (GNU C@t{++}); see @ref{Member Type Descriptor}. - -@item a -Array; see @ref{Arrays}. - -@item A -Open array; see @ref{Arrays}. - -@item b -Pascal space type (AIX); see @ref{Miscellaneous Types}. Builtin integer -type (Sun); see @ref{Builtin Type Descriptors}. Const and volatile -qualified type (OS9000). - -@item B -Volatile-qualified type; see @ref{Miscellaneous Types}. - -@item c -Complex builtin type (AIX); see @ref{Builtin Type Descriptors}. -Const-qualified type (OS9000). - -@item C -COBOL Picture type. See AIX documentation for details. - -@item d -File type; see @ref{Miscellaneous Types}. - -@item D -N-dimensional dynamic array; see @ref{Arrays}. - -@item e -Enumeration type; see @ref{Enumerations}. - -@item E -N-dimensional subarray; see @ref{Arrays}. - -@item f -Function type; see @ref{Function Types}. - -@item F -Pascal function parameter; see @ref{Function Types} - -@item g -Builtin floating point type; see @ref{Builtin Type Descriptors}. - -@item G -COBOL Group. See AIX documentation for details. - -@item i -Imported type (AIX); see @ref{Cross-References}. Volatile-qualified -type (OS9000). - -@item k -Const-qualified type; see @ref{Miscellaneous Types}. - -@item K -COBOL File Descriptor. See AIX documentation for details. - -@item M -Multiple instance type; see @ref{Miscellaneous Types}. - -@item n -String type; see @ref{Strings}. - -@item N -Stringptr; see @ref{Strings}. - -@item o -Opaque type; see @ref{Typedefs}. - -@item p -Procedure; see @ref{Function Types}. - -@item P -Packed array; see @ref{Arrays}. - -@item r -Range type; see @ref{Subranges}. - -@item R -Builtin floating type; see @ref{Builtin Type Descriptors} (Sun). Pascal -subroutine parameter; see @ref{Function Types} (AIX). Detecting this -conflict is possible with careful parsing (hint: a Pascal subroutine -parameter type will always contain a comma, and a builtin type -descriptor never will). - -@item s -Structure type; see @ref{Structures}. - -@item S -Set type; see @ref{Miscellaneous Types}. - -@item u -Union; see @ref{Unions}. - -@item v -Variant record. This is a Pascal and Modula-2 feature which is like a -union within a struct in C. See AIX documentation for details. - -@item w -Wide character; see @ref{Builtin Type Descriptors}. - -@item x -Cross-reference; see @ref{Cross-References}. - -@item Y -Used by IBM's xlC C@t{++} compiler (for structures, I think). - -@item z -gstring; see @ref{Strings}. -@end table - -@node Expanded Reference -@appendix Expanded Reference by Stab Type - -@c FIXME: This appendix should go away; see N_PSYM or N_SO for an example. - -For a full list of stab types, and cross-references to where they are -described, see @ref{Stab Types}. This appendix just covers certain -stabs which are not yet described in the main body of this document; -eventually the information will all be in one place. - -Format of an entry: - -The first line is the symbol type (see @file{include/aout/stab.def}). - -The second line describes the language constructs the symbol type -represents. - -The third line is the stab format with the significant stab fields -named and the rest NIL. - -Subsequent lines expand upon the meaning and possible values for each -significant stab field. - -Finally, any further information. - -@menu -* N_PC:: Pascal global symbol -* N_NSYMS:: Number of symbols -* N_NOMAP:: No DST map -* N_M2C:: Modula-2 compilation unit -* N_BROWS:: Path to .cb file for Sun source code browser -* N_DEFD:: GNU Modula2 definition module dependency -* N_EHDECL:: GNU C++ exception variable -* N_MOD2:: Modula2 information "for imc" -* N_CATCH:: GNU C++ "catch" clause -* N_SSYM:: Structure or union element -* N_SCOPE:: Modula2 scope information (Sun only) -* Gould:: non-base register symbols used on Gould systems -* N_LENG:: Length of preceding entry -@end menu - -@node N_PC -@section N_PC - -@deffn @code{.stabs} N_PC -@findex N_PC -Global symbol (for Pascal). - -@example -"name" -> "symbol_name" <<?>> -value -> supposedly the line number (stab.def is skeptical) -@end example - -@display -@file{stabdump.c} says: - -global pascal symbol: name,,0,subtype,line -<< subtype? >> -@end display -@end deffn - -@node N_NSYMS -@section N_NSYMS - -@deffn @code{.stabn} N_NSYMS -@findex N_NSYMS -Number of symbols (according to Ultrix V4.0). - -@display - 0, files,,funcs,lines (stab.def) -@end display -@end deffn - -@node N_NOMAP -@section N_NOMAP - -@deffn @code{.stabs} N_NOMAP -@findex N_NOMAP -No DST map for symbol (according to Ultrix V4.0). I think this means a -variable has been optimized out. - -@display - name, ,0,type,ignored (stab.def) -@end display -@end deffn - -@node N_M2C -@section N_M2C - -@deffn @code{.stabs} N_M2C -@findex N_M2C -Modula-2 compilation unit. - -@example -"string" -> "unit_name,unit_time_stamp[,code_time_stamp]" -desc -> unit_number -value -> 0 (main unit) - 1 (any other unit) -@end example - -See @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, for -more information. - -@end deffn - -@node N_BROWS -@section N_BROWS - -@deffn @code{.stabs} N_BROWS -@findex N_BROWS -Sun source code browser, path to @file{.cb} file - -<<?>> -"path to associated @file{.cb} file" - -Note: N_BROWS has the same value as N_BSLINE. -@end deffn - -@node N_DEFD -@section N_DEFD - -@deffn @code{.stabn} N_DEFD -@findex N_DEFD -GNU Modula2 definition module dependency. - -GNU Modula-2 definition module dependency. The value is the -modification time of the definition file. The other field is non-zero -if it is imported with the GNU M2 keyword @code{%INITIALIZE}. Perhaps -@code{N_M2C} can be used if there are enough empty fields? -@end deffn - -@node N_EHDECL -@section N_EHDECL - -@deffn @code{.stabs} N_EHDECL -@findex N_EHDECL -GNU C@t{++} exception variable <<?>>. - -"@var{string} is variable name" - -Note: conflicts with @code{N_MOD2}. -@end deffn - -@node N_MOD2 -@section N_MOD2 - -@deffn @code{.stab?} N_MOD2 -@findex N_MOD2 -Modula2 info "for imc" (according to Ultrix V4.0) - -Note: conflicts with @code{N_EHDECL} <<?>> -@end deffn - -@node N_CATCH -@section N_CATCH - -@deffn @code{.stabn} N_CATCH -@findex N_CATCH -GNU C@t{++} @code{catch} clause - -GNU C@t{++} @code{catch} clause. The value is its address. The desc field -is nonzero if this entry is immediately followed by a @code{CAUGHT} stab -saying what exception was caught. Multiple @code{CAUGHT} stabs means -that multiple exceptions can be caught here. If desc is 0, it means all -exceptions are caught here. -@end deffn - -@node N_SSYM -@section N_SSYM - -@deffn @code{.stabn} N_SSYM -@findex N_SSYM -Structure or union element. - -The value is the offset in the structure. - -<<?looking at structs and unions in C I didn't see these>> -@end deffn - -@node N_SCOPE -@section N_SCOPE - -@deffn @code{.stab?} N_SCOPE -@findex N_SCOPE -Modula2 scope information (Sun linker) -<<?>> -@end deffn - -@node Gould -@section Non-base registers on Gould systems - -@deffn @code{.stab?} N_NBTEXT -@deffnx @code{.stab?} N_NBDATA -@deffnx @code{.stab?} N_NBBSS -@deffnx @code{.stab?} N_NBSTS -@deffnx @code{.stab?} N_NBLCS -@findex N_NBTEXT -@findex N_NBDATA -@findex N_NBBSS -@findex N_NBSTS -@findex N_NBLCS -These are used on Gould systems for non-base registers syms. - -However, the following values are not the values used by Gould; they are -the values which GNU has been documenting for these values for a long -time, without actually checking what Gould uses. I include these values -only because perhaps some someone actually did something with the GNU -information (I hope not, why GNU knowingly assigned wrong values to -these in the header file is a complete mystery to me). - -@example -240 0xf0 N_NBTEXT ?? -242 0xf2 N_NBDATA ?? -244 0xf4 N_NBBSS ?? -246 0xf6 N_NBSTS ?? -248 0xf8 N_NBLCS ?? -@end example -@end deffn - -@node N_LENG -@section N_LENG - -@deffn @code{.stabn} N_LENG -@findex N_LENG -Second symbol entry containing a length-value for the preceding entry. -The value is the length. -@end deffn - -@node Questions -@appendix Questions and Anomalies - -@itemize @bullet -@item -@c I think this is changed in GCC 2.4.5 to put the line number there. -For GNU C stabs defining local and global variables (@code{N_LSYM} and -@code{N_GSYM}), the desc field is supposed to contain the source -line number on which the variable is defined. In reality the desc -field is always 0. (This behavior is defined in @file{dbxout.c} and -putting a line number in desc is controlled by @samp{#ifdef -WINNING_GDB}, which defaults to false). GDB supposedly uses this -information if you say @samp{list @var{var}}. In reality, @var{var} can -be a variable defined in the program and GDB says @samp{function -@var{var} not defined}. - -@item -In GNU C stabs, there seems to be no way to differentiate tag types: -structures, unions, and enums (symbol descriptor @samp{T}) and typedefs -(symbol descriptor @samp{t}) defined at file scope from types defined locally -to a procedure or other more local scope. They all use the @code{N_LSYM} -stab type. Types defined at procedure scope are emitted after the -@code{N_RBRAC} of the preceding function and before the code of the -procedure in which they are defined. This is exactly the same as -types defined in the source file between the two procedure bodies. -GDB over-compensates by placing all types in block #1, the block for -symbols of file scope. This is true for default, @samp{-ansi} and -@samp{-traditional} compiler options. (Bugs gcc/1063, gdb/1066.) - -@item -What ends the procedure scope? Is it the proc block's @code{N_RBRAC} or the -next @code{N_FUN}? (I believe it's the first.) -@end itemize - -@node Stab Sections -@appendix Using Stabs in Their Own Sections - -Many object file formats allow tools to create object files with custom -sections containing any arbitrary data. For any such object file -format, stabs can be embedded in special sections. This is how stabs -are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs -are used with COFF. - -@menu -* Stab Section Basics:: How to embed stabs in sections -* ELF Linker Relocation:: Sun ELF hacks -@end menu - -@node Stab Section Basics -@appendixsec How to Embed Stabs in Sections - -The assembler creates two custom sections, a section named @code{.stab} -which contains an array of fixed length structures, one struct per stab, -and a section named @code{.stabstr} containing all the variable length -strings that are referenced by stabs in the @code{.stab} section. The -byte order of the stabs binary data depends on the object file format. -For ELF, it matches the byte order of the ELF file itself, as determined -from the @code{EI_DATA} field in the @code{e_ident} member of the ELF -header. For SOM, it is always big-endian (is this true??? FIXME). For -COFF, it matches the byte order of the COFF headers. The meaning of the -fields is the same as for a.out (@pxref{Symbol Table Format}), except -that the @code{n_strx} field is relative to the strings for the current -compilation unit (which can be found using the synthetic N_UNDF stab -described below), rather than the entire string table. - -The first stab in the @code{.stab} section for each compilation unit is -synthetic, generated entirely by the assembler, with no corresponding -@code{.stab} directive as input to the assembler. This stab contains -the following fields: - -@table @code -@item n_strx -Offset in the @code{.stabstr} section to the source filename. - -@item n_type -@code{N_UNDF}. - -@item n_other -Unused field, always zero. -This may eventually be used to hold overflows from the count in -the @code{n_desc} field. - -@item n_desc -Count of upcoming symbols, i.e., the number of remaining stabs for this -source file. - -@item n_value -Size of the string table fragment associated with this source file, in -bytes. -@end table - -The @code{.stabstr} section always starts with a null byte (so that string -offsets of zero reference a null string), followed by random length strings, -each of which is null byte terminated. - -The ELF section header for the @code{.stab} section has its -@code{sh_link} member set to the section number of the @code{.stabstr} -section, and the @code{.stabstr} section has its ELF section -header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a -string table. SOM and COFF have no way of linking the sections together -or marking them as string tables. - -For COFF, the @code{.stab} and @code{.stabstr} sections may be simply -concatenated by the linker. GDB then uses the @code{n_desc} fields to -figure out the extent of the original sections. Similarly, the -@code{n_value} fields of the header symbols are added together in order -to get the actual position of the strings in a desired @code{.stabstr} -section. Although this design obviates any need for the linker to -relocate or otherwise manipulate @code{.stab} and @code{.stabstr} -sections, it also requires some care to ensure that the offsets are -calculated correctly. For instance, if the linker were to pad in -between the @code{.stabstr} sections before concatenating, then the -offsets to strings in the middle of the executable's @code{.stabstr} -section would be wrong. - -The GNU linker is able to optimize stabs information by merging -duplicate strings and removing duplicate header file information -(@pxref{Include Files}). When some versions of the GNU linker optimize -stabs in sections, they remove the leading @code{N_UNDF} symbol and -arranges for all the @code{n_strx} fields to be relative to the start of -the @code{.stabstr} section. - -@node ELF Linker Relocation -@appendixsec Having the Linker Relocate Stabs in ELF - -This section describes some Sun hacks for Stabs in ELF; it does not -apply to COFF or SOM. While @value{GDBN} no longer supports this hack -for Sun Stabs in ELF, this section is kept to document the issue. - -To keep linking fast, you don't want the linker to have to relocate very -many stabs. Making sure this is done for @code{N_SLINE}, -@code{N_RBRAC}, and @code{N_LBRAC} stabs is the most important thing -(see the descriptions of those stabs for more information). But Sun's -stabs in ELF has taken this further, to make all addresses in the -@code{n_value} field (functions and static variables) relative to the -source file. For the @code{N_SO} symbol itself, Sun simply omits the -address. To find the address of each section corresponding to a given -source file, the compiler puts out symbols giving the address of each -section for a given source file. Since these are ELF (not stab) -symbols, the linker relocates them correctly without having to touch the -stabs section. They are named @code{Bbss.bss} for the bss section, -@code{Ddata.data} for the data section, and @code{Drodata.rodata} for -the rodata section. For the text section, there is no such symbol (but -there should be, see below). For an example of how these symbols work, -@xref{Stab Section Transformations}. GCC does not provide these symbols; -it instead relies on the stabs getting relocated. Thus addresses which -would normally be relative to @code{Bbss.bss}, etc., are already -relocated. The Sun linker provided with Solaris 2.2 and earlier -relocates stabs using normal ELF relocation information, as it would do -for any section. Sun has been threatening to kludge their linker to not -do this (to speed up linking), even though the correct way to avoid -having the linker do these relocations is to have the compiler no longer -output relocatable values. Last I heard they had been talked out of the -linker kludge. See Sun point patch 101052-01 and Sun bug 1142109. With -the Sun compiler this affects @samp{S} symbol descriptor stabs -(@pxref{Statics}) and functions (@pxref{Procedures}). In the latter -case, to adopt the clean solution (making the value of the stab relative -to the start of the compilation unit), it would be necessary to invent a -@code{Ttext.text} symbol, analogous to the @code{Bbss.bss}, etc., -symbols. I recommend this rather than using a zero value and getting -the address from the ELF symbols. - -Finding the correct @code{Bbss.bss}, etc., symbol is difficult, because -the linker simply concatenates the @code{.stab} sections from each -@file{.o} file without including any information about which part of a -@code{.stab} section comes from which @file{.o} file. The way GDB use to -do this is to look for an ELF @code{STT_FILE} symbol which has the same -name as the last component of the file name from the @code{N_SO} symbol -in the stabs (for example, if the file name is @file{../../gdb/main.c}, -it looks for an ELF @code{STT_FILE} symbol named @code{main.c}). This -loses if different files have the same name (they could be in different -directories, a library could have been copied from one system to -another, etc.). It would be much cleaner to have the @code{Bbss.bss} -symbols in the stabs themselves. Having the linker relocate them there -is no more work than having the linker relocate ELF symbols, and it -solves the problem of having to associate the ELF and stab symbols. -However, no one has yet designed or implemented such a scheme. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include fdl.texi - -@node Symbol Types Index -@unnumbered Symbol Types Index - -@printindex fn - -@bye |