| 1 | /* Interface to C preprocessor macro tables for GDB. |
| 2 | Copyright (C) 2002-2019 Free Software Foundation, Inc. |
| 3 | Contributed by Red Hat, 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 | #ifndef MACROTAB_H |
| 21 | #define MACROTAB_H |
| 22 | |
| 23 | #include "common/function-view.h" |
| 24 | |
| 25 | struct obstack; |
| 26 | struct bcache; |
| 27 | struct compunit_symtab; |
| 28 | |
| 29 | /* How do we represent a source location? I mean, how should we |
| 30 | represent them within GDB; the user wants to use all sorts of |
| 31 | ambiguous abbreviations, like "break 32" and "break foo.c:32" |
| 32 | ("foo.c" may have been #included into several compilation units), |
| 33 | but what do we disambiguate those things to? |
| 34 | |
| 35 | - Answer 1: "Filename and line number." (Or column number, if |
| 36 | you're picky.) That's not quite good enough. For example, the |
| 37 | same source file can be #included into several different |
| 38 | compilation units --- which #inclusion do you mean? |
| 39 | |
| 40 | - Answer 2: "Compilation unit, filename, and line number." This is |
| 41 | a pretty good answer; GDB's `struct symtab_and_line' basically |
| 42 | embodies this representation. But it's still ambiguous; what if a |
| 43 | given compilation unit #includes the same file twice --- how can I |
| 44 | set a breakpoint on line 12 of the fifth #inclusion of "foo.c"? |
| 45 | |
| 46 | - Answer 3: "Compilation unit, chain of #inclusions, and line |
| 47 | number." This is analogous to the way GCC reports errors in |
| 48 | #include files: |
| 49 | |
| 50 | $ gcc -c base.c |
| 51 | In file included from header2.h:8, |
| 52 | from header1.h:3, |
| 53 | from base.c:5: |
| 54 | header3.h:1: parse error before ')' token |
| 55 | $ |
| 56 | |
| 57 | GCC tells you exactly what path of #inclusions led you to the |
| 58 | problem. It gives you complete information, in a way that the |
| 59 | following would not: |
| 60 | |
| 61 | $ gcc -c base.c |
| 62 | header3.h:1: parse error before ')' token |
| 63 | $ |
| 64 | |
| 65 | Converting all of GDB to use this is a big task, and I'm not really |
| 66 | suggesting it should be a priority. But this module's whole |
| 67 | purpose is to maintain structures describing the macro expansion |
| 68 | process, so I think it's appropriate for us to take a little care |
| 69 | to do that in a complete fashion. |
| 70 | |
| 71 | In this interface, the first line of a file is numbered 1, not 0. |
| 72 | This is the same convention the rest of GDB uses. */ |
| 73 | |
| 74 | |
| 75 | /* A table of all the macro definitions for a given compilation unit. */ |
| 76 | struct macro_table; |
| 77 | |
| 78 | /* The definition of a single macro. */ |
| 79 | struct macro_definition; |
| 80 | |
| 81 | /* A source file that participated in a compilation unit --- either a |
| 82 | main file, or an #included file. If a file is #included more than |
| 83 | once, the presence of the `included_from' and `included_at_line' |
| 84 | members means that we need to make one instance of this structure |
| 85 | for each #inclusion. Taken as a group, these structures form a |
| 86 | tree mapping the #inclusions that contributed to the compilation |
| 87 | unit, with the main source file as its root. |
| 88 | |
| 89 | Beware --- not every source file mentioned in a compilation unit's |
| 90 | symtab structures will appear in the #inclusion tree! As of Oct |
| 91 | 2002, GCC does record the effect of #line directives in the source |
| 92 | line info, but not in macro info. This means that GDB's symtabs |
| 93 | (built from the former, among other things) may mention filenames |
| 94 | that the #inclusion tree (built from the latter) doesn't have any |
| 95 | record of. See macroscope.c:sal_macro_scope for how to accomodate |
| 96 | this. |
| 97 | |
| 98 | It's worth noting that libcpp has a simpler way of representing all |
| 99 | this, which we should consider switching to. It might even be |
| 100 | suitable for ordinary non-macro line number info. |
| 101 | |
| 102 | Suppose you take your main source file, and after each line |
| 103 | containing an #include directive you insert the text of the |
| 104 | #included file. The result is a big file that pretty much |
| 105 | corresponds to the full text the compiler's going to see. There's |
| 106 | a one-to-one correspondence between lines in the big file and |
| 107 | per-inclusion lines in the source files. (Obviously, #include |
| 108 | directives that are #if'd out don't count. And you'll need to |
| 109 | append a newline to any file that doesn't end in one, to avoid |
| 110 | splicing the last #included line with the next line of the |
| 111 | #including file.) |
| 112 | |
| 113 | Libcpp calls line numbers in this big imaginary file "logical line |
| 114 | numbers", and has a data structure called a "line map" that can map |
| 115 | logical line numbers onto actual source filenames and line numbers, |
| 116 | and also tell you the chain of #inclusions responsible for any |
| 117 | particular logical line number. Basically, this means you can pass |
| 118 | around a single line number and some kind of "compilation unit" |
| 119 | object and you get nice, unambiguous source code locations that |
| 120 | distinguish between multiple #inclusions of the same file, etc. |
| 121 | |
| 122 | Pretty neat, huh? */ |
| 123 | |
| 124 | struct macro_source_file |
| 125 | { |
| 126 | |
| 127 | /* The macro table for the compilation unit this source location is |
| 128 | a part of. */ |
| 129 | struct macro_table *table; |
| 130 | |
| 131 | /* A source file --- possibly a header file. This filename is relative to |
| 132 | the compilation directory (table->comp_dir), it exactly matches the |
| 133 | symtab->filename content. */ |
| 134 | const char *filename; |
| 135 | |
| 136 | /* The location we were #included from, or zero if we are the |
| 137 | compilation unit's main source file. */ |
| 138 | struct macro_source_file *included_by; |
| 139 | |
| 140 | /* If `included_from' is non-zero, the line number in that source |
| 141 | file at which we were included. */ |
| 142 | int included_at_line; |
| 143 | |
| 144 | /* Head of a linked list of the source files #included by this file; |
| 145 | our children in the #inclusion tree. This list is sorted by its |
| 146 | elements' `included_at_line' values, which are unique. (The |
| 147 | macro splay tree's ordering function needs this property.) */ |
| 148 | struct macro_source_file *includes; |
| 149 | |
| 150 | /* The next file #included by our `included_from' file; our sibling |
| 151 | in the #inclusion tree. */ |
| 152 | struct macro_source_file *next_included; |
| 153 | }; |
| 154 | |
| 155 | |
| 156 | /* Create a new, empty macro table. Allocate it in OBSTACK, or use |
| 157 | xmalloc if OBSTACK is zero. Use BCACHE to store all macro names, |
| 158 | arguments, definitions, and anything else that might be the same |
| 159 | amongst compilation units in an executable file; if BCACHE is zero, |
| 160 | don't cache these things. CUST is a pointer to the containing |
| 161 | compilation unit, or NULL if there isn't one. |
| 162 | |
| 163 | Note that, if either OBSTACK or BCACHE are non-zero, then removing |
| 164 | information from the table may leak memory. Neither obstacks nor |
| 165 | bcaches really allow you to remove information, so although we can |
| 166 | update the data structure to record the change, we can't free the |
| 167 | old data. At the moment, since we only provide obstacks and |
| 168 | bcaches for macro tables for symtabs, this isn't a problem; only |
| 169 | odd debugging information makes a definition and then deletes it at |
| 170 | the same source location (although 'gcc -DFOO -UFOO -DFOO=2' does |
| 171 | do that in GCC 4.1.2.). */ |
| 172 | struct macro_table *new_macro_table (struct obstack *obstack, |
| 173 | struct bcache *bcache, |
| 174 | struct compunit_symtab *cust); |
| 175 | |
| 176 | |
| 177 | /* Free TABLE, and any macro definitions, source file structures, |
| 178 | etc. it owns. This will raise an internal error if TABLE was |
| 179 | allocated on an obstack, or if it uses a bcache. */ |
| 180 | void free_macro_table (struct macro_table *table); |
| 181 | |
| 182 | |
| 183 | /* Set FILENAME as the main source file of TABLE. Return a source |
| 184 | file structure describing that file; if we record the #definition |
| 185 | of macros, or the #inclusion of other files into FILENAME, we'll |
| 186 | use that source file structure to indicate the context. |
| 187 | |
| 188 | The "main source file" is the one that was given to the compiler; |
| 189 | all other source files that contributed to the compilation unit are |
| 190 | #included, directly or indirectly, from this one. |
| 191 | |
| 192 | The macro table makes its own copy of FILENAME; the caller is |
| 193 | responsible for freeing FILENAME when it is no longer needed. */ |
| 194 | struct macro_source_file *macro_set_main (struct macro_table *table, |
| 195 | const char *filename); |
| 196 | |
| 197 | |
| 198 | /* Return the main source file of the macro table TABLE. */ |
| 199 | struct macro_source_file *macro_main (struct macro_table *table); |
| 200 | |
| 201 | /* Mark the macro table TABLE so that macros defined in this table can |
| 202 | be redefined without error. Note that it invalid to call this if |
| 203 | TABLE is allocated on an obstack. */ |
| 204 | void macro_allow_redefinitions (struct macro_table *table); |
| 205 | |
| 206 | |
| 207 | /* Record a #inclusion. |
| 208 | Record in SOURCE's macro table that, at line number LINE in SOURCE, |
| 209 | we #included the file INCLUDED. Return a source file structure we |
| 210 | can use for symbols #defined or files #included into that. If we've |
| 211 | already created a source file structure for this #inclusion, return |
| 212 | the same structure we created last time. |
| 213 | |
| 214 | The first line of the source file has a line number of 1, not 0. |
| 215 | |
| 216 | The macro table makes its own copy of INCLUDED; the caller is |
| 217 | responsible for freeing INCLUDED when it is no longer needed. */ |
| 218 | struct macro_source_file *macro_include (struct macro_source_file *source, |
| 219 | int line, |
| 220 | const char *included); |
| 221 | |
| 222 | /* Define any special macros, like __FILE__ or __LINE__. This should |
| 223 | be called once, on the main source file. */ |
| 224 | |
| 225 | void macro_define_special (struct macro_table *table); |
| 226 | |
| 227 | /* Find any source file structure for a file named NAME, either |
| 228 | included into SOURCE, or SOURCE itself. Return zero if we have |
| 229 | none. NAME is only the final portion of the filename, not the full |
| 230 | path. e.g., `stdio.h', not `/usr/include/stdio.h'. If NAME |
| 231 | appears more than once in the inclusion tree, return the |
| 232 | least-nested inclusion --- the one closest to the main source file. */ |
| 233 | struct macro_source_file *macro_lookup_inclusion |
| 234 | (struct macro_source_file *source, |
| 235 | const char *name); |
| 236 | |
| 237 | |
| 238 | /* Record an object-like #definition (i.e., one with no parameter list). |
| 239 | Record in SOURCE's macro table that, at line number LINE in SOURCE, |
| 240 | we #defined a preprocessor symbol named NAME, whose replacement |
| 241 | string is REPLACEMENT. This function makes copies of NAME and |
| 242 | REPLACEMENT; the caller is responsible for freeing them. */ |
| 243 | void macro_define_object (struct macro_source_file *source, int line, |
| 244 | const char *name, const char *replacement); |
| 245 | |
| 246 | |
| 247 | /* Record an function-like #definition (i.e., one with a parameter list). |
| 248 | |
| 249 | Record in SOURCE's macro table that, at line number LINE in SOURCE, |
| 250 | we #defined a preprocessor symbol named NAME, with ARGC arguments |
| 251 | whose names are given in ARGV, whose replacement string is REPLACEMENT. If |
| 252 | the macro takes a variable number of arguments, then ARGC should be |
| 253 | one greater than the number of named arguments, and ARGV[ARGC-1] |
| 254 | should be the string "...". This function makes its own copies of |
| 255 | NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing |
| 256 | them. */ |
| 257 | void macro_define_function (struct macro_source_file *source, int line, |
| 258 | const char *name, int argc, const char **argv, |
| 259 | const char *replacement); |
| 260 | |
| 261 | |
| 262 | /* Record an #undefinition. |
| 263 | Record in SOURCE's macro table that, at line number LINE in SOURCE, |
| 264 | we removed the definition for the preprocessor symbol named NAME. */ |
| 265 | void macro_undef (struct macro_source_file *source, int line, |
| 266 | const char *name); |
| 267 | |
| 268 | /* Different kinds of macro definitions. */ |
| 269 | enum macro_kind |
| 270 | { |
| 271 | macro_object_like, |
| 272 | macro_function_like |
| 273 | }; |
| 274 | |
| 275 | /* Different kinds of special macros. */ |
| 276 | |
| 277 | enum macro_special_kind |
| 278 | { |
| 279 | /* Ordinary. */ |
| 280 | macro_ordinary, |
| 281 | /* The special macro __FILE__. */ |
| 282 | macro_FILE, |
| 283 | /* The special macro __LINE__. */ |
| 284 | macro_LINE |
| 285 | }; |
| 286 | |
| 287 | /* A preprocessor symbol definition. */ |
| 288 | struct macro_definition |
| 289 | { |
| 290 | /* The table this definition lives in. */ |
| 291 | struct macro_table *table; |
| 292 | |
| 293 | /* What kind of macro it is. */ |
| 294 | ENUM_BITFIELD (macro_kind) kind : 1; |
| 295 | |
| 296 | /* If `kind' is `macro_function_like', the number of arguments it |
| 297 | takes, and their names. The names, and the array of pointers to |
| 298 | them, are in the table's bcache, if it has one. If `kind' is |
| 299 | `macro_object_like', then this is actually a `macro_special_kind' |
| 300 | describing the macro. */ |
| 301 | int argc : 30; |
| 302 | const char * const *argv; |
| 303 | |
| 304 | /* The replacement string (body) of the macro. For ordinary macros, |
| 305 | this is in the table's bcache, if it has one. For special macros |
| 306 | like __FILE__, this value is only valid until the next use of any |
| 307 | special macro definition; that is, it is reset each time any |
| 308 | special macro is looked up or iterated over. */ |
| 309 | const char *replacement; |
| 310 | }; |
| 311 | |
| 312 | |
| 313 | /* Return a pointer to the macro definition for NAME in scope at line |
| 314 | number LINE of SOURCE. If LINE is -1, return the definition in |
| 315 | effect at the end of the file. The macro table owns the structure; |
| 316 | the caller need not free it. Return zero if NAME is not #defined |
| 317 | at that point. */ |
| 318 | struct macro_definition *macro_lookup_definition |
| 319 | (struct macro_source_file *source, |
| 320 | int line, const char *name); |
| 321 | |
| 322 | |
| 323 | /* Return the source location of the definition for NAME in scope at |
| 324 | line number LINE of SOURCE. Set *DEFINITION_LINE to the line |
| 325 | number of the definition, and return a source file structure for |
| 326 | the file. Return zero if NAME has no definition in scope at that |
| 327 | point, and leave *DEFINITION_LINE unchanged. */ |
| 328 | struct macro_source_file *macro_definition_location |
| 329 | (struct macro_source_file *source, |
| 330 | int line, |
| 331 | const char *name, |
| 332 | int *definition_line); |
| 333 | |
| 334 | /* Prototype for a callback callable when walking a macro table. NAME |
| 335 | is the name of the macro, and DEFINITION is the definition. SOURCE |
| 336 | is the file at the start of the include path, and LINE is the line |
| 337 | number of the SOURCE file where the macro was defined. */ |
| 338 | typedef void (macro_callback_fn) (const char *name, |
| 339 | const struct macro_definition *definition, |
| 340 | struct macro_source_file *source, |
| 341 | int line); |
| 342 | |
| 343 | /* Call the callable FN for each macro in the macro table TABLE. */ |
| 344 | void macro_for_each (struct macro_table *table, |
| 345 | gdb::function_view<macro_callback_fn> fn); |
| 346 | |
| 347 | /* Call FN for each macro that is visible in a given scope. The scope |
| 348 | is represented by FILE and LINE. */ |
| 349 | void macro_for_each_in_scope (struct macro_source_file *file, int line, |
| 350 | gdb::function_view<macro_callback_fn> fn); |
| 351 | |
| 352 | /* Return FILE->filename with possibly prepended compilation directory name. |
| 353 | This is raw concatenation without the "set substitute-path" and gdb_realpath |
| 354 | applications done by symtab_to_fullname. |
| 355 | |
| 356 | THis function ignores the "set filename-display" setting. Its default |
| 357 | setting is "relative" which is backward compatible but the former behavior |
| 358 | of macro filenames printing was "absolute". */ |
| 359 | extern std::string macro_source_fullname (struct macro_source_file *file); |
| 360 | |
| 361 | #endif /* MACROTAB_H */ |