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 May 23, 2023 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 . 96If 97.Ar tagsfile 98is 99.Dq - , 100the tags will be written to standard output instead. 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. 107This is ignored if the tags file does not exist or is not a regular 108file (e.g. 109.Fl f Ns - 110was used to write to standard output). 111.Pp 112Beware: this option is implemented in a way which is rather 113slow; it is usually faster to simply rebuild the 114.Pa tags 115file. 116.It Fl v 117An index of the form expected by 118.Xr vgrind 1 119is produced on the standard output. 120This listing 121contains the object name, file name, and page number (assuming 64 122line pages). 123Since the output will be sorted into lexicographic order, 124it may be desired to run the output through 125.Xr sort 1 . 126Sample use: 127.Bd -literal -offset indent 128ctags -v files | sort -f > index 129vgrind -x index 130.Ed 131.It Fl w 132Suppress warning diagnostics. 133.It Fl x 134.Nm 135produces a list of object 136names, the line number and file name on which each is defined, as well 137as the text of that line and prints this on the standard output. 138This 139is a simple index which can be printed out as an off-line readable 140function index. 141.El 142.Pp 143Files whose names end in 144.Pa .c 145or 146.Pa .h 147are assumed to be C 148source files and are searched for C style routine and macro definitions. 149Files whose names end in 150.Pa .y 151are assumed to be 152.Xr yacc 1 153source files. 154Files whose names end in 155.Pa .l 156are assumed to be Lisp files if their 157first non-blank character is 158.Ql \&; , 159.Ql \&( , 160or 161.Ql \&[ , 162otherwise, they are 163treated as 164.Xr lex 1 165files. 166Other files are first examined to see if they 167contain any Pascal or Fortran routine definitions, and, if not, are 168searched for C style definitions. 169.Pp 170The tag 171.Dq Li main 172is treated specially in C programs. 173The tag formed 174is created by prepending 175.Ql M 176to the name of the file, with the 177trailing 178.Pa .c 179and any leading pathname components removed. 180This makes use of 181.Nm 182practical in directories with more than one 183program. 184.Pp 185The 186.Xr yacc 1 187and 188.Xr lex 1 189files each have a special tag. 190.Dq Li yyparse 191is the start 192of the second section of the 193.Xr yacc 1 194file, and 195.Dq Li yylex 196is the start of 197the second section of the 198.Xr lex 1 199file. 200.Sh FILES 201.Bl -tag -width ".Pa tags" -compact 202.It Pa tags 203default output tags file 204.El 205.Sh EXIT STATUS 206The 207.Nm 208utility exits with a value of 1 if an error occurred, 0 otherwise. 209Duplicate objects are not considered errors. 210.Sh COMPATIBILITY 211The 212.Fl t 213option is a no-op for compatibility with previous versions of 214.Nm 215that did not create tags for typedefs, enums, structs and unions 216by default. 217.Sh SEE ALSO 218.Xr ex 1 , 219.Xr vi 1 220.Sh STANDARDS 221The 222.Nm 223utility conforms to 224.St -p1003.1-2001 . 225.Sh HISTORY 226The 227.Nm 228utility appeared in 229.Bx 3.0 . 230.Sh BUGS 231Recognition of functions, subroutines and procedures 232for Fortran and Pascal is done in a very simpleminded way. 233No attempt 234is made to deal with block structure; if you have two Pascal procedures 235in different blocks with the same name you lose. 236The 237.Nm 238utility does not 239understand about Pascal types. 240.Pp 241The method of deciding whether to look for C, Pascal or 242Fortran 243functions is a hack. 244.Pp 245The 246.Nm 247utility relies on the input being well formed, and any syntactical 248errors will completely confuse it. 249It also finds some legal syntax 250confusing; for example, since it does not understand 251.Li #ifdef Ns 's 252(incidentally, that is a feature, not a bug), any code with unbalanced 253braces inside 254.Li #ifdef Ns 's 255will cause it to become somewhat disoriented. 256In a similar fashion, multiple line changes within a definition will 257cause it to enter the last line of the object, rather than the first, as 258the searching pattern. 259The last line of multiple line 260.Li typedef Ns 's 261will similarly be noted. 262