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