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