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