From 7065f0735e0082ac6cb25dea25ec011a0b8f5680 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Sat, 18 Nov 2023 10:00:12 -0700 Subject: Document new Python and Guile constants This documents the new Python and Guile constants introduced earlier in this series. Approved-By: Eli Zaretskii --- gdb/NEWS | 12 ++++++++++++ gdb/doc/guile.texi | 27 ++++++++++++++++++++++++++- gdb/doc/python.texi | 39 ++++++++++++++++++++++++++++++++++++--- 3 files changed, 74 insertions(+), 4 deletions(-) diff --git a/gdb/NEWS b/gdb/NEWS index bab300e36b8..2638b3e0d9c 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -108,6 +108,11 @@ show remote thread-options-packet object, these will be stored in the object's new InferiorThread.__dict__ attribute. + ** New constants gdb.SYMBOL_TYPE_DOMAIN, gdb.SYMBOL_FUNCTION_DOMAIN, + and gdb.SEARCH_*_DOMAIN corresponding to all the existing symbol + domains. Symbol lookup can now search in multiple domains at + once, and can also narrowly search for just a type or function. + * Debugger Adapter Protocol changes ** GDB now emits the "process" event. @@ -121,6 +126,13 @@ show remote thread-options-packet ** The "set debug dap-log-file" command is now documented. This command was available in GDB 14 but not documented. +* Guile API + + ** New constants SYMBOL_TYPE_DOMAIN, SYMBOL_FUNCTION_DOMAIN, and + SEARCH_*_DOMAIN corresponding to all the existing symbol domains. + Symbol lookup can now search in multiple domains at once, and can + also narrowly search for just a type or function. + * New remote packets New stop reason: clone diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index 271b672fdc6..7326186941d 100644 --- a/gdb/doc/guile.texi +++ b/gdb/doc/guile.texi @@ -2802,8 +2802,24 @@ in the symbol information or in @value{GDBN}'s handling of symbols. This domain contains variables, function names, typedef names and enum type values. +@item SYMBOL_FUNCTION_DOMAIN +This domain contains functions. + +@item SYMBOL_TYPE_DOMAIN +This domain contains types. In a C-like language, types using a tag +(the name appearing after a @code{struct}, @code{union}, or +@code{enum} keyword) will not appear here; in other languages, all +types are in this domain. + @item SYMBOL_STRUCT_DOMAIN -This domain holds struct, union and enum type names. +This domain holds struct, union and enum tag names. This domain is +only used for C-like languages. For example, in this code: +@smallexample +struct type_one @{ int x; @}; +typedef struct type_one type_two; +@end smallexample +Here @code{type_one} will be in @code{SYMBOL_STRUCT_DOMAIN}, but +@code{type_two} will be in @code{SYMBOL_TYPE_DOMAIN}. @item SYMBOL_LABEL_DOMAIN This domain contains names of labels (for gotos). @@ -2822,6 +2838,15 @@ This domain contains all types. The available address class categories in @code{} are represented as constants in the @code{gdb} module: +When searching for a symbol, the desired domain constant can be passed +verbatim to the lookup function. + +For more complex searches, there is a corresponding set of constants, +each named after one of the preceding constants, but with the +@samp{SEARCH} prefix replacing the @samp{SYMBOL} prefix; for example, +@code{SEARCH_LABEL_DOMAIN}. These may be or'd together to form a +search constant. + @vtable @code @item SYMBOL_LOC_UNDEF If this is returned by address class, it indicates an error either in diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 71431878dd3..ece9038844c 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -6214,12 +6214,29 @@ in the symbol information or in @value{GDBN}'s handling of symbols. @vindex SYMBOL_VAR_DOMAIN @item gdb.SYMBOL_VAR_DOMAIN -This domain contains variables, function names, typedef names and enum -type values. +This domain contains variables. + +@vindex SYMBOL_FUNCTION_DOMAIN +@item gdb.SYMBOL_FUNCTION_DOMAIN +This domain contains functions. + +@vindex SYMBOL_TYPE_DOMAIN +@item gdb.SYMBOL_TYPE_DOMAIN +This domain contains types. In a C-like language, types using a tag +(the name appearing after a @code{struct}, @code{union}, or +@code{enum} keyword) will not appear here; in other languages, all +types are in this domain. @vindex SYMBOL_STRUCT_DOMAIN @item gdb.SYMBOL_STRUCT_DOMAIN -This domain holds struct, union and enum type names. +This domain holds struct, union and enum tag names. This domain is +only used for C-like languages. For example, in this code: +@smallexample +struct type_one @{ int x; @}; +typedef struct type_one type_two; +@end smallexample +Here @code{type_one} will be in @code{SYMBOL_STRUCT_DOMAIN}, but +@code{type_two} will be in @code{SYMBOL_TYPE_DOMAIN}. @vindex SYMBOL_LABEL_DOMAIN @item gdb.SYMBOL_LABEL_DOMAIN @@ -6234,6 +6251,22 @@ This domain contains names of Fortran module types. This domain contains names of Fortran common blocks. @end vtable +When searching for a symbol, the desired domain constant can be passed +verbatim to the lookup function. For example: +@smallexample +symbol = gdb.lookup_symbol ("name", domain=gdb.SYMBOL_VAR_DOMAIN) +@end smallexample + +For more complex searches, there is a corresponding set of constants, +each named after one of the preceding constants, but with the +@samp{SEARCH} prefix replacing the @samp{SYMBOL} prefix; for example, +@code{SEARCH_LABEL_DOMAIN}. These may be or'd together to form a +search constant, e.g.: +@smallexample +symbol = gdb.lookup_symbol ("name", + domain=gdb.SEARCH_VAR_DOMAIN | gdb.SEARCH_TYPE_DOMAIN) +@end smallexample + The available address class categories in @code{gdb.Symbol} are represented as constants in the @code{gdb} module: -- cgit v1.2.3