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: head/usr.bin/ctags/ctags.1 216370 2010-12-11 08:32:16Z joel $ 30.\" 31.Dd May 6, 2016 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 BFTadtuwvx 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 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 (default). 96.It Fl T 97Do not create tags for typedefs, structs, unions, and enums. 98.It Fl u 99Update the specified files in the 100.Pa tags 101file, that is, all 102references to them are deleted, and the new values are appended to the 103file. 104(Beware: this option is implemented in a way which is rather 105slow; it is usually faster to simply rebuild the 106.Pa tags 107file.) 108.It Fl v 109An index of the form expected by 110.Xr vgrind 1 111is produced on the standard output. 112This listing 113contains the object name, file name, and page number (assuming 64 114line pages). 115Since the output will be sorted into lexicographic order, 116it may be desired to run the output through 117.Xr sort 1 . 118Sample use: 119.Bd -literal -offset indent 120ctags -v files | sort -f > index 121vgrind -x index 122.Ed 123.It Fl w 124Suppress warning diagnostics. 125.It Fl x 126.Nm 127produces a list of object 128names, the line number and file name on which each is defined, as well 129as the text of that line and prints this on the standard output. 130This 131is a simple index which can be printed out as an off-line readable 132function index. 133.El 134.Pp 135Files whose names end in 136.Pa .c 137or 138.Pa .h 139are assumed to be C 140source files and are searched for C style routine and macro definitions. 141Files whose names end in 142.Pa .y 143are assumed to be 144.Xr yacc 1 145source files. 146Files whose names end in 147.Pa .l 148are assumed to be Lisp files if their 149first non-blank character is 150.Ql \&; , 151.Ql \&( , 152or 153.Ql \&[ , 154otherwise, they are 155treated as 156.Xr lex 1 157files. 158Other files are first examined to see if they 159contain any Pascal or Fortran routine definitions, and, if not, are 160searched for C style definitions. 161.Pp 162The tag 163.Dq Li main 164is treated specially in C programs. 165The tag formed 166is created by prepending 167.Ql M 168to the name of the file, with the 169trailing 170.Pa .c 171and any leading pathname components removed. 172This makes use of 173.Nm 174practical in directories with more than one 175program. 176.Pp 177The 178.Xr yacc 1 179and 180.Xr lex 1 181files each have a special tag. 182.Dq Li yyparse 183is the start 184of the second section of the 185.Xr yacc 1 186file, and 187.Dq Li yylex 188is the start of 189the second section of the 190.Xr lex 1 191file. 192.Sh FILES 193.Bl -tag -width ".Pa tags" -compact 194.It Pa tags 195default output tags file 196.El 197.Sh EXIT STATUS 198.Ex -std 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-2008 . 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