X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fpython.texi;h=a38f1dab426eb0e1413865e326c6690f16a83c64;hb=refs%2Fheads%2Fconcurrent-displaced-stepping-2020-04-01;hp=5d762aa612aefdf6ff4b1aad46479c3b4ee9fea5;hpb=db178f47dd4c9d2882da42a8915018d1fb90ea17;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 5d762aa612..a38f1dab42 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2008-2019 Free Software Foundation, Inc. +@c Copyright (C) 2008--2020 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.3 or @c any later version published by the Free Software Foundation; with the @@ -163,6 +163,7 @@ optional arguments while skipping others. Example: using Python. * Lazy Strings In Python:: Python representation of lazy strings. * Architectures In Python:: Python representation of architectures. +* TUI Windows In Python:: Implementing new TUI windows. @end menu @node Basic Python @@ -1067,6 +1068,29 @@ The type code for this type. The type code will be one of the @code{TYPE_CODE_} constants defined below. @end defvar +@defvar Type.dynamic +A boolean indicating whether this type is dynamic. In some +situations, such as Rust @code{enum} types or Ada variant records, the +concrete type of a value may vary depending on its contents. That is, +the declared type of a variable, or the type returned by +@code{gdb.lookup_type} may be dynamic; while the type of the +variable's value will be a concrete instance of that dynamic type. + +For example, consider this code: +@smallexample +int n; +int array[n]; +@end smallexample + +Here, at least conceptually (whether your compiler actually does this +is a separate issue), examining @w{@code{gdb.lookup_symbol("array", ...).type}} +could yield a @code{gdb.Type} which reports a size of @code{None}. +This is the dynamic type. + +However, examining @code{gdb.parse_and_eval("array").type} would yield +a concrete type, whose length would be known. +@end defvar + @defvar Type.name The name of this type. If this type has no name, then @code{None} is returned. @@ -1075,7 +1099,9 @@ is returned. @defvar Type.sizeof The size of this type, in target @code{char} units. Usually, a target's @code{char} type will be an 8-bit byte. However, on some -unusual platforms, this type may have a different size. +unusual platforms, this type may have a different size. A dynamic +type may not have a fixed size; in this case, this attribute's value +will be @code{None}. @end defvar @defvar Type.tag @@ -1105,7 +1131,10 @@ Each field is a @code{gdb.Field} object, with some pre-defined attributes: @item bitpos This attribute is not available for @code{enum} or @code{static} (as in C@t{++}) fields. The value is the position, counting -in bits, from the start of the containing type. +in bits, from the start of the containing type. Note that, in a +dynamic type, the position of a field may not be constant. In this +case, the value will be @code{None}. Also, a dynamic type may have +fields that do not appear in a corresponding concrete type. @item enumval This attribute is only available for @code{enum} fields, and its value @@ -2928,7 +2957,7 @@ itself. @findex gdb.Inferior Programs which are being run under @value{GDBN} are called inferiors -(@pxref{Inferiors and Programs}). Python scripts can access +(@pxref{Inferiors Connections and Programs}). Python scripts can access information about and manipulate inferiors controlled by @value{GDBN} via objects of the @code{gdb.Inferior} class. @@ -3294,7 +3323,7 @@ is no selected thread, this will return @code{None}. @end defun To get the list of threads for an inferior, use the @code{Inferior.threads()} -method. @xref{Inferiors In Python} +method. @xref{Inferiors In Python}. A @code{gdb.InferiorThread} object has the following attributes: @@ -3800,6 +3829,13 @@ The command has to do with tracepoints. For example, @code{trace}, @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of commands in this category. +@findex COMMAND_TUI +@findex gdb.COMMAND_TUI +@item gdb.COMMAND_TUI +The command has to do with the text user interface (@pxref{TUI}). +Type @kbd{help tui} at the @value{GDBN} prompt to see a list of +commands in this category. + @findex COMMAND_USER @findex gdb.COMMAND_USER @item gdb.COMMAND_USER @@ -4161,7 +4197,7 @@ A program space, or @dfn{progspace}, represents a symbolic view of an address space. It consists of all of the objfiles of the program. @xref{Objfiles In Python}. -@xref{Inferiors and Programs, program spaces}, for more details +@xref{Inferiors Connections and Programs, program spaces}, for more details about program spaces. The following progspace-related functions are available in the @@ -4170,7 +4206,7 @@ The following progspace-related functions are available in the @findex gdb.current_progspace @defun gdb.current_progspace () This function returns the program space of the currently selected inferior. -@xref{Inferiors and Programs}. This is identical to +@xref{Inferiors Connections and Programs}. This is identical to @code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is included for historical compatibility. @end defun @@ -4279,7 +4315,7 @@ gdb.events.clear_objfiles.connect(clear_objfiles_handler) gdb.events.new_objfile.connect(new_objfile_handler) end (gdb) file /tmp/hello -Reading symbols from /tmp/hello...done. +Reading symbols from /tmp/hello... Computing the answer to the ultimate question ... (gdb) python print gdb.current_progspace().expensive_computation 42 @@ -4418,7 +4454,7 @@ def new_objfile_handler(event): gdb.events.new_objfile.connect(new_objfile_handler) end (gdb) file ./hello -Reading symbols from ./hello...done. +Reading symbols from ./hello... (gdb) python print gdb.objfiles()[0].time_loaded 2014-10-09 11:41:36.770345 @end smallexample @@ -5673,6 +5709,110 @@ instruction in bytes. @end table @end defun +@node TUI Windows In Python +@subsubsection Implementing new TUI windows +@cindex Python TUI Windows + +New TUI (@pxref{TUI}) windows can be implemented in Python. + +@findex gdb.register_window_type +@defun gdb.register_window_type (@var{name}, @var{factory}) +Because TUI windows are created and destroyed depending on the layout +the user chooses, new window types are implemented by registering a +factory function with @value{GDBN}. + +@var{name} is the name of the new window. It's an error to try to +replace one of the built-in windows, but other window types can be +replaced. + +@var{function} is a factory function that is called to create the TUI +window. This is called with a single argument of type +@code{gdb.TuiWindow}, described below. It should return an object +that implements the TUI window protocol, also described below. +@end defun + +As mentioned above, when a factory function is called, it is passed a +an object of type @code{gdb.TuiWindow}. This object has these +methods and attributes: + +@defun TuiWindow.is_valid () +This method returns @code{True} when this window is valid. When the +user changes the TUI layout, windows no longer visible in the new +layout will be destroyed. At this point, the @code{gdb.TuiWindow} +will no longer be valid, and methods (and attributes) other than +@code{is_valid} will throw an exception. +@end defun + +@defvar TuiWindow.width +This attribute holds the width of the window. It is not writable. +@end defvar + +@defvar TuiWindow.height +This attribute holds the height of the window. It is not writable. +@end defvar + +@defvar TuiWindow.title +This attribute holds the window's title, a string. This is normally +displayed above the window. This attribute can be modified. +@end defvar + +@defun TuiWindow.erase () +Remove all the contents of the window. +@end defun + +@defun TuiWindow.write (@var{string}) +Write @var{string} to the window. @var{string} can contain ANSI +terminal escape styling sequences; @value{GDBN} will translate these +as appropriate for the terminal. +@end defun + +The factory function that you supply should return an object +conforming to the TUI window protocol. These are the method that can +be called on this object, which is referred to below as the ``window +object''. The methods documented below are optional; if the object +does not implement one of these methods, @value{GDBN} will not attempt +to call it. Additional new methods may be added to the window +protocol in the future. @value{GDBN} guarantees that they will begin +with a lower-case letter, so you can start implementation methods with +upper-case letters or underscore to avoid any future conflicts. + +@defun Window.close () +When the TUI window is closed, the @code{gdb.TuiWindow} object will be +put into an invalid state. At this time, @value{GDBN} will call +@code{close} method on the window object. + +After this method is called, @value{GDBN} will discard any references +it holds on this window object, and will no longer call methods on +this object. +@end defun + +@defun Window.render () +In some situations, a TUI window can change size. For example, this +can happen if the user resizes the terminal, or changes the layout. +When this happens, @value{GDBN} will call the @code{render} method on +the window object. + +If your window is intended to update in response to changes in the +inferior, you will probably also want to register event listeners and +send output to the @code{gdb.TuiWindow}. +@end defun + +@defun Window.hscroll (@var{num}) +This is a request to scroll the window horizontally. @var{num} is the +amount by which to scroll, with negative numbers meaning to scroll +right. In the TUI model, it is the viewport that moves, not the +contents. A positive argument should cause the viewport to move +right, and so the content should appear to move to the left. +@end defun + +@defun Window.vscroll (@var{num}) +This is a request to scroll the window vertically. @var{num} is the +amount by which to scroll, with negative numbers meaning to scroll +backward. In the TUI model, it is the viewport that moves, not the +contents. A positive argument should cause the viewport to move down, +and so the content should appear to move up. +@end defun + @node Python Auto-loading @subsection Python Auto-loading @cindex Python auto-loading