1/* Interface to C preprocessor macro tables for GDB. 2 Copyright (C) 2002, 2007 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 23struct obstack; 24struct 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. */ 73struct macro_table; 74 75 76/* A source file that participated in a compilation unit --- either a 77 main file, or an #included file. If a file is #included more than 78 once, the presence of the `included_from' and `included_at_line' 79 members means that we need to make one instance of this structure 80 for each #inclusion. Taken as a group, these structures form a 81 tree mapping the #inclusions that contributed to the compilation 82 unit, with the main source file as its root. 83 84 Beware --- not every source file mentioned in a compilation unit's 85 symtab structures will appear in the #inclusion tree! As of Oct 86 2002, GCC does record the effect of #line directives in the source 87 line info, but not in macro info. This means that GDB's symtabs 88 (built from the former, among other things) may mention filenames 89 that the #inclusion tree (built from the latter) doesn't have any 90 record of. See macroscope.c:sal_macro_scope for how to accomodate 91 this. 92 93 It's worth noting that libcpp has a simpler way of representing all 94 this, which we should consider switching to. It might even be 95 suitable for ordinary non-macro line number info. 96 97 Suppose you take your main source file, and after each line 98 containing an #include directive you insert the text of the 99 #included file. The result is a big file that pretty much 100 corresponds to the full text the compiler's going to see. There's 101 a one-to-one correspondence between lines in the big file and 102 per-inclusion lines in the source files. (Obviously, #include 103 directives that are #if'd out don't count. And you'll need to 104 append a newline to any file that doesn't end in one, to avoid 105 splicing the last #included line with the next line of the 106 #including file.) 107 108 Libcpp calls line numbers in this big imaginary file "logical line 109 numbers", and has a data structure called a "line map" that can map 110 logical line numbers onto actual source filenames and line numbers, 111 and also tell you the chain of #inclusions responsible for any 112 particular logical line number. Basically, this means you can pass 113 around a single line number and some kind of "compilation unit" 114 object and you get nice, unambiguous source code locations that 115 distinguish between multiple #inclusions of the same file, etc. 116 117 Pretty neat, huh? */ 118 119struct macro_source_file 120{ 121 122 /* The macro table for the compilation unit this source location is 123 a part of. */ 124 struct macro_table *table; 125 126 /* A source file --- possibly a header file. */ 127 const char *filename; 128 129 /* The location we were #included from, or zero if we are the 130 compilation unit's main source file. */ 131 struct macro_source_file *included_by; 132 133 /* If `included_from' is non-zero, the line number in that source 134 file at which we were included. */ 135 int included_at_line; 136 137 /* Head of a linked list of the source files #included by this file; 138 our children in the #inclusion tree. This list is sorted by its 139 elements' `included_at_line' values, which are unique. (The 140 macro splay tree's ordering function needs this property.) */ 141 struct macro_source_file *includes; 142 143 /* The next file #included by our `included_from' file; our sibling 144 in the #inclusion tree. */ 145 struct macro_source_file *next_included; 146}; 147 148 149/* Create a new, empty macro table. Allocate it in OBSTACK, or use 150 xmalloc if OBSTACK is zero. Use BCACHE to store all macro names, 151 arguments, definitions, and anything else that might be the same 152 amongst compilation units in an executable file; if BCACHE is zero, 153 don't cache these things. 154 155 Note that, if either OBSTACK or BCACHE are non-zero, then you 156 should only ever add information the macro table --- you should 157 never remove things from it. You'll get an error if you try. At 158 the moment, since we only provide obstacks and bcaches for macro 159 tables for symtabs, this restriction makes a nice sanity check. 160 Obstacks and bcaches are pretty much grow-only structures anyway. 161 However, if we find that it's occasionally useful to delete things 162 even from the symtab's tables, and the storage leak isn't a 163 problem, this restriction could be lifted. */ 164struct macro_table *new_macro_table (struct obstack *obstack, 165 struct bcache *bcache); 166 167 168/* Free TABLE, and any macro definitions, source file structures, 169 etc. it owns. This will raise an internal error if TABLE was 170 allocated on an obstack, or if it uses a bcache. */ 171void free_macro_table (struct macro_table *table); 172 173 174/* Set FILENAME as the main source file of TABLE. Return a source 175 file structure describing that file; if we record the #definition 176 of macros, or the #inclusion of other files into FILENAME, we'll 177 use that source file structure to indicate the context. 178 179 The "main source file" is the one that was given to the compiler; 180 all other source files that contributed to the compilation unit are 181 #included, directly or indirectly, from this one. 182 183 The macro table makes its own copy of FILENAME; the caller is 184 responsible for freeing FILENAME when it is no longer needed. */ 185struct macro_source_file *macro_set_main (struct macro_table *table, 186 const char *filename); 187 188 189/* Return the main source file of the macro table TABLE. */ 190struct macro_source_file *macro_main (struct macro_table *table); 191 192 193/* Record a #inclusion. 194 Record in SOURCE's macro table that, at line number LINE in SOURCE, 195 we #included the file INCLUDED. Return a source file structure we 196 can use for symbols #defined or files #included into that. If we've 197 already created a source file structure for this #inclusion, return 198 the same structure we created last time. 199 200 The first line of the source file has a line number of 1, not 0. 201 202 The macro table makes its own copy of INCLUDED; the caller is 203 responsible for freeing INCLUDED when it is no longer needed. */ 204struct macro_source_file *macro_include (struct macro_source_file *source, 205 int line, 206 const char *included); 207 208 209/* Find any source file structure for a file named NAME, either 210 included into SOURCE, or SOURCE itself. Return zero if we have 211 none. NAME is only the final portion of the filename, not the full 212 path. e.g., `stdio.h', not `/usr/include/stdio.h'. If NAME 213 appears more than once in the inclusion tree, return the 214 least-nested inclusion --- the one closest to the main source file. */ 215struct macro_source_file *(macro_lookup_inclusion 216 (struct macro_source_file *source, 217 const char *name)); 218 219 220/* Record an object-like #definition (i.e., one with no parameter list). 221 Record in SOURCE's macro table that, at line number LINE in SOURCE, 222 we #defined a preprocessor symbol named NAME, whose replacement 223 string is REPLACEMENT. This function makes copies of NAME and 224 REPLACEMENT; the caller is responsible for freeing them. */ 225void macro_define_object (struct macro_source_file *source, int line, 226 const char *name, const char *replacement); 227 228 229/* Record an function-like #definition (i.e., one with a parameter list). 230 231 Record in SOURCE's macro table that, at line number LINE in SOURCE, 232 we #defined a preprocessor symbol named NAME, with ARGC arguments 233 whose names are given in ARGV, whose replacement string is REPLACEMENT. If 234 the macro takes a variable number of arguments, then ARGC should be 235 one greater than the number of named arguments, and ARGV[ARGC-1] 236 should be the string "...". This function makes its own copies of 237 NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing 238 them. */ 239void macro_define_function (struct macro_source_file *source, int line, 240 const char *name, int argc, const char **argv, 241 const char *replacement); 242 243 244/* Record an #undefinition. 245 Record in SOURCE's macro table that, at line number LINE in SOURCE, 246 we removed the definition for the preprocessor symbol named NAME. */ 247void macro_undef (struct macro_source_file *source, int line, 248 const char *name); 249 250 251/* Different kinds of macro definitions. */ 252enum macro_kind 253{ 254 macro_object_like, 255 macro_function_like 256}; 257 258 259/* A preprocessor symbol definition. */ 260struct macro_definition 261{ 262 /* The table this definition lives in. */ 263 struct macro_table *table; 264 265 /* What kind of macro it is. */ 266 enum macro_kind kind; 267 268 /* If `kind' is `macro_function_like', the number of arguments it 269 takes, and their names. The names, and the array of pointers to 270 them, are in the table's bcache, if it has one. */ 271 int argc; 272 const char * const *argv; 273 274 /* The replacement string (body) of the macro. This is in the 275 table's bcache, if it has one. */ 276 const char *replacement; 277}; 278 279 280/* Return a pointer to the macro definition for NAME in scope at line 281 number LINE of SOURCE. If LINE is -1, return the definition in 282 effect at the end of the file. The macro table owns the structure; 283 the caller need not free it. Return zero if NAME is not #defined 284 at that point. */ 285struct macro_definition *(macro_lookup_definition 286 (struct macro_source_file *source, 287 int line, const char *name)); 288 289 290/* Return the source location of the definition for NAME in scope at 291 line number LINE of SOURCE. Set *DEFINITION_LINE to the line 292 number of the definition, and return a source file structure for 293 the file. Return zero if NAME has no definition in scope at that 294 point, and leave *DEFINITION_LINE unchanged. */ 295struct macro_source_file *(macro_definition_location 296 (struct macro_source_file *source, 297 int line, 298 const char *name, 299 int *definition_line)); 300 301 302#endif /* MACROTAB_H */ 303