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 */ 362