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