1 /* Python interface to symbols.
3 Copyright (C) 2008-2014 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"
27 typedef struct sympy_symbol_object
{
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
35 struct sympy_symbol_object
*prev
;
36 struct sympy_symbol_object
*next
;
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) \
43 symbol = symbol_object_to_symbol (symbol_obj); \
46 PyErr_SetString (PyExc_RuntimeError, \
47 _("Symbol is invalid.")); \
52 static const struct objfile_data
*sympy_objfile_data_key
;
55 sympy_str (PyObject
*self
)
58 struct symbol
*symbol
= NULL
;
60 SYMPY_REQUIRE_VALID (self
, symbol
);
62 result
= PyString_FromString (SYMBOL_PRINT_NAME (symbol
));
68 sympy_get_type (PyObject
*self
, void *closure
)
70 struct symbol
*symbol
= NULL
;
72 SYMPY_REQUIRE_VALID (self
, symbol
);
74 if (SYMBOL_TYPE (symbol
) == NULL
)
80 return type_to_type_object (SYMBOL_TYPE (symbol
));
84 sympy_get_symtab (PyObject
*self
, void *closure
)
86 struct symbol
*symbol
= NULL
;
88 SYMPY_REQUIRE_VALID (self
, symbol
);
90 return symtab_to_symtab_object (SYMBOL_SYMTAB (symbol
));
94 sympy_get_name (PyObject
*self
, void *closure
)
96 struct symbol
*symbol
= NULL
;
98 SYMPY_REQUIRE_VALID (self
, symbol
);
100 return PyString_FromString (SYMBOL_NATURAL_NAME (symbol
));
104 sympy_get_linkage_name (PyObject
*self
, void *closure
)
106 struct symbol
*symbol
= NULL
;
108 SYMPY_REQUIRE_VALID (self
, symbol
);
110 return PyString_FromString (SYMBOL_LINKAGE_NAME (symbol
));
114 sympy_get_print_name (PyObject
*self
, void *closure
)
116 struct symbol
*symbol
= NULL
;
118 SYMPY_REQUIRE_VALID (self
, symbol
);
120 return sympy_str (self
);
124 sympy_get_addr_class (PyObject
*self
, void *closure
)
126 struct symbol
*symbol
= NULL
;
128 SYMPY_REQUIRE_VALID (self
, symbol
);
130 return PyInt_FromLong (SYMBOL_CLASS (symbol
));
134 sympy_is_argument (PyObject
*self
, void *closure
)
136 struct symbol
*symbol
= NULL
;
138 SYMPY_REQUIRE_VALID (self
, symbol
);
140 return PyBool_FromLong (SYMBOL_IS_ARGUMENT (symbol
));
144 sympy_is_constant (PyObject
*self
, void *closure
)
146 struct symbol
*symbol
= NULL
;
147 enum address_class
class;
149 SYMPY_REQUIRE_VALID (self
, symbol
);
151 class = SYMBOL_CLASS (symbol
);
153 return PyBool_FromLong (class == LOC_CONST
|| class == LOC_CONST_BYTES
);
157 sympy_is_function (PyObject
*self
, void *closure
)
159 struct symbol
*symbol
= NULL
;
160 enum address_class
class;
162 SYMPY_REQUIRE_VALID (self
, symbol
);
164 class = SYMBOL_CLASS (symbol
);
166 return PyBool_FromLong (class == LOC_BLOCK
);
170 sympy_is_variable (PyObject
*self
, void *closure
)
172 struct symbol
*symbol
= NULL
;
173 enum address_class
class;
175 SYMPY_REQUIRE_VALID (self
, symbol
);
177 class = SYMBOL_CLASS (symbol
);
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
));
185 /* Implementation of gdb.Symbol.needs_frame -> Boolean.
186 Returns true iff the symbol needs a frame for evaluation. */
189 sympy_needs_frame (PyObject
*self
, void *closure
)
191 struct symbol
*symbol
= NULL
;
192 volatile struct gdb_exception except
;
195 SYMPY_REQUIRE_VALID (self
, symbol
);
197 TRY_CATCH (except
, RETURN_MASK_ALL
)
199 result
= symbol_read_needs_frame (symbol
);
201 GDB_PY_HANDLE_EXCEPTION (except
);
208 /* Implementation of gdb.Symbol.line -> int.
209 Returns the line number at which the symbol was defined. */
212 sympy_line (PyObject
*self
, void *closure
)
214 struct symbol
*symbol
= NULL
;
216 SYMPY_REQUIRE_VALID (self
, symbol
);
218 return PyInt_FromLong (SYMBOL_LINE (symbol
));
221 /* Implementation of gdb.Symbol.is_valid (self) -> Boolean.
222 Returns True if this Symbol still exists in GDB. */
225 sympy_is_valid (PyObject
*self
, PyObject
*args
)
227 struct symbol
*symbol
= NULL
;
229 symbol
= symbol_object_to_symbol (self
);
236 /* Implementation of gdb.Symbol.value (self[, frame]) -> gdb.Value. Returns
237 the value of the symbol, or an error in various circumstances. */
240 sympy_value (PyObject
*self
, PyObject
*args
)
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
;
248 if (!PyArg_ParseTuple (args
, "|O", &frame_obj
))
251 if (frame_obj
!= NULL
&& !PyObject_TypeCheck (frame_obj
, &frame_object_type
))
253 PyErr_SetString (PyExc_TypeError
, "argument is not a frame");
257 SYMPY_REQUIRE_VALID (self
, symbol
);
258 if (SYMBOL_CLASS (symbol
) == LOC_TYPEDEF
)
260 PyErr_SetString (PyExc_TypeError
, "cannot get the value of a typedef");
264 TRY_CATCH (except
, RETURN_MASK_ALL
)
266 if (frame_obj
!= NULL
)
268 frame_info
= frame_object_to_frame_info (frame_obj
);
269 if (frame_info
== NULL
)
270 error (_("invalid frame"));
273 if (symbol_read_needs_frame (symbol
) && frame_info
== NULL
)
274 error (_("symbol requires a frame to compute its value"));
276 value
= read_var_value (symbol
, frame_info
);
278 GDB_PY_HANDLE_EXCEPTION (except
);
280 return value_to_value_object (value
);
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. */
289 set_symbol (symbol_object
*obj
, struct symbol
*symbol
)
291 obj
->symbol
= symbol
;
293 if (SYMBOL_SYMTAB (symbol
))
295 obj
->next
= objfile_data (SYMBOL_OBJFILE (symbol
),
296 sympy_objfile_data_key
);
299 obj
->next
->prev
= obj
;
300 set_objfile_data (SYMBOL_OBJFILE (symbol
),
301 sympy_objfile_data_key
, obj
);
307 /* Create a new symbol object (gdb.Symbol) that encapsulates the struct
308 symbol object from GDB. */
310 symbol_to_symbol_object (struct symbol
*sym
)
312 symbol_object
*sym_obj
;
314 sym_obj
= PyObject_New (symbol_object
, &symbol_object_type
);
316 set_symbol (sym_obj
, sym
);
318 return (PyObject
*) sym_obj
;
321 /* Return the symbol that is wrapped by this symbol object. */
323 symbol_object_to_symbol (PyObject
*obj
)
325 if (! PyObject_TypeCheck (obj
, &symbol_object_type
))
327 return ((symbol_object
*) obj
)->symbol
;
331 sympy_dealloc (PyObject
*obj
)
333 symbol_object
*sym_obj
= (symbol_object
*) obj
;
336 sym_obj
->prev
->next
= sym_obj
->next
;
337 else if (sym_obj
->symbol
&& SYMBOL_SYMTAB (sym_obj
->symbol
))
339 set_objfile_data (SYMBOL_OBJFILE (sym_obj
->symbol
),
340 sympy_objfile_data_key
, sym_obj
->next
);
343 sym_obj
->next
->prev
= sym_obj
->prev
;
344 sym_obj
->symbol
= NULL
;
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). */
354 gdbpy_lookup_symbol (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
356 int domain
= VAR_DOMAIN
;
357 struct field_of_this_result is_a_field_of_this
;
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
;
365 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "s|O!i", keywords
, &name
,
366 &block_object_type
, &block_obj
, &domain
))
370 block
= block_object_to_block (block_obj
);
373 struct frame_info
*selected_frame
;
374 volatile struct gdb_exception except
;
376 TRY_CATCH (except
, RETURN_MASK_ALL
)
378 selected_frame
= get_selected_frame (_("No frame selected."));
379 block
= get_frame_block (selected_frame
, NULL
);
381 GDB_PY_HANDLE_EXCEPTION (except
);
384 TRY_CATCH (except
, RETURN_MASK_ALL
)
386 symbol
= lookup_symbol (name
, block
, domain
, &is_a_field_of_this
);
388 GDB_PY_HANDLE_EXCEPTION (except
);
390 ret_tuple
= PyTuple_New (2);
396 sym_obj
= symbol_to_symbol_object (symbol
);
399 Py_DECREF (ret_tuple
);
408 PyTuple_SET_ITEM (ret_tuple
, 0, sym_obj
);
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
);
418 gdb.lookup_global_symbol (name [, domain]) -> symbol or None. */
421 gdbpy_lookup_global_symbol (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
423 int domain
= VAR_DOMAIN
;
425 static char *keywords
[] = { "name", "domain", NULL
};
426 struct symbol
*symbol
= NULL
;
428 volatile struct gdb_exception except
;
430 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "s|i", keywords
, &name
,
434 TRY_CATCH (except
, RETURN_MASK_ALL
)
436 symbol
= lookup_global_symbol (name
, NULL
, domain
);
438 GDB_PY_HANDLE_EXCEPTION (except
);
442 sym_obj
= symbol_to_symbol_object (symbol
);
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
461 del_objfile_symbols (struct objfile
*objfile
, void *datum
)
463 symbol_object
*obj
= datum
;
466 symbol_object
*next
= obj
->next
;
477 gdbpy_initialize_symbols (void)
479 if (PyType_Ready (&symbol_object_type
) < 0)
482 /* Register an objfile "free" callback so we can properly
483 invalidate symbol when an object file that is about to be
485 sympy_objfile_data_key
486 = register_objfile_data_with_cleanup (NULL
, del_objfile_symbols
);
488 if (PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_UNDEF", LOC_UNDEF
) < 0
489 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_CONST",
491 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_STATIC",
493 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REGISTER",
495 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_ARG",
497 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REF_ARG",
499 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_LOCAL",
501 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_TYPEDEF",
503 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_LABEL",
505 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_BLOCK",
507 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_CONST_BYTES",
509 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_UNRESOLVED",
511 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_OPTIMIZED_OUT",
512 LOC_OPTIMIZED_OUT
) < 0
513 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_COMPUTED",
515 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REGPARM_ADDR",
516 LOC_REGPARM_ADDR
) < 0
517 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_UNDEF_DOMAIN",
519 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_VAR_DOMAIN",
521 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_STRUCT_DOMAIN",
523 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LABEL_DOMAIN",
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",
533 return gdb_pymodule_addobject (gdb_module
, "Symbol",
534 (PyObject
*) &symbol_object_type
);
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).",
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 */
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 */
579 PyTypeObject symbol_object_type
= {
580 PyVarObject_HEAD_INIT (NULL
, 0)
581 "gdb.Symbol", /*tp_name*/
582 sizeof (symbol_object
), /*tp_basicsize*/
584 sympy_dealloc
, /*tp_dealloc*/
591 0, /*tp_as_sequence*/
595 sympy_str
, /*tp_str*/
599 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
600 "GDB symbol object", /*tp_doc */
603 0, /*tp_richcompare */
604 0, /*tp_weaklistoffset */
607 symbol_object_methods
, /*tp_methods */
609 symbol_object_getset
/*tp_getset */