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$ 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 BFTaduwvx 42.Op Fl f Ar tagsfile 43.Ar 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 T 80Do not create tags for typedefs, structs, unions, and enums. 81.It Fl a 82Append to 83.Pa tags 84file. 85.It Fl d 86Create tags for 87.Li #defines 88that do not take arguments; 89.Li #defines 90that take arguments are tagged automatically. 91.It Fl f 92Place the tag descriptions in a file called 93.Ar tagsfile . 94The default behaviour is to place them in a file called 95.Pa tags . 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 175The 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 EXIT STATUS 196The 197.Nm 198utility exits with a value of 1 if an error occurred, 0 otherwise. 199Duplicate objects are not considered errors. 200.Sh COMPATIBILITY 201The 202.Fl t 203option is a no-op for compatibility with previous versions of 204.Nm 205that did not create tags for typedefs, enums, structs and unions 206by default. 207.Sh SEE ALSO 208.Xr ex 1 , 209.Xr vi 1 210.Sh STANDARDS 211The 212.Nm 213utility conforms to 214.St -p1003.1-2001 . 215.Sh HISTORY 216The 217.Nm 218utility appeared in 219.Bx 3.0 . 220.Sh BUGS 221Recognition of functions, subroutines and procedures 222for Fortran and Pascal is done in a very simpleminded way. 223No attempt 224is made to deal with block structure; if you have two Pascal procedures 225in different blocks with the same name you lose. 226The 227.Nm 228utility does not 229understand about Pascal types. 230.Pp 231The method of deciding whether to look for C, Pascal or 232Fortran 233functions is a hack. 234.Pp 235The 236.Nm 237utility relies on the input being well formed, and any syntactical 238errors will completely confuse it. 239It also finds some legal syntax 240confusing; for example, since it does not understand 241.Li #ifdef Ns 's 242(incidentally, that is a feature, not a bug), any code with unbalanced 243braces inside 244.Li #ifdef Ns 's 245will cause it to become somewhat disoriented. 246In a similar fashion, multiple line changes within a definition will 247cause it to enter the last line of the object, rather than the first, as 248the searching pattern. 249The last line of multiple line 250.Li typedef Ns 's 251will similarly be noted. 252