-
Notifications
You must be signed in to change notification settings - Fork 2
/
ctags.html
2085 lines (1615 loc) · 70.4 KB
/
ctags.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!-- Creator : groff version 1.21 -->
<!-- CreationDate: Thu Mar 17 14:38:55 2011 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>CTAGS</title>
</head>
<body>
<h1 align="center">CTAGS</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#SOURCE FILES">SOURCE FILES</a><br>
<a href="#OPTIONS">OPTIONS</a><br>
<a href="#OPERATIONAL DETAILS">OPERATIONAL DETAILS</a><br>
<a href="#TAG FILE FORMAT">TAG FILE FORMAT</a><br>
<a href="#HOW TO USE WITH VI">HOW TO USE WITH VI</a><br>
<a href="#HOW TO USE WITH GNU EMACS">HOW TO USE WITH GNU EMACS</a><br>
<a href="#HOW TO USE WITH NEDIT">HOW TO USE WITH NEDIT</a><br>
<a href="#CAVEATS">CAVEATS</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#ENVIRONMENT VARIABLES">ENVIRONMENT VARIABLES</a><br>
<a href="#FILES">FILES</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#AUTHOR">AUTHOR</a><br>
<a href="#MOTIVATION">MOTIVATION</a><br>
<a href="#CREDITS">CREDITS</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">ctags −
Generate tag files for source code</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>ctags</b>
[<b>options</b>] [<i>file(s)</i>] <b><br>
etags</b> [<b>options</b>] [<i>file(s)</i>]</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>ctags</b> and <b>etags</b> programs (hereinafter
collectively referred to as <b>ctags</b>, except where
distinguished) generate an index (or "tag") file
for a variety of language objects found in <i>file(s)</i>.
This tag file allows these items to be quickly and easily
located by a text editor or other utility. A "tag"
signifies a language object for which an index entry is
available (or, alternatively, the index entry created for
that object).</p>
<p style="margin-left:11%; margin-top: 1em">Alternatively,
<b>ctags</b> can generate a cross reference file which
lists, in human readable form, information about the various
source objects found in a set of language files.</p>
<p style="margin-left:11%; margin-top: 1em">Tag index files
are supported by numerous editors, which allow the user to
locate the object associated with a name appearing in a
source file and jump to the file and line which defines the
name. Those known about at the time of this release are:</p>
<p style="margin-left:17%; margin-top: 1em"><b>Vi</b>(1)
and its derivatives (e.g. Elvis, Vim, Vile, Lemmy),
<b>CRiSP</b>, <b>Emacs</b>, <b>FTE</b> (Folding Text
Editor), <b>JED</b>, <b>jEdit</b>, <b>Mined</b>,
<b>NEdit</b> (Nirvana Edit), <b>TSE</b> (The SemWare
Editor), <b>UltraEdit</b>, <b>WorkSpace</b>, <b>X2</b>,
<b>Zeus</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>Ctags</b> is
capable of generating different kinds of tags for each of
many different languages. For a complete list of supported
languages, the names by which they are recognized, and the
kinds of tags which are generated for each, see the
<b>−−list−languages</b> and
<b>−−list−kinds</b> options.</p>
<h2>SOURCE FILES
<a name="SOURCE FILES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Unless the
<b>−−language−force</b> option is
specified, the language of each source file is automatically
selected based upon a mapping of file names to languages.
The mappings in effect for each language may be display
using the <b>−−list−maps</b> option and
may be changed using the <b>−−langmap</b>
option. On platforms which support it, if the name of a file
is not mapped to a language and the file is executable, the
first line of the file is checked to see if the file is a
"#!" script for a recognized language.</p>
<p style="margin-left:11%; margin-top: 1em">By default, all
other files names are ignored. This permits running
<b>ctags</b> on all files in either a single directory (e.g.
"ctags *"), or on all files in an entire source
directory tree (e.g. "ctags −R"), since only
those files whose names are mapped to languages will be
scanned.</p>
<p style="margin-left:11%; margin-top: 1em">[The reason
that .h extensions are mapped to C++ files rather than C
files is because it is common to use .h extensions in C++,
and no harm results in treating them as C++ files.]</p>
<h2>OPTIONS
<a name="OPTIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Despite the
wealth of available options, defaults are set so that
<b>ctags</b> is most commonly executed without any options
(e.g. "ctags *", or "ctags −R"),
which will create a tag file in the current directory for
all recognized source files. The options described below are
provided merely to allow custom tailoring to meet special
needs.</p>
<p style="margin-left:11%; margin-top: 1em">Note that
spaces separating the single-letter options from their
parameters are optional.</p>
<p style="margin-left:11%; margin-top: 1em">Note also that
the boolean parameters to the long form options (those
beginning with "−−" and that take a
"<i>[=yes</i>|<i>no]</i>" parameter) may be
omitted, in which case "<b>=</b><i>yes</i>" is
implied. (e.g. <b>−−sort</b> is equivalent to
<b>−−sort</b>=<i>yes</i>). Note further that
"=<i>1</i>" and "=<i>on</i>" are
considered synonyms for "=<i>yes</i>", and that
"=<i>0</i>" and "=<i>off</i>" are
considered synonyms for "=<i>no</i>".</p>
<p style="margin-left:11%; margin-top: 1em">Some options
are either ignored or useful only when used while running in
etags mode (see <b>−e</b> option). Such options will
be noted.</p>
<p style="margin-left:11%; margin-top: 1em">Most options
may appear anywhere on the command line, affecting only
those files which follow the option. A few options, however,
must appear before the first file name and will be noted as
such.</p>
<p style="margin-left:11%; margin-top: 1em">Options taking
language names will accept those names in either upper or
lower case. See the
<b>−−list−languages</b> option for a
complete list of the built-in language names.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−a</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>Equivalent to <b>−−append</b>.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−B</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>Use backward searching patterns (e.g. ?pattern?).
[Ignored in etags mode]</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−e</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>Enable etags mode, which will create a tag file for use
with the Emacs editor. Alternatively, if <b>ctags</b> is
invoked by a name containing the string "etags"
(either by renaming, or creating a link to, the executable),
etags mode will be enabled. This option must appear before
the first file name.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>−f</b>
<i>tagfile</i></p>
<p style="margin-left:18%;">Use the name specified by
<i>tagfile</i> for the tag file (default is
"tags", or "TAGS" when running in etags
mode). If <i>tagfile</i> is specified as
"−", then the tag file is written to
standard output instead. <b>Ctags</b> will stubbornly refuse
to take orders if <i>tagfile</i> exists and its first line
contains something other than a valid tags line. This will
save your neck if you mistakenly type "ctags −f
*.c", which would otherwise overwrite your first C file
with the tags generated by the rest! It will also refuse to
accept a multi-character file name which begins with a
’−’ (dash) character, since this most
likely means that you left out the tag file name and this
option tried to grab the next option as the file name. If
you really want to name your output tag file
"−ugly", specify it as
"./−ugly". This option must appear before
the first file name. If this option is specified more than
once, only the last will apply.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−F</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>Use forward searching patterns (e.g. /pattern/)
(default). [Ignored in etags mode]</p></td></tr>
</table>
<p style="margin-left:11%;"><b>−h</b> <i>list</i></p>
<p style="margin-left:18%;">Specifies a list of file
extensions, separated by periods, which are to be
interpreted as include (or header) files. To indicate files
having no extension, use a period not followed by a
non-period character (e.g. ".", "..x",
".x."). This option only affects how the scoping
of a particular kinds of tags is interpreted (i.e. whether
or not they are considered as globally visible or visible
only within the file in which they are defined); it does not
map the extension to any particular language. Any tag which
is located in a non-include file and cannot be seen (e.g.
linked to) from another file is considered to have
file-limited (e.g. static) scope. No kind of tag appearing
in an include file will be considered to have file-limited
scope. If the first character in the list is a plus sign,
then the extensions in the list will be appended to the
current list; otherwise, the list will replace the current
list. See, also, the <b>−−file−scope</b>
option. The default list is
".h.H.hh.hpp.hxx.h++.inc.def". To restore the
default list, specify <b>−h</b> <i>default</i>. Note
that if an extension supplied to this option is not already
mapped to a particular language (see <b>SOURCE FILES</b>,
above), you will also need to use either the
<b>−−langmap</b> or
<b>−−language−force</b> option.</p>
<p style="margin-left:11%;"><b>−I</b>
<i>identifier−list</i></p>
<p style="margin-left:18%;">Specifies a list of identifiers
which are to be specially handled while parsing C and C++
source files. This option is specifically provided to handle
special cases arising through the use of preprocessor
macros. When the identifiers listed are simple identifiers,
these identifiers will be ignored during parsing of the
source files. If an identifier is suffixed with a
’+’ character, <b>ctags</b> will also ignore any
parenthesis-enclosed argument list which may immediately
follow the identifier in the source files. If two
identifiers are separated with the ’=’
character, the first identifiers is replaced by the second
identifiers for parsing purposes. The list of identifiers
may be supplied directly on the command line or read in from
a separate file. If the first character of
<i>identifier−list</i> is ’@’,
’.’ or a pathname separator (’/’ or
’\’), or the first two characters specify a
drive letter (e.g. "C:"), the parameter
<i>identifier−list</i> will be interpreted as a
filename from which to read a list of identifiers, one per
input line. Otherwise, <i>identifier−list</i> is a
list of identifiers (or identifier pairs) to be specially
handled, each delimited by a either a comma or by white
space (in which case the list should be quoted to keep the
entire list as one command line argument). Multiple
<b>−I</b> options may be supplied. To clear the list
of ignore identifiers, supply a single dash
("−") for <i>identifier−list</i>.</p>
<p style="margin-left:18%; margin-top: 1em">This feature is
useful when preprocessor macros are used in such a way that
they cause syntactic confusion due to their presence.
Indeed, this is the best way of working around a number of
problems caused by the presence of syntax-busting macros in
source files (see <b>CAVEATS</b>, below). Some examples will
illustrate this point.</p>
<p style="margin-left:23%; margin-top: 1em">int foo
ARGDECL4(void *, ptr, long int, nbytes)</p>
<p style="margin-left:18%; margin-top: 1em">In the above
example, the macro "ARGDECL4" would be mistakenly
interpreted to be the name of the function instead of the
correct name of "foo". Specifying <b>−I</b>
<i>ARGDECL4</i> results in the correct behavior.</p>
<p style="margin-left:23%; margin-top: 1em">/* creates an
RCS version string in module */ <br>
MODULE_VERSION("$Revision: 750 $")</p>
<p style="margin-left:18%; margin-top: 1em">In the above
example the macro invocation looks too much like a function
definition because it is not followed by a semicolon
(indeed, it could even be followed by a global variable
definition that would look much like a K&R style
function parameter declaration). In fact, this seeming
function definition could possibly even cause the rest of
the file to be skipped over while trying to complete the
definition. Specifying <b>−I</b>
<i>MODULE_VERSION+</i> would avoid such a problem.</p>
<p style="margin-left:23%; margin-top: 1em">CLASS Example {
<br>
// your content here <br>
};</p>
<p style="margin-left:18%; margin-top: 1em">The example
above uses "CLASS" as a preprocessor macro which
expands to something different for each platform. For
instance CLASS may be defined as "class
__declspec(dllexport)" on Win32 platforms and simply
"class" on UNIX. Normally, the absence of the C++
keyword "class" would cause the source file to be
incorrectly parsed. Correct behavior can be restored by
specifying <b>−I</b> <i>CLASS=class</i>.</p>
<p style="margin-left:11%;"><b>−L</b> <i>file</i></p>
<p style="margin-left:18%;">Read from <i>file</i> a list of
file names for which tags should be generated. If
<i>file</i> is specified as "−", then file
names are read from standard input. File names read using
this option are processed following file names appearing on
the command line. Options are also accepted in this input.
If this option is specified more than once, only the last
will apply. <b>Note:</b> <i>file</i> is read in
line-oriented mode, where a new line is the only delimiter
and non-trailing white space is considered significant, in
order that file names containing spaces may be supplied
(however, trailing white space is stripped from lines); this
can affect how options are parsed if included in the
input.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−n</b></p></td>
<td width="4%"></td>
<td width="47%">
<p>Equivalent to
<b>−−excmd</b>=<i>number</i>.</p> </td>
<td width="35%">
</td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−N</b></p></td>
<td width="4%"></td>
<td width="47%">
<p>Equivalent to
<b>−−excmd</b>=<i>pattern</i>.</p> </td>
<td width="35%">
</td></tr>
</table>
<p style="margin-left:11%;"><b>−o</b>
<i>tagfile</i></p>
<p style="margin-left:18%;">Equivalent to <b>−f</b>
<i>tagfile</i>.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−R</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>Equivalent to <b>−−recurse</b>.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−u</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>Equivalent to <b>−−sort</b>=<i>no</i> (i.e.
"unsorted").</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−V</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>Equivalent to <b>−−verbose</b>.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−w</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>This option is silently ignored for
backward-compatibility with the ctags of SVR4 Unix.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p><b>−x</b></p></td>
<td width="4%"></td>
<td width="82%">
<p>Print a tabular, human-readable cross reference (xref)
file to standard output instead of generating a tag file.
The information contained in the output includes: the tag
name; the kind of tag; the line number, file name, and
source line (with extra white space condensed) of the file
which defines the tag. No tag file is written and all
options affecting tag file output will be ignored. Example
applications for this feature are generating a listing of
all functions located in a source file (e.g. <b>ctags
−x −−c−kinds</b>=<i>f file</i>), or
generating a list of all externally visible global variables
located in a source file (e.g. <b>ctags −x
−−c−kinds</b>=<i>v</i>
<b>−−file−scope</b>=<i>no file</i>). This
option must appear before the first file name.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>−−append</b>[=<i>yes</i>|<i>no</i>]</p>
<p style="margin-left:18%;">Indicates whether tags
generated from the specified files should be appended to
those already present in the tag file or should replace
them. This option is off by default. This option must appear
before the first file name.</p>
<p style="margin-left:11%;"><b>−−etags−include</b>=<i>file</i></p>
<p style="margin-left:18%;">Include a reference to
<i>file</i> in the tag file. This option may be specified as
many times as desired. This supports Emacs’ capability
to use a tag file which "includes" other tag
files. [Available only in etags mode]</p>
<p style="margin-left:11%;"><b>−−exclude</b>=[<i>pattern</i>]</p>
<p style="margin-left:18%;">Add <i>pattern</i> to a list of
excluded files and directories. This option may be specified
as many times as desired. For each file name considered by
<b>ctags</b>, each <i>pattern</i> specified using this
option will be compared against both the complete path (e.g.
some/path/base.ext) and the base name (e.g. base.ext) of the
file, thus allowing patterns which match a given file name
irrespective of its path, or match only a specific path. If
appropriate support is available from the runtime library of
your C compiler, then <i>pattern</i> may contain the usual
shell wildcards (not regular expressions) common on Unix (be
sure to quote the option parameter to protect the wildcards
from being expanded by the shell before being passed to
<b>ctags</b>; also be aware that wildcards can match the
slash character, ’/’). You can determine if
shell wildcards are available on your platform by examining
the output of the <b>−−version</b> option, which
will include "+wildcards" in the compiled feature
list; otherwise, <i>pattern</i> is matched against file
names using a simple textual comparison.</p>
<p style="margin-left:18%; margin-top: 1em">If
<i>pattern</i> begins with the character ’@’,
then the rest of the string is interpreted as a file name
from which to read exclusion patterns, one per line. If
<i>pattern</i> is empty, the list of excluded patterns is
cleared. Note that at program startup, the default exclude
list contains "EIFGEN", "SCCS",
"RCS", and "CVS", which are names of
directories for which it is generally not desirable to
descend while processing the <b>−−recurse</b>
option.</p>
<p style="margin-left:11%;"><b>−−excmd</b>=<i>type</i></p>
<p style="margin-left:18%;">Determines the type of EX
command used to locate tags in the source file. [Ignored in
etags mode]</p>
<p style="margin-left:18%; margin-top: 1em">The valid
values for <i>type</i> (either the entire word or the first
letter is accepted) are:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%"></td>
<td width="10%">
<p><i>number</i></p></td>
<td width="4%"></td>
<td width="68%">
<p>Use only line numbers in the tag file for locating tags.
This has four advantages:</p></td></tr>
</table>
<p style="margin-left:32%;">1.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="32%"></td>
<td width="3%"></td>
<td width="3%"></td>
<td width="62%">
<p style="margin-top: 1em">Significantly reduces the size
of the resulting tag file.</p></td></tr>
<tr valign="top" align="left">
<td width="32%"></td>
<td width="3%">
<p>2.</p></td>
<td width="3%"></td>
<td width="62%">
<p>Eliminates failures to find tags because the line
defining the tag has changed, causing the pattern match to
fail (note that some editors, such as <b>vim</b>, are able
to recover in many such instances).</p></td></tr>
<tr valign="top" align="left">
<td width="32%"></td>
<td width="3%">
<p>3.</p></td>
<td width="3%"></td>
<td width="62%">
<p>Eliminates finding identical matching, but incorrect,
source lines (see <b>BUGS</b>, below).</p></td></tr>
<tr valign="top" align="left">
<td width="32%"></td>
<td width="3%">
<p>4.</p></td>
<td width="3%"></td>
<td width="62%">
<p>Retains separate entries in the tag file for lines which
are identical in content. In <i>pattern</i> mode, duplicate
entries are dropped because the search patterns they
generate are identical, making the duplicate entries
useless.</p> </td></tr>
</table>
<p style="margin-left:32%; margin-top: 1em">However, this
option has one significant drawback: changes to the source
files can cause the line numbers recorded in the tag file to
no longer correspond to the lines in the source file,
causing jumps to some tags to miss the target definition by
one or more lines. Basically, this option is best used when
the source code to which it is applied is not subject to
change. Selecting this option type causes the following
options to be ignored: <b>−BF</b>.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%"></td>
<td width="11%">
<p style="margin-top: 1em"><i>pattern</i></p></td>
<td width="3%"></td>
<td width="68%">
<p style="margin-top: 1em">Use only search patterns for all
tags, rather than the line numbers usually used for macro
definitions. This has the advantage of not referencing
obsolete line numbers when lines have been added or removed
since the tag file was generated.</p></td></tr>
<tr valign="top" align="left">
<td width="18%"></td>
<td width="11%">
<p><i>mixed</i></p></td>
<td width="3%"></td>
<td width="68%">
<p>In this mode, patterns are generally used with a few
exceptions. For C, line numbers are used for macro
definition tags. This was the default format generated by
the original <b>ctags</b> and is, therefore, retained as the
default for this option. For Fortran, line numbers are used
for common blocks because their corresponding source lines
are generally identical, making pattern searches useless for
finding all matches.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>−−extra</b>=<i>[+|−]flags</i></p>
<p style="margin-left:18%;">Specifies whether to include
extra tag entries for certain kinds of information. The
parameter <i>flags</i> is a set of one-letter flags, each
representing one kind of extra tag entry to include in the
tag file. If <i>flags</i> is preceded by either the
’+’ or ’−’ character, the
effect of each flag is added to, or removed from, those
currently enabled; otherwise the flags replace any current
settings. The meaning of each flag is as follows:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>f</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Include an entry for the base file name of every source
file (e.g. "example.c"), which addresses the first
line of the file.</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>q</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Include an extra class-qualified tag entry for each tag
which is a member of a class (for languages for which this
information is extracted; currently C++, Eiffel, and Java).
The actual form of the qualified tag depends upon the
language from which the tag was derived (using a form that
is most natural for how qualified calls are specified in the
language). For C++, it is in the form
"class::member"; for Eiffel and Java, it is in the
form "class.member". This may allow easier
location of a specific tags when multiple occurrences of a
tag name occur in the tag file. Note, however, that this
could potentially more than double the size of the tag
file.</p> </td></tr>
</table>
<p style="margin-left:11%;"><b>−−fields</b>=<i>[+|−]flags</i></p>
<p style="margin-left:18%;">Specifies the available
extension fields which are to be included in the entries of
the tag file (see <b>TAG FILE FORMAT</b>, below, for more
information). The parameter <i>flags</i> is a set of
one-letter flags, each representing one type of extension
field to include, with the following meanings (disabled by
default unless indicated):</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>a</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Access (or export) of class members</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>f</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>File-restricted scoping [enabled]</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>i</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Inheritance information</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>k</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Kind of tag as a single letter [enabled]</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>K</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Kind of tag as full name</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>l</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Language of source file containing tag</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>m</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Implementation information</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>n</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Line number of tag definition</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>s</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Scope of tag definition [enabled]</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>S</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Signature of routine (e.g. prototype or parameter
list)</p> </td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>z</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Include the "kind:" key in kind field</p></td></tr>
<tr valign="top" align="left">
<td width="23%"></td>
<td width="2%">
<p><i>t</i></p></td>
<td width="4%"></td>
<td width="71%">
<p>Type and name of a variable or typedef as
"typeref:" field [enabled]</p></td></tr>
</table>
<p style="margin-left:18%; margin-top: 1em">Each letter or
group of letters may be preceded by either ’+’
to add it to the default set, or ’−’ to
exclude it. In the absence of any preceding ’+’
or ’−’ sign, only those kinds explicitly
listed in <i>flags</i> will be included in the output (i.e.
overriding the default set). This option is ignored if the
option <b>−−format</b>=<i>1</i> has been
specified. The default value of this option is
<i>fkst</i>.</p>
<p style="margin-left:11%;"><b>−−file−scope</b>[=<i>yes</i>|<i>no</i>]</p>
<p style="margin-left:18%;">Indicates whether tags scoped
only for a single file (i.e. tags which cannot be seen
outside of the file in which they are defined, such as
"static" tags) should be included in the output.
See, also, the <b>−h</b> option. This option is
enabled by default.</p>
<p style="margin-left:11%;"><b>−−filter</b>[=<i>yes</i>|<i>no</i>]</p>
<p style="margin-left:18%;">Causes <b>ctags</b> to behave
as a filter, reading source file names from standard input
and printing their tags to standard output on a file-by-file
basis. If <b>−−sorted</b> is enabled, tags are
sorted only within the source file in which they are
defined. File names are read from standard input in
line-oriented input mode (see note for <b>−L</b>
option) and only after file names listed on the command line
or from any file supplied using the <b>−L</b> option.
When this option is enabled, the options <b>−f</b>,
<b>−o</b>, and <b>−−totals</b> are
ignored. This option is quite esoteric and is disabled by
default. This option must appear before the first file
name.</p>
<p style="margin-left:11%;"><b>−−filter−terminator</b>=<i>string</i></p>
<p style="margin-left:18%;">Specifies a string to print to
standard output following the tags for each file name parsed
when the <b>−−filter</b> option is enabled. This
may permit an application reading the output of ctags to
determine when the output for each file is finished. Note
that if the file name read is a directory and
<b>−−recurse</b> is enabled, this string will be
printed only once at the end of all tags found for by
descending the directory. This string will always be
separated from the last tag line for the file by its
terminating newline. This option is quite esoteric and is
empty by default. This option must appear before the first
file name.</p>
<p style="margin-left:11%;"><b>−−format</b>=<i>level</i></p>
<p style="margin-left:18%;">Change the format of the output
tag file. Currently the only valid values for <i>level</i>
are <i>1</i> or <i>2</i>. Level 1 specifies the original tag
file format and level 2 specifies a new extended format
containing extension fields (but in a manner which retains
backward-compatibility with original <b>vi</b>(1)
implementations). The default level is 2. This option must
appear before the first file name. [Ignored in etags
mode]</p>
<p style="margin-left:11%;"><b>−−help</b></p>
<p style="margin-left:18%;">Prints to standard output a
detailed usage description, and then exits.</p>
<p style="margin-left:11%;"><b>−−if0</b>[=<i>yes</i>|<i>no</i>]</p>
<p style="margin-left:18%;">Indicates a preference as to
whether code within an "#if 0" branch of a
preprocessor conditional should be examined for non-macro
tags (macro tags are always included). Because the intent of
this construct is to disable code, the default value of this
option is <i>no</i>. Note that this indicates a preference
only and does not guarantee skipping code within an
"#if 0" branch, since the fall-back algorithm used
to generate tags when preprocessor conditionals are too
complex follows all branches of a conditional. This option
is disabled by default.</p>
<p style="margin-left:11%;"><b>−−<LANG>−kinds</b>=<i>[+|−]kinds</i></p>
<p style="margin-left:18%;">Specifies a list of
language-specific kinds of tags (or kinds) to include in the
output file for a particular language, where
<b><LANG></b> is case-insensitive and is one of the
built-in language names (see the
<b>−−list−languages</b> option for a
complete list). The parameter <i>kinds</i> is a group of
one-letter flags designating kinds of tags (particular to
the language) to either include or exclude from the output.
The specific sets of flags recognized for each language,
their meanings and defaults may be list using the
<b>−−list−kinds</b> option. Each letter or
group of letters may be preceded by either ’+’
to add it to, or ’−’ to remove it from,
the default set. In the absence of any preceding
’+’ or ’−’ sign, only those
kinds explicitly listed in <i>kinds</i> will be included in
the output (i.e. overriding the default for the specified
language).</p>