1CTAGS(1)                        Exuberant Ctags                       CTAGS(1)
2
3
4

NAME

6       ctags - Generate tag files for source code
7
8
9

SYNOPSIS

11       ctags [options] [file(s)]
12
13       etags [options] [file(s)]
14
15
16

DESCRIPTION

18       The  ctags  and etags programs (hereinafter collectively referred to as
19       ctags, except where distinguished) generate an index  (or  "tag")  file
20       for  a  variety  of  language  objects found in file(s).  This tag file
21       allows these items to be quickly and easily located by a text editor or
22       other  utility.  A "tag" signifies a language object for which an index
23       entry is available (or, alternatively, the index entry created for that
24       object).
25
26       Alternatively,  ctags  can generate a cross reference file which lists,
27       in human readable form, information about the  various  source  objects
28       found in a set of language files.
29
30       Tag index files are supported by numerous editors, which allow the user
31       to locate the object associated with a name appearing in a source  file
32       and jump to the file and line which defines the name. Those known about
33       at the time of this release are:
34
35           Vi(1) and its derivatives (e.g. Elvis, Vim,  Vile,  Lemmy),  CRiSP,
36           Emacs, FTE (Folding Text Editor), JED, jEdit, Mined, NEdit (Nirvana
37           Edit), TSE (The SemWare Editor), UltraEdit, WorkSpace, X2, Zeus
38
39       Ctags is capable of generating different kinds of tags for each of many
40       different  languages.  For  a complete list of supported languages, the
41       names by which they are recognized, and the kinds  of  tags  which  are
42       generated for each, see the --list-languages and --list-kinds options.
43
44
45

SOURCE FILES

47       Unless  the  --language-force option is specified, the language of each
48       source file is automatically selected based  upon  a  mapping  of  file
49       names  to  languages.  The  mappings in effect for each language may be
50       display using the --list-maps option  and  may  be  changed  using  the
51       --langmap option.  On platforms which support it, if the name of a file
52       is not mapped to a language and the file is executable, the first  line
53       of the file is checked to see if the file is a "#!" script for a recog‐
54       nized language.
55
56       By default, all other files names are  ignored.  This  permits  running
57       ctags on all files in either a single directory (e.g. "ctags *"), or on
58       all files in an entire source directory tree (e.g. "ctags  -R"),  since
59       only those files whose names are mapped to languages will be scanned.
60
61       [The  reason  that  .h extensions are mapped to C++ files rather than C
62       files is because it is common to use .h extensions in C++, and no  harm
63       results in treating them as C++ files.]
64
65
66

OPTIONS

