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