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