gdb/python/py-symbol.c

   1 /* Python interface to symbols.
   2
   3    Copyright (C) 2008-2014 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #include "defs.h"
  21 #include "block.h"
  22 #include "exceptions.h"
  23 #include "frame.h"
  24 #include "symtab.h"
  25 #include "python-internal.h"
  26 #include "objfiles.h"
  27
  28 typedef struct sympy_symbol_object {
  29   PyObject_HEAD
  30   /* The GDB symbol structure this object is wrapping.  */
  31   struct symbol *symbol;
  32   /* A symbol object is associated with an objfile, so keep track with
  33      doubly-linked list, rooted in the objfile.  This lets us
  34      invalidate the underlying struct symbol when the objfile is
  35      deleted.  */
  36   struct sympy_symbol_object *prev;
  37   struct sympy_symbol_object *next;
  38 } symbol_object;
  39
  40 /* Require a valid symbol.  All access to symbol_object->symbol should be
  41    gated by this call.  */
  42 #define SYMPY_REQUIRE_VALID(symbol_obj, symbol)         \
  43   do {                                                  \
  44     symbol = symbol_object_to_symbol (symbol_obj);      \
  45     if (symbol == NULL)                                 \
  46       {                                                 \
  47         PyErr_SetString (PyExc_RuntimeError,            \
  48                          _("Symbol is invalid."));      \
  49         return NULL;                                    \
  50       }                                                 \
  51   } while (0)
  52
  53 static const struct objfile_data *sympy_objfile_data_key;
  54
  55 static PyObject *
  56 sympy_str (PyObject *self)
  57 {
  58   PyObject *result;
  59   struct symbol *symbol = NULL;
  60
  61   SYMPY_REQUIRE_VALID (self, symbol);
  62
  63   result = PyString_FromString (SYMBOL_PRINT_NAME (symbol));
  64
  65   return result;
  66 }
  67
  68 static PyObject *
  69 sympy_get_type (PyObject *self, void *closure)
  70 {
  71   struct symbol *symbol = NULL;
  72
  73   SYMPY_REQUIRE_VALID (self, symbol);
  74
  75   if (SYMBOL_TYPE (symbol) == NULL)
  76     {
  77       Py_INCREF (Py_None);
  78       return Py_None;
  79     }
  80
  81   return type_to_type_object (SYMBOL_TYPE (symbol));
  82 }
  83
  84 static PyObject *
  85 sympy_get_symtab (PyObject *self, void *closure)
  86 {
  87   struct symbol *symbol = NULL;
  88
  89   SYMPY_REQUIRE_VALID (self, symbol);
  90
  91   return symtab_to_symtab_object (SYMBOL_SYMTAB (symbol));
  92 }
  93
  94 static PyObject *
  95 sympy_get_name (PyObject *self, void *closure)
  96 {
  97   struct symbol *symbol = NULL;
  98
  99   SYMPY_REQUIRE_VALID (self, symbol);
 100
 101   return PyString_FromString (SYMBOL_NATURAL_NAME (symbol));
 102 }
 103
 104 static PyObject *
 105 sympy_get_linkage_name (PyObject *self, void *closure)
 106 {
 107   struct symbol *symbol = NULL;
 108
 109   SYMPY_REQUIRE_VALID (self, symbol);
 110
 111   return PyString_FromString (SYMBOL_LINKAGE_NAME (symbol));
 112 }
 113
 114 static PyObject *
 115 sympy_get_print_name (PyObject *self, void *closure)
 116 {
 117   struct symbol *symbol = NULL;
 118
 119   SYMPY_REQUIRE_VALID (self, symbol);
 120
 121   return sympy_str (self);
 122 }
 123
 124 static PyObject *
 125 sympy_get_addr_class (PyObject *self, void *closure)
 126 {
 127   struct symbol *symbol = NULL;
 128
 129   SYMPY_REQUIRE_VALID (self, symbol);
 130
 131   return PyInt_FromLong (SYMBOL_CLASS (symbol));
 132 }
 133
 134 static PyObject *
 135 sympy_is_argument (PyObject *self, void *closure)
 136 {
 137   struct symbol *symbol = NULL;
 138
 139   SYMPY_REQUIRE_VALID (self, symbol);
 140
 141   return PyBool_FromLong (SYMBOL_IS_ARGUMENT (symbol));
 142 }
 143
 144 static PyObject *
 145 sympy_is_constant (PyObject *self, void *closure)
 146 {
 147   struct symbol *symbol = NULL;
 148   enum address_class class;
 149
 150   SYMPY_REQUIRE_VALID (self, symbol);
 151
 152   class = SYMBOL_CLASS (symbol);
 153
 154   return PyBool_FromLong (class == LOC_CONST || class == LOC_CONST_BYTES);
 155 }
 156
 157 static PyObject *
 158 sympy_is_function (PyObject *self, void *closure)
 159 {
 160   struct symbol *symbol = NULL;
 161   enum address_class class;
 162
 163   SYMPY_REQUIRE_VALID (self, symbol);
 164
 165   class = SYMBOL_CLASS (symbol);
 166
 167   return PyBool_FromLong (class == LOC_BLOCK);
 168 }
 169
 170 static PyObject *
 171 sympy_is_variable (PyObject *self, void *closure)
 172 {
 173   struct symbol *symbol = NULL;
 174   enum address_class class;
 175
 176   SYMPY_REQUIRE_VALID (self, symbol);
 177
 178   class = SYMBOL_CLASS (symbol);
 179
 180   return PyBool_FromLong (!SYMBOL_IS_ARGUMENT (symbol)
 181                           && (class == LOC_LOCAL || class == LOC_REGISTER
 182                               || class == LOC_STATIC || class == LOC_COMPUTED
 183                               || class == LOC_OPTIMIZED_OUT));
 184 }
 185
 186 /* Implementation of gdb.Symbol.needs_frame -> Boolean.
 187    Returns true iff the symbol needs a frame for evaluation.  */
 188
 189 static PyObject *
 190 sympy_needs_frame (PyObject *self, void *closure)
 191 {
 192   struct symbol *symbol = NULL;
 193   volatile struct gdb_exception except;
 194   int result = 0;
 195
 196   SYMPY_REQUIRE_VALID (self, symbol);
 197
 198   TRY_CATCH (except, RETURN_MASK_ALL)
 199     {
 200       result = symbol_read_needs_frame (symbol);
 201     }
 202   GDB_PY_HANDLE_EXCEPTION (except);
 203
 204   if (result)
 205     Py_RETURN_TRUE;
 206   Py_RETURN_FALSE;
 207 }
 208
 209 /* Implementation of gdb.Symbol.line -> int.
 210    Returns the line number at which the symbol was defined.  */
 211
 212 static PyObject *
 213 sympy_line (PyObject *self, void *closure)
 214 {
 215   struct symbol *symbol = NULL;
 216
 217   SYMPY_REQUIRE_VALID (self, symbol);
 218
 219   return PyInt_FromLong (SYMBOL_LINE (symbol));
 220 }
 221
 222 /* Implementation of gdb.Symbol.is_valid (self) -> Boolean.
 223    Returns True if this Symbol still exists in GDB.  */
 224
 225 static PyObject *
 226 sympy_is_valid (PyObject *self, PyObject *args)
 227 {
 228   struct symbol *symbol = NULL;
 229
 230   symbol = symbol_object_to_symbol (self);
 231   if (symbol == NULL)
 232     Py_RETURN_FALSE;
 233
 234   Py_RETURN_TRUE;
 235 }
 236
 237 /* Implementation of gdb.Symbol.value (self[, frame]) -> gdb.Value.  Returns
 238    the value of the symbol, or an error in various circumstances.  */
 239
 240 static PyObject *
 241 sympy_value (PyObject *self, PyObject *args)
 242 {
 243   struct symbol *symbol = NULL;
 244   struct frame_info *frame_info = NULL;
 245   PyObject *frame_obj = NULL;
 246   struct value *value = NULL;
 247   volatile struct gdb_exception except;
 248
 249   if (!PyArg_ParseTuple (args, "|O", &frame_obj))
 250     return NULL;
 251
 252   if (frame_obj != NULL && !PyObject_TypeCheck (frame_obj, &frame_object_type))
 253     {
 254       PyErr_SetString (PyExc_TypeError, "argument is not a frame");
 255       return NULL;
 256     }
 257
 258   SYMPY_REQUIRE_VALID (self, symbol);
 259   if (SYMBOL_CLASS (symbol) == LOC_TYPEDEF)
 260     {
 261       PyErr_SetString (PyExc_TypeError, "cannot get the value of a typedef");
 262       return NULL;
 263     }
 264
 265   TRY_CATCH (except, RETURN_MASK_ALL)
 266     {
 267       if (frame_obj != NULL)
 268         {
 269           frame_info = frame_object_to_frame_info (frame_obj);
 270           if (frame_info == NULL)
 271             error (_("invalid frame"));
 272         }
 273
 274       if (symbol_read_needs_frame (symbol) && frame_info == NULL)
 275         error (_("symbol requires a frame to compute its value"));
 276
 277       value = read_var_value (symbol, frame_info);
 278     }
 279   GDB_PY_HANDLE_EXCEPTION (except);
 280
 281   return value_to_value_object (value);
 282 }
 283
 284 /* Given a symbol, and a symbol_object that has previously been
 285    allocated and initialized, populate the symbol_object with the
 286    struct symbol data.  Also, register the symbol_object life-cycle
 287    with the life-cycle of the object file associated with this
 288    symbol, if needed.  */
 289 static void
 290 set_symbol (symbol_object *obj, struct symbol *symbol)
 291 {
 292   obj->symbol = symbol;
 293   obj->prev = NULL;
 294   if (SYMBOL_SYMTAB (symbol))
 295     {
 296       obj->next = objfile_data (SYMBOL_SYMTAB (symbol)->objfile,
 297                                 sympy_objfile_data_key);
 298
 299       if (obj->next)
 300         obj->next->prev = obj;
 301       set_objfile_data (SYMBOL_SYMTAB (symbol)->objfile,
 302                         sympy_objfile_data_key, obj);
 303     }
 304   else
 305     obj->next = NULL;
 306 }
 307
 308 /* Create a new symbol object (gdb.Symbol) that encapsulates the struct
 309    symbol object from GDB.  */
 310 PyObject *
 311 symbol_to_symbol_object (struct symbol *sym)
 312 {
 313   symbol_object *sym_obj;
 314
 315   sym_obj = PyObject_New (symbol_object, &symbol_object_type);
 316   if (sym_obj)
 317     set_symbol (sym_obj, sym);
 318
 319   return (PyObject *) sym_obj;
 320 }
 321
 322 /* Return the symbol that is wrapped by this symbol object.  */
 323 struct symbol *
 324 symbol_object_to_symbol (PyObject *obj)
 325 {
 326   if (! PyObject_TypeCheck (obj, &symbol_object_type))
 327     return NULL;
 328   return ((symbol_object *) obj)->symbol;
 329 }
 330
 331 static void
 332 sympy_dealloc (PyObject *obj)
 333 {
 334   symbol_object *sym_obj = (symbol_object *) obj;
 335
 336   if (sym_obj->prev)
 337     sym_obj->prev->next = sym_obj->next;
 338   else if (sym_obj->symbol && SYMBOL_SYMTAB (sym_obj->symbol))
 339     {
 340       set_objfile_data (SYMBOL_SYMTAB (sym_obj->symbol)->objfile,
 341                         sympy_objfile_data_key, sym_obj->next);
 342     }
 343   if (sym_obj->next)
 344     sym_obj->next->prev = sym_obj->prev;
 345   sym_obj->symbol = NULL;
 346 }
 347
 348 /* Implementation of
 349    gdb.lookup_symbol (name [, block] [, domain]) -> (symbol, is_field_of_this)
 350    A tuple with 2 elements is always returned.  The first is the symbol
 351    object or None, the second is a boolean with the value of
 352    is_a_field_of_this (see comment in lookup_symbol_in_language).  */
 353
 354 PyObject *
 355 gdbpy_lookup_symbol (PyObject *self, PyObject *args, PyObject *kw)
 356 {
 357   int domain = VAR_DOMAIN;
 358   struct field_of_this_result is_a_field_of_this;
 359   const char *name;
 360   static char *keywords[] = { "name", "block", "domain", NULL };
 361   struct symbol *symbol = NULL;
 362   PyObject *block_obj = NULL, *ret_tuple, *sym_obj, *bool_obj;
 363   const struct block *block = NULL;
 364   volatile struct gdb_exception except;
 365
 366   if (! PyArg_ParseTupleAndKeywords (args, kw, "s|O!i", keywords, &name,
 367                                      &block_object_type, &block_obj, &domain))
 368     return NULL;
 369
 370   if (block_obj)
 371     block = block_object_to_block (block_obj);
 372   else
 373     {
 374       struct frame_info *selected_frame;
 375       volatile struct gdb_exception except;
 376
 377       TRY_CATCH (except, RETURN_MASK_ALL)
 378         {
 379           selected_frame = get_selected_frame (_("No frame selected."));
 380           block = get_frame_block (selected_frame, NULL);
 381         }
 382       GDB_PY_HANDLE_EXCEPTION (except);
 383     }
 384
 385   TRY_CATCH (except, RETURN_MASK_ALL)
 386     {
 387       symbol = lookup_symbol (name, block, domain, &is_a_field_of_this);
 388     }
 389   GDB_PY_HANDLE_EXCEPTION (except);
 390
 391   ret_tuple = PyTuple_New (2);
 392   if (!ret_tuple)
 393     return NULL;
 394
 395   if (symbol)
 396     {
 397       sym_obj = symbol_to_symbol_object (symbol);
 398       if (!sym_obj)
 399         {
 400           Py_DECREF (ret_tuple);
 401           return NULL;
 402         }
 403     }
 404   else
 405     {
 406       sym_obj = Py_None;
 407       Py_INCREF (Py_None);
 408     }
 409   PyTuple_SET_ITEM (ret_tuple, 0, sym_obj);
 410
 411   bool_obj = (is_a_field_of_this.type != NULL) ? Py_True : Py_False;
 412   Py_INCREF (bool_obj);
 413   PyTuple_SET_ITEM (ret_tuple, 1, bool_obj);
 414
 415   return ret_tuple;
 416 }
 417
 418 /* Implementation of
 419    gdb.lookup_global_symbol (name [, domain]) -> symbol or None.  */
 420
 421 PyObject *
 422 gdbpy_lookup_global_symbol (PyObject *self, PyObject *args, PyObject *kw)
 423 {
 424   int domain = VAR_DOMAIN;
 425   const char *name;
 426   static char *keywords[] = { "name", "domain", NULL };
 427   struct symbol *symbol = NULL;
 428   PyObject *sym_obj;
 429   volatile struct gdb_exception except;
 430
 431   if (! PyArg_ParseTupleAndKeywords (args, kw, "s|i", keywords, &name,
 432                                      &domain))
 433     return NULL;
 434
 435   TRY_CATCH (except, RETURN_MASK_ALL)
 436     {
 437       symbol = lookup_symbol_global (name, NULL, domain);
 438     }
 439   GDB_PY_HANDLE_EXCEPTION (except);
 440
 441   if (symbol)
 442     {
 443       sym_obj = symbol_to_symbol_object (symbol);
 444       if (!sym_obj)
 445         return NULL;
 446     }
 447   else
 448     {
 449       sym_obj = Py_None;
 450       Py_INCREF (Py_None);
 451     }
 452
 453   return sym_obj;
 454 }
 455
 456 /* This function is called when an objfile is about to be freed.
 457    Invalidate the symbol as further actions on the symbol would result
 458    in bad data.  All access to obj->symbol should be gated by
 459    SYMPY_REQUIRE_VALID which will raise an exception on invalid
 460    symbols.  */
 461 static void
 462 del_objfile_symbols (struct objfile *objfile, void *datum)
 463 {
 464   symbol_object *obj = datum;
 465   while (obj)
 466     {
 467       symbol_object *next = obj->next;
 468
 469       obj->symbol = NULL;
 470       obj->next = NULL;
 471       obj->prev = NULL;
 472
 473       obj = next;
 474     }
 475 }
 476
 477 int
 478 gdbpy_initialize_symbols (void)
 479 {
 480   if (PyType_Ready (&symbol_object_type) < 0)
 481     return -1;
 482
 483   /* Register an objfile "free" callback so we can properly
 484      invalidate symbol when an object file that is about to be
 485      deleted.  */
 486   sympy_objfile_data_key
 487     = register_objfile_data_with_cleanup (NULL, del_objfile_symbols);
 488
 489   if (PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_UNDEF", LOC_UNDEF) < 0
 490       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_CONST",
 491                                   LOC_CONST) < 0
 492       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_STATIC",
 493                                   LOC_STATIC) < 0
 494       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_REGISTER",
 495                                   LOC_REGISTER) < 0
 496       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_ARG",
 497                                   LOC_ARG) < 0
 498       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_REF_ARG",
 499                                   LOC_REF_ARG) < 0
 500       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_LOCAL",
 501                                   LOC_LOCAL) < 0
 502       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_TYPEDEF",
 503                                   LOC_TYPEDEF) < 0
 504       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_LABEL",
 505                                   LOC_LABEL) < 0
 506       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_BLOCK",
 507                                   LOC_BLOCK) < 0
 508       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_CONST_BYTES",
 509                                   LOC_CONST_BYTES) < 0
 510       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_UNRESOLVED",
 511                                   LOC_UNRESOLVED) < 0
 512       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_OPTIMIZED_OUT",
 513                                   LOC_OPTIMIZED_OUT) < 0
 514       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_COMPUTED",
 515                                   LOC_COMPUTED) < 0
 516       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LOC_REGPARM_ADDR",
 517                                   LOC_REGPARM_ADDR) < 0
 518       || PyModule_AddIntConstant (gdb_module, "SYMBOL_UNDEF_DOMAIN",
 519                                   UNDEF_DOMAIN) < 0
 520       || PyModule_AddIntConstant (gdb_module, "SYMBOL_VAR_DOMAIN",
 521                                   VAR_DOMAIN) < 0
 522       || PyModule_AddIntConstant (gdb_module, "SYMBOL_STRUCT_DOMAIN",
 523                                   STRUCT_DOMAIN) < 0
 524       || PyModule_AddIntConstant (gdb_module, "SYMBOL_LABEL_DOMAIN",
 525                                   LABEL_DOMAIN) < 0
 526       || PyModule_AddIntConstant (gdb_module, "SYMBOL_VARIABLES_DOMAIN",
 527                                   VARIABLES_DOMAIN) < 0
 528       || PyModule_AddIntConstant (gdb_module, "SYMBOL_FUNCTIONS_DOMAIN",
 529                                   FUNCTIONS_DOMAIN) < 0
 530       || PyModule_AddIntConstant (gdb_module, "SYMBOL_TYPES_DOMAIN",
 531                                   TYPES_DOMAIN) < 0)
 532     return -1;
 533
 534   return gdb_pymodule_addobject (gdb_module, "Symbol",
 535                                  (PyObject *) &symbol_object_type);
 536 }
 537
 538 \f
 539
 540 static PyGetSetDef symbol_object_getset[] = {
 541   { "type", sympy_get_type, NULL,
 542     "Type of the symbol.", NULL },
 543   { "symtab", sympy_get_symtab, NULL,
 544     "Symbol table in which the symbol appears.", NULL },
 545   { "name", sympy_get_name, NULL,
 546     "Name of the symbol, as it appears in the source code.", NULL },
 547   { "linkage_name", sympy_get_linkage_name, NULL,
 548     "Name of the symbol, as used by the linker (i.e., may be mangled).",
 549     NULL },
 550   { "print_name", sympy_get_print_name, NULL,
 551     "Name of the symbol in a form suitable for output.\n\
 552 This is either name or linkage_name, depending on whether the user asked GDB\n\
 553 to display demangled or mangled names.", NULL },
 554   { "addr_class", sympy_get_addr_class, NULL, "Address class of the symbol." },
 555   { "is_argument", sympy_is_argument, NULL,
 556     "True if the symbol is an argument of a function." },
 557   { "is_constant", sympy_is_constant, NULL,
 558     "True if the symbol is a constant." },
 559   { "is_function", sympy_is_function, NULL,
 560     "True if the symbol is a function or method." },
 561   { "is_variable", sympy_is_variable, NULL,
 562     "True if the symbol is a variable." },
 563   { "needs_frame", sympy_needs_frame, NULL,
 564     "True if the symbol requires a frame for evaluation." },
 565   { "line", sympy_line, NULL,
 566     "The source line number at which the symbol was defined." },
 567   { NULL }  /* Sentinel */
 568 };
 569
 570 static PyMethodDef symbol_object_methods[] = {
 571   { "is_valid", sympy_is_valid, METH_NOARGS,
 572     "is_valid () -> Boolean.\n\
 573 Return true if this symbol is valid, false if not." },
 574   { "value", sympy_value, METH_VARARGS,
 575     "value ([frame]) -> gdb.Value\n\
 576 Return the value of the symbol." },
 577   {NULL}  /* Sentinel */
 578 };
 579
 580 PyTypeObject symbol_object_type = {
 581   PyVarObject_HEAD_INIT (NULL, 0)
 582   "gdb.Symbol",                   /*tp_name*/
 583   sizeof (symbol_object),         /*tp_basicsize*/
 584   0,                              /*tp_itemsize*/
 585   sympy_dealloc,                  /*tp_dealloc*/
 586   0,                              /*tp_print*/
 587   0,                              /*tp_getattr*/
 588   0,                              /*tp_setattr*/
 589   0,                              /*tp_compare*/
 590   0,                              /*tp_repr*/
 591   0,                              /*tp_as_number*/
 592   0,                              /*tp_as_sequence*/
 593   0,                              /*tp_as_mapping*/
 594   0,                              /*tp_hash */
 595   0,                              /*tp_call*/
 596   sympy_str,                      /*tp_str*/
 597   0,                              /*tp_getattro*/
 598   0,                              /*tp_setattro*/
 599   0,                              /*tp_as_buffer*/
 600   Py_TPFLAGS_DEFAULT,             /*tp_flags*/
 601   "GDB symbol object",            /*tp_doc */
 602   0,                              /*tp_traverse */
 603   0,                              /*tp_clear */
 604   0,                              /*tp_richcompare */
 605   0,                              /*tp_weaklistoffset */
 606   0,                              /*tp_iter */
 607   0,                              /*tp_iternext */
 608   symbol_object_methods,          /*tp_methods */
 609   0,                              /*tp_members */
 610   symbol_object_getset            /*tp_getset */
 611 };