1 /* Interface to C preprocessor macro tables for GDB. 2 Copyright 2002 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 2 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, write to the Free Software 19 Foundation, Inc., 59 Temple Place - Suite 330, 20 Boston, MA 02111-1307, USA. */ 21 22 #ifndef MACROTAB_H 23 #define MACROTAB_H 24 25 struct obstack; 26 struct bcache; 27 28 /* How do we represent a source location? I mean, how should we 29 represent them within GDB; the user wants to use all sorts of 30 ambiguous abbreviations, like "break 32" and "break foo.c:32" 31 ("foo.c" may have been #included into several compilation units), 32 but what do we disambiguate those things to? 33 34 - Answer 1: "Filename and line number." (Or column number, if 35 you're picky.) That's not quite good enough. For example, the 36 same source file can be #included into several different 37 compilation units --- which #inclusion do you mean? 38 39 - Answer 2: "Compilation unit, filename, and line number." This is 40 a pretty good answer; GDB's `struct symtab_and_line' basically 41 embodies this representation. But it's still ambiguous; what if a 42 given compilation unit #includes the same file twice --- how can I 43 set a breakpoint on line 12 of the fifth #inclusion of "foo.c"? 44 45 - Answer 3: "Compilation unit, chain of #inclusions, and line 46 number." This is analogous to the way GCC reports errors in 47 #include files: 48 49 $ gcc -c base.c 50 In file included from header2.h:8, 51 from header1.h:3, 52 from base.c:5: 53 header3.h:1: parse error before ')' token 54 $ 55 56 GCC tells you exactly what path of #inclusions led you to the 57 problem. It gives you complete information, in a way that the 58 following would not: 59 60 $ gcc -c base.c 61 header3.h:1: parse error before ')' token 62 $ 63 64 Converting all of GDB to use this is a big task, and I'm not really 65 suggesting it should be a priority. But this module's whole 66 purpose is to maintain structures describing the macro expansion 67 process, so I think it's appropriate for us to take a little care 68 to do that in a complete fashion. 69 70 In this interface, the first line of a file is numbered 1, not 0. 71 This is the same convention the rest of GDB uses. */ 72 73 74 /* A table of all the macro definitions for a given compilation unit. */ 75 struct macro_table; 76 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. */ 129 const char *filename; 130 131 /* The location we were #included from, or zero if we are the 132 compilation unit's main source file. */ 133 struct macro_source_file *included_by; 134 135 /* If `included_from' is non-zero, the line number in that source 136 file at which we were included. */ 137 int included_at_line; 138 139 /* Head of a linked list of the source files #included by this file; 140 our children in the #inclusion tree. This list is sorted by its 141 elements' `included_at_line' values, which are unique. (The 142 macro splay tree's ordering function needs this property.) */ 143 struct macro_source_file *includes; 144 145 /* The next file #included by our `included_from' file; our sibling 146 in the #inclusion tree. */ 147 struct macro_source_file *next_included; 148 }; 149 150 151 /* Create a new, empty macro table. Allocate it in OBSTACK, or use 152 xmalloc if OBSTACK is zero. Use BCACHE to store all macro names, 153 arguments, definitions, and anything else that might be the same 154 amongst compilation units in an executable file; if BCACHE is zero, 155 don't cache these things. 156 157 Note that, if either OBSTACK or BCACHE are non-zero, then you 158 should only ever add information the macro table --- you should 159 never remove things from it. You'll get an error if you try. At 160 the moment, since we only provide obstacks and bcaches for macro 161 tables for symtabs, this restriction makes a nice sanity check. 162 Obstacks and bcaches are pretty much grow-only structures anyway. 163 However, if we find that it's occasionally useful to delete things 164 even from the symtab's tables, and the storage leak isn't a 165 problem, this restriction could be lifted. */ 166 struct macro_table *new_macro_table (struct obstack *obstack, 167 struct bcache *bcache); 168 169 170 /* Free TABLE, and any macro definitions, source file structures, 171 etc. it owns. This will raise an internal error if TABLE was 172 allocated on an obstack, or if it uses a bcache. */ 173 void free_macro_table (struct macro_table *table); 174 175 176 /* Set FILENAME as the main source file of TABLE. Return a source 177 file structure describing that file; if we record the #definition 178 of macros, or the #inclusion of other files into FILENAME, we'll 179 use that source file structure to indicate the context. 180 181 The "main source file" is the one that was given to the compiler; 182 all other source files that contributed to the compilation unit are 183 #included, directly or indirectly, from this one. 184 185 The macro table makes its own copy of FILENAME; the caller is 186 responsible for freeing FILENAME when it is no longer needed. */ 187 struct macro_source_file *macro_set_main (struct macro_table *table, 188 const char *filename); 189 190 191 /* Return the main source file of the macro table TABLE. */ 192 struct macro_source_file *macro_main (struct macro_table *table); 193 194 195 /* Record a #inclusion. 196 Record in SOURCE's macro table that, at line number LINE in SOURCE, 197 we #included the file INCLUDED. Return a source file structure we 198 can use for symbols #defined or files #included into that. If we've 199 already created a source file structure for this #inclusion, return 200 the same structure we created last time. 201 202 The first line of the source file has a line number of 1, not 0. 203 204 The macro table makes its own copy of INCLUDED; the caller is 205 responsible for freeing INCLUDED when it is no longer needed. */ 206 struct macro_source_file *macro_include (struct macro_source_file *source, 207 int line, 208 const char *included); 209 210 211 /* Find any source file structure for a file named NAME, either 212 included into SOURCE, or SOURCE itself. Return zero if we have 213 none. NAME is only the final portion of the filename, not the full 214 path. e.g., `stdio.h', not `/usr/include/stdio.h'. If NAME 215 appears more than once in the inclusion tree, return the 216 least-nested inclusion --- the one closest to the main source file. */ 217 struct macro_source_file *(macro_lookup_inclusion 218 (struct macro_source_file *source, 219 const char *name)); 220 221 222 /* Record an object-like #definition (i.e., one with no parameter list). 223 Record in SOURCE's macro table that, at line number LINE in SOURCE, 224 we #defined a preprocessor symbol named NAME, whose replacement 225 string is REPLACEMENT. This function makes copies of NAME and 226 REPLACEMENT; the caller is responsible for freeing them. */ 227 void macro_define_object (struct macro_source_file *source, int line, 228 const char *name, const char *replacement); 229 230 231 /* Record an function-like #definition (i.e., one with a parameter list). 232 233 Record in SOURCE's macro table that, at line number LINE in SOURCE, 234 we #defined a preprocessor symbol named NAME, with ARGC arguments 235 whose names are given in ARGV, whose replacement string is REPLACEMENT. If 236 the macro takes a variable number of arguments, then ARGC should be 237 one greater than the number of named arguments, and ARGV[ARGC-1] 238 should be the string "...". This function makes its own copies of 239 NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing 240 them. */ 241 void macro_define_function (struct macro_source_file *source, int line, 242 const char *name, int argc, const char **argv, 243 const char *replacement); 244 245 246 /* Record an #undefinition. 247 Record in SOURCE's macro table that, at line number LINE in SOURCE, 248 we removed the definition for the preprocessor symbol named NAME. */ 249 void macro_undef (struct macro_source_file *source, int line, 250 const char *name); 251 252 253 /* Different kinds of macro definitions. */ 254 enum macro_kind 255 { 256 macro_object_like, 257 macro_function_like 258 }; 259 260 261 /* A preprocessor symbol definition. */ 262 struct macro_definition 263 { 264 /* The table this definition lives in. */ 265 struct macro_table *table; 266 267 /* What kind of macro it is. */ 268 enum macro_kind kind; 269 270 /* If `kind' is `macro_function_like', the number of arguments it 271 takes, and their names. The names, and the array of pointers to 272 them, are in the table's bcache, if it has one. */ 273 int argc; 274 const char * const *argv; 275 276 /* The replacement string (body) of the macro. This is in the 277 table's bcache, if it has one. */ 278 const char *replacement; 279 }; 280 281 282 /* Return a pointer to the macro definition for NAME in scope at line 283 number LINE of SOURCE. If LINE is -1, return the definition in 284 effect at the end of the file. The macro table owns the structure; 285 the caller need not free it. Return zero if NAME is not #defined 286 at that point. */ 287 struct macro_definition *(macro_lookup_definition 288 (struct macro_source_file *source, 289 int line, const char *name)); 290 291 292 /* Return the source location of the definition for NAME in scope at 293 line number LINE of SOURCE. Set *DEFINITION_LINE to the line 294 number of the definition, and return a source file structure for 295 the file. Return zero if NAME has no definition in scope at that 296 point, and leave *DEFINITION_LINE unchanged. */ 297 struct macro_source_file *(macro_definition_location 298 (struct macro_source_file *source, 299 int line, 300 const char *name, 301 int *definition_line)); 302 303 304 #endif /* MACROTAB_H */ 305