aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc
diff options
context:
space:
mode:
Diffstat (limited to 'gdb/doc')
-rw-r--r--gdb/doc/Doxyfile-base.in2
-rw-r--r--gdb/doc/Doxyfile-gdb-api.in2
-rw-r--r--gdb/doc/Doxyfile-gdb-xref.in2
-rw-r--r--gdb/doc/Doxyfile-gdbserver.in2
-rw-r--r--gdb/doc/Makefile.in2
-rw-r--r--gdb/doc/agentexpr.texi2
-rw-r--r--gdb/doc/all-cfg.texi2
-rw-r--r--gdb/doc/annotate.texinfo6
-rw-r--r--gdb/doc/doxy-index.in2
-rw-r--r--gdb/doc/gdb.texinfo576
-rw-r--r--gdb/doc/guile.texi21
-rw-r--r--gdb/doc/python.texi174
-rw-r--r--gdb/doc/refcard.tex6
-rw-r--r--gdb/doc/stabs.texinfo2
14 files changed, 570 insertions, 231 deletions
diff --git a/gdb/doc/Doxyfile-base.in b/gdb/doc/Doxyfile-base.in
index 709a013..dc42b53 100644
--- a/gdb/doc/Doxyfile-base.in
+++ b/gdb/doc/Doxyfile-base.in
@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2024 Free Software Foundation, Inc.
+# Copyright (C) 2014-2025 Free Software Foundation, Inc.
# Base doxyfile for GDB.
# This file is part of GDB.
diff --git a/gdb/doc/Doxyfile-gdb-api.in b/gdb/doc/Doxyfile-gdb-api.in
index d3ba254..b4d6d5f 100644
--- a/gdb/doc/Doxyfile-gdb-api.in
+++ b/gdb/doc/Doxyfile-gdb-api.in
@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2024 Free Software Foundation, Inc.
+# Copyright (C) 2014-2025 Free Software Foundation, Inc.
# Doxygen file for GDB internal API.
# This file is part of GDB.
diff --git a/gdb/doc/Doxyfile-gdb-xref.in b/gdb/doc/Doxyfile-gdb-xref.in
index 3ec76b8..ce5aaaa 100644
--- a/gdb/doc/Doxyfile-gdb-xref.in
+++ b/gdb/doc/Doxyfile-gdb-xref.in
@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2024 Free Software Foundation, Inc.
+# Copyright (C) 2014-2025 Free Software Foundation, Inc.
# Doxygen file for a full GDB cross-reference.
# This file is part of GDB.
diff --git a/gdb/doc/Doxyfile-gdbserver.in b/gdb/doc/Doxyfile-gdbserver.in
index 0f7b34b..c130115 100644
--- a/gdb/doc/Doxyfile-gdbserver.in
+++ b/gdb/doc/Doxyfile-gdbserver.in
@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2024 Free Software Foundation, Inc.
+# Copyright (C) 2014-2025 Free Software Foundation, Inc.
# Doxygen file for a GDBserver cross-reference.
# This file is part of GDB.
diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index c75714b..b9c79b9 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -1,4 +1,4 @@
-##Copyright (C) 1991-2024 Free Software Foundation, Inc.
+##Copyright (C) 1991-2025 Free Software Foundation, Inc.
# Makefile for GDB documentation.
# This file is part of GDB.
diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi
index b15953f..970f930 100644
--- a/gdb/doc/agentexpr.texi
+++ b/gdb/doc/agentexpr.texi
@@ -7,7 +7,7 @@
@c This file is part of the GDB manual.
@c
-@c Copyright (C) 2003--2024 Free Software Foundation, Inc.
+@c Copyright (C) 2003--2025 Free Software Foundation, Inc.
@c
@c See the file gdb.texinfo for copying conditions.
diff --git a/gdb/doc/all-cfg.texi b/gdb/doc/all-cfg.texi
index 4ba231f..5d2af66 100644
--- a/gdb/doc/all-cfg.texi
+++ b/gdb/doc/all-cfg.texi
@@ -1,6 +1,6 @@
@c GDB MANUAL configuration file.
@c
-@c Copyright (C) 1993--2024 Free Software Foundation, Inc.
+@c Copyright (C) 1993--2025 Free Software Foundation, Inc.
@c
@c NOTE: While the GDB manual is configurable (by changing these
@c switches), its configuration is ***NOT*** automatically tied in to
diff --git a/gdb/doc/annotate.texinfo b/gdb/doc/annotate.texinfo
index 8593b00..eccdb87 100644
--- a/gdb/doc/annotate.texinfo
+++ b/gdb/doc/annotate.texinfo
@@ -27,7 +27,7 @@
@c cost. Having a smaller cheaper manual helps the GNU Press with its sales.
@copying
-Copyright @copyright{} 1994--2024 Free Software Foundation, Inc.
+Copyright @copyright{} 1994--2025 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -147,11 +147,11 @@ the annotation interface was marked as deprecated.
This chapter discusses the known problems.
-@section Dependant on @sc{cli} output
+@section Dependent on @sc{cli} output
The annotation interface works by interspersing markups with
@value{GDBN} normal command-line interpreter output. Unfortunately, this
-makes the annotation client dependant on not just the annotations, but
+makes the annotation client dependent on not just the annotations, but
also the @sc{cli} output. This is because the client is forced to
assume that specific @value{GDBN} commands provide specific information.
Any change to @value{GDBN}'s @sc{cli} output modifies or removes that
diff --git a/gdb/doc/doxy-index.in b/gdb/doc/doxy-index.in
index 67636bb..2da8658 100644
--- a/gdb/doc/doxy-index.in
+++ b/gdb/doc/doxy-index.in
@@ -1,4 +1,4 @@
-<!-- Copyright (C) 2014-2024 Free Software Foundation, Inc.
+<!-- Copyright (C) 2014-2025 Free Software Foundation, Inc.
Navigation page for Doxygen-generated GDB info.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index ff9fe29..2bbaf14 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1,5 +1,5 @@
\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988--2024 Free Software Foundation, Inc.
+@c Copyright (C) 1988--2025 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@@ -50,7 +50,7 @@
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2024 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2025 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -120,7 +120,7 @@ This is the @value{EDITION} Edition, for @value{GDBN}
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2024 Free Software Foundation, Inc.
+Copyright (C) 1988-2025 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
@@ -3807,7 +3807,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 +3857,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:
@@ -4090,6 +4098,56 @@ When @samp{on} @value{GDBN} will print additional messages when
threads are created and deleted.
@end table
+@cindex thread local storage
+@cindex @acronym{TLS}
+For some debugging targets, @value{GDBN} has support for accessing
+variables that reside in Thread Local Storage (@acronym{TLS}).
+@acronym{TLS} variables are similar to global variables, except that
+each thread has its own copy of the variable. While often used in
+multi-threaded programs, @acronym{TLS} variables can also be used in
+programs without threads. The C library variable @var{errno} is,
+perhaps, the most prominent example of a @acronym{TLS} variable that
+is frequently used in non-threaded programs. For targets where
+@value{GDBN} does not have good @acronym{TLS} support, printing or
+changing the value of @var{errno} might not be directly possible.
+
+@sc{gnu}/Linux and FreeBSD targets have support for accessing
+@acronym{TLS} variables. On @sc{gnu}/Linux, the helper library,
+@code{libthread_db}, is used to help resolve the addresses of
+@acronym{TLS} variables. Some FreeBSD and some @sc{gnu}/Linux targets
+also have @value{GDBN}-internal @acronym{TLS} resolution code.
+@sc{gnu}/Linux targets will attempt to use the @acronym{TLS} address
+lookup functionality provided by @code{libthread_db}, but will fall
+back to using its internal @acronym{TLS} support when
+@code{libthread_db} is not available. This can happen in
+cross-debugging scenarios or when debugging programs that are linked
+in such a way that @code{libthread_db} support is unavailable -- this
+includes statically linked programs, linking against @acronym{GLIBC}
+versions earlier than 2.34, but not with @code{libpthread}, and use of
+other (non-@acronym{GLIBC}) C libraries.
+
+@table @code
+@kindex maint set force-internal-tls-address-lookup
+@kindex maint show force-internal-tls-address-lookup
+@cindex internal @acronym{TLS} address lookup
+@item maint set force-internal-tls-address-lookup
+@itemx maint show force-internal-tls-address-lookup
+Turns on or off forced use of @value{GDBN}-internal @acronym{TLS}
+address lookup code. Use @code{on} to enable and @code{off} to
+disable. The default for this setting is @code{off}.
+
+When disabled, @value{GDBN} will attempt to use a helper
+@code{libthread_db} library if possible, but will fall back to use of
+its own internal @acronym{TLS} address lookup mechanisms if necessary.
+
+When enabled, @value{GDBN} will only use @value{GDBN}'s internal
+@acronym{TLS} address lookup mechanisms, if they exist.
+
+This command is only available for @sc{gnu}/Linux targets. Its
+primary use is for testing -- certain tests in the @value{GDBN} test
+suite use this command to force use of internal TLS address lookup.
+@end table
+
@node Forks
@section Debugging Forks
@@ -4322,18 +4380,36 @@ listed:
@table @code
@item Checkpoint ID
+@item Active state indicator
@item Process ID
@item Code Address
@item Source line, or label
@end table
+Checkpoint IDs will be displayed as either a non-negative integer or
+in the form @var{i}.@var{n}, where @var{i} is the inferior number, a
+positive integer, as shown by the command @code{info inferiors}, and
+@var{n}, a non-negative integer, is the checkpoint number for that
+inferior. The single non-negative integer form is used when
+there is only one inferior. The @var{i}.@var{n} form is used when
+there are multiple inferiors.
+
+The active state indicator is a single letter, either @samp{y} or
+@samp{n}, indicating yes or no. Only one checkpoint per inferior may
+be active at once. The active checkpoint in the current inferior is
+also shown by a @samp{*} at the start of the line. Checkpoints whose
+active state is @samp{n} can be switched to using the @code{restart}
+command or deleted using the @code{delete checkpoint} command.
+
@kindex restart @var{checkpoint-id}
@item restart @var{checkpoint-id}
Restore the program state that was saved as checkpoint number
@var{checkpoint-id}. All program variables, registers, stack frames
etc.@: will be returned to the values that they had when the checkpoint
was saved. In essence, gdb will ``wind back the clock'' to the point
-in time when the checkpoint was saved.
+in time when the checkpoint was saved. The checkpoint number
+@var{checkpoint-id} is specified in the same form as that output by the
+@code{info checkpoints} command.
Note that breakpoints, @value{GDBN} variables, command history etc.
are not affected by restoring a checkpoint. In general, a checkpoint
@@ -6882,7 +6958,7 @@ fatal so it can carry out the purpose of the interrupt: to kill the program.
@value{GDBN} has the ability to detect any occurrence of a signal in your
program. You can tell @value{GDBN} in advance what to do for each kind of
-signal.
+signal, apart from SIGKILL, which has its usual effect regardless.
When specifying a signal by number, @value{GDBN} translates the number
to the target platform according to the corresponding signal name.
@@ -7789,9 +7865,9 @@ previous instruction; otherwise, it will work in record mode, if the
platform supports reverse execution, or stop if not.
Currently, process record and replay is supported on ARM, Aarch64,
-LoongArch, Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running
-GNU/Linux. Process record and replay can be used both when native
-debugging, and when remote debugging via @code{gdbserver}.
+LoongArch, Moxie, PowerPC, PowerPC64, S/390, RISC-V and x86 (i386/amd64)
+running GNU/Linux. Process record and replay can be used both when
+native debugging, and when remote debugging via @code{gdbserver}.
When recording an inferior, @value{GDBN} may print auxiliary information
during stepping commands and commands displaying the execution history.
@@ -9671,20 +9747,21 @@ Any expression valid in the current working language.
@item @var{funcaddr}
An address of a function or procedure derived from its name. In C,
-C@t{++}, Objective-C, Fortran, minimal, and assembly, this is
+C@t{++}, Objective-C, Fortran, Pascal, Modula-2, minimal, and assembly, this is
simply the function's name @var{function} (and actually a special case
-of a valid expression). In Pascal and Modula-2, this is
-@code{&@var{function}}. In Ada, this is @code{@var{function}'Address}
-(although the Pascal form also works).
+of a valid expression). In Ada, this is @code{@var{function}'Address}
+(although @code{&@var{function}} also works).
This form specifies the address of the function's first instruction,
before the stack frame and arguments have been set up.
-@item '@var{filename}':@var{funcaddr}
+@item '@var{filename}'::@var{funcaddr}
Like @var{funcaddr} above, but also specifies the name of the source
file explicitly. This is useful if the name of the function does not
specify the function unambiguously, e.g., if there are several
-functions with identical names in different source files.
+functions with identical names in different source files,
+see @ref{variable name conflict}. This may not be supported for all
+languages, see @ref{Expressions}.
@end table
@node Edit
@@ -10825,8 +10902,9 @@ this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
Languages}, for information on how to use expressions in other
languages.
-In this section, we discuss operators that you can use in @value{GDBN}
-expressions regardless of your programming language.
+In this section, we discuss operators that may be available in @value{GDBN}
+expressions in addition to those of your programming language. However,
+they are not necessarily available in all working languages.
@cindex casts, in expressions
Casts are supported in all languages, not just in C, because it is so
@@ -10845,6 +10923,7 @@ to programming languages:
@item ::
@samp{::} allows you to specify a variable in terms of the file or
function where it is defined. @xref{Variables, ,Program Variables}.
+This is currently not supported in Ada, Rust, Pascal, Modula-2 and D.
@cindex @{@var{type}@}
@cindex type casting memory
@@ -10983,6 +11062,7 @@ executing within the function @code{foo}, but you can only use or
examine the variable @code{b} while your program is executing inside
the block where @code{b} is declared.
+@anchor{variable name conflict}
@cindex variable name conflict
There is an exception: you can refer to a variable or function whose
scope is a single source file even if the current execution point is not
@@ -10990,7 +11070,8 @@ in this file. But it is possible to have more than one such variable or
function with the same name (in different source files). If that
happens, referring to that name has unpredictable effects. If you wish,
you can specify a static variable in a particular function or file by
-using the colon-colon (@code{::}) notation:
+using the colon-colon (@code{::}) notation (this may not be supported for all
+languages, @pxref{Expressions}):
@cindex colon-colon, context for variables/functions
@ifnotinfo
@@ -13023,6 +13104,18 @@ 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 linker namespaces in the inferior (@pxref{Files}). In systems
+with no support for linker namespaces, this variable will always be set to
+@samp{1}.
+
+@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
@node Convenience Funs
@@ -22143,6 +22236,24 @@ Print the names of the shared libraries which are currently loaded
that match @var{regex}. If @var{regex} is omitted then print
all shared libraries that are loaded.
+For each library, @value{GDBN} also lists the address range allocated
+to that library if it can be determined. If the address range cannot
+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 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 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}.
@@ -22178,6 +22289,22 @@ less useful than setting a catchpoint, because it does not allow for
conditions or commands as a catchpoint does.
@table @code
+@kindex info linker-namespaces
+@item info linker-namespaces
+@item info linker-namespaces @code{[[@var{n}]]}
+
+With no argument, print the number of linker namespaces which are
+currently active --- that is, namespaces that have libraries loaded
+into them. Then, it prints the number of libraries loaded into each
+namespace, and all the libraries loaded into them, in the same way
+as @code{info sharedlibrary}.
+
+If an argument @code{[[@var{n}]]} is provided, only prints the
+library count and the libraried for the provided namespace @var{n}.
+The surrounding square brackets are optional.
+@end table
+
+@table @code
@item set stop-on-solib-events
@kindex set stop-on-solib-events
This command controls whether @value{GDBN} should give you control
@@ -22847,10 +22974,9 @@ To create an index file, use the @code{save gdb-index} command:
@kindex save gdb-index
Create index files for all symbol files currently known by
@value{GDBN}. For each known @var{symbol-file}, this command by
-default creates it produces a single file
-@file{@var{symbol-file}.gdb-index}. If you invoke this command with
-the @option{-dwarf-5} option, it produces 2 files:
-@file{@var{symbol-file}.debug_names} and
+default produces a single file @file{@var{symbol-file}.gdb-index}.
+If you invoke this command with the @option{-dwarf-5} option, it
+produces 2 files: @file{@var{symbol-file}.debug_names} and
@file{@var{symbol-file}.debug_str}. The files are created in the
given @var{directory}.
@@ -22958,16 +23084,48 @@ The DWARF specification documents an optional index section called
section. However, in order to work with @value{GDBN}, some extensions
were necessary.
-@value{GDBN} uses the augmentation string @samp{GDB2}. Earlier
-versions used the string @samp{GDB}, but these versions of the index
-are no longer supported.
+@value{GDBN} uses an augmentation string to specify which extensions
+are in use and to allow support of backwards-incompatible changes in
+this functionality. The augmentation string has the form
+@samp{GDB@var{n}}, where @var{n} is an integral version number of the
+extensions, which is incremented when the extensions are added or
+modified. The smallest @var{n} is 2; earlier versions of
+@value{GDBN} used just @samp{GDB} with no version number, but these
+versions of the index are no longer supported.
+
+Here is a list of augmentation string versions along with the changes
+introduced with each version, compared to the previous version.
+
+@table @samp
+
+@item GDB2
+Specifies the use of attributes @code{DW_IDX_GNU_internal},
+@code{DW_IDX_GNU_main}, @code{DW_IDX_GNU_language} and
+@code{DW_IDX_GNU_linkage_name}, described below.
+
+@item GDB3
+Changes the semantic of the @code{DW_IDX_parent} attribute.
+With @samp{GDB2}, @code{DW_IDX_parent} provided an offset into the name
+table. With @samp{GDB3}, it now provides an offset to the index entry
+of the parent, relative to the start of the entry pool region.
+
+@end table
+
+@value{GDBN} produces indexes with the augmentation string @samp{GDB3}.
+
+@value{GDBN} can read indexes with augmentation strings @samp{GDB2} or
+@samp{GDB3}. @value{GDBN} does not support reading indexes with any
+other augmentation strings.
@value{GDBN} does not use the specified hash table. Therefore,
because this hash table is optional, @value{GDBN} also does not write
it.
-@value{GDBN} also generates and uses some extra index attributes:
+@value{GDBN} generates and uses the following non-standard index
+attributes:
+
@table @code
+
@item DW_IDX_GNU_internal
This has the value @samp{0x2000}. It is a flag that, when set,
indicates that the associated entry has @code{static} linkage.
@@ -22984,6 +23142,7 @@ indicating the language of the associated entry.
This has the value @samp{0x2004}. It is a flag that, when set,
indicates that the associated entry is a linkage name, and not a
source name.
+
@end table
@node Symbol Errors
@@ -23494,7 +23653,7 @@ on the @code{gdbserver} command line or use the @option{--attach} option
on the @code{gdbserver} command line, or you can load the program or attach
to it using @value{GDBN} commands after connecting to @code{gdbserver}.
-@anchor{--multi Option in Types of Remote Connnections}
+@anchor{--multi Option in Types of Remote Connections}
You can start @code{gdbserver} without supplying an initial command to run
or process ID to attach. To do this, use the @option{--multi} command line
option. Then you can connect using @code{target extended-remote} and start
@@ -23983,7 +24142,7 @@ You can use the @option{--multi} option to start @code{gdbserver} without
specifying a program to debug or a process to attach to. Then you can
attach in @code{target extended-remote} mode and run or attach to a
program. For more information,
-@pxref{--multi Option in Types of Remote Connnections}.
+@pxref{--multi Option in Types of Remote Connections}.
@cindex @option{--debug}, @code{gdbserver} option
The @option{--debug[=option1,option2,@dots{}]} option tells
@@ -24623,6 +24782,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
@@ -26486,8 +26649,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
@@ -26526,11 +26690,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
@@ -26722,11 +26885,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:
@@ -26766,8 +26928,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
@@ -26777,8 +26940,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
@@ -27495,6 +27659,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}}
@@ -27830,6 +28004,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
@@ -27846,6 +28033,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}.
@@ -29987,7 +30186,7 @@ but it was deemed this would be confusing, and so is not allowed.}.
For example, if you often use the command @code{thread apply all}
specifying to work on the threads in ascending order and to continue in case it
-encounters an error, you can tell @value{GDBN} to automatically preprend
+encounters an error, you can tell @value{GDBN} to automatically prepend
the @code{-ascending} and @code{-c} options by using:
@smallexample
@@ -31148,138 +31347,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.
+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 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.
-
-@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}).
@@ -32235,12 +32309,22 @@ to this library.
@item =library-unloaded,...
Reports that a library was unloaded by the program. This notification
-has 3 fields---@var{id}, @var{target-name} and @var{host-name} with
-the same meaning as for the @code{=library-loaded} notification.
+has the following fields---@var{id}, @var{target-name},
+@var{host-name} and @var{ranges} with the same meaning as for the
+@code{=library-loaded} notification.
+
+It is possible that a library can appear multiple times in an
+inferior's library list, but the library is only mapped once into the
+inferior's address space. When this happens, and one copy of the
+library is unloaded, but there are remaining copies, the
+@var{still-in-use} field will be @samp{true}. In all other
+situations, the @var{still-in-use} field will have the value
+@samp{false}.
+
The @var{thread-group} field, if present, specifies the id of the
-thread group in whose context the library was unloaded. If the field is
-absent, it means the library was unloaded in the context of all present
-thread groups.
+thread group in whose context the library was unloaded. If the field
+is absent, it means the library was unloaded in the context of all
+present thread groups.
@item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum}
@itemx =traceframe-changed,end
@@ -32369,6 +32453,11 @@ by a symbol name.
If this breakpoint is pending, this field is present and holds the
text used to set the breakpoint, as entered by the user.
+@value{GDBN}'s internal breakpoints (@pxref{maint info breakpoints})
+can sometimes become pending too, for these breakpoints the
+@var{pending} field will be empty as @value{GDBN} automatically
+creates these breakpoints as shared libraries are loaded.
+
@item evaluated-by
Where this breakpoint's condition is evaluated, either @samp{host} or
@samp{target}.
@@ -41275,7 +41364,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.
@@ -41473,6 +41562,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
@@ -42328,7 +42424,7 @@ required.
@end table
@var{name} and @var{class} are always case insensitive. If no option
-starting wth @code{-} is given, @value{GDBN} assumes @code{-class}.
+starting with @code{-} is given, @value{GDBN} assumes @code{-class}.
@kindex maint set worker-threads
@kindex maint show worker-threads
@@ -42669,6 +42765,23 @@ reports and error and the command is aborted.
@item show watchdog
Show the current setting of the target wait timeout.
+
+@kindex maint set console-translation-mode
+@kindex maint show console-translation-mode
+@item maint set console-translation-mode @r{[}binary|text@r{]}
+@itemx maint show console-translation-mode
+Controls the translation mode of @value{GDBN} stdout/stderr. MS-Windows
+only. Useful for running the @value{GDBN} testsuite.
+
+The translation mode values are as follows:
+@table @code
+@item binary
+No translation.
+@item text
+Translate @samp{\n} (LF, a single Line Feed) into @samp{\r\n} (CR-LF, a
+Carriage Return-Line Feed combination).
+@end table
+
@end table
@node Remote Protocol
@@ -46645,12 +46758,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.
@@ -48383,7 +48512,7 @@ the following structure:
@smallexample
<?xml version="1.0"?>
<threads>
- <thread id="id" core="0" name="name" handle="1a2b3c">
+ <thread id="id" core="0" name="name" id_str="Thread 12.34" handle="1a2b3c">
... description ...
</thread>
</threads>
@@ -48395,7 +48524,10 @@ identifies the thread (@pxref{thread-id syntax}). The
the thread was last executing on. The @samp{name} attribute, if
present, specifies the human-readable name of the thread. The content
of the of @samp{thread} element is interpreted as human-readable
-auxiliary information. The @samp{handle} attribute, if present,
+auxiliary information. The @samp{id_str} attribute, if present,
+specifies what @value{GDBN} should print as the target ID of the
+thread (e.g.@: in the @samp{info threads} command or when switching
+to the thread). The @samp{handle} attribute, if present,
is a hex encoded representation of the thread handle.
@@ -49115,6 +49247,7 @@ registers using the capitalization used in the description.
@menu
* AArch64 Features::
+* Alpha Features::
* ARC Features::
* ARM Features::
* i386 Features::
@@ -49421,6 +49554,47 @@ of bytes.
Extra registers are allowed in this feature, but they will not affect
@value{GDBN}.
+@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
@@ -51318,7 +51492,8 @@ Richard M. Stallman and Roland H. Pesch, July 1991.
@format
@c man begin SYNOPSIS gcore
-gcore [-a] [-o @var{prefix}] [-d @var{directory}] @var{pid1} [@var{pid2}...@var{pidN}]
+gcore [-v | --version] [-h | --help] [-a] [-o @var{prefix}] [-d @var{directory}]
+ @var{pid1} [@var{pid2}...@var{pidN}]
@c man end
@end format
@@ -51345,11 +51520,19 @@ The optional argument @var{prefix} specifies the prefix to be used
when composing the file names of the core dumps. The file name is
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{gcore}.
+If not specified, @var{prefix} defaults to @var{core}.
@item -d @var{directory}
Use @var{directory} as the data directory when invoking @value{GDBN} for running
the gcore command. This argument is optional.
+
+@item --help
+@itemx -h
+List all options, with brief explanations.
+
+@item --version
+@itemx -v
+Print version information and then exit.
@end table
@c man end
@@ -51561,7 +51744,7 @@ Richard M. Stallman and Roland H. Pesch, July 1991.
@c man title gdb-add-index Add index files to speed up GDB
@c man begin SYNOPSIS gdb-add-index
-gdb-add-index [-dwarf-5] @var{filename}
+gdb-add-index [-h | --help] [-v | --version] [--dwarf-5] @var{filename}
@c man end
@c man begin DESCRIPTION gdb-add-index
@@ -51579,8 +51762,8 @@ which use ELF binaries and DWARF debug information (i.e., sections
named @code{.debug_*}).
By default @command{gdb-add-index} will add a pre-DWARF 5
-@code{.gdb_index} section to @var{filename}. With @option{-dwarf-5}
-DWARF 5 sections are added instead.
+@code{.gdb_index} section to @var{filename}. With @option{--dwarf-5}
+the DWARF 5 section @code{.debug_names} is added instead.
@var{filename} must be writable.
@@ -51604,9 +51787,16 @@ the @value{GDBN} manual in node @code{Index Files}
@c man begin OPTIONS gdb-add-index
@table @env
-@item -dwarf-5
-Add DWARF 5 sections instead of previous @code{.debug_index} section.
+@item --dwarf-5
+Add DWARF 5 sections instead of previous @code{.gdb_index} section.
+@item --help
+@itemx -h
+List all options, with brief explanations.
+
+@item --version
+@itemx -v
+Print version information and then exit.
@end table
@c man end
diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index f1b638e..9677229 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -1,4 +1,4 @@
-@c Copyright (C) 2008--2024 Free Software Foundation, Inc.
+@c Copyright (C) 2008--2025 Free Software Foundation, Inc.
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3 or
@c any later version published by the Free Software Foundation; with the
@@ -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}.
@@ -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.
@@ -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 a682132..6fa2285 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -257,7 +257,7 @@ Python code must not override these, or even change the options using
signals, @value{GDBN} will most likely stop working correctly. Note
that it is unfortunately common for GUI toolkits to install a
@code{SIGCHLD} handler. When creating a new Python thread, you can
-use @code{gdb.block_signals} or @code{gdb.Thread} to handle this
+use @code{gdb.blocked_signals} or @code{gdb.Thread} to handle this
correctly; see @ref{Threading in GDB}.
@item
@@ -285,7 +285,7 @@ offered for debugging purposes only, expect them to change over time.
A string containing the python directory (@pxref{Python}).
@end defvar
-@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
+@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string @w{@r{[}, styling @r{]]]}})
Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
If a GDB exception happens while @var{command} runs, it is
translated as described in @ref{Exception Handling,,Exception Handling}.
@@ -302,6 +302,14 @@ returned as a string. The default is @code{False}, in which case the
return value is @code{None}. If @var{to_string} is @code{True}, the
@value{GDBN} virtual terminal will be temporarily set to unlimited width
and height, and its pagination will be disabled; @pxref{Screen Size}.
+
+When @var{styling} is @code{True}, the output, whether sent to
+standard output, or to a string, will have styling applied, if
+@value{GDBN}'s standard output supports styling, and @kbd{show style
+enabled} is @kbd{on}. When @var{styling} is @code{False} then no
+styling is applied. The default for @var{styling} is @code{True} when
+@var{to_string} is @code{False}, and @code{False} when @var{to_string}
+is @code{True}.
@end defun
@defun gdb.breakpoints ()
@@ -471,7 +479,7 @@ 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
@@ -501,6 +509,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
@@ -646,22 +665,22 @@ threads, you must be careful to only call @value{GDBN}-specific
functions in the @value{GDBN} thread. @value{GDBN} provides some
functions to help with this.
-@defun gdb.block_signals ()
+@defun gdb.blocked_signals ()
As mentioned earlier (@pxref{Basic Python}), certain signals must be
-delivered to the @value{GDBN} main thread. The @code{block_signals}
+delivered to the @value{GDBN} main thread. The @code{blocked_signals}
function returns a context manager that will block these signals on
entry. This can be used when starting a new thread to ensure that the
signals are blocked there, like:
@smallexample
-with gdb.block_signals():
+with gdb.blocked_signals():
start_new_thread()
@end smallexample
@end defun
@deftp {class} gdb.Thread
This is a subclass of Python's @code{threading.Thread} class. It
-overrides the @code{start} method to call @code{block_signals}, making
+overrides the @code{start} method to call @code{blocked_signals}, making
this an easy-to-use drop-in replacement for creating threads that will
work well in @value{GDBN}.
@end deftp
@@ -4517,6 +4536,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
@@ -4546,10 +4566,11 @@ registered.
The help text for the new command is taken from the Python
documentation string for the command's class, if there is one. If no
-documentation string is provided, the default value ``This command is
-not documented.'' is used.
+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
@@ -4560,6 +4581,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.
@@ -4573,6 +4595,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
@@ -5071,7 +5104,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
@@ -5250,6 +5285,99 @@ 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}).
+
+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
+
@node Functions In Python
@subsubsection Writing new convenience functions
@@ -7041,13 +7169,13 @@ writable.
@cindex colors in python
@tindex gdb.Color
-You can assign instance of @code{Color} to the @code{value} of
+You can assign instance of @code{gdb.Color} to the @code{value} of
a @code{Parameter} instance created with @code{PARAM_COLOR}.
-@code{Color} may refer to an index from color palette or contain components
-of a color from some colorspace.
+@code{gdb.Color} may refer to an index from a color palette or contain
+components of a color from some color space.
-@defun Color.__init__ (@r{[}@var{value} @r{[}, @var{color-space}@r{]}@r{]})
+@defun Color.__init__ (@r{[}value @r{[}, color_space@r{]}@r{]})
@var{value} is @code{None} (meaning the terminal's default color),
an integer index of a color in palette, tuple with color components
@@ -7057,22 +7185,23 @@ or one of the following color names:
@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan},
or @samp{white}.
-@var{color-space} should be one of the @samp{COLORSPACE_} constants. This
-argument tells @value{GDBN} which color space @var{value} belongs.
+@var{color_space} should be one of the @samp{COLORSPACE_} constants
+listed below. This argument tells @value{GDBN} which color space
+@var{value} belongs.
@end defun
@defvar Color.is_none
-This atribute is boolean. If its value is @code{True} then color is terminal's
+This attribute is boolean. If its value is @code{True} then color is terminal's
default.
@end defvar
@defvar Color.is_indexed
-This atribute is boolean. If its value is @code{True} then color is indexed,
+This attribute is boolean. If its value is @code{True} then color is indexed,
i.e. belongs to some palette.
@end defvar
@defvar Color.is_direct
-This atribute is boolean. If its value is @code{True} then this object
+This attribute is boolean. If its value is @code{True} then this object
describes direct colour in the sense of ISO/IEC 8613-6.
@end defvar
@@ -7086,12 +7215,15 @@ This attribute exist if @code{is_direct} is @code{True}. Its value is tuple
with integer components of a color.
@end defvar
-@defun Color.escape_sequence (@var{self}, @var{is_foreground})
+@defun Color.escape_sequence (is_foreground)
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
@@ -7128,6 +7260,8 @@ Direct 24-bit RGB colors.
@end table
+It is not possible to sub-class the @code{Color} class.
+
@node Architectures In Python
@subsubsection Python representation of architectures
@cindex Python architectures
diff --git a/gdb/doc/refcard.tex b/gdb/doc/refcard.tex
index 78b88f5..8a40262 100644
--- a/gdb/doc/refcard.tex
+++ b/gdb/doc/refcard.tex
@@ -1,7 +1,7 @@
%%%%%%%%%%%%%%%% gdb-refcard.tex %%%%%%%%%%%%%%%%
%This file is TeX source for a reference card describing GDB, the GNU debugger.
-%Copyright (C) 1991--2024 Free Software Foundation, Inc.
+%Copyright (C) 1991--2025 Free Software Foundation, Inc.
%Permission is granted to make and distribute verbatim copies of
%this reference provided the copyright notices and permission notices
%are preserved on all copies.
@@ -307,7 +307,7 @@ shell {\it cmd}&execute arbitrary shell command string\cr
\line{\smrm \opt{ } surround optional arguments \hfill $\ldots$ show
one or more arguments}
\vskip\baselineskip
-\centerline{\smrm \copyright 1998-2024 Free Software Foundation, Inc.\qquad Permissions on back}
+\centerline{\smrm \copyright 1998-2025 Free Software Foundation, Inc.\qquad Permissions on back}
\eject
\sec Breakpoints and Watchpoints;
break \opt{\it file\tt:}{\it line}\par
@@ -632,7 +632,7 @@ statement.\cr
\vfill
{\smrm\parskip=6pt
-Copyright \copyright 1991-2024 Free Software Foundation, Inc.
+Copyright \copyright 1991-2025 Free Software Foundation, Inc.
Author: Roland H. Pesch
The author assumes no responsibility for any errors on this card.
diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo
index 98810f8..eac342a 100644
--- a/gdb/doc/stabs.texinfo
+++ b/gdb/doc/stabs.texinfo
@@ -17,7 +17,7 @@
@end direntry
@copying
-Copyright @copyright{} 1992--2024 Free Software Foundation, Inc.
+Copyright @copyright{} 1992--2025 Free Software Foundation, Inc.
Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon,
and David MacKenzie.
generated by cgit v1.1 at 2025-08-10 16:47:40 +0000