| Index: gdb/doc/gdb.info-4
|
| diff --git a/gdb/doc/gdb.info-4 b/gdb/doc/gdb.info-4
|
| index e53a5c0ab4768fe00dd587898ac97d12d3735cea..e26bfc764279243ba84379da35230fa96e75a5ac 100644
|
| --- a/gdb/doc/gdb.info-4
|
| +++ b/gdb/doc/gdb.info-4
|
| @@ -1,13 +1,12 @@
|
| -This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
|
| +This is gdb.info, produced by makeinfo version 4.13 from ./gdb.texinfo.
|
|
|
| INFO-DIR-SECTION Software development
|
| START-INFO-DIR-ENTRY
|
| * Gdb: (gdb). The GNU debugger.
|
| +* gdbserver: (gdb) Server. The GNU debugging server.
|
| END-INFO-DIR-ENTRY
|
|
|
| - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
| -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
| -2010 2011, 2012 Free Software Foundation, Inc.
|
| + Copyright (C) 1988-2013 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
|
| @@ -23,11 +22,9 @@ developing GNU and promoting software freedom."
|
| This file documents the GNU debugger GDB.
|
|
|
| This is the Tenth Edition, of `Debugging with GDB: the GNU
|
| -Source-Level Debugger' for GDB (GDB) Version 7.5.1.
|
| +Source-Level Debugger' for GDB (GDB) Version 7.6.50.20131211-cvs.
|
|
|
| - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
| -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
| -2010 2011, 2012 Free Software Foundation, Inc.
|
| + Copyright (C) 1988-2013 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
|
| @@ -41,6 +38,2029 @@ this GNU Manual. Buying copies from GNU Press supports the FSF in
|
| developing GNU and promoting software freedom."
|
|
|
|
|
| +File: gdb.info, Node: Writing a Frame Filter, Next: Inferiors In Python, Prev: Frame Decorator API, Up: Python API
|
| +
|
| +23.2.2.11 Writing a Frame Filter
|
| +................................
|
| +
|
| +There are three basic elements that a frame filter must implement: it
|
| +must correctly implement the documented interface (*note Frame Filter
|
| +API::), it must register itself with GDB, and finally, it must decide
|
| +if it is to work on the data provided by GDB. In all cases, whether it
|
| +works on the iterator or not, each frame filter must return an
|
| +iterator. A bare-bones frame filter follows the pattern in the
|
| +following example.
|
| +
|
| + import gdb
|
| +
|
| + class FrameFilter():
|
| +
|
| + def __init__(self):
|
| + # Frame filter attribute creation.
|
| + #
|
| + # 'name' is the name of the filter that GDB will display.
|
| + #
|
| + # 'priority' is the priority of the filter relative to other
|
| + # filters.
|
| + #
|
| + # 'enabled' is a boolean that indicates whether this filter is
|
| + # enabled and should be executed.
|
| +
|
| + self.name = "Foo"
|
| + self.priority = 100
|
| + self.enabled = True
|
| +
|
| + # Register this frame filter with the global frame_filters
|
| + # dictionary.
|
| + gdb.frame_filters[self.name] = self
|
| +
|
| + def filter(self, frame_iter):
|
| + # Just return the iterator.
|
| + return frame_iter
|
| +
|
| + The frame filter in the example above implements the three
|
| +requirements for all frame filters. It implements the API, self
|
| +registers, and makes a decision on the iterator (in this case, it just
|
| +returns the iterator untouched).
|
| +
|
| + The first step is attribute creation and assignment, and as shown in
|
| +the comments the filter assigns the following attributes: `name',
|
| +`priority' and whether the filter should be enabled with the `enabled'
|
| +attribute.
|
| +
|
| + The second step is registering the frame filter with the dictionary
|
| +or dictionaries that the frame filter has interest in. As shown in the
|
| +comments, this filter just registers itself with the global dictionary
|
| +`gdb.frame_filters'. As noted earlier, `gdb.frame_filters' is a
|
| +dictionary that is initialized in the `gdb' module when GDB starts.
|
| +What dictionary a filter registers with is an important consideration.
|
| +Generally, if a filter is specific to a set of code, it should be
|
| +registered either in the `objfile' or `progspace' dictionaries as they
|
| +are specific to the program currently loaded in GDB. The global
|
| +dictionary is always present in GDB and is never unloaded. Any filters
|
| +registered with the global dictionary will exist until GDB exits. To
|
| +avoid filters that may conflict, it is generally better to register
|
| +frame filters against the dictionaries that more closely align with the
|
| +usage of the filter currently in question. *Note Python
|
| +Auto-loading::, for further information on auto-loading Python scripts.
|
| +
|
| + GDB takes a hands-off approach to frame filter registration,
|
| +therefore it is the frame filter's responsibility to ensure
|
| +registration has occurred, and that any exceptions are handled
|
| +appropriately. In particular, you may wish to handle exceptions
|
| +relating to Python dictionary key uniqueness. It is mandatory that the
|
| +dictionary key is the same as frame filter's `name' attribute. When a
|
| +user manages frame filters (*note Frame Filter Management::), the names
|
| +GDB will display are those contained in the `name' attribute.
|
| +
|
| + The final step of this example is the implementation of the `filter'
|
| +method. As shown in the example comments, we define the `filter'
|
| +method and note that the method must take an iterator, and also must
|
| +return an iterator. In this bare-bones example, the frame filter is
|
| +not very useful as it just returns the iterator untouched. However
|
| +this is a valid operation for frame filters that have the `enabled'
|
| +attribute set, but decide not to operate on any frames.
|
| +
|
| + In the next example, the frame filter operates on all frames and
|
| +utilizes a frame decorator to perform some work on the frames. *Note
|
| +Frame Decorator API::, for further information on the frame decorator
|
| +interface.
|
| +
|
| + This example works on inlined frames. It highlights frames which are
|
| +inlined by tagging them with an "[inlined]" tag. By applying a frame
|
| +decorator to all frames with the Python `itertools imap' method, the
|
| +example defers actions to the frame decorator. Frame decorators are
|
| +only processed when GDB prints the backtrace.
|
| +
|
| + This introduces a new decision making topic: whether to perform
|
| +decision making operations at the filtering step, or at the printing
|
| +step. In this example's approach, it does not perform any filtering
|
| +decisions at the filtering step beyond mapping a frame decorator to
|
| +each frame. This allows the actual decision making to be performed
|
| +when each frame is printed. This is an important consideration, and
|
| +well worth reflecting upon when designing a frame filter. An issue
|
| +that frame filters should avoid is unwinding the stack if possible.
|
| +Some stacks can run very deep, into the tens of thousands in some
|
| +cases. To search every frame to determine if it is inlined ahead of
|
| +time may be too expensive at the filtering step. The frame filter
|
| +cannot know how many frames it has to iterate over, and it would have
|
| +to iterate through them all. This ends up duplicating effort as GDB
|
| +performs this iteration when it prints the frames.
|
| +
|
| + In this example decision making can be deferred to the printing step.
|
| +As each frame is printed, the frame decorator can examine each frame in
|
| +turn when GDB iterates. From a performance viewpoint, this is the most
|
| +appropriate decision to make as it avoids duplicating the effort that
|
| +the printing step would undertake anyway. Also, if there are many
|
| +frame filters unwinding the stack during filtering, it can
|
| +substantially delay the printing of the backtrace which will result in
|
| +large memory usage, and a poor user experience.
|
| +
|
| + class InlineFilter():
|
| +
|
| + def __init__(self):
|
| + self.name = "InlinedFrameFilter"
|
| + self.priority = 100
|
| + self.enabled = True
|
| + gdb.frame_filters[self.name] = self
|
| +
|
| + def filter(self, frame_iter):
|
| + frame_iter = itertools.imap(InlinedFrameDecorator,
|
| + frame_iter)
|
| + return frame_iter
|
| +
|
| + This frame filter is somewhat similar to the earlier example, except
|
| +that the `filter' method applies a frame decorator object called
|
| +`InlinedFrameDecorator' to each element in the iterator. The `imap'
|
| +Python method is light-weight. It does not proactively iterate over
|
| +the iterator, but rather creates a new iterator which wraps the
|
| +existing one.
|
| +
|
| + Below is the frame decorator for this example.
|
| +
|
| + class InlinedFrameDecorator(FrameDecorator):
|
| +
|
| + def __init__(self, fobj):
|
| + super(InlinedFrameDecorator, self).__init__(fobj)
|
| +
|
| + def function(self):
|
| + frame = fobj.inferior_frame()
|
| + name = str(frame.name())
|
| +
|
| + if frame.type() == gdb.INLINE_FRAME:
|
| + name = name + " [inlined]"
|
| +
|
| + return name
|
| +
|
| + This frame decorator only defines and overrides the `function'
|
| +method. It lets the supplied `FrameDecorator', which is shipped with
|
| +GDB, perform the other work associated with printing this frame.
|
| +
|
| + The combination of these two objects create this output from a
|
| +backtrace:
|
| +
|
| + #0 0x004004e0 in bar () at inline.c:11
|
| + #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
|
| + #2 0x00400566 in main () at inline.c:31
|
| +
|
| + So in the case of this example, a frame decorator is applied to all
|
| +frames, regardless of whether they may be inlined or not. As GDB
|
| +iterates over the iterator produced by the frame filters, GDB executes
|
| +each frame decorator which then makes a decision on what to print in
|
| +the `function' callback. Using a strategy like this is a way to defer
|
| +decisions on the frame content to printing time.
|
| +
|
| +Eliding Frames
|
| +--------------
|
| +
|
| +It might be that the above example is not desirable for representing
|
| +inlined frames, and a hierarchical approach may be preferred. If we
|
| +want to hierarchically represent frames, the `elided' frame decorator
|
| +interface might be preferable.
|
| +
|
| + This example approaches the issue with the `elided' method. This
|
| +example is quite long, but very simplistic. It is out-of-scope for
|
| +this section to write a complete example that comprehensively covers
|
| +all approaches of finding and printing inlined frames. However, this
|
| +example illustrates the approach an author might use.
|
| +
|
| + This example comprises of three sections.
|
| +
|
| + class InlineFrameFilter():
|
| +
|
| + def __init__(self):
|
| + self.name = "InlinedFrameFilter"
|
| + self.priority = 100
|
| + self.enabled = True
|
| + gdb.frame_filters[self.name] = self
|
| +
|
| + def filter(self, frame_iter):
|
| + return ElidingInlineIterator(frame_iter)
|
| +
|
| + This frame filter is very similar to the other examples. The only
|
| +difference is this frame filter is wrapping the iterator provided to it
|
| +(`frame_iter') with a custom iterator called `ElidingInlineIterator'.
|
| +This again defers actions to when GDB prints the backtrace, as the
|
| +iterator is not traversed until printing.
|
| +
|
| + The iterator for this example is as follows. It is in this section
|
| +of the example where decisions are made on the content of the backtrace.
|
| +
|
| + class ElidingInlineIterator:
|
| + def __init__(self, ii):
|
| + self.input_iterator = ii
|
| +
|
| + def __iter__(self):
|
| + return self
|
| +
|
| + def next(self):
|
| + frame = next(self.input_iterator)
|
| +
|
| + if frame.inferior_frame().type() != gdb.INLINE_FRAME:
|
| + return frame
|
| +
|
| + try:
|
| + eliding_frame = next(self.input_iterator)
|
| + except StopIteration:
|
| + return frame
|
| + return ElidingFrameDecorator(eliding_frame, [frame])
|
| +
|
| + This iterator implements the Python iterator protocol. When the
|
| +`next' function is called (when GDB prints each frame), the iterator
|
| +checks if this frame decorator, `frame', is wrapping an inlined frame.
|
| +If it is not, it returns the existing frame decorator untouched. If it
|
| +is wrapping an inlined frame, it assumes that the inlined frame was
|
| +contained within the next oldest frame, `eliding_frame', which it
|
| +fetches. It then creates and returns a frame decorator,
|
| +`ElidingFrameDecorator', which contains both the elided frame, and the
|
| +eliding frame.
|
| +
|
| + class ElidingInlineDecorator(FrameDecorator):
|
| +
|
| + def __init__(self, frame, elided_frames):
|
| + super(ElidingInlineDecorator, self).__init__(frame)
|
| + self.frame = frame
|
| + self.elided_frames = elided_frames
|
| +
|
| + def elided(self):
|
| + return iter(self.elided_frames)
|
| +
|
| + This frame decorator overrides one function and returns the inlined
|
| +frame in the `elided' method. As before it lets `FrameDecorator' do
|
| +the rest of the work involved in printing this frame. This produces
|
| +the following output.
|
| +
|
| + #0 0x004004e0 in bar () at inline.c:11
|
| + #2 0x00400529 in main () at inline.c:25
|
| + #1 0x00400529 in max (b=6, a=12) at inline.c:15
|
| +
|
| + In that output, `max' which has been inlined into `main' is printed
|
| +hierarchically. Another approach would be to combine the `function'
|
| +method, and the `elided' method to both print a marker in the inlined
|
| +frame, and also show the hierarchical relationship.
|
| +
|
| +
|
| +File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing a Frame Filter, Up: Python API
|
| +
|
| +23.2.2.12 Inferiors In Python
|
| +.............................
|
| +
|
| +Programs which are being run under GDB are called inferiors (*note
|
| +Inferiors and Programs::). Python scripts can access information about
|
| +and manipulate inferiors controlled by GDB via objects of the
|
| +`gdb.Inferior' class.
|
| +
|
| + The following inferior-related functions are available in the `gdb'
|
| +module:
|
| +
|
| + -- Function: gdb.inferiors ()
|
| + Return a tuple containing all inferior objects.
|
| +
|
| + -- Function: gdb.selected_inferior ()
|
| + Return an object representing the current inferior.
|
| +
|
| + A `gdb.Inferior' object has the following attributes:
|
| +
|
| + -- Variable: Inferior.num
|
| + ID of inferior, as assigned by GDB.
|
| +
|
| + -- Variable: Inferior.pid
|
| + Process ID of the inferior, as assigned by the underlying operating
|
| + system.
|
| +
|
| + -- Variable: Inferior.was_attached
|
| + Boolean signaling whether the inferior was created using `attach',
|
| + or started by GDB itself.
|
| +
|
| + A `gdb.Inferior' object has the following methods:
|
| +
|
| + -- Function: Inferior.is_valid ()
|
| + Returns `True' if the `gdb.Inferior' object is valid, `False' if
|
| + not. A `gdb.Inferior' object will become invalid if the inferior
|
| + no longer exists within GDB. All other `gdb.Inferior' methods
|
| + will throw an exception if it is invalid at the time the method is
|
| + called.
|
| +
|
| + -- Function: Inferior.threads ()
|
| + This method returns a tuple holding all the threads which are valid
|
| + when it is called. If there are no valid threads, the method will
|
| + return an empty tuple.
|
| +
|
| + -- Function: Inferior.read_memory (address, length)
|
| + Read LENGTH bytes of memory from the inferior, starting at
|
| + ADDRESS. Returns a buffer object, which behaves much like an array
|
| + or a string. It can be modified and given to the
|
| + `Inferior.write_memory' function. In `Python' 3, the return value
|
| + is a `memoryview' object.
|
| +
|
| + -- Function: Inferior.write_memory (address, buffer [, length])
|
| + Write the contents of BUFFER to the inferior, starting at ADDRESS.
|
| + The BUFFER parameter must be a Python object which supports the
|
| + buffer protocol, i.e., a string, an array or the object returned
|
| + from `Inferior.read_memory'. If given, LENGTH determines the
|
| + number of bytes from BUFFER to be written.
|
| +
|
| + -- Function: Inferior.search_memory (address, length, pattern)
|
| + Search a region of the inferior memory starting at ADDRESS with
|
| + the given LENGTH using the search pattern supplied in PATTERN.
|
| + The PATTERN parameter must be a Python object which supports the
|
| + buffer protocol, i.e., a string, an array or the object returned
|
| + from `gdb.read_memory'. Returns a Python `Long' containing the
|
| + address where the pattern was found, or `None' if the pattern
|
| + could not be found.
|
| +
|
| +
|
| +File: gdb.info, Node: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API
|
| +
|
| +23.2.2.13 Events In Python
|
| +..........................
|
| +
|
| +GDB provides a general event facility so that Python code can be
|
| +notified of various state changes, particularly changes that occur in
|
| +the inferior.
|
| +
|
| + An "event" is just an object that describes some state change. The
|
| +type of the object and its attributes will vary depending on the details
|
| +of the change. All the existing events are described below.
|
| +
|
| + In order to be notified of an event, you must register an event
|
| +handler with an "event registry". An event registry is an object in the
|
| +`gdb.events' module which dispatches particular events. A registry
|
| +provides methods to register and unregister event handlers:
|
| +
|
| + -- Function: EventRegistry.connect (object)
|
| + Add the given callable OBJECT to the registry. This object will be
|
| + called when an event corresponding to this registry occurs.
|
| +
|
| + -- Function: EventRegistry.disconnect (object)
|
| + Remove the given OBJECT from the registry. Once removed, the
|
| + object will no longer receive notifications of events.
|
| +
|
| + Here is an example:
|
| +
|
| + def exit_handler (event):
|
| + print "event type: exit"
|
| + print "exit code: %d" % (event.exit_code)
|
| +
|
| + gdb.events.exited.connect (exit_handler)
|
| +
|
| + In the above example we connect our handler `exit_handler' to the
|
| +registry `events.exited'. Once connected, `exit_handler' gets called
|
| +when the inferior exits. The argument "event" in this example is of
|
| +type `gdb.ExitedEvent'. As you can see in the example the
|
| +`ExitedEvent' object has an attribute which indicates the exit code of
|
| +the inferior.
|
| +
|
| + The following is a listing of the event registries that are
|
| +available and details of the events they emit:
|
| +
|
| +`events.cont'
|
| + Emits `gdb.ThreadEvent'.
|
| +
|
| + Some events can be thread specific when GDB is running in non-stop
|
| + mode. When represented in Python, these events all extend
|
| + `gdb.ThreadEvent'. Note, this event is not emitted directly;
|
| + instead, events which are emitted by this or other modules might
|
| + extend this event. Examples of these events are
|
| + `gdb.BreakpointEvent' and `gdb.ContinueEvent'.
|
| +
|
| + -- Variable: ThreadEvent.inferior_thread
|
| + In non-stop mode this attribute will be set to the specific
|
| + thread which was involved in the emitted event. Otherwise, it
|
| + will be set to `None'.
|
| +
|
| + Emits `gdb.ContinueEvent' which extends `gdb.ThreadEvent'.
|
| +
|
| + This event indicates that the inferior has been continued after a
|
| + stop. For inherited attribute refer to `gdb.ThreadEvent' above.
|
| +
|
| +`events.exited'
|
| + Emits `events.ExitedEvent' which indicates that the inferior has
|
| + exited. `events.ExitedEvent' has two attributes:
|
| +
|
| + -- Variable: ExitedEvent.exit_code
|
| + An integer representing the exit code, if available, which
|
| + the inferior has returned. (The exit code could be
|
| + unavailable if, for example, GDB detaches from the inferior.)
|
| + If the exit code is unavailable, the attribute does not exist.
|
| +
|
| + -- Variable: ExitedEvent inferior
|
| + A reference to the inferior which triggered the `exited'
|
| + event.
|
| +
|
| +`events.stop'
|
| + Emits `gdb.StopEvent' which extends `gdb.ThreadEvent'.
|
| +
|
| + Indicates that the inferior has stopped. All events emitted by
|
| + this registry extend StopEvent. As a child of `gdb.ThreadEvent',
|
| + `gdb.StopEvent' will indicate the stopped thread when GDB is
|
| + running in non-stop mode. Refer to `gdb.ThreadEvent' above for
|
| + more details.
|
| +
|
| + Emits `gdb.SignalEvent' which extends `gdb.StopEvent'.
|
| +
|
| + This event indicates that the inferior or one of its threads has
|
| + received as signal. `gdb.SignalEvent' has the following
|
| + attributes:
|
| +
|
| + -- Variable: SignalEvent.stop_signal
|
| + A string representing the signal received by the inferior. A
|
| + list of possible signal values can be obtained by running the
|
| + command `info signals' in the GDB command prompt.
|
| +
|
| + Also emits `gdb.BreakpointEvent' which extends `gdb.StopEvent'.
|
| +
|
| + `gdb.BreakpointEvent' event indicates that one or more breakpoints
|
| + have been hit, and has the following attributes:
|
| +
|
| + -- Variable: BreakpointEvent.breakpoints
|
| + A sequence containing references to all the breakpoints (type
|
| + `gdb.Breakpoint') that were hit. *Note Breakpoints In
|
| + Python::, for details of the `gdb.Breakpoint' object.
|
| +
|
| + -- Variable: BreakpointEvent.breakpoint
|
| + A reference to the first breakpoint that was hit. This
|
| + function is maintained for backward compatibility and is now
|
| + deprecated in favor of the `gdb.BreakpointEvent.breakpoints'
|
| + attribute.
|
| +
|
| +`events.new_objfile'
|
| + Emits `gdb.NewObjFileEvent' which indicates that a new object file
|
| + has been loaded by GDB. `gdb.NewObjFileEvent' has one attribute:
|
| +
|
| + -- Variable: NewObjFileEvent.new_objfile
|
| + A reference to the object file (`gdb.Objfile') which has been
|
| + loaded. *Note Objfiles In Python::, for details of the
|
| + `gdb.Objfile' object.
|
| +
|
| +
|
| +
|
| +File: gdb.info, Node: Threads In Python, Next: Commands In Python, Prev: Events In Python, Up: Python API
|
| +
|
| +23.2.2.14 Threads In Python
|
| +...........................
|
| +
|
| +Python scripts can access information about, and manipulate inferior
|
| +threads controlled by GDB, via objects of the `gdb.InferiorThread'
|
| +class.
|
| +
|
| + The following thread-related functions are available in the `gdb'
|
| +module:
|
| +
|
| + -- Function: gdb.selected_thread ()
|
| + This function returns the thread object for the selected thread.
|
| + If there is no selected thread, this will return `None'.
|
| +
|
| + A `gdb.InferiorThread' object has the following attributes:
|
| +
|
| + -- Variable: InferiorThread.name
|
| + The name of the thread. If the user specified a name using
|
| + `thread name', then this returns that name. Otherwise, if an
|
| + OS-supplied name is available, then it is returned. Otherwise,
|
| + this returns `None'.
|
| +
|
| + This attribute can be assigned to. The new value must be a string
|
| + object, which sets the new name, or `None', which removes any
|
| + user-specified thread name.
|
| +
|
| + -- Variable: InferiorThread.num
|
| + ID of the thread, as assigned by GDB.
|
| +
|
| + -- Variable: InferiorThread.ptid
|
| + ID of the thread, as assigned by the operating system. This
|
| + attribute is a tuple containing three integers. The first is the
|
| + Process ID (PID); the second is the Lightweight Process ID
|
| + (LWPID), and the third is the Thread ID (TID). Either the LWPID
|
| + or TID may be 0, which indicates that the operating system does
|
| + not use that identifier.
|
| +
|
| + A `gdb.InferiorThread' object has the following methods:
|
| +
|
| + -- Function: InferiorThread.is_valid ()
|
| + Returns `True' if the `gdb.InferiorThread' object is valid,
|
| + `False' if not. A `gdb.InferiorThread' object will become invalid
|
| + if the thread exits, or the inferior that the thread belongs is
|
| + deleted. All other `gdb.InferiorThread' methods will throw an
|
| + exception if it is invalid at the time the method is called.
|
| +
|
| + -- Function: InferiorThread.switch ()
|
| + This changes GDB's currently selected thread to the one represented
|
| + by this object.
|
| +
|
| + -- Function: InferiorThread.is_stopped ()
|
| + Return a Boolean indicating whether the thread is stopped.
|
| +
|
| + -- Function: InferiorThread.is_running ()
|
| + Return a Boolean indicating whether the thread is running.
|
| +
|
| + -- Function: InferiorThread.is_exited ()
|
| + Return a Boolean indicating whether the thread is exited.
|
| +
|
| +
|
| +File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Threads In Python, Up: Python API
|
| +
|
| +23.2.2.15 Commands In Python
|
| +............................
|
| +
|
| +You can implement new GDB CLI commands in Python. A CLI command is
|
| +implemented using an instance of the `gdb.Command' class, most commonly
|
| +using a subclass.
|
| +
|
| + -- Function: Command.__init__ (name, COMMAND_CLASS [, COMPLETER_CLASS
|
| + [, PREFIX]])
|
| + The object initializer for `Command' registers the new command
|
| + with GDB. This initializer is normally invoked from the subclass'
|
| + own `__init__' method.
|
| +
|
| + NAME is the name of the command. If NAME consists of multiple
|
| + words, then the initial words are looked for as prefix commands.
|
| + In this case, if one of the prefix commands does not exist, an
|
| + exception is raised.
|
| +
|
| + There is no support for multi-line commands.
|
| +
|
| + COMMAND_CLASS should be one of the `COMMAND_' constants defined
|
| + below. This argument tells GDB how to categorize the new command
|
| + in the help system.
|
| +
|
| + COMPLETER_CLASS is an optional argument. If given, it should be
|
| + one of the `COMPLETE_' constants defined below. This argument
|
| + tells GDB how to perform completion for this command. If not
|
| + given, GDB will attempt to complete using the object's `complete'
|
| + method (see below); if no such method is found, an error will
|
| + occur when completion is attempted.
|
| +
|
| + PREFIX is an optional argument. If `True', then the new command
|
| + is a prefix command; sub-commands of this command may be
|
| + 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.
|
| +
|
| + -- Function: Command.dont_repeat ()
|
| + By default, a GDB command is repeated when the user enters a blank
|
| + line at the command prompt. A command can suppress this behavior
|
| + by invoking the `dont_repeat' method. This is similar to the user
|
| + command `dont-repeat', see *note dont-repeat: Define.
|
| +
|
| + -- Function: Command.invoke (argument, from_tty)
|
| + This method is called by GDB when this command is invoked.
|
| +
|
| + ARGUMENT is a string. It is the argument to the command, after
|
| + leading and trailing whitespace has been stripped.
|
| +
|
| + FROM_TTY is a boolean argument. When true, this means that the
|
| + command was entered by the user at the terminal; when false it
|
| + means that the command came from elsewhere.
|
| +
|
| + If this method throws an exception, it is turned into a GDB
|
| + `error' call. Otherwise, the return value is ignored.
|
| +
|
| + To break ARGUMENT up into an argv-like string use
|
| + `gdb.string_to_argv'. This function behaves identically to GDB's
|
| + internal argument lexer `buildargv'. It is recommended to use
|
| + this for consistency. Arguments are separated by spaces and may
|
| + be quoted. Example:
|
| +
|
| + print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
|
| + ['1', '2 "3', '4 "5', "6 '7"]
|
| +
|
| +
|
| + -- Function: Command.complete (text, word)
|
| + This method is called by GDB when the user attempts completion on
|
| + this command. All forms of completion are handled by this method,
|
| + that is, the <TAB> and <M-?> key bindings (*note Completion::),
|
| + and the `complete' command (*note complete: Help.).
|
| +
|
| + The arguments TEXT and WORD are both strings. TEXT holds the
|
| + complete command line up to the cursor's location. WORD holds the
|
| + last word of the command line; this is computed using a
|
| + word-breaking heuristic.
|
| +
|
| + The `complete' method can return several values:
|
| + * If the return value is a sequence, the contents of the
|
| + sequence are used as the completions. It is up to `complete'
|
| + to ensure that the contents actually do complete the word. A
|
| + zero-length sequence is allowed, it means that there were no
|
| + completions available. Only string elements of the sequence
|
| + are used; other elements in the sequence are ignored.
|
| +
|
| + * If the return value is one of the `COMPLETE_' constants
|
| + defined below, then the corresponding GDB-internal completion
|
| + function is invoked, and its result is used.
|
| +
|
| + * All other results are treated as though there were no
|
| + available completions.
|
| +
|
| + When a new command is registered, it must be declared as a member of
|
| +some general class of commands. This is used to classify top-level
|
| +commands in the on-line help system; note that prefix commands are not
|
| +listed under their own category but rather that of their top-level
|
| +command. The available classifications are represented by constants
|
| +defined in the `gdb' module:
|
| +
|
| +`gdb.COMMAND_NONE'
|
| + The command does not belong to any particular class. A command in
|
| + this category will not be displayed in any of the help categories.
|
| +
|
| +`gdb.COMMAND_RUNNING'
|
| + The command is related to running the inferior. For example,
|
| + `start', `step', and `continue' are in this category. Type `help
|
| + running' at the GDB prompt to see a list of commands in this
|
| + category.
|
| +
|
| +`gdb.COMMAND_DATA'
|
| + The command is related to data or variables. For example, `call',
|
| + `find', and `print' are in this category. Type `help data' at the
|
| + GDB prompt to see a list of commands in this category.
|
| +
|
| +`gdb.COMMAND_STACK'
|
| + The command has to do with manipulation of the stack. For example,
|
| + `backtrace', `frame', and `return' are in this category. Type
|
| + `help stack' at the GDB prompt to see a list of commands in this
|
| + category.
|
| +
|
| +`gdb.COMMAND_FILES'
|
| + This class is used for file-related commands. For example,
|
| + `file', `list' and `section' are in this category. Type `help
|
| + files' at the GDB prompt to see a list of commands in this
|
| + category.
|
| +
|
| +`gdb.COMMAND_SUPPORT'
|
| + This should be used for "support facilities", generally meaning
|
| + things that are useful to the user when interacting with GDB, but
|
| + not related to the state of the inferior. For example, `help',
|
| + `make', and `shell' are in this category. Type `help support' at
|
| + the GDB prompt to see a list of commands in this category.
|
| +
|
| +`gdb.COMMAND_STATUS'
|
| + The command is an `info'-related command, that is, related to the
|
| + state of GDB itself. For example, `info', `macro', and `show' are
|
| + in this category. Type `help status' at the GDB prompt to see a
|
| + list of commands in this category.
|
| +
|
| +`gdb.COMMAND_BREAKPOINTS'
|
| + The command has to do with breakpoints. For example, `break',
|
| + `clear', and `delete' are in this category. Type `help
|
| + breakpoints' at the GDB prompt to see a list of commands in this
|
| + category.
|
| +
|
| +`gdb.COMMAND_TRACEPOINTS'
|
| + The command has to do with tracepoints. For example, `trace',
|
| + `actions', and `tfind' are in this category. Type `help
|
| + tracepoints' at the GDB prompt to see a list of commands in this
|
| + category.
|
| +
|
| +`gdb.COMMAND_USER'
|
| + The command is a general purpose command for the user, and
|
| + typically does not fit in one of the other categories. Type `help
|
| + user-defined' at the GDB prompt to see a list of commands in this
|
| + category, as well as the list of gdb macros (*note Sequences::).
|
| +
|
| +`gdb.COMMAND_OBSCURE'
|
| + The command is only used in unusual circumstances, or is not of
|
| + general interest to users. For example, `checkpoint', `fork', and
|
| + `stop' are in this category. Type `help obscure' at the GDB
|
| + prompt to see a list of commands in this category.
|
| +
|
| +`gdb.COMMAND_MAINTENANCE'
|
| + The command is only useful to GDB maintainers. The `maintenance'
|
| + and `flushregs' commands are in this category. Type `help
|
| + internals' at the GDB prompt to see a list of commands in this
|
| + category.
|
| +
|
| + A new command can use a predefined completion function, either by
|
| +specifying it via an argument at initialization, or by returning it
|
| +from the `complete' method. These predefined completion constants are
|
| +all defined in the `gdb' module:
|
| +
|
| +`gdb.COMPLETE_NONE'
|
| + This constant means that no completion should be done.
|
| +
|
| +`gdb.COMPLETE_FILENAME'
|
| + This constant means that filename completion should be performed.
|
| +
|
| +`gdb.COMPLETE_LOCATION'
|
| + This constant means that location completion should be done.
|
| + *Note Specify Location::.
|
| +
|
| +`gdb.COMPLETE_COMMAND'
|
| + This constant means that completion should examine GDB command
|
| + names.
|
| +
|
| +`gdb.COMPLETE_SYMBOL'
|
| + This constant means that completion should be done using symbol
|
| + names as the source.
|
| +
|
| +`gdb.COMPLETE_EXPRESSION'
|
| + This constant means that completion should be done on expressions.
|
| + Often this means completing on symbol names, but some language
|
| + parsers also have support for completing on field names.
|
| +
|
| + The following code snippet shows how a trivial CLI command can be
|
| +implemented in Python:
|
| +
|
| + class HelloWorld (gdb.Command):
|
| + """Greet the whole world."""
|
| +
|
| + def __init__ (self):
|
| + super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
|
| +
|
| + def invoke (self, arg, from_tty):
|
| + print "Hello, World!"
|
| +
|
| + HelloWorld ()
|
| +
|
| + The last line instantiates the class, and is necessary to trigger the
|
| +registration of the command with GDB. Depending on how the Python code
|
| +is read into GDB, you may need to import the `gdb' module explicitly.
|
| +
|
| +
|
| +File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: Commands In Python, Up: Python API
|
| +
|
| +23.2.2.16 Parameters In Python
|
| +..............................
|
| +
|
| +You can implement new GDB parameters using Python. A new parameter is
|
| +implemented as an instance of the `gdb.Parameter' class.
|
| +
|
| + Parameters are exposed to the user via the `set' and `show'
|
| +commands. *Note Help::.
|
| +
|
| + There are many parameters that already exist and can be set in GDB.
|
| +Two examples are: `set follow fork' and `set charset'. Setting these
|
| +parameters influences certain behavior in GDB. Similarly, you can
|
| +define parameters that can be used to influence behavior in custom
|
| +Python scripts and commands.
|
| +
|
| + -- Function: Parameter.__init__ (name, COMMAND-CLASS, PARAMETER-CLASS
|
| + [, ENUM-SEQUENCE])
|
| + The object initializer for `Parameter' registers the new parameter
|
| + with GDB. This initializer is normally invoked from the subclass'
|
| + own `__init__' method.
|
| +
|
| + NAME is the name of the new parameter. If NAME consists of
|
| + multiple words, then the initial words are looked for as prefix
|
| + parameters. An example of this can be illustrated with the `set
|
| + print' set of parameters. If NAME is `print foo', then `print'
|
| + will be searched as the prefix parameter. In this case the
|
| + parameter can subsequently be accessed in GDB as `set print foo'.
|
| +
|
| + If NAME consists of multiple words, and no prefix parameter group
|
| + can be found, an exception is raised.
|
| +
|
| + COMMAND-CLASS should be one of the `COMMAND_' constants (*note
|
| + Commands In Python::). This argument tells GDB how to categorize
|
| + the new parameter in the help system.
|
| +
|
| + PARAMETER-CLASS should be one of the `PARAM_' constants defined
|
| + below. This argument tells GDB the type of the new parameter;
|
| + this information is used for input validation and completion.
|
| +
|
| + If PARAMETER-CLASS is `PARAM_ENUM', then ENUM-SEQUENCE must be a
|
| + sequence of strings. These strings represent the possible values
|
| + for the parameter.
|
| +
|
| + If PARAMETER-CLASS is not `PARAM_ENUM', then the presence of a
|
| + fourth argument will cause an exception to be thrown.
|
| +
|
| + The help text for the new parameter is taken from the Python
|
| + documentation string for the parameter's class, if there is one.
|
| + If there is no documentation string, a default value is used.
|
| +
|
| + -- Variable: Parameter.set_doc
|
| + If this attribute exists, and is a string, then its value is used
|
| + as the help text for this parameter's `set' command. The value is
|
| + examined when `Parameter.__init__' is invoked; subsequent changes
|
| + have no effect.
|
| +
|
| + -- Variable: Parameter.show_doc
|
| + If this attribute exists, and is a string, then its value is used
|
| + as the help text for this parameter's `show' command. The value is
|
| + examined when `Parameter.__init__' is invoked; subsequent changes
|
| + have no effect.
|
| +
|
| + -- Variable: Parameter.value
|
| + The `value' attribute holds the underlying value of the parameter.
|
| + It can be read and assigned to just as any other attribute. GDB
|
| + does validation when assignments are made.
|
| +
|
| + There are two methods that should be implemented in any `Parameter'
|
| +class. These are:
|
| +
|
| + -- Function: Parameter.get_set_string (self)
|
| + GDB will call this method when a PARAMETER's value has been
|
| + changed via the `set' API (for example, `set foo off'). The
|
| + `value' attribute has already been populated with the new value
|
| + and may be used in output. This method must return a string.
|
| +
|
| + -- Function: Parameter.get_show_string (self, svalue)
|
| + GDB will call this method when a PARAMETER's `show' API has been
|
| + invoked (for example, `show foo'). The argument `svalue' receives
|
| + the string representation of the current value. This method must
|
| + return a string.
|
| +
|
| + When a new parameter is defined, its type must be specified. The
|
| +available types are represented by constants defined in the `gdb'
|
| +module:
|
| +
|
| +`gdb.PARAM_BOOLEAN'
|
| + The value is a plain boolean. The Python boolean values, `True'
|
| + and `False' are the only valid values.
|
| +
|
| +`gdb.PARAM_AUTO_BOOLEAN'
|
| + The value has three possible states: true, false, and `auto'. In
|
| + Python, true and false are represented using boolean constants, and
|
| + `auto' is represented using `None'.
|
| +
|
| +`gdb.PARAM_UINTEGER'
|
| + The value is an unsigned integer. The value of 0 should be
|
| + interpreted to mean "unlimited".
|
| +
|
| +`gdb.PARAM_INTEGER'
|
| + The value is a signed integer. The value of 0 should be
|
| + interpreted to mean "unlimited".
|
| +
|
| +`gdb.PARAM_STRING'
|
| + The value is a string. When the user modifies the string, any
|
| + escape sequences, such as `\t', `\f', and octal escapes, are
|
| + translated into corresponding characters and encoded into the
|
| + current host charset.
|
| +
|
| +`gdb.PARAM_STRING_NOESCAPE'
|
| + The value is a string. When the user modifies the string, escapes
|
| + are passed through untranslated.
|
| +
|
| +`gdb.PARAM_OPTIONAL_FILENAME'
|
| + The value is a either a filename (a string), or `None'.
|
| +
|
| +`gdb.PARAM_FILENAME'
|
| + The value is a filename. This is just like
|
| + `PARAM_STRING_NOESCAPE', but uses file names for completion.
|
| +
|
| +`gdb.PARAM_ZINTEGER'
|
| + The value is an integer. This is like `PARAM_INTEGER', except 0
|
| + is interpreted as itself.
|
| +
|
| +`gdb.PARAM_ENUM'
|
| + The value is a string, which must be one of a collection string
|
| + constants provided when the parameter is created.
|
| +
|
| +
|
| +File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API
|
| +
|
| +23.2.2.17 Writing new convenience functions
|
| +...........................................
|
| +
|
| +You can implement new convenience functions (*note Convenience Vars::)
|
| +in Python. A convenience function is an instance of a subclass of the
|
| +class `gdb.Function'.
|
| +
|
| + -- Function: Function.__init__ (name)
|
| + The initializer for `Function' registers the new function with
|
| + GDB. The argument NAME is the name of the function, a string.
|
| + The function will be visible to the user as a convenience variable
|
| + of type `internal function', whose name is the same as the given
|
| + NAME.
|
| +
|
| + The documentation for the new function is taken from the
|
| + documentation string for the new class.
|
| +
|
| + -- Function: Function.invoke (*ARGS)
|
| + When a convenience function is evaluated, its arguments are
|
| + converted to instances of `gdb.Value', and then the function's
|
| + `invoke' method is called. Note that GDB does not predetermine
|
| + the arity of convenience functions. Instead, all available
|
| + arguments are passed to `invoke', following the standard Python
|
| + calling convention. In particular, a convenience function can
|
| + have default values for parameters without ill effect.
|
| +
|
| + The return value of this method is used as its value in the
|
| + enclosing expression. If an ordinary Python value is returned, it
|
| + is converted to a `gdb.Value' following the usual rules.
|
| +
|
| + The following code snippet shows how a trivial convenience function
|
| +can be implemented in Python:
|
| +
|
| + class Greet (gdb.Function):
|
| + """Return string to greet someone.
|
| + Takes a name as argument."""
|
| +
|
| + def __init__ (self):
|
| + super (Greet, self).__init__ ("greet")
|
| +
|
| + def invoke (self, name):
|
| + return "Hello, %s!" % name.string ()
|
| +
|
| + Greet ()
|
| +
|
| + The last line instantiates the class, and is necessary to trigger the
|
| +registration of the function with GDB. Depending on how the Python
|
| +code is read into GDB, you may need to import the `gdb' module
|
| +explicitly.
|
| +
|
| + Now you can use the function in an expression:
|
| +
|
| + (gdb) print $greet("Bob")
|
| + $1 = "Hello, Bob!"
|
| +
|
| +
|
| +File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API
|
| +
|
| +23.2.2.18 Program Spaces In Python
|
| +..................................
|
| +
|
| +A program space, or "progspace", represents a symbolic view of an
|
| +address space. It consists of all of the objfiles of the program.
|
| +*Note Objfiles In Python::. *Note program spaces: Inferiors and
|
| +Programs, for more details about program spaces.
|
| +
|
| + The following progspace-related functions are available in the `gdb'
|
| +module:
|
| +
|
| + -- Function: gdb.current_progspace ()
|
| + This function returns the program space of the currently selected
|
| + inferior. *Note Inferiors and Programs::.
|
| +
|
| + -- Function: gdb.progspaces ()
|
| + Return a sequence of all the progspaces currently known to GDB.
|
| +
|
| + Each progspace is represented by an instance of the `gdb.Progspace'
|
| +class.
|
| +
|
| + -- Variable: Progspace.filename
|
| + The file name of the progspace as a string.
|
| +
|
| + -- Variable: Progspace.pretty_printers
|
| + The `pretty_printers' attribute is a list of functions. It is
|
| + used to look up pretty-printers. A `Value' is passed to each
|
| + function in order; if the function returns `None', then the search
|
| + continues. Otherwise, the return value should be an object which
|
| + is used to format the value. *Note Pretty Printing API::, for more
|
| + information.
|
| +
|
| + -- Variable: Progspace.type_printers
|
| + The `type_printers' attribute is a list of type printer objects.
|
| + *Note Type Printing API::, for more information.
|
| +
|
| + -- Variable: Progspace.frame_filters
|
| + The `frame_filters' attribute is a dictionary of frame filter
|
| + objects. *Note Frame Filter API::, for more information.
|
| +
|
| +
|
| +File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API
|
| +
|
| +23.2.2.19 Objfiles In Python
|
| +............................
|
| +
|
| +GDB loads symbols for an inferior from various symbol-containing files
|
| +(*note Files::). These include the primary executable file, any shared
|
| +libraries used by the inferior, and any separate debug info files
|
| +(*note Separate Debug Files::). GDB calls these symbol-containing
|
| +files "objfiles".
|
| +
|
| + The following objfile-related functions are available in the `gdb'
|
| +module:
|
| +
|
| + -- Function: gdb.current_objfile ()
|
| + When auto-loading a Python script (*note Python Auto-loading::),
|
| + GDB sets the "current objfile" to the corresponding objfile. This
|
| + function returns the current objfile. If there is no current
|
| + objfile, this function returns `None'.
|
| +
|
| + -- Function: gdb.objfiles ()
|
| + Return a sequence of all the objfiles current known to GDB. *Note
|
| + Objfiles In Python::.
|
| +
|
| + Each objfile is represented by an instance of the `gdb.Objfile'
|
| +class.
|
| +
|
| + -- Variable: Objfile.filename
|
| + The file name of the objfile as a string.
|
| +
|
| + -- Variable: Objfile.pretty_printers
|
| + The `pretty_printers' attribute is a list of functions. It is
|
| + used to look up pretty-printers. A `Value' is passed to each
|
| + function in order; if the function returns `None', then the search
|
| + continues. Otherwise, the return value should be an object which
|
| + is used to format the value. *Note Pretty Printing API::, for more
|
| + information.
|
| +
|
| + -- Variable: Objfile.type_printers
|
| + The `type_printers' attribute is a list of type printer objects.
|
| + *Note Type Printing API::, for more information.
|
| +
|
| + -- Variable: Objfile.frame_filters
|
| + The `frame_filters' attribute is a dictionary of frame filter
|
| + objects. *Note Frame Filter API::, for more information.
|
| +
|
| + A `gdb.Objfile' object has the following methods:
|
| +
|
| + -- Function: Objfile.is_valid ()
|
| + Returns `True' if the `gdb.Objfile' object is valid, `False' if
|
| + not. A `gdb.Objfile' object can become invalid if the object file
|
| + it refers to is not loaded in GDB any longer. All other
|
| + `gdb.Objfile' methods will throw an exception if it is invalid at
|
| + the time the method is called.
|
| +
|
| +
|
| +File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API
|
| +
|
| +23.2.2.20 Accessing inferior stack frames from Python.
|
| +......................................................
|
| +
|
| +When the debugged program stops, GDB is able to analyze its call stack
|
| +(*note Stack frames: Frames.). The `gdb.Frame' class represents a
|
| +frame in the stack. A `gdb.Frame' object is only valid while its
|
| +corresponding frame exists in the inferior's stack. If you try to use
|
| +an invalid frame object, GDB will throw a `gdb.error' exception (*note
|
| +Exception Handling::).
|
| +
|
| + Two `gdb.Frame' objects can be compared for equality with the `=='
|
| +operator, like:
|
| +
|
| + (gdb) python print gdb.newest_frame() == gdb.selected_frame ()
|
| + True
|
| +
|
| + The following frame-related functions are available in the `gdb'
|
| +module:
|
| +
|
| + -- Function: gdb.selected_frame ()
|
| + Return the selected frame object. (*note Selecting a Frame:
|
| + Selection.).
|
| +
|
| + -- Function: gdb.newest_frame ()
|
| + Return the newest frame object for the selected thread.
|
| +
|
| + -- Function: gdb.frame_stop_reason_string (reason)
|
| + Return a string explaining the reason why GDB stopped unwinding
|
| + frames, as expressed by the given REASON code (an integer, see the
|
| + `unwind_stop_reason' method further down in this section).
|
| +
|
| + A `gdb.Frame' object has the following methods:
|
| +
|
| + -- Function: Frame.is_valid ()
|
| + Returns true if the `gdb.Frame' object is valid, false if not. A
|
| + frame object can become invalid if the frame it refers to doesn't
|
| + exist anymore in the inferior. All `gdb.Frame' methods will throw
|
| + an exception if it is invalid at the time the method is called.
|
| +
|
| + -- Function: Frame.name ()
|
| + Returns the function name of the frame, or `None' if it can't be
|
| + obtained.
|
| +
|
| + -- Function: Frame.architecture ()
|
| + Returns the `gdb.Architecture' object corresponding to the frame's
|
| + architecture. *Note Architectures In Python::.
|
| +
|
| + -- Function: Frame.type ()
|
| + Returns the type of the frame. The value can be one of:
|
| + `gdb.NORMAL_FRAME'
|
| + An ordinary stack frame.
|
| +
|
| + `gdb.DUMMY_FRAME'
|
| + A fake stack frame that was created by GDB when performing an
|
| + inferior function call.
|
| +
|
| + `gdb.INLINE_FRAME'
|
| + A frame representing an inlined function. The function was
|
| + inlined into a `gdb.NORMAL_FRAME' that is older than this one.
|
| +
|
| + `gdb.TAILCALL_FRAME'
|
| + A frame representing a tail call. *Note Tail Call Frames::.
|
| +
|
| + `gdb.SIGTRAMP_FRAME'
|
| + A signal trampoline frame. This is the frame created by the
|
| + OS when it calls into a signal handler.
|
| +
|
| + `gdb.ARCH_FRAME'
|
| + A fake stack frame representing a cross-architecture call.
|
| +
|
| + `gdb.SENTINEL_FRAME'
|
| + This is like `gdb.NORMAL_FRAME', but it is only used for the
|
| + newest frame.
|
| +
|
| + -- Function: Frame.unwind_stop_reason ()
|
| + Return an integer representing the reason why it's not possible to
|
| + find more frames toward the outermost frame. Use
|
| + `gdb.frame_stop_reason_string' to convert the value returned by
|
| + this function to a string. The value can be one of:
|
| +
|
| + `gdb.FRAME_UNWIND_NO_REASON'
|
| + No particular reason (older frames should be available).
|
| +
|
| + `gdb.FRAME_UNWIND_NULL_ID'
|
| + The previous frame's analyzer returns an invalid result.
|
| + This is no longer used by GDB, and is kept only for backward
|
| + compatibility.
|
| +
|
| + `gdb.FRAME_UNWIND_OUTERMOST'
|
| + This frame is the outermost.
|
| +
|
| + `gdb.FRAME_UNWIND_UNAVAILABLE'
|
| + Cannot unwind further, because that would require knowing the
|
| + values of registers or memory that have not been collected.
|
| +
|
| + `gdb.FRAME_UNWIND_INNER_ID'
|
| + This frame ID looks like it ought to belong to a NEXT frame,
|
| + but we got it for a PREV frame. Normally, this is a sign of
|
| + unwinder failure. It could also indicate stack corruption.
|
| +
|
| + `gdb.FRAME_UNWIND_SAME_ID'
|
| + This frame has the same ID as the previous one. That means
|
| + that unwinding further would almost certainly give us another
|
| + frame with exactly the same ID, so break the chain. Normally,
|
| + this is a sign of unwinder failure. It could also indicate
|
| + stack corruption.
|
| +
|
| + `gdb.FRAME_UNWIND_NO_SAVED_PC'
|
| + The frame unwinder did not find any saved PC, but we needed
|
| + one to unwind further.
|
| +
|
| + `gdb.FRAME_UNWIND_FIRST_ERROR'
|
| + Any stop reason greater or equal to this value indicates some
|
| + kind of error. This special value facilitates writing code
|
| + that tests for errors in unwinding in a way that will work
|
| + correctly even if the list of the other values is modified in
|
| + future GDB versions. Using it, you could write:
|
| + reason = gdb.selected_frame().unwind_stop_reason ()
|
| + reason_str = gdb.frame_stop_reason_string (reason)
|
| + if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
|
| + print "An error occured: %s" % reason_str
|
| +
|
| +
|
| + -- Function: Frame.pc ()
|
| + Returns the frame's resume address.
|
| +
|
| + -- Function: Frame.block ()
|
| + Return the frame's code block. *Note Blocks In Python::.
|
| +
|
| + -- Function: Frame.function ()
|
| + Return the symbol for the function corresponding to this frame.
|
| + *Note Symbols In Python::.
|
| +
|
| + -- Function: Frame.older ()
|
| + Return the frame that called this frame.
|
| +
|
| + -- Function: Frame.newer ()
|
| + Return the frame called by this frame.
|
| +
|
| + -- Function: Frame.find_sal ()
|
| + Return the frame's symtab and line object. *Note Symbol Tables In
|
| + Python::.
|
| +
|
| + -- Function: Frame.read_var (variable [, block])
|
| + Return the value of VARIABLE in this frame. If the optional
|
| + argument BLOCK is provided, search for the variable from that
|
| + block; otherwise start at the frame's current block (which is
|
| + determined by the frame's current program counter). VARIABLE must
|
| + be a string or a `gdb.Symbol' object. BLOCK must be a `gdb.Block'
|
| + object.
|
| +
|
| + -- Function: Frame.select ()
|
| + Set this frame to be the selected frame. *Note Examining the
|
| + Stack: Stack.
|
| +
|
| +
|
| +File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API
|
| +
|
| +23.2.2.21 Accessing blocks from Python.
|
| +.......................................
|
| +
|
| +In GDB, symbols are stored in blocks. A block corresponds roughly to a
|
| +scope in the source code. Blocks are organized hierarchically, and are
|
| +represented individually in Python as a `gdb.Block'. Blocks rely on
|
| +debugging information being available.
|
| +
|
| + A frame has a block. Please see *note Frames In Python::, for a more
|
| +in-depth discussion of frames.
|
| +
|
| + The outermost block is known as the "global block". The global
|
| +block typically holds public global variables and functions.
|
| +
|
| + The block nested just inside the global block is the "static block".
|
| +The static block typically holds file-scoped variables and functions.
|
| +
|
| + GDB provides a method to get a block's superblock, but there is
|
| +currently no way to examine the sub-blocks of a block, or to iterate
|
| +over all the blocks in a symbol table (*note Symbol Tables In Python::).
|
| +
|
| + Here is a short example that should help explain blocks:
|
| +
|
| + /* This is in the global block. */
|
| + int global;
|
| +
|
| + /* This is in the static block. */
|
| + static int file_scope;
|
| +
|
| + /* 'function' is in the global block, and 'argument' is
|
| + in a block nested inside of 'function'. */
|
| + int function (int argument)
|
| + {
|
| + /* 'local' is in a block inside 'function'. It may or may
|
| + not be in the same block as 'argument'. */
|
| + int local;
|
| +
|
| + {
|
| + /* 'inner' is in a block whose superblock is the one holding
|
| + 'local'. */
|
| + int inner;
|
| +
|
| + /* If this call is expanded by the compiler, you may see
|
| + a nested block here whose function is 'inline_function'
|
| + and whose superblock is the one holding 'inner'. */
|
| + inline_function ();
|
| + }
|
| + }
|
| +
|
| + A `gdb.Block' is iterable. The iterator returns the symbols (*note
|
| +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 GDB features and infrastructure may cause symbols move
|
| +across blocks in a symbol table.
|
| +
|
| + The following block-related functions are available in the `gdb'
|
| +module:
|
| +
|
| + -- Function: gdb.block_for_pc (pc)
|
| + Return the innermost `gdb.Block' containing the given PC value.
|
| + If the block cannot be found for the PC value specified, the
|
| + function will return `None'.
|
| +
|
| + A `gdb.Block' object has the following methods:
|
| +
|
| + -- Function: Block.is_valid ()
|
| + Returns `True' if the `gdb.Block' object is valid, `False' if not.
|
| + A block object can become invalid if the block it refers to
|
| + doesn't exist anymore in the inferior. All other `gdb.Block'
|
| + methods will throw an exception if it is invalid at the time the
|
| + method is called. The block's validity is also checked during
|
| + iteration over symbols of the block.
|
| +
|
| + A `gdb.Block' object has the following attributes:
|
| +
|
| + -- Variable: Block.start
|
| + The start address of the block. This attribute is not writable.
|
| +
|
| + -- Variable: Block.end
|
| + The end address of the block. This attribute is not writable.
|
| +
|
| + -- Variable: Block.function
|
| + The name of the block represented as a `gdb.Symbol'. If the block
|
| + is not named, then this attribute holds `None'. This attribute is
|
| + not writable.
|
| +
|
| + For ordinary function blocks, the superblock is the static block.
|
| + However, you should note that it is possible for a function block
|
| + to have a superblock that is not the static block - for instance
|
| + this happens for an inlined function.
|
| +
|
| + -- Variable: Block.superblock
|
| + The block containing this block. If this parent block does not
|
| + exist, this attribute holds `None'. This attribute is not
|
| + writable.
|
| +
|
| + -- Variable: Block.global_block
|
| + The global block associated with this block. This attribute is not
|
| + writable.
|
| +
|
| + -- Variable: Block.static_block
|
| + The static block associated with this block. This attribute is not
|
| + writable.
|
| +
|
| + -- Variable: Block.is_global
|
| + `True' if the `gdb.Block' object is a global block, `False' if
|
| + not. This attribute is not writable.
|
| +
|
| + -- Variable: Block.is_static
|
| + `True' if the `gdb.Block' object is a static block, `False' if
|
| + not. This attribute is not writable.
|
| +
|
| +
|
| +File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API
|
| +
|
| +23.2.2.22 Python representation of Symbols.
|
| +...........................................
|
| +
|
| +GDB represents every variable, function and type as an entry in a
|
| +symbol table. *Note Examining the Symbol Table: Symbols. Similarly,
|
| +Python represents these symbols in GDB with the `gdb.Symbol' object.
|
| +
|
| + The following symbol-related functions are available in the `gdb'
|
| +module:
|
| +
|
| + -- Function: gdb.lookup_symbol (name [, block [, domain]])
|
| + This function searches for a symbol by name. The search scope can
|
| + be restricted to the parameters defined in the optional domain and
|
| + block arguments.
|
| +
|
| + NAME is the name of the symbol. It must be a string. The
|
| + optional BLOCK argument restricts the search to symbols visible in
|
| + that BLOCK. The BLOCK argument must be a `gdb.Block' object. If
|
| + omitted, the block for the current frame is used. The optional
|
| + DOMAIN argument restricts the search to the domain type. The
|
| + DOMAIN argument must be a domain constant defined in the `gdb'
|
| + module and described later in this chapter.
|
| +
|
| + The result is a tuple of two elements. The first element is a
|
| + `gdb.Symbol' object or `None' if the symbol is not found. If the
|
| + symbol is found, the second element is `True' if the symbol is a
|
| + field of a method's object (e.g., `this' in C++), otherwise it is
|
| + `False'. If the symbol is not found, the second element is
|
| + `False'.
|
| +
|
| + -- Function: gdb.lookup_global_symbol (name [, domain])
|
| + This function searches for a global symbol by name. The search
|
| + scope can be restricted to by the domain argument.
|
| +
|
| + NAME is the name of the symbol. It must be a string. The
|
| + optional DOMAIN argument restricts the search to the domain type.
|
| + The DOMAIN argument must be a domain constant defined in the `gdb'
|
| + module and described later in this chapter.
|
| +
|
| + The result is a `gdb.Symbol' object or `None' if the symbol is not
|
| + found.
|
| +
|
| + A `gdb.Symbol' object has the following attributes:
|
| +
|
| + -- Variable: Symbol.type
|
| + The type of the symbol or `None' if no type is recorded. This
|
| + attribute is represented as a `gdb.Type' object. *Note Types In
|
| + Python::. This attribute is not writable.
|
| +
|
| + -- Variable: Symbol.symtab
|
| + The symbol table in which the symbol appears. This attribute is
|
| + represented as a `gdb.Symtab' object. *Note Symbol Tables In
|
| + Python::. This attribute is not writable.
|
| +
|
| + -- Variable: Symbol.line
|
| + The line number in the source code at which the symbol was defined.
|
| + This is an integer.
|
| +
|
| + -- Variable: Symbol.name
|
| + The name of the symbol as a string. This attribute is not
|
| + writable.
|
| +
|
| + -- Variable: Symbol.linkage_name
|
| + The name of the symbol, as used by the linker (i.e., may be
|
| + mangled). This attribute is not writable.
|
| +
|
| + -- Variable: Symbol.print_name
|
| + The name of the symbol in a form suitable for output. This is
|
| + either `name' or `linkage_name', depending on whether the user
|
| + asked GDB to display demangled or mangled names.
|
| +
|
| + -- Variable: Symbol.addr_class
|
| + The address class of the symbol. This classifies how to find the
|
| + value of a symbol. Each address class is a constant defined in the
|
| + `gdb' module and described later in this chapter.
|
| +
|
| + -- Variable: Symbol.needs_frame
|
| + This is `True' if evaluating this symbol's value requires a frame
|
| + (*note Frames In Python::) and `False' otherwise. Typically,
|
| + local variables will require a frame, but other symbols will not.
|
| +
|
| + -- Variable: Symbol.is_argument
|
| + `True' if the symbol is an argument of a function.
|
| +
|
| + -- Variable: Symbol.is_constant
|
| + `True' if the symbol is a constant.
|
| +
|
| + -- Variable: Symbol.is_function
|
| + `True' if the symbol is a function or a method.
|
| +
|
| + -- Variable: Symbol.is_variable
|
| + `True' if the symbol is a variable.
|
| +
|
| + A `gdb.Symbol' object has the following methods:
|
| +
|
| + -- Function: Symbol.is_valid ()
|
| + Returns `True' if the `gdb.Symbol' object is valid, `False' if
|
| + not. A `gdb.Symbol' object can become invalid if the symbol it
|
| + refers to does not exist in GDB any longer. All other
|
| + `gdb.Symbol' methods will throw an exception if it is invalid at
|
| + the time the method is called.
|
| +
|
| + -- Function: Symbol.value ([frame])
|
| + Compute the value of the symbol, as a `gdb.Value'. For functions,
|
| + this computes the address of the function, cast to the appropriate
|
| + type. If the symbol requires a frame in order to compute its
|
| + value, then FRAME must be given. If FRAME is not given, or if
|
| + FRAME is invalid, then this method will throw an exception.
|
| +
|
| + The available domain categories in `gdb.Symbol' are represented as
|
| +constants in the `gdb' module:
|
| +
|
| +`gdb.SYMBOL_UNDEF_DOMAIN'
|
| + This is used when a domain has not been discovered or none of the
|
| + following domains apply. This usually indicates an error either
|
| + in the symbol information or in GDB's handling of symbols.
|
| +
|
| +`gdb.SYMBOL_VAR_DOMAIN'
|
| + This domain contains variables, function names, typedef names and
|
| + enum type values.
|
| +
|
| +`gdb.SYMBOL_STRUCT_DOMAIN'
|
| + This domain holds struct, union and enum type names.
|
| +
|
| +`gdb.SYMBOL_LABEL_DOMAIN'
|
| + This domain contains names of labels (for gotos).
|
| +
|
| +`gdb.SYMBOL_VARIABLES_DOMAIN'
|
| + This domain holds a subset of the `SYMBOLS_VAR_DOMAIN'; it
|
| + contains everything minus functions and types.
|
| +
|
| +`gdb.SYMBOL_FUNCTION_DOMAIN'
|
| + This domain contains all functions.
|
| +
|
| +`gdb.SYMBOL_TYPES_DOMAIN'
|
| + This domain contains all types.
|
| +
|
| + The available address class categories in `gdb.Symbol' are
|
| +represented as constants in the `gdb' module:
|
| +
|
| +`gdb.SYMBOL_LOC_UNDEF'
|
| + If this is returned by address class, it indicates an error either
|
| + in the symbol information or in GDB's handling of symbols.
|
| +
|
| +`gdb.SYMBOL_LOC_CONST'
|
| + Value is constant int.
|
| +
|
| +`gdb.SYMBOL_LOC_STATIC'
|
| + Value is at a fixed address.
|
| +
|
| +`gdb.SYMBOL_LOC_REGISTER'
|
| + Value is in a register.
|
| +
|
| +`gdb.SYMBOL_LOC_ARG'
|
| + Value is an argument. This value is at the offset stored within
|
| + the symbol inside the frame's argument list.
|
| +
|
| +`gdb.SYMBOL_LOC_REF_ARG'
|
| + Value address is stored in the frame's argument list. Just like
|
| + `LOC_ARG' except that the value's address is stored at the offset,
|
| + not the value itself.
|
| +
|
| +`gdb.SYMBOL_LOC_REGPARM_ADDR'
|
| + Value is a specified register. Just like `LOC_REGISTER' except
|
| + the register holds the address of the argument instead of the
|
| + argument itself.
|
| +
|
| +`gdb.SYMBOL_LOC_LOCAL'
|
| + Value is a local variable.
|
| +
|
| +`gdb.SYMBOL_LOC_TYPEDEF'
|
| + Value not used. Symbols in the domain `SYMBOL_STRUCT_DOMAIN' all
|
| + have this class.
|
| +
|
| +`gdb.SYMBOL_LOC_BLOCK'
|
| + Value is a block.
|
| +
|
| +`gdb.SYMBOL_LOC_CONST_BYTES'
|
| + Value is a byte-sequence.
|
| +
|
| +`gdb.SYMBOL_LOC_UNRESOLVED'
|
| + Value is at a fixed address, but the address of the variable has
|
| + to be determined from the minimal symbol table whenever the
|
| + variable is referenced.
|
| +
|
| +`gdb.SYMBOL_LOC_OPTIMIZED_OUT'
|
| + The value does not actually exist in the program.
|
| +
|
| +`gdb.SYMBOL_LOC_COMPUTED'
|
| + The value's address is a computed location.
|
| +
|
| +
|
| +File: gdb.info, Node: Symbol Tables In Python, Next: Line Tables In Python, Prev: Symbols In Python, Up: Python API
|
| +
|
| +23.2.2.23 Symbol table representation in Python.
|
| +................................................
|
| +
|
| +Access to symbol table data maintained by GDB on the inferior is
|
| +exposed to Python via two objects: `gdb.Symtab_and_line' and
|
| +`gdb.Symtab'. Symbol table and line data for a frame is returned from
|
| +the `find_sal' method in `gdb.Frame' object. *Note Frames In Python::.
|
| +
|
| + For more information on GDB's symbol table management, see *note
|
| +Examining the Symbol Table: Symbols, for more information.
|
| +
|
| + A `gdb.Symtab_and_line' object has the following attributes:
|
| +
|
| + -- Variable: Symtab_and_line.symtab
|
| + The symbol table object (`gdb.Symtab') for this frame. This
|
| + attribute is not writable.
|
| +
|
| + -- Variable: Symtab_and_line.pc
|
| + Indicates the start of the address range occupied by code for the
|
| + current source line. This attribute is not writable.
|
| +
|
| + -- Variable: Symtab_and_line.last
|
| + Indicates the end of the address range occupied by code for the
|
| + current source line. This attribute is not writable.
|
| +
|
| + -- Variable: Symtab_and_line.line
|
| + Indicates the current line number for this object. This attribute
|
| + is not writable.
|
| +
|
| + A `gdb.Symtab_and_line' object has the following methods:
|
| +
|
| + -- Function: Symtab_and_line.is_valid ()
|
| + Returns `True' if the `gdb.Symtab_and_line' object is valid,
|
| + `False' if not. A `gdb.Symtab_and_line' object can become invalid
|
| + if the Symbol table and line object it refers to does not exist in
|
| + GDB any longer. All other `gdb.Symtab_and_line' methods will
|
| + throw an exception if it is invalid at the time the method is
|
| + called.
|
| +
|
| + A `gdb.Symtab' object has the following attributes:
|
| +
|
| + -- Variable: Symtab.filename
|
| + The symbol table's source filename. This attribute is not
|
| + writable.
|
| +
|
| + -- Variable: Symtab.objfile
|
| + The symbol table's backing object file. *Note Objfiles In
|
| + Python::. This attribute is not writable.
|
| +
|
| + A `gdb.Symtab' object has the following methods:
|
| +
|
| + -- Function: Symtab.is_valid ()
|
| + Returns `True' if the `gdb.Symtab' object is valid, `False' if
|
| + not. A `gdb.Symtab' object can become invalid if the symbol table
|
| + it refers to does not exist in GDB any longer. All other
|
| + `gdb.Symtab' methods will throw an exception if it is invalid at
|
| + the time the method is called.
|
| +
|
| + -- Function: Symtab.fullname ()
|
| + Return the symbol table's source absolute file name.
|
| +
|
| + -- Function: Symtab.global_block ()
|
| + Return the global block of the underlying symbol table. *Note
|
| + Blocks In Python::.
|
| +
|
| + -- Function: Symtab.static_block ()
|
| + Return the static block of the underlying symbol table. *Note
|
| + Blocks In Python::.
|
| +
|
| + -- Function: Symtab.linetable ()
|
| + Return the line table associated with the symbol table. *Note
|
| + Line Tables In Python::.
|
| +
|
| +
|
| +File: gdb.info, Node: Line Tables In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API
|
| +
|
| +23.2.2.24 Manipulating line tables using Python
|
| +...............................................
|
| +
|
| +Python code can request and inspect line table information from a
|
| +symbol table that is loaded in GDB. A line table is a mapping of
|
| +source lines to their executable locations in memory. To acquire the
|
| +line table information for a particular symbol table, use the
|
| +`linetable' function (*note Symbol Tables In Python::).
|
| +
|
| + A `gdb.LineTable' is iterable. The iterator returns
|
| +`LineTableEntry' objects that correspond to the source line and address
|
| +for each line table entry. `LineTableEntry' objects have the following
|
| +attributes:
|
| +
|
| + -- Variable: LineTableEntry.line
|
| + The source line number for this line table entry. This number
|
| + corresponds to the actual line of source. This attribute is not
|
| + writable.
|
| +
|
| + -- Variable: LineTableEntry.pc
|
| + The address that is associated with the line table entry where the
|
| + executable code for that source line resides in memory. This
|
| + attribute is not writable.
|
| +
|
| + As there can be multiple addresses for a single source line, you may
|
| +receive multiple `LineTableEntry' objects with matching `line'
|
| +attributes, but with different `pc' attributes. The iterator is sorted
|
| +in ascending `pc' order. Here is a small example illustrating
|
| +iterating over a line table.
|
| +
|
| + symtab = gdb.selected_frame().find_sal().symtab
|
| + linetable = symtab.linetable()
|
| + for line in linetable:
|
| + print "Line: "+str(line.line)+" Address: "+hex(line.pc)
|
| +
|
| + This will have the following output:
|
| +
|
| + Line: 33 Address: 0x4005c8L
|
| + Line: 37 Address: 0x4005caL
|
| + Line: 39 Address: 0x4005d2L
|
| + Line: 40 Address: 0x4005f8L
|
| + Line: 42 Address: 0x4005ffL
|
| + Line: 44 Address: 0x400608L
|
| + Line: 42 Address: 0x40060cL
|
| + Line: 45 Address: 0x400615L
|
| +
|
| + In addition to being able to iterate over a `LineTable', it also has
|
| +the following direct access methods:
|
| +
|
| + -- Function: LineTable.line (line)
|
| + Return a Python `Tuple' of `LineTableEntry' objects for any
|
| + entries in the line table for the given LINE. LINE refers to the
|
| + source code line. If there are no entries for that source code
|
| + LINE, the Python `None' is returned.
|
| +
|
| + -- Function: LineTable.has_line (line)
|
| + Return a Python `Boolean' indicating whether there is an entry in
|
| + the line table for this source line. Return `True' if an entry is
|
| + found, or `False' if not.
|
| +
|
| + -- Function: LineTable.source_lines ()
|
| + Return a Python `List' of the source line numbers in the symbol
|
| + table. Only lines with executable code locations are returned.
|
| + The contents of the `List' will just be the source line entries
|
| + represented as Python `Long' values.
|
| +
|
| +
|
| +File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Line Tables In Python, Up: Python API
|
| +
|
| +23.2.2.25 Manipulating breakpoints using Python
|
| +...............................................
|
| +
|
| +Python code can manipulate breakpoints via the `gdb.Breakpoint' class.
|
| +
|
| + -- Function: Breakpoint.__init__ (spec [, type [, wp_class [,internal
|
| + [,temporary]]]])
|
| + Create a new breakpoint. SPEC is a string naming the location of
|
| + the breakpoint, or an expression that defines a watchpoint. The
|
| + contents can be any location recognized by the `break' command, or
|
| + in the case of a watchpoint, by the `watch' command. The optional
|
| + TYPE denotes the breakpoint to create from the types defined later
|
| + in this chapter. This argument can be either: `gdb.BP_BREAKPOINT'
|
| + or `gdb.BP_WATCHPOINT'. TYPE defaults to `gdb.BP_BREAKPOINT'.
|
| + The optional INTERNAL argument allows the breakpoint to become
|
| + invisible to the user. The breakpoint will neither be reported
|
| + when created, nor will it be listed in the output from `info
|
| + breakpoints' (but will be listed with the `maint info breakpoints'
|
| + command). The optional TEMPORARY argument makes the breakpoint a
|
| + temporary breakpoint. Temporary breakpoints are deleted after
|
| + they have been hit. Any further access to the Python breakpoint
|
| + after it has been hit will result in a runtime error (as that
|
| + breakpoint has now been automatically deleted). The optional
|
| + WP_CLASS argument defines the class of watchpoint to create, if
|
| + TYPE is `gdb.BP_WATCHPOINT'. If a watchpoint class is not
|
| + provided, it is assumed to be a `gdb.WP_WRITE' class.
|
| +
|
| + -- Function: Breakpoint.stop (self)
|
| + The `gdb.Breakpoint' class can be sub-classed and, in particular,
|
| + you may choose to implement the `stop' method. If this method is
|
| + defined in a sub-class of `gdb.Breakpoint', it will be called when
|
| + the inferior reaches any location of a breakpoint which
|
| + instantiates that sub-class. If the method returns `True', the
|
| + inferior will be stopped at the location of the breakpoint,
|
| + otherwise the inferior will continue.
|
| +
|
| + If there are multiple breakpoints at the same location with a
|
| + `stop' method, each one will be called regardless of the return
|
| + status of the previous. This ensures that all `stop' methods have
|
| + a chance to execute at that location. In this scenario if one of
|
| + the methods returns `True' but the others return `False', the
|
| + inferior will still be stopped.
|
| +
|
| + You should not alter the execution state of the inferior (i.e.,
|
| + step, next, etc.), alter the current frame context (i.e., change
|
| + the current active frame), or alter, add or delete any breakpoint.
|
| + As a general rule, you should not alter any data within GDB or the
|
| + inferior at this time.
|
| +
|
| + Example `stop' implementation:
|
| +
|
| + class MyBreakpoint (gdb.Breakpoint):
|
| + def stop (self):
|
| + inf_val = gdb.parse_and_eval("foo")
|
| + if inf_val == 3:
|
| + return True
|
| + return False
|
| +
|
| + The available watchpoint types represented by constants are defined
|
| +in the `gdb' module:
|
| +
|
| +`gdb.WP_READ'
|
| + Read only watchpoint.
|
| +
|
| +`gdb.WP_WRITE'
|
| + Write only watchpoint.
|
| +
|
| +`gdb.WP_ACCESS'
|
| + Read/Write watchpoint.
|
| +
|
| + -- Function: Breakpoint.is_valid ()
|
| + Return `True' if this `Breakpoint' object is valid, `False'
|
| + otherwise. A `Breakpoint' object can become invalid if the user
|
| + deletes the breakpoint. In this case, the object still exists,
|
| + but the underlying breakpoint does not. In the cases of
|
| + watchpoint scope, the watchpoint remains valid even if execution
|
| + of the inferior leaves the scope of that watchpoint.
|
| +
|
| + -- Function: Breakpoint.delete
|
| + Permanently deletes the GDB breakpoint. This also invalidates the
|
| + Python `Breakpoint' object. Any further access to this object's
|
| + attributes or methods will raise an error.
|
| +
|
| + -- Variable: Breakpoint.enabled
|
| + This attribute is `True' if the breakpoint is enabled, and `False'
|
| + otherwise. This attribute is writable.
|
| +
|
| + -- Variable: Breakpoint.silent
|
| + This attribute is `True' if the breakpoint is silent, and `False'
|
| + otherwise. This attribute is writable.
|
| +
|
| + Note that a breakpoint can also be silent if it has commands and
|
| + the first command is `silent'. This is not reported by the
|
| + `silent' attribute.
|
| +
|
| + -- Variable: Breakpoint.thread
|
| + If the breakpoint is thread-specific, this attribute holds the
|
| + thread id. If the breakpoint is not thread-specific, this
|
| + attribute is `None'. This attribute is writable.
|
| +
|
| + -- Variable: Breakpoint.task
|
| + If the breakpoint is Ada task-specific, this attribute holds the
|
| + Ada task id. If the breakpoint is not task-specific (or the
|
| + underlying language is not Ada), this attribute is `None'. This
|
| + attribute is writable.
|
| +
|
| + -- Variable: Breakpoint.ignore_count
|
| + This attribute holds the ignore count for the breakpoint, an
|
| + integer. This attribute is writable.
|
| +
|
| + -- Variable: Breakpoint.number
|
| + This attribute holds the breakpoint's number -- the identifier
|
| + used by the user to manipulate the breakpoint. This attribute is
|
| + not writable.
|
| +
|
| + -- Variable: Breakpoint.type
|
| + This attribute holds the breakpoint's type -- the identifier used
|
| + to determine the actual breakpoint type or use-case. This
|
| + attribute is not writable.
|
| +
|
| + -- Variable: Breakpoint.visible
|
| + This attribute tells whether the breakpoint is visible to the user
|
| + when set, or when the `info breakpoints' command is run. This
|
| + attribute is not writable.
|
| +
|
| + -- Variable: Breakpoint.temporary
|
| + This attribute indicates whether the breakpoint was created as a
|
| + temporary breakpoint. Temporary breakpoints are automatically
|
| + deleted after that breakpoint has been hit. Access to this
|
| + attribute, and all other attributes and functions other than the
|
| + `is_valid' function, will result in an error after the breakpoint
|
| + has been hit (as it has been automatically deleted). This
|
| + attribute is not writable.
|
| +
|
| + The available types are represented by constants defined in the `gdb'
|
| +module:
|
| +
|
| +`gdb.BP_BREAKPOINT'
|
| + Normal code breakpoint.
|
| +
|
| +`gdb.BP_WATCHPOINT'
|
| + Watchpoint breakpoint.
|
| +
|
| +`gdb.BP_HARDWARE_WATCHPOINT'
|
| + Hardware assisted watchpoint.
|
| +
|
| +`gdb.BP_READ_WATCHPOINT'
|
| + Hardware assisted read watchpoint.
|
| +
|
| +`gdb.BP_ACCESS_WATCHPOINT'
|
| + Hardware assisted access watchpoint.
|
| +
|
| + -- Variable: Breakpoint.hit_count
|
| + This attribute holds the hit count for the breakpoint, an integer.
|
| + This attribute is writable, but currently it can only be set to
|
| + zero.
|
| +
|
| + -- Variable: Breakpoint.location
|
| + This attribute holds the location of the breakpoint, as specified
|
| + by the user. It is a string. If the breakpoint does not have a
|
| + location (that is, it is a watchpoint) the attribute's value is
|
| + `None'. This attribute is not writable.
|
| +
|
| + -- Variable: Breakpoint.expression
|
| + This attribute holds a breakpoint expression, as specified by the
|
| + user. It is a string. If the breakpoint does not have an
|
| + expression (the breakpoint is not a watchpoint) the attribute's
|
| + value is `None'. This attribute is not writable.
|
| +
|
| + -- Variable: Breakpoint.condition
|
| + This attribute holds the condition of the breakpoint, as specified
|
| + by the user. It is a string. If there is no condition, this
|
| + attribute's value is `None'. This attribute is writable.
|
| +
|
| + -- Variable: Breakpoint.commands
|
| + This attribute holds the commands attached to the breakpoint. If
|
| + there are commands, this attribute's value is a string holding all
|
| + the commands, separated by newlines. If there are no commands,
|
| + this attribute is `None'. This attribute is not writable.
|
| +
|
| +
|
| +File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API
|
| +
|
| +23.2.2.26 Finish Breakpoints
|
| +............................
|
| +
|
| +A finish breakpoint is a temporary breakpoint set at the return address
|
| +of a frame, based on the `finish' command. `gdb.FinishBreakpoint'
|
| +extends `gdb.Breakpoint'. The underlying breakpoint will be disabled
|
| +and deleted when the execution will run out of the breakpoint scope
|
| +(i.e. `Breakpoint.stop' or `FinishBreakpoint.out_of_scope' triggered).
|
| +Finish breakpoints are thread specific and must be create with the right
|
| +thread selected.
|
| +
|
| + -- Function: FinishBreakpoint.__init__ ([frame] [, internal])
|
| + Create a finish breakpoint at the return address of the `gdb.Frame'
|
| + object FRAME. If FRAME is not provided, this defaults to the
|
| + newest frame. The optional INTERNAL argument allows the
|
| + breakpoint to become invisible to the user. *Note Breakpoints In
|
| + Python::, for further details about this argument.
|
| +
|
| + -- Function: FinishBreakpoint.out_of_scope (self)
|
| + In some circumstances (e.g. `longjmp', C++ exceptions, GDB
|
| + `return' command, ...), a function may not properly terminate, and
|
| + thus never hit the finish breakpoint. When GDB notices such a
|
| + situation, the `out_of_scope' callback will be triggered.
|
| +
|
| + You may want to sub-class `gdb.FinishBreakpoint' and override this
|
| + method:
|
| +
|
| + class MyFinishBreakpoint (gdb.FinishBreakpoint)
|
| + def stop (self):
|
| + print "normal finish"
|
| + return True
|
| +
|
| + def out_of_scope ():
|
| + print "abnormal finish"
|
| +
|
| + -- Variable: FinishBreakpoint.return_value
|
| + When GDB is stopped at a finish breakpoint and the frame used to
|
| + build the `gdb.FinishBreakpoint' object had debug symbols, this
|
| + attribute will contain a `gdb.Value' object corresponding to the
|
| + return value of the function. The value will be `None' if the
|
| + function return type is `void' or if the return value was not
|
| + computable. This attribute is not writable.
|
| +
|
| +
|
| +File: gdb.info, Node: Lazy Strings In Python, Next: Architectures In Python, Prev: Finish Breakpoints in Python, Up: Python API
|
| +
|
| +23.2.2.27 Python representation of lazy strings.
|
| +................................................
|
| +
|
| +A "lazy string" is a string whose contents is not retrieved or encoded
|
| +until it is needed.
|
| +
|
| + A `gdb.LazyString' is represented in GDB as an `address' that points
|
| +to a region of memory, an `encoding' that will be used to encode that
|
| +region of memory, and a `length' to delimit the region of memory that
|
| +represents the string. The difference between a `gdb.LazyString' and a
|
| +string wrapped within a `gdb.Value' is that a `gdb.LazyString' will be
|
| +treated differently by GDB when printing. A `gdb.LazyString' is
|
| +retrieved and encoded during printing, while a `gdb.Value' wrapping a
|
| +string is immediately retrieved and encoded on creation.
|
| +
|
| + A `gdb.LazyString' object has the following functions:
|
| +
|
| + -- Function: LazyString.value ()
|
| + Convert the `gdb.LazyString' to a `gdb.Value'. This value will
|
| + point to the string in memory, but will lose all the delayed
|
| + retrieval, encoding and handling that GDB applies to a
|
| + `gdb.LazyString'.
|
| +
|
| + -- Variable: LazyString.address
|
| + This attribute holds the address of the string. This attribute is
|
| + not writable.
|
| +
|
| + -- Variable: LazyString.length
|
| + This attribute holds the length of the string in characters. If
|
| + the length is -1, then the string will be fetched and encoded up
|
| + to the first null of appropriate width. This attribute is not
|
| + writable.
|
| +
|
| + -- Variable: LazyString.encoding
|
| + This attribute holds the encoding that will be applied to the
|
| + string when the string is printed by GDB. If the encoding is not
|
| + set, or contains an empty string, then GDB will select the most
|
| + appropriate encoding when the string is printed. This attribute
|
| + is not writable.
|
| +
|
| + -- Variable: LazyString.type
|
| + This attribute holds the type that is represented by the lazy
|
| + string's type. For a lazy string this will always be a pointer
|
| + type. To resolve this to the lazy string's character type, use
|
| + the type's `target' method. *Note Types In Python::. This
|
| + attribute is not writable.
|
| +
|
| +
|
| +File: gdb.info, Node: Architectures In Python, Prev: Lazy Strings In Python, Up: Python API
|
| +
|
| +23.2.2.28 Python representation of architectures
|
| +................................................
|
| +
|
| +GDB uses architecture specific parameters and artifacts in a number of
|
| +its various computations. An architecture is represented by an
|
| +instance of the `gdb.Architecture' class.
|
| +
|
| + A `gdb.Architecture' class has the following methods:
|
| +
|
| + -- Function: Architecture.name ()
|
| + Return the name (string value) of the architecture.
|
| +
|
| + -- Function: Architecture.disassemble (START_PC [, END_PC [, COUNT]])
|
| + Return a list of disassembled instructions starting from the memory
|
| + address START_PC. The optional arguments END_PC and COUNT
|
| + determine the number of instructions in the returned list. If
|
| + both the optional arguments END_PC and COUNT are specified, then a
|
| + list of at most COUNT disassembled instructions whose start
|
| + address falls in the closed memory address interval from START_PC
|
| + to END_PC are returned. If END_PC is not specified, but COUNT is
|
| + specified, then COUNT number of instructions starting from the
|
| + address START_PC are returned. If COUNT is not specified but
|
| + END_PC is specified, then all instructions whose start address
|
| + falls in the closed memory address interval from START_PC to
|
| + END_PC are returned. If neither END_PC nor COUNT are specified,
|
| + then a single instruction at START_PC is returned. For all of
|
| + these cases, each element of the returned list is a Python `dict'
|
| + with the following string keys:
|
| +
|
| + `addr'
|
| + The value corresponding to this key is a Python long integer
|
| + capturing the memory address of the instruction.
|
| +
|
| + `asm'
|
| + The value corresponding to this key is a string value which
|
| + represents the instruction with assembly language mnemonics.
|
| + The assembly language flavor used is the same as that
|
| + specified by the current CLI variable `disassembly-flavor'.
|
| + *Note Machine Code::.
|
| +
|
| + `length'
|
| + The value corresponding to this key is the length (integer
|
| + value) of the instruction in bytes.
|
| +
|
| +
|
| +
|
| +File: gdb.info, Node: Python Auto-loading, Next: Python modules, Prev: Python API, Up: Python
|
| +
|
| +23.2.3 Python Auto-loading
|
| +--------------------------
|
| +
|
| +When a new object file is read (for example, due to the `file' command,
|
| +or because the inferior has loaded a shared library), GDB will look for
|
| +Python support scripts in several ways: `OBJFILE-gdb.py' (*note
|
| +objfile-gdb.py file::) and `.debug_gdb_scripts' section (*note
|
| +dotdebug_gdb_scripts section::).
|
| +
|
| + The auto-loading feature is useful for supplying application-specific
|
| +debugging commands and scripts.
|
| +
|
| + Auto-loading can be enabled or disabled, and the list of auto-loaded
|
| +scripts can be printed.
|
| +
|
| +`set auto-load python-scripts [on|off]'
|
| + Enable or disable the auto-loading of Python scripts.
|
| +
|
| +`show auto-load python-scripts'
|
| + Show whether auto-loading of Python scripts is enabled or disabled.
|
| +
|
| +`info auto-load python-scripts [REGEXP]'
|
| + Print the list of all Python scripts that GDB auto-loaded.
|
| +
|
| + Also printed is the list of Python scripts that were mentioned in
|
| + the `.debug_gdb_scripts' section and were not found (*note
|
| + dotdebug_gdb_scripts section::). This is useful because their
|
| + names are not printed when GDB tries to load them and fails.
|
| + There may be many of them, and printing an error message for each
|
| + one is problematic.
|
| +
|
| + If REGEXP is supplied only Python scripts with matching names are
|
| + printed.
|
| +
|
| + Example:
|
| +
|
| + (gdb) info auto-load python-scripts
|
| + Loaded Script
|
| + Yes py-section-script.py
|
| + full name: /tmp/py-section-script.py
|
| + No my-foo-pretty-printers.py
|
| +
|
| + When reading an auto-loaded file, GDB sets the "current objfile".
|
| +This is available via the `gdb.current_objfile' function (*note
|
| +Objfiles In Python::). This can be useful for registering
|
| +objfile-specific pretty-printers and frame-filters.
|
| +
|
| +* Menu:
|
| +
|
| +* objfile-gdb.py file:: The `OBJFILE-gdb.py' file
|
| +* dotdebug_gdb_scripts section:: The `.debug_gdb_scripts' section
|
| +* Which flavor to choose?::
|
| +
|
| +
|
| File: gdb.info, Node: objfile-gdb.py file, Next: dotdebug_gdb_scripts section, Up: Python Auto-loading
|
|
|
| 23.2.3.1 The `OBJFILE-gdb.py' file
|
| @@ -242,7 +2262,7 @@ File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: P
|
| ..................
|
|
|
| This module provides a collection of utilities for working with
|
| -`gdb.Types' objects.
|
| +`gdb.Type' objects.
|
|
|
| `get_basic_type (TYPE)'
|
| Return TYPE with const and volatile qualifiers stripped, and with
|
| @@ -293,6 +2313,35 @@ This module provides a collection of utilities for working with
|
| (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)]
|
| {['a', 'b0', 'b1']}
|
|
|
| +`get_type_recognizers ()'
|
| + Return a list of the enabled type recognizers for the current
|
| + context. This is called by GDB during the type-printing process
|
| + (*note Type Printing API::).
|
| +
|
| +`apply_type_recognizers (recognizers, type_obj)'
|
| + Apply the type recognizers, RECOGNIZERS, to the type object
|
| + TYPE_OBJ. If any recognizer returns a string, return that string.
|
| + Otherwise, return `None'. This is called by GDB during the
|
| + type-printing process (*note Type Printing API::).
|
| +
|
| +`register_type_printer (locus, printer)'
|
| + This is a convenience function to register a type printer.
|
| + PRINTER is the type printer to register. It must implement the
|
| + type printer protocol. LOCUS is either a `gdb.Objfile', in which
|
| + case the printer is registered with that objfile; a
|
| + `gdb.Progspace', in which case the printer is registered with that
|
| + progspace; or `None', in which case the printer is registered
|
| + globally.
|
| +
|
| +`TypePrinter'
|
| + This is a base class that implements the type printer protocol.
|
| + Type printers are encouraged, but not required, to derive from
|
| + this class. It defines a constructor:
|
| +
|
| + -- Method on TypePrinter: __init__ (self, name)
|
| + Initialize the type printer with the given name. The new
|
| + printer starts in the enabled state.
|
| +
|
|
|
|
|
| File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules
|
| @@ -462,7 +2511,7 @@ include:
|
| `mi'
|
| The newest GDB/MI interface (currently `mi2'). Used primarily by
|
| programs wishing to use GDB as a backend for a debugger GUI or an
|
| - IDE. For more information, see *Note The GDB/MI Interface: GDB/MI.
|
| + IDE. For more information, see *note The GDB/MI Interface: GDB/MI.
|
|
|
| `mi2'
|
| The current GDB/MI interface.
|
| @@ -1037,6 +3086,7 @@ This chapter uses the following notation:
|
| * GDB/MI Simple Examples::
|
| * GDB/MI Command Description Format::
|
| * GDB/MI Breakpoint Commands::
|
| +* GDB/MI Catchpoint Commands::
|
| * GDB/MI Program Context::
|
| * GDB/MI Thread Commands::
|
| * GDB/MI Ada Tasking Commands::
|
| @@ -1049,6 +3099,7 @@ This chapter uses the following notation:
|
| * GDB/MI File Commands::
|
| * GDB/MI Target Manipulation::
|
| * GDB/MI File Transfer Commands::
|
| +* GDB/MI Ada Exceptions Commands::
|
| * GDB/MI Miscellaneous Commands::
|
|
|
|
|
| @@ -1111,6 +3162,9 @@ File: gdb.info, Node: Context management, Next: Asynchronous and non-stop mode
|
| 27.1.1 Context management
|
| -------------------------
|
|
|
| +27.1.1.1 Threads and Frames
|
| +...........................
|
| +
|
| In most cases when GDB accesses the target, this access is done in
|
| context of a specific thread and frame (*note Frames::). Often, even
|
| when accessing global data, the target requires that a thread be
|
| @@ -1159,6 +3213,23 @@ add `-thread-select' for all subsequent commands. No frontend is known
|
| to do this exactly right, so it is suggested to just always pass the
|
| `--thread' and `--frame' options.
|
|
|
| +27.1.1.2 Language
|
| +.................
|
| +
|
| +The execution of several commands depends on which language is selected.
|
| +By default, the current language (*note show language::) is used. But
|
| +for commands known to be language-sensitive, it is recommended to use
|
| +the `--language' option. This option takes one argument, which is the
|
| +name of the language to use while executing the command. For instance:
|
| +
|
| + -data-evaluate-expression --language c "sizeof (void*)"
|
| + ^done,value="4"
|
| + (gdb)
|
| +
|
| + The valid language names are the same names accepted by the `set
|
| +language' command (*note Manually::), excluding `auto', `local' or
|
| +`unknown'.
|
| +
|
|
|
| File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design
|
|
|
| @@ -1497,6 +3568,7 @@ File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Pr
|
| * GDB/MI Result Records::
|
| * GDB/MI Stream Records::
|
| * GDB/MI Async Records::
|
| +* GDB/MI Breakpoint Information::
|
| * GDB/MI Frame Information::
|
| * GDB/MI Thread Information::
|
| * GDB/MI Ada Exception Information::
|
| @@ -1525,9 +3597,16 @@ GDB/MI command includes one of the following result indications:
|
| `"^connected"'
|
| GDB has connected to a remote target.
|
|
|
| -`"^error" "," C-STRING'
|
| - The operation failed. The `C-STRING' contains the corresponding
|
| - error message.
|
| +`"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]'
|
| + The operation failed. The `msg=C-STRING' variable contains the
|
| + corresponding error message.
|
| +
|
| + If present, the `code=C-STRING' variable provides an error code on
|
| + which consumers can rely on to detect the corresponding error
|
| + condition. At present, only one error code is defined:
|
| +
|
| + `"undefined-command"'
|
| + Indicates that the command causing the error does not exist.
|
|
|
| `"^exit"'
|
| GDB has terminated.
|
| @@ -1565,7 +3644,7 @@ or a quoted C string (which does not contain an implicit newline).
|
| internals.
|
|
|
|
|
| -File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Frame Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
|
| +File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Breakpoint Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
|
|
|
| 27.5.3 GDB/MI Async Records
|
| ---------------------------
|
| @@ -1732,24 +3811,188 @@ activity (e.g., target stopped).
|
| absent, it means the library was unloaded in the context of all
|
| present thread groups.
|
|
|
| -`=breakpoint-created,bkpt={...}'
|
| -`=breakpoint-modified,bkpt={...}'
|
| -`=breakpoint-deleted,bkpt={...}'
|
| - Reports that a breakpoint was created, modified, or deleted,
|
| +`=traceframe-changed,num=TFNUM,tracepoint=TPNUM'
|
| +`=traceframe-changed,end'
|
| + Reports that the trace frame was changed and its new number is
|
| + TFNUM. The number of the tracepoint associated with this trace
|
| + frame is TPNUM.
|
| +
|
| +`=tsv-created,name=NAME,initial=INITIAL'
|
| + Reports that the new trace state variable NAME is created with
|
| + initial value INITIAL.
|
| +
|
| +`=tsv-deleted,name=NAME'
|
| +`=tsv-deleted'
|
| + Reports that the trace state variable NAME is deleted or all trace
|
| + state variables are deleted.
|
| +
|
| +`=tsv-modified,name=NAME,initial=INITIAL[,current=CURRENT]'
|
| + Reports that the trace state variable NAME is modified with the
|
| + initial value INITIAL. The current value CURRENT of trace state
|
| + variable is optional and is reported if the current value of trace
|
| + state variable is known.
|
| +
|
| +`=breakpoint-created,bkpt={...}'
|
| +`=breakpoint-modified,bkpt={...}'
|
| +`=breakpoint-deleted,id=NUMBER'
|
| + Reports that a breakpoint was created, modified, or deleted,
|
| respectively. Only user-visible breakpoints are reported to the MI
|
| user.
|
|
|
| The BKPT argument is of the same form as returned by the various
|
| - breakpoint commands; *Note GDB/MI Breakpoint Commands::.
|
| + breakpoint commands; *Note GDB/MI Breakpoint Commands::. The
|
| + NUMBER is the ordinal number of the breakpoint.
|
|
|
| Note that if a breakpoint is emitted in the result record of a
|
| command, then it will not also be emitted in an async record.
|
|
|
| +`=record-started,thread-group="ID"'
|
| +`=record-stopped,thread-group="ID"'
|
| + Execution log recording was either started or stopped on an
|
| + inferior. The ID is the GDB identifier of the thread group
|
| + corresponding to the affected inferior.
|
| +
|
| +`=cmd-param-changed,param=PARAM,value=VALUE'
|
| + Reports that a parameter of the command `set PARAM' is changed to
|
| + VALUE. In the multi-word `set' command, the PARAM is the whole
|
| + parameter list to `set' command. For example, In command `set
|
| + check type on', PARAM is `check type' and VALUE is `on'.
|
| +
|
| +`=memory-changed,thread-group=ID,addr=ADDR,len=LEN[,type="code"]'
|
| + Reports that bytes from ADDR to DATA + LEN were written in an
|
| + inferior. The ID is the identifier of the thread group
|
| + corresponding to the affected inferior. The optional
|
| + `type="code"' part is reported if the memory written to holds
|
| + executable code.
|
| +
|
| +
|
| +File: gdb.info, Node: GDB/MI Breakpoint Information, Next: GDB/MI Frame Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records
|
| +
|
| +27.5.4 GDB/MI Breakpoint Information
|
| +------------------------------------
|
| +
|
| +When GDB reports information about a breakpoint, a tracepoint, a
|
| +watchpoint, or a catchpoint, it uses a tuple with the following fields:
|
| +
|
| +`number'
|
| + The breakpoint number. For a breakpoint that represents one
|
| + location of a multi-location breakpoint, this will be a dotted
|
| + pair, like `1.2'.
|
| +
|
| +`type'
|
| + The type of the breakpoint. For ordinary breakpoints this will be
|
| + `breakpoint', but many values are possible.
|
| +
|
| +`catch-type'
|
| + If the type of the breakpoint is `catchpoint', then this indicates
|
| + the exact type of catchpoint.
|
| +
|
| +`disp'
|
| + This is the breakpoint disposition--either `del', meaning that the
|
| + breakpoint will be deleted at the next stop, or `keep', meaning
|
| + that the breakpoint will not be deleted.
|
| +
|
| +`enabled'
|
| + This indicates whether the breakpoint is enabled, in which case the
|
| + value is `y', or disabled, in which case the value is `n'. Note
|
| + that this is not the same as the field `enable'.
|
| +
|
| +`addr'
|
| + The address of the breakpoint. This may be a hexidecimal number,
|
| + giving the address; or the string `<PENDING>', for a pending
|
| + breakpoint; or the string `<MULTIPLE>', for a breakpoint with
|
| + multiple locations. This field will not be present if no address
|
| + can be determined. For example, a watchpoint does not have an
|
| + address.
|
| +
|
| +`func'
|
| + If known, the function in which the breakpoint appears. If not
|
| + known, this field is not present.
|
| +
|
| +`filename'
|
| + The name of the source file which contains this function, if known.
|
| + If not known, this field is not present.
|
| +
|
| +`fullname'
|
| + The full file name of the source file which contains this
|
| + function, if known. If not known, this field is not present.
|
| +
|
| +`line'
|
| + The line number at which this breakpoint appears, if known. If
|
| + not known, this field is not present.
|
| +
|
| +`at'
|
| + If the source file is not known, this field may be provided. If
|
| + provided, this holds the address of the breakpoint, possibly
|
| + followed by a symbol name.
|
| +
|
| +`pending'
|
| + If this breakpoint is pending, this field is present and holds the
|
| + text used to set the breakpoint, as entered by the user.
|
| +
|
| +`evaluated-by'
|
| + Where this breakpoint's condition is evaluated, either `host' or
|
| + `target'.
|
| +
|
| +`thread'
|
| + If this is a thread-specific breakpoint, then this identifies the
|
| + thread in which the breakpoint can trigger.
|
| +
|
| +`task'
|
| + If this breakpoint is restricted to a particular Ada task, then
|
| + this field will hold the task identifier.
|
| +
|
| +`cond'
|
| + If the breakpoint is conditional, this is the condition expression.
|
| +
|
| +`ignore'
|
| + The ignore count of the breakpoint.
|
| +
|
| +`enable'
|
| + The enable count of the breakpoint.
|
| +
|
| +`traceframe-usage'
|
| + FIXME.
|
| +
|
| +`static-tracepoint-marker-string-id'
|
| + For a static tracepoint, the name of the static tracepoint marker.
|
| +
|
| +`mask'
|
| + For a masked watchpoint, this is the mask.
|
| +
|
| +`pass'
|
| + A tracepoint's pass count.
|
| +
|
| +`original-location'
|
| + The location of the breakpoint as originally specified by the user.
|
| + This field is optional.
|
| +
|
| +`times'
|
| + The number of times the breakpoint has been hit.
|
| +
|
| +`installed'
|
| + This field is only given for tracepoints. This is either `y',
|
| + meaning that the tracepoint is installed, or `n', meaning that it
|
| + is not.
|
| +
|
| +`what'
|
| + Some extra data, the exact contents of which are type-dependent.
|
| +
|
| +
|
| + For example, here is what the output of `-break-insert' (*note
|
| +GDB/MI Breakpoint Commands::) might be:
|
| +
|
| + -> -break-insert main
|
| + <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
|
| + enabled="y",addr="0x08048564",func="main",file="myprog.c",
|
| + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
|
| + times="0"}
|
| + <- (gdb)
|
|
|
|
|
| -File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records
|
| +File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Breakpoint Information, Up: GDB/MI Output Records
|
|
|
| -27.5.4 GDB/MI Frame Information
|
| +27.5.5 GDB/MI Frame Information
|
| -------------------------------
|
|
|
| Response from many MI commands includes an information about stack
|
| @@ -1783,7 +4026,7 @@ frame. This information is a tuple that may have the following fields:
|
|
|
| File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records
|
|
|
| -27.5.5 GDB/MI Thread Information
|
| +27.5.6 GDB/MI Thread Information
|
| --------------------------------
|
|
|
| Whenever GDB has to report an information about a thread, it uses a
|
| @@ -1813,7 +4056,7 @@ tuple with the following fields:
|
|
|
| File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records
|
|
|
| -27.5.6 GDB/MI Ada Exception Information
|
| +27.5.7 GDB/MI Ada Exception Information
|
| ---------------------------------------
|
|
|
| Whenever a `*stopped' record is emitted because the program stopped
|
| @@ -1844,7 +4087,8 @@ detailed information of the breakpoint.
|
| -> -break-insert main
|
| <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
|
| enabled="y",addr="0x08048564",func="main",file="myprog.c",
|
| - fullname="/home/nickrob/myprog.c",line="68",times="0"}
|
| + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
|
| + times="0"}
|
| <- (gdb)
|
|
|
| Program Execution
|
| @@ -1937,7 +4181,7 @@ have not been implemented yet and these are labeled N.A. (not
|
| available).
|
|
|
|
|
| -File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI
|
| +File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Catchpoint Commands, Prev: GDB/MI Command Description Format, Up: GDB/MI
|
|
|
| 27.8 GDB/MI Breakpoint Commands
|
| ===============================
|
| @@ -1969,7 +4213,8 @@ Example
|
| -break-insert main
|
| ^done,bkpt={number="1",type="breakpoint",disp="keep",
|
| enabled="y",addr="0x000100d0",func="main",file="hello.c",
|
| - fullname="/home/foo/hello.c",line="5",times="0"}
|
| + fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
|
| + times="0"}
|
| (gdb)
|
| -break-after 1 3
|
| ~
|
| @@ -1985,7 +4230,7 @@ Example
|
| {width="40",alignment="2",col_name="what",colhdr="What"}],
|
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
| - line="5",times="0",ignore="3"}]}
|
| + line="5",thread-groups=["i1"],times="0",ignore="3"}]}
|
| (gdb)
|
|
|
| The `-break-commands' Command
|
| @@ -2015,7 +4260,8 @@ Example
|
| -break-insert main
|
| ^done,bkpt={number="1",type="breakpoint",disp="keep",
|
| enabled="y",addr="0x000100d0",func="main",file="hello.c",
|
| - fullname="/home/foo/hello.c",line="5",times="0"}
|
| + fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
|
| + times="0"}
|
| (gdb)
|
| -break-commands 1 "print v" "continue"
|
| ^done
|
| @@ -2055,7 +4301,7 @@ Example
|
| {width="40",alignment="2",col_name="what",colhdr="What"}],
|
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
| - line="5",cond="1",times="0",ignore="3"}]}
|
| + line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]}
|
| (gdb)
|
|
|
| The `-break-delete' Command
|
| @@ -2125,7 +4371,7 @@ Example
|
| {width="40",alignment="2",col_name="what",colhdr="What"}],
|
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
|
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
| - line="5",times="0"}]}
|
| + line="5",thread-groups=["i1"],times="0"}]}
|
| (gdb)
|
|
|
| The `-break-enable' Command
|
| @@ -2160,7 +4406,7 @@ Example
|
| {width="40",alignment="2",col_name="what",colhdr="What"}],
|
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
| - line="5",times="0"}]}
|
| + line="5",thread-groups=["i1"],times="0"}]}
|
| (gdb)
|
|
|
| The `-break-info' Command
|
| @@ -2173,6 +4419,10 @@ Synopsis
|
|
|
| Get information about a single breakpoint.
|
|
|
| + The result is a table of breakpoints. *Note GDB/MI Breakpoint
|
| +Information::, for details on the format of each breakpoint in the
|
| +table.
|
| +
|
| GDB Command
|
| ...........
|
|
|
| @@ -2236,19 +4486,8 @@ If specified, LOCATION, can be one of:
|
| Result
|
| ......
|
|
|
| -The result is in the form:
|
| -
|
| - ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep",
|
| - enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME",
|
| - fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,]
|
| - times="TIMES"}
|
| -
|
| -where NUMBER is the GDB number for this breakpoint, FUNCNAME is the
|
| -name of the function where the breakpoint was inserted, FILENAME is the
|
| -name of the source file which contains this function, LINENO is the
|
| -source line number within that file and TIMES the number of times that
|
| -the breakpoint has been hit (always 0 for -break-insert but may be
|
| -greater for -break-info or -break-list which use the same output).
|
| +*Note GDB/MI Breakpoint Information::, for details on the format of the
|
| +resulting breakpoint.
|
|
|
| Note: this format is open to change.
|
|
|
| @@ -2264,11 +4503,13 @@ Example
|
| (gdb)
|
| -break-insert main
|
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
|
| - fullname="/home/foo/recursive2.c,line="4",times="0"}
|
| + fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],
|
| + times="0"}
|
| (gdb)
|
| -break-insert -t foo
|
| ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
|
| - fullname="/home/foo/recursive2.c,line="11",times="0"}
|
| + fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],
|
| + times="0"}
|
| (gdb)
|
| -break-list
|
| ^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
| @@ -2280,10 +4521,87 @@ Example
|
| {width="40",alignment="2",col_name="what",colhdr="What"}],
|
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x0001072c", func="main",file="recursive2.c",
|
| - fullname="/home/foo/recursive2.c,"line="4",times="0"},
|
| + fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],
|
| + times="0"},
|
| bkpt={number="2",type="breakpoint",disp="del",enabled="y",
|
| addr="0x00010774",func="foo",file="recursive2.c",
|
| - fullname="/home/foo/recursive2.c",line="11",times="0"}]}
|
| + fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
|
| + times="0"}]}
|
| + (gdb)
|
| +
|
| +The `-dprintf-insert' Command
|
| +-----------------------------
|
| +
|
| +Synopsis
|
| +........
|
| +
|
| + -dprintf-insert [ -t ] [ -f ] [ -d ]
|
| + [ -c CONDITION ] [ -i IGNORE-COUNT ]
|
| + [ -p THREAD-ID ] [ LOCATION ] [ FORMAT ]
|
| + [ ARGUMENT ]
|
| +
|
| +If specified, LOCATION, can be one of:
|
| +
|
| + * FUNCTION
|
| +
|
| + * FILENAME:LINENUM
|
| +
|
| + * FILENAME:function
|
| +
|
| + * *ADDRESS
|
| +
|
| + The possible optional parameters of this command are:
|
| +
|
| +`-t'
|
| + Insert a temporary breakpoint.
|
| +
|
| +`-f'
|
| + If LOCATION cannot be parsed (for example, if it refers to unknown
|
| + files or functions), create a pending breakpoint. Without this
|
| + flag, GDB will report an error, and won't create a breakpoint, if
|
| + LOCATION cannot be parsed.
|
| +
|
| +`-d'
|
| + Create a disabled breakpoint.
|
| +
|
| +`-c CONDITION'
|
| + Make the breakpoint conditional on CONDITION.
|
| +
|
| +`-i IGNORE-COUNT'
|
| + Set the ignore count of the breakpoint (*note ignore count:
|
| + Conditions.) to IGNORE-COUNT.
|
| +
|
| +`-p THREAD-ID'
|
| + Restrict the breakpoint to the specified THREAD-ID.
|
| +
|
| +Result
|
| +......
|
| +
|
| +*Note GDB/MI Breakpoint Information::, for details on the format of the
|
| +resulting breakpoint.
|
| +
|
| +GDB Command
|
| +...........
|
| +
|
| +The corresponding GDB command is `dprintf'.
|
| +
|
| +Example
|
| +.......
|
| +
|
| + (gdb)
|
| + 4-dprintf-insert foo "At foo entry\n"
|
| + 4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y",
|
| + addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
|
| + fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
|
| + times="0",script={"printf \"At foo entry\\n\"","continue"},
|
| + original-location="foo"}
|
| + (gdb)
|
| + 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
|
| + 5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y",
|
| + addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
|
| + fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
|
| + times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"},
|
| + original-location="mi-dprintf.c:26"}
|
| (gdb)
|
|
|
| The `-break-list' Command
|
| @@ -2317,6 +4635,9 @@ fields:
|
| logical location of the breakpoint, expressed by function name,
|
| file name, line number
|
|
|
| +`Thread-groups'
|
| + list of thread groups to which this breakpoint applies
|
| +
|
| `Times'
|
| number of times the breakpoint has been hit
|
|
|
| @@ -2341,10 +4662,11 @@ Example
|
| {width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
| {width="40",alignment="2",col_name="what",colhdr="What"}],
|
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
| - addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
|
| + addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],
|
| + times="0"},
|
| bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
|
| - line="13",times="0"}]}
|
| + line="13",thread-groups=["i1"],times="0"}]}
|
| (gdb)
|
|
|
| Here's an example of the result when there are no breakpoints:
|
| @@ -2462,9 +4784,10 @@ is deleted.
|
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x00010734",func="callee4",
|
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
| - fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"},
|
| + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],
|
| + times="1"},
|
| bkpt={number="2",type="watchpoint",disp="keep",
|
| - enabled="y",addr="",what="C",times="0"}]}
|
| + enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]}
|
| (gdb)
|
| -exec-continue
|
| ^running
|
| @@ -2486,9 +4809,10 @@ is deleted.
|
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x00010734",func="callee4",
|
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
| - fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
|
| + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],
|
| + times="1"},
|
| bkpt={number="2",type="watchpoint",disp="keep",
|
| - enabled="y",addr="",what="C",times="-5"}]}
|
| + enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]}
|
| (gdb)
|
| -exec-continue
|
| ^running
|
| @@ -2510,14 +4834,181 @@ is deleted.
|
| addr="0x00010734",func="callee4",
|
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
|
| - times="1"}]}
|
| + thread-groups=["i1"],times="1"}]}
|
| (gdb)
|
|
|
|
|
| -File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
|
| +File: gdb.info, Node: GDB/MI Catchpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
|
|
|
| -27.9 GDB/MI Program Context
|
| -============================
|
| +27.9 GDB/MI Catchpoint Commands
|
| +===============================
|
| +
|
| +This section documents GDB/MI commands for manipulating catchpoints.
|
| +
|
| +* Menu:
|
| +
|
| +* Shared Library GDB/MI Catchpoint Commands::
|
| +* Ada Exception GDB/MI Catchpoint Commands::
|
| +
|
| +
|
| +File: gdb.info, Node: Shared Library GDB/MI Catchpoint Commands, Next: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands
|
| +
|
| +27.9.1 Shared Library GDB/MI Catchpoints
|
| +----------------------------------------
|
| +
|
| +The `-catch-load' Command
|
| +-------------------------
|
| +
|
| +Synopsis
|
| +........
|
| +
|
| + -catch-load [ -t ] [ -d ] REGEXP
|
| +
|
| + Add a catchpoint for library load events. If the `-t' option is
|
| +used, the catchpoint is a temporary one (*note Setting Breakpoints: Set
|
| +Breaks.). If the `-d' option is used, the catchpoint is created in a
|
| +disabled state. The `regexp' argument is a regular expression used to
|
| +match the name of the loaded library.
|
| +
|
| +GDB Command
|
| +...........
|
| +
|
| +The corresponding GDB command is `catch load'.
|
| +
|
| +Example
|
| +.......
|
| +
|
| + -catch-load -t foo.so
|
| + ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y",
|
| + what="load of library matching foo.so",catch-type="load",times="0"}
|
| + (gdb)
|
| +
|
| +The `-catch-unload' Command
|
| +---------------------------
|
| +
|
| +Synopsis
|
| +........
|
| +
|
| + -catch-unload [ -t ] [ -d ] REGEXP
|
| +
|
| + Add a catchpoint for library unload events. If the `-t' option is
|
| +used, the catchpoint is a temporary one (*note Setting Breakpoints: Set
|
| +Breaks.). If the `-d' option is used, the catchpoint is created in a
|
| +disabled state. The `regexp' argument is a regular expression used to
|
| +match the name of the unloaded library.
|
| +
|
| +GDB Command
|
| +...........
|
| +
|
| +The corresponding GDB command is `catch unload'.
|
| +
|
| +Example
|
| +.......
|
| +
|
| + -catch-unload -d bar.so
|
| + ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n",
|
| + what="load of library matching bar.so",catch-type="unload",times="0"}
|
| + (gdb)
|
| +
|
| +
|
| +File: gdb.info, Node: Ada Exception GDB/MI Catchpoint Commands, Prev: Shared Library GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands
|
| +
|
| +27.9.2 Ada Exception GDB/MI Catchpoints
|
| +---------------------------------------
|
| +
|
| +The following GDB/MI commands can be used to create catchpoints that
|
| +stop the execution when Ada exceptions are being raised.
|
| +
|
| +The `-catch-assert' Command
|
| +---------------------------
|
| +
|
| +Synopsis
|
| +........
|
| +
|
| + -catch-assert [ -c CONDITION] [ -d ] [ -t ]
|
| +
|
| + Add a catchpoint for failed Ada assertions.
|
| +
|
| + The possible optional parameters for this command are:
|
| +
|
| +`-c CONDITION'
|
| + Make the catchpoint conditional on CONDITION.
|
| +
|
| +`-d'
|
| + Create a disabled catchpoint.
|
| +
|
| +`-t'
|
| + Create a temporary catchpoint.
|
| +
|
| +GDB Command
|
| +...........
|
| +
|
| +The corresponding GDB command is `catch assert'.
|
| +
|
| +Example
|
| +.......
|
| +
|
| + -catch-assert
|
| + ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep",
|
| + enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
|
| + thread-groups=["i1"],times="0",
|
| + original-location="__gnat_debug_raise_assert_failure"}
|
| + (gdb)
|
| +
|
| +The `-catch-exception' Command
|
| +------------------------------
|
| +
|
| +Synopsis
|
| +........
|
| +
|
| + -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ]
|
| + [ -t ] [ -u ]
|
| +
|
| + Add a catchpoint stopping when Ada exceptions are raised. By
|
| +default, the command stops the program when any Ada exception gets
|
| +raised. But it is also possible, by using some of the optional
|
| +parameters described below, to create more selective catchpoints.
|
| +
|
| + The possible optional parameters for this command are:
|
| +
|
| +`-c CONDITION'
|
| + Make the catchpoint conditional on CONDITION.
|
| +
|
| +`-d'
|
| + Create a disabled catchpoint.
|
| +
|
| +`-e EXCEPTION-NAME'
|
| + Only stop when EXCEPTION-NAME is raised. This option cannot be
|
| + used combined with `-u'.
|
| +
|
| +`-t'
|
| + Create a temporary catchpoint.
|
| +
|
| +`-u'
|
| + Stop only when an unhandled exception gets raised. This option
|
| + cannot be used combined with `-e'.
|
| +
|
| +GDB Command
|
| +...........
|
| +
|
| +The corresponding GDB commands are `catch exception' and `catch
|
| +exception unhandled'.
|
| +
|
| +Example
|
| +.......
|
| +
|
| + -catch-exception -e Program_Error
|
| + ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep",
|
| + enabled="y",addr="0x0000000000404874",
|
| + what="`Program_Error' Ada exception", thread-groups=["i1"],
|
| + times="0",original-location="__gnat_debug_raise_exception"}
|
| + (gdb)
|
| +
|
| +
|
| +File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Catchpoint Commands, Up: GDB/MI
|
| +
|
| +27.10 GDB/MI Program Context
|
| +=============================
|
|
|
| The `-exec-arguments' Command
|
| -----------------------------
|
| @@ -2677,7 +5168,7 @@ Example
|
|
|
| File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI
|
|
|
| -27.10 GDB/MI Thread Commands
|
| +27.11 GDB/MI Thread Commands
|
| ============================
|
|
|
| The `-thread-info' Command
|
| @@ -2833,7 +5324,7 @@ Example
|
|
|
| File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI
|
|
|
| -27.11 GDB/MI Ada Tasking Commands
|
| +27.12 GDB/MI Ada Tasking Commands
|
| =================================
|
|
|
| The `-ada-task-info' Command
|
| @@ -2885,7 +5376,7 @@ for each Ada task:
|
|
|
| `state'
|
| The current state of the task. For a detailed description of the
|
| - possible states, see *Note Ada Tasks::.
|
| + possible states, see *note Ada Tasks::.
|
|
|
| `name'
|
| The name of the task.
|
| @@ -2911,7 +5402,7 @@ Example
|
|
|
| File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI
|
|
|
| -27.12 GDB/MI Program Execution
|
| +27.13 GDB/MI Program Execution
|
| ==============================
|
|
|
| These are the asynchronous commands which generate the out-of-band
|
| @@ -3194,17 +5685,22 @@ The `-exec-run' Command
|
| Synopsis
|
| ........
|
|
|
| - -exec-run [--all | --thread-group N]
|
| + -exec-run [ --all | --thread-group N ] [ --start ]
|
|
|
| Starts execution of the inferior from the beginning. The inferior
|
| executes until either a breakpoint is encountered or the program exits.
|
| -In the latter case the output will include an exit code, if the
|
| -program has exited exceptionally.
|
| +In the latter case the output will include an exit code, if the program
|
| +has exited exceptionally.
|
| +
|
| + When neither the `--all' nor the `--thread-group' option is
|
| +specified, the current inferior is started. If the `--thread-group'
|
| +option is specified, it should refer to a thread group of type
|
| +`process', and that thread group will be started. If the `--all'
|
| +option is specified, then all inferiors will be started.
|
|
|
| - When no option is specified, the current inferior is started. If the
|
| -`--thread-group' option is specified, it should refer to a thread group
|
| -of type `process', and that thread group will be started. If the
|
| -`--all' option is specified, then all inferiors will be started.
|
| + Using the `--start' option instructs the debugger to stop the
|
| +execution at the start of the inferior's main subprogram, following the
|
| +same behavior as the `start' command (*note Starting::).
|
|
|
| GDB Command
|
| ...........
|
| @@ -3369,9 +5865,24 @@ Example
|
|
|
| File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI
|
|
|
| -27.13 GDB/MI Stack Manipulation Commands
|
| +27.14 GDB/MI Stack Manipulation Commands
|
| ========================================
|
|
|
| +The `-enable-frame-filters' Command
|
| +-----------------------------------
|
| +
|
| + -enable-frame-filters
|
| +
|
| + GDB allows Python-based frame filters to affect the output of the MI
|
| +commands relating to stack traces. As there is no way to implement
|
| +this in a fully backward-compatible way, a front end must request that
|
| +this functionality be enabled.
|
| +
|
| + Once enabled, this feature cannot be disabled.
|
| +
|
| + Note that if Python support has not been compiled into GDB, this
|
| +command will still succeed (and do nothing).
|
| +
|
| The `-stack-info-frame' Command
|
| -------------------------------
|
|
|
| @@ -3442,7 +5953,7 @@ The `-stack-list-arguments' Command
|
| Synopsis
|
| ........
|
|
|
| - -stack-list-arguments PRINT-VALUES
|
| + -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
|
| [ LOW-FRAME HIGH-FRAME ]
|
|
|
| Display a list of the arguments for the frames between LOW-FRAME and
|
| @@ -3457,7 +5968,12 @@ in which case only existing frames will be returned.
|
| variables; if it is 1 or `--all-values', print also their values; and
|
| if it is 2 or `--simple-values', print the name, type and value for
|
| simple data types, and the name and type for arrays, structures and
|
| -unions.
|
| +unions. If the option `--no-frame-filters' is supplied, then Python
|
| +frame filters will not be executed.
|
| +
|
| + If the `--skip-unavailable' option is specified, arguments that are
|
| +not available are not listed. Partially available arguments are still
|
| +displayed, however.
|
|
|
| Use of this command to obtain arguments in a single frame is
|
| deprecated in favor of the `-stack-list-variables' command.
|
| @@ -3531,7 +6047,7 @@ The `-stack-list-frames' Command
|
| Synopsis
|
| ........
|
|
|
| - -stack-list-frames [ LOW-FRAME HIGH-FRAME ]
|
| + -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ]
|
|
|
| List the frames currently on the stack. For each frame it displays
|
| the following info:
|
| @@ -3565,7 +6081,9 @@ levels are between the two arguments (inclusive). If the two arguments
|
| are equal, it shows the single frame at the corresponding level. It is
|
| an error if LOW-FRAME is larger than the actual number of frames. On
|
| the other hand, HIGH-FRAME may be larger than the actual number of
|
| -frames, in which case only existing frames will be returned.
|
| +frames, in which case only existing frames will be returned. If the
|
| +option `--no-frame-filters' is supplied, then Python frame filters will
|
| +not be executed.
|
|
|
| GDB Command
|
| ...........
|
| @@ -3634,7 +6152,7 @@ The `-stack-list-locals' Command
|
| Synopsis
|
| ........
|
|
|
| - -stack-list-locals PRINT-VALUES
|
| + -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
|
|
|
| Display the local variable names for the selected frame. If
|
| PRINT-VALUES is 0 or `--no-values', print only the names of the
|
| @@ -3643,7 +6161,13 @@ if it is 2 or `--simple-values', print the name, type and value for
|
| simple data types, and the name and type for arrays, structures and
|
| unions. In this last case, a frontend can immediately display the
|
| value of simple data types and create variable objects for other data
|
| -types when the user wishes to explore their values in more detail.
|
| +types when the user wishes to explore their values in more detail. If
|
| +the option `--no-frame-filters' is supplied, then Python frame filters
|
| +will not be executed.
|
| +
|
| + If the `--skip-unavailable' option is specified, local variables
|
| +that are not available are not listed. Partially available local
|
| +variables are still displayed, however.
|
|
|
| This command is deprecated in favor of the `-stack-list-variables'
|
| command.
|
| @@ -3674,14 +6198,19 @@ The `-stack-list-variables' Command
|
| Synopsis
|
| ........
|
|
|
| - -stack-list-variables PRINT-VALUES
|
| + -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES
|
|
|
| Display the names of local variables and function arguments for the
|
| selected frame. If PRINT-VALUES is 0 or `--no-values', print only the
|
| names of the variables; if it is 1 or `--all-values', print also their
|
| values; and if it is 2 or `--simple-values', print the name, type and
|
| value for simple data types, and the name and type for arrays,
|
| -structures and unions.
|
| +structures and unions. If the option `--no-frame-filters' is supplied,
|
| +then Python frame filters will not be executed.
|
| +
|
| + If the `--skip-unavailable' option is specified, local variables and
|
| +arguments that are not available are not listed. Partially available
|
| +arguments and local variables are still displayed, however.
|
|
|
| Example
|
| .......
|
| @@ -3722,7 +6251,7 @@ Example
|
|
|
| File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
|
|
|
| -27.14 GDB/MI Variable Objects
|
| +27.15 GDB/MI Variable Objects
|
| =============================
|
|
|
| Introduction to Variable Objects
|
| @@ -4011,8 +6540,7 @@ Synopsis
|
| ........
|
|
|
| -var-list-children [PRINT-VALUES] NAME [FROM TO]
|
| -
|
| - Return a list of the children of the specified variable object and
|
| +Return a list of the children of the specified variable object and
|
| create variable objects for them, if they do not already exist. With a
|
| single argument or if PRINT-VALUES has a value of 0 or `--no-values',
|
| print only the names of the variables; if PRINT-VALUES is 1 or
|
| @@ -4077,6 +6605,17 @@ FROZEN
|
| If the variable object is frozen, this variable will be present
|
| with a value of 1.
|
|
|
| +DISPLAYHINT
|
| + A dynamic varobj can supply a display hint to the front end. The
|
| + value comes directly from the Python pretty-printer object's
|
| + `display_hint' method. *Note Pretty Printing API::.
|
| +
|
| +DYNAMIC
|
| + This attribute will be present and have the value `1' if the
|
| + varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
|
| + then this attribute will not be present.
|
| +
|
| +
|
| The result may have its own attributes:
|
|
|
| `displayhint'
|
| @@ -4131,7 +6670,8 @@ for `a', then we'll get this output:
|
| (gdb) -var-info-expression A.1
|
| ^done,lang="C",exp="1"
|
|
|
| -Here, the values of `lang' can be `{"C" | "C++" | "Java"}'.
|
| +Here, the value of `lang' is the language name, which can be found in
|
| +*note Supported Languages::.
|
|
|
| Note that the output of the `-var-list-children' command also
|
| includes those expressions, so the `-var-info-expression' command is of
|
| @@ -4444,7 +6984,7 @@ be used to instantiate this class for a varobj:
|
|
|
| File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI
|
|
|
| -27.15 GDB/MI Data Manipulation
|
| +27.16 GDB/MI Data Manipulation
|
| ==============================
|
|
|
| This section describes the GDB/MI commands that manipulate data:
|
| @@ -4492,24 +7032,64 @@ Where:
|
| Result
|
| ......
|
|
|
| -The output for each instruction is composed of four fields:
|
| +The result of the `-data-disassemble' command will be a list named
|
| +`asm_insns', the contents of this list depend on the MODE used with the
|
| +`-data-disassemble' command.
|
|
|
| - * Address
|
| + For modes 0 and 2 the `asm_insns' list contains tuples with the
|
| +following fields:
|
|
|
| - * Func-name
|
| +`address'
|
| + The address at which this instruction was disassembled.
|
|
|
| - * Offset
|
| +`func-name'
|
| + The name of the function this instruction is within.
|
|
|
| - * Instruction
|
| +`offset'
|
| + The decimal offset in bytes from the start of `func-name'.
|
| +
|
| +`inst'
|
| + The text disassembly for this `address'.
|
| +
|
| +`opcodes'
|
| + This field is only present for mode 2. This contains the raw
|
| + opcode bytes for the `inst' field.
|
| +
|
| +
|
| + For modes 1 and 3 the `asm_insns' list contains tuples named
|
| +`src_and_asm_line', each of which has the following fields:
|
| +
|
| +`line'
|
| + The line number within `file'.
|
| +
|
| +`file'
|
| + The file name from the compilation unit. This might be an absolute
|
| + file name or a relative file name depending on the compile command
|
| + used.
|
| +
|
| +`fullname'
|
| + Absolute file name of `file'. It is converted to a canonical form
|
| + using the source file search path (*note Specifying Source
|
| + Directories: Source Path.) and after resolving all the symbolic
|
| + links.
|
| +
|
| + If the source file is not found this field will contain the path as
|
| + present in the debug information.
|
|
|
| - Note that whatever included in the instruction field, is not
|
| -manipulated directly by GDB/MI, i.e., it is not possible to adjust its
|
| -format.
|
| +`line_asm_insn'
|
| + This is a list of tuples containing the disassembly for `line' in
|
| + `file'. The fields of each tuple are the same as for
|
| + `-data-disassemble' in MODE 0 and 2, so `address', `func-name',
|
| + `offset', `inst', and optionally `opcodes'.
|
| +
|
| +
|
| + Note that whatever included in the `inst' field, is not manipulated
|
| +directly by GDB/MI, i.e., it is not possible to adjust its format.
|
|
|
| GDB Command
|
| ...........
|
|
|
| -There's no direct mapping from this command to the CLI.
|
| +The corresponding GDB command is `disassemble'.
|
|
|
| Example
|
| .......
|
| @@ -4566,15 +7146,15 @@ Disassemble from the current value of `$pc' to `$pc + 20':
|
| -data-disassemble -f basics.c -l 32 -n 3 -- 1
|
| ^done,asm_insns=[
|
| src_and_asm_line={line="31",
|
| - file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
|
| - testsuite/gdb.mi/basics.c",line_asm_insn=[
|
| - {address="0x000107bc",func-name="main",offset="0",
|
| - inst="save %sp, -112, %sp"}]},
|
| + file="../../../src/gdb/testsuite/gdb.mi/basics.c",
|
| + fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
|
| + line_asm_insn=[{address="0x000107bc",
|
| + func-name="main",offset="0",inst="save %sp, -112, %sp"}]},
|
| src_and_asm_line={line="32",
|
| - file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
|
| - testsuite/gdb.mi/basics.c",line_asm_insn=[
|
| - {address="0x000107c0",func-name="main",offset="4",
|
| - inst="mov 2, %o0"},
|
| + file="../../../src/gdb/testsuite/gdb.mi/basics.c",
|
| + fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
|
| + line_asm_insn=[{address="0x000107c0",
|
| + func-name="main",offset="4",inst="mov 2, %o0"},
|
| {address="0x000107c4",func-name="main",offset="8",
|
| inst="sethi %hi(0x11800), %o2"}]}]
|
| (gdb)
|
| @@ -4601,7 +7181,7 @@ Example
|
| .......
|
|
|
| In the following example, the numbers that precede the commands are the
|
| -"tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command
|
| +"tokens" described in *note GDB/MI Command Syntax: GDB/MI Command
|
| Syntax. Notice how GDB/MI returns the same tokens in its output.
|
|
|
| 211-data-evaluate-expression A
|
| @@ -4699,13 +7279,15 @@ The `-data-list-register-values' Command
|
| Synopsis
|
| ........
|
|
|
| - -data-list-register-values FMT [ ( REGNO )*]
|
| + -data-list-register-values
|
| + [ `--skip-unavailable' ] FMT [ ( REGNO )*]
|
|
|
| Display the registers' contents. FMT is the format according to
|
| which the registers' contents are to be returned, followed by an
|
| optional list of numbers specifying the registers to display. A
|
| missing list of numbers indicates that the contents of all the
|
| -registers must be returned.
|
| +registers must be returned. The `--skip-unavailable' option indicates
|
| +that only the available registers are to be returned.
|
|
|
| Allowed formats for FMT are:
|
|
|
| @@ -4972,6 +7554,7 @@ Synopsis
|
| ........
|
|
|
| -data-write-memory-bytes ADDRESS CONTENTS
|
| + -data-write-memory-bytes ADDRESS CONTENTS [COUNT]
|
|
|
| where:
|
|
|
| @@ -4983,6 +7566,11 @@ where:
|
| `CONTENTS'
|
| The hex-encoded bytes to write.
|
|
|
| +`COUNT'
|
| + Optional argument indicating the number of bytes to be written.
|
| + If COUNT is greater than CONTENTS' length, GDB will repeatedly
|
| + write CONTENTS until it fills COUNT bytes.
|
| +
|
|
|
| GDB Command
|
| ...........
|
| @@ -4997,14 +7585,19 @@ Example
|
| ^done
|
| (gdb)
|
|
|
| + (gdb)
|
| + -data-write-memory-bytes &a "aabbccdd" 16e
|
| + ^done
|
| + (gdb)
|
| +
|
|
|
| File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI
|
|
|
| -27.16 GDB/MI Tracepoint Commands
|
| +27.17 GDB/MI Tracepoint Commands
|
| ================================
|
|
|
| The commands defined in this section implement MI support for
|
| -tracepoints. For detailed introduction, see *Note Tracepoints::.
|
| +tracepoints. For detailed introduction, see *note Tracepoints::.
|
|
|
| The `-trace-find' Command
|
| -------------------------
|
| @@ -5016,7 +7609,7 @@ Synopsis
|
|
|
| Find a trace frame using criteria defined by MODE and PARAMETERS.
|
| The following table lists permissible modes and their parameters. For
|
| -details of operation, see *Note tfind::.
|
| +details of operation, see *note tfind::.
|
|
|
| `none'
|
| No parameters are required. Stops examining trace frames.
|
| @@ -5094,21 +7687,130 @@ GDB Command
|
|
|
| The corresponding GDB command is `tvariable'.
|
|
|
| --trace-list-variables
|
| ----------------------
|
| +The `-trace-frame-collected' Command
|
| +------------------------------------
|
|
|
| Synopsis
|
| ........
|
|
|
| - -trace-list-variables
|
| + -trace-frame-collected
|
| + [--var-print-values VAR_PVAL]
|
| + [--comp-print-values COMP_PVAL]
|
| + [--registers-format REGFORMAT]
|
| + [--memory-contents]
|
|
|
| - Return a table of all defined trace variables. Each element of the
|
| -table has the following fields:
|
| + This command returns the set of collected objects, register names,
|
| +trace state variable names, memory ranges and computed expressions that
|
| +have been collected at a particular trace frame. The optional
|
| +parameters to the command affect the output format in different ways.
|
| +See the output description table below for more details.
|
|
|
| -`name'
|
| - The name of the trace variable. This field is always present.
|
| + The reported names can be used in the normal manner to create
|
| +varobjs and inspect the objects themselves. The items returned by this
|
| +command are categorized so that it is clear which is a variable, which
|
| +is a register, which is a trace state variable, which is a memory range
|
| +and which is a computed expression.
|
|
|
| -`initial'
|
| + For instance, if the actions were
|
| + collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
|
| + collect *(int*)0xaf02bef0@40
|
| +
|
| +the object collected in its entirety would be `myVar'. The object
|
| +`myArray' would be partially collected, because only the element at
|
| +index `myIndex' would be collected. The remaining objects would be
|
| +computed expressions.
|
| +
|
| + An example output would be:
|
| +
|
| + (gdb)
|
| + -trace-frame-collected
|
| + ^done,
|
| + explicit-variables=[{name="myVar",value="1"}],
|
| + computed-expressions=[{name="myArray[myIndex]",value="0"},
|
| + {name="myObj.field",value="0"},
|
| + {name="myPtr->field",value="1"},
|
| + {name="myCount + 2",value="3"},
|
| + {name="$tvar1 + 1",value="43970027"}],
|
| + registers=[{number="0",value="0x7fe2c6e79ec8"},
|
| + {number="1",value="0x0"},
|
| + {number="2",value="0x4"},
|
| + ...
|
| + {number="125",value="0x0"}],
|
| + tvars=[{name="$tvar1",current="43970026"}],
|
| + memory=[{address="0x0000000000602264",length="4"},
|
| + {address="0x0000000000615bc0",length="4"}]
|
| + (gdb)
|
| +
|
| + Where:
|
| +
|
| +`explicit-variables'
|
| + The set of objects that have been collected in their entirety (as
|
| + opposed to collecting just a few elements of an array or a few
|
| + struct members). For each object, its name and value are printed.
|
| + The `--var-print-values' option affects how or whether the value
|
| + field is output. If VAR_PVAL is 0, then print only the names; if
|
| + it is 1, print also their values; and if it is 2, print the name,
|
| + type and value for simple data types, and the name and type for
|
| + arrays, structures and unions.
|
| +
|
| +`computed-expressions'
|
| + The set of computed expressions that have been collected at the
|
| + current trace frame. The `--comp-print-values' option affects
|
| + this set like the `--var-print-values' option affects the
|
| + `explicit-variables' set. See above.
|
| +
|
| +`registers'
|
| + The registers that have been collected at the current trace frame.
|
| + For each register collected, the name and current value are
|
| + returned. The value is formatted according to the
|
| + `--registers-format' option. See the `-data-list-register-values'
|
| + command for a list of the allowed formats. The default is `x'.
|
| +
|
| +`tvars'
|
| + The trace state variables that have been collected at the current
|
| + trace frame. For each trace state variable collected, the name and
|
| + current value are returned.
|
| +
|
| +`memory'
|
| + The set of memory ranges that have been collected at the current
|
| + trace frame. Its content is a list of tuples. Each tuple
|
| + represents a collected memory range and has the following fields:
|
| +
|
| + `address'
|
| + The start address of the memory range, as hexadecimal literal.
|
| +
|
| + `length'
|
| + The length of the memory range, as decimal literal.
|
| +
|
| + `contents'
|
| + The contents of the memory block, in hex. This field is only
|
| + present if the `--memory-contents' option is specified.
|
| +
|
| +
|
| +
|
| +GDB Command
|
| +...........
|
| +
|
| +There is no corresponding GDB command.
|
| +
|
| +Example
|
| +.......
|
| +
|
| +-trace-list-variables
|
| +---------------------
|
| +
|
| +Synopsis
|
| +........
|
| +
|
| + -trace-list-variables
|
| +
|
| + Return a table of all defined trace variables. Each element of the
|
| +table has the following fields:
|
| +
|
| +`name'
|
| + The name of the trace variable. This field is always present.
|
| +
|
| +`initial'
|
| The initial value. This is a 64-bit signed integer. This field
|
| is always present.
|
|
|
| @@ -5232,6 +7934,10 @@ the following fields:
|
| tracing will continue after GDB disconnects, `0' means that the
|
| trace run will stop.
|
|
|
| +`trace-file'
|
| + The filename of the trace file being examined. This field is
|
| + optional, and only present when examining a trace file.
|
| +
|
|
|
| GDB Command
|
| ...........
|
| @@ -5258,7 +7964,7 @@ The corresponding GDB command is `tstop'.
|
|
|
| File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
|
|
|
| -27.17 GDB/MI Symbol Query Commands
|
| +27.18 GDB/MI Symbol Query Commands
|
| ==================================
|
|
|
| The `-symbol-list-lines' Command
|
| @@ -5289,7 +7995,7 @@ Example
|
|
|
| File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI
|
|
|
| -27.18 GDB/MI File Commands
|
| +27.19 GDB/MI File Commands
|
| ==========================
|
|
|
| This section describes the GDB/MI commands to specify executable file
|
| @@ -5386,8 +8092,8 @@ Synopsis
|
|
|
| List the source files for the current executable.
|
|
|
| - It will always output the filename, but only when GDB can find the
|
| -absolute file name of a source file, will it output the fullname.
|
| + It will always output both the filename and fullname (absolute file
|
| +name) of a source file.
|
|
|
| GDB Command
|
| ...........
|
| @@ -5434,7 +8140,7 @@ Example
|
|
|
| File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI
|
|
|
| -27.19 GDB/MI Target Manipulation Commands
|
| +27.20 GDB/MI Target Manipulation Commands
|
| =========================================
|
|
|
| The `-target-attach' Command
|
| @@ -5663,9 +8369,9 @@ Example
|
| (gdb)
|
|
|
|
|
| -File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
|
| +File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Ada Exceptions Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
|
|
|
| -27.20 GDB/MI File Transfer Commands
|
| +27.21 GDB/MI File Transfer Commands
|
| ===================================
|
|
|
| The `-target-file-put' Command
|
| @@ -5740,3144 +8446,55 @@ Example
|
| (gdb)
|
|
|
|
|
| -File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
|
| +File: gdb.info, Node: GDB/MI Ada Exceptions Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
|
|
|
| -27.21 Miscellaneous GDB/MI Commands
|
| -===================================
|
| +27.22 Ada Exceptions GDB/MI Commands
|
| +====================================
|
|
|
| -The `-gdb-exit' Command
|
| ------------------------
|
| +The `-info-ada-exceptions' Command
|
| +----------------------------------
|
|
|
| Synopsis
|
| ........
|
|
|
| - -gdb-exit
|
| + -info-ada-exceptions [ REGEXP]
|
|
|
| - Exit GDB immediately.
|
| + List all Ada exceptions defined within the program being debugged.
|
| +With a regular expression REGEXP, only those exceptions whose names
|
| +match REGEXP are listed.
|
|
|
| GDB Command
|
| ...........
|
|
|
| -Approximately corresponds to `quit'.
|
| -
|
| -Example
|
| -.......
|
| -
|
| - (gdb)
|
| - -gdb-exit
|
| - ^exit
|
| -
|
| -The `-gdb-set' Command
|
| -----------------------
|
| +The corresponding GDB command is `info exceptions'.
|
|
|
| -Synopsis
|
| -........
|
| +Result
|
| +......
|
|
|
| - -gdb-set
|
| +The result is a table of Ada exceptions. The following columns are
|
| +defined for each exception:
|
|
|
| - Set an internal GDB variable.
|
| +`name'
|
| + The name of the exception.
|
|
|
| -GDB Command
|
| -...........
|
| +`address'
|
| + The address of the exception.
|
|
|
| -The corresponding GDB command is `set'.
|
|
|
| Example
|
| .......
|
|
|
| - (gdb)
|
| - -gdb-set $foo=3
|
| - ^done
|
| - (gdb)
|
| + -info-ada-exceptions aint
|
| + ^done,ada-exceptions={nr_rows="2",nr_cols="2",
|
| + hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"},
|
| + {width="1",alignment="-1",col_name="address",colhdr="Address"}],
|
| + body=[{name="constraint_error",address="0x0000000000613da0"},
|
| + {name="const.aint_global_e",address="0x0000000000613b00"}]}
|
|
|
| -The `-gdb-show' Command
|
| +Catching Ada Exceptions
|
| -----------------------
|
|
|
| -Synopsis
|
| -........
|
| -
|
| - -gdb-show
|
| -
|
| - Show the current value of a GDB variable.
|
| -
|
| -GDB Command
|
| -...........
|
| -
|
| -The corresponding GDB command is `show'.
|
| -
|
| -Example
|
| -.......
|
| -
|
| - (gdb)
|
| - -gdb-show annotate
|
| - ^done,value="0"
|
| - (gdb)
|
| -
|
| -The `-gdb-version' Command
|
| ---------------------------
|
| -
|
| -Synopsis
|
| -........
|
| -
|
| - -gdb-version
|
| -
|
| - Show version information for GDB. Used mostly in testing.
|
| -
|
| -GDB Command
|
| -...........
|
| -
|
| -The GDB equivalent is `show version'. GDB by default shows this
|
| -information when you start an interactive session.
|
| -
|
| -Example
|
| -.......
|
| -
|
| - (gdb)
|
| - -gdb-version
|
| - ~GNU gdb 5.2.1
|
| - ~Copyright 2000 Free Software Foundation, Inc.
|
| - ~GDB is free software, covered by the GNU General Public License, and
|
| - ~you are welcome to change it and/or distribute copies of it under
|
| - ~ certain conditions.
|
| - ~Type "show copying" to see the conditions.
|
| - ~There is absolutely no warranty for GDB. Type "show warranty" for
|
| - ~ details.
|
| - ~This GDB was configured as
|
| - "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
|
| - ^done
|
| - (gdb)
|
| -
|
| -The `-list-features' Command
|
| -----------------------------
|
| -
|
| -Returns a list of particular features of the MI protocol that this
|
| -version of gdb implements. A feature can be a command, or a new field
|
| -in an output of some command, or even an important bugfix. While a
|
| -frontend can sometimes detect presence of a feature at runtime, it is
|
| -easier to perform detection at debugger startup.
|
| -
|
| - The command returns a list of strings, with each string naming an
|
| -available feature. Each returned string is just a name, it does not
|
| -have any internal structure. The list of possible feature names is
|
| -given below.
|
| -
|
| - Example output:
|
| -
|
| - (gdb) -list-features
|
| - ^done,result=["feature1","feature2"]
|
| -
|
| - The current list of features is:
|
| -
|
| -`frozen-varobjs'
|
| - Indicates support for the `-var-set-frozen' command, as well as
|
| - possible presense of the `frozen' field in the output of
|
| - `-varobj-create'.
|
| -
|
| -`pending-breakpoints'
|
| - Indicates support for the `-f' option to the `-break-insert'
|
| - command.
|
| -
|
| -`python'
|
| - Indicates Python scripting support, Python-based pretty-printing
|
| - commands, and possible presence of the `display_hint' field in the
|
| - output of `-var-list-children'
|
| -
|
| -`thread-info'
|
| - Indicates support for the `-thread-info' command.
|
| -
|
| -`data-read-memory-bytes'
|
| - Indicates support for the `-data-read-memory-bytes' and the
|
| - `-data-write-memory-bytes' commands.
|
| -
|
| -`breakpoint-notifications'
|
| - Indicates that changes to breakpoints and breakpoints created via
|
| - the CLI will be announced via async records.
|
| -
|
| -`ada-task-info'
|
| - Indicates support for the `-ada-task-info' command.
|
| -
|
| -The `-list-target-features' Command
|
| ------------------------------------
|
| -
|
| -Returns a list of particular features that are supported by the target.
|
| -Those features affect the permitted MI commands, but unlike the
|
| -features reported by the `-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 `-target-select', `-target-attach' or
|
| -`-exec-run', the list of target features may change, and the frontend
|
| -should obtain it again. Example output:
|
| -
|
| - (gdb) -list-features
|
| - ^done,result=["async"]
|
| -
|
| - The current list of features is:
|
| -
|
| -`async'
|
| - Indicates that the target is capable of asynchronous command
|
| - execution, which means that GDB will accept further commands while
|
| - the target is running.
|
| -
|
| -`reverse'
|
| - Indicates that the target is capable of reverse execution. *Note
|
| - Reverse Execution::, for more information.
|
| -
|
| -
|
| -The `-list-thread-groups' Command
|
| ----------------------------------
|
| -
|
| -Synopsis
|
| ---------
|
| -
|
| - -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]
|
| -
|
| - Lists thread groups (*note Thread groups::). When a single thread
|
| -group is passed as the argument, lists the children of that group.
|
| -When several thread group are passed, lists information about those
|
| -thread groups. Without any parameters, lists information about all
|
| -top-level thread groups.
|
| -
|
| - Normally, thread groups that are being debugged are reported. With
|
| -the `--available' option, GDB reports thread groups available on the
|
| -target.
|
| -
|
| - The output of this command may have either a `threads' result or a
|
| -`groups' result. The `thread' result has a list of tuples as value,
|
| -with each tuple describing a thread (*note GDB/MI Thread
|
| -Information::). The `groups' result has a list of tuples as value,
|
| -each tuple describing a thread group. If top-level groups are
|
| -requested (that is, no parameter is passed), or when several groups are
|
| -passed, the output always has a `groups' result. The format of the
|
| -`group' result is described below.
|
| -
|
| - To reduce the number of roundtrips it's possible to list thread
|
| -groups together with their children, by passing the `--recurse' option
|
| -and the recursion depth. Presently, only recursion depth of 1 is
|
| -permitted. If this option is present, then every reported thread group
|
| -will also include its children, either as `group' or `threads' field.
|
| -
|
| - In general, any combination of option and parameters is permitted,
|
| -with the following caveats:
|
| -
|
| - * When a single thread group is passed, the output will typically be
|
| - the `threads' result. Because threads may not contain anything,
|
| - the `recurse' option will be ignored.
|
| -
|
| - * When the `--available' option is passed, limited information may
|
| - be available. In particular, the list of threads of a process
|
| - might be inaccessible. Further, specifying specific thread groups
|
| - might not give any performance advantage over listing all thread
|
| - groups. The frontend should assume that `-list-thread-groups
|
| - --available' is always an expensive operation and cache the
|
| - results.
|
| -
|
| -
|
| - The `groups' result is a list of tuples, where each tuple may have
|
| -the following fields:
|
| -
|
| -`id'
|
| - Identifier of the thread group. This field is always present.
|
| - The identifier is an opaque string; frontends should not try to
|
| - convert it to an integer, even though it might look like one.
|
| -
|
| -`type'
|
| - The type of the thread group. At present, only `process' is a
|
| - valid type.
|
| -
|
| -`pid'
|
| - The target-specific process identifier. This field is only present
|
| - for thread groups of type `process' and only if the process exists.
|
| -
|
| -`num_children'
|
| - The number of children this thread group has. This field may be
|
| - absent for an available thread group.
|
| -
|
| -`threads'
|
| - This field has a list of tuples as value, each tuple describing a
|
| - thread. It may be present if the `--recurse' option is specified,
|
| - and it's actually possible to obtain the threads.
|
| -
|
| -`cores'
|
| - This field is a list of integers, each identifying a core that one
|
| - thread of the group is running on. This field may be absent if
|
| - such information is not available.
|
| -
|
| -`executable'
|
| - The name of the executable file that corresponds to this thread
|
| - group. The field is only present for thread groups of type
|
| - `process', and only if there is a corresponding executable file.
|
| -
|
| -
|
| -Example
|
| --------
|
| -
|
| - gdb
|
| - -list-thread-groups
|
| - ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}]
|
| - -list-thread-groups 17
|
| - ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
|
| - frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},
|
| - {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
|
| - frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],
|
| - file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]]
|
| - -list-thread-groups --available
|
| - ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}]
|
| - -list-thread-groups --available --recurse 1
|
| - ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
|
| - threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
|
| - {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..]
|
| - -list-thread-groups --available --recurse 1 17 18
|
| - ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
|
| - threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
|
| - {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]
|
| -
|
| -The `-info-os' Command
|
| -----------------------
|
| -
|
| -Synopsis
|
| -........
|
| -
|
| - -info-os [ TYPE ]
|
| -
|
| - If no argument is supplied, the command returns a table of available
|
| -operating-system-specific information types. If one of these types is
|
| -supplied as an argument TYPE, then the command returns a table of data
|
| -of that type.
|
| -
|
| - The types of information available depend on the target operating
|
| -system.
|
| -
|
| -GDB Command
|
| -...........
|
| -
|
| -The corresponding GDB command is `info os'.
|
| -
|
| -Example
|
| -.......
|
| -
|
| -When run on a GNU/Linux system, the output will look something like
|
| -this:
|
| -
|
| - gdb
|
| - -info-os
|
| - ^done,OSDataTable={nr_rows="9",nr_cols="3",
|
| - hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"},
|
| - {width="10",alignment="-1",col_name="col1",colhdr="Description"},
|
| - {width="10",alignment="-1",col_name="col2",colhdr="Title"}],
|
| - body=[item={col0="processes",col1="Listing of all processes",
|
| - col2="Processes"},
|
| - item={col0="procgroups",col1="Listing of all process groups",
|
| - col2="Process groups"},
|
| - item={col0="threads",col1="Listing of all threads",
|
| - col2="Threads"},
|
| - item={col0="files",col1="Listing of all file descriptors",
|
| - col2="File descriptors"},
|
| - item={col0="sockets",col1="Listing of all internet-domain sockets",
|
| - col2="Sockets"},
|
| - item={col0="shm",col1="Listing of all shared-memory regions",
|
| - col2="Shared-memory regions"},
|
| - item={col0="semaphores",col1="Listing of all semaphores",
|
| - col2="Semaphores"},
|
| - item={col0="msg",col1="Listing of all message queues",
|
| - col2="Message queues"},
|
| - item={col0="modules",col1="Listing of all loaded kernel modules",
|
| - col2="Kernel modules"}]}
|
| - gdb
|
| - -info-os processes
|
| - ^done,OSDataTable={nr_rows="190",nr_cols="4",
|
| - hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"},
|
| - {width="10",alignment="-1",col_name="col1",colhdr="user"},
|
| - {width="10",alignment="-1",col_name="col2",colhdr="command"},
|
| - {width="10",alignment="-1",col_name="col3",colhdr="cores"}],
|
| - body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"},
|
| - item={col0="2",col1="root",col2="[kthreadd]",col3="1"},
|
| - item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"},
|
| - ...
|
| - item={col0="26446",col1="stan",col2="bash",col3="0"},
|
| - item={col0="28152",col1="stan",col2="bash",col3="1"}]}
|
| - (gdb)
|
| -
|
| - (Note that the MI output here includes a `"Title"' column that does
|
| -not appear in command-line `info os'; this column is useful for MI
|
| -clients that want to enumerate the types of data, such as in a popup
|
| -menu, but is needless clutter on the command line, and `info os' omits
|
| -it.)
|
| -
|
| -The `-add-inferior' Command
|
| ----------------------------
|
| -
|
| -Synopsis
|
| ---------
|
| -
|
| - -add-inferior
|
| -
|
| - Creates a new inferior (*note Inferiors and Programs::). The created
|
| -inferior is not associated with any executable. Such association may
|
| -be established with the `-file-exec-and-symbols' command (*note GDB/MI
|
| -File Commands::). The command response has a single field,
|
| -`thread-group', whose value is the identifier of the thread group
|
| -corresponding to the new inferior.
|
| -
|
| -Example
|
| --------
|
| -
|
| - gdb
|
| - -add-inferior
|
| - ^done,thread-group="i3"
|
| -
|
| -The `-interpreter-exec' Command
|
| --------------------------------
|
| -
|
| -Synopsis
|
| ---------
|
| -
|
| - -interpreter-exec INTERPRETER COMMAND
|
| -
|
| - Execute the specified COMMAND in the given INTERPRETER.
|
| -
|
| -GDB Command
|
| ------------
|
| -
|
| -The corresponding GDB command is `interpreter-exec'.
|
| -
|
| -Example
|
| --------
|
| -
|
| - (gdb)
|
| - -interpreter-exec console "break main"
|
| - &"During symbol reading, couldn't parse type; debugger out of date?.\n"
|
| - &"During symbol reading, bad structure-type format.\n"
|
| - ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
|
| - ^done
|
| - (gdb)
|
| -
|
| -The `-inferior-tty-set' Command
|
| --------------------------------
|
| -
|
| -Synopsis
|
| ---------
|
| -
|
| - -inferior-tty-set /dev/pts/1
|
| -
|
| - Set terminal for future runs of the program being debugged.
|
| -
|
| -GDB Command
|
| ------------
|
| -
|
| -The corresponding GDB command is `set inferior-tty' /dev/pts/1.
|
| -
|
| -Example
|
| --------
|
| -
|
| - (gdb)
|
| - -inferior-tty-set /dev/pts/1
|
| - ^done
|
| - (gdb)
|
| -
|
| -The `-inferior-tty-show' Command
|
| ---------------------------------
|
| -
|
| -Synopsis
|
| ---------
|
| -
|
| - -inferior-tty-show
|
| -
|
| - Show terminal for future runs of program being debugged.
|
| -
|
| -GDB Command
|
| ------------
|
| -
|
| -The corresponding GDB command is `show inferior-tty'.
|
| -
|
| -Example
|
| --------
|
| -
|
| - (gdb)
|
| - -inferior-tty-set /dev/pts/1
|
| - ^done
|
| - (gdb)
|
| - -inferior-tty-show
|
| - ^done,inferior_tty_terminal="/dev/pts/1"
|
| - (gdb)
|
| -
|
| -The `-enable-timings' Command
|
| ------------------------------
|
| -
|
| -Synopsis
|
| ---------
|
| -
|
| - -enable-timings [yes | no]
|
| -
|
| - Toggle the printing of the wallclock, user and system times for an MI
|
| -command as a field in its output. This command is to help frontend
|
| -developers optimize the performance of their code. No argument is
|
| -equivalent to `yes'.
|
| -
|
| -GDB Command
|
| ------------
|
| -
|
| -No equivalent.
|
| -
|
| -Example
|
| --------
|
| -
|
| - (gdb)
|
| - -enable-timings
|
| - ^done
|
| - (gdb)
|
| - -break-insert main
|
| - ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
| - addr="0x080484ed",func="main",file="myprog.c",
|
| - fullname="/home/nickrob/myprog.c",line="73",times="0"},
|
| - time={wallclock="0.05185",user="0.00800",system="0.00000"}
|
| - (gdb)
|
| - -enable-timings no
|
| - ^done
|
| - (gdb)
|
| - -exec-run
|
| - ^running
|
| - (gdb)
|
| - *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
|
| - frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
|
| - {name="argv",value="0xbfb60364"}],file="myprog.c",
|
| - fullname="/home/nickrob/myprog.c",line="73"}
|
| - (gdb)
|
| -
|
| -
|
| -File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top
|
| -
|
| -28 GDB Annotations
|
| -******************
|
| -
|
| -This chapter describes annotations in GDB. Annotations were designed
|
| -to interface GDB to graphical user interfaces or other similar programs
|
| -which want to interact with GDB at a relatively high level.
|
| -
|
| - The annotation mechanism has largely been superseded by GDB/MI
|
| -(*note GDB/MI::).
|
| -
|
| -* Menu:
|
| -
|
| -* Annotations Overview:: What annotations are; the general syntax.
|
| -* Server Prefix:: Issuing a command without affecting user state.
|
| -* Prompting:: Annotations marking GDB's need for input.
|
| -* Errors:: Annotations for error messages.
|
| -* Invalidation:: Some annotations describe things now invalid.
|
| -* Annotations for Running::
|
| - Whether the program is running, how it stopped, etc.
|
| -* Source Annotations:: Annotations describing source code.
|
| -
|
| -
|
| -File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
|
| -
|
| -28.1 What is an Annotation?
|
| -===========================
|
| -
|
| -Annotations start with a newline character, two `control-z' characters,
|
| -and the name of the annotation. If there is no additional information
|
| -associated with this annotation, the name of the annotation is followed
|
| -immediately by a newline. If there is additional information, the name
|
| -of the annotation is followed by a space, the additional information,
|
| -and a newline. The additional information cannot contain newline
|
| -characters.
|
| -
|
| - Any output not beginning with a newline and two `control-z'
|
| -characters denotes literal output from GDB. Currently there is no need
|
| -for GDB to output a newline followed by two `control-z' characters, but
|
| -if there was such a need, the annotations could be extended with an
|
| -`escape' annotation which means those three characters as output.
|
| -
|
| - The annotation LEVEL, which is specified using the `--annotate'
|
| -command line option (*note Mode Options::), controls how much
|
| -information GDB prints together with its prompt, values of expressions,
|
| -source lines, and other types of output. Level 0 is for no
|
| -annotations, level 1 is for use when GDB is run as a subprocess of GNU
|
| -Emacs, level 3 is the maximum annotation suitable for programs that
|
| -control GDB, and level 2 annotations have been made obsolete (*note
|
| -Limitations of the Annotation Interface: (annotate)Limitations.).
|
| -
|
| -`set annotate LEVEL'
|
| - The GDB command `set annotate' sets the level of annotations to
|
| - the specified LEVEL.
|
| -
|
| -`show annotate'
|
| - Show the current annotation level.
|
| -
|
| - This chapter describes level 3 annotations.
|
| -
|
| - A simple example of starting up GDB with annotations is:
|
| -
|
| - $ gdb --annotate=3
|
| - GNU gdb 6.0
|
| - Copyright 2003 Free Software Foundation, Inc.
|
| - GDB is free software, covered by the GNU General Public License,
|
| - and you are welcome to change it and/or distribute copies of it
|
| - under certain conditions.
|
| - Type "show copying" to see the conditions.
|
| - There is absolutely no warranty for GDB. Type "show warranty"
|
| - for details.
|
| - This GDB was configured as "i386-pc-linux-gnu"
|
| -
|
| - ^Z^Zpre-prompt
|
| - (gdb)
|
| - ^Z^Zprompt
|
| - quit
|
| -
|
| - ^Z^Zpost-prompt
|
| - $
|
| -
|
| - Here `quit' is input to GDB; the rest is output from GDB. The three
|
| -lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
|
| -annotations; the rest is output from GDB.
|
| -
|
| -
|
| -File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
|
| -
|
| -28.2 The Server Prefix
|
| -======================
|
| -
|
| -If you prefix a command with `server ' then it will not affect the
|
| -command history, nor will it affect GDB's notion of which command to
|
| -repeat if <RET> is pressed on a line by itself. This means that
|
| -commands can be run behind a user's back by a front-end in a
|
| -transparent manner.
|
| -
|
| - The `server ' prefix does not affect the recording of values into
|
| -the value history; to print a value without recording it into the value
|
| -history, use the `output' command instead of the `print' command.
|
| -
|
| - Using this prefix also disables confirmation requests (*note
|
| -confirmation requests::).
|
| -
|
| -
|
| -File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
|
| -
|
| -28.3 Annotation for GDB Input
|
| -=============================
|
| -
|
| -When GDB prompts for input, it annotates this fact so it is possible to
|
| -know when to send output, when the output from a given command is over,
|
| -etc.
|
| -
|
| - Different kinds of input each have a different "input type". Each
|
| -input type has three annotations: a `pre-' annotation, which denotes
|
| -the beginning of any prompt which is being output, a plain annotation,
|
| -which denotes the end of the prompt, and then a `post-' annotation
|
| -which denotes the end of any echo which may (or may not) be associated
|
| -with the input. For example, the `prompt' input type features the
|
| -following annotations:
|
| -
|
| - ^Z^Zpre-prompt
|
| - ^Z^Zprompt
|
| - ^Z^Zpost-prompt
|
| -
|
| - The input types are
|
| -
|
| -`prompt'
|
| - When GDB is prompting for a command (the main GDB prompt).
|
| -
|
| -`commands'
|
| - When GDB prompts for a set of commands, like in the `commands'
|
| - command. The annotations are repeated for each command which is
|
| - input.
|
| -
|
| -`overload-choice'
|
| - When GDB wants the user to select between various overloaded
|
| - functions.
|
| -
|
| -`query'
|
| - When GDB wants the user to confirm a potentially dangerous
|
| - operation.
|
| -
|
| -`prompt-for-continue'
|
| - When GDB is asking the user to press return to continue. Note:
|
| - Don't expect this to work well; instead use `set height 0' to
|
| - disable prompting. This is because the counting of lines is buggy
|
| - in the presence of annotations.
|
| -
|
| -
|
| -File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
|
| -
|
| -28.4 Errors
|
| -===========
|
| -
|
| - ^Z^Zquit
|
| -
|
| - This annotation occurs right before GDB responds to an interrupt.
|
| -
|
| - ^Z^Zerror
|
| -
|
| - This annotation occurs right before GDB responds to an error.
|
| -
|
| - Quit and error annotations indicate that any annotations which GDB
|
| -was in the middle of may end abruptly. For example, if a
|
| -`value-history-begin' annotation is followed by a `error', one cannot
|
| -expect to receive the matching `value-history-end'. One cannot expect
|
| -not to receive it either, however; an error annotation does not
|
| -necessarily mean that GDB is immediately returning all the way to the
|
| -top level.
|
| -
|
| - A quit or error annotation may be preceded by
|
| -
|
| - ^Z^Zerror-begin
|
| -
|
| - Any output between that and the quit or error annotation is the error
|
| -message.
|
| -
|
| - Warning messages are not yet annotated.
|
| -
|
| -
|
| -File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
|
| -
|
| -28.5 Invalidation Notices
|
| -=========================
|
| -
|
| -The following annotations say that certain pieces of state may have
|
| -changed.
|
| -
|
| -`^Z^Zframes-invalid'
|
| - The frames (for example, output from the `backtrace' command) may
|
| - have changed.
|
| -
|
| -`^Z^Zbreakpoints-invalid'
|
| - The breakpoints may have changed. For example, the user just
|
| - added or deleted a breakpoint.
|
| -
|
| -
|
| -File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
|
| -
|
| -28.6 Running the Program
|
| -========================
|
| -
|
| -When the program starts executing due to a GDB command such as `step'
|
| -or `continue',
|
| -
|
| - ^Z^Zstarting
|
| -
|
| - is output. When the program stops,
|
| -
|
| - ^Z^Zstopped
|
| -
|
| - is output. Before the `stopped' annotation, a variety of
|
| -annotations describe how the program stopped.
|
| -
|
| -`^Z^Zexited EXIT-STATUS'
|
| - The program exited, and EXIT-STATUS is the exit status (zero for
|
| - successful exit, otherwise nonzero).
|
| -
|
| -`^Z^Zsignalled'
|
| - The program exited with a signal. After the `^Z^Zsignalled', the
|
| - annotation continues:
|
| -
|
| - INTRO-TEXT
|
| - ^Z^Zsignal-name
|
| - NAME
|
| - ^Z^Zsignal-name-end
|
| - MIDDLE-TEXT
|
| - ^Z^Zsignal-string
|
| - STRING
|
| - ^Z^Zsignal-string-end
|
| - END-TEXT
|
| -
|
| - where NAME is the name of the signal, such as `SIGILL' or
|
| - `SIGSEGV', and STRING is the explanation of the signal, such as
|
| - `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT,
|
| - MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
|
| - particular format.
|
| -
|
| -`^Z^Zsignal'
|
| - The syntax of this annotation is just like `signalled', but GDB is
|
| - just saying that the program received the signal, not that it was
|
| - terminated with it.
|
| -
|
| -`^Z^Zbreakpoint NUMBER'
|
| - The program hit breakpoint number NUMBER.
|
| -
|
| -`^Z^Zwatchpoint NUMBER'
|
| - The program hit watchpoint number NUMBER.
|
| -
|
| -
|
| -File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
|
| -
|
| -28.7 Displaying Source
|
| -======================
|
| -
|
| -The following annotation is used instead of displaying source code:
|
| -
|
| - ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
|
| -
|
| - where FILENAME is an absolute file name indicating which source
|
| -file, LINE is the line number within that file (where 1 is the first
|
| -line in the file), CHARACTER is the character position within the file
|
| -(where 0 is the first character in the file) (for most debug formats
|
| -this will necessarily point to the beginning of a line), MIDDLE is
|
| -`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
|
| -the beginning of the line, and ADDR is the address in the target
|
| -program associated with the source which is being displayed. ADDR is
|
| -in the form `0x' followed by one or more lowercase hex digits (note
|
| -that this does not depend on the language).
|
| -
|
| -
|
| -File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top
|
| -
|
| -29 JIT Compilation Interface
|
| -****************************
|
| -
|
| -This chapter documents GDB's "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.
|
| -
|
| - Programs that use JIT compilation are normally difficult to debug
|
| -because portions of their code are generated at runtime, instead of
|
| -being loaded from object files, which is where GDB normally finds the
|
| -program's symbols and debug information. In order to debug programs
|
| -that use JIT compilation, GDB has an interface that allows the program
|
| -to register in-memory symbol files with GDB at runtime.
|
| -
|
| - If you are using GDB to debug a program that uses this interface,
|
| -then it should work transparently so long as you have not stripped the
|
| -binary. If you are developing a JIT compiler, then the interface is
|
| -documented in the rest of this chapter. At this time, the only known
|
| -client of this interface is the LLVM JIT.
|
| -
|
| - Broadly speaking, the JIT interface mirrors the dynamic loader
|
| -interface. The JIT compiler communicates with GDB by writing data into
|
| -a global variable and calling a fuction at a well-known symbol. When
|
| -GDB attaches, it reads a linked list of symbol files from the global
|
| -variable to find existing code, and puts a breakpoint in the function
|
| -so that it can find out about additional code.
|
| -
|
| -* Menu:
|
| -
|
| -* Declarations:: Relevant C struct declarations
|
| -* Registering Code:: Steps to register code
|
| -* Unregistering Code:: Steps to unregister code
|
| -* Custom Debug Info:: Emit debug information in a custom format
|
| -
|
| -
|
| -File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface
|
| -
|
| -29.1 JIT Declarations
|
| -=====================
|
| -
|
| -These are the relevant struct declarations that a C program should
|
| -include to implement the interface:
|
| -
|
| - typedef enum
|
| - {
|
| - JIT_NOACTION = 0,
|
| - JIT_REGISTER_FN,
|
| - JIT_UNREGISTER_FN
|
| - } jit_actions_t;
|
| -
|
| - struct jit_code_entry
|
| - {
|
| - struct jit_code_entry *next_entry;
|
| - struct jit_code_entry *prev_entry;
|
| - const char *symfile_addr;
|
| - uint64_t symfile_size;
|
| - };
|
| -
|
| - struct jit_descriptor
|
| - {
|
| - uint32_t version;
|
| - /* This type should be jit_actions_t, but we use uint32_t
|
| - to be explicit about the bitwidth. */
|
| - uint32_t action_flag;
|
| - struct jit_code_entry *relevant_entry;
|
| - struct jit_code_entry *first_entry;
|
| - };
|
| -
|
| - /* GDB puts a breakpoint in this function. */
|
| - void __attribute__((noinline)) __jit_debug_register_code() { };
|
| -
|
| - /* Make sure to specify the version statically, because the
|
| - debugger may check the version before we can set it. */
|
| - struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 };
|
| -
|
| - If the JIT is multi-threaded, then it is important that the JIT
|
| -synchronize any modifications to this global data properly, which can
|
| -easily be done by putting a global mutex around modifications to these
|
| -structures.
|
| -
|
| -
|
| -File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface
|
| -
|
| -29.2 Registering Code
|
| -=====================
|
| -
|
| -To register code with GDB, the JIT should follow this protocol:
|
| -
|
| - * Generate an object file in memory with symbols and other desired
|
| - debug information. The file must include the virtual addresses of
|
| - the sections.
|
| -
|
| - * Create a code entry for the file, which gives the start and size
|
| - of the symbol file.
|
| -
|
| - * Add it to the linked list in the JIT descriptor.
|
| -
|
| - * Point the relevant_entry field of the descriptor at the entry.
|
| -
|
| - * Set `action_flag' to `JIT_REGISTER' and call
|
| - `__jit_debug_register_code'.
|
| -
|
| - When GDB is attached and the breakpoint fires, GDB uses the
|
| -`relevant_entry' pointer so it doesn't have to walk the list looking for
|
| -new code. However, the linked list must still be maintained in order
|
| -to allow GDB to attach to a running process and still find the symbol
|
| -files.
|
| -
|
| -
|
| -File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface
|
| -
|
| -29.3 Unregistering Code
|
| -=======================
|
| -
|
| -If code is freed, then the JIT should use the following protocol:
|
| -
|
| - * Remove the code entry corresponding to the code from the linked
|
| - list.
|
| -
|
| - * Point the `relevant_entry' field of the descriptor at the code
|
| - entry.
|
| -
|
| - * Set `action_flag' to `JIT_UNREGISTER' and call
|
| - `__jit_debug_register_code'.
|
| -
|
| - If the JIT frees or recompiles code without unregistering it, then
|
| -GDB and the JIT will leak the memory used for the associated symbol
|
| -files.
|
| -
|
| -
|
| -File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface
|
| -
|
| -29.4 Custom Debug Info
|
| -======================
|
| -
|
| -Generating debug information in platform-native file formats (like ELF
|
| -or COFF) may be an overkill for JIT compilers; especially if all the
|
| -debug info is used for is displaying a meaningful backtrace. The issue
|
| -can be resolved by having the JIT writers decide on a debug info format
|
| -and also provide a reader that parses the debug info generated by the
|
| -JIT compiler. This section gives a brief overview on writing such a
|
| -parser. More specific details can be found in the source file
|
| -`gdb/jit-reader.in', which is also installed as a header at
|
| -`INCLUDEDIR/gdb/jit-reader.h' for easy inclusion.
|
| -
|
| - The reader is implemented as a shared object (so this functionality
|
| -is not available on platforms which don't allow loading shared objects
|
| -at runtime). Two GDB commands, `jit-reader-load' and
|
| -`jit-reader-unload' are provided, to be used to load and unload the
|
| -readers from a preconfigured directory. Once loaded, the shared object
|
| -is used the parse the debug information emitted by the JIT compiler.
|
| -
|
| -* Menu:
|
| -
|
| -* Using JIT Debug Info Readers:: How to use supplied readers correctly
|
| -* Writing JIT Debug Info Readers:: Creating a debug-info reader
|
| -
|
| -
|
| -File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info
|
| -
|
| -29.4.1 Using JIT Debug Info Readers
|
| ------------------------------------
|
| -
|
| -Readers can be loaded and unloaded using the `jit-reader-load' and
|
| -`jit-reader-unload' commands.
|
| -
|
| -`jit-reader-load READER-NAME'
|
| - Load the JIT reader named READER-NAME. On a UNIX system, this
|
| - will usually load `LIBDIR/gdb/READER-NAME', where LIBDIR is the
|
| - system library directory, usually `/usr/local/lib'. Only one
|
| - reader can be active at a time; trying to load a second reader
|
| - when one is already loaded will result in GDB reporting an error.
|
| - A new JIT reader can be loaded by first unloading the current one
|
| - using `jit-reader-load' and then invoking `jit-reader-load'.
|
| -
|
| -`jit-reader-unload'
|
| - Unload the currently loaded JIT reader.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info
|
| -
|
| -29.4.2 Writing JIT Debug Info Readers
|
| --------------------------------------
|
| -
|
| -As mentioned, a reader is essentially a shared object conforming to a
|
| -certain ABI. This ABI is described in `jit-reader.h'.
|
| -
|
| - `jit-reader.h' defines the structures, macros and functions required
|
| -to write a reader. It is installed (along with GDB), in
|
| -`INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory.
|
| -
|
| - Readers need to be released under a GPL compatible license. A reader
|
| -can be declared as released under such a license by placing the macro
|
| -`GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file.
|
| -
|
| - The entry point for readers is the symbol `gdb_init_reader', which
|
| -is expected to be a function with the prototype
|
| -
|
| - extern struct gdb_reader_funcs *gdb_init_reader (void);
|
| -
|
| - `struct gdb_reader_funcs' contains a set of pointers to callback
|
| -functions. These functions are executed to read the debug info
|
| -generated by the JIT compiler (`read'), to unwind stack frames
|
| -(`unwind') and to create canonical frame IDs (`get_Frame_id'). It also
|
| -has a callback that is called when the reader is being unloaded
|
| -(`destroy'). The struct looks like this
|
| -
|
| - struct gdb_reader_funcs
|
| - {
|
| - /* Must be set to GDB_READER_INTERFACE_VERSION. */
|
| - int reader_version;
|
| -
|
| - /* For use by the reader. */
|
| - void *priv_data;
|
| -
|
| - gdb_read_debug_info *read;
|
| - gdb_unwind_frame *unwind;
|
| - gdb_get_frame_id *get_frame_id;
|
| - gdb_destroy_reader *destroy;
|
| - };
|
| -
|
| - The callbacks are provided with another set of callbacks by GDB to
|
| -do their job. For `read', these callbacks are passed in a `struct
|
| -gdb_symbol_callbacks' and for `unwind' and `get_frame_id', in a `struct
|
| -gdb_unwind_callbacks'. `struct gdb_symbol_callbacks' has callbacks to
|
| -create new object files and new symbol tables inside those object
|
| -files. `struct gdb_unwind_callbacks' has callbacks to read registers
|
| -off the current frame and to write out the values of the registers in
|
| -the previous frame. Both have a callback (`target_read') to read bytes
|
| -off the target's address space.
|
| -
|
| -
|
| -File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top
|
| -
|
| -30 In-Process Agent
|
| -*******************
|
| -
|
| -The traditional debugging model is conceptually low-speed, but works
|
| -fine, because most bugs can be reproduced in debugging-mode execution.
|
| -However, as multi-core or many-core processors are becoming mainstream,
|
| -and multi-threaded programs become more and more popular, there should
|
| -be more and more bugs that only manifest themselves at normal-mode
|
| -execution, for example, thread races, because debugger's interference
|
| -with the program's timing may conceal the bugs. On the other hand, in
|
| -some applications, it is not feasible for the debugger to interrupt the
|
| -program's execution long enough for the developer to learn anything
|
| -helpful about its behavior. If the program's correctness depends on
|
| -its real-time behavior, delays introduced by a debugger might cause the
|
| -program to fail, even when the code itself is correct. It is useful to
|
| -be able to observe the program's behavior without interrupting it.
|
| -
|
| - Therefore, traditional debugging model is too intrusive to reproduce
|
| -some bugs. In order to reduce the interference with the program, we can
|
| -reduce the number of operations performed by debugger. The "In-Process
|
| -Agent", a shared library, is running within the same process with
|
| -inferior, and is able to perform some debugging operations itself. As
|
| -a result, debugger is only involved when necessary, and performance of
|
| -debugging can be improved accordingly. Note that interference with
|
| -program can be reduced but can't be removed completely, because the
|
| -in-process agent will still stop or slow down the program.
|
| -
|
| - The in-process agent can interpret and execute Agent Expressions
|
| -(*note Agent Expressions::) during performing debugging operations. The
|
| -agent expressions can be used for different purposes, such as collecting
|
| -data in tracepoints, and condition evaluation in breakpoints.
|
| -
|
| - You can control whether the in-process agent is used as an aid for
|
| -debugging with the following commands:
|
| -
|
| -`set agent on'
|
| - Causes the in-process agent to perform some operations on behalf
|
| - of the debugger. Just which operations requested by the user will
|
| - be done by the in-process agent depends on the its capabilities.
|
| - For example, if you request to evaluate breakpoint conditions in
|
| - the in-process agent, and the in-process agent has such capability
|
| - as well, then breakpoint conditions will be evaluated in the
|
| - in-process agent.
|
| -
|
| -`set agent off'
|
| - Disables execution of debugging operations by the in-process
|
| - agent. All of the operations will be performed by GDB.
|
| -
|
| -`show agent'
|
| - Display the current setting of execution of debugging operations by
|
| - the in-process agent.
|
| -
|
| -* Menu:
|
| -
|
| -* In-Process Agent Protocol::
|
| -
|
| -
|
| -File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent
|
| -
|
| -30.1 In-Process Agent Protocol
|
| -==============================
|
| -
|
| -The in-process agent is able to communicate with both GDB and GDBserver
|
| -(*note In-Process Agent::). This section documents the protocol used
|
| -for communications between GDB or GDBserver and the IPA. In general,
|
| -GDB or GDBserver sends commands (*note IPA Protocol Commands::) and
|
| -data to in-process agent, and then in-process agent replies back with
|
| -the return result of the command, or some other information. The data
|
| -sent to in-process agent is composed of primitive data types, such as
|
| -4-byte or 8-byte type, and composite types, which are called objects
|
| -(*note IPA Protocol Objects::).
|
| -
|
| -* Menu:
|
| -
|
| -* IPA Protocol Objects::
|
| -* IPA Protocol Commands::
|
| -
|
| -
|
| -File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol
|
| -
|
| -30.1.1 IPA Protocol Objects
|
| ----------------------------
|
| -
|
| -The commands sent to and results received from agent may contain some
|
| -complex data types called "objects".
|
| -
|
| - The in-process agent is running on the same machine with GDB or
|
| -GDBserver, so it doesn't have to handle as much differences between two
|
| -ends as remote protocol (*note Remote Protocol::) tries to handle.
|
| -However, there are still some differences of two ends in two processes:
|
| -
|
| - 1. word size. On some 64-bit machines, GDB or GDBserver can be
|
| - compiled as a 64-bit executable, while in-process agent is a
|
| - 32-bit one.
|
| -
|
| - 2. ABI. Some machines may have multiple types of ABI, GDB or
|
| - GDBserver is compiled with one, and in-process agent is compiled
|
| - with the other one.
|
| -
|
| - Here are the IPA Protocol Objects:
|
| -
|
| - 1. agent expression object. It represents an agent expression (*note
|
| - Agent Expressions::).
|
| -
|
| - 2. tracepoint action object. It represents a tracepoint action
|
| - (*note Tracepoint Action Lists: Tracepoint Actions.) to collect
|
| - registers, memory, static trace data and to evaluate expression.
|
| -
|
| - 3. tracepoint object. It represents a tracepoint (*note
|
| - Tracepoints::).
|
| -
|
| -
|
| - The following table describes important attributes of each IPA
|
| -protocol object:
|
| -
|
| -Name Size Description
|
| ----------------------------------------------------------------------------
|
| -_agent expression
|
| -object_
|
| -length 4 length of bytes code
|
| -byte code LENGTH contents of byte code
|
| -_tracepoint action
|
| -for collecting
|
| -memory_
|
| -'M' 1 type of tracepoint action
|
| -addr 8 if BASEREG is `-1', ADDR is the
|
| - address of the lowest byte to
|
| - collect, otherwise ADDR is the
|
| - offset of BASEREG for memory
|
| - collecting.
|
| -len 8 length of memory for collecting
|
| -basereg 4 the register number containing the
|
| - starting memory address for
|
| - collecting.
|
| -_tracepoint action
|
| -for collecting
|
| -registers_
|
| -'R' 1 type of tracepoint action
|
| -_tracepoint action
|
| -for collecting static
|
| -trace data_
|
| -'L' 1 type of tracepoint action
|
| -_tracepoint action
|
| -for expression
|
| -evaluation_
|
| -'X' 1 type of tracepoint action
|
| -agent expression length of *Note agent expression object::
|
| -_tracepoint object_
|
| -number 4 number of tracepoint
|
| -address 8 address of tracepoint inserted on
|
| -type 4 type of tracepoint
|
| -enabled 1 enable or disable of tracepoint
|
| -step_count 8 step
|
| -pass_count 8 pass
|
| -numactions 4 number of tracepoint actions
|
| -hit count 8 hit count
|
| -trace frame usage 8 trace frame usage
|
| -compiled_cond 8 compiled condition
|
| -orig_size 8 orig size
|
| -condition 4 if zero if condition is NULL,
|
| - condition is otherwise is *Note agent expression
|
| - NULL object::
|
| - otherwise
|
| - length of
|
| - *Note agent
|
| - expression
|
| - object::
|
| -actions variable numactions number of *Note
|
| - tracepoint action object::
|
| -
|
| -
|
| -File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol
|
| -
|
| -30.1.2 IPA Protocol Commands
|
| -----------------------------
|
| -
|
| -The spaces in each command are delimiters to ease reading this commands
|
| -specification. They don't exist in real commands.
|
| -
|
| -`FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD'
|
| - Installs a new fast tracepoint described by TRACEPOINT_OBJECT
|
| - (*note tracepoint object::). GDB_JUMP_PAD_HEAD, 8-byte long, is
|
| - the head of "jumppad", which is used to jump to data collection
|
| - routine in IPA finally.
|
| -
|
| - Replies:
|
| - `OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP'
|
| - TARGET_ADDRESS is address of tracepoint in the inferior.
|
| - GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of
|
| - TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. FJUMP
|
| - contains a sequence of instructions jump to jumppad entry.
|
| - FJUMP_SIZE, 4-byte long, is the size of FJUMP.
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -
|
| -`qTfSTM'
|
| - *Note qTfSTM::.
|
| -
|
| -`qTsSTM'
|
| - *Note qTsSTM::.
|
| -
|
| -`qTSTMat'
|
| - *Note qTSTMat::.
|
| -
|
| -`probe_marker_at:ADDRESS'
|
| - Asks in-process agent to probe the marker at ADDRESS.
|
| -
|
| - Replies:
|
| - `E NN'
|
| - for an error
|
| -
|
| -`unprobe_marker_at:ADDRESS'
|
| - Asks in-process agent to unprobe the marker at ADDRESS.
|
| -
|
| -
|
| -File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top
|
| -
|
| -31 Reporting Bugs in GDB
|
| -************************
|
| -
|
| -Your bug reports play an essential role in making GDB reliable.
|
| -
|
| - Reporting a bug may help you by bringing a solution to your problem,
|
| -or it may not. But in any case the principal function of a bug report
|
| -is to help the entire community by making the next version of GDB work
|
| -better. Bug reports are your contribution to the maintenance of GDB.
|
| -
|
| - In order for a bug report to serve its purpose, you must include the
|
| -information that enables us to fix the bug.
|
| -
|
| -* Menu:
|
| -
|
| -* Bug Criteria:: Have you found a bug?
|
| -* Bug Reporting:: How to report bugs
|
| -
|
| -
|
| -File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
|
| -
|
| -31.1 Have You Found a Bug?
|
| -==========================
|
| -
|
| -If you are not sure whether you have found a bug, here are some
|
| -guidelines:
|
| -
|
| - * If the debugger gets a fatal signal, for any input whatever, that
|
| - is a GDB bug. Reliable debuggers never crash.
|
| -
|
| - * If GDB produces an error message for valid input, that is a bug.
|
| - (Note that if you're cross debugging, the problem may also be
|
| - somewhere in the connection to the target.)
|
| -
|
| - * If GDB does not produce an error message for invalid input, that
|
| - is a bug. However, you should note that your idea of "invalid
|
| - input" might be our idea of "an extension" or "support for
|
| - traditional practice".
|
| -
|
| - * If you are an experienced user of debugging tools, your suggestions
|
| - for improvement of GDB are welcome in any case.
|
| -
|
| -
|
| -File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
|
| -
|
| -31.2 How to Report Bugs
|
| -=======================
|
| -
|
| -A number of companies and individuals offer support for GNU products.
|
| -If you obtained GDB from a support organization, we recommend you
|
| -contact that organization first.
|
| -
|
| - You can find contact information for many support companies and
|
| -individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
|
| -
|
| - In any event, we also recommend that you submit bug reports for GDB.
|
| -The preferred method is to submit them directly using GDB's Bugs web
|
| -page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the
|
| -e-mail gateway <bug-gdb@gnu.org> can be used.
|
| -
|
| - *Do not send bug reports to `info-gdb', or to `help-gdb', or to any
|
| -newsgroups.* Most users of GDB do not want to receive bug reports.
|
| -Those that do have arranged to receive `bug-gdb'.
|
| -
|
| - The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
|
| -serves as a repeater. The mailing list and the newsgroup carry exactly
|
| -the same messages. Often people think of posting bug reports to the
|
| -newsgroup instead of mailing them. This appears to work, but it has one
|
| -problem which can be crucial: a newsgroup posting often lacks a mail
|
| -path back to the sender. Thus, if we need to ask for more information,
|
| -we may be unable to reach you. For this reason, it is better to send
|
| -bug reports to the mailing list.
|
| -
|
| - The fundamental principle of reporting bugs usefully is this:
|
| -*report all the facts*. If you are not sure whether to state a fact or
|
| -leave it out, state it!
|
| -
|
| - Often people omit facts because they think they know what causes the
|
| -problem and assume that some details do not matter. Thus, you might
|
| -assume that the name of the variable you use in an example does not
|
| -matter. Well, probably it does not, but one cannot be sure. Perhaps
|
| -the bug is a stray memory reference which happens to fetch from the
|
| -location where that name is stored in memory; perhaps, if the name were
|
| -different, the contents of that location would fool the debugger into
|
| -doing the right thing despite the bug. Play it safe and give a
|
| -specific, complete example. That is the easiest thing for you to do,
|
| -and the most helpful.
|
| -
|
| - Keep in mind that the purpose of a bug report is to enable us to fix
|
| -the bug. It may be that the bug has been reported previously, but
|
| -neither you nor we can know that unless your bug report is complete and
|
| -self-contained.
|
| -
|
| - Sometimes people give a few sketchy facts and ask, "Does this ring a
|
| -bell?" Those bug reports are useless, and we urge everyone to _refuse
|
| -to respond to them_ except to chide the sender to report bugs properly.
|
| -
|
| - To enable us to fix the bug, you should include all these things:
|
| -
|
| - * The version of GDB. GDB announces it if you start with no
|
| - arguments; you can also print it at any time using `show version'.
|
| -
|
| - Without this, we will not know whether there is any point in
|
| - looking for the bug in the current version of GDB.
|
| -
|
| - * The type of machine you are using, and the operating system name
|
| - and version number.
|
| -
|
| - * What compiler (and its version) was used to compile GDB--e.g.
|
| - "gcc-2.8.1".
|
| -
|
| - * What compiler (and its version) was used to compile the program
|
| - you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
|
| - C Compiler". For GCC, you can say `gcc --version' to get this
|
| - information; for other compilers, see the documentation for those
|
| - compilers.
|
| -
|
| - * The command arguments you gave the compiler to compile your
|
| - example and observe the bug. For example, did you use `-O'? To
|
| - guarantee you will not omit something important, list them all. A
|
| - copy of the Makefile (or the output from make) is sufficient.
|
| -
|
| - If we were to try to guess the arguments, we would probably guess
|
| - wrong and then we might not encounter the bug.
|
| -
|
| - * A complete input script, and all necessary source files, that will
|
| - reproduce the bug.
|
| -
|
| - * A description of what behavior you observe that you believe is
|
| - incorrect. For example, "It gets a fatal signal."
|
| -
|
| - Of course, if the bug is that GDB gets a fatal signal, then we
|
| - will certainly notice it. But if the bug is incorrect output, we
|
| - might not notice unless it is glaringly wrong. You might as well
|
| - not give us a chance to make a mistake.
|
| -
|
| - Even if the problem you experience is a fatal signal, you should
|
| - still say so explicitly. Suppose something strange is going on,
|
| - such as, your copy of GDB is out of synch, or you have encountered
|
| - a bug in the C library on your system. (This has happened!) Your
|
| - copy might crash and ours would not. If you told us to expect a
|
| - crash, then when ours fails to crash, we would know that the bug
|
| - was not happening for us. If you had not told us to expect a
|
| - crash, then we would not be able to draw any conclusion from our
|
| - observations.
|
| -
|
| - To collect all this information, you can use a session recording
|
| - program such as `script', which is available on many Unix systems.
|
| - Just run your GDB session inside `script' and then include the
|
| - `typescript' file with your bug report.
|
| -
|
| - Another way to record a GDB session is to run GDB inside Emacs and
|
| - then save the entire buffer to a file.
|
| -
|
| - * If you wish to suggest changes to the GDB source, send us context
|
| - diffs. If you even discuss something in the GDB source, refer to
|
| - it by context, not by line number.
|
| -
|
| - The line numbers in our development sources will not match those
|
| - in your sources. Your line numbers would convey no useful
|
| - information to us.
|
| -
|
| -
|
| - Here are some things that are not necessary:
|
| -
|
| - * A description of the envelope of the bug.
|
| -
|
| - Often people who encounter a bug spend a lot of time investigating
|
| - which changes to the input file will make the bug go away and which
|
| - changes will not affect it.
|
| -
|
| - This is often time consuming and not very useful, because the way
|
| - we will find the bug is by running a single example under the
|
| - debugger with breakpoints, not by pure deduction from a series of
|
| - examples. We recommend that you save your time for something else.
|
| -
|
| - Of course, if you can find a simpler example to report _instead_
|
| - of the original one, that is a convenience for us. Errors in the
|
| - output will be easier to spot, running under the debugger will take
|
| - less time, and so on.
|
| -
|
| - However, simplification is not vital; if you do not want to do
|
| - this, report the bug anyway and send us the entire test case you
|
| - used.
|
| -
|
| - * A patch for the bug.
|
| -
|
| - A patch for the bug does help us if it is a good one. But do not
|
| - omit the necessary information, such as the test case, on the
|
| - assumption that a patch is all we need. We might see problems
|
| - with your patch and decide to fix the problem another way, or we
|
| - might not understand it at all.
|
| -
|
| - Sometimes with a program as complicated as GDB it is very hard to
|
| - construct an example that will make the program follow a certain
|
| - path through the code. If you do not send us the example, we will
|
| - not be able to construct one, so we will not be able to verify
|
| - that the bug is fixed.
|
| -
|
| - And if we cannot understand what bug you are trying to fix, or why
|
| - your patch should be an improvement, we will not install it. A
|
| - test case will help us to understand.
|
| -
|
| - * A guess about what the bug is or what it depends on.
|
| -
|
| - Such guesses are usually wrong. Even we cannot guess right about
|
| - such things without first using the debugger to find the facts.
|
| -
|
| -
|
| -File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
|
| -
|
| -32 Command Line Editing
|
| -***********************
|
| -
|
| -This chapter describes the basic features of the GNU command line
|
| -editing interface.
|
| -
|
| -* Menu:
|
| -
|
| -* Introduction and Notation:: Notation used in this text.
|
| -* Readline Interaction:: The minimum set of commands for editing a line.
|
| -* Readline Init File:: Customizing Readline from a user's view.
|
| -* Bindable Readline Commands:: A description of most of the Readline commands
|
| - available for binding
|
| -* Readline vi Mode:: A short description of how to make Readline
|
| - behave like the vi editor.
|
| -
|
| -
|
| -File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
|
| -
|
| -32.1 Introduction to Line Editing
|
| -=================================
|
| -
|
| -The following paragraphs describe the notation used to represent
|
| -keystrokes.
|
| -
|
| - The text `C-k' is read as `Control-K' and describes the character
|
| -produced when the <k> key is pressed while the Control key is depressed.
|
| -
|
| - The text `M-k' is read as `Meta-K' and describes the character
|
| -produced when the Meta key (if you have one) is depressed, and the <k>
|
| -key is pressed. The Meta key is labeled <ALT> on many keyboards. On
|
| -keyboards with two keys labeled <ALT> (usually to either side of the
|
| -space bar), the <ALT> on the left side is generally set to work as a
|
| -Meta key. The <ALT> key on the right may also be configured to work as
|
| -a Meta key or may be configured as some other modifier, such as a
|
| -Compose key for typing accented characters.
|
| -
|
| - If you do not have a Meta or <ALT> key, or another key working as a
|
| -Meta key, the identical keystroke can be generated by typing <ESC>
|
| -_first_, and then typing <k>. Either process is known as "metafying"
|
| -the <k> key.
|
| -
|
| - The text `M-C-k' is read as `Meta-Control-k' and describes the
|
| -character produced by "metafying" `C-k'.
|
| -
|
| - In addition, several keys have their own names. Specifically,
|
| -<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
|
| -when seen in this text, or in an init file (*note Readline Init File::).
|
| -If your keyboard lacks a <LFD> key, typing <C-j> will produce the
|
| -desired character. The <RET> key may be labeled <Return> or <Enter> on
|
| -some keyboards.
|
| -
|
| -
|
| -File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
|
| -
|
| -32.2 Readline Interaction
|
| -=========================
|
| -
|
| -Often during an interactive session you type in a long line of text,
|
| -only to notice that the first word on the line is misspelled. The
|
| -Readline library gives you a set of commands for manipulating the text
|
| -as you type it in, allowing you to just fix your typo, and not forcing
|
| -you to retype the majority of the line. Using these editing commands,
|
| -you move the cursor to the place that needs correction, and delete or
|
| -insert the text of the corrections. Then, when you are satisfied with
|
| -the line, you simply press <RET>. You do not have to be at the end of
|
| -the line to press <RET>; the entire line is accepted regardless of the
|
| -location of the cursor within the line.
|
| -
|
| -* Menu:
|
| -
|
| -* Readline Bare Essentials:: The least you need to know about Readline.
|
| -* Readline Movement Commands:: Moving about the input line.
|
| -* Readline Killing Commands:: How to delete text, and how to get it back!
|
| -* Readline Arguments:: Giving numeric arguments to commands.
|
| -* Searching:: Searching through previous lines.
|
| -
|
| -
|
| -File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
|
| -
|
| -32.2.1 Readline Bare Essentials
|
| --------------------------------
|
| -
|
| -In order to enter characters into the line, simply type them. The typed
|
| -character appears where the cursor was, and then the cursor moves one
|
| -space to the right. If you mistype a character, you can use your erase
|
| -character to back up and delete the mistyped character.
|
| -
|
| - Sometimes you may mistype a character, and not notice the error
|
| -until you have typed several other characters. In that case, you can
|
| -type `C-b' to move the cursor to the left, and then correct your
|
| -mistake. Afterwards, you can move the cursor to the right with `C-f'.
|
| -
|
| - When you add text in the middle of a line, you will notice that
|
| -characters to the right of the cursor are `pushed over' to make room
|
| -for the text that you have inserted. Likewise, when you delete text
|
| -behind the cursor, characters to the right of the cursor are `pulled
|
| -back' to fill in the blank space created by the removal of the text. A
|
| -list of the bare essentials for editing the text of an input line
|
| -follows.
|
| -
|
| -`C-b'
|
| - Move back one character.
|
| -
|
| -`C-f'
|
| - Move forward one character.
|
| -
|
| -<DEL> or <Backspace>
|
| - Delete the character to the left of the cursor.
|
| -
|
| -`C-d'
|
| - Delete the character underneath the cursor.
|
| -
|
| -Printing characters
|
| - Insert the character into the line at the cursor.
|
| -
|
| -`C-_' or `C-x C-u'
|
| - Undo the last editing command. You can undo all the way back to an
|
| - empty line.
|
| -
|
| -(Depending on your configuration, the <Backspace> key be set to delete
|
| -the character to the left of the cursor and the <DEL> key set to delete
|
| -the character underneath the cursor, like `C-d', rather than the
|
| -character to the left of the cursor.)
|
| -
|
| -
|
| -File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
|
| -
|
| -32.2.2 Readline Movement Commands
|
| ----------------------------------
|
| -
|
| -The above table describes the most basic keystrokes that you need in
|
| -order to do editing of the input line. For your convenience, many
|
| -other commands have been added in addition to `C-b', `C-f', `C-d', and
|
| -<DEL>. Here are some commands for moving more rapidly about the line.
|
| -
|
| -`C-a'
|
| - Move to the start of the line.
|
| -
|
| -`C-e'
|
| - Move to the end of the line.
|
| -
|
| -`M-f'
|
| - Move forward a word, where a word is composed of letters and
|
| - digits.
|
| -
|
| -`M-b'
|
| - Move backward a word.
|
| -
|
| -`C-l'
|
| - Clear the screen, reprinting the current line at the top.
|
| -
|
| - Notice how `C-f' moves forward a character, while `M-f' moves
|
| -forward a word. It is a loose convention that control keystrokes
|
| -operate on characters while meta keystrokes operate on words.
|
| -
|
| -
|
| -File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
|
| -
|
| -32.2.3 Readline Killing Commands
|
| ---------------------------------
|
| -
|
| -"Killing" text means to delete the text from the line, but to save it
|
| -away for later use, usually by "yanking" (re-inserting) it back into
|
| -the line. (`Cut' and `paste' are more recent jargon for `kill' and
|
| -`yank'.)
|
| -
|
| - If the description for a command says that it `kills' text, then you
|
| -can be sure that you can get the text back in a different (or the same)
|
| -place later.
|
| -
|
| - When you use a kill command, the text is saved in a "kill-ring".
|
| -Any number of consecutive kills save all of the killed text together, so
|
| -that when you yank it back, you get it all. The kill ring is not line
|
| -specific; the text that you killed on a previously typed line is
|
| -available to be yanked back later, when you are typing another line.
|
| -
|
| - Here is the list of commands for killing text.
|
| -
|
| -`C-k'
|
| - Kill the text from the current cursor position to the end of the
|
| - line.
|
| -
|
| -`M-d'
|
| - Kill from the cursor to the end of the current word, or, if between
|
| - words, to the end of the next word. Word boundaries are the same
|
| - as those used by `M-f'.
|
| -
|
| -`M-<DEL>'
|
| - Kill from the cursor the start of the current word, or, if between
|
| - words, to the start of the previous word. Word boundaries are the
|
| - same as those used by `M-b'.
|
| -
|
| -`C-w'
|
| - Kill from the cursor to the previous whitespace. This is
|
| - different than `M-<DEL>' because the word boundaries differ.
|
| -
|
| -
|
| - Here is how to "yank" the text back into the line. Yanking means to
|
| -copy the most-recently-killed text from the kill buffer.
|
| -
|
| -`C-y'
|
| - Yank the most recently killed text back into the buffer at the
|
| - cursor.
|
| -
|
| -`M-y'
|
| - Rotate the kill-ring, and yank the new top. You can only do this
|
| - if the prior command is `C-y' or `M-y'.
|
| -
|
| -
|
| -File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
|
| -
|
| -32.2.4 Readline Arguments
|
| --------------------------
|
| -
|
| -You can pass numeric arguments to Readline commands. Sometimes the
|
| -argument acts as a repeat count, other times it is the sign of the
|
| -argument that is significant. If you pass a negative argument to a
|
| -command which normally acts in a forward direction, that command will
|
| -act in a backward direction. For example, to kill text back to the
|
| -start of the line, you might type `M-- C-k'.
|
| -
|
| - The general way to pass numeric arguments to a command is to type
|
| -meta digits before the command. If the first `digit' typed is a minus
|
| -sign (`-'), then the sign of the argument will be negative. Once you
|
| -have typed one meta digit to get the argument started, you can type the
|
| -remainder of the digits, and then the command. For example, to give
|
| -the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
|
| -will delete the next ten characters on the input line.
|
| -
|
| -
|
| -File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
|
| -
|
| -32.2.5 Searching for Commands in the History
|
| ---------------------------------------------
|
| -
|
| -Readline provides commands for searching through the command history
|
| -for lines containing a specified string. There are two search modes:
|
| -"incremental" and "non-incremental".
|
| -
|
| - Incremental searches begin before the user has finished typing the
|
| -search string. As each character of the search string is typed,
|
| -Readline displays the next entry from the history matching the string
|
| -typed so far. An incremental search requires only as many characters
|
| -as needed to find the desired history entry. To search backward in the
|
| -history for a particular string, type `C-r'. Typing `C-s' searches
|
| -forward through the history. The characters present in the value of
|
| -the `isearch-terminators' variable are used to terminate an incremental
|
| -search. If that variable has not been assigned a value, the <ESC> and
|
| -`C-J' characters will terminate an incremental search. `C-g' will
|
| -abort an incremental search and restore the original line. When the
|
| -search is terminated, the history entry containing the search string
|
| -becomes the current line.
|
| -
|
| - To find other matching entries in the history list, type `C-r' or
|
| -`C-s' as appropriate. This will search backward or forward in the
|
| -history for the next entry matching the search string typed so far.
|
| -Any other key sequence bound to a Readline command will terminate the
|
| -search and execute that command. For instance, a <RET> will terminate
|
| -the search and accept the line, thereby executing the command from the
|
| -history list. A movement command will terminate the search, make the
|
| -last line found the current line, and begin editing.
|
| -
|
| - Readline remembers the last incremental search string. If two
|
| -`C-r's are typed without any intervening characters defining a new
|
| -search string, any remembered search string is used.
|
| -
|
| - Non-incremental searches read the entire search string before
|
| -starting to search for matching history lines. The search string may be
|
| -typed by the user or be part of the contents of the current line.
|
| -
|
| -
|
| -File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
|
| -
|
| -32.3 Readline Init File
|
| -=======================
|
| -
|
| -Although the Readline library comes with a set of Emacs-like
|
| -keybindings installed by default, it is possible to use a different set
|
| -of keybindings. Any user can customize programs that use Readline by
|
| -putting commands in an "inputrc" file, conventionally in his home
|
| -directory. The name of this file is taken from the value of the
|
| -environment variable `INPUTRC'. If that variable is unset, the default
|
| -is `~/.inputrc'. If that file does not exist or cannot be read, the
|
| -ultimate default is `/etc/inputrc'.
|
| -
|
| - When a program which uses the Readline library starts up, the init
|
| -file is read, and the key bindings are set.
|
| -
|
| - In addition, the `C-x C-r' command re-reads this init file, thus
|
| -incorporating any changes that you might have made to it.
|
| -
|
| -* Menu:
|
| -
|
| -* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
|
| -
|
| -* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
|
| -
|
| -* Sample Init File:: An example inputrc file.
|
| -
|
| -
|
| -File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
|
| -
|
| -32.3.1 Readline Init File Syntax
|
| ---------------------------------
|
| -
|
| -There are only a few basic constructs allowed in the Readline init
|
| -file. Blank lines are ignored. Lines beginning with a `#' are
|
| -comments. Lines beginning with a `$' indicate conditional constructs
|
| -(*note Conditional Init Constructs::). Other lines denote variable
|
| -settings and key bindings.
|
| -
|
| -Variable Settings
|
| - You can modify the run-time behavior of Readline by altering the
|
| - values of variables in Readline using the `set' command within the
|
| - init file. The syntax is simple:
|
| -
|
| - set VARIABLE VALUE
|
| -
|
| - Here, for example, is how to change from the default Emacs-like
|
| - key binding to use `vi' line editing commands:
|
| -
|
| - set editing-mode vi
|
| -
|
| - Variable names and values, where appropriate, are recognized
|
| - without regard to case. Unrecognized variable names are ignored.
|
| -
|
| - Boolean variables (those that can be set to on or off) are set to
|
| - on if the value is null or empty, ON (case-insensitive), or 1.
|
| - Any other value results in the variable being set to off.
|
| -
|
| - A great deal of run-time behavior is changeable with the following
|
| - variables.
|
| -
|
| - `bell-style'
|
| - Controls what happens when Readline wants to ring the
|
| - terminal bell. If set to `none', Readline never rings the
|
| - bell. If set to `visible', Readline uses a visible bell if
|
| - one is available. If set to `audible' (the default),
|
| - Readline attempts to ring the terminal's bell.
|
| -
|
| - `bind-tty-special-chars'
|
| - If set to `on', Readline attempts to bind the control
|
| - characters treated specially by the kernel's terminal driver
|
| - to their Readline equivalents.
|
| -
|
| - `comment-begin'
|
| - The string to insert at the beginning of the line when the
|
| - `insert-comment' command is executed. The default value is
|
| - `"#"'.
|
| -
|
| - `completion-display-width'
|
| - The number of screen columns used to display possible matches
|
| - when performing completion. The value is ignored if it is
|
| - less than 0 or greater than the terminal screen width. A
|
| - value of 0 will cause matches to be displayed one per line.
|
| - The default value is -1.
|
| -
|
| - `completion-ignore-case'
|
| - If set to `on', Readline performs filename matching and
|
| - completion in a case-insensitive fashion. The default value
|
| - is `off'.
|
| -
|
| - `completion-map-case'
|
| - If set to `on', and COMPLETION-IGNORE-CASE is enabled,
|
| - Readline treats hyphens (`-') and underscores (`_') as
|
| - equivalent when performing case-insensitive filename matching
|
| - and completion.
|
| -
|
| - `completion-prefix-display-length'
|
| - The length in characters of the common prefix of a list of
|
| - possible completions that is displayed without modification.
|
| - When set to a value greater than zero, common prefixes longer
|
| - than this value are replaced with an ellipsis when displaying
|
| - possible completions.
|
| -
|
| - `completion-query-items'
|
| - The number of possible completions that determines when the
|
| - user is asked whether the list of possibilities should be
|
| - displayed. If the number of possible completions is greater
|
| - than this value, Readline will ask the user whether or not he
|
| - wishes to view them; otherwise, they are simply listed. This
|
| - variable must be set to an integer value greater than or
|
| - equal to 0. A negative value means Readline should never ask.
|
| - The default limit is `100'.
|
| -
|
| - `convert-meta'
|
| - If set to `on', Readline will convert characters with the
|
| - eighth bit set to an ASCII key sequence by stripping the
|
| - eighth bit and prefixing an <ESC> character, converting them
|
| - to a meta-prefixed key sequence. The default value is `on'.
|
| -
|
| - `disable-completion'
|
| - If set to `On', Readline will inhibit word completion.
|
| - Completion characters will be inserted into the line as if
|
| - they had been mapped to `self-insert'. The default is `off'.
|
| -
|
| - `editing-mode'
|
| - The `editing-mode' variable controls which default set of key
|
| - bindings is used. By default, Readline starts up in Emacs
|
| - editing mode, where the keystrokes are most similar to Emacs.
|
| - This variable can be set to either `emacs' or `vi'.
|
| -
|
| - `echo-control-characters'
|
| - When set to `on', on operating systems that indicate they
|
| - support it, readline echoes a character corresponding to a
|
| - signal generated from the keyboard. The default is `on'.
|
| -
|
| - `enable-keypad'
|
| - When set to `on', Readline will try to enable the application
|
| - keypad when it is called. Some systems need this to enable
|
| - the arrow keys. The default is `off'.
|
| -
|
| - `enable-meta-key'
|
| - When set to `on', Readline will try to enable any meta
|
| - modifier key the terminal claims to support when it is
|
| - called. On many terminals, the meta key is used to send
|
| - eight-bit characters. The default is `on'.
|
| -
|
| - `expand-tilde'
|
| - If set to `on', tilde expansion is performed when Readline
|
| - attempts word completion. The default is `off'.
|
| -
|
| - `history-preserve-point'
|
| - If set to `on', the history code attempts to place the point
|
| - (the current cursor position) at the same location on each
|
| - history line retrieved with `previous-history' or
|
| - `next-history'. The default is `off'.
|
| -
|
| - `history-size'
|
| - Set the maximum number of history entries saved in the
|
| - history list. If set to zero, the number of entries in the
|
| - history list is not limited.
|
| -
|
| - `horizontal-scroll-mode'
|
| - This variable can be set to either `on' or `off'. Setting it
|
| - to `on' means that the text of the lines being edited will
|
| - scroll horizontally on a single screen line when they are
|
| - longer than the width of the screen, instead of wrapping onto
|
| - a new screen line. By default, this variable is set to `off'.
|
| -
|
| - `input-meta'
|
| - If set to `on', Readline will enable eight-bit input (it will
|
| - not clear the eighth bit in the characters it reads),
|
| - regardless of what the terminal claims it can support. The
|
| - default value is `off'. The name `meta-flag' is a synonym
|
| - for this variable.
|
| -
|
| - `isearch-terminators'
|
| - The string of characters that should terminate an incremental
|
| - search without subsequently executing the character as a
|
| - command (*note Searching::). If this variable has not been
|
| - given a value, the characters <ESC> and `C-J' will terminate
|
| - an incremental search.
|
| -
|
| - `keymap'
|
| - Sets Readline's idea of the current keymap for key binding
|
| - commands. Acceptable `keymap' names are `emacs',
|
| - `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
|
| - `vi-command', and `vi-insert'. `vi' is equivalent to
|
| - `vi-command'; `emacs' is equivalent to `emacs-standard'. The
|
| - default value is `emacs'. The value of the `editing-mode'
|
| - variable also affects the default keymap.
|
| -
|
| - `mark-directories'
|
| - If set to `on', completed directory names have a slash
|
| - appended. The default is `on'.
|
| -
|
| - `mark-modified-lines'
|
| - This variable, when set to `on', causes Readline to display an
|
| - asterisk (`*') at the start of history lines which have been
|
| - modified. This variable is `off' by default.
|
| -
|
| - `mark-symlinked-directories'
|
| - If set to `on', completed names which are symbolic links to
|
| - directories have a slash appended (subject to the value of
|
| - `mark-directories'). The default is `off'.
|
| -
|
| - `match-hidden-files'
|
| - This variable, when set to `on', causes Readline to match
|
| - files whose names begin with a `.' (hidden files) when
|
| - performing filename completion. If set to `off', the leading
|
| - `.' must be supplied by the user in the filename to be
|
| - completed. This variable is `on' by default.
|
| -
|
| - `menu-complete-display-prefix'
|
| - If set to `on', menu completion displays the common prefix of
|
| - the list of possible completions (which may be empty) before
|
| - cycling through the list. The default is `off'.
|
| -
|
| - `output-meta'
|
| - If set to `on', Readline will display characters with the
|
| - eighth bit set directly rather than as a meta-prefixed escape
|
| - sequence. The default is `off'.
|
| -
|
| - `page-completions'
|
| - If set to `on', Readline uses an internal `more'-like pager
|
| - to display a screenful of possible completions at a time.
|
| - This variable is `on' by default.
|
| -
|
| - `print-completions-horizontally'
|
| - If set to `on', Readline will display completions with matches
|
| - sorted horizontally in alphabetical order, rather than down
|
| - the screen. The default is `off'.
|
| -
|
| - `revert-all-at-newline'
|
| - If set to `on', Readline will undo all changes to history
|
| - lines before returning when `accept-line' is executed. By
|
| - default, history lines may be modified and retain individual
|
| - undo lists across calls to `readline'. The default is `off'.
|
| -
|
| - `show-all-if-ambiguous'
|
| - This alters the default behavior of the completion functions.
|
| - If set to `on', words which have more than one possible
|
| - completion cause the matches to be listed immediately instead
|
| - of ringing the bell. The default value is `off'.
|
| -
|
| - `show-all-if-unmodified'
|
| - This alters the default behavior of the completion functions
|
| - in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
|
| - `on', words which have more than one possible completion
|
| - without any possible partial completion (the possible
|
| - completions don't share a common prefix) cause the matches to
|
| - be listed immediately instead of ringing the bell. The
|
| - default value is `off'.
|
| -
|
| - `skip-completed-text'
|
| - If set to `on', this alters the default completion behavior
|
| - when inserting a single match into the line. It's only
|
| - active when performing completion in the middle of a word.
|
| - If enabled, readline does not insert characters from the
|
| - completion that match characters after point in the word
|
| - being completed, so portions of the word following the cursor
|
| - are not duplicated. For instance, if this is enabled,
|
| - attempting completion when the cursor is after the `e' in
|
| - `Makefile' will result in `Makefile' rather than
|
| - `Makefilefile', assuming there is a single possible
|
| - completion. The default value is `off'.
|
| -
|
| - `visible-stats'
|
| - If set to `on', a character denoting a file's type is
|
| - appended to the filename when listing possible completions.
|
| - The default is `off'.
|
| -
|
| -
|
| -Key Bindings
|
| - The syntax for controlling key bindings in the init file is
|
| - simple. First you need to find the name of the command that you
|
| - want to change. The following sections contain tables of the
|
| - command name, the default keybinding, if any, and a short
|
| - description of what the command does.
|
| -
|
| - Once you know the name of the command, simply place on a line in
|
| - the init file the name of the key you wish to bind the command to,
|
| - a colon, and then the name of the command. There can be no space
|
| - between the key name and the colon - that will be interpreted as
|
| - part of the key name. The name of the key can be expressed in
|
| - different ways, depending on what you find most comfortable.
|
| -
|
| - In addition to command names, readline allows keys to be bound to
|
| - a string that is inserted when the key is pressed (a MACRO).
|
| -
|
| - KEYNAME: FUNCTION-NAME or MACRO
|
| - KEYNAME is the name of a key spelled out in English. For
|
| - example:
|
| - Control-u: universal-argument
|
| - Meta-Rubout: backward-kill-word
|
| - Control-o: "> output"
|
| -
|
| - In the above example, `C-u' is bound to the function
|
| - `universal-argument', `M-DEL' is bound to the function
|
| - `backward-kill-word', and `C-o' is bound to run the macro
|
| - expressed on the right hand side (that is, to insert the text
|
| - `> output' into the line).
|
| -
|
| - A number of symbolic character names are recognized while
|
| - processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
|
| - NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
|
| -
|
| - "KEYSEQ": FUNCTION-NAME or MACRO
|
| - KEYSEQ differs from KEYNAME above in that strings denoting an
|
| - entire key sequence can be specified, by placing the key
|
| - sequence in double quotes. Some GNU Emacs style key escapes
|
| - can be used, as in the following example, but the special
|
| - character names are not recognized.
|
| -
|
| - "\C-u": universal-argument
|
| - "\C-x\C-r": re-read-init-file
|
| - "\e[11~": "Function Key 1"
|
| -
|
| - In the above example, `C-u' is again bound to the function
|
| - `universal-argument' (just as it was in the first example),
|
| - `C-x C-r' is bound to the function `re-read-init-file', and
|
| - `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function
|
| - Key 1'.
|
| -
|
| -
|
| - The following GNU Emacs style escape sequences are available when
|
| - specifying key sequences:
|
| -
|
| - `\C-'
|
| - control prefix
|
| -
|
| - `\M-'
|
| - meta prefix
|
| -
|
| - `\e'
|
| - an escape character
|
| -
|
| - `\\'
|
| - backslash
|
| -
|
| - `\"'
|
| - <">, a double quotation mark
|
| -
|
| - `\''
|
| - <'>, a single quote or apostrophe
|
| -
|
| - In addition to the GNU Emacs style escape sequences, a second set
|
| - of backslash escapes is available:
|
| -
|
| - `\a'
|
| - alert (bell)
|
| -
|
| - `\b'
|
| - backspace
|
| -
|
| - `\d'
|
| - delete
|
| -
|
| - `\f'
|
| - form feed
|
| -
|
| - `\n'
|
| - newline
|
| -
|
| - `\r'
|
| - carriage return
|
| -
|
| - `\t'
|
| - horizontal tab
|
| -
|
| - `\v'
|
| - vertical tab
|
| -
|
| - `\NNN'
|
| - the eight-bit character whose value is the octal value NNN
|
| - (one to three digits)
|
| -
|
| - `\xHH'
|
| - the eight-bit character whose value is the hexadecimal value
|
| - HH (one or two hex digits)
|
| -
|
| - When entering the text of a macro, single or double quotes must be
|
| - used to indicate a macro definition. Unquoted text is assumed to
|
| - be a function name. In the macro body, the backslash escapes
|
| - described above are expanded. Backslash will quote any other
|
| - character in the macro text, including `"' and `''. For example,
|
| - the following binding will make `C-x \' insert a single `\' into
|
| - the line:
|
| - "\C-x\\": "\\"
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
|
| -
|
| -32.3.2 Conditional Init Constructs
|
| -----------------------------------
|
| -
|
| -Readline implements a facility similar in spirit to the conditional
|
| -compilation features of the C preprocessor which allows key bindings
|
| -and variable settings to be performed as the result of tests. There
|
| -are four parser directives used.
|
| -
|
| -`$if'
|
| - The `$if' construct allows bindings to be made based on the
|
| - editing mode, the terminal being used, or the application using
|
| - Readline. The text of the test extends to the end of the line; no
|
| - characters are required to isolate it.
|
| -
|
| - `mode'
|
| - The `mode=' form of the `$if' directive is used to test
|
| - whether Readline is in `emacs' or `vi' mode. This may be
|
| - used in conjunction with the `set keymap' command, for
|
| - instance, to set bindings in the `emacs-standard' and
|
| - `emacs-ctlx' keymaps only if Readline is starting out in
|
| - `emacs' mode.
|
| -
|
| - `term'
|
| - The `term=' form may be used to include terminal-specific key
|
| - bindings, perhaps to bind the key sequences output by the
|
| - terminal's function keys. The word on the right side of the
|
| - `=' is tested against both the full name of the terminal and
|
| - the portion of the terminal name before the first `-'. This
|
| - allows `sun' to match both `sun' and `sun-cmd', for instance.
|
| -
|
| - `application'
|
| - The APPLICATION construct is used to include
|
| - application-specific settings. Each program using the
|
| - Readline library sets the APPLICATION NAME, and you can test
|
| - for a particular value. This could be used to bind key
|
| - sequences to functions useful for a specific program. For
|
| - instance, the following command adds a key sequence that
|
| - quotes the current or previous word in Bash:
|
| - $if Bash
|
| - # Quote the current or previous word
|
| - "\C-xq": "\eb\"\ef\""
|
| - $endif
|
| -
|
| -`$endif'
|
| - This command, as seen in the previous example, terminates an `$if'
|
| - command.
|
| -
|
| -`$else'
|
| - Commands in this branch of the `$if' directive are executed if the
|
| - test fails.
|
| -
|
| -`$include'
|
| - This directive takes a single filename as an argument and reads
|
| - commands and bindings from that file. For example, the following
|
| - directive reads from `/etc/inputrc':
|
| - $include /etc/inputrc
|
| -
|
| -
|
| -File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
|
| -
|
| -32.3.3 Sample Init File
|
| ------------------------
|
| -
|
| -Here is an example of an INPUTRC file. This illustrates key binding,
|
| -variable assignment, and conditional syntax.
|
| -
|
| -
|
| - # This file controls the behaviour of line input editing for
|
| - # programs that use the GNU Readline library. Existing
|
| - # programs include FTP, Bash, and GDB.
|
| - #
|
| - # You can re-read the inputrc file with C-x C-r.
|
| - # Lines beginning with '#' are comments.
|
| - #
|
| - # First, include any systemwide bindings and variable
|
| - # assignments from /etc/Inputrc
|
| - $include /etc/Inputrc
|
| -
|
| - #
|
| - # Set various bindings for emacs mode.
|
| -
|
| - set editing-mode emacs
|
| -
|
| - $if mode=emacs
|
| -
|
| - Meta-Control-h: backward-kill-word Text after the function name is ignored
|
| -
|
| - #
|
| - # Arrow keys in keypad mode
|
| - #
|
| - #"\M-OD": backward-char
|
| - #"\M-OC": forward-char
|
| - #"\M-OA": previous-history
|
| - #"\M-OB": next-history
|
| - #
|
| - # Arrow keys in ANSI mode
|
| - #
|
| - "\M-[D": backward-char
|
| - "\M-[C": forward-char
|
| - "\M-[A": previous-history
|
| - "\M-[B": next-history
|
| - #
|
| - # Arrow keys in 8 bit keypad mode
|
| - #
|
| - #"\M-\C-OD": backward-char
|
| - #"\M-\C-OC": forward-char
|
| - #"\M-\C-OA": previous-history
|
| - #"\M-\C-OB": next-history
|
| - #
|
| - # Arrow keys in 8 bit ANSI mode
|
| - #
|
| - #"\M-\C-[D": backward-char
|
| - #"\M-\C-[C": forward-char
|
| - #"\M-\C-[A": previous-history
|
| - #"\M-\C-[B": next-history
|
| -
|
| - C-q: quoted-insert
|
| -
|
| - $endif
|
| -
|
| - # An old-style binding. This happens to be the default.
|
| - TAB: complete
|
| -
|
| - # Macros that are convenient for shell interaction
|
| - $if Bash
|
| - # edit the path
|
| - "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
|
| - # prepare to type a quoted word --
|
| - # insert open and close double quotes
|
| - # and move to just after the open quote
|
| - "\C-x\"": "\"\"\C-b"
|
| - # insert a backslash (testing backslash escapes
|
| - # in sequences and macros)
|
| - "\C-x\\": "\\"
|
| - # Quote the current or previous word
|
| - "\C-xq": "\eb\"\ef\""
|
| - # Add a binding to refresh the line, which is unbound
|
| - "\C-xr": redraw-current-line
|
| - # Edit variable on current line.
|
| - "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
|
| - $endif
|
| -
|
| - # use a visible bell if one is available
|
| - set bell-style visible
|
| -
|
| - # don't strip characters to 7 bits when reading
|
| - set input-meta on
|
| -
|
| - # allow iso-latin1 characters to be inserted rather
|
| - # than converted to prefix-meta sequences
|
| - set convert-meta off
|
| -
|
| - # display characters with the eighth bit set directly
|
| - # rather than as meta-prefixed characters
|
| - set output-meta on
|
| -
|
| - # if there are more than 150 possible completions for
|
| - # a word, ask the user if he wants to see all of them
|
| - set completion-query-items 150
|
| -
|
| - # For FTP
|
| - $if Ftp
|
| - "\C-xg": "get \M-?"
|
| - "\C-xt": "put \M-?"
|
| - "\M-.": yank-last-arg
|
| - $endif
|
| -
|
| -
|
| -File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
|
| -
|
| -32.4 Bindable Readline Commands
|
| -===============================
|
| -
|
| -* Menu:
|
| -
|
| -* Commands For Moving:: Moving about the line.
|
| -* Commands For History:: Getting at previous lines.
|
| -* Commands For Text:: Commands for changing text.
|
| -* Commands For Killing:: Commands for killing and yanking.
|
| -* Numeric Arguments:: Specifying numeric arguments, repeat counts.
|
| -* Commands For Completion:: Getting Readline to do the typing for you.
|
| -* Keyboard Macros:: Saving and re-executing typed characters
|
| -* Miscellaneous Commands:: Other miscellaneous commands.
|
| -
|
| - This section describes Readline commands that may be bound to key
|
| -sequences. Command names without an accompanying key sequence are
|
| -unbound by default.
|
| -
|
| - In the following descriptions, "point" refers to the current cursor
|
| -position, and "mark" refers to a cursor position saved by the
|
| -`set-mark' command. The text between the point and mark is referred to
|
| -as the "region".
|
| -
|
| -
|
| -File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
|
| -
|
| -32.4.1 Commands For Moving
|
| ---------------------------
|
| -
|
| -`beginning-of-line (C-a)'
|
| - Move to the start of the current line.
|
| -
|
| -`end-of-line (C-e)'
|
| - Move to the end of the line.
|
| -
|
| -`forward-char (C-f)'
|
| - Move forward a character.
|
| -
|
| -`backward-char (C-b)'
|
| - Move back a character.
|
| -
|
| -`forward-word (M-f)'
|
| - Move forward to the end of the next word. Words are composed of
|
| - letters and digits.
|
| -
|
| -`backward-word (M-b)'
|
| - Move back to the start of the current or previous word. Words are
|
| - composed of letters and digits.
|
| -
|
| -`clear-screen (C-l)'
|
| - Clear the screen and redraw the current line, leaving the current
|
| - line at the top of the screen.
|
| -
|
| -`redraw-current-line ()'
|
| - Refresh the current line. By default, this is unbound.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
|
| -
|
| -32.4.2 Commands For Manipulating The History
|
| ---------------------------------------------
|
| -
|
| -`accept-line (Newline or Return)'
|
| - Accept the line regardless of where the cursor is. If this line is
|
| - non-empty, it may be added to the history list for future recall
|
| - with `add_history()'. If this line is a modified history line,
|
| - the history line is restored to its original state.
|
| -
|
| -`previous-history (C-p)'
|
| - Move `back' through the history list, fetching the previous
|
| - command.
|
| -
|
| -`next-history (C-n)'
|
| - Move `forward' through the history list, fetching the next command.
|
| -
|
| -`beginning-of-history (M-<)'
|
| - Move to the first line in the history.
|
| -
|
| -`end-of-history (M->)'
|
| - Move to the end of the input history, i.e., the line currently
|
| - being entered.
|
| -
|
| -`reverse-search-history (C-r)'
|
| - Search backward starting at the current line and moving `up'
|
| - through the history as necessary. This is an incremental search.
|
| -
|
| -`forward-search-history (C-s)'
|
| - Search forward starting at the current line and moving `down'
|
| - through the the history as necessary. This is an incremental
|
| - search.
|
| -
|
| -`non-incremental-reverse-search-history (M-p)'
|
| - Search backward starting at the current line and moving `up'
|
| - through the history as necessary using a non-incremental search
|
| - for a string supplied by the user.
|
| -
|
| -`non-incremental-forward-search-history (M-n)'
|
| - Search forward starting at the current line and moving `down'
|
| - through the the history as necessary using a non-incremental search
|
| - for a string supplied by the user.
|
| -
|
| -`history-search-forward ()'
|
| - Search forward through the history for the string of characters
|
| - between the start of the current line and the point. This is a
|
| - non-incremental search. By default, this command is unbound.
|
| -
|
| -`history-search-backward ()'
|
| - Search backward through the history for the string of characters
|
| - between the start of the current line and the point. This is a
|
| - non-incremental search. By default, this command is unbound.
|
| -
|
| -`yank-nth-arg (M-C-y)'
|
| - Insert the first argument to the previous command (usually the
|
| - second word on the previous line) at point. With an argument N,
|
| - insert the Nth word from the previous command (the words in the
|
| - previous command begin with word 0). A negative argument inserts
|
| - the Nth word from the end of the previous command. Once the
|
| - argument N is computed, the argument is extracted as if the `!N'
|
| - history expansion had been specified.
|
| -
|
| -`yank-last-arg (M-. or M-_)'
|
| - Insert last argument to the previous command (the last word of the
|
| - previous history entry). With a numeric argument, behave exactly
|
| - like `yank-nth-arg'. Successive calls to `yank-last-arg' move
|
| - back through the history list, inserting the last word (or the
|
| - word specified by the argument to the first call) of each line in
|
| - turn. Any numeric argument supplied to these successive calls
|
| - determines the direction to move through the history. A negative
|
| - argument switches the direction through the history (back or
|
| - forward). The history expansion facilities are used to extract
|
| - the last argument, as if the `!$' history expansion had been
|
| - specified.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
|
| -
|
| -32.4.3 Commands For Changing Text
|
| ----------------------------------
|
| -
|
| -`delete-char (C-d)'
|
| - Delete the character at point. If point is at the beginning of
|
| - the line, there are no characters in the line, and the last
|
| - character typed was not bound to `delete-char', then return EOF.
|
| -
|
| -`backward-delete-char (Rubout)'
|
| - Delete the character behind the cursor. A numeric argument means
|
| - to kill the characters instead of deleting them.
|
| -
|
| -`forward-backward-delete-char ()'
|
| - Delete the character under the cursor, unless the cursor is at the
|
| - end of the line, in which case the character behind the cursor is
|
| - deleted. By default, this is not bound to a key.
|
| -
|
| -`quoted-insert (C-q or C-v)'
|
| - Add the next character typed to the line verbatim. This is how to
|
| - insert key sequences like `C-q', for example.
|
| -
|
| -`tab-insert (M-<TAB>)'
|
| - Insert a tab character.
|
| -
|
| -`self-insert (a, b, A, 1, !, ...)'
|
| - Insert yourself.
|
| -
|
| -`transpose-chars (C-t)'
|
| - Drag the character before the cursor forward over the character at
|
| - the cursor, moving the cursor forward as well. If the insertion
|
| - point is at the end of the line, then this transposes the last two
|
| - characters of the line. Negative arguments have no effect.
|
| -
|
| -`transpose-words (M-t)'
|
| - Drag the word before point past the word after point, moving point
|
| - past that word as well. If the insertion point is at the end of
|
| - the line, this transposes the last two words on the line.
|
| -
|
| -`upcase-word (M-u)'
|
| - Uppercase the current (or following) word. With a negative
|
| - argument, uppercase the previous word, but do not move the cursor.
|
| -
|
| -`downcase-word (M-l)'
|
| - Lowercase the current (or following) word. With a negative
|
| - argument, lowercase the previous word, but do not move the cursor.
|
| -
|
| -`capitalize-word (M-c)'
|
| - Capitalize the current (or following) word. With a negative
|
| - argument, capitalize the previous word, but do not move the cursor.
|
| -
|
| -`overwrite-mode ()'
|
| - Toggle overwrite mode. With an explicit positive numeric argument,
|
| - switches to overwrite mode. With an explicit non-positive numeric
|
| - argument, switches to insert mode. This command affects only
|
| - `emacs' mode; `vi' mode does overwrite differently. Each call to
|
| - `readline()' starts in insert mode.
|
| -
|
| - In overwrite mode, characters bound to `self-insert' replace the
|
| - text at point rather than pushing the text to the right.
|
| - Characters bound to `backward-delete-char' replace the character
|
| - before point with a space.
|
| -
|
| - By default, this command is unbound.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
|
| -
|
| -32.4.4 Killing And Yanking
|
| ---------------------------
|
| -
|
| -`kill-line (C-k)'
|
| - Kill the text from point to the end of the line.
|
| -
|
| -`backward-kill-line (C-x Rubout)'
|
| - Kill backward to the beginning of the line.
|
| -
|
| -`unix-line-discard (C-u)'
|
| - Kill backward from the cursor to the beginning of the current line.
|
| -
|
| -`kill-whole-line ()'
|
| - Kill all characters on the current line, no matter where point is.
|
| - By default, this is unbound.
|
| -
|
| -`kill-word (M-d)'
|
| - Kill from point to the end of the current word, or if between
|
| - words, to the end of the next word. Word boundaries are the same
|
| - as `forward-word'.
|
| -
|
| -`backward-kill-word (M-<DEL>)'
|
| - Kill the word behind point. Word boundaries are the same as
|
| - `backward-word'.
|
| -
|
| -`unix-word-rubout (C-w)'
|
| - Kill the word behind point, using white space as a word boundary.
|
| - The killed text is saved on the kill-ring.
|
| -
|
| -`unix-filename-rubout ()'
|
| - Kill the word behind point, using white space and the slash
|
| - character as the word boundaries. The killed text is saved on the
|
| - kill-ring.
|
| -
|
| -`delete-horizontal-space ()'
|
| - Delete all spaces and tabs around point. By default, this is
|
| - unbound.
|
| -
|
| -`kill-region ()'
|
| - Kill the text in the current region. By default, this command is
|
| - unbound.
|
| -
|
| -`copy-region-as-kill ()'
|
| - Copy the text in the region to the kill buffer, so it can be yanked
|
| - right away. By default, this command is unbound.
|
| -
|
| -`copy-backward-word ()'
|
| - Copy the word before point to the kill buffer. The word
|
| - boundaries are the same as `backward-word'. By default, this
|
| - command is unbound.
|
| -
|
| -`copy-forward-word ()'
|
| - Copy the word following point to the kill buffer. The word
|
| - boundaries are the same as `forward-word'. By default, this
|
| - command is unbound.
|
| -
|
| -`yank (C-y)'
|
| - Yank the top of the kill ring into the buffer at point.
|
| -
|
| -`yank-pop (M-y)'
|
| - Rotate the kill-ring, and yank the new top. You can only do this
|
| - if the prior command is `yank' or `yank-pop'.
|
| -
|
| -
|
| -File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
|
| -
|
| -32.4.5 Specifying Numeric Arguments
|
| ------------------------------------
|
| -
|
| -`digit-argument (M-0, M-1, ... M--)'
|
| - Add this digit to the argument already accumulating, or start a new
|
| - argument. `M--' starts a negative argument.
|
| -
|
| -`universal-argument ()'
|
| - This is another way to specify an argument. If this command is
|
| - followed by one or more digits, optionally with a leading minus
|
| - sign, those digits define the argument. If the command is
|
| - followed by digits, executing `universal-argument' again ends the
|
| - numeric argument, but is otherwise ignored. As a special case, if
|
| - this command is immediately followed by a character that is
|
| - neither a digit or minus sign, the argument count for the next
|
| - command is multiplied by four. The argument count is initially
|
| - one, so executing this function the first time makes the argument
|
| - count four, a second time makes the argument count sixteen, and so
|
| - on. By default, this is not bound to a key.
|
| -
|
| -
|
| -File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
|
| -
|
| -32.4.6 Letting Readline Type For You
|
| -------------------------------------
|
| -
|
| -`complete (<TAB>)'
|
| - Attempt to perform completion on the text before point. The
|
| - actual completion performed is application-specific. The default
|
| - is filename completion.
|
| -
|
| -`possible-completions (M-?)'
|
| - List the possible completions of the text before point. When
|
| - displaying completions, Readline sets the number of columns used
|
| - for display to the value of `completion-display-width', the value
|
| - of the environment variable `COLUMNS', or the screen width, in
|
| - that order.
|
| -
|
| -`insert-completions (M-*)'
|
| - Insert all completions of the text before point that would have
|
| - been generated by `possible-completions'.
|
| -
|
| -`menu-complete ()'
|
| - Similar to `complete', but replaces the word to be completed with
|
| - a single match from the list of possible completions. Repeated
|
| - execution of `menu-complete' steps through the list of possible
|
| - completions, inserting each match in turn. At the end of the list
|
| - of completions, the bell is rung (subject to the setting of
|
| - `bell-style') and the original text is restored. An argument of N
|
| - moves N positions forward in the list of matches; a negative
|
| - argument may be used to move backward through the list. This
|
| - command is intended to be bound to <TAB>, but is unbound by
|
| - default.
|
| -
|
| -`menu-complete-backward ()'
|
| - Identical to `menu-complete', but moves backward through the list
|
| - of possible completions, as if `menu-complete' had been given a
|
| - negative argument.
|
| -
|
| -`delete-char-or-list ()'
|
| - Deletes the character under the cursor if not at the beginning or
|
| - end of the line (like `delete-char'). If at the end of the line,
|
| - behaves identically to `possible-completions'. This command is
|
| - unbound by default.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
|
| -
|
| -32.4.7 Keyboard Macros
|
| -----------------------
|
| -
|
| -`start-kbd-macro (C-x ()'
|
| - Begin saving the characters typed into the current keyboard macro.
|
| -
|
| -`end-kbd-macro (C-x ))'
|
| - Stop saving the characters typed into the current keyboard macro
|
| - and save the definition.
|
| -
|
| -`call-last-kbd-macro (C-x e)'
|
| - Re-execute the last keyboard macro defined, by making the
|
| - characters in the macro appear as if typed at the keyboard.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
|
| -
|
| -32.4.8 Some Miscellaneous Commands
|
| -----------------------------------
|
| -
|
| -`re-read-init-file (C-x C-r)'
|
| - Read in the contents of the INPUTRC file, and incorporate any
|
| - bindings or variable assignments found there.
|
| -
|
| -`abort (C-g)'
|
| - Abort the current editing command and ring the terminal's bell
|
| - (subject to the setting of `bell-style').
|
| -
|
| -`do-uppercase-version (M-a, M-b, M-X, ...)'
|
| - If the metafied character X is lowercase, run the command that is
|
| - bound to the corresponding uppercase character.
|
| -
|
| -`prefix-meta (<ESC>)'
|
| - Metafy the next character typed. This is for keyboards without a
|
| - meta key. Typing `<ESC> f' is equivalent to typing `M-f'.
|
| -
|
| -`undo (C-_ or C-x C-u)'
|
| - Incremental undo, separately remembered for each line.
|
| -
|
| -`revert-line (M-r)'
|
| - Undo all changes made to this line. This is like executing the
|
| - `undo' command enough times to get back to the beginning.
|
| -
|
| -`tilde-expand (M-~)'
|
| - Perform tilde expansion on the current word.
|
| -
|
| -`set-mark (C-@)'
|
| - Set the mark to the point. If a numeric argument is supplied, the
|
| - mark is set to that position.
|
| -
|
| -`exchange-point-and-mark (C-x C-x)'
|
| - Swap the point with the mark. The current cursor position is set
|
| - to the saved position, and the old cursor position is saved as the
|
| - mark.
|
| -
|
| -`character-search (C-])'
|
| - A character is read and point is moved to the next occurrence of
|
| - that character. A negative count searches for previous
|
| - occurrences.
|
| -
|
| -`character-search-backward (M-C-])'
|
| - A character is read and point is moved to the previous occurrence
|
| - of that character. A negative count searches for subsequent
|
| - occurrences.
|
| -
|
| -`skip-csi-sequence ()'
|
| - Read enough characters to consume a multi-key sequence such as
|
| - those defined for keys like Home and End. Such sequences begin
|
| - with a Control Sequence Indicator (CSI), usually ESC-[. If this
|
| - sequence is bound to "\e[", keys producing such sequences will
|
| - have no effect unless explicitly bound to a readline command,
|
| - instead of inserting stray characters into the editing buffer.
|
| - This is unbound by default, but usually bound to ESC-[.
|
| -
|
| -`insert-comment (M-#)'
|
| - Without a numeric argument, the value of the `comment-begin'
|
| - variable is inserted at the beginning of the current line. If a
|
| - numeric argument is supplied, this command acts as a toggle: if
|
| - the characters at the beginning of the line do not match the value
|
| - of `comment-begin', the value is inserted, otherwise the
|
| - characters in `comment-begin' are deleted from the beginning of
|
| - the line. In either case, the line is accepted as if a newline
|
| - had been typed.
|
| -
|
| -`dump-functions ()'
|
| - Print all of the functions and their key bindings to the Readline
|
| - output stream. If a numeric argument is supplied, the output is
|
| - formatted in such a way that it can be made part of an INPUTRC
|
| - file. This command is unbound by default.
|
| -
|
| -`dump-variables ()'
|
| - Print all of the settable variables and their values to the
|
| - Readline output stream. If a numeric argument is supplied, the
|
| - output is formatted in such a way that it can be made part of an
|
| - INPUTRC file. This command is unbound by default.
|
| -
|
| -`dump-macros ()'
|
| - Print all of the Readline key sequences bound to macros and the
|
| - strings they output. If a numeric argument is supplied, the
|
| - output is formatted in such a way that it can be made part of an
|
| - INPUTRC file. This command is unbound by default.
|
| -
|
| -`emacs-editing-mode (C-e)'
|
| - When in `vi' command mode, this causes a switch to `emacs' editing
|
| - mode.
|
| -
|
| -`vi-editing-mode (M-C-j)'
|
| - When in `emacs' editing mode, this causes a switch to `vi' editing
|
| - mode.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
|
| -
|
| -32.5 Readline vi Mode
|
| -=====================
|
| -
|
| -While the Readline library does not have a full set of `vi' editing
|
| -functions, it does contain enough to allow simple editing of the line.
|
| -The Readline `vi' mode behaves as specified in the POSIX standard.
|
| -
|
| - In order to switch interactively between `emacs' and `vi' editing
|
| -modes, use the command `M-C-j' (bound to emacs-editing-mode when in
|
| -`vi' mode and to vi-editing-mode in `emacs' mode). The Readline
|
| -default is `emacs' mode.
|
| -
|
| - When you enter a line in `vi' mode, you are already placed in
|
| -`insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
|
| -you into `command' mode, where you can edit the text of the line with
|
| -the standard `vi' movement keys, move to previous history lines with
|
| -`k' and subsequent lines with `j', and so forth.
|
| -
|
| -
|
| -File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top
|
| -
|
| -33 Using History Interactively
|
| -******************************
|
| -
|
| -This chapter describes how to use the GNU History Library interactively,
|
| -from a user's standpoint. It should be considered a user's guide. For
|
| -information on using the GNU History Library in your own programs,
|
| -*note Programming with GNU History: (history)Programming with GNU
|
| -History.
|
| -
|
| -* Menu:
|
| -
|
| -* History Interaction:: What it feels like using History as a user.
|
| -
|
| -
|
| -File: gdb.info, Node: History Interaction, Up: Using History Interactively
|
| -
|
| -33.1 History Expansion
|
| -======================
|
| -
|
| -The History library provides a history expansion feature that is similar
|
| -to the history expansion provided by `csh'. This section describes the
|
| -syntax used to manipulate the history information.
|
| -
|
| - History expansions introduce words from the history list into the
|
| -input stream, making it easy to repeat commands, insert the arguments
|
| -to a previous command into the current input line, or fix errors in
|
| -previous commands quickly.
|
| -
|
| - History expansion takes place in two parts. The first is to
|
| -determine which line from the history list should be used during
|
| -substitution. The second is to select portions of that line for
|
| -inclusion into the current one. The line selected from the history is
|
| -called the "event", and the portions of that line that are acted upon
|
| -are called "words". Various "modifiers" are available to manipulate
|
| -the selected words. The line is broken into words in the same fashion
|
| -that Bash does, so that several words surrounded by quotes are
|
| -considered one word. History expansions are introduced by the
|
| -appearance of the history expansion character, which is `!' by default.
|
| -
|
| -* Menu:
|
| -
|
| -* Event Designators:: How to specify which history line to use.
|
| -* Word Designators:: Specifying which words are of interest.
|
| -* Modifiers:: Modifying the results of substitution.
|
| -
|
| -
|
| -File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
|
| -
|
| -33.1.1 Event Designators
|
| -------------------------
|
| -
|
| -An event designator is a reference to a command line entry in the
|
| -history list. Unless the reference is absolute, events are relative to
|
| -the current position in the history list.
|
| -
|
| -`!'
|
| - Start a history substitution, except when followed by a space, tab,
|
| - the end of the line, or `='.
|
| -
|
| -`!N'
|
| - Refer to command line N.
|
| -
|
| -`!-N'
|
| - Refer to the command N lines back.
|
| -
|
| -`!!'
|
| - Refer to the previous command. This is a synonym for `!-1'.
|
| -
|
| -`!STRING'
|
| - Refer to the most recent command preceding the current position in
|
| - the history list starting with STRING.
|
| -
|
| -`!?STRING[?]'
|
| - Refer to the most recent command preceding the current position in
|
| - the history list containing STRING. The trailing `?' may be
|
| - omitted if the STRING is followed immediately by a newline.
|
| -
|
| -`^STRING1^STRING2^'
|
| - Quick Substitution. Repeat the last command, replacing STRING1
|
| - with STRING2. Equivalent to `!!:s/STRING1/STRING2/'.
|
| -
|
| -`!#'
|
| - The entire command line typed so far.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
|
| -
|
| -33.1.2 Word Designators
|
| ------------------------
|
| -
|
| -Word designators are used to select desired words from the event. A
|
| -`:' separates the event specification from the word designator. It may
|
| -be omitted if the word designator begins with a `^', `$', `*', `-', or
|
| -`%'. Words are numbered from the beginning of the line, with the first
|
| -word being denoted by 0 (zero). Words are inserted into the current
|
| -line separated by single spaces.
|
| -
|
| - For example,
|
| -
|
| -`!!'
|
| - designates the preceding command. When you type this, the
|
| - preceding command is repeated in toto.
|
| -
|
| -`!!:$'
|
| - designates the last argument of the preceding command. This may be
|
| - shortened to `!$'.
|
| -
|
| -`!fi:2'
|
| - designates the second argument of the most recent command starting
|
| - with the letters `fi'.
|
| -
|
| - Here are the word designators:
|
| -
|
| -`0 (zero)'
|
| - The `0'th word. For many applications, this is the command word.
|
| -
|
| -`N'
|
| - The Nth word.
|
| -
|
| -`^'
|
| - The first argument; that is, word 1.
|
| -
|
| -`$'
|
| - The last argument.
|
| -
|
| -`%'
|
| - The word matched by the most recent `?STRING?' search.
|
| -
|
| -`X-Y'
|
| - A range of words; `-Y' abbreviates `0-Y'.
|
| -
|
| -`*'
|
| - All of the words, except the `0'th. This is a synonym for `1-$'.
|
| - It is not an error to use `*' if there is just one word in the
|
| - event; the empty string is returned in that case.
|
| -
|
| -`X*'
|
| - Abbreviates `X-$'
|
| -
|
| -`X-'
|
| - Abbreviates `X-$' like `X*', but omits the last word.
|
| -
|
| -
|
| - If a word designator is supplied without an event specification, the
|
| -previous command is used as the event.
|
| -
|
| -
|
| -File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
|
| -
|
| -33.1.3 Modifiers
|
| -----------------
|
| -
|
| -After the optional word designator, you can add a sequence of one or
|
| -more of the following modifiers, each preceded by a `:'.
|
| -
|
| -`h'
|
| - Remove a trailing pathname component, leaving only the head.
|
| -
|
| -`t'
|
| - Remove all leading pathname components, leaving the tail.
|
| -
|
| -`r'
|
| - Remove a trailing suffix of the form `.SUFFIX', leaving the
|
| - basename.
|
| -
|
| -`e'
|
| - Remove all but the trailing suffix.
|
| -
|
| -`p'
|
| - Print the new command but do not execute it.
|
| -
|
| -`s/OLD/NEW/'
|
| - Substitute NEW for the first occurrence of OLD in the event line.
|
| - Any delimiter may be used in place of `/'. The delimiter may be
|
| - quoted in OLD and NEW with a single backslash. If `&' appears in
|
| - NEW, it is replaced by OLD. A single backslash will quote the
|
| - `&'. The final delimiter is optional if it is the last character
|
| - on the input line.
|
| -
|
| -`&'
|
| - Repeat the previous substitution.
|
| -
|
| -`g'
|
| -`a'
|
| - Cause changes to be applied over the entire event line. Used in
|
| - conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
|
| -
|
| -`G'
|
| - Apply the following `s' modifier once to each word in the event.
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top
|
| -
|
| -Appendix A In Memoriam
|
| -**********************
|
| -
|
| -The GDB project mourns the loss of the following long-time contributors:
|
| -
|
| -`Fred Fish'
|
| - Fred was a long-standing contributor to GDB (1991-2006), and to
|
| - Free Software in general. Outside of GDB, he was known in the
|
| - Amiga world for his series of Fish Disks, and the GeekGadget
|
| - project.
|
| -
|
| -`Michael Snyder'
|
| - Michael was one of the Global Maintainers of the GDB project, with
|
| - contributions recorded as early as 1996, until 2011. In addition
|
| - to his day to day participation, he was a large driving force
|
| - behind adding Reverse Debugging to GDB.
|
| -
|
| - Beyond their technical contributions to the project, they were also
|
| -enjoyable members of the Free Software Community. We will miss them.
|
| -
|
| -
|
| -File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top
|
| -
|
| -Appendix B Formatting Documentation
|
| -***********************************
|
| -
|
| -The GDB 4 release includes an already-formatted reference card, ready
|
| -for printing with PostScript or Ghostscript, in the `gdb' subdirectory
|
| -of the main source directory(1). If you can use PostScript or
|
| -Ghostscript with your printer, you can print the reference card
|
| -immediately with `refcard.ps'.
|
| -
|
| - The release also includes the source for the reference card. You
|
| -can format it, using TeX, by typing:
|
| -
|
| - make refcard.dvi
|
| -
|
| - The GDB reference card is designed to print in "landscape" mode on
|
| -US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
|
| -high. You will need to specify this form of printing as an option to
|
| -your DVI output program.
|
| -
|
| - All the documentation for GDB comes as part of the machine-readable
|
| -distribution. The documentation is written in Texinfo format, which is
|
| -a documentation system that uses a single source file to produce both
|
| -on-line information and a printed manual. You can use one of the Info
|
| -formatting commands to create the on-line version of the documentation
|
| -and TeX (or `texi2roff') to typeset the printed version.
|
| -
|
| - GDB includes an already formatted copy of the on-line Info version
|
| -of this manual in the `gdb' subdirectory. The main Info file is
|
| -`gdb-7.5.1/gdb/gdb.info', and it refers to subordinate files matching
|
| -`gdb.info*' in the same directory. If necessary, you can print out
|
| -these files, or read them with any editor; but they are easier to read
|
| -using the `info' subsystem in GNU Emacs or the standalone `info'
|
| -program, available as part of the GNU Texinfo distribution.
|
| -
|
| - If you want to format these Info files yourself, you need one of the
|
| -Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
|
| -
|
| - If you have `makeinfo' installed, and are in the top level GDB
|
| -source directory (`gdb-7.5.1', in the case of version 7.5.1), you can
|
| -make the Info file by typing:
|
| -
|
| - cd gdb
|
| - make gdb.info
|
| -
|
| - If you want to typeset and print copies of this manual, you need TeX,
|
| -a program to print its DVI output files, and `texinfo.tex', the Texinfo
|
| -definitions file.
|
| -
|
| - TeX is a typesetting program; it does not print files directly, but
|
| -produces output files called DVI files. To print a typeset document,
|
| -you need a program to print DVI files. If your system has TeX
|
| -installed, chances are it has such a program. The precise command to
|
| -use depends on your system; `lpr -d' is common; another (for PostScript
|
| -devices) is `dvips'. The DVI print command may require a file name
|
| -without any extension or a `.dvi' extension.
|
| -
|
| - TeX also requires a macro definitions file called `texinfo.tex'.
|
| -This file tells TeX how to typeset a document written in Texinfo
|
| -format. On its own, TeX cannot either read or typeset a Texinfo file.
|
| -`texinfo.tex' is distributed with GDB and is located in the
|
| -`gdb-VERSION-NUMBER/texinfo' directory.
|
| -
|
| - If you have TeX and a DVI printer program installed, you can typeset
|
| -and print this manual. First switch to the `gdb' subdirectory of the
|
| -main source directory (for example, to `gdb-7.5.1/gdb') and type:
|
| -
|
| - make gdb.dvi
|
| -
|
| - Then give `gdb.dvi' to your DVI printing program.
|
| -
|
| - ---------- Footnotes ----------
|
| -
|
| - (1) In `gdb-7.5.1/gdb/refcard.ps' of the version 7.5.1 release.
|
| -
|
| -
|
| -File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
|
| -
|
| -Appendix C Installing GDB
|
| -*************************
|
| -
|
| -* Menu:
|
| -
|
| -* Requirements:: Requirements for building GDB
|
| -* Running Configure:: Invoking the GDB `configure' script
|
| -* Separate Objdir:: Compiling GDB in another directory
|
| -* Config Names:: Specifying names for hosts and targets
|
| -* Configure Options:: Summary of options for configure
|
| -* System-wide configuration:: Having a system-wide init file
|
| -
|
| -
|
| -File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
|
| -
|
| -C.1 Requirements for Building GDB
|
| -=================================
|
| -
|
| -Building GDB requires various tools and packages to be available.
|
| -Other packages will be used only if they are found.
|
| -
|
| -Tools/Packages Necessary for Building GDB
|
| -=========================================
|
| -
|
| -ISO C90 compiler
|
| - GDB is written in ISO C90. It should be buildable with any
|
| - working C90 compiler, e.g. GCC.
|
| -
|
| -
|
| -Tools/Packages Optional for Building GDB
|
| -========================================
|
| -
|
| -Expat
|
| - GDB can use the Expat XML parsing library. This library may be
|
| - included with your operating system distribution; if it is not, you
|
| - can get the latest version from `http://expat.sourceforge.net'.
|
| - The `configure' script will search for this library in several
|
| - standard locations; if it is installed in an unusual path, you can
|
| - use the `--with-libexpat-prefix' option to specify its location.
|
| -
|
| - Expat is used for:
|
| -
|
| - * Remote protocol memory maps (*note Memory Map Format::)
|
| -
|
| - * Target descriptions (*note Target Descriptions::)
|
| -
|
| - * Remote shared library lists (*Note Library List Format::, or
|
| - alternatively *note Library List Format for SVR4 Targets::)
|
| -
|
| - * MS-Windows shared libraries (*note Shared Libraries::)
|
| -
|
| - * Traceframe info (*note Traceframe Info Format::)
|
| -
|
| -zlib
|
| - GDB will use the `zlib' library, if available, to read compressed
|
| - debug sections. Some linkers, such as GNU gold, are capable of
|
| - producing binaries with compressed debug sections. If GDB is
|
| - compiled with `zlib', it will be able to read the debug
|
| - information in such binaries.
|
| -
|
| - The `zlib' library is likely included with your operating system
|
| - distribution; if it is not, you can get the latest version from
|
| - `http://zlib.net'.
|
| -
|
| -iconv
|
| - GDB's features related to character sets (*note Character Sets::)
|
| - require a functioning `iconv' implementation. If you are on a GNU
|
| - system, then this is provided by the GNU C Library. Some other
|
| - systems also provide a working `iconv'.
|
| -
|
| - If GDB is using the `iconv' program which is installed in a
|
| - non-standard place, you will need to tell GDB where to find it.
|
| - This is done with `--with-iconv-bin' which specifies the directory
|
| - that contains the `iconv' program.
|
| -
|
| - On systems without `iconv', you can install GNU Libiconv. If you
|
| - have previously installed Libiconv, you can use the
|
| - `--with-libiconv-prefix' option to configure.
|
| -
|
| - GDB's top-level `configure' and `Makefile' will arrange to build
|
| - Libiconv if a directory named `libiconv' appears in the top-most
|
| - source directory. If Libiconv is built this way, and if the
|
| - operating system does not provide a suitable `iconv'
|
| - implementation, then the just-built library will automatically be
|
| - used by GDB. One easy way to set this up is to download GNU
|
| - Libiconv, unpack it, and then rename the directory holding the
|
| - Libiconv source code to `libiconv'.
|
| +The commands describing how to ask GDB to stop when a program raises an
|
| +exception are described at *note Ada Exception GDB/MI Catchpoint
|
| +Commands::.
|
|
|
|
|
Chromium Code Reviews
Issue 124383005:
GDB 7.6.50 (Closed)
Base URL: http://git.chromium.org/native_client/nacl-gdb.git@upstream