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