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