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/>. */
22 #include "exceptions.h"
25 #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 return symtab_to_symtab_object (SYMBOL_SYMTAB (symbol
));
95 sympy_get_name (PyObject
*self
, void *closure
)
97 struct symbol
*symbol
= NULL
;
99 SYMPY_REQUIRE_VALID (self
, symbol
);
101 return PyString_FromString (SYMBOL_NATURAL_NAME (symbol
));
105 sympy_get_linkage_name (PyObject
*self
, void *closure
)
107 struct symbol
*symbol
= NULL
;
109 SYMPY_REQUIRE_VALID (self
, symbol
);
111 return PyString_FromString (SYMBOL_LINKAGE_NAME (symbol
));
115 sympy_get_print_name (PyObject
*self
, void *closure
)
117 struct symbol
*symbol
= NULL
;
119 SYMPY_REQUIRE_VALID (self
, symbol
);
121 return sympy_str (self
);
125 sympy_get_addr_class (PyObject
*self
, void *closure
)
127 struct symbol
*symbol
= NULL
;
129 SYMPY_REQUIRE_VALID (self
, symbol
);
131 return PyInt_FromLong (SYMBOL_CLASS (symbol
));
135 sympy_is_argument (PyObject
*self
, void *closure
)
137 struct symbol
*symbol
= NULL
;
139 SYMPY_REQUIRE_VALID (self
, symbol
);
141 return PyBool_FromLong (SYMBOL_IS_ARGUMENT (symbol
));
145 sympy_is_constant (PyObject
*self
, void *closure
)
147 struct symbol
*symbol
= NULL
;
148 enum address_class
class;
150 SYMPY_REQUIRE_VALID (self
, symbol
);
152 class = SYMBOL_CLASS (symbol
);
154 return PyBool_FromLong (class == LOC_CONST
|| class == LOC_CONST_BYTES
);
158 sympy_is_function (PyObject
*self
, void *closure
)
160 struct symbol
*symbol
= NULL
;
161 enum address_class
class;
163 SYMPY_REQUIRE_VALID (self
, symbol
);
165 class = SYMBOL_CLASS (symbol
);
167 return PyBool_FromLong (class == LOC_BLOCK
);
171 sympy_is_variable (PyObject
*self
, void *closure
)
173 struct symbol
*symbol
= NULL
;
174 enum address_class
class;
176 SYMPY_REQUIRE_VALID (self
, symbol
);
178 class = SYMBOL_CLASS (symbol
);
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
));
186 /* Implementation of gdb.Symbol.needs_frame -> Boolean.
187 Returns true iff the symbol needs a frame for evaluation. */
190 sympy_needs_frame (PyObject
*self
, void *closure
)
192 struct symbol
*symbol
= NULL
;
193 volatile struct gdb_exception except
;
196 SYMPY_REQUIRE_VALID (self
, symbol
);
198 TRY_CATCH (except
, RETURN_MASK_ALL
)
200 result
= symbol_read_needs_frame (symbol
);
202 GDB_PY_HANDLE_EXCEPTION (except
);
209 /* Implementation of gdb.Symbol.line -> int.
210 Returns the line number at which the symbol was defined. */
213 sympy_line (PyObject
*self
, void *closure
)
215 struct symbol
*symbol
= NULL
;
217 SYMPY_REQUIRE_VALID (self
, symbol
);
219 return PyInt_FromLong (SYMBOL_LINE (symbol
));
222 /* Implementation of gdb.Symbol.is_valid (self) -> Boolean.
223 Returns True if this Symbol still exists in GDB. */
226 sympy_is_valid (PyObject
*self
, PyObject
*args
)
228 struct symbol
*symbol
= NULL
;
230 symbol
= symbol_object_to_symbol (self
);
237 /* Implementation of gdb.Symbol.value (self[, frame]) -> gdb.Value. Returns
238 the value of the symbol, or an error in various circumstances. */
241 sympy_value (PyObject
*self
, PyObject
*args
)
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
;
249 if (!PyArg_ParseTuple (args
, "|O", &frame_obj
))
252 if (frame_obj
!= NULL
&& !PyObject_TypeCheck (frame_obj
, &frame_object_type
))
254 PyErr_SetString (PyExc_TypeError
, "argument is not a frame");
258 SYMPY_REQUIRE_VALID (self
, symbol
);
259 if (SYMBOL_CLASS (symbol
) == LOC_TYPEDEF
)
261 PyErr_SetString (PyExc_TypeError
, "cannot get the value of a typedef");
265 TRY_CATCH (except
, RETURN_MASK_ALL
)
267 if (frame_obj
!= NULL
)
269 frame_info
= frame_object_to_frame_info (frame_obj
);
270 if (frame_info
== NULL
)
271 error (_("invalid frame"));
274 if (symbol_read_needs_frame (symbol
) && frame_info
== NULL
)
275 error (_("symbol requires a frame to compute its value"));
277 value
= read_var_value (symbol
, frame_info
);
279 GDB_PY_HANDLE_EXCEPTION (except
);
281 return value_to_value_object (value
);
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. */
290 set_symbol (symbol_object
*obj
, struct symbol
*symbol
)
292 obj
->symbol
= symbol
;
294 if (SYMBOL_SYMTAB (symbol
))
296 obj
->next
= objfile_data (SYMBOL_SYMTAB (symbol
)->objfile
,
297 sympy_objfile_data_key
);
300 obj
->next
->prev
= obj
;
301 set_objfile_data (SYMBOL_SYMTAB (symbol
)->objfile
,
302 sympy_objfile_data_key
, obj
);
308 /* Create a new symbol object (gdb.Symbol) that encapsulates the struct
309 symbol object from GDB. */
311 symbol_to_symbol_object (struct symbol
*sym
)
313 symbol_object
*sym_obj
;
315 sym_obj
= PyObject_New (symbol_object
, &symbol_object_type
);
317 set_symbol (sym_obj
, sym
);
319 return (PyObject
*) sym_obj
;
322 /* Return the symbol that is wrapped by this symbol object. */
324 symbol_object_to_symbol (PyObject
*obj
)
326 if (! PyObject_TypeCheck (obj
, &symbol_object_type
))
328 return ((symbol_object
*) obj
)->symbol
;
332 sympy_dealloc (PyObject
*obj
)
334 symbol_object
*sym_obj
= (symbol_object
*) obj
;
337 sym_obj
->prev
->next
= sym_obj
->next
;
338 else if (sym_obj
->symbol
&& SYMBOL_SYMTAB (sym_obj
->symbol
))
340 set_objfile_data (SYMBOL_SYMTAB (sym_obj
->symbol
)->objfile
,
341 sympy_objfile_data_key
, sym_obj
->next
);
344 sym_obj
->next
->prev
= sym_obj
->prev
;
345 sym_obj
->symbol
= NULL
;
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). */
355 gdbpy_lookup_symbol (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
357 int domain
= VAR_DOMAIN
;
358 struct field_of_this_result is_a_field_of_this
;
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
;
366 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "s|O!i", keywords
, &name
,
367 &block_object_type
, &block_obj
, &domain
))
371 block
= block_object_to_block (block_obj
);
374 struct frame_info
*selected_frame
;
375 volatile struct gdb_exception except
;
377 TRY_CATCH (except
, RETURN_MASK_ALL
)
379 selected_frame
= get_selected_frame (_("No frame selected."));
380 block
= get_frame_block (selected_frame
, NULL
);
382 GDB_PY_HANDLE_EXCEPTION (except
);
385 TRY_CATCH (except
, RETURN_MASK_ALL
)
387 symbol
= lookup_symbol (name
, block
, domain
, &is_a_field_of_this
);
389 GDB_PY_HANDLE_EXCEPTION (except
);
391 ret_tuple
= PyTuple_New (2);
397 sym_obj
= symbol_to_symbol_object (symbol
);
400 Py_DECREF (ret_tuple
);
409 PyTuple_SET_ITEM (ret_tuple
, 0, sym_obj
);
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
);
419 gdb.lookup_global_symbol (name [, domain]) -> symbol or None. */
422 gdbpy_lookup_global_symbol (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
424 int domain
= VAR_DOMAIN
;
426 static char *keywords
[] = { "name", "domain", NULL
};
427 struct symbol
*symbol
= NULL
;
429 volatile struct gdb_exception except
;
431 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "s|i", keywords
, &name
,
435 TRY_CATCH (except
, RETURN_MASK_ALL
)
437 symbol
= lookup_symbol_global (name
, NULL
, domain
);
439 GDB_PY_HANDLE_EXCEPTION (except
);
443 sym_obj
= symbol_to_symbol_object (symbol
);
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
462 del_objfile_symbols (struct objfile
*objfile
, void *datum
)
464 symbol_object
*obj
= datum
;
467 symbol_object
*next
= obj
->next
;
478 gdbpy_initialize_symbols (void)
480 if (PyType_Ready (&symbol_object_type
) < 0)
483 /* Register an objfile "free" callback so we can properly
484 invalidate symbol when an object file that is about to be
486 sympy_objfile_data_key
487 = register_objfile_data_with_cleanup (NULL
, del_objfile_symbols
);
489 if (PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_UNDEF", LOC_UNDEF
) < 0
490 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_CONST",
492 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_STATIC",
494 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REGISTER",
496 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_ARG",
498 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REF_ARG",
500 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_LOCAL",
502 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_TYPEDEF",
504 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_LABEL",
506 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_BLOCK",
508 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_CONST_BYTES",
510 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_UNRESOLVED",
512 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_OPTIMIZED_OUT",
513 LOC_OPTIMIZED_OUT
) < 0
514 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_COMPUTED",
516 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LOC_REGPARM_ADDR",
517 LOC_REGPARM_ADDR
) < 0
518 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_UNDEF_DOMAIN",
520 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_VAR_DOMAIN",
522 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_STRUCT_DOMAIN",
524 || PyModule_AddIntConstant (gdb_module
, "SYMBOL_LABEL_DOMAIN",
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",
534 return gdb_pymodule_addobject (gdb_module
, "Symbol",
535 (PyObject
*) &symbol_object_type
);
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).",
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 */
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 */
580 PyTypeObject symbol_object_type
= {
581 PyVarObject_HEAD_INIT (NULL
, 0)
582 "gdb.Symbol", /*tp_name*/
583 sizeof (symbol_object
), /*tp_basicsize*/
585 sympy_dealloc
, /*tp_dealloc*/
592 0, /*tp_as_sequence*/
596 sympy_str
, /*tp_str*/
600 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
601 "GDB symbol object", /*tp_doc */
604 0, /*tp_richcompare */
605 0, /*tp_weaklistoffset */
608 symbol_object_methods
, /*tp_methods */
610 symbol_object_getset
/*tp_getset */