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