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