macrotab.h revision 130804
1229997Sken/* Interface to C preprocessor macro tables for GDB. 2229997Sken Copyright 2002 Free Software Foundation, Inc. 3229997Sken Contributed by Red Hat, Inc. 4229997Sken 5229997Sken This file is part of GDB. 6229997Sken 7229997Sken This program is free software; you can redistribute it and/or modify 8229997Sken it under the terms of the GNU General Public License as published by 9229997Sken the Free Software Foundation; either version 2 of the License, or 10229997Sken (at your option) any later version. 11229997Sken 12229997Sken This program is distributed in the hope that it will be useful, 13229997Sken but WITHOUT ANY WARRANTY; without even the implied warranty of 14229997Sken MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15229997Sken GNU General Public License for more details. 16229997Sken 17229997Sken You should have received a copy of the GNU General Public License 18229997Sken along with this program; if not, write to the Free Software 19229997Sken Foundation, Inc., 59 Temple Place - Suite 330, 20229997Sken Boston, MA 02111-1307, USA. */ 21229997Sken 22229997Sken#ifndef MACROTAB_H 23229997Sken#define MACROTAB_H 24229997Sken 25229997Skenstruct obstack; 26229997Skenstruct bcache; 27229997Sken 28229997Sken/* How do we represent a source location? I mean, how should we 29229997Sken represent them within GDB; the user wants to use all sorts of 30229997Sken ambiguous abbreviations, like "break 32" and "break foo.c:32" 31229997Sken ("foo.c" may have been #included into several compilation units), 32229997Sken but what do we disambiguate those things to? 33229997Sken 34229997Sken - Answer 1: "Filename and line number." (Or column number, if 35229997Sken you're picky.) That's not quite good enough. For example, the 36229997Sken same source file can be #included into several different 37229997Sken compilation units --- which #inclusion do you mean? 38229997Sken 39229997Sken - Answer 2: "Compilation unit, filename, and line number." This is 40229997Sken a pretty good answer; GDB's `struct symtab_and_line' basically 41229997Sken embodies this representation. But it's still ambiguous; what if a 42229997Sken given compilation unit #includes the same file twice --- how can I 43229997Sken set a breakpoint on line 12 of the fifth #inclusion of "foo.c"? 44229997Sken 45229997Sken - Answer 3: "Compilation unit, chain of #inclusions, and line 46229997Sken number." This is analogous to the way GCC reports errors in 47229997Sken #include files: 48229997Sken 49229997Sken $ gcc -c base.c 50229997Sken In file included from header2.h:8, 51229997Sken from header1.h:3, 52229997Sken from base.c:5: 53229997Sken header3.h:1: parse error before ')' token 54229997Sken $ 55229997Sken 56229997Sken GCC tells you exactly what path of #inclusions led you to the 57229997Sken problem. It gives you complete information, in a way that the 58229997Sken following would not: 59229997Sken 60229997Sken $ gcc -c base.c 61229997Sken header3.h:1: parse error before ')' token 62229997Sken $ 63229997Sken 64229997Sken Converting all of GDB to use this is a big task, and I'm not really 65229997Sken suggesting it should be a priority. But this module's whole 66229997Sken purpose is to maintain structures describing the macro expansion 67229997Sken process, so I think it's appropriate for us to take a little care 68229997Sken to do that in a complete fashion. 69229997Sken 70229997Sken In this interface, the first line of a file is numbered 1, not 0. 71229997Sken This is the same convention the rest of GDB uses. */ 72229997Sken 73229997Sken 74229997Sken/* A table of all the macro definitions for a given compilation unit. */ 75229997Skenstruct macro_table; 76229997Sken 77275878Smav 78229997Sken/* A source file that participated in a compilation unit --- either a 79229997Sken main file, or an #included file. If a file is #included more than 80275878Smav once, the presence of the `included_from' and `included_at_line' 81229997Sken members means that we need to make one instance of this structure 82229997Sken for each #inclusion. Taken as a group, these structures form a 83229997Sken tree mapping the #inclusions that contributed to the compilation 84229997Sken unit, with the main source file as its root. 85229997Sken 86229997Sken Beware --- not every source file mentioned in a compilation unit's 87229997Sken symtab structures will appear in the #inclusion tree! As of Oct 88229997Sken 2002, GCC does record the effect of #line directives in the source 89229997Sken line info, but not in macro info. This means that GDB's symtabs 90229997Sken (built from the former, among other things) may mention filenames 91268677Smav that the #inclusion tree (built from the latter) doesn't have any 92229997Sken record of. See macroscope.c:sal_macro_scope for how to accomodate 93229997Sken this. 94229997Sken 95229997Sken It's worth noting that libcpp has a simpler way of representing all 96229997Sken this, which we should consider switching to. It might even be 97272630Smav suitable for ordinary non-macro line number info. 98229997Sken 99272630Smav Suppose you take your main source file, and after each line 100275895Smav containing an #include directive you insert the text of the 101229997Sken #included file. The result is a big file that pretty much 102229997Sken corresponds to the full text the compiler's going to see. There's 103229997Sken a one-to-one correspondence between lines in the big file and 104229997Sken per-inclusion lines in the source files. (Obviously, #include 105229997Sken directives that are #if'd out don't count. And you'll need to 106229997Sken append a newline to any file that doesn't end in one, to avoid 107229997Sken splicing the last #included line with the next line of the 108229997Sken #including file.) 109229997Sken 110229997Sken Libcpp calls line numbers in this big imaginary file "logical line 111229997Sken numbers", and has a data structure called a "line map" that can map 112229997Sken logical line numbers onto actual source filenames and line numbers, 113229997Sken and also tell you the chain of #inclusions responsible for any 114229997Sken particular logical line number. Basically, this means you can pass 115229997Sken around a single line number and some kind of "compilation unit" 116229997Sken object and you get nice, unambiguous source code locations that 117229997Sken distinguish between multiple #inclusions of the same file, etc. 118229997Sken 119229997Sken Pretty neat, huh? */ 120268674Smav 121229997Skenstruct macro_source_file 122229997Sken{ 123229997Sken 124229997Sken /* The macro table for the compilation unit this source location is 125229997Sken a part of. */ 126229997Sken struct macro_table *table; 127274003Smav 128229997Sken /* A source file --- possibly a header file. */ 129229997Sken const char *filename; 130229997Sken 131229997Sken /* The location we were #included from, or zero if we are the 132229997Sken compilation unit's main source file. */ 133229997Sken struct macro_source_file *included_by; 134229997Sken 135268674Smav /* If `included_from' is non-zero, the line number in that source 136268674Smav file at which we were included. */ 137229997Sken int included_at_line; 138229997Sken 139229997Sken /* Head of a linked list of the source files #included by this file; 140229997Sken our children in the #inclusion tree. This list is sorted by its 141229997Sken elements' `included_at_line' values, which are unique. (The 142229997Sken macro splay tree's ordering function needs this property.) */ 143265634Smav struct macro_source_file *includes; 144229997Sken 145229997Sken /* The next file #included by our `included_from' file; our sibling 146229997Sken in the #inclusion tree. */ 147229997Sken struct macro_source_file *next_included; 148229997Sken}; 149269295Smav 150229997Sken 151229997Sken/* Create a new, empty macro table. Allocate it in OBSTACK, or use 152229997Sken xmalloc if OBSTACK is zero. Use BCACHE to store all macro names, 153229997Sken arguments, definitions, and anything else that might be the same 154229997Sken amongst compilation units in an executable file; if BCACHE is zero, 155229997Sken don't cache these things. 156229997Sken 157229997Sken Note that, if either OBSTACK or BCACHE are non-zero, then you 158229997Sken should only ever add information the macro table --- you should 159229997Sken never remove things from it. You'll get an error if you try. At 160229997Sken the moment, since we only provide obstacks and bcaches for macro 161229997Sken tables for symtabs, this restriction makes a nice sanity check. 162229997Sken Obstacks and bcaches are pretty much grow-only structures anyway. 163229997Sken However, if we find that it's occasionally useful to delete things 164229997Sken even from the symtab's tables, and the storage leak isn't a 165268674Smav problem, this restriction could be lifted. */ 166268674Smavstruct macro_table *new_macro_table (struct obstack *obstack, 167268674Smav struct bcache *bcache); 168229997Sken 169229997Sken 170229997Sken/* Free TABLE, and any macro definitions, source file structures, 171229997Sken etc. it owns. This will raise an internal error if TABLE was 172229997Sken allocated on an obstack, or if it uses a bcache. */ 173229997Skenvoid free_macro_table (struct macro_table *table); 174229997Sken 175229997Sken 176229997Sken/* Set FILENAME as the main source file of TABLE. Return a source 177229997Sken file structure describing that file; if we record the #definition 178229997Sken of macros, or the #inclusion of other files into FILENAME, we'll 179229997Sken use that source file structure to indicate the context. 180229997Sken 181229997Sken The "main source file" is the one that was given to the compiler; 182273312Smav all other source files that contributed to the compilation unit are 183273312Smav #included, directly or indirectly, from this one. 184229997Sken 185229997Sken The macro table makes its own copy of FILENAME; the caller is 186229997Sken responsible for freeing FILENAME when it is no longer needed. */ 187275895Smavstruct macro_source_file *macro_set_main (struct macro_table *table, 188275895Smav const char *filename); 189275895Smav 190275895Smav 191275895Smav/* Return the main source file of the macro table TABLE. */ 192275895Smavstruct macro_source_file *macro_main (struct macro_table *table); 193229997Sken 194229997Sken 195229997Sken/* Record a #inclusion. 196229997Sken Record in SOURCE's macro table that, at line number LINE in SOURCE, 197229997Sken we #included the file INCLUDED. Return a source file structure we 198229997Sken can use for symbols #defined or files #included into that. If we've 199229997Sken already created a source file structure for this #inclusion, return 200229997Sken the same structure we created last time. 201229997Sken 202229997Sken The first line of the source file has a line number of 1, not 0. 203229997Sken 204229997Sken The macro table makes its own copy of INCLUDED; the caller is 205229997Sken responsible for freeing INCLUDED when it is no longer needed. */ 206229997Skenstruct macro_source_file *macro_include (struct macro_source_file *source, 207229997Sken int line, 208229997Sken const char *included); 209229997Sken 210229997Sken 211229997Sken/* Find any source file structure for a file named NAME, either 212229997Sken included into SOURCE, or SOURCE itself. Return zero if we have 213229997Sken none. NAME is only the final portion of the filename, not the full 214229997Sken path. e.g., `stdio.h', not `/usr/include/stdio.h'. If NAME 215229997Sken appears more than once in the inclusion tree, return the 216229997Sken least-nested inclusion --- the one closest to the main source file. */ 217229997Skenstruct macro_source_file *(macro_lookup_inclusion 218229997Sken (struct macro_source_file *source, 219229997Sken const char *name)); 220229997Sken 221229997Sken 222229997Sken/* Record an object-like #definition (i.e., one with no parameter list). 223229997Sken Record in SOURCE's macro table that, at line number LINE in SOURCE, 224229997Sken we #defined a preprocessor symbol named NAME, whose replacement 225229997Sken string is REPLACEMENT. This function makes copies of NAME and 226229997Sken REPLACEMENT; the caller is responsible for freeing them. */ 227229997Skenvoid macro_define_object (struct macro_source_file *source, int line, 228229997Sken const char *name, const char *replacement); 229229997Sken 230229997Sken 231229997Sken/* Record an function-like #definition (i.e., one with a parameter list). 232229997Sken 233229997Sken Record in SOURCE's macro table that, at line number LINE in SOURCE, 234229997Sken we #defined a preprocessor symbol named NAME, with ARGC arguments 235229997Sken whose names are given in ARGV, whose replacement string is REPLACEMENT. If 236229997Sken the macro takes a variable number of arguments, then ARGC should be 237229997Sken one greater than the number of named arguments, and ARGV[ARGC-1] 238229997Sken should be the string "...". This function makes its own copies of 239229997Sken NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing 240229997Sken them. */ 241229997Skenvoid macro_define_function (struct macro_source_file *source, int line, 242229997Sken const char *name, int argc, const char **argv, 243229997Sken const char *replacement); 244229997Sken 245229997Sken 246229997Sken/* Record an #undefinition. 247229997Sken Record in SOURCE's macro table that, at line number LINE in SOURCE, 248229997Sken we removed the definition for the preprocessor symbol named NAME. */ 249229997Skenvoid macro_undef (struct macro_source_file *source, int line, 250229997Sken const char *name); 251229997Sken 252229997Sken 253229997Sken/* Different kinds of macro definitions. */ 254229997Skenenum macro_kind 255229997Sken{ 256229997Sken macro_object_like, 257229997Sken macro_function_like 258229997Sken}; 259229997Sken 260274492Smav 261229997Sken/* A preprocessor symbol definition. */ 262229997Skenstruct macro_definition 263229997Sken{ 264229997Sken /* The table this definition lives in. */ 265229997Sken struct macro_table *table; 266229997Sken 267229997Sken /* What kind of macro it is. */ 268229997Sken enum macro_kind kind; 269229997Sken 270229997Sken /* If `kind' is `macro_function_like', the number of arguments it 271229997Sken takes, and their names. The names, and the array of pointers to 272229997Sken them, are in the table's bcache, if it has one. */ 273229997Sken int argc; 274229997Sken const char * const *argv; 275229997Sken 276229997Sken /* The replacement string (body) of the macro. This is in the 277229997Sken table's bcache, if it has one. */ 278229997Sken const char *replacement; 279229997Sken}; 280229997Sken 281229997Sken 282229997Sken/* Return a pointer to the macro definition for NAME in scope at line 283229997Sken number LINE of SOURCE. If LINE is -1, return the definition in 284229997Sken effect at the end of the file. The macro table owns the structure; 285229997Sken the caller need not free it. Return zero if NAME is not #defined 286229997Sken at that point. */ 287229997Skenstruct macro_definition *(macro_lookup_definition 288229997Sken (struct macro_source_file *source, 289229997Sken int line, const char *name)); 290229997Sken 291274732Smav 292274732Smav/* Return the source location of the definition for NAME in scope at 293274732Smav line number LINE of SOURCE. Set *DEFINITION_LINE to the line 294274732Smav number of the definition, and return a source file structure for 295274732Smav the file. Return zero if NAME has no definition in scope at that 296274732Smav point, and leave *DEFINITION_LINE unchanged. */ 297274732Smavstruct macro_source_file *(macro_definition_location 298274732Smav (struct macro_source_file *source, 299274732Smav int line, 300274732Smav const char *name, 301274732Smav int *definition_line)); 302232074Sdim 303273977Smav 304273977Smav#endif /* MACROTAB_H */ 305229997Sken