1.\" Copyright (c) 1987, 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)ctags.1 6.8 (Berkeley) 04/24/91 7.\" 8.Dd 9.Dt CTAGS 1 10.Os BSD 4 11.Sh NAME 12.Nm ctags 13.Nd create a tags file 14.Sh SYNOPSIS 15.Nm ctags 16.Op Fl BFadtuwvx 17.Op Fl f Ar tagsfile 18.Ar name ... 19.Sh DESCRIPTION 20.Nm Ctags 21makes a tags file for 22.Xr ex 1 23from the specified C, 24Pascal, Fortran, 25.Tn YACC , 26lex, and lisp sources. A tags file gives the 27locations of specified objects in a group of files. Each line of the 28tags file contains the object name, the file in which it is defined, 29and a search pattern for the object definition, separated by white-space. 30Using the 31.Ar tags 32file, 33.Xr ex 1 34can quickly locate these object 35definitions. Depending on the options provided to 36.Nm ctags , 37objects will consist of subroutines, typedefs, defines, structs, 38enums and unions. 39.Bl -tag -width Ds 40.It Fl B 41use backward searching patterns 42.Pq Li ?...? . 43.It Fl F 44use forward searching patterns 45.Pq Li /.../ 46(the default). 47.It Fl a 48append to 49.Ar tags 50file. 51.It Fl d 52create tags for 53.Li #defines 54that don't take arguments; 55.Li #defines 56that take arguments are tagged automatically. 57.It Fl f 58Places the tag descriptions in a file called 59.Ar tagsfile . 60The default behaviour is to place them in a file 61.Ar tags . 62.It Fl t 63create tags for typedefs, structs, unions, and enums. 64.It Fl u 65update the specified files in the 66.Ar tags 67file, that is, all 68references to them are deleted, and the new values are appended to the 69file. (Beware: this option is implemented in a way which is rather 70slow; it is usually faster to simply rebuild the 71.Ar tags 72file.) 73.It Fl v 74An index of the form expected by 75.Xr vgrind 1 76is produced on the standard output. This listing 77contains the object name, file name, and page number (assuming 64 78line pages). Since the output will be sorted into lexicographic order, 79it may be desired to run the output through 80.Xr sort 1 . 81Sample use: 82.Bd -literal -offset indent 83ctags \-v files \&| sort \-f > index 84vgrind \-x index 85.Ed 86.It Fl w 87suppress warning diagnostics. 88.It Fl x 89.Nm ctags 90produces a list of object 91names, the line number and file name on which each is defined, as well 92as the text of that line and prints this on the standard output. This 93is a simple index which can be printed out as an off-line readable 94function index. 95.El 96.Pp 97Files whose names end in 98.Nm \&.c 99or 100.Nm \&.h 101are assumed to be C 102source files and are searched for C style routine and macro definitions. 103Files whose names end in 104.Nm \&.y 105are assumed to be 106.Tn YACC 107source files. 108Files whose names end in 109.Nm \&.l 110are assumed to be lisp files if their 111first non-blank character is `;', `(', or `[', 112otherwise, they are 113treated as lex files. Other files are first examined to see if they 114contain any Pascal or Fortran routine definitions, and, if not, are 115searched for C style definitions. 116.Pp 117The tag 118.Li main 119is treated specially in C programs. The tag formed 120is created by prepending 121.Ar M 122to the name of the file, with the 123trailing 124.Nm \&.c 125and any leading pathname components removed. This 126makes use of 127.Nm ctags 128practical in directories with more than one 129program. 130.Pp 131Yacc and lex files each have a special tag. 132.Ar Yyparse 133is the start 134of the second section of the yacc file, and 135.Ar yylex 136is the start of 137the second section of the lex file. 138.Sh FILES 139.Bl -tag -width tags -compact 140.It Pa tags 141default output tags file 142.El 143.Sh DIAGNOSTICS 144.Nm Ctags 145exits with a value of 1 if an error occurred, where 146duplicate objects are not considered errors, 0 otherwise. 147.Sh SEE ALSO 148.Xr ex 1 , 149.Xr vi 1 150.Sh BUGS 151Recognition of 152.Nm functions , 153.Nm subroutines 154and 155.Nm procedures 156for 157.Tn FORTRAN 158and Pascal is done is a very simpleminded way. No attempt 159is made to deal with block structure; if you have two Pascal procedures 160in different blocks with the same name you lose. 161.Nm Ctags 162doesn't 163understand about Pascal types. 164.Pp 165The method of deciding whether to look for C, Pascal or 166.Tn FORTRAN 167functions is a hack. 168.Pp 169.Nm Ctags 170relies on the input being well formed, and any syntactical 171errors will completely confuse it. It also finds some legal syntax 172confusing; for example, as it doesn't understand 173.Li #ifdef Ns 's , 174(incidentally, that's a feature, not a bug) any code with unbalanced 175braces inside 176.Li #ifdef Ns 's 177will cause it to become somewhat disoriented. 178In a similar fashion, multiple line changes within a definition will 179cause it to enter the last line of the object, rather than the first, as 180the searching pattern. The last line of multiple line 181.Li typedef Ns 's 182will similarly be noted. 183.Sh HISTORY 184The 185.Nm 186command appeared in 187.Bx 3.0 . 188