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