* Conditions:: Break conditions
* Break Commands:: Breakpoint command lists
* Save Breakpoints:: How to save breakpoints in a file
+* Static Probe Points:: Listing static probe points
* Error in Breakpoints:: ``Cannot insert breakpoints''
* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
@end menu
that can no longer be recreated.
@end table
+@node Static Probe Points
+@subsection Static Probe Points
+
+@cindex static probe point, SystemTap
+@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands
+for Statically Defined Tracing, and the probes are designed to have a tiny
+runtime code and data footprint, and no dynamic relocations. They are
+usable from assembly, C and C@t{++} languages. See
+@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
+for a good reference on how the @acronym{SDT} probes are implemented.
+
+Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
+@acronym{SDT} probes are supported on ELF-compatible systems. See
+@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
+for more information on how to add @code{SystemTap} @acronym{SDT} probes
+in your applications.
+
+@cindex semaphores on static probe points
+Some probes have an associated semaphore variable; for instance, this
+happens automatically if you defined your probe using a DTrace-style
+@file{.d} file. If your probe has a semaphore, @value{GDBN} will
+automatically enable it when you specify a breakpoint using the
+@samp{-probe-stap} notation. But, if you put a breakpoint at a probe's
+location by some other method (e.g., @code{break file:line}), then
+@value{GDBN} will not automatically set the semaphore.
+
+You can examine the available static static probes using @code{info
+probes}, with optional arguments:
+
+@table @code
+@kindex info probes
+@item info probes stap @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+If given, @var{provider} is a regular expression used to match against provider
+names when selecting which probes to list. If omitted, probes by all
+probes from all providers are listed.
+
+If given, @var{name} is a regular expression to match against probe names
+when selecting which probes to list. If omitted, probe names are not
+considered when deciding whether to display them.
+
+If given, @var{objfile} is a regular expression used to select which
+object files (executable or shared libraries) to examine. If not
+given, all object files are considered.
+
+@item info probes all
+List the available static probes, from all types.
+@end table
+
+@vindex $_probe_arg@r{, convenience variable}
+A probe may specify up to twelve arguments. These are available at the
+point at which the probe is defined---that is, when the current PC is
+at the probe's location. The arguments are available using the
+convenience variables (@pxref{Convenience Vars})
+@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. Each probe argument is
+an integer of the appropriate size; types are not preserved. The
+convenience variable @code{$_probe_argc} holds the number of arguments
+at the current probe point.
+
+These variables are always available, but attempts to access them at
+any location other than a probe point will cause @value{GDBN} to give
+an error message.
+
+
@c @ifclear BARETARGET
@node Error in Breakpoints
@subsection ``Cannot insert breakpoints''
functions with identical names in different source files.
@end table
+@cindex breakpoint at static probe point
+@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
+The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
+applications to embed static probes. @xref{Static Probe Points}, for more
+information on finding and using static probes. This form of linespec
+specifies the location of such a static probe.
+
+If @var{objfile} is given, only probes coming from that shared library
+or executable matching @var{objfile} as a regular expression are considered.
+If @var{provider} is given, then only probes from that provider are considered.
+If several probes match the spec, @value{GDBN} will insert a breakpoint at
+each one of those probes.
+
@end table
The variable @code{$_exitcode} is automatically set to the exit code when
the program being debugged terminates.
+@item $_probe_argc
+@itemx $_probe_arg0@dots{}$_probe_arg11
+Arguments to a static probe. @xref{Static Probe Points}.
+
@item $_sdata
@vindex $_sdata@r{, inspect, convenience variable}
The variable @code{$_sdata} contains extra collected static tracepoint
Collect the return address. This is helpful if you want to see more
of a backtrace.
+@item $_probe_argc
+Collects the number of arguments from the static probe at which the
+tracepoint is located.
+@xref{Static Probe Points}.
+
+@item $_probe_arg@var{n}
+@var{n} is an integer between 0 and 11. Collects the @var{n}th argument
+from the static probe at which the tracepoint is located.
+@xref{Static Probe Points}.
+
@item $_sdata
@vindex $_sdata@r{, collect}
Collect static tracepoint marker specific data. Only available for
@node Supported Languages
@section Supported Languages
-@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, OpenCL C, Pascal,
-assembly, Modula-2, and Ada.
+@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, Java,
+OpenCL C, Pascal, assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
language you use: the @value{GDBN} @code{@@} and @code{::} operators,
@menu
* C:: C and C@t{++}
* D:: D
+* Go:: Go
* Objective-C:: Objective-C
* OpenCL C:: OpenCL C
* Fortran:: Fortran
GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D
specific feature --- dynamic arrays.
+@node Go
+@subsection Go
+
+@cindex Go (programming language)
+@value{GDBN} can be used to debug programs written in Go and compiled with
+@file{gccgo} or @file{6g} compilers.
+
+Here is a summary of the Go-specific features and restrictions:
+
+@table @code
+@cindex current Go package
+@item The current Go package
+The name of the current package does not need to be specified when
+specifying global variables and functions.
+
+For example, given the program:
+
+@example
+package main
+var myglob = "Shall we?"
+func main () @{
+ // ...
+@}
+@end example
+
+When stopped inside @code{main} either of these work:
+
+@example
+(gdb) p myglob
+(gdb) p main.myglob
+@end example
+
+@cindex builtin Go types
+@item Builtin Go types
+The @code{string} type is recognized by @value{GDBN} and is printed
+as a string.
+
+@cindex builtin Go functions
+@item Builtin Go functions
+The @value{GDBN} expression parser recognizes the @code{unsafe.Sizeof}
+function and handles it internally.
+
+@cindex restrictions on Go expressions
+@item Restrictions on Go expressions
+All Go operators are supported except @code{&^}.
+The Go @code{_} ``blank identifier'' is not supported.
+Automatic dereferencing of pointers is not supported.
+@end table
+
@node Objective-C
@subsection Objective-C
@menu
* i386::
-* A29K::
* Alpha::
* MIPS::
* HPPA:: HP PA architecture
from functions.
@end table
-@node A29K
-@subsection A29K
-
-@table @code
-
-@kindex set rstack_high_address
-@cindex AMD 29K register stack
-@cindex register stack, AMD29K
-@item set rstack_high_address @var{address}
-On AMD 29000 family processors, registers are saved in a separate
-@dfn{register stack}. There is no way for @value{GDBN} to determine the
-extent of this stack. Normally, @value{GDBN} just assumes that the
-stack is ``large enough''. This may result in @value{GDBN} referencing
-memory locations that do not exist. If necessary, you can get around
-this problem by specifying the ending address of the register stack with
-the @code{set rstack_high_address} command. The argument should be an
-address, which you probably want to precede with @samp{0x} to specify in
-hexadecimal.
-
-@kindex show rstack_high_address
-@item show rstack_high_address
-Display the current limit of the register stack, on AMD 29000 family
-processors.
-
-@end table
-
@node Alpha
@subsection Alpha
libthread-db: Auto-loading of inferior specific libthread_db is on.
local-gdbinit: Auto-loading of .gdbinit script from current directory is on.
python-scripts: Auto-loading of Python scripts is on.
+safe-path: List of directories from which it is safe to auto-load files
+ is /usr/local.
@end smallexample
@anchor{info auto-load}
@tab Show setting of thread debugging library.
@item @xref{info auto-load libthread-db}.
@tab Show state of thread debugging library.
+@item @xref{set auto-load safe-path}.
+@tab Control directories trusted for automatic loading.
+@item @xref{show auto-load safe-path}.
+@tab Show directories trusted for automatic loading.
+@item @xref{add-auto-load-safe-path}.
+@tab Add directory trusted for automatic loading.
@end multitable
@menu
* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
* objfile-gdb.gdb file:: @samp{set/show/info auto-load gdb-script}
+* Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
+* Auto-loading verbose mode:: @samp{set/show debug auto-load}
@xref{Python Auto-loading}.
@end menu
If @var{regexp} is supplied only canned sequences of commands scripts with
matching names are printed.
+@node Auto-loading safe path
+@subsection Security restriction for auto-loading
+@cindex auto-loading safe-path
+
+As the files of inferior can come from untrusted source (such as submitted by
+an application user) @value{GDBN} does not always load any files automatically.
+@value{GDBN} provides the @samp{set auto-load safe-path} setting to list
+directories trusted for loading files not explicitly requested by user.
+
+If the path is not set properly you will see a warning and the file will not
+get loaded:
+
+@smallexample
+$ ./gdb -q ./gdb
+Reading symbols from /home/user/gdb/gdb...done.
+warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been
+ declined by your `auto-load safe-path' set to "/usr/local".
+warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been
+ declined by your `auto-load safe-path' set to "/usr/local".
+@end smallexample
+
+The list of trusted directories is controlled by the following commands:
+
+@table @code
+@anchor{set auto-load safe-path}
+@kindex set auto-load safe-path
+@item set auto-load safe-path @r{[}@var{directories}@r{]}
+Set the list of directories (and their subdirectories) trusted for automatic
+loading and execution of scripts. You can also enter a specific trusted file.
+If you omit @var{directories}, @samp{auto-load safe-path} will be reset to
+its default value as specified during @value{GDBN} compilation.
+
+The list of directories uses directory separator (@samp{:} on GNU and Unix
+systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
+to the @env{PATH} environment variable.
+
+@anchor{show auto-load safe-path}
+@kindex show auto-load safe-path
+@item show auto-load safe-path
+Show the list of directories trusted for automatic loading and execution of
+scripts.
+
+@anchor{add-auto-load-safe-path}
+@kindex add-auto-load-safe-path
+@item add-auto-load-safe-path
+Add an entry (or list of entries) the list of directories trusted for automatic
+loading and execution of scripts. Multiple entries may be delimited by the
+host platform directory separator in use.
+@end table
+
+Setting this variable to @file{/} disables this security protection.
+This variable is supposed to be set to the system directories writable by the
+system superuser only. Users can add their source directories in init files in
+their home directories (@pxref{Home Directory Init File}). See also deprecated
+init file in the current directory
+(@pxref{Init File in the Current Directory during Startup}).
+
+To force @value{GDBN} to load the files it declined to load in the previous
+example, you could use one of the following ways:
+
+@table @asis
+@item @file{~/.gdbinit}: @samp{add-auto-load-safe-path ~/src/gdb}
+Specify this trusted directory (or a file) as additional component of the list.
+You have to specify also any existing directories displayed by
+by @samp{show auto-load safe-path} (such as @samp{/usr:/bin} in this example).
+
+@item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" @dots{}}
+Specify this directory as in the previous case but just for a single
+@value{GDBN} session.
+
+@item @kbd{gdb -iex "set auto-load safe-path /" @dots{}}
+Disable auto-loading safety for a single @value{GDBN} session.
+This assumes all the files you debug during this @value{GDBN} session will come
+from trusted sources.
+
+@item @kbd{./configure --without-auto-load-safe-path}
+During compilation of @value{GDBN} you may disable any auto-loading safety.
+This assumes all the files you will ever debug with this @value{GDBN} come from
+trusted sources.
+@end table
+
+On the other hand you can also explicitly forbid automatic files loading which
+also suppresses any such warning messages:
+
+@table @asis
+@item @kbd{gdb -iex "set auto-load no" @dots{}}
+You can use @value{GDBN} command-line option for a single @value{GDBN} session.
+
+@item @file{~/.gdbinit}: @samp{set auto-load no}
+Disable auto-loading globally for the user
+(@pxref{Home Directory Init File}). While it is improbable, you could also
+use system init file instead (@pxref{System-wide configuration}).
+@end table
+
+This setting applies to the file names as entered by user. If no entry matches
+@value{GDBN} tries as a last resort to also resolve all the file names into
+their canonical form (typically resolving symbolic links) and compare the
+entries again. @value{GDBN} already canonicalizes most of the filenames on its
+own before starting the comparison so a canonical form of directories is
+recommended to be entered.
+
+@node Auto-loading verbose mode
+@subsection Displaying files tried for auto-load
+@cindex auto-loading verbose mode
+
+For better visibility of all the file locations where you can place scripts to
+be auto-loaded with inferior --- or to protect yourself against accidental
+execution of untrusted scripts --- @value{GDBN} provides a feature for printing
+all the files attempted to be loaded. Both existing and non-existing files may
+be printed.
+
+For example the list of directories from which it is safe to auto-load files
+(@pxref{Auto-loading safe path}) applies also to canonicalized filenames which
+may not be too obvious while setting it up.
+
+@smallexample
+(gdb) set debug auto-load on
+(gdb) file ~/src/t/true
+auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb"
+ for objfile "/tmp/true".
+auto-load: Updating directories of "/usr:/opt".
+auto-load: Using directory "/usr".
+auto-load: Using directory "/opt".
+warning: File "/tmp/true-gdb.gdb" auto-loading has been declined
+ by your `auto-load safe-path' set to "/usr:/opt".
+@end smallexample
+
+@table @code
+@anchor{set debug auto-load}
+@kindex set debug auto-load
+@item set debug auto-load [on|off]
+Set whether to print the filenames attempted to be auto-loaded.
+
+@anchor{show debug auto-load}
+@kindex show debug auto-load
+@item show debug auto-load
+Show whether printing of the filenames attempted to be auto-loaded is turned
+on or off.
+@end table
+
@node Messages/Warnings
@section Optional Warnings and Messages
stack.
A @code{gdb.Block} is iterable. The iterator returns the symbols
-(@pxref{Symbols In Python}) local to the block.
+(@pxref{Symbols In Python}) local to the block. Python programs
+should not assume that a specific block object will always contain a
+given symbol, since changes in @value{GDBN} features and
+infrastructure may cause symbols move across blocks in a symbol
+table.
The following block-related functions are available in the @code{gdb}
module:
@defun Symtab.fullname ()
Return the symbol table's source absolute file name.
@end defun
+
+@defun Symtab.global_block ()
+Return the global block of the underlying symbol table.
+@xref{Blocks In Python}.
+@end defun
+
+@defun Symtab.static_block ()
+Return the static block of the underlying symbol table.
+@xref{Blocks In Python}.
+@end defun
@end table
@node Breakpoints In Python
@smallexample
(gdb) info auto-load python-scripts
-Loaded Script
-Yes py-section-script.py
- full name: /tmp/py-section-script.py
-Missing my-foo-pretty-printers.py
+Loaded Script
+Yes py-section-script.py
+ full name: /tmp/py-section-script.py
+No my-foo-pretty-printers.py
@end smallexample
@end table
projects / deliverable / binutils-gdb.git / blobdiff