Commands Reference, Volume 1

ctags Command

Purpose

Makes a file of tags to help locate objects in source files.

Syntax

ctags [ -u | -x ] [ -B | -F ] [ -a ] [ -m ] [ -o ] [ -t ] [ -v ] [ -w ] [ -f TagsFile ] File. ..

Description

The ctags command creates a tags file for use with the ex and vi editors from the specified C, Pascal, FORTRAN, yacc, lex, and LISP source files. The tags file consists of locators of programming language specific objects (such as functions and type definitions) within the source files. A locator consists of the object name, the file in which it is defined, and either a basic regular expression or a line number that can be used in searching for the object definition. Specifiers are given in separate fields on the line, separated by spaces or tabs. Using the tags file, ex and vi can quickly find these object definitions.

The following file name suffixes are supported by the ctags command:

.c	Treated as C-language source code and searched for C routine and macro definitions.
.h	Treated as C-language source code and searched for C routine and macro definitions.
.f	Treated as FORTRAN-language source code.
.l	Treated as LISP-language source code if its first nonspace character is [ (open bracket), ( (open parenthesis), or ; (semicolon). Treated as lex-language source code otherwise.

File names ending with any other suffixes are first examined to see if they contain any Pascal or FORTRAN routine definitions. If not, they are processed again as C-language source code. Files without a . (dot) suffix are processed as C-language source code.

The main tag is treated specially in C programs. The tag formed is created by prefixing M to the file name, removing a trailing .c (if any), and removing the leading path name components. This makes use of ctags practical in directories with more than one program.

Notes:

Recognition of the keywords function, an address specification for the subroutine, and procedure in FORTRAN and Pascal code ignores block structure. The ctags command may yield inadequate results if any two Pascal procedures have the same name, even though they are in different blocks.

The ctags command does not recognize #if and #ifdef statements.

If both the -B and -F options are specified, the last one specified will take precedence.

The -x option takes precedence over any options (-a, -u, or -f) that would otherwise create a tags file.

When the -v option is specified, the -x option is implied.

The output of the ctags command is always sorted by object identifier.

Flags

-a	Appends to the tags file. After appending, ctags sorts the tags file.
-B	Causes ctags to use backward searching patterns (?. . .?).
-F	Causes ctags to use forward searching patterns (/. . ./). This is the default searching pattern.
-f TagsFile	Creates a tags file with the name specified by TagsFile instead of the default tags file.
-m	Causes ctags to not create tags for macro definitions.
-o	Causes ctags to generate line numbers for typedefs instead of a basic regular expression which is used in searching for the object definition.
-t	Creates tags for typedefs. This flag is on by default due to standards conformance.
-u	Updates the specified files in tags; that is, all references to them are deleted, and the new values are appended to the file. This flag may slow the processing of the command. (It is usually faster to simply rebuild the tags file.)
-v	Produces an index of the form expected by the vgrind command on the standard output. This listing contains the function name, file name, and page number (assuming 64-line pages).
-w	Causes ctags to suppress diagnostic warning messages.
-x	Causes the ctags command to display a list of object names, the line number and file name on which each is defined, as well as the text of that line. This provides a simple, readable, function index. If you specify this flag, the ctags command does not build, update, or append a tags file, but writes to standard output.

Examples

To write the output of the ctags command to standard output for the C-language source files, x.c, y.c, and z.c, enter:
```
ctags -x x.c y.c z.c
```
To create a tags file named foo_tags for all the C-language source files within the current directory, enter:
```
ctags -f foo_tags *
```
To add additional tags,including type definitions, to the foo_tags tags file for the C-language source file zip.c, enter:
```
ctags -utf foo_tags zip.c
```

Exit Status

The following exit values are returned:

0	Successful completion.
>0	An error occurred.

Files

tags	Output tags file.

Related Information

The ex command, lex command, vgrind command, vi command, yacc command.