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