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