home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 5 Edit
/
05-Edit.zip
/
vim45os2.zip
/
vim-4.5
/
doc
/
ctags.man
< prev
next >
Wrap
Text File
|
1996-10-15
|
21KB
|
529 lines
CTAGS(1) CTAGS(1)
NAME
ctags - Generate C language tag files for use with vi(1)
SYNOPSIS
ctags [ -aBdFnNsStTuwWx ] [ -f tagfile ] [ -h list ]
[ -i types ] [ -I ignorelist ] [ -L listfile ]
[ -o tagfile ] [ --help ] [ file(s) ]
DESCRIPTION
Ctags generates an index (or "tag") file of C language
objects found in file(s) that allows these items to be
quickly and easily located by a text editor or other util-
ity. 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 language files.
Tag index files are supported by the vi(1) editor and its
derivatives (such as vim, elvis, stevie, and xvi) through
the use of the ":ta" command, which locates the object
associated with a name appearing in a source file and
jumps to the file and line which defines the name. The
following types of tags are supported by ctags:
macro definitions (i.e. names created by #define)
enumerated values (i.e. the values inside enum{...})
function definitions
function prototypes or declarations (optional)
class, enum, struct and union tags
typedefs
variables
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 out-
side of brace enclosed function blocks are candidates for
a tag. For every one of the qualified objects which are
discovered in the source files supplied to ctags, a sepa-
rate line is added to the tags file in the following for-
mat:
1. tag name (a C language identifier)
2. a single tab character
3. the name of the file in which the object associ-
ated with the tag is located
4. a single tab character
5. an Ex command to locate the tag within the file;
generally either a search pattern (either /pat-
tern/ or ?pattern?) or line number
Note that, unless changed via -n or -N, line numbers are
Darren Hiebert 5 October 1996 1
CTAGS(1) CTAGS(1)
only used for tags from macro definitions, while patterns
are used for all other tags.
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 for-
matting assumptions in order to help it resolve coding
dilemmas caused by preprocessor conditionals.
In general, ctags tries to be smart about conditional pre-
processor 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 unbal-
anced and ctags would be unable to make sense of the syn-
tax.
If the application of this heuristic fails to properly
parse a file, generally due to complicated and inconsis-
tent pairing within the conditionals, ctags will retry the
file using a different heuristic which does not selec-
tively 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 is detected within a #if conditional.
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 automati-
cally ignored and the previous name will be used.
Darren Hiebert 5 October 1996 2
CTAGS(1) CTAGS(1)
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 identi-
cal 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).
OPTIONS
Note that spaces separating options from their parameters
are optional.
--help
Prints to standard output a detailed usage descrip-
tion.
-a Append the tags to an existing tag file.
-B Use backward searching patterns (?...?).
-d Include macro definitions in the output file. This is
equivalent to -i+d and is supported only for back-
wards compatibility with other versions of ctags. Use
of -i is preferred.
-f tagfile
Output tags to the specified file (default is
"tags"). 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 -o *.c", which would oth-
erwise overwrite your first C file with the tags gen-
erated by the rest!
-F Use forward searching patterns (/.../) (default).
-h list
Specifies a list of file extensions used for headers,
separated by either periods or commas. The default
list is ".h.H.hpp.hxx.h++".
-i types
Specifies the list of tag types to include in the
output file. Types is a group of letters 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
Darren Hiebert 5 October 1996 3
CTAGS(1) CTAGS(1)
exclusion of those not listed. The following tag
types are supported:
d macro definitions
e enumerated values (values inside enum{...})
f function and method definitions
g enum/struct/union tags (or new C++ types)
p external function prototypes
t typedefs
v variable declarations
In addition, the following two modifiers are
accepted:
P Prefix static tags (if included) in the tag
file with the filename in which they appear,
followed by a colon (Elvis style; not widely
supported).
S Include static tags (those not visible outside
of a single source file). Function and vari-
able 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 (see the -h option).
The default value of list is "=defgtvS" (i.e all tag
types except for function prototypes; include static
tags but do not prefix them).
-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 cur-
rent directory, use "./filename".
This feature is useful when preprocessor macros are
used in such a way that they cause syntactic confu-
sion due to their presence. Some examples will illus-
trate this point.
/* creates a global version string in module */
MODULE_VERSION("$Revision: 1.25 $")
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
Darren Hiebert 5 October 1996 4
CTAGS(1) CTAGS(1)
cause the rest of the file to be skipped over while
trying to complete the definition. Ignoring "MOD-
ULE_ID" would avoid such a problem.
int foo ARGDECL2(void *, ptr, long int, nbytes)
In this example, the macro "ARGDECL2" would be mis-
takenly 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 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 incor-
rect, source lines (see BUGS, below).
However, this option has one significant drawback:
changes to the source files can cause the line num-
bers 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. See also the -N option. Selecting this
option causes the following options to be ignored:
-F, -B and -N.
-N Uses 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. See also the -n option.
Selecting this option causes the following options to
be ignored: -F, -B and -n.
-o tagfile
Alternative for -f.
-s Include static tags in the output file, each prefixed
with the name of the file in which it appears fol-
lowed by a colon. This is equivalent to -i+SP and is
supported only for backwards compatibility with other
versions of ctags. Use of -i is preferred.
Darren Hiebert 5 October 1996 5
CTAGS(1) CTAGS(1)
-S Include static tags in the output file, but do not
prefix them, thereby making them appear the same as
global tags. This is equivalent to -i+S-P and is sup-
ported only for backwards compatibility with other
versions of ctags. Use of -i is preferred.
-t Include typedefs in the output file. This is equiva-
lent to -i+t and is supported only for backwards com-
patibility with other versions of ctags. Use of -i is
preferred.
-T Include typedefs and class/enum/struct/union tags in
the output file. This is equivalent to -i+tg and is
supported only for backwards compatibility with other
versions of ctags. Use of -i is preferred.
-u Unsorted; do not sort the tags. Please note that this
disables the warning messages normally enabled by -W,
because sorted tags are used to detect duplicate
tags. Note also that vi(1) requires sorted tags.
-w Exclude warnings about duplicate tags (default).
-W Generate warnings about duplicate tags.
-x Print a tabular, human-readable cross reference
(xref) file to standard output. The information con-
tained in the output includes: the tag name; the tag
type; 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 fol-
lowing options will be ignored: -a, -f, -i+P, -n, -o,
-B and -F. 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).
ENVIRONMENT VARIABLES
CTAGS If found, this variable 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 speci-
fied in this variable. Only options may be speci-
fied with this variable; no source file names are
read from its value.
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 build, the
following vi commands take exercise the tag indexing
Darren Hiebert 5 October 1996 6
CTAGS(1) CTAGS(1)
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).
BUGS
Support for C++ features is quite limited.
Because ctags does not look inside brace enclosed function
blocks, local declarations of class/enum/struct/union tags
and enumeration values within a function will not have
tags generated for them.
Note that because ctags generates search patterns for non-
macro tags, it is entirely possible that the wrong line
may be found by your editor if there exists another, iden-
tical, line (whose context prevents it from generating a
tag) 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 -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 inappro-
priate tag. In particular, the use of preprocessor con-
structs 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
Darren Hiebert 5 October 1996 7
CTAGS(1) CTAGS(1)
#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.
SEE ALSO
The official Exuberant Ctags web site at:
http://fly.hiwaay.net/~darren/ctags.html
Also ex(1), vi(1), elvis, or, better yet, vim, the offi-
cial editor of ctags. For more information on vim, see
the VIM Pages web site at:
http://www.math.fu-berlin.de/~guckes/vim/
AUTHOR
Darren Hiebert, (darren@sirsi.com, darren@hiwaay.net,
http://fly.hiwaay.net/~darren)
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 full-
ness 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 is derived from and inspired by the
ctags program by Steve Kirkendall (kirkenda@cs.pdx.edu)
that comes with the Elvis vi clone (though almost none of
the original code remains).
Credit is also due Bram Moolenaar, the author of vim, who
has devoted so much of his time and energy both to devel-
oping the editor as a service to others, and to helping
the orphans of Uganda.
Darren Hiebert 5 October 1996 8