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.\" $DragonFly: src/usr.bin/ctags/ctags.1,v 1.2 2003/06/17 04:29:25 dillon Exp $ 31.\" 32.Dd June 6, 1993 33.Dt CTAGS 1 34.Os 35.Sh NAME 36.Nm ctags 37.Nd create a 38.Pa tags 39file 40.Sh SYNOPSIS 41.Nm 42.Op Fl BFadtuwvx 43.Op Fl f Ar tagsfile 44.Ar name ... 45.Sh DESCRIPTION 46The 47.Nm 48utility makes a 49.Pa tags 50file for 51.Xr ex 1 52from the specified C, 53Pascal, Fortran, 54.Xr yacc 1 , 55.Xr lex 1 , 56and Lisp sources. 57A tags file gives the locations of specified objects in a group of files. 58Each line of the tags file contains the object name, the file in which it 59is defined, and a search pattern for the object definition, separated by 60white-space. 61Using the 62.Pa tags 63file, 64.Xr ex 1 65can quickly locate these object definitions. 66Depending upon the options provided to 67.Nm , 68objects will consist of subroutines, typedefs, defines, structs, 69enums and unions. 70.Pp 71The following options are available: 72.Bl -tag -width indent 73.It Fl B 74Use backward searching patterns 75.Pq Li ?...? . 76.It Fl F 77Use forward searching patterns 78.Pq Li /.../ 79(the default). 80.It Fl a 81Append to 82.Pa tags 83file. 84.It Fl d 85Create tags for 86.Li #defines 87that do not take arguments; 88.Li #defines 89that take arguments are tagged automatically. 90.It Fl f 91Place the tag descriptions in a file called 92.Ar tagsfile . 93The default behaviour is to place them in a file called 94.Pa tags . 95.It Fl t 96Create tags for typedefs, structs, unions, and enums. 97.It Fl u 98Update the specified files in the 99.Pa tags 100file, that is, all 101references to them are deleted, and the new values are appended to the 102file. 103(Beware: this option is implemented in a way which is rather 104slow; it is usually faster to simply rebuild the 105.Pa tags 106file.) 107.It Fl v 108An index of the form expected by 109.Xr vgrind 1 110is produced on the standard output. 111This listing 112contains the object name, file name, and page number (assuming 64 113line pages). 114Since the output will be sorted into lexicographic order, 115it may be desired to run the output through 116.Xr sort 1 . 117Sample use: 118.Bd -literal -offset indent 119ctags -v files | sort -f > index 120vgrind -x index 121.Ed 122.It Fl w 123Suppress warning diagnostics. 124.It Fl x 125.Nm 126produces a list of object 127names, the line number and file name on which each is defined, as well 128as the text of that line and prints this on the standard output. 129This 130is a simple index which can be printed out as an off-line readable 131function index. 132.El 133.Pp 134Files whose names end in 135.Pa .c 136or 137.Pa .h 138are assumed to be C 139source files and are searched for C style routine and macro definitions. 140Files whose names end in 141.Pa .y 142are assumed to be 143.Xr yacc 1 144source files. 145Files whose names end in 146.Pa .l 147are assumed to be Lisp files if their 148first non-blank character is 149.Ql \&; , 150.Ql \&( , 151or 152.Ql \&[ , 153otherwise, they are 154treated as 155.Xr lex 1 156files. 157Other files are first examined to see if they 158contain any Pascal or Fortran routine definitions, and, if not, are 159searched for C style definitions. 160.Pp 161The tag 162.Dq Li main 163is treated specially in C programs. 164The tag formed 165is created by prepending 166.Ql M 167to the name of the file, with the 168trailing 169.Pa .c 170and any leading pathname components removed. 171This makes use of 172.Nm 173practical in directories with more than one 174program. 175.Pp 176.Xr yacc 1 177and 178.Xr lex 1 179files each have a special tag. 180.Dq Li yyparse 181is the start 182of the second section of the 183.Xr yacc 1 184file, and 185.Dq Li yylex 186is the start of 187the second section of the 188.Xr lex 1 189file. 190.Sh FILES 191.Bl -tag -width ".Pa tags" -compact 192.It Pa tags 193default output tags file 194.El 195.Sh DIAGNOSTICS 196The 197.Nm 198utility exits with a value of 1 if an error occurred, 0 otherwise. 199Duplicate objects are not considered errors. 200.Sh SEE ALSO 201.Xr ex 1 , 202.Xr vi 1 203.Sh HISTORY 204The 205.Nm 206utility appeared in 207.Bx 3.0 . 208.Sh BUGS 209Recognition of functions, subroutines and procedures 210for Fortran and Pascal is done in a very simpleminded way. 211No attempt 212is made to deal with block structure; if you have two Pascal procedures 213in different blocks with the same name you lose. 214The 215.Nm 216utility does not 217understand about Pascal types. 218.Pp 219The method of deciding whether to look for C, Pascal or 220Fortran 221functions is a hack. 222.Pp 223The 224.Nm 225utility relies on the input being well formed, and any syntactical 226errors will completely confuse it. 227It also finds some legal syntax 228confusing; for example, since it does not understand 229.Li #ifdef Ns 's 230(incidentally, that is a feature, not a bug), any code with unbalanced 231braces inside 232.Li #ifdef Ns 's 233will cause it to become somewhat disoriented. 234In a similar fashion, multiple line changes within a definition will 235cause it to enter the last line of the object, rather than the first, as 236the searching pattern. 237The last line of multiple line 238.Li typedef Ns 's 239will similarly be noted. 240