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