68       Despite the wealth of available options, defaults are set so that ctags
69       is most commonly executed without  any  options  (e.g.  "ctags  *",  or
70       "ctags  -R"), which will create a tag file in the current directory for
71       all recognized source files. The options described below  are  provided
72       merely to allow custom tailoring to meet special needs.
73
74       Note that spaces separating the single-letter options from their param‐
75       eters are optional.
76
77       Note also that the boolean parameters to the long form  options  (those
78       beginning with "--" and that take a "[=yes|no]" parameter) may be omit‐
79       ted, in which case "=yes" is implied. (e.g.  --sort  is  equivalent  to
80       --sort=yes).  Note  further that "=1" and "=on" are considered synonyms
81       for "=yes", and that "=0" and "=off" are considered synonyms for "=no".
82
83       Some options are either ignored or useful only when used while  running
84       in etags mode (see -e option). Such options will be noted.
85
86       Most  options  may  appear anywhere on the command line, affecting only
87       those files which follow the  option.  A  few  options,  however,  must
88       appear before the first file name and will be noted as such.
89
90       Options  taking  language names will accept those names in either upper
91       or lower case. See the --list-languages option for a complete  list  of
92       the built-in language names.
93
94
95       -a   Equivalent to --append.
96
97
98       -B   Use  backward  searching  patterns  (e.g.  ?pattern?). [Ignored in
99            etags mode]
100
101
102       -e   Enable etags mode, which will create a tag file for use  with  the
103            Emacs  editor.   Alternatively, if ctags is invoked by a name con‐
104            taining the string "etags" (either by renaming, or creating a link
105            to,  the executable), etags mode will be enabled. This option must
106            appear before the first file name.
107
108
109       -f tagfile
110            Use the name specified by tagfile for the  tag  file  (default  is
111            "tags", or "TAGS" when running in etags mode). If tagfile is spec‐
112            ified as "-", then the tag file  is  written  to  standard  output
113            instead.  Ctags  will  stubbornly refuse to take orders if tagfile
114            exists and its first line contains something other  than  a  valid
115            tags  line. This will save your neck if you mistakenly type "ctags
116            -f *.c", which would otherwise overwrite your first  C  file  with
117            the  tags  generated  by the rest! It will also refuse to accept a
118            multi-character file name which begins with a '-'  (dash)  charac‐
119            ter,  since  this most likely means that you left out the tag file
120            name and this option tried to grab the next  option  as  the  file
121            name.  If  you  really  want to name your output tag file "-ugly",
122            specify it as "./-ugly". This option must appear before the  first
123            file  name.  If  this option is specified more than once, only the
124            last will apply.
125
126
127       -F   Use  forward  searching  patterns  (e.g.   /pattern/)   (default).
128            [Ignored in etags mode]
129
130
131       -h list
132            Specifies  a  list of file extensions, separated by periods, which
133            are to be interpreted as include (or header)  files.  To  indicate
134            files  having  no  extension,  use a period not followed by a non-
135            period character  (e.g.  ".",  "..x",  ".x.").  This  option  only
136            affects  how  the  scoping of a particular kinds of tags is inter‐
137            preted (i.e. whether or not they are considered as globally  visi‐
138            ble or visible only within the file in which they are defined); it
139            does not map the extension to any  particular  language.  Any  tag
140            which  is  located  in a non-include file and cannot be seen (e.g.
141            linked to) from another file is considered  to  have  file-limited
142            (e.g.  static)  scope. No kind of tag appearing in an include file
143            will be considered to have file-limited scope. If the first  char‐
144            acter  in the list is a plus sign, then the extensions in the list
145            will be appended to the current list;  otherwise,  the  list  will
146            replace  the current list. See, also, the --file-scope option. The
147            default list  is  ".h.H.hh.hpp.hxx.h++.inc.def".  To  restore  the
148            default  list,  specify -h default. Note that if an extension sup‐
149            plied to this option is not already mapped to  a  particular  lan‐
150            guage  (see SOURCE FILES, above), you will also need to use either
151            the --langmap or --language-force option.
152
153
154       -I identifier-list
155            Specifies a list of identifiers which are to be specially  handled
156            while  parsing C and C++ source files. This option is specifically
157            provided to handle special cases arising through the use  of  pre‐
158            processor  macros.  When the identifiers listed are simple identi‐
159            fiers, these identifiers will be ignored  during  parsing  of  the
160            source  files.  If an identifier is suffixed with a '+' character,
161            ctags will also  ignore  any  parenthesis-enclosed  argument  list
162            which  may  immediately follow the identifier in the source files.
163            If two identifiers are separated with the '=' character, the first
164            identifiers is replaced by the second identifiers for parsing pur‐
165            poses. The list of identifiers may be  supplied  directly  on  the
166            command line or read in from a separate file. If the first charac‐
167            ter of identifier-list is '@', '.' or a pathname separator ('/' or
168            '\'),  or  the  first  two characters specify a drive letter (e.g.
169            "C:"), the parameter identifier-list  will  be  interpreted  as  a
170            filename  from  which to read a list of identifiers, one per input
171            line. Otherwise, identifier-list is  a  list  of  identifiers  (or
172            identifier  pairs)  to  be  specially handled, each delimited by a
173            either a comma or by white space (in which case the list should be
174            quoted to keep the entire list as one command line argument). Mul‐
175            tiple -I options may be supplied.  To clear  the  list  of  ignore
176            identifiers, supply a single dash ("-") for identifier-list.
177
178            This feature is useful when preprocessor macros are used in such a
179            way that they cause syntactic confusion  due  to  their  presence.
180            Indeed,  this  is the best way of working around a number of prob‐
181            lems caused by the presence of  syntax-busting  macros  in  source
182            files  (see  CAVEATS,  below).  Some examples will illustrate this
183            point.
184
185               int foo ARGDECL4(void *, ptr, long int, nbytes)
186
187
188            In the above example, the macro  "ARGDECL4"  would  be  mistakenly
189            interpreted  to be the name of the function instead of the correct
190            name of "foo". Specifying  -I  ARGDECL4  results  in  the  correct
191            behavior.
192
193               /* creates an RCS version string in module */
194               MODULE_VERSION("$Revision: 690 $")
195
196
197            In  the  above  example the macro invocation looks too much like a
198            function definition because it is  not  followed  by  a  semicolon
199            (indeed, it could even be followed by a global variable definition
200            that would look much like a K&R style function parameter  declara‐
201            tion).  In  fact,  this seeming function definition could possibly
202            even cause the rest of the file to be skipped over while trying to
203            complete the definition. Specifying -I MODULE_VERSION+ would avoid
204            such a problem.
205
206               CLASS Example {
207                   // your content here
208               };
209
210
211            The example above uses  "CLASS"  as  a  preprocessor  macro  which
212            expands  to  something  different  for each platform. For instance
213            CLASS may be defined as  "class  __declspec(dllexport)"  on  Win32
214            platforms  and  simply  "class" on UNIX.  Normally, the absence of
215            the C++ keyword "class" would cause the source file to  be  incor‐
216            rectly  parsed.  Correct behavior can be restored by specifying -I
217            CLASS=class.
218
219
220       -L file
221            Read from file a list of file names for which tags should be  gen‐
222            erated.   If  file  is  specified as "-", then file names are read
223            from standard input. File names read using this  option  are  pro‐
224            cessed following file names appearing on the command line. Options
225            are also accepted in this input. If this option is specified  more
226            than  once,  only the last will apply. Note: file is read in line-
227            oriented mode, where a new line is the  only  delimiter  and  non-
228            trailing white space is considered significant, in order that file
229            names containing spaces may be supplied (however,  trailing  white
230            space  is  stripped  from  lines); this can affect how options are
231            parsed if included in the input.
232
233
234       -n   Equivalent to --excmd=number.
235
236
237       -N   Equivalent to --excmd=pattern.
238
239
240       -o tagfile
241            Equivalent to -f tagfile.
242
243
244       -R   Equivalent to --recurse.
245
246
247       -u   Equivalent to --sort=no (i.e. "unsorted").
248
249
250       -V   Equivalent to --verbose.
251
252
253       -w   This option is silently ignored  for  backward-compatibility  with
254            the ctags of SVR4 Unix.
255
256
257       -x   Print  a  tabular,  human-readable  cross reference (xref) file to
258            standard output instead of generating a tag file. The  information
259            contained  in  the output includes: the tag name; the kind of tag;
260            the line number, file name, and  source  line  (with  extra  white
261            space condensed) of the file which defines the tag. No tag file is
262            written and all options affecting tag file output will be ignored.
263            Example  applications for this feature are generating a listing of
264            all functions located in a source file (e.g. ctags -x  --c-kinds=f
265            file), or generating a list of all externally visible global vari‐
266            ables  located  in  a  source  file  (e.g.  ctags  -x  --c-kinds=v
267            --file-scope=no  file).  This  option must appear before the first
268            file name.
269
270
271       --append[=yes|no]
272            Indicates whether tags generated from the specified  files  should
273            be  appended  to  those  already present in the tag file or should
274            replace them. This option is off  by  default.  This  option  must
275            appear before the first file name.
276
277
278       --etags-include=file
279            Include  a  reference  to file in the tag file. This option may be
280            specified as many times as desired. This supports Emacs'  capabil‐
281            ity to use a tag file which "includes" other tag files. [Available
282            only in etags mode]
283
284
285       --exclude=[pattern]
286            Add pattern to a list of  excluded  files  and  directories.  This
287            option  may  be  specified as many times as desired. For each file
288            name considered by ctags, each pattern specified using this option
289            will   be   compared   against   both   the  complete  path  (e.g.
290            some/path/base.ext) and the base name (e.g. base.ext) of the file,
291            thus  allowing patterns which match a given file name irrespective
292            of its path, or match only a specific path. If appropriate support
293            is  available  from  the  runtime library of your C compiler, then
294            pattern may contain the usual shell wildcards (not regular expres‐
295            sions)  common  on  Unix (be sure to quote the option parameter to
296            protect the wildcards from being  expanded  by  the  shell  before
297            being  passed to ctags; also be aware that wildcards can match the
298            slash character, '/'). You can determine if  shell  wildcards  are
299            available  on  your platform by examining the output of the --ver‐
300            sion option, which will include "+wildcards" in the compiled  fea‐
301            ture  list; otherwise, pattern is matched against file names using
302            a simple textual comparison.
303
304            If pattern begins with the character '@', then  the  rest  of  the
305            string  is interpreted as a file name from which to read exclusion
306            patterns, one per line. If pattern is empty, the list of  excluded
307            patterns  is  cleared.   Note that at program startup, the default
308            exclude list contains "EIFGEN", "SCCS", "RCS",  and  "CVS",  which
309            are  names  of directories for which it is generally not desirable
310            to descend while processing the --recurse option.
311
312
313       --excmd=type
314            Determines the type of EX command  used  to  locate  tags  in  the
315            source file.  [Ignored in etags mode]
316
317            The  valid  values  for  type (either the entire word or the first
318            letter is accepted) are:
319
320
321            number   Use only line numbers in the tag file for locating  tags.
322                     This has four advantages:
323                     1.  Significantly  reduces  the size of the resulting tag
324                         file.
325                     2.  Eliminates failures to find  tags  because  the  line
326                         defining  the  tag  has  changed, causing the pattern
327                         match to fail (note that some editors, such  as  vim,
328                         are able to recover in many such instances).
329                     3.  Eliminates finding identical matching, but incorrect,
330                         source lines (see BUGS, below).
331                     4.  Retains separate entries in the tag  file  for  lines
332                         which  are  identical  in  content.  In pattern mode,
333                         duplicate entries are dropped because the search pat‐
334                         terns  they generate are identical, making the dupli‐
335                         cate entries useless.
336
337
338                     However,  this  option  has  one  significant   drawback:
339                     changes  to  the  source files can cause the line numbers
340                     recorded in the tag file to no longer correspond  to  the
341                     lines  in  the source file, causing jumps to some tags to
342                     miss the target definition by one or  more  lines.  Basi‐
343                     cally,  this  option is best used when the source code to
344                     which it is applied is not subject to  change.  Selecting
345                     this  option  type  causes  the  following  options to be
346                     ignored: -BF.
347
348
349            pattern  Use only search patterns for all tags,  rather  than  the
350                     line numbers usually used for macro definitions. This has
351                     the advantage of not referencing  obsolete  line  numbers
352                     when  lines have been added or removed since the tag file
353                     was generated.
354
355
356            mixed    In this mode, patterns are  generally  used  with  a  few
357                     exceptions.  For C, line numbers are used for macro defi‐
358                     nition tags. This was the default format generated by the
359                     original ctags and is, therefore, retained as the default
360                     for this option. For Fortran, line numbers are  used  for
361                     common  blocks  because  their corresponding source lines
362                     are generally identical, making pattern searches  useless
363                     for finding all matches.
364
365
366       --extra=[+|-]flags
367            Specifies  whether  to include extra tag entries for certain kinds
368            of information. The parameter flags is a set of one-letter  flags,
369            each  representing  one  kind of extra tag entry to include in the
370            tag file. If flags is preceded by by either the '+' or '-' charac‐
371            ter,  the  effect of each flag is added to, or removed from, those
372            currently enabled; otherwise the flags replace  any  current  set‐
373            tings. The meaning of each flag is as follows:
374
375
376               f   Include  an  entry  for  the base file name of every source
377                   file (e.g.  "example.c"), which addresses the first line of
378                   the file.
379
380               q   Include  an  extra  class-qualified  tag entry for each tag
381                   which is a member of a class (for languages for which  this
382                   information is extracted; currently C++, Eiffel, and Java).
383                   The actual form of the qualified tag depends upon the  lan‐
384                   guage  from which the tag was derived (using a form that is
385                   most natural for how qualified calls are specified  in  the
386                   language).  For C++, it is in the form "class::member"; for
387                   Eiffel and Java, it is in the form "class.member". This may
388                   allow  easier  location  of  a  specific tags when multiple
389                   occurrences of a tag name occur in the tag file. Note, how‐
390                   ever, that this could potentially more than double the size
391                   of the tag file.
392
393
394       --fields=[+|-]flags
395            Specifies the available extension fields which are to be  included
396            in  the  entries  of the tag file (see TAG FILE FORMAT, below, for
397            more information). The parameter flags  is  a  set  of  one-letter
398            flags,  each  representing one type of extension field to include,
399            with the following meanings  (disabled  by  default  unless  indi‐
400            cated):
401
402
403               a   Access (or export) of class members
404               f   File-restricted scoping [enabled]
405               i   Inheritance information
406               k   Kind of tag as a single letter [enabled]
407               K   Kind of tag as full name
408               l   Language of source file containing tag
409               m   Implementation information
410               n   Line number of tag definition
411               s   Scope of tag definition [enabled]
412               S   Signature of routine (e.g. prototype or parameter list)
413               z   Include the "kind:" key in kind field
414               t   Type  and name of a variable or typedef as "typeref:" field
415                   [enabled]
416
417            Each letter or group of letters may be preceded by either  '+'  to
418            add it to the default set, or '-' to exclude it. In the absence of
419            any preceding '+' or '-' sign, only those kinds explicitly  listed
420            in  flags  will  be  included  in  the output (i.e. overriding the
421            default set). This option is ignored if the option --format=1  has
422            been specified. The default value of this option is fkst.
423
424
425       --file-scope[=yes|no]
426            Indicates  whether  tags  scoped only for a single file (i.e. tags
427            which cannot be seen  outside  of  the  file  in  which  they  are
428            defined,  such as "static" tags) should be included in the output.
429            See, also, the -h option. This option is enabled by default.
430
431
432       --filter[=yes|no]
433            Causes ctags to behave as a filter, reading source file names from
434            standard  input  and  printing  their tags to standard output on a
435            file-by-file basis. If --sorted is enabled, tags are  sorted  only
436            within  the  source file in which they are defined. File names are
437            read from standard input in line-oriented input mode (see note for
438            -L option) and only after file names listed on the command line or
439            from any file supplied using the -L option. When  this  option  is
440            enabled, the options -f, -o, and --totals are ignored. This option
441            is quite esoteric and is disabled by  default.  This  option  must
442            appear before the first file name.
443
444
445       --filter-terminator=string
446            Specifies  a string to print to standard output following the tags
447            for each file name parsed when the  --filter  option  is  enabled.
448            This  may  permit  an  application  reading the output of ctags to
449            determine when the output for each file is finished. Note that  if
450            the  file  name read is a directory and --recurse is enabled, this
451            string will be printed only one once at the end of all tags  found
452            for  by descending the directory. This string will always be sepa‐
453            rated from the last tag line for the file by its terminating  new‐
454            line.  This option is quite esoteric and is empty by default. This
455            option must appear before the first file name.
456
457
458       --format=level
459            Change the format of the output tag file. Currently the only valid
460            values  for  level  are 1 or 2. Level 1 specifies the original tag
461            file format and level 2 specifies a new extended format containing
462            extension  fields (but in a manner which retains backward-compati‐
463            bility with original vi(1) implementations). The default level  is
464            2. This option must appear before the first file name. [Ignored in
465            etags mode]
466
467
468       --help
469            Prints to standard output a detailed usage description,  and  then
470            exits.
471
472
473       --if0[=yes|no]
474            Indicates a preference as to whether code within an "#if 0" branch
475            of a preprocessor conditional should  be  examined  for  non-macro
476            tags  (macro tags are always included). Because the intent of this
477            construct is to disable code, the default value of this option  is
478            no.  Note that this indicates a preference only and does not guar‐
479            antee skipping code within an "#if 0" branch, since the  fall-back
480            algorithm used to generate tags when preprocessor conditionals are
481            too complex follows all branches of a conditional. This option  is
482            disabled by default.
483
484
485       --<LANG>-kinds=[+|-]kinds
486            Specifies  a list of language-specific kinds of tags (or kinds) to
487            include in the output file for a particular language, where <LANG>
488            is case-insensitive and is one of the built-in language names (see
489            the --list-languages option for a complete  list).  The  parameter
490            kinds  is  a  group  of one-letter flags designating kinds of tags
491            (particular to the language) to either include or exclude from the
492            output.  The  specific sets of flags recognized for each language,
493            their meanings and defaults may be  list  using  the  --list-kinds
494            option.  Each letter or group of letters may be preceded by either
495            '+' to add it to, or '-' to remove it from, the  default  set.  In
496            the  absence  of  any  preceding '+' or '-' sign, only those kinds
497            explicitly listed in kinds will be included in  the  output  (i.e.
498            overriding the default for the specified language).
499
500            As  an  example for the C language, in order to add prototypes and
501            external variable declarations to the default set  of  tag  kinds,
502            but  exclude macros, use --c-kinds=+px-d; to include only tags for
503            functions, use --c-kinds=f.
504
505
506       --langdef=name
507            Defines a new user-defined language, name, to be parsed with regu‐
508            lar  expressions.  Once defined, name may be used in other options
509            taking language names. The typical use of this option is to  first
510            define  the  language,  then map file names to it using --langmap,
511            then specify regular expressions using  --regex-<LANG>  to  define
512            how its tags are found.
513
514
515       --langmap=map[,map[...]]
516            Controls   how  file  names  are  mapped  to  languages  (see  the
517            --list-maps option). Each comma-separated map consists of the lan‐
518            guage  name (either a built-in or user-defined language), a colon,
519            and a list of file extensions and/or file name  patterns.  A  file
520            extension  is  specified  by preceding the extension with a period
521            (e.g. ".c"). A file name pattern is  specified  by  enclosing  the
522            pattern in parentheses (e.g. "([Mm]akefile)"). If appropriate sup‐
523            port is available from the runtime library  of  your  C  compiler,
524            then  the  file name pattern may contain the usual shell wildcards
525            common on Unix (be sure to quote the option parameter  to  protect
526            the wildcards from being expanded by the shell before being passed
527            to ctags). You can determine if shell wildcards are  available  on
528            your  platform  by  examining  the output of the --version option,
529            which will include "+wildcards" in the compiled feature list; oth‐
530            erwise,  the  file  name  patterns  are matched against file names
531            using a simple textual comparison. When mapping a file  extension,
532            it will first be unmapped from any other languages.
533
534            If  the  first  character in a map is a plus sign, then the exten‐
535            sions and file name patterns in that map will be appended  to  the
536            current map for that language; otherwise, the map will replace the
537            current map. For example, to specify that only files  with  exten‐
538            sions  of  .c  and  .x  are to be treated as C language files, use
539            "--langmap=c:.c.x"; to also add files with  extensions  of  .j  as
540            Java  language  files, specify "--langmap=c:.c.x,java:+.j". To map
541            makefiles (e.g. files named either "Makefile", "makefile", or hav‐
542            ing  the  extension  ".mak")  to a language called "make", specify
543            "--langmap=make:([Mm]akefile).mak".  To map files having no exten‐
544            sion,  specify  a  period  not  followed by a non-period character
545            (e.g. ".", "..x", ".x."). To clear the mapping  for  a  particular
546            language  (thus  inhibiting  automatic generation of tags for that
547            language), specify an empty extension list (e.g.   "--langmap=for‐
548            tran:").  To  restore the default language mappings for all a par‐
549            ticular language, supply the keyword "default"  for  the  mapping.
550            To  specify  restore  the  default  language mappings for all lan‐
551            guages, specify "--langmap=default". Note that file extensions are
552            tested  before file name patterns when inferring the language of a
553            file.
554
555
556       --language-force=language
557            By default, ctags automatically selects the language of  a  source
558            file,  ignoring  those  files  whose language cannot be determined
559            (see SOURCE FILES, above). This option forces the  specified  lan‐
560            guage  (case-insensitive;  either  built-in or user-defined) to be
561            used for every supplied file instead  of  automatically  selecting
562            the  language  based  upon its extension. In addition, the special
563            value auto indicates that the  language  should  be  automatically
564            selected (which effectively disables this option).
565
566
567       --languages=[+|-]list
568            Specifies  the languages for which tag generation is enabled, with
569            list containing a comma-separated list of  language  names  (case-
570            insensitive;  either  built-in or user-defined). If the first lan‐
571            guage of list is not preceded by either a '+' or '-', the  current
572            list  will  be  cleared before adding or removing the languages in
573            list. Until a '-' is encountered, each language in the  list  will
574            be  added to the current list. As either the '+' or '-' is encoun‐
575            tered in the list, the languages following it are added or removed
576            from  the  current  list, respectively. Thus, it becomes simple to
577            replace the current list with a new one, or to add or remove  lan‐
578            guages  from  the current list. The actual list of files for which
579            tags will be generated depends upon the language extension mapping
580            in  effect  (see  the  --langmap option). Note that all languages,
581            including user-defined languages  are  enabled  unless  explicitly
582            disabled using this option. Language names included in list may be
583            any built-in language or one previously  defined  with  --langdef.
584            The  default is "all", which is also accepted as a valid argument.
585            See the --list-languages option for a complete list of the  built-
586            in language names.
587
588
589       --license
590            Prints  a  summary of the software license to standard output, and
591            then exits.
592
593
594       --line-directives[=yes|no]
595            Specifies whether "#line" directives should be  recognized.  These
596            are  present  in  the output of preprocessors and contain the line
597            number, and possibly the file name, of the original source file(s)
598            from  which  the  preprocessor  output  file  was  generated. When
599            enabled, this option will cause  ctags  to  generate  tag  entries
600            marked  with  the  file  names and line numbers of their locations
601            original source file(s), instead of their actual locations in  the
602            preprocessor  output.  The  actual  file names placed into the tag
603            file will have the same leading path components as the  preproces‐
604            sor  output  file,  since  it  is assumed that the original source
605            files  are  located  relative  to  the  preprocessor  output  file
606            (unless,  of  course,  the  #line  directive specifies an absolute
607            path). This option is off by default. Note: This option is  gener‐
608            ally  only  useful when used together with the --excmd=number (-n)
609            option. Also, you may have to use either the --langmap  or  --lan‐
610            guage-force  option  if  the  extension of the preprocessor output
611            file is not known to ctags.
612
613
614       --links[=yes|no]
615            Indicates whether symbolic links (if  supported)  should  be  fol‐
616            lowed.  When  disabled, symbolic links are ignored. This option is
617            on by default.
618
619
620       --list-kinds[=language|all]
621            Lists the tag kinds recognized for either the  specified  language
622            or all languages, and then exits. Each kind of tag recorded in the
623            tag file is represented by a one-letter flag, which is  also  used
624            to  filter  the  tags  placed  into  the output through use of the
625            --<LANG>-kinds option. Note that some languages and/or  tag  kinds
626            may be implemented using regular expressions and may not be avail‐
627            able if  regex  support  is  not  compiled  into  ctags  (see  the
628            --regex-<LANG>  option).  Each  kind listed is enabled unless fol‐
629            lowed by "[off]".
630
631
632       --list-maps[=language|all]
633            Lists the file extensions and file name patterns which associate a
634            file name with a language for either the specified language or all
635            languages, and then exits. See the --langmap  option,  and  SOURCE
636            FILES, above.
637
638
639       --list-languages
640            Lists  the  names  of  the languages understood by ctags, and then
641            exits.  These language names are case insensitive and may be  used
642            in   the   --language-force,   --languages,   --<LANG>-kinds,  and
643            --regex-<LANG> options.
644
645
646       --options=file
647            Read additional options from file. The  file  should  contain  one
648            option per line. As a special case, if --options=NONE is specified
649            as the first option on the command line, it will disable the auto‐
650            matic  reading  of any configuration options from either a file or
651            the environment (see FILES).
652
653
654       --recurse[=yes|no]
655            Recurse into directories  encountered  in  the  list  of  supplied
656            files.  If the list of supplied files is empty and no file list is
657            specified with the -L option, then  the  current  directory  (i.e.
658            ".")  is  assumed.  Symbolic links are followed. If you don't like
659            these behaviors, either explicitly specify the files or  pipe  the
660            output of find(1) into ctags -L- instead. Note: This option is not
661            supported on all platforms at present.  It  is  available  if  the
662            output  of the --help option includes this option.  See, also, the
663            --exclude to limit recursion.
664
665
666       --regex-<LANG>=/regexp/replacement/[kind-spec/][flags]
667            The /regexp/replacement/ pair define a regular expression replace‐
668            ment  pattern, similar in style to sed substitution commands, with
669            which to generate tags from source files mapped to the named  lan‐
670            guage,  <LANG>,  (case-insensitive;  either  a  built-in  or user-
671            defined language). The  regular  expression,  regexp,  defines  an
672            extended regular expression (roughly that used by egrep(1)), which
673            is used to locate a single source line containing a  tag  and  may
674            specify  tab characters using \t. When a matching line is found, a
675            tag will be generated for the name defined by  replacement,  which
676            generally  will  contain the special back-references \1 through \9
677            to refer to matching sub-expression groups within regexp. The  '/'
678            separator  characters  shown  in  the  parameter to the option can
679            actually be replaced by any character. Note that whichever separa‐
680            tor  character  is  used  will have to be escaped with a backslash
681            ('\') character wherever it is used in the parameter as  something
682            other  than  a  separator.  The regular expression defined by this
683            option is added to the current list of regular expressions for the
684            specified  language unless the parameter is omitted, in which case
685            the current list is cleared.
686
687            Unless modified  by  flags,  regexp  is  interpreted  as  a  Posix
688            extended regular expression. The replacement should expand for all
689            matching lines to a non-empty string of characters, or  a  warning
690            message  will  be  reported.  An  optional kind specifier for tags
691            matching regexp may follow replacement, which will determine  what
692            kind  of  tag  is  reported in the "kind" extension field (see TAG
693            FILE FORMAT, below). The full form of kind-spec is in the form  of
694            a  single  letter,  a  comma,  a name (without spaces), a comma, a
695            description, followed by a separator, which specify the short  and
696            long  forms  of  the  kind value and its textual description (dis‐
697            played using  --list-kinds).  Either  the  kind  name  and/or  the
698            description  may  be omitted. If kind-spec is omitted, it defaults
699            to "r,regex". Finally, flags are one or more single-letter charac‐
700            ters  having  the following effect upon the interpretation of reg‐
701            exp:
702
703
704               b   The pattern is interpreted as a Posix basic regular expres‐
705                   sion.
706
707               e   The  pattern  is  interpreted  as  a Posix extended regular
708                   expression (default).
709
710               i   The regular expression is to be applied in a  case-insensi‐
711                   tive manner.
712
713            Note that this option is available only if ctags was compiled with
714            support for regular expressions, which depends upon your platform.
715            You  can  determine if support for regular expressions is compiled
716            in by examining the output of the  --version  option,  which  will
717            include "+regex" in the compiled feature list.
718
719            For more information on the regular expressions used by ctags, see
720            either the regex(5,7) man page, or the GNU info documentation  for
721            regex (e.g. "info regex").
722
723
724       --sort[=yes|no|foldcase]
725            Indicates  whether  the  tag file should be sorted on the tag name
726            (default is yes). Note that the  original  vi(1)  required  sorted
727            tags.   The  foldcase  value  specifies case insensitive (or case-
728            folded) sorting.  Fast binary searches of tag  files  sorted  with
729            case-folding  will  require  special  support from tools using tag
730            files, such as that found in the ctags readtags  library,  or  Vim
731            version  6.2  or higher (using "set ignorecase"). This option must
732            appear before the first file name. [Ignored in etags mode]
733
734
735       --tag-relative[=yes|no]
736            Indicates that the file paths recorded in the tag file  should  be
737            relative  to  the  directory  containing the tag file, rather than
738            relative to the current directory, unless the  files  supplied  on
739            the  command  line  are specified with absolute paths. This option
740            must appear before the first file name. The default  is  yes  when
741            running in etags mode (see the -e option), no otherwise.
742
743
744       --totals[=yes|no]
745            Prints  statistics  about  the  source files read and the tag file
746            written during the current invocation of ctags. This option is off
747            by default.  This option must appear before the first file name.
748
749
750       --verbose[=yes|no]
751            Enable  verbose  mode.  This prints out information on option pro‐
752            cessing and a brief message describing what action is being  taken
753            for  each  file considered by ctags. Normally, ctags does not read
754            command line arguments until after options are read from the  con‐
755            figuration  files  (see  FILES,  below)  and the CTAGS environment
756            variable. However, if this option is the  first  argument  on  the
757            command line, it will take effect before any options are read from
758            these sources. The default is no.
759
760
761       --version
762            Prints a version identifier for ctags to standard output, and then
763            exits.  This is guaranteed to always contain the string "Exuberant
764            Ctags".
765
766
767

OPERATIONAL DETAILS

769       As ctags considers each file name in turn, it tries  to  determine  the
770       language of the file by applying the following three tests in order: if
771       the file extension has been mapped to a  language,  if  the  file  name
772       matches  a  shell pattern mapped to a language, and finally if the file
773       is executable and its first line specifies  an  interpreter  using  the
774       Unix-style "#!" specification (if supported on the platform). If a lan‐
775       guage was identified, the file is opened and then the appropriate  lan‐
776       guage  parser  is  called  to  operate  on the currently open file. The
777       parser parses through the file and adds an entry to the  tag  file  for
778       each  language  object  it  is  written to handle. See TAG FILE FORMAT,
779       below, for details on these entries.
780
781       This implementation of ctags imposes no formatting  requirements  on  C
782       code  as  do  legacy  implementations.  Older  implementations of ctags
783       tended to rely upon certain formatting assumptions in order to help  it
784       resolve coding dilemmas caused by preprocessor conditionals.
785
786       In  general,  ctags  tries  to  be smart about conditional preprocessor
787       directives. If a  preprocessor  conditional  is  encountered  within  a
788       statement  which  defines a tag, ctags follows only the first branch of
789       that conditional (except in the special case of "#if 0", in which  case
790       it  follows  only the last branch). The reason for this is that failing
791       to pursue only one branch can result in ambiguous  syntax,  as  in  the
792       following example:
793
794              #ifdef TWO_ALTERNATIVES
795              struct {
796              #else
797              union {
798              #endif
799                  short a;
800                  long b;
801              }
802
803       Both branches cannot be followed, or braces become unbalanced and ctags
804       would be unable to make sense of the syntax.
805
806       If the application of this heuristic fails to properly  parse  a  file,
807       generally due to complicated and inconsistent pairing within the condi‐
808       tionals, ctags will retry the file using a  different  heuristic  which
809       does  not  selectively  follow  conditional  preprocessor branches, but
810       instead falls back to relying upon a closing brace ("}") in column 1 as
811       indicating  the  end  of  a block once any brace imbalance results from
812       following a #if conditional branch.
813
814       Ctags will also try to specially handle  arguments  lists  enclosed  in
815       double sets of parentheses in order to accept the following conditional
816       construct:
817
818              extern void foo __ARGS((int one, char two));
819
820       Any name immediately preceding the "((" will be  automatically  ignored
821       and the previous name will be used.
822
823       C++  operator  definitions  are specially handled. In order for consis‐
824       tency with all types of  operators  (overloaded  and  conversion),  the
825       operator  name  in  the  tag file will always be preceded by the string
826       "operator " (i.e. even if the actual operator definition was written as
827       "operator<<").
828
829       After  creating  or  appending to the tag file, it is sorted by the tag
830       name, removing identical tag lines.
831
832
833

TAG FILE FORMAT

835       When not running in etags mode, each entry in the tag file consists  of
836       a separate line, each looking like this in the most general case:
837
838        tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields
839
840       The fields and separators of these lines are specified as follows:
841
842           1.  tag name
843           2.  single tab character
844           3.  name of the file in which the object associated with the tag is
845               located
846           4.  single tab character
847           5.  EX command used to locate the tag within the file; generally  a
848               search  pattern  (either /pattern/ or ?pattern?) or line number
849               (see --excmd). Tag file format 2 (see --format) extends this EX
850               command  under certain circumstances to include a set of exten‐
851               sion fields (described below) embedded in an EX comment immedi‐
852               ately appended to the EX command, which leaves it backward-com‐
853               patible with original vi(1) implementations.
854
855       A few special tags are written into the tag file for internal purposes.
856       These  tags are composed in such a way that they always sort to the top
857       of the file.  Therefore, the first two characters  of  these  tags  are
858       used  a  magic  number to detect a tag file for purposes of determining
859       whether a valid tag file is being  overwritten  rather  than  a  source
860       file.
861
862       Note that the name of each source file will be recorded in the tag file
863       exactly as it appears on the command line. Therefore, if the  path  you
864       specified  on  the  command line was relative to the current directory,
865       then it will be recorded in that same manner in the tag file. See, how‐
866       ever, the --tag-relative option for how this behavior can be modified.
867
868       Extension  fields are tab-separated key-value pairs appended to the end
869       of the EX command as a comment, as described  above.  These  key  value
870       pairs  appear  in  the  general form "key:value". Their presence in the
871       lines of the tag file are controlled by the --fields option. The possi‐
872       ble keys and the meaning of their values are as follows:
873
874
875       access      Indicates  the visibility of this class member, where value
876                   is specific to the language.
877
878
879       file        Indicates that the tag has  file-limited  visibility.  This
880                   key has no corresponding value.
881
882
883       kind        Indicates  the  type,  or kind, of tag. Its value is either
884                   one of the corresponding one-letter flags  described  under
885                   the  various  --<LANG>-kinds options above, or a full name.
886                   It is permitted (and is, in fact, the default) for the  key
887                   portion of this field to be omitted. The optional behaviors
888                   are controlled with the --fields option.
889
890
891       implementation
892                   When  present,  this  indicates  a  limited  implementation
893                   (abstract  vs. concrete) of a routine or class, where value
894                   is specific to the language ("virtual"  or  "pure  virtual"
895                   for C++; "abstract" for Java).
896
897
898       inherits    When  present,  value. is a comma-separated list of classes
899                   from which this class is derived (i.e. inherits from).
900
901
902       signature   When present, value is a language-dependent  representation
903                   of  the  signature of a routine. A routine signature in its
904                   complete form specifies the return type of  a  routine  and
905                   its formal argument list. This extension field is presently
906                   supported only for C-based languages and does  not  include
907                   the return type.
908
909
910       In  addition,  information  on  the  scope of the tag definition may be
911       available, with the key portion equal to some  language-dependent  con‐
912       struct  name  and its value the name declared for that construct in the
913       program. This scope entry indicates the scope  in  which  the  tag  was
914       found. For example, a tag generated for a C structure member would have
915       a scope looking like "struct:myStruct".
916
917
918

HOW TO USE WITH VI

920       Vi will, by default, expect a tag file by the name "tags" in  the  cur‐
921       rent  directory.  Once  the  tag  file is built, the following commands
922       exercise the tag indexing feature:
923
924       vi -t tag   Start vi and position the cursor at the file and line where
925                   "tag" is defined.
926
927       :ta tag     Find a tag.
928
929       Ctrl-]      Find the tag under the cursor.
930
931       Ctrl-T      Return  to previous location before jump to tag (not widely
932                   implemented).
933
934
935

HOW TO USE WITH GNU EMACS

937       Emacs will, by default, expect a tag file by the  name  "TAGS"  in  the
938       current  directory.  Once the tag file is built, the following commands
939       exercise the tag indexing feature:
940
941       M-x visit-tags-table <RET> FILE <RET>
942                 Select the tag file, "FILE", to use.
943
944       M-. [TAG] <RET>
945                 Find the first definition of TAG.  The  default  tag  is  the
946                 identifier under the cursor.
947
948       M-*       Pop back to where you previously invoked "M-.".
949
950       C-u M-.   Find the next definition for the last tag.
951
952
953       For more commands, see the Tags topic in the Emacs info document.
954
955
956

HOW TO USE WITH NEDIT

958       NEdit version 5.1 and later can handle the new extended tag file format
959       (see --format). To make NEdit use the tag file, select "File->Load Tags
960       File".  To  jump  to  the definition for a tag, highlight the word, the
961       press Ctrl-D. NEdit 5.1 can can read multiple tag files from  different
962       directories.  Setting the X resource nedit.tagFile to the name of a tag
963       file instructs NEdit to automatically load that  tag  file  at  startup
964       time.
965
966
967

CAVEATS

969       Because  ctags  is  neither  a preprocessor nor a compiler, use of pre‐
970       processor macros can fool ctags into either missing tags or  improperly
971       generating inappropriate tags. Although ctags has been designed to han‐
972       dle certain common cases, this is the single biggest cause of  reported
973       problems. In particular, the use of preprocessor constructs which alter
974       the textual syntax of C can fool ctags. You can work around  many  such
975       problems by using the -I option.
976
977       Note  that  since  ctags  generates patterns for locating tags (see the
978       --excmd option), it is entirely possible that the  wrong  line  may  be
979       found by your editor if there exists another source line which is iden‐
980       tical to the line containing the  tag.  The  following  example  demon‐
981       strates this condition:
982
983              int variable;
984
985              /* ... */
986              void foo(variable)
987              int variable;
988              {
989                  /* ... */
990              }
991
992       Depending upon which editor you use and where in the code you happen to
993       be, it is possible that the search pattern may locate the local parame‐
994       ter  declaration  in  foo()  before it finds the actual global variable
995       definition, since the lines (and therefore their  search  patterns  are
996       identical). This can be avoided by use of the --excmd=n option.
997
998
999

BUGS

1001       Ctags has more options than ls(1).
1002
1003       When  parsing  a C++ member function definition (e.g. "className::func‐
1004       tion"), ctags cannot determine whether the scope specifier is  a  class
1005       name  or  a  namespace specifier and always lists it as a class name in
1006       the scope portion of the extension fields. Also, if a C++  function  is
1007       defined  outside  of the class declaration (the usual case), the access
1008       specification (i.e. public, protected, or private)  and  implementation
1009       information (e.g. virtual, pure virtual) contained in the function dec‐
1010       laration are not known when the tag is generated for the function defi‐
1011       nition.   It   will,   however   be   available   for  prototypes  (e.g
1012       --c++-kinds=+p).
1013
1014       No qualified tags are generated for language objects inherited  into  a
1015       class.
1016
1017
1018

ENVIRONMENT VARIABLES

1020       CTAGS   If  this  environment  variable  exists, it will be expected to
1021               contain a set of default options  which  are  read  when  ctags
1022               starts,  after  the configuration files listed in FILES, below,
1023               are read, but before any command line options are read. Options
1024               appearing  on  the command line will override options specified
1025               in this variable. Only options will be read from this variable.
1026               Note that all white space in this variable is considered a sep‐
1027               arator, making it impossible to pass an option  parameter  con‐
1028               taining an embedded space. If this is a problem, use a configu‐
1029               ration file instead.
1030
1031
1032       ETAGS   Similar to the CTAGS variable above, this variable,  if  found,
1033               will  be read when etags starts. If this variable is not found,
1034               etags will try to use CTAGS instead.
1035
1036
1037       TMPDIR  On Unix-like hosts where mkstemp() is available, the  value  of
1038               this  variable specifies the directory in which to place tempo‐
1039               rary files. This can be useful if the size of a temporary  file
1040               becomes  too  large to fit on the partition holding the default
1041               temporary directory defined at compilation time.  ctags creates
1042               temporary  files  only if either (1) an emacs-style tag file is
1043               being generated, (2) the tag file is  being  sent  to  standard
1044               output, or (3) the program was compiled to use an internal sort
1045               algorithm to sort the tag files instead of the the sort utility
1046               of  the  operating system. If the sort utility of the operating
1047               system is being used, it will generally observe  this  variable
1048               also. Note that if ctags is setuid, the value of TMPDIR will be
1049               ignored.
1050
1051
1052

FILES

1054       /ctags.cnf (on MSDOS, MSWindows only)
1055       /etc/ctags.conf
1056       /usr/local/etc/ctags.conf
1057       $HOME/.ctags
1058       $HOME/ctags.cnf (on MSDOS, MSWindows only)
1059       .ctags
1060       ctags.cnf (on MSDOS, MSWindows only)
1061              If any of these configuration files exist, each will be expected
1062              to  contain a set of default options which are read in the order
1063              listed when ctags starts, but before the CTAGS environment vari‐
1064              able is read or any command line options are read. This makes it
1065              possible  to  set  up  site-wide,  personal   or   project-level
1066              defaults.  It is possible to compile ctags to read an additional
1067              configuration file before any of those shown above,  which  will
1068              be  indicated  if  the  output  produced by the --version option
1069              lists the "custom-conf" feature. Options appearing in the  CTAGS
1070              environment  variable  or  on  the  command  line  will override
1071              options specified in these files. Only options will be read from
1072              these  files.  Note  that the option files are read in line-ori‐
1073              ented mode in which spaces are significant (since shell  quoting
1074              is  not  possible). Each line of the file is read as one command
1075              line parameter (as if it were quoted with single quotes). There‐
1076              fore, use new lines to indicate separate command-line arguments.
1077
1078
1079       tags   The default tag file created by ctags.
1080
1081       TAGS   The default tag file created by etags.
1082
1083

SEE ALSO

1085       The official Exuberant Ctags web site at:
1086
1087              http://ctags.sourceforge.net
1088
1089       Also  ex(1),  vi(1), elvis, or, better yet, vim, the official editor of
1090       ctags. For more information on vim, see the VIM Pages web site at:
1091
1092              http://www.vim.org/
1093
1094
1095

AUTHOR

1097       Darren Hiebert <dhiebert at users.sourceforge.net>
1098       http://DarrenHiebert.com/
1099
1100
1101

MOTIVATION

1103       "Think ye at all times of rendering some service to every member of the
1104       human race."
1105
1106       "All  effort  and  exertion  put  forth by man from the fullness of his
1107       heart is worship, if it is prompted by the highest motives and the will
1108       to do service to humanity."
1109
1110              -- From the Baha'i Writings
1111
1112
1113

CREDITS

1115       This  version  of ctags was originally derived from and inspired by the
1116       ctags program by Steve Kirkendall <kirkenda@cs.pdx.edu> that comes with
1117       the  Elvis  vi  clone  (though  virtually  none  of  the  original code
1118       remains).
1119
1120       Credit is also due Bram Moolenaar <Bram@vim.org>, the  author  of  vim,
1121       who  has  devoted so much of his time and energy both to developing the
1122       editor as a service to others, and to helping the orphans of Uganda.
1123
1124       The section entitled "HOW TO USE WITH GNU EMACS" was shamelessly stolen
1125       from the info page for GNU etags.
1126
1127
1128
1129Darren Hiebert                    Version 5.8                         CTAGS(1)
Impressum