CTAGS(1)

NAME
ctags - create a tags file for use with ex and vi

SYNOPSIS
ctags [ -aBFtuvwx ] [ -f tagsfile ] filename...

DESCRIPTION
ctags makes a tags file for ex(1) from the specified C, Pascal, FORTRAN, yacc(1), and lex(1) sources. A tags file gives the locations of specified objects (in this case functions and type definitions) in a group of files. Each entry in the tags is composed of three fields separated by white space, the object name, the file in which it is defined, and an address specification. Function definitions are located using regular expression patterns, type definitions, using a line number.

ex and vi(1) use entries in the tags file to locate and display a definition.

Normally ctags places the tag descriptions in a file called tags; this may be overridden with the -f option. By default, the tags file is sorted in lexicographic (ASCII) order, and ex expects its entries to be so sorted.

Files with names ending in .c or .h are assumed to be C source files and are searched for C routine and macro definitions. Files with names ending in .y are assumed to be yacc source files. Files with names ending in .l are assumed to be lex files. Others are first examined to see if they contain any Pascal or FORTRAN routine definitions; if not, they are processed again looking for C definitions.

The tag for the main() function is treated specially in C programs. The tag formed is created by prepending M to filename, with a trailing .c removed, if any, and leading pathname components also removed. This makes use of ctags practical in directories with more than one program.

OPTIONS

-a  Append output to an existing tags file. The resulting file is not sorted. To preserve the order, use -u instead.

-B  Use backward searching patterns (?...?).

-F  Use forward searching patterns (/.../) (default).

-t  Create tags for typedefs.

-u  Update the specified files in the tags file. Entries that refer to them are deleted and then replaced in lexicographic order. Beware: this option is implemented in a way which is rather slow; it may be faster simply to rebuild the tags file.

-v  Produce an index of the form expected by vgrind(1) on the standard output. This listing contains the function name, file name, and page number (assuming 64 line pages). Since the output will be sorted into lexicographic order, it may be desired to run the output through `sort -f'. See EXAMPLES.

-w  Suppress warning diagnostics.

-x  Produce a list of object names, the line number and file name on which each is defined, as well as the text of that line and prints this on the standard output. This is a simple index which can be printed out as an off-line readable function index.

EXAMPLES
Using ctags with the -v option produces entries in an order which may not always be appropriate for vgrind. To produce results in alphabetical order, you may want to run the output through `sort -f'.

    example% ctags -v filename.c filename.h | sort -f > index
    example% vgrind -x index

To build a tags file for C sources in a directory hierarchy, first create an empty tags file, and then run the following find(1) command:

    example% cd ~/src ; rm -f tags ; touch tags
    example% find ~/src \( -name '*.c' -o -name '*.h' \) -exec ctags -u -f /usr/src/tags {} \;

FILES
tags
    output tags file

SEE ALSO
cc(1V), ex(1), find(1), vgrind(1), vi(1)

NOTES
While the compiler allows 8-bit strings and comments, 8-bits are not allowed anywhere else. See cc(1V) for an explanation about why cc is not 8-bit clean.

BUGS
Recognition of functions, subroutines and procedures for FORTRAN and Pascal is done is a very simpleminded way. No attempt is made to deal with block structure; if you have two Pascal procedures in different blocks with the same name, ctags will only make an entry for one.

ctags does not know about #ifdefs.

ctags should know about Pascal types. Relies on the input being well formed to detect typedefs. Use of -tx shows only the last line of typedefs.