usr.bin/ctags/ctags.1

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