1.\" Copyright (c) 1987, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)ctags.1 8.1 (Berkeley) 6/6/93 29.\" $FreeBSD: src/usr.bin/ctags/ctags.1,v 1.5.2.6 2002/07/30 01:06:31 tjr Exp $ 30.\" 31.Dd June 6, 1993 32.Dt CTAGS 1 33.Os 34.Sh NAME 35.Nm ctags 36.Nd create a 37.Pa tags 38file 39.Sh SYNOPSIS 40.Nm 41.Op Fl BFadtuwvx 42.Op Fl f Ar tagsfile 43.Ar name ... 44.Sh DESCRIPTION 45The 46.Nm 47utility makes a 48.Pa tags 49file for 50.Xr ex 1 51from the specified C, 52Pascal, Fortran, 53.Xr yacc 1 , 54.Xr lex 1 , 55and Lisp sources. 56A tags file gives the locations of specified objects in a group of files. 57Each line of the tags file contains the object name, the file in which it 58is defined, and a search pattern for the object definition, separated by 59white-space. 60Using the 61.Pa tags 62file, 63.Xr ex 1 64can quickly locate these object definitions. 65Depending upon the options provided to 66.Nm , 67objects will consist of subroutines, typedefs, defines, structs, 68enums and unions. 69.Pp 70The following options are available: 71.Bl -tag -width indent 72.It Fl B 73Use backward searching patterns 74.Pq Li ?...? . 75.It Fl F 76Use forward searching patterns 77.Pq Li /.../ 78(the default). 79.It Fl a 80Append to 81.Pa tags 82file. 83.It Fl d 84Create tags for 85.Li #defines 86that do not take arguments; 87.Li #defines 88that take arguments are tagged automatically. 89.It Fl f 90Place the tag descriptions in a file called 91.Ar tagsfile . 92The default behaviour is to place them in a file called 93.Pa tags . 94.It Fl t 95Create tags for typedefs, structs, unions, and enums. 96.It Fl u 97Update the specified files in the 98.Pa tags 99file, that is, all 100references to them are deleted, and the new values are appended to the 101file. 102(Beware: this option is implemented in a way which is rather 103slow; it is usually faster to simply rebuild the 104.Pa tags 105file.) 106.It Fl v 107An index of the form expected by 108.Xr vgrind 1 109is produced on the standard output. 110This listing 111contains the object name, file name, and page number (assuming 64 112line pages). 113Since the output will be sorted into lexicographic order, 114it may be desired to run the output through 115.Xr sort 1 . 116Sample use: 117.Bd -literal -offset indent 118ctags -v files | sort -f > index 119vgrind -x index 120.Ed 121.It Fl w 122Suppress warning diagnostics. 123.It Fl x 124.Nm 125produces a list of object 126names, the line number and file name on which each is defined, as well 127as the text of that line and prints this on the standard output. 128This 129is a simple index which can be printed out as an off-line readable 130function index. 131.El 132.Pp 133Files whose names end in 134.Pa .c 135or 136.Pa .h 137are assumed to be C 138source files and are searched for C style routine and macro definitions. 139Files whose names end in 140.Pa .y 141are assumed to be 142.Xr yacc 1 143source files. 144Files whose names end in 145.Pa .l 146are assumed to be Lisp files if their 147first non-blank character is 148.Ql \&; , 149.Ql \&( , 150or 151.Ql \&[ , 152otherwise, they are 153treated as 154.Xr lex 1 155files. 156Other files are first examined to see if they 157contain any Pascal or Fortran routine definitions, and, if not, are 158searched for C style definitions. 159.Pp 160The tag 161.Dq Li main 162is treated specially in C programs. 163The tag formed 164is created by prepending 165.Ql M 166to the name of the file, with the 167trailing 168.Pa .c 169and any leading pathname components removed. 170This makes use of 171.Nm 172practical in directories with more than one 173program. 174.Pp 175.Xr yacc 1 176and 177.Xr lex 1 178files each have a special tag. 179.Dq Li yyparse 180is the start 181of the second section of the 182.Xr yacc 1 183file, and 184.Dq Li yylex 185is the start of 186the second section of the 187.Xr lex 1 188file. 189.Sh FILES 190.Bl -tag -width ".Pa tags" -compact 191.It Pa tags 192default output tags file 193.El 194.Sh EXIT STATUS 195.Ex -std 196Duplicate objects are not considered errors. 197.Sh SEE ALSO 198.Xr ex 1 , 199.Xr vi 1 200.Sh HISTORY 201The 202.Nm 203utility appeared in 204.Bx 3.0 . 205.Sh BUGS 206Recognition of functions, subroutines and procedures 207for Fortran and Pascal is done in a very simpleminded way. 208No attempt 209is made to deal with block structure; if you have two Pascal procedures 210in different blocks with the same name you lose. 211The 212.Nm 213utility does not 214understand about Pascal types. 215.Pp 216The method of deciding whether to look for C, Pascal or 217Fortran 218functions is a hack. 219.Pp 220The 221.Nm 222utility relies on the input being well formed, and any syntactical 223errors will completely confuse it. 224It also finds some legal syntax 225confusing; for example, since it does not understand 226.Li #ifdef Ns 's 227(incidentally, that is a feature, not a bug), any code with unbalanced 228braces inside 229.Li #ifdef Ns 's 230will cause it to become somewhat disoriented. 231In a similar fashion, multiple line changes within a definition will 232cause it to enter the last line of the object, rather than the first, as 233the searching pattern. 234The last line of multiple line 235.Li typedef Ns 's 236will similarly be noted. 237