Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 327 lines (324 sloc) 10.638 kb
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
1 .TH CTAGS 1
2 .SH NAME
3 ctags - Generates "tags" and (optionally) "refs" files
4 .SH SYNOPSIS
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
5 .B ctags
6 .RB [ -D
7 .IR word ]
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
8 .RB [ -FBNgitvshlpdxra ]
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
9 .I files...
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
10 .SH VERSION
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
11 This page describes the
2fe6e17 @mbert Import Elvis 2.2_1 (written by Steve Kirkendall)
authored
12 .B Elvis 2.2_1
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
13 version of
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
14 .BR c\&tags .
15 See
16 .BR elvis (1).
17 .SH DESCRIPTION
18 .B ctags
19 generates the
20 .I tags
21 and
22 .I refs
23 files from a group of C source files.
24 The
25 .I tags
26 file is used by Elvis' ":tag" command,
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
27 \fB^]\fR command, and \fB-t\fR option.
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
28 The
29 .I refs
30 file is sometimes used by the
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
31 .BR ref (1)
32 program.
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
33 .PP
34 Each C source file is scanned for #define statements and
35 global function definitions.
36 The name of the macro or function becomes the name of a tag.
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
37 For each tag, a line is added to the
38 .I tags
39 file.
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
40 .PP
41 The filenames list will typically be the names of all C source
42 files in the current directory, like this:
43 .RS
44 .nf
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
45
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
46 $ ctags *.c *.h
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
47 .RE
48 .fi
49 .SH OPTIONS
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
50 If no options are given, then
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
51 .B ctags
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
52 acts as though the
53 .B -l -i -t -v
54 and
55 .B -s
56 option flags were given.
57 If you want to omit those options, you can do so by explicitly giving
58 a harmless option such as
59 .BR -F.
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
60 .IP \fB-D\fIword\fR
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
61 This causes Elvis to ignore any instance of "\fIword\fR" in your source code.
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
62 This is handy if you're using a macro for conditionally declaring the arguments
63 to functions, in order to make your code be backward-compatible with older K&R
64 C compilers.
65 \fIctags\fR always ignores "P_" and "__P";
66 the \fB-D\fIword\fR flag allows you to make it ignore a third word.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
67 .IP \fB-F\fR
68 Enclose regular expressions in slashes (/regexp/) which will cause
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
69 .BR elvis (1)
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
70 to search from the top of the file.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
71 This is the default.
72 .IP \fB-B\fR
73 Enclose the regular expressions in question marks (?regexp?) so
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
74 .BR elvis (1)
75 will search backward from the bottom of the file.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
76 The search direction rarely matters; this option exists mostly for
77 compatibility with earlier versions of ctags.
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
78 .IP \fB-N\fR
79 This causes
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
80 .B ctags
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
81 to use line numbers for all tags.
82 Without this flag, it would use numbers for #define'ed macros,
83 and regular expressions for anything else.
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
84 .IP \fB-g\fR
85 For static tags, generate entries that look like global tags.
86 (I.e., never generate an extra "file:" attribute.)
b190a43 @mbert Applied some of the debian patches.
authored
87 This implies \-s and \-h.
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
88 .IP \fB-i\fR
89 Include inline definitions.
90 A tag will be generated for each function which is declared as being
91 inline, __inline, or __inline__.
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
92 .IP \fB-t\fR
93 Include typedefs.
94 A tag will be generated for each user-defined type.
95 Also tags will be generated for struct and enum names.
96 Types are considered to be global if they are defined in a header file,
97 and static if they are defined in a C source file.
98 .IP \fB-v\fR
99 Include variable declarations.
100 A tag will be generated for each variable, except for those that are declared
101 inside the body of a function.
102 .IP \fB-s\fR
103 Include static tags.
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
104 .B ctags
105 will normally put global tags in the
106 .I tags
107 file, and silently ignore the static tags.
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
108 This flag causes both global and static tags to be added.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
109 .IP \fB-e\fR
110 Include extern tags.
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
111 .B ctags
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
112 will normally ignore extern declarations of functions or variables;
113 that's handy when generating tags for your own programs.
114 A tags file for the extern declarations in the system's standard header files
115 can be a very handy resource, so this \fB-e\fR flag was created.
116 .IP \fB-h\fR
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
117 Add hints that may help Elvis handle overloaded tags better.
118 The resulting tags file may be unreadable by programs other than Elvis, though.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
119 .IP \fB-l\fR
120 Add "ln" line number hints.
121 This implies \fB-h\fR, since it would be pointless if hints weren't allowed.
122 The "ln" hints are used by
123 .BR elvis (1)
124 to make its "showtag" option work much faster.
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
125 .IP \fB-p\fR
126 Write parsing information to stdout.
127 This is intended mainly as an aid to debugging the \fIctags\fR command itself.
128 If \fIctags\fR doesn't generate all of the tags that you expect it to,
129 then try studying the \fB-p\fR output to determine what syntax feature is
130 tripping it up.
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
131 .IP \fB-d\fR
132 Warn about duplicates, on stdout.
133 .B ctags
134 allows tags with duplicate names, except for typedefs (tags with kind=t)
135 which must be unique.
136 When a duplicate tag is detected,
137 .B ctags
138 can either add it if neither the new tag nor the existing one has "kind=t",
139 skip it if the existing one has "kind=t", or
140 add it and delete the existing one if the new one has "kind=t".
141 Usually you won't care, but
142 .B -d
143 may help you understand why
144 .I ctags
145 fails to add a tag that you expected it to add.
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
146 .IP \fB-x\fR
147 Generate a human-readable tag list instead of a "tags" file.
148 The list is written to stdout.
149 Each line contains a tag name, the line number and file name where
150 the tag is defined, and the text of that line.
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
151 .IP \fB-r\fP
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
152 This causes
153 .B ctags
154 to generate both
155 .I tags
156 and
157 .IR refs .
158 Without \fB-r\fP, it would only generate
159 .IR tags .
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
160 .IP \fB-a\fR
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
161 Append to
162 .IR tags ,
163 and maybe
164 .IR refs .
165 Normally,
166 .B ctags
167 overwrites these files each time it is invoked.
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
168 This flag is useful when you have too many files in the current directory
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
169 for you to list them on a single command-line;
170 it allows you to split the arguments among several invocations.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
171 .B "This may result in an unsorted tags file."
172 .SH "FORMAT OF THE TAGS FILE"
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
173 The
174 .I tags
175 file is a text file.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
176 Each line stores the attributes of a single tag.
177 The basic format of a line is:
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
178 .IP
179 \(bu the name of the tag
180 .br
181 \(bu a tab character
182 .br
183 \(bu the name of the file containing the tag
184 .br
185 \(bu a tab character
186 .br
187 \(bu the tag's address within that file
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
188 .PP
189 The tag address may be given as either line number (a string of digits),
190 or a regular expression using ex/vi's "nomagic" syntax, delimited by either
191 slashes or question marks.
192 Regular expressions are allowed to contain tab characters.
193 .PP
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
194 The authors of Elvis, Vim, and "Exuberant" Ctags have agreed on a
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
195 standard format for adding additional attributes to tags.
196 In this format, the first three fields of all tags are identical to the
197 traditional format, except that a semicolon-doublequote character pair
198 is appended to the tag address field, with the extra attributes appearing
199 after that.
200 .PP
201 The semicolon-doublequote character pair is present because it has the
202 surprising side-effect of making the original ex/vi ignore the remainder
203 of the line, thus allowing the original ex/vi to read new-format tags files.
204 The original ex/vi will simply ignore the extra attributes.
205 .PP
206 Any additional attributes are appended to the tag's line.
207 They may be appended in any order.
208 Each attribute will use the following format:
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
209 .IP
210 \(bu a tab character
211 .br
212 \(bu the name of the attribute
213 .br
214 \(bu a colon character, ':'
215 .br
216 \(bu the value of the attribute.
217 .PP
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
218 Note that each additional attribute has an explicit name.
219 Different tags files may use totally different names for additional attributes,
220 and even within a single file, most tags will use only a subset of the
3a9bb55 @mbert Import Elvis 2.1_3 (written by Steve Kirkendall)
authored
221 possible attributes.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
222 This version of ctags uses the following names:
223 .IP file
224 This attribute is used to mark static tags -- i.e., tags for C/C++ functions
225 or variables whose scope is limited to the function in which they are
226 defined.
227 The value is the name of the file where it is defined,
228 except that if the file is the same as field 2
229 (and it nearly always is)
230 then the value may be given as a zero-length string.
231 .IP class
232 This is used to mark member functions of C++ classes.
233 The value is the class name.
234 However, currently ctags doesn't do a very good job of detecting whether a
235 function is a member function or not.
236 .IP kind
237 This attribute's value is a single letter, indicating the lexical type
238 of the tagged identifier:
239 \fBf\fR for a function,
240 \fBt\fR for a typedef,
3a9bb55 @mbert Import Elvis 2.1_3 (written by Steve Kirkendall)
authored
241 \fBs\fR for a struct tag,
242 \fBu\fR for a union tag,
243 \fBv\fR for a variable,
244 \fBd\fR for a macro definition, or
245 \fBx\fR for an extern declaration.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
246 .IP
247 Note that in the tags file, the "kind:" label is omitted, for the sake of compactness.
248 .IP ln
249 This gives the line number where the tag was defined.
250 It is redundant, but it is still somewhat useful because it allows
251 .BR elvis (1)'s
252 "showtag" option to work faster.
253 .PP
254 The values can only contain tabs if those tabs are converted to the '\\t'
255 (backslash-t) notation.
256 Similarly, a newline, carriage return, or literal backslash can be given
257 as '\\n', '\\r', or '\\\\' respectively.
258 For MS-DOS file names, this means the names must use double backslashes.
259 Space characters don't require any special encoding.
260 (This doesn't apply to file names in the
261 .I tagfile
262 field, where names can be given without any special encoding.
263 It only applies to file names in extra fields.)
264 .PP
265 As a special case, if an extra attribute contains no ':' to delimit the
266 name from the value, then the attribute string is assumed to be the value
267 of an attribute named "kind".
268 Usually this will be a single letter indicating what type of token the
269 tag represents -- 'f' for function, 'v' for variable, and so on.
270 .PP
271 Here's an example of a new-format tag:
272 .RS
273 .nf
274 bar foo.c /^void Foo::bar(int zot)$/;" class:Foo
275 .fi
276 .RE
277 The tagname is "bar", to match its function's name.
278 The tagfile is "foo.c".
279 The tagaddress is a regular expression containing the whole definition line.
280 Note that a semicolon-doublequote character pair has been appended to the
281 tagaddress.
282 There is only one additional attribute, with the name "class" and the value
283 "Foo".
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
284 .SH FILES
285 .IP tags
286 A cross-reference that lists each tag name, the name of the source file that
287 contains it, and a way to locate a particular line in the source file.
288 .IP refs
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
289 The
290 .I refs
291 file contains the definitions for each tag in the
292 .I tags
293 file, and very little else.
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
294 This file can be useful, for example, when licensing restrictions prevent
295 you from making the source code to the standard C library readable by everybody,
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
296 but you still want everybody to know what arguments the library functions need.
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
297 .SH BUGS
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
298 .B ctags
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
299 is sensitive to indenting and line breaks.
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
300 Consequently, it might not discover all of the tags in a file that
301 is formatted in an unusual way.
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
302 .PP
303 The
304 .B -a
305 flag causes tag files to be appended, but not necessarily sorted.
306 Some programs expect tags files to be sorted, and will misbehave if they
307 aren't.
308 Also, the new format allows a "!_TAG_FILE_SORTED" marker near the top of the
309 file to indicate whether the file is sorted, but that might not be accurate
310 after new tags are appended to the file.
311 Consequently, you should avoid the use of
312 .BR -a .
313 .PP
314 The new standard doesn't specify how overloaded operators are to be labelled.
315 If your C++ source contains a definition of operator+=(), then this version of
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
316 .B ctags
8d1ac0c @mbert Import Elvis 2.1 (written by Steve Kirkendall)
authored
317 will store a tag named "operator+=".
318 Other versions of ctags could simply use the name "+=".
319
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
320 .SH "SEE ALSO"
cf92e3b @mbert Import Elvis 2.0 (written by Steve Kirkendall)
authored
321 .BR elvis (1),
322 .BR ref (1)
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
323 .SH AUTHOR
324 Steve Kirkendall
9f1c6f0 @mbert Import Elvis 2.2_0 (written by Steve Kirkendall)
authored
325 .br
6335386 @mbert Import Elvis 1.8 (written by Steve Kirkendall)
authored
326 kirkenda@cs.pdx.edu
Something went wrong with that request. Please try again.