1 /* Python interface to symbols.
3 Copyright (C) 2008-2017 Free Software Foundation, Inc.
5 This file is part of GDB.
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.
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.
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/>. */
24 #include "python-internal.h"
28 typedef struct sympy_symbol_object
{
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
36 struct sympy_symbol_object
*prev
;
37 struct sympy_symbol_object
*next
;
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) \
44 symbol = symbol_object_to_symbol (symbol_obj); \
47 PyErr_SetString (PyExc_RuntimeError, \
48 _("Symbol is invalid.")); \
53 static const struct objfile_data
*sympy_objfile_data_key
;
56 sympy_str (PyObject
*self
)
59 struct symbol
*symbol
= NULL
;
61 SYMPY_REQUIRE_VALID (self
, symbol
);
63 result
= PyString_FromString (SYMBOL_PRINT_NAME (symbol
));
69 sympy_get_type (PyObject
*self
, void *closure
)
71 struct symbol
*symbol
= NULL
;
73 SYMPY_REQUIRE_VALID (self
, symbol
);
75 if (SYMBOL_TYPE (symbol
) == NULL
)
81 return type_to_type_object (SYMBOL_TYPE (symbol
));
85 sympy_get_symtab (PyObject
*self
, void *closure
)
87 struct symbol
*symbol
= NULL
;
89 SYMPY_REQUIRE_VALID (self
, symbol
);
91 if (!SYMBOL_OBJFILE_OWNED (symbol
))
94 return symtab_to_symtab_object (symbol_symtab (symbol
));
98 sympy_get_name (PyObject
*self
, void *closure
)
100 struct symbol
*symbol
= NULL
;
102 SYMPY_REQUIRE_VALID (self
, symbol
);
104 return PyString_FromString (SYMBOL_NATURAL_NAME (symbol
));
108 sympy_get_linkage_name (PyObject
*self
, void *closure
)
110 struct symbol
*symbol
= NULL
;
112 SYMPY_REQUIRE_VALID (self
, symbol
);
114 return PyString_FromString (SYMBOL_LINKAGE_NAME (symbol
));
118 sympy_get_print_name (PyObject
*self
, void *closure
)
120 struct symbol
*symbol
= NULL
;
122 SYMPY_REQUIRE_VALID (self
, symbol
);
124 return sympy_str (self
);
128 sympy_get_addr_class (PyObject
*self
, void *closure
)
130 struct symbol
*symbol
= NULL
;
132 SYMPY_REQUIRE_VALID (self
, symbol
);
134 return PyInt_FromLong (SYMBOL_CLASS (symbol
));
138 sympy_is_argument (PyObject
*self
, void *closure
)
140 struct symbol
*symbol
= NULL
;
142 SYMPY_REQUIRE_VALID (self
, symbol
);
144 return PyBool_FromLong (SYMBOL_IS_ARGUMENT (symbol
));
148 sympy_is_constant (PyObject
*self
, void *closure
)
150 struct symbol
*symbol
= NULL
;
151 enum address_class theclass
;
153 SYMPY_REQUIRE_VALID (self
, symbol
);
155 theclass
= SYMBOL_CLASS (symbol
);
157 return PyBool_FromLong (theclass
== LOC_CONST
|| theclass
== LOC_CONST_BYTES
);
161 sympy_is_function (PyObject
*self
, void *closure
)
163 struct symbol
*symbol
= NULL
;
164 enum address_class theclass
;
166 SYMPY_REQUIRE_VALID (self
, symbol
);
168 theclass
= SYMBOL_CLASS (symbol
);
170 return PyBool_FromLong (theclass
== LOC_BLOCK
);
174 sympy_is_variable (PyObject
*self
, void *closure
)
176 struct symbol
*symbol
= NULL
;
177 enum address_class theclass
;
179 SYMPY_REQUIRE_VALID (self
, symbol
);
181 theclass
= SYMBOL_CLASS (symbol
);
183 return PyBool_FromLong (!SYMBOL_IS_ARGUMENT (symbol
)
184 && (theclass
== LOC_LOCAL
|| theclass
== LOC_REGISTER
185 || theclass
== LOC_STATIC
|| theclass
== LOC_COMPUTED
186 || theclass
== LOC_OPTIMIZED_OUT
));
189 /* Implementation of gdb.Symbol.needs_frame -> Boolean.
190 Returns true iff the symbol needs a frame for evaluation. */
193 sympy_needs_frame (PyObject
*self
, void *closure
)
195 struct symbol
*symbol
= NULL
;
198 SYMPY_REQUIRE_VALID (self
, symbol
);
202 result
= symbol_read_needs_frame (symbol
);
204 CATCH (except
, RETURN_MASK_ALL
)
206 GDB_PY_HANDLE_EXCEPTION (except
);
215 /* Implementation of gdb.Symbol.line -> int.
216 Returns the line number at which the symbol was defined. */
219 sympy_line (PyObject
*self
, void *closure
)
221 struct symbol
*symbol
= NULL
;
223 SYMPY_REQUIRE_VALID (self
, symbol
);
225 return PyInt_FromLong (SYMBOL_LINE (symbol
));
228 /* Implementation of gdb.Symbol.is_valid (self) -> Boolean.
229 Returns True if this Symbol still exists in GDB. */
232 sympy_is_valid (PyObject
*self
, PyObject
*args
)
234 struct symbol
*symbol
= NULL
;
236 symbol
= symbol_object_to_symbol (self
);
243 /* Implementation of gdb.Symbol.value (self[, frame]) -> gdb.Value. Returns
244 the value of the symbol, or an error in various circumstances. */
247 sympy_value (PyObject
*self
, PyObject
*args
)
249 struct symbol
*symbol
= NULL
;
250 struct frame_info
*frame_info
= NULL
;
251 PyObject
*frame_obj
= NULL
;
252 struct value
*value
= NULL
;
254 if (!PyArg_ParseTuple (args
, "|O", &frame_obj
))
257 if (frame_obj
!= NULL
&& !PyObject_TypeCheck (frame_obj
, &frame_object_type
))
259 PyErr_SetString (PyExc_TypeError
, "argument is not a frame");
263 SYMPY_REQUIRE_VALID (self
, symbol
);
264 if (SYMBOL_CLASS (symbol
) == LOC_TYPEDEF
)
266 PyErr_SetString (PyExc_TypeError
, "cannot get the value of a typedef");
272 if (frame_obj
!= NULL
)
274 frame_info
= frame_object_to_frame_info (frame_obj
);
275 if (frame_info
== NULL
)
276 error (_("invalid frame"));
279 if (symbol_read_needs_frame (symbol
) && frame_info
== NULL
)
280 error (_("symbol requires a frame to compute its value"));
282 /* TODO: currently, we have no way to recover the block in which SYMBOL
283 was found, so we have no block to pass to read_var_value. This will
284 yield an incorrect value when symbol is not local to FRAME_INFO (this
285 can happen with nested functions). */
286 value
= read_var_value (symbol
, NULL
, frame_info
);
288 CATCH (except
, RETURN_MASK_ALL
)
290 GDB_PY_HANDLE_EXCEPTION (except
);
294 return value_to_value_object (value
);
297 /* Given a symbol, and a symbol_object that has previously been
298 allocated and initialized, populate the symbol_object with the
299 struct symbol data. Also, register the symbol_object life-cycle
300 with the life-cycle of the object file associated with this
301 symbol, if needed. */
303 set_symbol (symbol_object
*obj
, struct symbol
*symbol
)
305 obj
->symbol
= symbol
;
307 if (SYMBOL_OBJFILE_OWNED (symbol
)
308 && symbol_symtab (symbol
) != NULL
)
310 struct objfile
*objfile
= symbol_objfile (symbol
);
312 obj
->next
= ((struct sympy_symbol_object
*)
313 objfile_data (objfile
, sympy_objfile_data_key
));
315 obj
->next
->prev
= obj
;
316 set_objfile_data (objfile
, sympy_objfile_data_key
, obj
);
322 /* Create a new symbol object (gdb.Symbol) that encapsulates the struct
323 symbol object from GDB. */
325 symbol_to_symbol_object (struct symbol
*sym
)
327 symbol_object
*sym_obj
;
329 sym_obj
= PyObject_New (symbol_object
, &symbol_object_type
);
331 set_symbol (sym_obj
, sym
);
333 return (PyObject
*) sym_obj
;
336 /* Return the symbol that is wrapped by this symbol object. */
338 symbol_object_to_symbol (PyObject
*obj
)
340 if (! PyObject_TypeCheck (obj
, &symbol_object_type
))
342 return ((symbol_object
*) obj
)->symbol
;
346 sympy_dealloc (PyObject
*obj
)
348 symbol_object
*sym_obj
= (symbol_object
*) obj
;
351 sym_obj
->prev
->next
= sym_obj
->next
;
352 else if (sym_obj
->symbol
!= NULL
353 && SYMBOL_OBJFILE_OWNED (sym_obj
->symbol
)
354 && symbol_symtab (sym_obj
->symbol
) != NULL
)
356 set_objfile_data (symbol_objfile (sym_obj
->symbol
),
357 sympy_objfile_data_key
, sym_obj
->next
);
360 sym_obj
->next
->prev
= sym_obj
->prev
;
361 sym_obj
->symbol
= NULL
;
365 gdb.lookup_symbol (name [, block] [, domain]) -> (symbol, is_field_of_this)
366 A tuple with 2 elements is always returned. The first is the symbol
367 object or None, the second is a boolean with the value of
368 is_a_field_of_this (see comment in lookup_symbol_in_language). */
371 gdbpy_lookup_symbol (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
373 int domain
= VAR_DOMAIN
;
374 struct field_of_this_result is_a_field_of_this
;
376 static char *keywords
[] = { "name", "block", "domain", NULL
};
377 struct symbol
*symbol
= NULL
;
378 PyObject
*block_obj
= NULL
, *sym_obj
, *bool_obj
;
379 const struct block
*block
= NULL
;
381 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "s|O!i", keywords
, &name
,
382 &block_object_type
, &block_obj
, &domain
))
386 block
= block_object_to_block (block_obj
);
389 struct frame_info
*selected_frame
;
393 selected_frame
= get_selected_frame (_("No frame selected."));
394 block
= get_frame_block (selected_frame
, NULL
);
396 CATCH (except
, RETURN_MASK_ALL
)
398 GDB_PY_HANDLE_EXCEPTION (except
);
405 symbol
= lookup_symbol (name
, block
, (domain_enum
) domain
,
406 &is_a_field_of_this
).symbol
;
408 CATCH (except
, RETURN_MASK_ALL
)
410 GDB_PY_HANDLE_EXCEPTION (except
);
414 gdbpy_ref
<> ret_tuple (PyTuple_New (2));
415 if (ret_tuple
== NULL
)
420 sym_obj
= symbol_to_symbol_object (symbol
);
429 PyTuple_SET_ITEM (ret_tuple
.get (), 0, sym_obj
);
431 bool_obj
= (is_a_field_of_this
.type
!= NULL
) ? Py_True
: Py_False
;
432 Py_INCREF (bool_obj
);
433 PyTuple_SET_ITEM (ret_tuple
.get (), 1, bool_obj
);
435 return ret_tuple
.release ();
439 gdb.lookup_global_symbol (name [, domain]) -> symbol or None. */
442 gdbpy_lookup_global_symbol (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
444 int domain
= VAR_DOMAIN
;
446 static char *keywords
[] = { "name", "domain", NULL
};
447 struct symbol
*symbol
= NULL
;
450 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "s|i", keywords
, &name
,
456 symbol
= lookup_global_symbol (name
, NULL
, (domain_enum
) domain
).symbol
;
458 CATCH (except
, RETURN_MASK_ALL
)
460 GDB_PY_HANDLE_EXCEPTION (except
);
466 sym_obj
= symbol_to_symbol_object (symbol
);
479 /* This function is called when an objfile is about to be freed.
480 Invalidate the symbol as further actions on the symbol would result
481 in bad data. All access to obj->symbol should be gated by
482 SYMPY_REQUIRE_VALID which will raise an exception on invalid
485 del_objfile_symbols (struct objfile
*objfile
, void *datum
)
487 symbol_object
*obj
= (symbol_object
*) datum
;
490 symbol_object
*next
= obj
->next
;
501 gdbpy_initialize_symbols (void)
503 if (PyType_Ready (&symbol_object_type
) < 0)
506 /* Register an objfile "free" callback so we can properly
507 invalidate symbol when an object file that is about to be
509 sympy_objfile_data_key
510 = register_objfile_data_with_cleanup (NULL
, del_objfile_symbols
);
512 if (PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_UNDEF", LOC_UNDEF
) < 0
513 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_CONST",
515 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_STATIC",
517 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REGISTER",
519 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_ARG",
521 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REF_ARG",
523 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_LOCAL",
525 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_TYPEDEF",
527 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_LABEL",
529 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_BLOCK",
531 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_CONST_BYTES",
533 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_UNRESOLVED",
535 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_OPTIMIZED_OUT",
536 LOC_OPTIMIZED_OUT
) < 0
537 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_COMPUTED",
539 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REGPARM_ADDR",
540 LOC_REGPARM_ADDR
) < 0
541 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_UNDEF_DOMAIN",
543 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_VAR_DOMAIN",
545 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_STRUCT_DOMAIN",
547 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LABEL_DOMAIN",
549 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_VARIABLES_DOMAIN",
550 VARIABLES_DOMAIN
) < 0
551 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_FUNCTIONS_DOMAIN",
552 FUNCTIONS_DOMAIN
) < 0
553 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_TYPES_DOMAIN",
557 return gdb_pymodule_addobject (gdb_module
, "Symbol",
558 (PyObject
*) &symbol_object_type
);
563 static PyGetSetDef symbol_object_getset
[] = {
564 { "type", sympy_get_type
, NULL
,
565 "Type of the symbol.", NULL
},
566 { "symtab", sympy_get_symtab
, NULL
,
567 "Symbol table in which the symbol appears.", NULL
},
568 { "name", sympy_get_name
, NULL
,
569 "Name of the symbol, as it appears in the source code.", NULL
},
570 { "linkage_name", sympy_get_linkage_name
, NULL
,
571 "Name of the symbol, as used by the linker (i.e., may be mangled).",
573 { "print_name", sympy_get_print_name
, NULL
,
574 "Name of the symbol in a form suitable for output.\n\
575 This is either name or linkage_name, depending on whether the user asked GDB\n\
576 to display demangled or mangled names.", NULL
},
577 { "addr_class", sympy_get_addr_class
, NULL
, "Address class of the symbol." },
578 { "is_argument", sympy_is_argument
, NULL
,
579 "True if the symbol is an argument of a function." },
580 { "is_constant", sympy_is_constant
, NULL
,
581 "True if the symbol is a constant." },
582 { "is_function", sympy_is_function
, NULL
,
583 "True if the symbol is a function or method." },
584 { "is_variable", sympy_is_variable
, NULL
,
585 "True if the symbol is a variable." },
586 { "needs_frame", sympy_needs_frame
, NULL
,
587 "True if the symbol requires a frame for evaluation." },
588 { "line", sympy_line
, NULL
,
589 "The source line number at which the symbol was defined." },
590 { NULL
} /* Sentinel */
593 static PyMethodDef symbol_object_methods
[] = {
594 { "is_valid", sympy_is_valid
, METH_NOARGS
,
595 "is_valid () -> Boolean.\n\
596 Return true if this symbol is valid, false if not." },
597 { "value", sympy_value
, METH_VARARGS
,
598 "value ([frame]) -> gdb.Value\n\
599 Return the value of the symbol." },
600 {NULL
} /* Sentinel */
603 PyTypeObject symbol_object_type
= {
604 PyVarObject_HEAD_INIT (NULL
, 0)
605 "gdb.Symbol", /*tp_name*/
606 sizeof (symbol_object
), /*tp_basicsize*/
608 sympy_dealloc
, /*tp_dealloc*/
615 0, /*tp_as_sequence*/
619 sympy_str
, /*tp_str*/
623 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
624 "GDB symbol object", /*tp_doc */
627 0, /*tp_richcompare */
628 0, /*tp_weaklistoffset */
631 symbol_object_methods
, /*tp_methods */
633 symbol_object_getset
/*tp_getset */