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