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