ctags - create a tags file


ctags [-BFadtuwvx] [ -f tagsfile] name ...


The ctags(1) utility makes a tags file for ex(1) from the specified C, Pascal, FORTRAN, yacc(1), lex(1), and LISt Processing programming language (LISP) sources. A tags file gives the locations of specified objects in a group of files. Each line of the tags file contains the object name, the file in which it is defined, and a search pattern for the object definition, separated by white space. Using the tags file, ex(1) and vi(1) can quickly locate these object definitions (using the -t option). Depending upon the options provided to ctags(1), objects will consist of subroutines and typedef, define, struct, enums and union statements.


Append to tags file.
Use backward searching patterns (?...?).
Create tags for #define statements that do not take arguments; #define statements that take arguments are tagged automatically.
Use forward searching patterns (/.../) (the default).
-f tagsfile
Place the tag descriptions in a file called tagsfile. The default behavior is to place them in a file called tags.
Create tags for typedef, struct, union, and enum statements.
Update the specified files in the tags file; that is, all references to them are deleted, and the new values are appended to the file. (It should be noted that this option is implemented in a way that is rather slow. It is usually faster to simply rebuild the tags file.)
Produce on the standard output an index of the form expected by vgrind(1) (not supplied with Windows Services for UNIX). This listing contains the object name, file name, and page number (assuming 64-line pages). Since the output will be sorted into lexicographic order, you may want to run the output through sort(1); for example:
ctags -v files | sort -f > index
vgrind -x index
Suppress warning diagnostics.
Produce on the standard output a list of object names, the line number and file name on which each is defined, and the text of that line. This is a simple index that can be printed out as an off-line readable function index.

Files whose names end in .c or .h are assumed to be C source files and are searched for C-style routine and macro definitions. Files whose names end in .y are assumed to be yacc(1) source files. Files whose names end in .l are assumed to be LISP files if their first non-blank character is a semicolon (;), opening parenthesis ((), or opening bracket ([), otherwise, they are treated as lex(1) files. Other files are first examined to determine whether they contain any Pascal or FORTRAN routine definitions, and, if not, are searched for C-style definitions.

The tag main is treated specially in C programs. The tag formed is created by prepending M to the name of the file, with the trailing .c and any leading path name components removed. Because of this, it is practical to use ctags(1) in directories with more than one program. This implementation of ctags(1) recognizes both the /* */ style of C comments and the C++ // to-end-of-line comment.

Yacc(1) and lex(1) files each have a special tag. Yyparse is the start of the second section of the yacc(1) file, and yylex is the start of the second section of the lex(1) file.


The ctags(1) utility uses the following files:
Default output tags file


The ctags(1) utility exits with a value of 1 if an error occurred; otherwise it exits with 0. Duplicate objects are not considered errors.


Recognition of functions, subroutines and procedures for FORTRAN and Pascal is not very sophisticated. No attempt is made to deal with block structure; ctags(1) cannot handle two Pascal procedures in different blocks with the same name. The ctags(1) utility cannot handle Pascal types.

The ctags(1) utility relies on the input being well formed, and any syntactical errors will cause problems. It also finds some legal syntax confusing. For example, since it does not understand #ifdef statements (incidentally, that is a feature, not a bug), any code with unbalanced braces inside #ifdef statements will cause it to become unstable. Similarly, multiple line changes within a definition will cause it to enter the last line of the object, rather than the first, as the searching pattern. The last line of multiple line typedefs will similarly be noted.