CTAGS
Section: User Commands (1)
Updated: Version 2.3
Index
Return to Main Contents
NAME
ctags - Generate C and C++ language tag files for use with
vi(1)
SYNOPSIS
- ctags
-
[-aBeFnNRux]
[-f tagfile]
[-h list]
[-i types]
[-I ignorelist]
[-L listfile]
[-p path]
[-o tagfile]
[--append]
[--excmd=m|n|p]
[--format=level]
[--help]
[--if0]
[--lang=c|c++|java]
[--langmap=map(s)]
[--recurse]
[--sort]
[--totals]
[--version]
[file(s)]
- etags
-
[-aRx]
[-f tagfile]
[-h list]
[-i types]
[-I ignorelist]
[-L listfile]
[-p path]
[-o tagfile]
[--append]
[--help]
[--if0]
[--lang=c|c++|java]
[--langmap=map(s)]
[--recurse]
[--totals]
[--version]
[file(s)]
DESCRIPTION
The ctags and etags programs (hereinafter collectively referred to
as ctags, except where distinguished) generate an index (or "tag") file
for C, C++ and Java language objects found in file(s) that allows these
items to be quickly and easily located by a text editor or other utility. A
"tag" signifies a C language object for which an index entry is available (or,
alternatively, the index entry created for that object).
Alternatively, ctags can generate a cross reference file which lists, in
human readable form, information about the various objects found in a set of C
or C++ language files.
Tag index files are supported by the vi(1) editor and its derivatives
(such as vim, elvis, stevie, and xvi), and by the
emacs editor (see the HOW TO USE WITH sections, below), all of
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.
The following types of tags are supported by ctags (some are optional):
-
macro definitions (names created by #define)
enumerators (values inside an enumeration)
function (method) definitions
class, enum, struct, and union names
interface names (Java)
namespace names (C++)
typedefs
variables (definitions and extern declarations)
function prototypes and declarations
data members
Ctags
only generates tags for objects which have global scoping (file-wide
visibility). This means that, with the exception of macro definitions, only
objects defined outside of brace enclosed function blocks are candidates for a
tag.
SOURCE FILES
Unless the --lang option is specified, the language of each source file
is automatically selected based upon its file extension, according to the
following default mapping.
-
- C
-
*.c
- C++
-
*.C, *.c++, *.cc, *.cpp, *.cxx and any file considered a header file according
to the -h option.
- Java
-
*.java
All other files extensions are ignored. This permits running ctags on
all files in either a single directory (e.g. "ctags *"), or all files in an
entire source directory tree (e.g. "ctags -R"), since only those files whose
extensions are known to ctags will be scanned. This default mapping of
file extensions to source language may be changed by using the --langmap
option. Automatic selection of the source language may be disabled by using
the --lang option.
OPTIONS
Despite the wealth of available options, defaults are set so that ctags
is most commonly executed without any options (e.g. "ctags *"), which will
create a tag file in the current directory for the specified files. The
options described below are provided merely to allow custom tailoring to meet
special needs.
Note that spaces separating the single-letter options from their parameters
are optional.
Note also that the boolean parameters to the long form options (those
beginning with "--" and that take a "=yes|no" parameter) may
be omitted, in which case "=yes" is implied. (e.g. --sort is
equivalent to --sort=yes).
- -a
-
Append the tags to an existing tag file. Equivalent to --append.
- -B
-
Use backward searching patterns (e.g. ?regexp?).
- -e
-
Output tag file for use with Emacs. If this program is executed by the name
etags, this option is set by default. Selecting this option causes the
following options to be ignored: -BFnNsuwW, --excmd,
--format, --sort.
- -f tagfile
-
Use the name specified by tagfile for the tag file (default is "tags",
or "TAGS" when using the -e option). If tagfile is specified as
"-", then the tag file is written to standard output instead. Ctags
will stubbornly refuse to take orders if tagfile 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!
- -F
-
Use forward searching patterns (e.g. /regexp/) (default).
- -h list
-
Specifies a list of file extensions used for headers, separated by periods.
This option affects how the scoping of tag types is interpreted (i.e. whether
or not they are considered as static). All tag types other than functions
(methods) and variables are considered static when they appear in a non-header
file (since they cannot be seen outside of that file) and non-static when they
appear in a header file (since they can be seen in other files wherever that
header file is included). See also the S modifier of the -i
option. The default list is ".h.H.hh.hpp.hxx.h++".
- -i types
-
Specifies the list of tag types to include in the output file.
Types
is a group of one-letter flags designating the types of tags affected. Each
letter or group of letters may be preceded by either a '+' sign (default, if
omitted) to add it to those already included, a '-' sign to exclude it from
the list (e.g. to exclude a default tag type), or an '=' sign to include its
corresponding tag type at the exclusion of those not listed. Tags for the
following language contructs are supported (default settings are on except as
noted):
-
- c
-
class names
- d
-
macro definitions
- e
-
enumerators
- f
-
function (or method) definitions
- g
-
enumeration names
- i
-
interface names (Java only)
- m
-
data members [off]
- i
-
namespace names (C++ only)
- p
-
function prototypes and declarations [off]
- s
-
structure names
- t
-
typedefs
- u
-
union names
- v
-
variable definitions
- x
-
extern variable declarations [off]
-
In addition to the above flags, the following one-letter modifiers are
accepted:
-
- C
-
For C++ and Java, include an extra, class-qualified tag entry for each class
member (function/method and data) in the form "class::member" (C++) or
"class.member" (Java). This allows locating class-qualified tags (e.g. ":tag
class::member" in vi(1)). This is disabled by default because this could
potentially more than double the size of the tag file.
-
- F
-
Include tags for the basename of each source file. This permits jumping to a
file by its name (e.g. ":tag file.c" in vi(1)). This is disabled by
default.
- S
-
Include static tags (those not visible outside of a single source file).
Function and variable definitions are considered static only when their
definitions are preceded with the "static" keyword. All other types of tags
are considered static when they appear in a non-header file, and non-static
when they appear in a header file. See also the -h option. This is
enabled by default.
-
The default value for types is "=cdefgintuvCS".
- -I ignorelist
-
Reads a list of names which are to be ignored while generating tags for the
source files. The list may be supplied directly on the command line or found
in a separate file. Normally, the parameter
ignorelist
is a list of names to be ignored, each separated with a comma, a semicolon, or
white space (in which case the list should be quoted to keep the entire list
as one command line argument). The parameter
ignorelist
will be interpreted as a filename if its first character is given as either
a '.' or a pathname separator ('/' or '\'). In order to specify a file found
in the current directory, use "./filename".
-
This feature is useful when preprocessor macros are used in such a way that
they cause syntactic confusion due to their presence. Some examples will
illustrate this point.
-
/* creates a global version string in module */
MODULE_VERSION("$Revision: 6.10 $")
-
In this example, the macro invocation looks to 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 exactly like a K&R style
function parameter declaration). In fact, this seeming function definition
would likely cause the rest of the file to be skipped over while trying to
complete the definition. Ignoring "MODULE_ID" would avoid such a problem.
-
int foo ARGDECL2(void *, ptr, long int, nbytes)
-
In this example, the macro "ARGDECL2" would be mistakenly interpreted to be
the name of the function instead of the correct name of "foo". Ignoring the
name "ARGDECL2" results in the correct behavior.
- -L listfile
-
Read from
listfile
a list of file names for which tags should be generated. If
listfile
is specified as "-", then file names are read from standard input.
- -n
-
Equivalent to --excmd=number.
- -N
-
Equivalent to --excmd=pattern.
- -o tagfile
-
Alternative for -f.
- -p path
-
Use path as the default directory for each supplied source file (whether
supplied on the command line or in a file specified with the -L option),
unless the source file is already specified as an absolute path. The supplied
path is merely prepended to the each non-absolute source file name,
adding any necessary path separator.
- -R
-
Equivalent to --recurse=yes.
- -u
-
Equivalent to --sort=no.
- -x
-
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 the following options will be ignored:
-aBefFno, and -i+P. Example applications for this feature are
generating a listing of all functions (including statics) located in a source
file (e.g. ctags -xi=fS file), or generating a list of all
externally visible global variables located in a source file (e.g. ctags
-xi=v file).
- --append=yes|no
-
Indicates whether tags generated from the specified files should be appended
to those already present in the tag file or should replace them. If the
parameter is omitted, =yes is implied. This option is off by default.
- --excmd=type
-
Determines the type of EX command used to locate tags in the source file. The
valid values for type are (either the entire word or the first letter is
accepted):
-
- number
-
Places into the tag file line numbers in the source file where tags are located
rather than patterns to be searched for. This has three advantages:
-
- 1.
-
Significantly reduces the size of the resulting tag file.
- 2.
-
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
vim, are able to recover in many such instances).
- 3.
-
Eliminates finding identical matching, but incorrect, source lines (see
BUGS, below).
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: -BF.
- pattern
-
Uses EX 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.
- mixed
-
Uses line numbers for macro definition tags and EX patterns for everything
else. This is the default format generated by the original ctags and is,
therefore, retained as the default for this option.
- --format=level
-
Change the format of the output tag file. Currently the only valid values for
level are 1 or 2. Level 1 specifies the original tag file
format and level 2 specifies a new extended format containing extension flags
(but in a manner which retains backward compatibility with original
vi(1) implementations). The default level is 2.
- --help
-
Prints to standard output a detailed usage description.
- --if0=yes|no
-
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 options is no. 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. If the
parameter is omitted, =yes is implied. This option is off by default.
- --lang=c|c++|java
-
By default, ctags automatically selects the language of a source file
according to its file name extension, ignoring those files whose extensions
are unknown to ctags. This option forces the specified language to be
used for every supplied file, instead of keying off of their extensions.
- --langmap=map(s)
-
Overrides the default mapping between source language and file extension. Each
comma-separated map consists of the source language name, a colon, and a
list of extensions separated by periods. For example, to specify that files
with extensions of .c, .ec, and .xs are to be treated as C language files, use
"--langmap=c:.c.ec.xs". To also specify that files with extensions
of .j are to be treated as Java language files, use
"--langmap=c:.c.ec.xs,java:.java.j".
- --recurse=yes|no
-
Recurse into directories encountered in the list of supplied files. If the
list of supplied files is empty and no file list is specified with the
-L option, then the current directory (i.e. ".") is assumed. On Unix,
directories named "SCCS" are skipped, because files in these directories are
not source code, even though they have the same names as the source code they
relate to. Also on Unix, symbolic links are followed; if you don't like this,
pipe the output of find(1) into ctags -L- instead. Note:
This option is not supported on all platforms at present.
- --sort=yes|no
-
Indicates whether the tag file should be sorted on the tag name (default is
yes). Note that the original vi(1) requires sorted tags. If the
parameter is omitted, =yes is implied. This option is on by default
for ctags, and ignored for etags.
- --totals=yes|no
-
Prints statistics about the source files read and the tag file written during
the current invocation of ctags. If the parameter is omitted,
=yes is implied. This option is off by default.
- --version
-
Prints a version identifier for ctags to standard output. This is
guaranteed to always contain the string "Exuberant Ctags".
OPERATIONAL DETAILS
For every one of the qualified objects which are discovered in the source
files supplied to ctags, a separate line is added to the tag file, each
looking like this in the most general case:
-
tag_name file_name ex_cmd;" xflags
The fields and separators of these lines are specified as follows:
-
- 1.
-
tag name (a C language identifier)
- 2.
-
a single tab character
- 3.
-
the name of the file in which the object associated with the tag is located
- 4.
-
a single tab character
- 5.
-
an EX command to locate the tag within the file; generally a search pattern
(either /pattern/ or ?pattern?) or line number (see --excmd). Tag file
format 2 (see --format) extends this EX command under certain
circumstances to include a set of extension flags (see EXTENSION FLAGS,
below) embedded in an EX comment immediately appended to the EX command, which
leaves it backwards compatible with original vi(1) implemenations.
A few special tags are written into the tag file for internal purposes. These
tags are composed in such a way that they always sort to the top of the file.
Therefore, the first two characters of these tags are used a magic number to
detect a tag file for purposes of determining whether a valid tag file is
being overwritten rather than a source file.
When this program is invoked by the name etags, or with the -e
option, the output file is in a different format that is used by emacs(1).
Note that the name of each source file will be recorded in the tag file
exactly as it appears on the command line. Therefore, if the path you
specified on the command line was relative to some directory, then it will
be recorded in that same manner in the tag file.
This version of ctags imposes no formatting requirements. Other versions
of ctags tended to rely upon certain formatting assumptions in order to help
it resolve coding dilemmas caused by preprocessor conditionals.
In general, ctags tries to be smart about conditional preprocessor
directives. If a preprocessor conditional is encountered within a statement
which defines a tag, ctags follows only the first branch of that
conditional (except in the special case of "#if 0", in which case it follows
only the last branch). The reason for this is that failing to pursue only one
branch can result in ambiguous syntax, as in the following example:
-
#ifdef TWO_ALTERNATIVES
struct {
#else
union {
#endif
-
short a;
long b;
}
Both branches cannot be followed, or braces become unbalanced and ctags
would be unable to make sense of the syntax.
If the application of this heuristic fails to properly parse a file,
generally due to complicated and inconsistent pairing within the conditionals,
ctags will retry the file using a different heuristic which does not
selectively follow conditional preprocessor branches, but instead falls back
to relying upon a closing brace ("}") in column 1 as indicating the end of a
block once any brace imbalance results from following a #if conditional branch.
Ctags will also try to specially handle arguments lists enclosed in
double sets of parentheses in order to accept the following conditional
construct:
-
extern void foo __ARGS((int one, char two));
Any name immediately preceding the "((" will be automatically ignored and
the previous name will be used.
C++ operator definitions are specially handled. In the case of operators
beginning with a non-identifer character (e.g. "operator ="), the name of the
tag added to the tag file will be the operator prefixed by "operator", with no
intervening white space (e.g. "operator="). In the case of operators beginning
with identifer characters (e.g. "operator new"), the name of the tag added to
the tag file will be simply the name of the operator, without a prefix (e.g.
"new").
After creating or appending to the tag file, it is sorted by the tag name,
removing identical tag lines.
Note that the path recorded for filenames in the tag file and utilized by
the editor to search for tags are identical to the paths specified for
file(s) on the command line. This means the if you want the paths for
files to be relative to some directory, you must invoke ctags with the
same pathnames for file(s) (this can be overridden with -p).
EXTENSION FLAGS
Extension flags are tab-separated key-value pairs appended to the end of the
EX command as a comment, as described above in OPERATIONAL DETAILS.
These key value pairs appear in the general form "key:value".
The possible keys and the meaning of their values are as follows:
- class
-
Indicates that this tag is a member of the class whose name is given by
value.
- enum
-
Indicates that this tag is a member of the enumeration whose name is given by
value.
- file
-
Indicates that the tag has a file-limited scope (i.e. is static to the file).
This key has no corresponding value.
- kind
-
Indicates the type of the tag. Its value is one of the corresponding
one-letter flags described under the -i option, above. Alternatively,
this key may be omitted, with only the value present (i.e. a field without a
- interface
-
Indicates that this tag is a member of the interface whose name is given by
value.
- namespace
-
Indicates that this tag is a member of the namespace whose name is given by
value.
- private
-
Indicates the visibility of this class member is private.
This key has no corresponding value.
- protected
-
Indicates the visibility of this class member is protected.
This key has no corresponding value.
- public
-
Indicates the visibility of this class member is public.
This key has no corresponding value.
- struct
-
Indicates that this tag is a member of the structure whose name is given by
value.
- union
-
Indicates that this tag is a member of the union whose name is given by
value.
ENVIRONMENT VARIABLES
- CTAGS
-
This variable, if found, will be assumed to contain a set of custom default
options which are read when ctags starts, but before any command line
options are read. Options in this variable should be in the same form as those
on the command line. Command line options will override options specified in
this variable. Only options may be specified with this variable; no source
file names are read from its value.
- ETAGS
-
Similar to the CTAGS variable above, this variable, if found, will be
read when etags starts. If this variable is not found, etags will
try to use CTAGS instead.
HOW TO USE WITH VI
Vi will, by default, expect a tag file by the name "tags" in the current
directory. Once the tag file is built, the following commands exercise the tag
indexing feature:
- vi -t tag
-
Start vi and position the cursor at the file and line where "tag" is defined.
- Control-]
-
Find the tag under the cursor.
- :ta tag
-
Find a tag.
- Control-T
-
Return to previous location before jump to tag (not widely implemented).
HOW TO USE WITH GNU EMACS
Emacs will, by default, expect a tag file by the name "TAGS" in the current
directory. Once the tag file is built, the following commands exercise the
tag indexing feature:
- Meta-x visit-tags-table
-
Visit a TAGS file.
- Meta-.
-
Find a definition for a tag. The default tag is the identifier under the
cursor. There is name completion in the minibuffer; typing "foo TAB"
completes the identifier starting with `foo' (`foobar', for example) or lists
the alternatives.
- Meta-,
-
Find the next definition for the tag. Exact matches are found first, followed
by fuzzier matches.
For more commands, see the
Tags
topic in the Emacs info tree.
BUGS
Because ctags does not look inside brace-enclosed function blocks, local
definitions of objects within a function will not have tags generated for them.
Legacy C source code which uses C++ reserved keywords as variable or parameter
names (e.g. "class", etc.) in a header file may fail to have correct tags
generated for the objects using them. In order to properly handle such code,
use the --lang option.
Note that when ctags generates uses patterns for locating tags (see
the --excmd option), it is entirely possible that the wrong line may be
found by your editor if there exists another source line which is identical to
the line containing the tag. The following example demonstrates this condition:
-
int variable;
/* ... */
void foo(variable)
int variable;
{
-
/* ... */
}
Depending upon which editor you use and where in the code you happen to be, it
is possible that the search pattern may locate the local parameter declaration
in foo() before it finds the actual global variable definition, since the
lines (and therefore their search patterns are identical). This can be avoided
by use of the --excmd=n option.
Because ctags is neither a preprocessor nor a compiler, some complex
or obscure constructs can fool ctags into either missing a tag or
improperly generating an inappropriate tag. In particular, the use of
preprocessor constructs which alter the textual syntax of C can fool
ctags, as demonstrated by the following example:
-
#ifdef GLOBAL
#define EXTERN
#define INIT(assign) assign
#else
#define EXTERN extern
#define INIT(assign)
#endif
EXTERN BUF *firstbuf INIT(= NULL);
This looks too much like a declaration for a function called "INIT", which
returns a pointer to a typedef "firstbuf", rather than the actual variable
definition that it is, since this distinction can only be resolved by the
preprocessor. The moral of the story: don't do this if you want a tag
generated for it, or use the -I option to specify "INIT" as a keyword
to be ignored.
FILES
- tags
-
The default tag file created by ctags.
- TAGS
-
The default tag file created by etags.
SEE ALSO
The official Exuberant Ctags web site at:
-
http://darren.hiebert.com/ctags/index.html
Also ex(1), vi(1), elvis, or, better yet, vim, the
official editor of ctags. For more information on vim, see the VIM
Pages web site at:
-
http://www.vim.org/
AUTHOR
Darren Hiebert <darren@hiebert.com>, <darren@hiwaay.net>
http://darren.hiebert.com/
MOTIVATION
"Think ye at all times of rendering some service to every member of the human
race."
"All effort and exertion put forth by man from the fullness of his heart is
worship, if it is prompted by the highest motives and the will to do service
to humanity."
-
-- From the Baha'i Writings
CREDITS
This version of ctags was originally derived from and inspired by the
ctags program by Steve Kirkendall <kirkenda@cs.pdx.edu> that comes with the
Elvis vi clone (though virtually none of the original code remains).
Credit is also due Bram Moolenaar <mool@oce.nl>, the author of vim, who
has devoted so much of his time and energy both to developing the editor as a
service to others, and to helping the orphans of Uganda.
The section entitled "HOW TO USE WITH GNU EMACS" was shamelessly stolen from
the man page for GNU etags.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- SOURCE FILES
-
- OPTIONS
-
- OPERATIONAL DETAILS
-
- EXTENSION FLAGS
-
- ENVIRONMENT VARIABLES
-
- HOW TO USE WITH VI
-
- HOW TO USE WITH GNU EMACS
-
- BUGS
-
- FILES
-
- SEE ALSO
-
- AUTHOR
-
- MOTIVATION
-
- CREDITS
-
This document was created by
man2html,
using the manual pages.
Time: 23:38:37 GMT, February 15, 2023